74 KiB
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 (subjectlolympus-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)
- 매 요청마다
/healthcheck (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}
- 온보딩 세션 (lolympus 본체가 작성, agent는 read-only):
- MongoDB (
dakaoDB,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 발송
핵심 원칙
agent.ts(NATS 레이어)는 ALS wrap만 추가. NATS 인터페이스 변경은 신규 subject 추가로만.- 모든 개선은
Skill.handle내부(src/skills/{name}/{state,prompts,runtime}/모듈들)에서.SkillRuntime이라는 별도 클래스는 없으며 "skill의 runtime 모듈군"의 통칭. - 95% 트래픽은 fast path 1-hop. Tier 결정 = DerivedState.tier.
- LLM 호출 수 turn당 평균 1회 목표.
- 모든 시간은 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.tscolocated, 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전역 주입. 주입 방식 — 파일 상단에서: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)
- Redis 의존 부분은
- 린트/포맷: 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.publishsrc/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—summaryslot 추가. 5턴 초과 시 Redis Streamlolympus-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— 의존성 + scriptslaunch-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 fallbacksrc/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 | prodSERVICE_NAME— 기본lolympus-agentNATS_ENDPOINT,NATS_USER,NATS_PASSGARNET_ENDPOINT,GARNET_USERID,GARNET_PASSWORDMONGODB_CONNECTION_STRING,MONGODB_PROJECT_IDCLI_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 예시:
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로 단독 머지 가능.
작업
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
- runtime:
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/*vitest.config.ts(paths alias 동기화),eslint.config.js(flat config, type-checked rules),.prettierrc(print-width 100, single-quote),.editorconfig- 기존
*-types.ts파일을 각 feature 폴더types.ts로 이동src/agent/agent-types.ts→src/agent/types.tssrc/llm/llm-types.ts→src/llm/types.tssrc/room-context/room-context-types.ts→src/room-context/types.tssrc/skills/onboarding/onboarding-types.ts→src/skills/onboarding/types.ts
- 모든 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(envLOG_LEVELoverride) - 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해 importlogger.child({requestId, chatroomId, userId})헬퍼
- 기본 level:
- 전 파일
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
- 각 endpoint key →
1.4 main/agent wiring
src/main.ts:initTracing()→initLogger()→ 기존 부트스트랩src/agent/agent.ts:handleRequest: 전체를runWithContext(ctx, async () => withSpan("agent.handle", {requestId, skill}, ...))로 wrapsrc/llm/llm-client.ts:chatCompletion:- 엔드포인트 루프 시작 전
circuit.canUse(ep)체크 - 요청 부분을
withLlmSpan으로 감싸고 response에서usage추출해 span attribute로 - 성공/실패 시
circuit.record*호출
- 엔드포인트 루프 시작 전
검증
- 부팅 → stdout에 OTel span JSON + pino pretty log
- 부하: 100 req 발사 →
circuit:*Hash에서lastCheckedAt업데이트가 30s에 한 번 정도만 발생 - 고의로 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: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
- trigger=
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": "..."})
- 1단계:
- 신규
src/skills/onboarding/state/intent-keywords.ts: intent → 기대 키워드 사전 (validator에서 사용)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):// 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는 빈 필드로 생성 → 사용자가 수동 큐레이션
- MongoDB
- 신규
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가 들어갈 수 없도록 강제
- 닉네임/userId: 결정적 해시(
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 하단에 appendstateLayer(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[]>
- 기존 prompt의 15개 예시를 intent별로 분류해
- 신규
src/skills/onboarding/prompts/builder.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: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}, TTLBLACKBOARD_TTL_SEC load(),update(patch),save()OnboardingSkill.handle흐름:bb = await blackboard.load()builder.build({ ..., blackboard: bb })- 응답 생성 후
blackboard.update({ lastIntent: derived.intent.kind, lastIntentAt: nowUtc() })+ save
3.3 Conversation summary (비동기 트리거)
- 수정
src/conversation/conversation-store.ts:appendMessage후history.length > 5이면 Redis Streamlolympus-agent:background에XADD * type summarize chatroomId ... userId ...발행summaryslot: Redis Stringlolympus-agent:summary:{chatroomId}:{userId}, TTLCONVERSATION_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: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>+ OpenAItool_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래핑
- args:
src/tools/builtins/check-onboarding-progress.ts:- args:
{ chatroomId, userId }, result:{ nicknameDone, photoDone, remainingSteps, deadlineInHours } - session 읽어 가공
- args:
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_URLHEART_RULE_TEXT,NICKNAME_FORMAT_TEXTDEADLINE_NEAR_THRESHOLD_MIN— 데드라인까지 남은 시간이 이 값(분) 이하이면 phase=deadline-near로 유도 (derive.ts / transitions.ts가 참조)ESCALATION_BUDGET_PER_TURN— §9.4.6 escalation 상한
- SoT 정책: env를 단일 소스로.
constants.ts는 env 로드 wrapper만 제공:기본값은 env catalog(§6.2) 기준.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)constants.ts는 값을 독자 하드코딩하지 않음(중복 SoT 금지). - validate-nickname / 템플릿 fallback / lookup-community-rule이 모두 이 파일을 참조 (중복 정의 금지)
- tool은 단순히
CONSTANTS[topic]조회 후 zod로 narrowing
- args:
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 호출)
- args:
4.3 Tool 사용 정책 (prompt 주입)
- 신규
src/skills/onboarding/prompts/tool-policy.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: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 → rejectnicknameExampleConsistency: 응답에 닉네임 예시(.+/\d{2}/(남|여)/[GIBSPEDMCU]|GM)가 있으면 regex 통과intentAlignment:EXPECTED_KEYWORDS[intent]중 하나 이상 포함minLength:!allowShortResponse && length < 10→ rejectphraseRepetition: 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 정책)
- tier 0 응답이 validator
- 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 evalregression 없음- 수동: 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: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: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 제한 전달:
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에서 종료.
- Responder 호출 시 prompt 주입뿐 아니라 tool-loop에 toolSet 제한 전달:
5.2 LLM client tier routing
- 수정
src/llm/llm-client.ts:chatCompletion(messages, opts)— routing.ts로 위임.opts타입: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: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: 공통 인터페이스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>매칭
- cliproxy/openrouter → request
- 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+ 콘솔 요약
- golden 로드 → 각 케이스를 in-process에서 실행 (NATS 거치지 않음,
- 신규
src/eval/judges/rule-judge.ts:- expected의
mustIncludeAny,mustNotInclude,responseMode,intent매칭
- expected의
- 신규
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로 강제
- CLIPROXY
- 신규
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가 거의 안 잡힘):
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의
XPENDINGdelivery count 사용. delivery count ≥ 3이면 DLQ로 이동 —XADD lolympus-agent:background:dlq * type <orig> payload <json> retryCount <n> lastError <msg> originalId <streamId>후 원본은XACK으로 종료 (사일런트 drop 방지) - 부트스트랩 절차 (worker 시작 시 1회):
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. PM2kill_timeout: 12000설정 - DLQ 조사 절차 (수동 운영):
redis-cli XRANGE lolympus-agent:background:dlq - + COUNT 50으로 payload/retryCount/lastError 확인. 재처리 자동화 헬퍼는 필요 시점에 별도 추가 (현 단계에서는 구현 X — DLQ 엔트리 발생 자체가 이상 신호이므로 사용자 수동 조사 우선). alert 별도 발송 X — 정기 점검으로 충분
- Redis Stream consumer group
- 신규
src/workers/background.ts: 위 worker를 부트스트랩하는 엔트리 (별도 PM2). signal handler 등록 + redis/nats 연결 lifecycle 관리 ecosystem.config.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-downalert publish. rate-limit은 §8 Redis Schema의lolympus-agent:alert:dedupe:endpoint:{endpointHash}key로 처리 (동일 endpoint 재알림 5분 내 1회). agent process 측에서 pub/sub 이벤트를 따로 내보내지 않음 — Redis Hash가 SoT이므로 worker가 폴링만으로 충분
- p95 latency >
- 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
검증
- shadow eval: 프로덕션 부팅 5분 후
XLEN lolympus-agent:eval:results≥ 1 - 고의로 latency 3s 초과 응답 유발 →
lolympus-agent.alertpublish 확인 (NATS 로그) - OpenRouter enable → tier 1 호출 시 라우팅 확인
npm run eval결과가 eval-reports/에 저장, baseline과 diff 출력
10. Migration Strategy (v2 직진)
- Phase 0~5는 각 독립 PR로 순차 머지. 각 PR 끝에 v2가 곧바로 활성화됨.
- 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 직진 원칙을 어기지 않음.
- 예외: Phase 2는 golden set 확보를 위해 §9 Phase 2의 PR 2a/2b 분할 정책 적용 — PR 2a에서
- feature flag 없음.
- Phase 2 PR 2a 머지 후 → 사용자가
npm run eval:capture실행 → golden set 큐레이션(30–50건) → 별도 PR로src/eval/golden/onboarding.jsonl커밋 → 이후 PR 2b 진행. - Phase 3 이후 각 PR에서
npm run eval을 CI gate로. 회귀 시 PR 블록. - 프로덕션 배포 후 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 최소 수정")에 부합하는 방향으로 진행.
- 불가한 모순 발견 시 작업 중단하고 사용자에게 확인.