Files
lolympus-agent/plan.md
T
2026-04-16 13:48:53 -07:00

1116 lines
70 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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축 점수 + 한줄 이유 |
| `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_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일 |
| `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: "latency" | "eval-score-drop" | "llm-error-rate" | "endpoint-down";
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: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 |
---
## 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 최소 수정")에 부합하는 방향으로 진행.
- 불가한 모순 발견 시 작업 중단하고 사용자에게 확인.