Update CLAUDE.md with network diagnostic and AI intent classification docs
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
kappa
31
CLAUDE.md
31
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user