# 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` 등) - 응답 후처리: `` 제거, 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 │ ├── 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 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 인터페이스 + zod │ ├── registry.ts Tool 등록/조회 │ ├── parser.ts Hermes ... + 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(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` + `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 = { "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_` / 닉네임은 ``로 치환. 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_` - **메시지 본문**: 전화번호(`/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` - 신규 `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` — 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 { name: string; description: string; // Anthropic 연구상 가장 중요한 prompt slot argsSchema: z.ZodType; resultSchema: z.ZodType; execute(args: A, ctx: ToolContext): Promise; } ``` - 신규 `src/tools/registry.ts`: `register(tool)`, `get(name)`, `list()` - 신규 `src/tools/parser.ts`: Hermes `{...}` + OpenAI `tool_calls` 양쪽 파싱, 정규화된 `ToolCall[]` 반환 - 신규 `src/tools/serializer.ts`: tool 선언을 system prompt에 주입하는 포맷터. Hermes spec 준수(`...`), 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 { 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 } } } ``` - 실패 시 (parse 에러, tool throw) → 템플릿 fallback **4.5 Validator** - 신규 `src/skills/onboarding/runtime/validator.ts`: - 기존 `postProcessResponse` 흡수 (URL 화이트리스트, 마크다운 제거, 600자 절단, `` 제거, `[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 { 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; ``` - 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[]; // 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; 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: "\n" + JSON.stringify({name: call.name, result}) + "\n" }` (Hermes 규약) - **provider별 tool 선언 주입**: - cliproxy/openrouter → request `tools` 필드(OpenAI tools array) - llama → system prompt 끝에 `[...]` 블록 추가, parser는 응답에서 `...` 매칭 - llama provider는 `response_format` 미지원 가정 → Hermes `...` 포맷으로 강제, 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} 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 payload retryCount lastError originalId ` 후 원본은 `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` - 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 `` 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 `...` 사용 + 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 — \" 명시 **참고 문서**: - 기존 `/Users/dahyeon/.claude/plans/graceful-jumping-hoare.md` (초기 plan) - 이 문서(`plan.md`)가 최종 버전이며, 충돌 시 이 문서 우선 **질문 대응**: - plan에 없는 세부 결정이 나오면 이 문서의 Resolved Decisions와 최소 침습 원칙("기존 인터페이스 유지, agent.ts 최소 수정")에 부합하는 방향으로 진행. - 불가한 모순 발견 시 작업 중단하고 사용자에게 확인.