1159 lines
74 KiB
Markdown
1159 lines
74 KiB
Markdown
# lolympus-agent 2026 Overhaul — Implementation Plan
|
||
|
||
> **Audience**: 이 문서는 Codex(또는 다른 AI 에이전트)가 self-contained하게 작업할 수 있도록 작성됨. 모든 결정 사항, 파일 경로, 인터페이스, env/Redis 스키마, NATS subject 카탈로그, Phase별 산출물이 명시됨.
|
||
|
||
---
|
||
|
||
## 1. Executive Summary
|
||
|
||
**목적**: 카카오톡 오픈채팅 게임 커뮤니티(lolympus) 새내기 온보딩 Agent를 "인간 직원에 가까운 응답 품질"로 끌어올린다.
|
||
|
||
**접근**: 2026 AI agent 연구(Anthropic context engineering, OTel GenAI semconv, Reflection 패턴, Hermes/OpenAI tool calling, confidence-gated orchestration)를 적용해 6단계(Phase 0–5)로 광범위 개선.
|
||
|
||
**최종 목표 지표**:
|
||
- p50 응답 latency < 800ms, p95 < 2.8s
|
||
- Shadow eval LLM-judge 평균 점수 ≥ 4.0/5.0 유지
|
||
- 온보딩 완료율 기준선 대비 유의미한 향상 (별도 측정)
|
||
|
||
**총 추정 소요 (단일 개발자)**: 약 **20–27일 (≈ 4–5.5주)**.
|
||
|
||
---
|
||
|
||
## 2. Current State (기존 시스템)
|
||
|
||
### 2.1 진입/통신
|
||
- `src/main.ts` → NATS request/reply (subject `lolympus-agent.request`)
|
||
- `src/agent/agent.ts`: `request.skill` 매칭된 `Skill.handle()` 호출
|
||
- Request: `{requestId, skill, chatroomId, userId, nickname, trigger, userMessage?, context?}`
|
||
- Response: `{requestId, text, confidence, source: "llm"|"template", metadata?}`
|
||
|
||
### 2.2 LLM
|
||
- `src/llm/llm-client.ts`: 엔드포인트 체인 `CLI_PROXY_API_URLS → AGENT_LLM_API_URLS → LLAMA_SERVER_API_URL`
|
||
- 모델: Qwen3.5-4B (로컬 llama-server)
|
||
- 매 요청마다 `/health` check (5s timeout) — 병목
|
||
- Function calling 미사용, 단일 system prompt + few-shot
|
||
|
||
### 2.3 Skill
|
||
- 단일 `OnboardingSkill`. 7가지 trigger 라우팅 (new-member / nickname-invalid / photo-failed / progress-update / timeout-warning / completed / user-message) + default
|
||
- 단일 거대 system prompt (약 1800 tokens)
|
||
- 정규식 기반 의도 감지 (`message-filter.ts`): `shouldSkipMessage`, `detectLightweightIntent`, `isRemainingStatusQuestion`
|
||
- 폴백 템플릿: `onboarding-templates.ts` (`analyzeNicknameIssues`, `getNicknameInvalidMessage` 등)
|
||
- 응답 후처리: `<think>` 제거, URL 화이트리스트(discord/kakao), 마크다운 제거, 600자 절단
|
||
- 저품질 감지: 길이 < 10자 또는 bigram 3회+ → temp +0.1 재시도
|
||
|
||
### 2.4 상태 저장
|
||
- Garnet/Redis
|
||
- 온보딩 세션 (lolympus 본체가 작성, agent는 read-only): `lolympus:onboarding:{chatroomId}:{userId}`
|
||
- 대화 히스토리 (FIFO 20개, 12h TTL): `lolympus-agent:conv:{chatroomId}:{userId}`
|
||
- MongoDB (`dakao` DB, `events` 컬렉션): `RoomContextService`가 최근 8개 메시지 조회
|
||
|
||
### 2.5 부재
|
||
- 테스트 0건, eval set 0건
|
||
- 메트릭/트레이싱 0 (console.log만)
|
||
- 로깅 라이브러리, 린터 없음
|
||
- Function calling 미사용
|
||
- Feature flag, circuit breaker 없음
|
||
|
||
---
|
||
|
||
## 3. Target Architecture
|
||
|
||
```
|
||
NATS "lolympus-agent.request"
|
||
│
|
||
▼
|
||
Agent.handleRequest
|
||
│ AsyncLocalStorage(RequestContext) 개시, root OTel span
|
||
▼
|
||
OnboardingSkill.handle (skill.ts) — 이하 단계는 src/skills/onboarding/{state,prompts,runtime}/ 모듈들이 담당
|
||
├─ 1. classifier.classify(userMessage) → Intent (regex first, LLM fallback)
|
||
├─ 2. state.derive(session, trigger, intent) → DerivedState {phase, responseMode, tier, ...}
|
||
│ • shouldRespond=false면 여기서 empty 반환
|
||
├─ 3. blackboard.load() + prompt.PromptBuilder.forDerived(derived, ctx).build()
|
||
├─ 4. orchestrator.run(derived, messages)
|
||
│ • Tier 0 (~95%): single LLM call
|
||
│ • Tier 1 (~4%): Planner → Responder
|
||
│ • Tier 2 (~1%): Planner → Responder → Critic → Rewrite
|
||
│ • LLM 호출 내부에 tool loop (max 2 hop) — Hermes XML + OpenAI JSON 양쪽 파싱
|
||
├─ 5. validator.check(response, derived) → pass | soft-warn | reject
|
||
│ • reject → 템플릿 fallback
|
||
├─ 6. postProcess (URL/마크다운/길이)
|
||
└─ 7. blackboard.update() + shadowBus.publish() (fire-and-forget)
|
||
|
||
병렬:
|
||
OTel spans → stdout exporter (prod: 10% sampling)
|
||
Pino logs → stdout (NODE_ENV별 level 분기)
|
||
Background worker (별도 PM2 entry):
|
||
• Redis Stream consumer: eval judging, conversation summarization
|
||
Alert: 임계값 이상 → NATS "lolympus-agent.alert" → 본체가 KakaoTalk 발송
|
||
```
|
||
|
||
**핵심 원칙**
|
||
1. `agent.ts` (NATS 레이어)는 ALS wrap만 추가. NATS 인터페이스 변경은 신규 subject 추가로만.
|
||
2. 모든 개선은 `Skill.handle` 내부(`src/skills/{name}/{state,prompts,runtime}/` 모듈들)에서. `SkillRuntime`이라는 별도 클래스는 없으며 "skill의 runtime 모듈군"의 통칭.
|
||
3. 95% 트래픽은 fast path 1-hop. Tier 결정 = DerivedState.tier.
|
||
4. LLM 호출 수 turn당 평균 1회 목표.
|
||
5. 모든 시간은 **UTC** ISO-8601.
|
||
|
||
---
|
||
|
||
## 4. Resolved Decisions (모두 확정)
|
||
|
||
| # | 영역 | 결정 |
|
||
|---|---|---|
|
||
| 1 | LLM provider 우선순위 | **모든 tier에서 CLIPROXY 최우선** → 실패 시 로컬 Qwen 폴백. 추후 CLIPROXY → OpenRouter → Qwen (OpenRouter는 구현만, `OPENROUTER_ENABLED=false` 기본 비활성) |
|
||
| 2 | CLIPROXY 사양 | OpenAI-compatible API. JSON 모드 + tool calling 지원 확인됨. 사용 모델: 저지연 `gpt-5.3-codex-spark`, 고성능 `gpt-5.4`, LLM-judge용 `gpt-5.3-codex-spark` |
|
||
| 3 | Tier별 모델 매핑 | Tier 0: `gpt-5.3-codex-spark`; Tier 1 Planner: `gpt-5.4`, Responder: `gpt-5.3-codex-spark`; Tier 2 Critic/Rewrite: `gpt-5.4`. 모두 CLIPROXY 경유. 실패 시 각각 로컬 Qwen으로 폴백 |
|
||
| 4 | 로깅 정책 | PII 마스킹 X. `NODE_ENV`별 level: `dev=trace`, `test=debug`, `prod=warn`. prod OTel sampling 10%. Infisical `KNOWN_SECRET_KEYS` 값은 redact |
|
||
| 5 | Timezone | **모든 timestamp UTC** ISO-8601. 프롬프트 표시만 Asia/Seoul 변환 |
|
||
| 6 | 본체 계약 | 변경 자유 — 새 trigger, context 필드, NATS subject 추가 적극 활용 |
|
||
| 7 | Shadow worker 배포 | **별도 PM2 entry** (`ecosystem.config.js`). 단일 worker가 eval judging + conversation summarization 모두 처리 (`lolympus-agent:background` Redis Stream consumer group) |
|
||
| 8 | Garnet 키 네임스페이스 | `lolympus-agent:*`. 본체의 `lolympus:*`와 분리. 자료구조는 §8 참조 |
|
||
| 9 | Alert | `lolympus-agent.alert` NATS subject. 본체가 KakaoTalk 발송. 자동 rollback 없음 — 알림만, 사용자 승인 후 수동 revert |
|
||
| 10 | Rollout | **v2 직진 cutover** — feature flag 없음, v1 alias 없음. PR 단위로 갈아치움 |
|
||
| 11 | `onboarding-templates.ts` | Phase 5 안정화 후 deprecated. validator reject 시 fallback으로 그동안 재사용 |
|
||
| 12 | Golden set | Phase 2 완료 후 사용자가 `npm run eval:capture`로 MongoDB events에서 추출. expected 직접 큐레이션. 규모 30–50건 |
|
||
| 13 | Property test | v1↔v2 비교 생략. 핵심 불변식 5–10개만 unit test |
|
||
| 14 | Phase별 smoke test | Phase 3/4 끝마다 `npm run eval` 실행(규칙+golden set). Phase 5에서 shadow eval 본격 가동 |
|
||
|
||
### DX 결정
|
||
- 디렉토리: **Feature-first + tsconfig paths** (`@agent/*`, `@skills/*`, `@llm/*`, `@obs/*`, `@eval/*`, `@tools/*`, `@common/*`, `@conv/*`, `@room/*`)
|
||
- Types colocated: 각 feature 폴더 내 `types.ts` (기존 `*-types.ts` 통합)
|
||
- 테스트: **Vitest + fast-check**, `*.test.ts` colocated, coverage `@vitest/coverage-v8`
|
||
- **Redis 의존 부분은 `ioredis-mock`으로 in-memory**. integration 테스트 별도 경로 불필요 (단일 개발자 환경, 운영 부하 수준에서 Redis 자체 버그 희귀)
|
||
- **MongoDB 의존 코드 (`room-context`, `eval:capture`)는 unit test 대상 외** — service interface를 mock하는 방식으로만 테스트. eval:capture는 수동 실행이라 CI 대상 아님
|
||
- `vitest.setup.ts` 신설: pino silent, OTel noop exporter, `ioredis-mock` 전역 주입. 주입 방식 — 파일 상단에서:
|
||
```ts
|
||
import { vi } from "vitest";
|
||
vi.mock("ioredis", async () => {
|
||
const RedisMock = (await import("ioredis-mock")).default;
|
||
return { default: RedisMock, Redis: RedisMock };
|
||
});
|
||
```
|
||
`vitest.config.ts`에 `test.setupFiles: ["./vitest.setup.ts"]` 등록. Redis를 직접 `new Redis(...)`로 생성하는 코드는 모두 자동으로 ioredis-mock 인스턴스 반환 — Stream 포함 동작 지원 확인됨 (XADD/XREADGROUP/XACK/XCLAIM)
|
||
- 린트/포맷: **ESLint flat config (typescript-eslint recommended-type-checked) + Prettier 3 + tsc strict**. PR gate
|
||
- Skill 내부: `src/skills/onboarding/{state,prompts,runtime}/` 서브디렉토리 (§5.5)
|
||
|
||
---
|
||
|
||
## 5. File Map
|
||
|
||
### 5.1 신규
|
||
|
||
```
|
||
src/
|
||
├── observability/ [Phase 0]
|
||
│ ├── logger.ts pino + NODE_ENV 기반 level + Infisical secret redaction
|
||
│ ├── tracing.ts OTel SDK init, stdout exporter, prod 10% sampling
|
||
│ ├── spans.ts withLlmSpan, withToolSpan, withSkillSpan, withClassifierSpan
|
||
│ ├── context.ts AsyncLocalStorage<RequestContext>
|
||
│ ├── alert.ts [Phase 5] 임계값 초과 시 NATS "lolympus-agent.alert" publish
|
||
│ └── types.ts
|
||
│
|
||
├── llm/
|
||
│ ├── circuit.ts [Phase 1] endpoint별 상태 (healthy/unhealthy/open), 30s 캐시, 연속 실패 N회 cooldown
|
||
│ ├── routing.ts [Phase 5] tier → provider 우선순위 결정
|
||
│ ├── providers/
|
||
│ │ ├── cliproxy.ts OpenAI-compatible, JSON/tool 지원
|
||
│ │ ├── llama.ts llama.cpp, Hermes prompt로 JSON 강제
|
||
│ │ └── openrouter.ts 구현만, OPENROUTER_ENABLED gate
|
||
│ └── types.ts (기존 llm-types.ts를 통합)
|
||
│
|
||
├── skills/onboarding/
|
||
│ ├── skill.ts [Phase 2 개명] 진입점 (기존 onboarding-skill.ts를 git mv)
|
||
│ ├── index.ts [Phase 2] barrel export (§5.5)
|
||
│ ├── constants.ts [Phase 4] 규칙 상수 SoT (VALID_TIERS, HEART_RULE_TEXT 등 + env wrapper)
|
||
│ ├── types.ts (기존 onboarding-types.ts 통합)
|
||
│ ├── state/ [Phase 2]
|
||
│ │ ├── onboarding-state.ts OnboardingPhase / Intent discriminated union
|
||
│ │ ├── derive.ts derive(session, trigger, intent): DerivedState (pure)
|
||
│ │ ├── transitions.ts phase 전이 테이블 (현재는 session 필드 기반이라 얇음)
|
||
│ │ ├── classifier.ts regex first + LLM JSON fallback
|
||
│ │ ├── intent-keywords.ts intent → 기대 키워드 사전 (validator에서 사용)
|
||
│ │ └── blackboard.ts [Phase 3] Redis conv working memory
|
||
│ │
|
||
│ ├── prompts/ [Phase 3]
|
||
│ │ ├── layers.ts persona / policy / state / examples / context 5-layer
|
||
│ │ ├── examples.ts Record<Intent["kind"], Example[]> few-shot bank
|
||
│ │ ├── builder.ts PromptBuilder.forDerived(derived, ctx).build()
|
||
│ │ └── tool-policy.ts [Phase 4] buildToolPolicy(intent, phase) — tool 사용 시나리오 가이드
|
||
│ │
|
||
│ └── runtime/ [Phase 4–5]
|
||
│ ├── orchestrator.ts [Phase 5] tier 0/1/2 분기 + 모델 매핑 실행
|
||
│ ├── planner-schema.ts [Phase 5] PlannerOutput zod schema (§9.5.1.1)
|
||
│ ├── tool-loop.ts [Phase 4] tool call 감지 → 실행 → tool_result append → 재호출 (max 2 hop)
|
||
│ ├── validator.ts [Phase 4] postProcess + state 모순 / self-consistency / intent 매칭 검사
|
||
│ └── critic.ts [Phase 4 정의 / Phase 5 orchestrator 통합] tier 2 전용 self-critique
|
||
│
|
||
├── tools/ [Phase 4]
|
||
│ ├── tool.ts Tool<TArgs, TResult> 인터페이스 + zod
|
||
│ ├── registry.ts Tool 등록/조회
|
||
│ ├── parser.ts Hermes <tool_call>...</tool_call> + OpenAI tool_calls 양쪽 파싱
|
||
│ ├── serializer.ts tool 선언을 system prompt에 주입할 포맷(Hermes spec 준수)
|
||
│ └── builtins/
|
||
│ ├── validate-nickname.ts analyzeNicknameIssues 래핑
|
||
│ ├── check-onboarding-progress.ts session → 구조화 요약
|
||
│ ├── lookup-community-rule.ts 나이 27+, 티어 코드, 디스코드 링크 등
|
||
│ └── get-room-context.ts RoomContextService 래핑, LLM 호출 시만 조회
|
||
│
|
||
├── eval/ [Phase 5]
|
||
│ ├── golden/
|
||
│ │ └── onboarding.jsonl
|
||
│ ├── judges/
|
||
│ │ ├── rule-judge.ts validator + must-include/exclude 매칭
|
||
│ │ └── llm-judge.ts CLIPROXY gpt-5.3-codex-spark로 1-5점 (친근/정확/간결/범위)
|
||
│ ├── runner.ts golden set 실행
|
||
│ ├── shadow-bus.ts Redis Stream publish (fire-and-forget <5ms)
|
||
│ ├── shadow-worker.ts consumer 로직 (workers/background.ts PM2 entry가 기동)
|
||
│ ├── capture.ts MongoDB events에서 실제 케이스 추출하는 helper
|
||
│ ├── anonymize.ts [Phase 2] capture 파이프라인 익명화 (§9.2.5, 강제 단계)
|
||
│ └── cli.ts npm run eval / eval:capture 엔트리
|
||
│
|
||
├── conversation/
|
||
│ └── summarizer.ts [Phase 3] 5턴 초과 오래된 절반 요약. shadow-worker가 consume
|
||
│
|
||
├── workers/ [Phase 5]
|
||
│ └── background.ts shadow-worker.ts + summarizer consumer를 하나의 PM2 entry로 묶음
|
||
│
|
||
└── common/
|
||
└── nats-subjects.ts 모든 NATS subject 상수 + 타입 (§7 참조)
|
||
```
|
||
|
||
### 5.2 수정
|
||
|
||
- `src/main.ts` — bootstrap 순서에 `initTracing()`, `initLogger()` 최상위 추가
|
||
- `src/agent/agent.ts` — `runWithContext(ctx, () => ...)`(§9.1.2의 context.ts 헬퍼)로 handleRequest 전체 wrap, root span 생성, 응답 후 `shadowBus.publish`
|
||
- `src/llm/llm-client.ts` — `chatCompletion(messages, opts: ChatCompletionOpts)` 시그니처(상세 타입은 **§9.5.2** 참조, `signal`/`deadlineMs`/`maxTokens`/`role`/`modelOverride`/`temperature` 포함). 내부에서 `withLlmSpan` + circuit breaker + tier→provider 라우팅. health check는 `circuit.ts`에서 조회
|
||
- `src/skills/onboarding/onboarding-skill.ts` → **`skill.ts`로 개명(§5.4/§5.5, Phase 2 PR 2a에서 git mv) + handle 재작성**. 얇은 진입점으로. classifier → derive → orchestrator 위임
|
||
- `src/conversation/conversation-store.ts` — `summary` slot 추가. 5턴 초과 시 Redis Stream `lolympus-agent:background`에 `{type:"summarize", chatroomId, userId}` 발행
|
||
- `src/config.ts` — tier별 model / maxTokens / temperature getter, OpenRouter 관련 env, ALERT_THRESHOLD_* 추가
|
||
- `src/common/secret-manager.ts` — redact 대상 키 리스트 export (logger에서 사용)
|
||
- `tsconfig.json` — `paths` 추가
|
||
- `package.json` — 의존성 + scripts
|
||
- `launch-server.ps1` — `pm2 start ecosystem.config.js --only agent,agent-worker` 기반으로 단순화 (Windows 호환 유지)
|
||
|
||
### 5.3 신설 (루트)
|
||
|
||
- `ecosystem.config.js` — PM2 설정. 2 process: `agent`(main), `agent-worker`(background)
|
||
- `vitest.config.ts` — paths alias 동기화, 커버리지
|
||
- `eslint.config.js` — flat config. `no-restricted-imports`로 `@skills/onboarding/runtime/*` 외부 import 차단
|
||
- `.prettierrc`
|
||
- `.editorconfig`
|
||
- `.gitignore` 신설/갱신 — `eval-reports/`, `*.tsbuildinfo`, `coverage/`, `dist/`, `.env*` 추가
|
||
|
||
### 5.4 Deprecate (v2 직진 — 삭제 시점은 Phase별 상이)
|
||
|
||
- `src/skills/onboarding/message-filter.ts` → PR 2a에서 `@deprecated` 표시 + classifier 내부에서 일시 재사용 → **PR 2b에서 삭제** (golden set 통과 후)
|
||
- `src/skills/onboarding/onboarding-prompts.ts` → PR 2a에서 `@deprecated` 표시 + 인라인 유지 → **Phase 3 PR에서 builder 도입과 함께 삭제**
|
||
- `src/skills/onboarding/onboarding-templates.ts` → Phase 5 안정화 이후 **삭제**. 그 전까지 validator reject fallback
|
||
- `src/skills/onboarding/onboarding-skill.ts` → Phase 2에서 `src/skills/onboarding/skill.ts`로 **개명**(파일 내용은 handle 재작성과 함께). 개명 이유는 §5.5 참조
|
||
|
||
### 5.5 파일 구조 (skill별 분리)
|
||
|
||
진입점은 폴더 최상위, 내부 구현은 서브디렉토리 — 각 skill이 자체 runtime/state/prompts 를 가짐. 향후 `game-analysis` 등 skill 추가 시 동일 패턴.
|
||
|
||
```
|
||
src/skills/
|
||
├── skill.ts # Skill 인터페이스(공통)
|
||
├── registry.ts # skill 등록/조회 (skill이 2+개 되면 신설)
|
||
└── onboarding/
|
||
├── skill.ts # OnboardingSkill (진입점, Phase 2에서 onboarding-skill.ts를 개명)
|
||
├── index.ts # barrel: export { OnboardingSkill } from "./skill"
|
||
├── constants.ts # SoT 상수 (나이, 티어, 데드라인 등)
|
||
├── types.ts # OnboardingSession, NicknameIssue 등 skill-local 타입
|
||
├── state/ # Phase 2: classifier, derive, transitions, blackboard
|
||
├── prompts/ # Phase 3: layers, examples, builder, (Phase 4) tool-policy
|
||
└── runtime/ # Phase 4~5: orchestrator, tool-loop, validator, critic, planner-schema
|
||
```
|
||
|
||
외부 import는 `import { OnboardingSkill } from "@skills/onboarding"` 단일 경로. `runtime/*`은 skill-internal (외부 import 금지 — eslint 규칙으로 `@skills/onboarding/runtime/*` import 차단).
|
||
|
||
---
|
||
|
||
## 6. Env Variables Catalog
|
||
|
||
`env-vars/{dev,test,prod}.env` 공통. 시크릿은 Infisical.
|
||
|
||
### 6.1 기존 (유지)
|
||
- `NODE_ENV` — dev | test | prod
|
||
- `SERVICE_NAME` — 기본 `lolympus-agent`
|
||
- `NATS_ENDPOINT`, `NATS_USER`, `NATS_PASS`
|
||
- `GARNET_ENDPOINT`, `GARNET_USERID`, `GARNET_PASSWORD`
|
||
- `MONGODB_CONNECTION_STRING`, `MONGODB_PROJECT_ID`
|
||
- `CLI_PROXY_API_URLS` (newline 또는 comma 분리)
|
||
- `AGENT_LLM_API_URLS`, `LLAMA_SERVER_API_URL`
|
||
|
||
### 6.2 신규
|
||
| Key | 기본값 | 설명 |
|
||
|---|---|---|
|
||
| `LOG_LEVEL` | NODE_ENV별 기본 | 명시 시 override |
|
||
| `OTEL_SAMPLING_RATIO` | dev/test=1.0, prod=0.1 | OTel trace sampling |
|
||
| `OTEL_EXPORTER` | `stdout` | 향후 `otlp`로 전환 가능 |
|
||
| `LLM_HEALTH_CACHE_TTL_MS` | 30000 | circuit breaker 캐시 |
|
||
| `LLM_CIRCUIT_FAILURE_THRESHOLD` | 3 | 연속 실패 횟수 |
|
||
| `LLM_CIRCUIT_COOLDOWN_MS` | 60000 | 개방 후 쿨다운 |
|
||
| `TIER0_MODEL` | `gpt-5.3-codex-spark` | |
|
||
| `TIER1_PLANNER_MODEL` | `gpt-5.4` | |
|
||
| `TIER1_RESPONDER_MODEL` | `gpt-5.3-codex-spark` | |
|
||
| `TIER2_CRITIC_MODEL` | `gpt-5.4` | |
|
||
| `TIER0_MAX_TOKENS` | 384 | |
|
||
| `TIER1_MAX_TOKENS` | 512 | Responder 출력 상한 |
|
||
| `TIER2_MAX_TOKENS` | 512 | Rewrite 출력 상한 |
|
||
| `PLANNER_MAX_TOKENS` | 256 | Tier 1 Planner JSON 출력 상한 |
|
||
| `CRITIC_MAX_TOKENS` | 512 | Tier 2 Critic 출력 상한 |
|
||
| `CLASSIFIER_FALLBACK_MODEL` | `gpt-5.3-codex-spark` | 경량 intent classify |
|
||
| `CLASSIFIER_BUDGET_MS` | 200 | classifier LLM fallback 허용 시간. deadline에서 차감 |
|
||
| `CLASSIFIER_MAX_TOKENS` | 16 | intent JSON만 받으므로 매우 작게 |
|
||
| `LLM_JUDGE_MODEL` | `gpt-5.3-codex-spark` | Phase 5 shadow eval judge |
|
||
| `LLM_JUDGE_MAX_TOKENS` | 128 | 4축 점수 + 한줄 이유 |
|
||
| `EVAL_PROCESS_LLM_JUDGE_ENABLED` | `false` | Phase 7 shadow-worker process judge LLM 보조 평가 활성화 |
|
||
| `EVAL_PROCESS_LLM_JUDGE_SAMPLING_RATE` | 0.1 | Phase 7 process LLM judge sampling rate |
|
||
| `EVAL_PROCESS_LLM_JUDGE_MAX_TOKENS` | 256 | Phase 7 process LLM judge 출력 상한 |
|
||
| `SAFETY_MARGIN_MS` | 500 | NATS 5s timeout에서 차감 (§7) |
|
||
| `TIER0_ESTIMATED_CALL_MS` | 600 | deadline 계산용 |
|
||
| `TIER1_ESTIMATED_CALL_MS` | 1200 | |
|
||
| `TIER2_ESTIMATED_CALL_MS` | 1400 | |
|
||
| `ESCALATION_BUDGET_PER_TURN` | 2 | §9.4.6 escalation 추가 호출 상한 |
|
||
| `DEADLINE_NEAR_THRESHOLD_MIN` | 30 | §9.2 constants. 데드라인 ≤ 30분 시 phase=deadline-near |
|
||
| ~~`EVAL_ANON_SALT`~~ | (env 아님) | **env 등록 X** — `src/eval/anonymize.ts` 상단에 `const EVAL_ANON_SALT = "lolympus-agent-v1"`로 하드코딩(§9.2.5). 값 변경 시 golden set 해시 불일치 → env로 빼면 의도치 않은 override 위험 |
|
||
| `OPENROUTER_ENABLED` | `false` | Phase 5 구현만, 기본 비활성 |
|
||
| `OPENROUTER_API_URL` | `https://openrouter.ai/api/v1` | |
|
||
| `OPENROUTER_API_KEY` | — | Infisical |
|
||
| `OPENROUTER_TIER1_MODEL` | `openai/gpt-5.3-codex-spark` | |
|
||
| `OPENROUTER_TIER2_MODEL` | `openai/gpt-5.4` | |
|
||
| `SHADOW_EVAL_SAMPLING_RATE_TIER0` | prod=0.1, dev=1.0 | tier 0 응답 sampling (트래픽 95%라 낮게) |
|
||
| `SHADOW_EVAL_SAMPLING_RATE_TIER1` | prod=0.5, dev=1.0 | tier 1 응답 sampling (트래픽 4%라 높게) |
|
||
| `SHADOW_EVAL_SAMPLING_RATE_TIER2` | prod=1.0, dev=1.0 | tier 2 응답 sampling (트래픽 1%라 100%) |
|
||
| `ALERT_THRESHOLD_P95_LATENCY_MS` | 3000 | 초과 시 KakaoTalk alert |
|
||
| `ALERT_THRESHOLD_EVAL_SCORE_DROP_PCT` | 10 | baseline 대비 하락률 |
|
||
| `ALERT_THRESHOLD_LLM_ERROR_RATE` | 0.1 | 1분 윈도우 에러율 |
|
||
| `ALERT_THRESHOLD_DRIFT_PCT` | 15 | Phase 6 24h vs 7d slice 점수 하락률 |
|
||
| `ALERT_RATE_LIMIT_SEC` | 300 | 동일 종류 알림 재발송 최소 간격 |
|
||
| `BLACKBOARD_TTL_SEC` | 43200 | 12h |
|
||
| `CONVERSATION_SUMMARY_TTL_SEC` | 86400 | 24h |
|
||
| `EVAL_STREAM_MAXLEN` | 10000 | Redis Stream MAXLEN ~ |
|
||
| `EVAL_RESULTS_TTL_SEC` | 2592000 | 30일 |
|
||
| `EVAL_AGG_TICK_MS` | 300000 | Phase 6 slice aggregator tick |
|
||
| `EVAL_AGG_TTL_SEC` | 604800 | Phase 6 slice Hash TTL |
|
||
| `EVAL_AGG_LATENCY_SAMPLE_CAP` | 200 | Phase 6 p50/p95 계산용 latency sample cap |
|
||
| `EVAL_ARCHIVE_TICK_MS` | 3600000 | Phase 6 Redis eval stream → Mongo archive tick |
|
||
| `EVAL_ARCHIVE_TTL_DAYS` | 30 | Phase 6 `eval_archive.evaluatedAt` TTL index |
|
||
| `EVAL_ARCHIVE_BATCH_SIZE` | 500 | Phase 6 archive tick당 stream entry 처리 수 |
|
||
| `EVAL_DRIFT_TICK_MS` | 86400000 | Phase 6 drift detection tick |
|
||
| `EVAL_PROMOTE_TICK_MS` | 86400000 | Phase 6 golden candidate promotion tick |
|
||
| `EVAL_PROMOTE_LOW_SCORE` | 2 | Phase 6 low-score candidate 임계 |
|
||
| `EVAL_PROMOTE_RARE_THRESHOLD` | 5 | Phase 6 rare-slice candidate 임계 |
|
||
| `EVAL_PROMOTE_PER_CATEGORY_LIMIT` | 10 | Phase 6 promotion 카테고리별 최대 후보 수 |
|
||
| `EVAL_REVIEW_TICK_MS` | 300000 | Phase 8 review-routing tick |
|
||
| `EVAL_REVIEW_QUEUE_MAXLEN` | 500 | Phase 8 review queue Stream MAXLEN |
|
||
| `EVAL_REVIEW_LABEL_MAXLEN` | 5000 | Phase 8 labeled Stream MAXLEN |
|
||
| `EVAL_REVIEW_PER_CATEGORY_LIMIT` | 5 | Phase 8 tick당 카테고리별 enqueue 한도 |
|
||
| `EVAL_REVIEW_DEDUPE_TTL_SEC` | 604800 | Phase 8 review enqueue dedupe TTL |
|
||
| `EVAL_CALIBRATION_MIN_CORR` | 0.5 | Phase 8 사람/LLM calibration 최소 상관 |
|
||
| `REVIEWER_ID` | git user.email fallback | Phase 8 review CLI reviewedBy 식별자 |
|
||
| `LLM_PROPOSE_MODEL` | `LLM_JUDGE_MODEL` | Phase 9 propose 단계 모델 |
|
||
| `LLM_PROPOSE_MAX_TOKENS` | 1024 | Phase 9 proposal JSON 출력 상한 |
|
||
| `EVAL_TOURNAMENT_MAX_MATCHES` | 50 | Phase 9 tournament 최대 match 수 |
|
||
| `EVAL_TOURNAMENT_MIN_CASES` | 10 | Phase 9 propose/tournament 최소 archive case 수 |
|
||
| `PROMPT_VARIANT_ID` | — | Phase 9 운영 prompt variant manifest 적용 |
|
||
| `BACKGROUND_STREAM_MAXLEN` | 5000 | |
|
||
|
||
---
|
||
|
||
## 7. NATS Subject Catalog
|
||
|
||
`src/common/nats-subjects.ts`에 상수 + 타입으로 정의.
|
||
|
||
| Subject | 방향 | Payload | 설명 |
|
||
|---|---|---|---|
|
||
| `lolympus-agent.request` | in | `AgentRequest` | 기존. lolympus 본체 → agent. **timeout 5000ms (본체 NATS request timeout, 본체 측 PR로 명시)** |
|
||
| `lolympus-agent.alert` | out | `AlertPayload` | 신규. agent → lolympus 본체 (본체가 KakaoTalk 발송) |
|
||
| `lolympus-agent.eval.report` | out (optional) | `EvalReport` | 신규. 배치 eval 결과 publish. 본체가 대시보드로 수집 가능 |
|
||
|
||
**Deadline budget propagation** (timeout 마진 운영):
|
||
- `Agent.handleRequest` 진입 시 `deadlineAt = now + 5000ms - SAFETY_MARGIN_MS(기본 500ms) = +4500ms`. ALS context에 저장.
|
||
- **Classifier LLM fallback도 budget 차감 대상**: regex unknown → LLM fallback 호출 시 `CLASSIFIER_BUDGET_MS`(기본 200ms) 차감 확인. 여유 없으면 classifier fallback 생략하고 intent=`unknown`으로 진행(derive가 tier 0 / responseMode=`llm`으로 처리).
|
||
- Orchestrator는 각 LLM 호출 전 `if (now > deadlineAt - estimatedCallMs) { degrade(); }` 체크.
|
||
- tier 2 escalation 직전에도 동일 체크 → deadline 부족하면 escalation 포기
|
||
- `chatCompletion`에 `signal: AbortController.signal`로 deadline-aware timeout 전달. AbortError → validator reject → 템플릿 fallback
|
||
- tier별 estimatedCallMs(env override 가능): tier0=600, tier1=1200, tier2=1400. 운영 측정 후 조정
|
||
|
||
**AlertPayload 예시**:
|
||
```ts
|
||
interface AlertPayload {
|
||
kind:
|
||
| "archive-stalled"
|
||
| "endpoint-down"
|
||
| "eval-drift"
|
||
| "eval-score-drop"
|
||
| "latency"
|
||
| "llm-error-rate";
|
||
severity: "info" | "warn" | "critical";
|
||
metric: string;
|
||
value: number;
|
||
threshold: number;
|
||
window: string; // e.g. "5m"
|
||
traceId?: string;
|
||
timestamp: string; // UTC ISO
|
||
suggestedAction?: string;
|
||
}
|
||
```
|
||
|
||
**lolympus 본체 측 변경**: `lolympus-agent.alert` 구독자 추가해 운영 채팅방(관리자 전용)에 카톡으로 발송.
|
||
|
||
---
|
||
|
||
## 7.1 OTel Attribute 표준
|
||
|
||
span/log 일관성 위해 커스텀 attribute는 아래 네이밍만 사용. dashboard 쿼리 작성 시 예측 가능.
|
||
|
||
| Attribute | 타입 | 범위 | 설명 |
|
||
|---|---|---|---|
|
||
| `gen_ai.system` | string | LLM span | 표준 semconv. 값: `"cliproxy"` \| `"llama"` \| `"openrouter"` |
|
||
| `gen_ai.request.model` | string | LLM span | 표준 semconv |
|
||
| `gen_ai.usage.input_tokens` | int | LLM span | 표준 semconv |
|
||
| `gen_ai.usage.output_tokens` | int | LLM span | 표준 semconv |
|
||
| `gen_ai.response.finish_reasons` | string[] | LLM span | 표준 semconv |
|
||
| `agent.request_id` | string | root | `AgentRequest.requestId` |
|
||
| `agent.chatroom_id` | string | root | |
|
||
| `agent.user_id` | string | root | |
|
||
| `agent.skill` | string | root | 예: `"onboarding"` |
|
||
| `agent.trigger` | string | root | `AgentRequest.trigger` |
|
||
| `agent.intent` | string | skill span | `Intent["kind"]` |
|
||
| `agent.phase` | string | skill span | `OnboardingPhase["kind"]` |
|
||
| `agent.response_mode` | string | skill span | `"skip"` \| `"template"` \| `"llm"` \| `"llm-with-tools"` |
|
||
| `agent.tier.initial` | int | skill span | `derived.tier` |
|
||
| `agent.tier.final` | int | skill span | escalation 후 최종 tier |
|
||
| `agent.tier.escalated_from` | int | escalation event | |
|
||
| `agent.tier.escalated_to` | int | escalation event | |
|
||
| `agent.validator.status` | string | skill span | `"pass"` \| `"soft-warn"` \| `"reject"` |
|
||
| `agent.validator.warnings` | string[] | skill span | 감지된 rule 이름 배열 |
|
||
| `agent.tool.name` | string | tool span | |
|
||
| `agent.tool.hop` | int | tool span | 현 turn 내 hop number (0-indexed) |
|
||
| `agent.tool.result_valid` | bool | tool span | zod result schema 통과 여부 |
|
||
| `agent.deadline.remaining_ms` | int | skill span 종료 시 | 음수면 초과 |
|
||
| `agent.source` | string | root response | `"llm"` \| `"template"` \| `"empty"` |
|
||
| `agent.classifier.source` | string | classifier span | `"regex"` \| `"llm"` |
|
||
| `agent.classifier.confidence` | float | classifier span | 0-1 |
|
||
|
||
커스텀 attribute 네임스페이스는 항상 `agent.*`. OTel 표준 영역은 `gen_ai.*` 그대로 사용. 다른 네임스페이스 신설 금지.
|
||
|
||
---
|
||
|
||
## 8. Garnet/Redis Key Schema
|
||
|
||
| Key Pattern | Type | TTL | 설명 |
|
||
|---|---|---|---|
|
||
| `lolympus:onboarding:{chatroomId}:{userId}` | String (JSON) | 본체 관리 | **본체 소유**, agent read-only |
|
||
| `lolympus-agent:conv:{chatroomId}:{userId}` | String (JSON array) | 12h | 대화 히스토리 FIFO 20 (기존) |
|
||
| `lolympus-agent:summary:{chatroomId}:{userId}` | String | 24h | Phase 3 대화 요약 slot |
|
||
| `lolympus-agent:bb:{chatroomId}:{userId}` | String (JSON) | 12h | Phase 3 Blackboard |
|
||
| `lolympus-agent:circuit:{endpointHash}` | Hash | no TTL | Phase 1 circuit breaker 상태 |
|
||
| `lolympus-agent:background` | **Stream** | MAXLEN ~ `$BACKGROUND_STREAM_MAXLEN` (기본 5000) | Phase 5 background jobs (eval/summary). Consumer group: `bg-worker` |
|
||
| `lolympus-agent:background:dlq` | **Stream** | MAXLEN ~ 1000 (리터럴, 작은 값이라 env 미등록) | Phase 5 dead-letter. retry 실패 시 XADD. 수동 조사용 |
|
||
| `lolympus-agent:eval:results` | **Stream** | MAXLEN ~ `$EVAL_STREAM_MAXLEN` (기본 10000) | Phase 5 shadow eval 결과 |
|
||
| `lolympus-agent:eval:baseline` | String (JSON) | no TTL | Phase 5 최근 안정 baseline 점수 |
|
||
| `lolympus-agent:eval:agg:{tier}:{intent}:{phase}` | Hash | `$EVAL_AGG_TTL_SEC` | Phase 6 slice별 count/score/validator/latency metric |
|
||
| `lolympus-agent:eval:agg:cursor` | String | no TTL | Phase 6 마지막 aggregated eval stream id |
|
||
| `lolympus-agent:eval:archive:cursor` | String | no TTL | Phase 6 마지막 Mongo archived eval stream id |
|
||
| `lolympus-agent:eval:review:queue` | Stream | MAXLEN ~ `$EVAL_REVIEW_QUEUE_MAXLEN` | Phase 8 사람 검토 대기 큐. Consumer group: `reviewers` |
|
||
| `lolympus-agent:eval:review:labeled` | Stream | MAXLEN ~ `$EVAL_REVIEW_LABEL_MAXLEN` | Phase 8 사람 라벨 적립 Stream |
|
||
| `lolympus-agent:eval:review:dedupe:{evalStreamId}` | String | `$EVAL_REVIEW_DEDUPE_TTL_SEC` | Phase 8 동일 eval result 중복 검토 라우팅 방지 |
|
||
| `lolympus-agent:eval:review:cursor` | String | no TTL | Phase 8 마지막 review-routed eval stream id |
|
||
| `lolympus-agent:eval:review:label-archive:cursor` | String | no TTL | Phase 8 마지막 Mongo archived review label stream id |
|
||
| `lolympus-agent:metrics:tier:{YYYYMMDDHH}` | Hash | 7일 | tier 0/1/2 분포 카운터 (시작/최종 tier, escalation 카운트 포함) |
|
||
| `lolympus-agent:metrics:escalation:{YYYYMMDDHH}` | Hash | 7일 | tier escalation from→to 카운트 |
|
||
| `lolympus-agent:alert:dedupe:{kind}` | String | `ALERT_RATE_LIMIT_SEC` | 동일 알림 rate limit |
|
||
| `lolympus-agent:alert:dedupe:endpoint:{endpointHash}` | String | `ALERT_RATE_LIMIT_SEC` | endpoint-down 알림 per-endpoint rate limit |
|
||
| `lolympus-agent:alert:dedupe:eval-drift:{tier}:{intent}:{phase}` | String | `ALERT_RATE_LIMIT_SEC` | Phase 6 drift alert per-slice rate limit |
|
||
| `lolympus-agent:alert:dedupe:archive-stalled` | String | `ALERT_RATE_LIMIT_SEC` | Phase 6 archive failure alert rate limit |
|
||
|
||
---
|
||
|
||
## 9. Phase별 작업 명세
|
||
|
||
### Phase 0 — DX Infrastructure (1일)
|
||
|
||
**목표**: 이후 모든 phase의 기반. PR로 단독 머지 가능.
|
||
|
||
**작업**
|
||
1. `package.json` 의존성 추가
|
||
- runtime: `pino`, `@opentelemetry/api`, `@opentelemetry/sdk-node`, `@opentelemetry/auto-instrumentations-node`, `@opentelemetry/semantic-conventions`, `zod`
|
||
- dev: `pino-pretty`, `vitest`, `fast-check`, `@vitest/coverage-v8`, `eslint`, `@typescript-eslint/parser`, `@typescript-eslint/eslint-plugin`, `prettier`, `eslint-config-prettier`, `@types/node`
|
||
- scripts: `test`, `test:watch`, `test:coverage`, `lint`, `lint:fix`, `format`, `typecheck`, `eval`, `eval:capture`
|
||
2. `tsconfig.json`에 `paths`: `@agent/*`→`src/agent/*`, `@skills/*`→`src/skills/*`, `@llm/*`→`src/llm/*`, `@obs/*`→`src/observability/*`, `@eval/*`→`src/eval/*`, `@tools/*`→`src/tools/*`, `@common/*`→`src/common/*`, `@conv/*`→`src/conversation/*`, `@room/*`→`src/room-context/*`
|
||
3. `vitest.config.ts` (paths alias 동기화), `eslint.config.js` (flat config, type-checked rules), `.prettierrc` (print-width 100, single-quote), `.editorconfig`
|
||
4. 기존 `*-types.ts` 파일을 각 feature 폴더 `types.ts`로 이동
|
||
- `src/agent/agent-types.ts` → `src/agent/types.ts`
|
||
- `src/llm/llm-types.ts` → `src/llm/types.ts`
|
||
- `src/room-context/room-context-types.ts` → `src/room-context/types.ts`
|
||
- `src/skills/onboarding/onboarding-types.ts` → `src/skills/onboarding/types.ts`
|
||
5. 모든 import를 alias로 치환 + barrel `index.ts` 추가(feature별 공개 API 명시)
|
||
|
||
**검증**
|
||
- `npm run typecheck && npm run lint && npm run build` 통과
|
||
- `npm start:dev`로 부팅 성공 (기능 변경 없음 확인)
|
||
|
||
---
|
||
|
||
### Phase 1 — Foundation (Observability + Health 캐싱) (2–3일)
|
||
|
||
**목표**: 측정 가능성 확보 + 매 요청 health check 제거로 즉시 latency 절감.
|
||
|
||
**작업**
|
||
|
||
**1.1 Pino logger + NODE_ENV 분기 + secret redaction**
|
||
- 신규 `src/observability/logger.ts`:
|
||
- 기본 level: `dev=trace`, `test=debug`, `prod=warn` (env `LOG_LEVEL` override)
|
||
- transport: dev/test=`pino-pretty`, prod=JSON stdout
|
||
- `redact: ['req.headers.authorization', ...KNOWN_SECRET_KEYS.map(k=>\`req.body.${k}\`), ...]`
|
||
- `secret-manager.ts`에서 `KNOWN_SECRET_KEYS`를 export해 import
|
||
- `logger.child({requestId, chatroomId, userId})` 헬퍼
|
||
- 전 파일 `console.*` → `logger.*`로 치환 (grep + 수동)
|
||
|
||
**1.2 OpenTelemetry SDK**
|
||
- 신규 `src/observability/tracing.ts`:
|
||
- NodeSDK 초기화 (stdout span exporter)
|
||
- `@opentelemetry/auto-instrumentations-node` 활성 (http, nats, ioredis 자동 계측)
|
||
- prod: `ParentBasedSampler(TraceIdRatioBasedSampler(0.1))`
|
||
- 신규 `src/observability/spans.ts`:
|
||
- `withSpan<T>(name, attrs, fn)` 기본 헬퍼
|
||
- `withLlmSpan(op, attrs, fn)`: OTel GenAI semconv attribute 기록 (`gen_ai.system`, `gen_ai.request.model`, `gen_ai.usage.input_tokens/output_tokens`, `gen_ai.response.finish_reasons`)
|
||
- `withToolSpan(toolName, args, fn)`, `withSkillSpan`, `withClassifierSpan`
|
||
- 신규 `src/observability/context.ts`: `AsyncLocalStorage<RequestContext>` + `getContext()`, `runWithContext()`
|
||
|
||
**1.3 Circuit breaker**
|
||
- 신규 `src/llm/circuit.ts`:
|
||
- 각 endpoint key → `{ state: "healthy"|"unhealthy"|"open", lastCheckedAt, failureCount, openedAt }`
|
||
- Redis Hash `lolympus-agent:circuit:{endpointHash}` + 로컬 LRU cache
|
||
- `canUse(endpoint): boolean`, `recordSuccess(endpoint)`, `recordFailure(endpoint)`
|
||
- health check는 LRU TTL(30s) 초과시에만. cooldown 기간이면 `canUse=false`
|
||
|
||
**1.4 main/agent wiring**
|
||
- `src/main.ts`: `initTracing()` → `initLogger()` → 기존 부트스트랩
|
||
- `src/agent/agent.ts:handleRequest`: 전체를 `runWithContext(ctx, async () => withSpan("agent.handle", {requestId, skill}, ...))`로 wrap
|
||
- `src/llm/llm-client.ts:chatCompletion`:
|
||
- 엔드포인트 루프 시작 전 `circuit.canUse(ep)` 체크
|
||
- 요청 부분을 `withLlmSpan`으로 감싸고 response에서 `usage` 추출해 span attribute로
|
||
- 성공/실패 시 `circuit.record*` 호출
|
||
|
||
**검증**
|
||
1. 부팅 → stdout에 OTel span JSON + pino pretty log
|
||
2. 부하: 100 req 발사 → `circuit:*` Hash에서 `lastCheckedAt` 업데이트가 30s에 한 번 정도만 발생
|
||
3. 고의로 endpoint를 kill → 3회 실패 후 `state: "open"` 전환, 60s 후 half-open 시도
|
||
|
||
---
|
||
|
||
### Phase 2 — State Machine + Intent Classifier (3–4일)
|
||
|
||
**목표**: 흩어진 분기 로직을 순수 함수로 통합. 테스트 가능.
|
||
|
||
**PR 분할 (회귀 위험 완화)**: Phase 2를 **2개 PR로 쪼갠다**. golden set이 없는 시점에 v1 코드를 일괄 삭제하면 회귀를 잡을 방법이 없음.
|
||
- **PR 2a**: `state/`, `classifier.ts`, `eval/capture.ts` 신규 추가 + `OnboardingSkill.handle`을 derive/classifier로 교체. 단, `message-filter.ts`/`onboarding-prompts.ts`는 **deprecated 표시(@deprecated JSDoc)만 하고 삭제하지 않음**. classifier 내부에서 message-filter 함수를 재사용해 동작 동일성 확보.
|
||
- **PR 2a 머지 후**: 사용자가 `npm run eval:capture` 실행 → §2.5 익명화 파이프라인 통과 → 30–50건 expected 수동 큐레이션 → `src/eval/golden/onboarding.jsonl` 커밋(별도 PR).
|
||
- **PR 2b**: golden set 기반 `npm run eval` 통과 확인 후 `message-filter.ts` 삭제. `onboarding-prompts.ts`는 Phase 3 PR에서 builder 도입과 함께 삭제(Phase 3까지 임시 인라인 prompt 유지 허용 정책 그대로).
|
||
- 이 분할은 v2 직진 원칙을 어기지 않음(feature flag 없음, alias 없음). 단순히 "삭제 시점"을 golden set 확보 직후로 미루는 것.
|
||
|
||
**작업**
|
||
|
||
**2.1 State/Intent 타입**
|
||
- `src/skills/onboarding/types.ts`에 **skill-local 타입** 집중 (§5.5 구조):
|
||
- `OnboardingSession` (기존 onboarding-types.ts 통합)
|
||
- `NicknameIssue` 신규: `{ kind: "missing-tier" | "invalid-age" | "missing-gender" | "wrong-separator" | "unknown-tier" | "other"; message: string; suggestion?: string }`
|
||
- `Example`, `PromptContext` 등 prompts에서 쓰는 공용 타입도 여기 (Phase 3에서 추가)
|
||
- `Blackboard` 타입(§9.3.2)도 여기로 이동
|
||
- 신규 `src/skills/onboarding/state/onboarding-state.ts`:
|
||
```ts
|
||
export type OnboardingPhase =
|
||
| { kind: "fresh" }
|
||
| { kind: "nickname-pending"; current: string }
|
||
| { kind: "photo-pending" }
|
||
| { kind: "both-pending" }
|
||
| { kind: "nickname-rejected"; current: string; issues: NicknameIssue[] }
|
||
| { kind: "photo-rejected"; reason?: string }
|
||
| { kind: "deadline-near"; remaining: ("nickname" | "photo")[] }
|
||
| { kind: "completed" }
|
||
| { kind: "timed-out" };
|
||
|
||
export type Intent =
|
||
| { kind: "greeting" } | { kind: "acknowledgement" }
|
||
| { kind: "status-question" } | { kind: "help-how" } | { kind: "help-where" }
|
||
| { kind: "nickname-question" } | { kind: "photo-question" }
|
||
| { kind: "discord-question" } | { kind: "age-question" }
|
||
| { kind: "chitchat" } | { kind: "off-topic-to-other" } | { kind: "unknown" };
|
||
|
||
export interface DerivedState {
|
||
phase: OnboardingPhase; intent: Intent;
|
||
shouldRespond: boolean;
|
||
responseMode: "skip" | "template" | "llm" | "llm-with-tools";
|
||
suggestedMaxTokens: number;
|
||
allowShortResponse: boolean;
|
||
tier: 0 | 1 | 2;
|
||
}
|
||
```
|
||
|
||
**2.2 derive (pure function)**
|
||
- 신규 `src/skills/onboarding/state/derive.ts`
|
||
- 입력: (session | null, trigger, intent)
|
||
- 출력: DerivedState. 규칙:
|
||
- trigger=`new-member` → shouldRespond=false (본체가 템플릿 발송)
|
||
- intent=`off-topic-to-other`|`chitchat` → shouldRespond=false
|
||
- intent=`greeting`|`acknowledgement` → responseMode=`template`, tier 0
|
||
- phase=`nickname-rejected` → responseMode=`llm-with-tools`, tier 1
|
||
- phase=`deadline-near` → responseMode=`llm`, tier 1 (중요도 ↑)
|
||
- 그 외 user-message → responseMode=`llm`, tier 0
|
||
- `src/skills/onboarding/state/transitions.ts`: session 필드로부터 phase 유도 (순수)
|
||
|
||
**2.3 Classifier (regex first, LLM fallback)**
|
||
- 신규 `src/skills/onboarding/state/classifier.ts`:
|
||
- 1단계: `message-filter.ts`에서 가져온 regex + 추가 패턴으로 `IntentCandidate[]` 생성
|
||
- 1단계 unknown 또는 confidence < threshold → 2단계 LLM (`CLASSIFIER_FALLBACK_MODEL`, `response_format: {type: "json_object"}`, max_tokens=16, schema `{"intent": "..."}`)
|
||
- 신규 `src/skills/onboarding/state/intent-keywords.ts`: intent → 기대 키워드 사전 (validator에서 사용)
|
||
```ts
|
||
export const EXPECTED_KEYWORDS: Record<Intent["kind"], string[]> = {
|
||
"status-question": ["남았", "완료", "아직", "끝났"],
|
||
"discord-question": ["디스코드"],
|
||
...
|
||
};
|
||
```
|
||
|
||
**2.4 Skill 진입점 재작성**
|
||
- `src/skills/onboarding/skill.ts`의 `handle()` 재작성 (PR 2a에서 `onboarding-skill.ts`를 git mv로 개명 — §5.4):
|
||
```ts
|
||
// src/skills/onboarding/skill.ts (PR 2a git mv로 개명된 파일)
|
||
async handle(req, history) {
|
||
const session = await this.loadSession(req);
|
||
const intent = await classifier.classify(req.userMessage, req.trigger);
|
||
const derived = derive(session, req.trigger, intent);
|
||
if (!derived.shouldRespond) return makeEmpty(req.requestId);
|
||
if (derived.responseMode === "template") return this.handleTemplate(req, derived, session);
|
||
// Phase 4/5에서 orchestrator로 위임. 지금은 기존 generateLlmText 호출하되 derived 사용.
|
||
return this.handleLlm(req, derived, session, history);
|
||
}
|
||
```
|
||
- `message-filter.ts`, `onboarding-prompts.ts`는 **PR 2a에서는 유지**(`@deprecated` 표시만). classifier가 내부적으로 message-filter 함수 재사용. golden set 확보 후 PR 2b에서 `message-filter.ts` 삭제, Phase 3 PR에서 `onboarding-prompts.ts` 삭제. (개명은 line 위 코드 블록 주석 참조 — git mv + handle 재작성을 한 커밋으로)
|
||
|
||
**2.5 eval:capture helper (Phase 5용 준비)**
|
||
- 신규 `src/eval/capture.ts` (스켈레톤 먼저):
|
||
- MongoDB `events`에서 `category: "message.received"` 샘플링
|
||
- `{ input: { request, session, roomContext }, expected: { ...skeleton } }` JSONL 출력
|
||
- expected는 빈 필드로 생성 → 사용자가 수동 큐레이션
|
||
- 신규 `src/eval/anonymize.ts` (capture 파이프라인의 강제 단계):
|
||
- **닉네임/userId**: 결정적 해시(`SHA256(salt+value).slice(0,8)`) 후 `user_<hash>` / 닉네임은 `<nick:hash>`로 치환. salt는 **소스 하드코딩 상수**(`EVAL_ANON_SALT`, env 아님 — 익명화 강도가 아니라 일관성 목적)
|
||
- **`EVAL_ANON_SALT` 저장 위치**: `src/eval/anonymize.ts` 상단에 `const EVAL_ANON_SALT = "lolympus-agent-v1" as const;` 로 **하드코딩**. env-vars/Infisical 경유 X — 값이 바뀌면 기존 golden set과 해시 불일치해서 의미 없음. 값 변경은 golden set 재캡처와 동시에만 허용(PR 설명에 명시)
|
||
- **chatroomId**: 동일 방식으로 `room_<hash>`
|
||
- **메시지 본문**: 전화번호(`/01[016789][- ]?\d{3,4}[- ]?\d{4}/`), 이메일, 카드번호 패턴, KakaoTalk 오픈채팅 링크(`open.kakao.com/o/...` 토큰), Discord 초대(`discord.gg/...`)을 `[REDACTED:phone]` 등으로 치환
|
||
- **기타 ID 필드**(deviceId, sessionToken 등)는 화이트리스트 외 전부 제거
|
||
- **타임스탬프**: 절대시각 → 상대(`+0s`, `+12s` 등)로 변환해 시점 추적 어렵게
|
||
- capture는 위 파이프라인을 **항상 통과시킴** (`--no-anonymize` 플래그 미제공). golden set 커밋 시 평문 PII가 들어갈 수 없도록 강제
|
||
- `src/eval/cli.ts`에 `eval:capture` 명령 추가
|
||
|
||
**2.6 테스트**
|
||
- `src/skills/onboarding/state/derive.test.ts` — 5–10개 불변식 (`shouldRespond=false면 tier=0 & responseMode=skip`, `completed phase면 responseMode=template or skip` 등)
|
||
- `src/skills/onboarding/state/classifier.test.ts` — 기존 message-filter 회귀 케이스 복붙해서 동일 출력 검증
|
||
|
||
**검증**
|
||
- 수동: 로컬에서 기존 요청 5–10종을 NATS로 쏴서 v1 시절과 유사한 응답 나오는지 확인
|
||
- Phase 2 끝난 후 `npm run eval:capture`로 golden set 30–50건 추출 → 사용자 수동 큐레이션 (이 작업은 사용자 몫)
|
||
|
||
---
|
||
|
||
### Phase 3 — Context Engineering + Blackboard (4–5일)
|
||
|
||
**목표**: 응답 품질 ↑, prompt 토큰 ~50% 감축.
|
||
|
||
**작업**
|
||
|
||
**3.1 5-layer prompt**
|
||
- 신규 `src/skills/onboarding/prompts/layers.ts`:
|
||
- `personaLayer()`: 역할 정의, 변하지 않음 (~200 tok)
|
||
- `policyLayer(intent, opts: { toolPolicy?: string })`: 답변 원칙만. intent별 조항 선별 (~100 tok). `toolPolicy`는 optional — Phase 3 시점엔 주입하지 않음. Phase 4에서 `toolPolicy` 인자로 `tool-policy.ts` 출력을 넘겨받아 layer 하단에 append
|
||
- `stateLayer(session)`: 닉네임/하트 상태 (~50 tok). deadline은 **UTC 기반**, 프롬프트에는 KST로 변환해 표시
|
||
- `examplesLayer(intent, n=3)`: intent 매칭 예시 n개
|
||
- `contextLayer(roomContext, history, blackboard, summary)`: 요약 (~300 tok)
|
||
- **Tool 사용 정책은 Phase 4에서 신설** (§9.4.3). Phase 3 policyLayer에는 tool 관련 문구를 넣지 않아 dead text 방지.
|
||
|
||
**Conversation history slice 책임** (§3.1.1):
|
||
- `conversation-store`는 FIFO 20개 원본 유지(변경 없음). **`builder.ts` 책임**: summary 존재 시 `history.slice(-5)`로 잘라 프롬프트에 주입, 없으면 전체(최대 20). store는 얇게 유지.
|
||
- 신규 `src/skills/onboarding/prompts/examples.ts`:
|
||
- 기존 prompt의 15개 예시를 intent별로 분류해 `Record<Intent["kind"], Example[]>`
|
||
- 신규 `src/skills/onboarding/prompts/builder.ts`:
|
||
```ts
|
||
export class PromptBuilder {
|
||
static forDerived(d: DerivedState, ctx: PromptContext) { ... }
|
||
build(): ChatMessage[] { return [
|
||
{ role: "system", content: [persona, policy, state, examples, context].join("\n\n") },
|
||
...historyAsMessages,
|
||
{ role: "user", content: userMessage },
|
||
]; }
|
||
}
|
||
```
|
||
- persona+policy를 **항상 맨 앞**에 (SGLang/vLLM RadixAttention prefix cache 활용. CLIPROXY는 OpenAI compat이라 명시적 `cache_control` 마킹은 미지원 — provider abstraction에 `capabilities.promptCache=false` 고정. 향후 Anthropic 직접 endpoint 추가 시 layer 마킹 hook만 활용)
|
||
- `onboarding-prompts.ts`는 이 PR에서 **삭제**
|
||
|
||
**`contextLayer` 슬롯 상세** (상기 5-layer 중 가장 가변적이므로 별도 명시):
|
||
```
|
||
[최근 요약]
|
||
{summary ?? "(요약 없음)"}
|
||
|
||
[최근 대화 (최신 5턴)]
|
||
{history.slice(-5)}
|
||
|
||
[방 분위기]
|
||
{roomContext.summary}
|
||
|
||
[메모]
|
||
- lastIntent: {bb.lastIntent}
|
||
- openQuestions: {bb.openQuestions.join(", ")}
|
||
```
|
||
summary가 있으면 history는 최신 5턴으로 절단(token 절감). 없으면 전체 history(최대 20개) 사용. slice 책임은 상기 "Conversation history slice 책임"과 동일 (builder).
|
||
|
||
**3.2 Blackboard**
|
||
- 신규 `src/skills/onboarding/state/blackboard.ts`:
|
||
```ts
|
||
interface Blackboard {
|
||
lastIntent?: Intent["kind"];
|
||
lastIntentAt?: string; // UTC ISO
|
||
openQuestions: string[];
|
||
flaggedIssues: string[];
|
||
recentNicknameAttempts: string[];
|
||
toneMemory: { greetedAt?: string; thankedAt?: string };
|
||
}
|
||
```
|
||
- Redis `lolympus-agent:bb:{chatroomId}:{userId}`, TTL `BLACKBOARD_TTL_SEC`
|
||
- `load()`, `update(patch)`, `save()`
|
||
- `OnboardingSkill.handle` 흐름:
|
||
1. `bb = await blackboard.load()`
|
||
2. `builder.build({ ..., blackboard: bb })`
|
||
3. 응답 생성 후 `blackboard.update({ lastIntent: derived.intent.kind, lastIntentAt: nowUtc() })` + save
|
||
|
||
**3.3 Conversation summary (비동기 트리거)**
|
||
- 수정 `src/conversation/conversation-store.ts`:
|
||
- `appendMessage` 후 `history.length > 5` 이면 Redis Stream `lolympus-agent:background`에 `XADD * type summarize chatroomId ... userId ...` 발행
|
||
- `summary` slot: Redis String `lolympus-agent:summary:{chatroomId}:{userId}`, TTL `CONVERSATION_SUMMARY_TTL_SEC`
|
||
- 신규 `src/conversation/summarizer.ts`:
|
||
- `summarize(history, existingSummary?): Promise<string>` — CLIPROXY gpt-5.3-codex-spark 호출, max_tokens=256
|
||
- 이 summarizer는 Phase 5의 worker가 consume. Phase 3에서는 publish만 구현 (worker는 stub).
|
||
|
||
**3.4 테스트/smoke**
|
||
- `prompts/builder.test.ts` — 토큰 수 측정(단순 길이 기준), intent별 다른 예시 선택되는지
|
||
- Phase 3 완료 후 `npm run eval`로 Phase 2 시점 대비 regression 확인 (golden set 기준)
|
||
|
||
**검증**
|
||
- 기존 prompt 토큰(약 1800) → 새 prompt 토큰(약 900) 감소 확인 (OTel span attribute `gen_ai.usage.input_tokens`)
|
||
- 수동: 5개 대표 시나리오에서 응답 톤/품질 동등 이상 확인
|
||
|
||
---
|
||
|
||
### Phase 4 — Tool Calling + Validation (5–7일)
|
||
|
||
**목표**: 환각 제거. deterministic 검증을 LLM이 호출하도록.
|
||
|
||
**작업**
|
||
|
||
**4.1 Tool 인프라**
|
||
- 신규 `src/tools/tool.ts`:
|
||
```ts
|
||
export interface Tool<A, R> {
|
||
name: string;
|
||
description: string; // Anthropic 연구상 가장 중요한 prompt slot
|
||
argsSchema: z.ZodType<A>;
|
||
resultSchema: z.ZodType<R>;
|
||
execute(args: A, ctx: ToolContext): Promise<R>;
|
||
}
|
||
```
|
||
- 신규 `src/tools/registry.ts`: `register(tool)`, `get(name)`, `list()`
|
||
- 신규 `src/tools/parser.ts`: Hermes `<tool_call>{...}</tool_call>` + OpenAI `tool_calls` 양쪽 파싱, 정규화된 `ToolCall[]` 반환
|
||
- 신규 `src/tools/serializer.ts`: tool 선언을 system prompt에 주입하는 포맷터. Hermes spec 준수(`<tools>...</tools>`), OpenAI tools 배열도 생성 (provider별 선택)
|
||
|
||
**4.2 빌트인 도구**
|
||
- `src/tools/builtins/validate-nickname.ts`:
|
||
- args: `{ nickname: string }`, result: `{ valid: boolean, issues: NicknameIssue[], normalized?: string }`
|
||
- `analyzeNicknameIssues` 래핑
|
||
- `src/tools/builtins/check-onboarding-progress.ts`:
|
||
- args: `{ chatroomId, userId }`, result: `{ nicknameDone, photoDone, remainingSteps, deadlineInHours }`
|
||
- session 읽어 가공
|
||
- `src/tools/builtins/lookup-community-rule.ts`:
|
||
- args: `{ topic: "age" | "tier-codes" | "discord-link" | "heart-rule" | "nickname-format" | "deadline" }`, result: `{ topic, text, source: "constants" }`
|
||
- **SoT**: 신규 `src/skills/onboarding/constants.ts` 한 곳에서 모든 규칙 상수 export. 내용:
|
||
- `VALID_TIERS = ["GM","I","B","S","G","P","E","D","M","C","U"]`
|
||
- `MIN_AGE`, `MAX_AGE` (현재 27+ 정책)
|
||
- `DISCORD_INVITE_URL`
|
||
- `HEART_RULE_TEXT`, `NICKNAME_FORMAT_TEXT`
|
||
- `DEADLINE_NEAR_THRESHOLD_MIN` — 데드라인까지 남은 시간이 이 값(분) 이하이면 phase=`deadline-near`로 유도 (derive.ts / transitions.ts가 참조)
|
||
- `ESCALATION_BUDGET_PER_TURN` — §9.4.6 escalation 상한
|
||
- **SoT 정책**: env를 단일 소스로. `constants.ts`는 env 로드 wrapper만 제공:
|
||
```ts
|
||
export const DEADLINE_NEAR_THRESHOLD_MIN = Number(process.env.DEADLINE_NEAR_THRESHOLD_MIN ?? 30);
|
||
export const ESCALATION_BUDGET_PER_TURN = Number(process.env.ESCALATION_BUDGET_PER_TURN ?? 2);
|
||
// 문자열/JSON 상수(VALID_TIERS, HEART_RULE_TEXT 등)는 env 없이 constants.ts에 직접 기재 (유일 SoT)
|
||
```
|
||
기본값은 **env catalog(§6.2)** 기준. `constants.ts`는 값을 독자 하드코딩하지 않음(중복 SoT 금지).
|
||
- validate-nickname / 템플릿 fallback / lookup-community-rule이 모두 이 파일을 참조 (중복 정의 금지)
|
||
- tool은 단순히 `CONSTANTS[topic]` 조회 후 zod로 narrowing
|
||
- `src/tools/builtins/get-room-context.ts`:
|
||
- args: `{ chatroomId, limit?: number }`, result: `{ messages: RoomMessage[] }`
|
||
- RoomContextService 래핑
|
||
- **주의**: LLM이 호출한 경우만 조회. Phase 4 이전에는 `OnboardingSkill.handleUserMessage`에서 unconditional 조회 → 이걸 LLM 결정 기반으로 전환(contextLayer에는 blackboard 요약만 포함하고, 상세 room 조회는 LLM이 필요하다 판단할 때만 tool 호출)
|
||
|
||
**4.3 Tool 사용 정책 (prompt 주입)**
|
||
- 신규 `src/skills/onboarding/prompts/tool-policy.ts`:
|
||
```ts
|
||
export function buildToolPolicy(intent: Intent["kind"], phase: OnboardingPhase["kind"]): string {
|
||
// intent/phase 조합 → "언제 어떤 tool을 부를지" 짧은 지침 생성
|
||
// 예: nickname-rejected + nickname-pending → "닉네임 후보가 나오면 validate-nickname을 먼저 호출한 뒤 diff를 설명"
|
||
// answer-direct 계열 → "도구 호출 없이 즉답"
|
||
}
|
||
```
|
||
- `prompts/builder.ts`가 **policy layer** 구성 시 `buildToolPolicy(derived.intent.kind, derived.phase.kind)`를 호출해 system prompt에 주입
|
||
- 용도:
|
||
- LLM이 tool을 과도하게 호출/미호출하지 않도록 intent별 기대 동작 명시
|
||
- Planner(§9.5.1)가 `suggestedTools`를 고를 때도 동일 정책을 참고 (prompt에 함께 주입)
|
||
- serializer.ts가 선언하는 tool 자체는 전체(혹은 Planner subset) — 이 정책은 **사용 가이드**라는 점에서 구분
|
||
- intent/phase 조합 수가 적고(~10×9=90) 순수 함수라 간단한 lookup table + default로 구현. 별도 LLM 호출 없음
|
||
|
||
**4.4 Tool loop**
|
||
- 신규 `src/skills/onboarding/runtime/tool-loop.ts`:
|
||
```ts
|
||
async runWithTools(messages, toolSet, llmOpts, maxHops=2): Promise<string> {
|
||
for (let hop = 0; hop <= maxHops; hop++) {
|
||
const resp = await llm.chatCompletion(messages, llmOpts);
|
||
const toolCalls = parseToolCalls(resp);
|
||
if (toolCalls.length === 0) return resp.content;
|
||
if (hop === maxHops) {
|
||
// hop 초과: "이제 tool 없이 답만 해" 강제 프롬프트로 한번 더 호출
|
||
messages.push({ role: "user", content: "도구 없이 지금까지 얻은 정보로만 한국어 문장으로 답해줘." });
|
||
const finalResp = await llm.chatCompletion(messages, { ...llmOpts, tools: undefined, maxTokens: Math.min(256, llmOpts.maxTokens) });
|
||
return finalResp.content;
|
||
}
|
||
for (const call of toolCalls) {
|
||
const tool = registry.get(call.name);
|
||
const validated = tool.argsSchema.parse(call.arguments);
|
||
const result = await withToolSpan(call.name, validated, () => tool.execute(validated, toolCtx));
|
||
messages.push(provider.formatToolResult(call, result)); // §5.2 provider 추상화 경유 — cliproxy/openrouter는 role:"tool", llama는 Hermes <tool_response>
|
||
}
|
||
}
|
||
}
|
||
```
|
||
- 실패 시 (parse 에러, tool throw) → 템플릿 fallback
|
||
|
||
**4.5 Validator**
|
||
- 신규 `src/skills/onboarding/runtime/validator.ts`:
|
||
- 기존 `postProcessResponse` 흡수 (URL 화이트리스트, 마크다운 제거, 600자 절단, `<think>` 제거, `[NO_RESPONSE]` 처리)
|
||
- **신규 규칙**:
|
||
- `stateConsistency`: 응답에 "디스코드" + phase가 nickname/photo pending → reject
|
||
- `nicknameExampleConsistency`: 응답에 닉네임 예시(`.+/\d{2}/(남|여)/[GIBSPEDMCU]|GM`)가 있으면 regex 통과
|
||
- `intentAlignment`: `EXPECTED_KEYWORDS[intent]` 중 하나 이상 포함
|
||
- `minLength`: `!allowShortResponse && length < 10` → reject
|
||
- `phraseRepetition`: bigram 3회+ 반복 → soft-warn
|
||
- 반환: `{ status: "pass" | "soft-warn" | "reject", text: string, reasons: string[] }`
|
||
- reject → 템플릿 fallback
|
||
|
||
**4.6 Self-critique (Tier 2 한정) + Dynamic Tier Escalation**
|
||
- 신규 `src/skills/onboarding/runtime/critic.ts`:
|
||
- `critique(draft, derived, ctx): Promise<{ text: string; changed: boolean }>`
|
||
- Critic prompt: "교정 필요하면 교정된 응답만, 필요 없으면 `[OK]`만"
|
||
- max_tokens=512 cap. `[OK]`로 시작 → changed=false (원본 유지)
|
||
- **Dynamic tier escalation** (orchestrator가 validator 결과 기반으로 동적 승격):
|
||
- `derived.tier`는 시작 tier일 뿐. validator/critic 결과에 따라 같은 turn 내에서 승격 가능
|
||
- 승격 규칙:
|
||
- tier 0 응답이 validator `soft-warn ≥ 2` → tier 1 Planner+Responder로 1회 재시도
|
||
- tier 1 응답이 validator `soft-warn ≥ 2` 또는 `intentAlignment` 실패 → tier 2 Critic 호출
|
||
- tier 2 응답도 validator `reject` → 템플릿 fallback (이미 §9.4.5 정책)
|
||
- **escalation budget**: turn당 추가 LLM 호출 ≤ 2회. deadline 50% 이상 잔여 + budget 남았을 때만 escalate. 그 외엔 현재 응답 그대로 통과 (validator soft-warn은 로그만)
|
||
- 승격 사실은 OTel span attribute `agent.tier.escalated_from/to`에 기록 → shadow eval에서 분포 확인
|
||
- **Phase 4 / Phase 5 경계**: §9.4.6의 escalation 규칙/예산 **정의**는 Phase 4 PR에 포함하되, **실제 실행 orchestrator는 §9.5.1에서 완성**. Phase 4 PR이 보장하는 건 (a) validator가 `status: "pass" | "soft-warn" | "reject"` + `warnings[]` 을 반환하는 인터페이스, (b) critic이 `[OK]` 규약을 지키는 인터페이스 두 가지. Phase 4 orchestrator는 §9.4.7 "얇게" — llm / llm-with-tools 분기만. escalation loop/budget/deadline 체크는 §9.5.1 orchestrator가 소비.
|
||
|
||
**4.7 Orchestrator 통합 (얇게, Phase 5에서 확장)**
|
||
- `skill.ts`의 LLM 경로(Phase 2에서 개명 완료)에서 `derived.responseMode === "llm-with-tools"` 시 `tool-loop.runWithTools` 호출, 그 외는 단순 `chatCompletion`
|
||
|
||
**4.8 테스트**
|
||
- `validator.test.ts`: 10개 케이스 (state 모순, 닉네임 예시 regex, intent 매칭 등)
|
||
- `tools/parser.test.ts`: Hermes + OpenAI 포맷 각각 3-5개
|
||
- `tool-loop.test.ts`: mock LLM으로 hop 동작 시나리오
|
||
|
||
**검증**
|
||
- `npm run eval` regression 없음
|
||
- 수동: nickname-rejected 3종(3-part, 나이 문자, 티어 오탈자) → validate-nickname 호출 트레이스 + 정확한 diff 응답
|
||
|
||
---
|
||
|
||
### Phase 5 — Orchestration + Eval + Alerting (5–7일)
|
||
|
||
**목표**: 지속 개선 루프 + tier별 모델 라우팅 + 실시간 품질 모니터링.
|
||
|
||
**작업**
|
||
|
||
**5.1 Orchestrator**
|
||
- 신규 `src/skills/onboarding/runtime/orchestrator.ts`:
|
||
```ts
|
||
async run(derived, messages, ctx): Promise<string> {
|
||
const deadline = ctx.deadlineAt; // §7 참조 — 본체 NATS timeout 5s에서 안전 마진 0.5s 차감
|
||
switch (derived.tier) {
|
||
case 0: return this.runTier0(derived, messages, ctx, deadline);
|
||
case 1: return this.runTier1(derived, messages, ctx, deadline);
|
||
case 2: return this.runTier2(derived, messages, ctx, deadline);
|
||
}
|
||
}
|
||
// tier 0: 단일 chatCompletion (+tool loop if llm-with-tools)
|
||
// tier 1: Planner LLM (PlannerOutput JSON) → Responder LLM
|
||
// tier 2: tier 1 + Critic → (조건부 Rewrite)
|
||
```
|
||
- `skill.ts`(Phase 2에서 개명)에서 이 orchestrator 사용
|
||
|
||
**5.1.1 Planner output 스키마 (zod)**
|
||
- 신규 `src/skills/onboarding/runtime/planner-schema.ts`:
|
||
```ts
|
||
import { z } from "zod";
|
||
|
||
export const PlannerOutputSchema = z.object({
|
||
approach: z.enum([
|
||
"answer-direct", "ask-clarification", "redirect-to-step",
|
||
"validate-then-explain", "lookup-rule-then-answer", "soft-decline",
|
||
]),
|
||
targetPhase: z.enum([
|
||
"fresh", "nickname-pending", "photo-pending", "both-pending",
|
||
"nickname-rejected", "photo-rejected", "deadline-near", "completed", "timed-out",
|
||
]).optional(),
|
||
mustInclude: z.array(z.string().min(1).max(80)).max(5).default([]),
|
||
mustAvoid: z.array(z.string().min(1).max(80)).max(5).default([]),
|
||
suggestedTools: z.array(z.enum([
|
||
"validate-nickname", "check-onboarding-progress",
|
||
"lookup-community-rule", "get-room-context",
|
||
])).max(3).default([]),
|
||
tone: z.enum(["friendly", "concise", "encouraging", "neutral", "apologetic"]).default("friendly"),
|
||
targetLengthChars: z.number().int().min(20).max(500).default(150),
|
||
rationale: z.string().max(200), // 디버깅/eval용. 응답 본문에는 노출 X
|
||
});
|
||
export type PlannerOutput = z.infer<typeof PlannerOutputSchema>;
|
||
```
|
||
- Planner 호출 옵션: `response_format: { type: "json_object" }`, `max_tokens: PLANNER_MAX_TOKENS`, `TIER1_PLANNER_MODEL`.
|
||
- **파싱 실패 fallback**: zod parse 실패 시 1회 재시도("스키마에 맞춰 다시"), 그래도 실패하면 Planner 결과 무시 → Responder를 derived 기반 기본값으로 직접 호출 (tier 0 경로와 동일하게 degrade).
|
||
- Responder는 system prompt에 PlannerOutput을 "[PLAN] approach=X, mustInclude=[...]" 형태로 주입. mustInclude/mustAvoid는 §9.4.5 validator가 동일 케이스에서 재검증.
|
||
- **suggestedTools 전달 방식** (Planner → tool-loop 연계):
|
||
- Responder 호출 시 prompt 주입뿐 아니라 **tool-loop에 toolSet 제한** 전달:
|
||
```ts
|
||
const toolSet = plan.suggestedTools.length > 0
|
||
? registry.pick(plan.suggestedTools) // 화이트리스트
|
||
: registry.all(); // Planner가 비워두면 전체 허용
|
||
return runWithTools(messages, toolSet, { ...llmOpts, tier: 1 });
|
||
```
|
||
- 이렇게 하면 serializer가 실제 선언하는 tool도 그 subset으로 제한 → LLM이 관계 없는 tool 호출 확률 ↓, 토큰 절감.
|
||
- Planner가 `approach="answer-direct"`이면 `toolSet=[]` 강제 → tool-loop가 hop 0에서 종료.
|
||
|
||
**5.2 LLM client tier routing**
|
||
- 수정 `src/llm/llm-client.ts`: `chatCompletion(messages, opts)` — routing.ts로 위임. `opts` 타입:
|
||
```ts
|
||
interface ChatCompletionOpts {
|
||
tier: 0 | 1 | 2;
|
||
modelOverride?: string;
|
||
tools?: Tool<any, any>[]; // Phase 4 tool-loop가 주입
|
||
jsonMode?: boolean; // response_format: json_object
|
||
maxTokens?: number; // 미지정 시 tier별 기본(TIER{N}_MAX_TOKENS)
|
||
temperature?: number;
|
||
signal?: AbortSignal; // §7 deadline 전파 — 초과 시 AbortError → validator reject → 템플릿 fallback
|
||
deadlineMs?: number; // 남은 budget 힌트. provider가 내부 http 타임아웃에 반영
|
||
role?: "planner" | "responder" | "critic"; // routing.selectModel용
|
||
}
|
||
```
|
||
- 신규 `src/llm/routing.ts`:
|
||
```ts
|
||
function selectProviders(tier): Provider[] {
|
||
const chain = [cliproxy];
|
||
if (OPENROUTER_ENABLED) chain.push(openrouter);
|
||
chain.push(llama);
|
||
return chain;
|
||
}
|
||
function selectModel(tier, role?): string {
|
||
if (role === "planner") return TIER1_PLANNER_MODEL;
|
||
if (role === "critic") return TIER2_CRITIC_MODEL;
|
||
return tier === 0 ? TIER0_MODEL : TIER1_RESPONDER_MODEL;
|
||
}
|
||
```
|
||
- 신규 `src/llm/providers/{cliproxy,llama,openrouter}.ts`: 공통 인터페이스
|
||
```ts
|
||
export interface Provider {
|
||
name: "cliproxy" | "llama" | "openrouter";
|
||
capabilities: {
|
||
jsonMode: boolean; // response_format: json_object 지원
|
||
toolCalls: "openai" | "hermes" | "none"; // 네이티브 tool 포맷
|
||
promptCache: false; // 현재 모든 provider false (CLIPROXY OpenAI compat은 자동 prefix cache만)
|
||
};
|
||
complete(req: NormalizedRequest): Promise<NormalizedResponse>;
|
||
formatToolDeclarations(tools: Tool[]): { systemAddendum?: string; openAiTools?: any[] };
|
||
formatToolResult(call: ToolCall, result: unknown): ChatMessage;
|
||
}
|
||
```
|
||
- **provider별 tool result 직렬화** (Phase 4 §9.4.4 tool-loop이 이걸 호출):
|
||
- `cliproxy.formatToolResult` → `{ role: "tool", tool_call_id: call.id, content: JSON.stringify(result) }`
|
||
- `openrouter.formatToolResult` → 동일 (OpenAI 호환)
|
||
- `llama.formatToolResult` → `{ role: "user", content: "<tool_response>\n" + JSON.stringify({name: call.name, result}) + "\n</tool_response>" }` (Hermes 규약)
|
||
- **provider별 tool 선언 주입**:
|
||
- cliproxy/openrouter → request `tools` 필드(OpenAI tools array)
|
||
- llama → system prompt 끝에 `<tools>[...]</tools>` 블록 추가, parser는 응답에서 `<tool_call>...</tool_call>` 매칭
|
||
- llama provider는 `response_format` 미지원 가정 → Hermes `<json>...</json>` 포맷으로 강제, parser가 감지
|
||
|
||
**5.3 Golden set + runner + judges**
|
||
- `src/eval/golden/onboarding.jsonl` (사용자 큐레이션 결과 여기에 커밋. PR 첨부)
|
||
- 신규 `src/eval/runner.ts`:
|
||
- golden 로드 → 각 케이스를 in-process에서 실행 (NATS 거치지 않음, `Agent.handleRequest`를 직접 함수 호출)
|
||
- rule-judge + llm-judge 각각 점수화
|
||
- 리포트: `eval-reports/{timestamp}.json` + 콘솔 요약
|
||
- 신규 `src/eval/judges/rule-judge.ts`:
|
||
- expected의 `mustIncludeAny`, `mustNotInclude`, `responseMode`, `intent` 매칭
|
||
- 신규 `src/eval/judges/llm-judge.ts`:
|
||
- CLIPROXY `gpt-5.3-codex-spark` 호출
|
||
- prompt: "친근함(1-5), 정확성(1-5), 간결성(1-5), 범위준수(1-5) + 한줄 이유"
|
||
- `response_format: json_object`로 강제
|
||
- 신규 `src/eval/cli.ts`: commander/yargs 기반 `eval`, `eval:capture`, `eval:baseline` (현재 baseline 업데이트)
|
||
- `package.json`: `"eval": "tsx src/eval/cli.ts run --set=golden"`, `"eval:capture": "tsx src/eval/cli.ts capture"`
|
||
|
||
**5.4 Shadow eval + Worker**
|
||
- 신규 `src/eval/shadow-bus.ts`:
|
||
- `publish(input, output, derived): void` — `XADD lolympus-agent:background MAXLEN ~ $BACKGROUND_STREAM_MAXLEN * type shadow-eval input ... output ... derived ...` fire-and-forget. **MAXLEN은 env에서 로드** (리터럴 금지)
|
||
- **Stratified sampling** (tier별 분리, 균등 sampling이면 tier 1/2가 거의 안 잡힘):
|
||
```ts
|
||
const rate = {
|
||
0: SHADOW_EVAL_SAMPLING_RATE_TIER0, // 기본 0.1
|
||
1: SHADOW_EVAL_SAMPLING_RATE_TIER1, // 기본 0.5
|
||
2: SHADOW_EVAL_SAMPLING_RATE_TIER2, // 기본 1.0
|
||
}[derived.tier];
|
||
if (Math.random() >= rate) return;
|
||
```
|
||
- 신규 `src/eval/shadow-worker.ts`:
|
||
- Redis Stream consumer group `bg-worker`, block 5s
|
||
- `type=shadow-eval` → llm-judge 호출 → `XADD lolympus-agent:eval:results MAXLEN ~ $EVAL_STREAM_MAXLEN * ...` → **`XACK`** (MAXLEN 누락 시 Stream 무한 증가, TTL 미적용)
|
||
- `type=summarize` → summarizer 호출 → `SET lolympus-agent:summary:{chatroomId}:{userId} <text> EX $CONVERSATION_SUMMARY_TTL_SEC` (TTL 필수, 기본 24h. 누락 시 summary가 영구 저장됨) → **`XACK`**
|
||
- **Retry 집계**: Stream 메시지는 불변이므로 retry count를 메시지 field로 덮어쓰지 않고 **consumer group의 `XPENDING` delivery count** 사용. delivery count ≥ 3이면 DLQ로 이동 — `XADD lolympus-agent:background:dlq * type <orig> payload <json> retryCount <n> lastError <msg> originalId <streamId>` 후 원본은 `XACK`으로 종료 (사일런트 drop 방지)
|
||
- **부트스트랩 절차** (worker 시작 시 1회):
|
||
```ts
|
||
try { await redis.xgroup("CREATE", "lolympus-agent:background", "bg-worker", "$", "MKSTREAM"); }
|
||
catch (e) { if (!String(e).includes("BUSYGROUP")) throw e; } // 이미 있으면 무시
|
||
```
|
||
- **Pending entries 복구** (worker 재기동 시): 시작 직후 `XPENDING ... bg-worker - + 100` 조회 → `XCLAIM`으로 본인 consumer로 이양 → 처리 → 위와 동일한 retry/DLQ 정책 적용
|
||
- **Graceful shutdown**: `SIGTERM`/`SIGINT` 수신 시 (1) 신규 `XREADGROUP` 호출 중단, (2) in-flight 작업 완료까지 최대 10s 대기, (3) `XACK` 마무리 후 redis quit. PM2 `kill_timeout: 12000` 설정
|
||
- **DLQ 조사 절차** (수동 운영): `redis-cli XRANGE lolympus-agent:background:dlq - + COUNT 50`으로 payload/retryCount/lastError 확인. 재처리 자동화 헬퍼는 **필요 시점에** 별도 추가 (현 단계에서는 구현 X — DLQ 엔트리 발생 자체가 이상 신호이므로 사용자 수동 조사 우선). alert 별도 발송 X — 정기 점검으로 충분
|
||
- 신규 `src/workers/background.ts`: 위 worker를 부트스트랩하는 엔트리 (별도 PM2). signal handler 등록 + redis/nats 연결 lifecycle 관리
|
||
- `ecosystem.config.js`:
|
||
```js
|
||
module.exports = {
|
||
apps: [
|
||
{ name: "agent", script: "dist/main.js", instances: 1, max_memory_restart: "512M" },
|
||
{ name: "agent-worker", script: "dist/workers/background.js", instances: 1, max_memory_restart: "512M" },
|
||
]
|
||
};
|
||
```
|
||
- `launch-server.ps1`: 기존 분기(PM2/직접실행) 유지하되, PM2 분기에서 `pm2 start ecosystem.config.js --only agent,agent-worker`로 변경. 직접 실행은 main만(worker는 PM2 강제)
|
||
|
||
**5.5 Alert**
|
||
- 신규 `src/observability/alert.ts`:
|
||
- `sendAlert(payload: AlertPayload): Promise<void>`
|
||
- Rate limit: Redis `lolympus-agent:alert:dedupe:{kind}` SETNX + EXPIRE
|
||
- NATS publish `lolympus-agent.alert`
|
||
- shadow-worker가 주기적으로 (1분 tick) eval 결과 + circuit 상태 aggregate:
|
||
- p95 latency > `ALERT_THRESHOLD_P95_LATENCY_MS` → alert
|
||
- 최근 window 평균 점수가 baseline 대비 `ALERT_THRESHOLD_EVAL_SCORE_DROP_PCT` 하락 → alert
|
||
- LLM error rate > `ALERT_THRESHOLD_LLM_ERROR_RATE` → alert
|
||
- **Circuit breaker open 감지**: worker가 1분 tick마다 `SCAN 0 MATCH lolympus-agent:circuit:* COUNT 100` (cursor 0 될 때까지 loop — `KEYS`는 blocking이라 금지) → 각 Hash의 `state=="open"`이면 `kind=endpoint-down` alert publish. rate-limit은 §8 Redis Schema의 `lolympus-agent:alert:dedupe:endpoint:{endpointHash}` key로 처리 (동일 endpoint 재알림 5분 내 1회). agent process 측에서 pub/sub 이벤트를 따로 내보내지 않음 — Redis Hash가 SoT이므로 worker가 폴링만으로 충분
|
||
- **lolympus 본체 측 변경**: `lolympus-agent.alert` 구독 후 관리자 채팅방에 카톡 발송 (본체 PR 별도)
|
||
|
||
**5.6 Summary worker 활성화**
|
||
- Phase 3에서 stub으로 둔 consumer를 shadow-worker에서 실제 구현
|
||
- summary 생성 실패 시 2회 재시도, 그 후 drop + warn log
|
||
|
||
**5.7 테스트**
|
||
- `orchestrator.test.ts`: tier 분기 mock 테스트
|
||
- `judges/*.test.ts`: rule-judge 고정 case, llm-judge는 mock response
|
||
- E2E smoke: `npm run eval` 돌려 골든셋 ≥ 80% pass
|
||
|
||
**검증**
|
||
1. shadow eval: 프로덕션 부팅 5분 후 `XLEN lolympus-agent:eval:results` ≥ 1
|
||
2. 고의로 latency 3s 초과 응답 유발 → `lolympus-agent.alert` publish 확인 (NATS 로그)
|
||
3. OpenRouter enable → tier 1 호출 시 라우팅 확인
|
||
4. `npm run eval` 결과가 eval-reports/에 저장, baseline과 diff 출력
|
||
|
||
---
|
||
|
||
## 10. Migration Strategy (v2 직진)
|
||
|
||
1. Phase 0~5는 각 **독립 PR**로 순차 머지. 각 PR 끝에 v2가 곧바로 활성화됨.
|
||
2. v1 코드는 각 PR 내에서 즉시 삭제 (alias 단계 없음). backward-compat 고려 없음.
|
||
- **예외: Phase 2는 golden set 확보를 위해 §9 Phase 2의 PR 2a/2b 분할 정책 적용** — PR 2a에서 `message-filter.ts`는 `@deprecated` 표시만, PR 2b에서 `npm run eval` 통과 후 삭제. `onboarding-prompts.ts`는 Phase 3 PR에서 builder 도입과 함께 삭제. 이 지연은 feature flag/alias 없이 "삭제 시점"만 1 PR 미루는 것이라 v2 직진 원칙을 어기지 않음.
|
||
3. feature flag 없음.
|
||
4. Phase 2 PR 2a 머지 후 → 사용자가 `npm run eval:capture` 실행 → golden set 큐레이션(30–50건) → 별도 PR로 `src/eval/golden/onboarding.jsonl` 커밋 → 이후 PR 2b 진행.
|
||
5. Phase 3 이후 각 PR에서 `npm run eval`을 CI gate로. 회귀 시 PR 블록.
|
||
6. 프로덕션 배포 후 shadow eval 점수 하락 알림 → **사용자 판단으로 git revert** (자동 rollback 없음).
|
||
|
||
---
|
||
|
||
## 11. Risks & Mitigations
|
||
|
||
| 리스크 | 영향 | 완화 |
|
||
|---|---|---|
|
||
| CLIPROXY 장애 | 모든 tier 영향 | circuit breaker + 로컬 Qwen 폴백. Phase 5의 alert가 감지 |
|
||
| 4B Qwen 폴백 품질 | tier 1/2에서 fallback 시 응답 품질 ↓ | CLIPROXY 실패로 llama 폴백 시 §9.5.2 provider가 `capabilities.toolCalls="hermes"`에 맞춰 tool 선언/결과를 Hermes 포맷으로 자동 변환. 정확성은 §9.4.5 validator + Phase 5 escalation으로 재검증/재시도하여 보완 |
|
||
| Multi-layer prompt가 오히려 품질 하락 | 응답 톤 변화 | Phase 3 완료 후 `npm run eval` smoke로 확인, 안 좋으면 layers 재조정 |
|
||
| shadow eval 비용 | CLIPROXY 호출량 | tier별 sampling rate 조절 (`SHADOW_EVAL_SAMPLING_RATE_TIER{0,1,2}`, prod 기본 tier 0=0.1, tier 1=0.5, tier 2=1.0) |
|
||
| Phase 3/4 직진 후 Phase 5에서 버그 발견 | 디버깅 어려움 | Phase 끝마다 smoke eval 돌리고, 각 phase PR 분리 유지 (revert 용이) |
|
||
| OTel overhead | 부하 ↑ | prod sampling 10%, exporter=stdout(망가지지 않음) |
|
||
| OpenAI-compat JSON 모드 비호환 | 일부 응답 파싱 실패 | Hermes `<json>` fallback 파서. llama provider에서 강제 |
|
||
| launch-server.ps1 Windows only | 배포 환경 제약 | 기존 Windows 환경 그대로 유지. Linux 배포는 별도 검토 |
|
||
| lolympus 본체 `lolympus-agent.alert` 구독 미구현 시 | alert 사일런트 drop | Phase 5 롤아웃 전 본체 변경 PR 먼저 |
|
||
| eval:capture가 MongoDB 부하 | 일시적 read 부하 | 샘플링 + 쿼리 시 `{chatroomId, category, "data.body.timestamp"}` 복합 인덱스 확인/생성. `eval:capture` 실행은 개발자 수동 |
|
||
|
||
---
|
||
|
||
## 12. Verification Plan
|
||
|
||
### Phase 별 (각 phase PR 머지 조건)
|
||
|
||
| Phase | 검증 |
|
||
|---|---|
|
||
| 0 | `typecheck && lint && build && start:dev` 통과, 기능 동일 |
|
||
| 1 | stdout OTel span + pino pretty, 100 req 중 health 호출 ≤ 5회 |
|
||
| 2a | `derive.test.ts`, `classifier.test.ts` 통과. `message-filter.ts`와 classifier의 동일 입력 회귀 테스트 통과(classifier 내부 재사용이라 의미 있음). 수동 5 시나리오 회귀 없음. `onboarding-skill.ts` → `skill.ts` 개명 확인 |
|
||
| 2-curation | (golden set 커밋 전용 PR) `eval:capture` 결과 jsonl에 평문 PII 0건(grep 기반 검사), expected 필드 30–50건 채워짐, `npm run eval --dry-run`이 golden set 파싱 성공 |
|
||
| 2b | `npm run eval` 골든셋 규칙 판정 ≥ 80% pass 시 `message-filter.ts` 삭제 허용. 이후 grep으로 dead import 0건 확인 |
|
||
| 3 | `input_tokens` span에서 ~50% 감소, `onboarding-prompts.ts` 삭제 확인, 수동 5 시나리오 품질 동등 이상, smoke `npm run eval` regression 없음 |
|
||
| 4 | `validator.test.ts`, `tool-loop.test.ts`, `tools/parser.test.ts` 통과. nickname-rejected 3종에서 `validate-nickname` tool span 트레이스 확인. tool-policy 주입이 `llm-with-tools` 케이스에서만 발생 확인 |
|
||
| 5 | `npm run eval` 골든셋 ≥ 80% pass, shadow eval 5분 내 결과 ≥ 1건, alert 재현 테스트(고의 latency 3s 초과) 통과, tier escalation 분포 로그 확인, smoke eval 실행 구간 동안 DLQ 0건(고의 부하/장애 주입 케이스는 제외) |
|
||
|
||
### 운영 지속 검증
|
||
- Shadow eval LLM-judge 평균 ≥ 4.0/5.0
|
||
- p50 < 800ms, p95 < 2.8s
|
||
- LLM error rate < 10% / 1분
|
||
|
||
---
|
||
|
||
## 13. Minor Decisions (확정 기본값)
|
||
|
||
| 항목 | 결정 |
|
||
|---|---|
|
||
| 영어/외국어 입력 | 시스템 프롬프트에 "한국어로 답변" 유지. 외국어 들어와도 한국어로 응답 |
|
||
| MongoDB 인덱스 | `events` 컬렉션에 `{chatroomId:1, category:1, "data.body.timestamp":-1}` 복합 인덱스 권장. Phase 2 `eval:capture` 구현 시 함께 생성 스크립트 추가 (있으면 skip) |
|
||
| llama.cpp JSON 모드 | `response_format` 미지원 가정. Hermes `<json>...</json>` 사용 + parser.ts가 태그/순수JSON 양쪽 파싱 |
|
||
| Skill 인터페이스 일반화 | Phase 6 보류. 현재 skill 1개. 필요해지면 `declareIntents()` 확장 |
|
||
| 시간대 | 모든 코드/Redis/로그/NATS payload **UTC**. 카톡 사용자에게 노출되는 문장만 KST 변환 |
|
||
| Commit 메시지 컨벤션 | Conventional Commits (`feat:`, `fix:`, `chore:`, `refactor:`, `test:`, `docs:`) |
|
||
|
||
---
|
||
|
||
## 14. Codex Hand-off Checklist
|
||
|
||
Codex(또는 다른 AI)가 이 plan으로 실제 코드 작업할 때 **Phase 0부터 순차 진행**. 각 Phase 완료 기준:
|
||
|
||
- [ ] §9의 Phase 작업 전체 구현
|
||
- [ ] `npm run typecheck && npm run lint && npm run build && npm test` 통과
|
||
- [ ] §12의 Phase별 검증 항목 통과
|
||
- [ ] 해당 Phase의 Critical Files 변경이 §5와 일치
|
||
- [ ] env/키/subject 추가 시 §6/§7/§8 업데이트
|
||
- [ ] 커밋/PR 본문에 "Phase N — \<title\>" 명시
|
||
|
||
**참고 문서**:
|
||
- 기존 `/Users/dahyeon/.claude/plans/graceful-jumping-hoare.md` (초기 plan)
|
||
- 이 문서(`plan.md`)가 최종 버전이며, 충돌 시 이 문서 우선
|
||
|
||
**질문 대응**:
|
||
- plan에 없는 세부 결정이 나오면 이 문서의 Resolved Decisions와 최소 침습 원칙("기존 인터페이스 유지, agent.ts 최소 수정")에 부합하는 방향으로 진행.
|
||
- 불가한 모순 발견 시 작업 중단하고 사용자에게 확인.
|