diff --git a/CLAUDE.md b/CLAUDE.md index 08d84db..610cc74 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,13 +15,14 @@ npx wrangler d1 execute telegram-ai-support-db --file=schema.sql # D1 스키마 ``` src/ -├── index.ts # Hono 앱 + cron scheduled handler +├── index.ts # Hono 앱 + queue handler + cron scheduled handler ├── types.ts # 모든 타입 정의 (Env, Telegram, OpenAI, DB 모델) ├── telegram.ts # Telegram Bot API 래퍼 ├── security.ts # webhook 인증, rate limit, admin 체크 ├── agents/ # AI 에이전트 시스템 │ ├── base-agent.ts # 추상 기반 (세션, AI 호출 루프, 마커 처리) │ ├── agent-registry.ts # 우선순위 기반 에이전트 라우팅 +│ ├── diagram-agent.ts # 다이어그램 서브 에이전트 (Mermaid 생성 → Kroki 렌더 → Telegram 전송) │ ├── onboarding-agent.ts # 신규 고객 안내 (multi-round) │ ├── troubleshoot-agent.ts # 장애/문제 해결 (multi-round, 에스컬레이션) │ ├── asset-agent.ts # 자산 조회 (single-shot) @@ -32,13 +33,15 @@ src/ │ ├── wallet-tool.ts # 지갑/충전/거래내역 │ ├── server-tool.ts # 서버 관리 (시작/중지/재부팅) │ ├── service-tool.ts # DDoS/VPN 서비스 상태 -│ ├── d2-tool.ts # D2 다이어그램 렌더링 (Incus jp1 + R2 캐시) │ ├── admin-tool.ts # 관리자 기능 (차단, 입금 확인 등) │ └── knowledge-tool.ts # 지식베이스 검색 +├── consumers/ # 비동기 큐 처리 +│ └── queue-dispatcher.ts # 태그 기반 범용 큐 디스패처 (WORK_QUEUE) ├── services/ # 비즈니스 로직 서비스 │ ├── audit.ts # 감사 로그 │ ├── feedback.ts # 피드백 수집/통계 │ ├── human-handoff.ts # 관리자 에스컬레이션 +│ ├── network-diagnostic.ts # 네트워크 진단 (DNS, ISP 차단, HTTP, TCP, Globalping) │ ├── notification.ts # 관리자 알림 │ ├── pending-actions.ts # 인프라 변경 승인 워크플로우 │ ├── kv-cache.ts # KV 캐시 추상화 @@ -54,34 +57,52 @@ src/ ├── i18n/ # 다국어 (ko, en) └── utils/ # 유틸리티 ├── logger.ts # 구조화 JSON 로깅 + PII 마스킹 - ├── patterns.ts # 의도 감지 정규식 패턴 + ├── patterns.ts # 도구 선택용 정규식 패턴 (에이전트 라우팅은 AI 분류) ├── session-manager.ts # 제네릭 D1 세션 CRUD + TTL ├── circuit-breaker.ts # 서킷 브레이커 패턴 ├── retry.ts # 지수 백오프 재시도 ├── optimistic-lock.ts # 낙관적 잠금 (금융 데이터) ├── metrics.ts # 메트릭 수집기 ├── env-validation.ts # Zod 환경 변수 검증 - └── api-urls.ts # OpenAI/D2 API URL 헬퍼 + └── api-urls.ts # OpenAI API URL 헬퍼 ``` ## Key Patterns - **BaseAgent**: multi-round (도구 실행 -> AI 재호출) vs single-shot (도구 호출 반환 -> 외부 실행) + - `processConsultation(db, userId, msg, env, meta?)` — meta로 chatId/messageId 전달 + - `AgentToolContext`에 chatId/messageId 포함 → 서브 에이전트(DiagramAgent 등)가 Telegram 직접 전송 가능 - **Agent Registry**: 우선순위 순 활성 세션 확인. `__PASSTHROUGH__` → 다음 에이전트로 이관 +- **DiagramAgent**: 서브 에이전트 패턴 (BaseAgent 상속 X, 세션 불필요) + - 에이전트가 `generate_diagram` 도구 호출 → DiagramAgent.generateAndSend() + - OpenAI로 Mermaid 코드 생성 → Kroki로 PNG 렌더 → Telegram sendPhoto 직접 전송 + R2 캐시 + - troubleshoot-agent, onboarding-agent 양쪽에서 사용 +- **Intent Classification**: AI 기반 의도 분류 (message-handler.ts의 `classifyIntent()`) + - troubleshoot / onboarding / billing / asset / general 5개 의도 + - 패턴 매칭이 아닌 AI가 분류 → 자연어 의도 파악 정확도 향상 - **Session markers**: `__SESSION_END__`, `[세션 종료]`, `__ESCALATE__`, `__PASSTHROUGH__` - **Tool selection**: 메시지 패턴 → 카테고리 → 필요한 도구만 OpenAI에 전달 (토큰 절약) +- **Network Diagnostic** (`diagnose_domain` tool in troubleshoot-agent): + - DoH DNS 조회 (Cloudflare 1.1.1.1, Google 8.8.8.8) + - 한국 ISP DNS 차단 감지 (KT/LG/SK) — TCP DNS 와이어 포맷 쿼리 via `cloudflare:sockets` + - HTTP/HTTPS HEAD 요청 연결 테스트 + - TCP 포트 테스트 (사용자 지정 비-HTTP 포트만, HTTP 포트는 fetch로 커버) + - Globalping API — 한국 내 프로브(서울/춘천/대전)에서 Ping + HTTP 응답 시간 측정 - **Pending actions**: 위험한 인프라 변경은 `pending_actions` 테이블에 저장 → 사용자/관리자 승인 후 실행 - **AI fallback**: OpenAI 실패 시 Workers AI (llama-3.1-8b-instruct-fp8) +- **WORK_QUEUE**: 태그 기반 범용 비동기 큐. queue-dispatcher.ts의 TAG_HANDLERS에 태그 → 핸들러 등록으로 확장 ## Bindings (wrangler.toml) - `DB`: D1 데이터베이스 - `AI`: Workers AI +- `WORK_QUEUE`: Cloudflare Queue (태그 기반 범용, queue=work-queue, DLQ=work-queue-dlq) - `RATE_LIMIT_KV`, `SESSION_KV`, `CACHE_KV`: KV 네임스페이스 -- `ASSETS_BUCKET`: R2 버킷 +- `R2_BUCKET`: R2 버킷 - `BOT_TOKEN`, `WEBHOOK_SECRET`, `OPENAI_API_KEY`: 시크릿 - `ADMIN_TELEGRAM_IDS`: 쉼표 구분 관리자 ID - `CLOUD_ORCHESTRATOR`: 서비스 바인딩 +- `KROKI_URL`: 다이어그램 렌더링 서비스 (Mermaid/D2 등, https://kroki.anvil.it.com) ## Testing