telegram-ai-support/CLAUDE.md

CLAUDE.md - telegram-ai-support

Telegram AI 고객 지원 봇. Cloudflare Workers + Hono + D1 + KV + R2 + Workers AI.

Commands

npm run typecheck     # TypeScript 타입 체크
npm test              # Vitest 테스트 실행
npx wrangler deploy   # Workers 배포
npx wrangler d1 execute telegram-ai-support-db --file=schema.sql  # D1 스키마 적용

Architecture

src/
├── 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)
│   └── billing-agent.ts        # 결제/충전 (single-shot, optimistic lock)
├── tools/                      # OpenAI Function Calling 도구
│   ├── index.ts                # Zod 검증 + 도구 레지스트리 + 동적 선택
│   ├── domain-tool.ts          # 도메인 WHOIS/등록/관리
│   ├── wallet-tool.ts          # 지갑/충전/거래내역
│   ├── server-tool.ts          # 서버 관리 (시작/중지/재부팅)
│   ├── service-tool.ts         # DDoS/VPN 서비스 상태
│   ├── 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 캐시 추상화
│   └── cron-jobs.ts            # 크론 작업 (만료 알림, 아카이빙, 모니터링)
├── routes/                     # HTTP 라우팅
│   ├── webhook.ts              # Telegram webhook (인증 미들웨어)
│   ├── api.ts                  # 관리자 API
│   ├── health.ts               # 헬스 체크
│   └── handlers/
│       ├── message-handler.ts  # 메시지 처리 파이프라인
│       └── callback-handler.ts # 인라인 키보드 콜백
├── constants/agent-config.ts   # 에이전트별 설정 (TTL, 토큰, 온도)
├── i18n/                       # 다국어 (ko, en)
└── utils/                      # 유틸리티
    ├── logger.ts               # 구조화 JSON 로깅 + PII 마스킹
    ├── 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 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 네임스페이스
• R2_BUCKET: R2 버킷
• BOT_TOKEN, WEBHOOK_SECRET, OPENAI_API_KEY: 시크릿
• ADMIN_TELEGRAM_IDS: 쉼표 구분 관리자 ID
• CLOUD_ORCHESTRATOR: 서비스 바인딩
• KROKI_URL: 다이어그램 렌더링 서비스 (Mermaid/D2 등, https://kroki.inouter.com)

Testing

Vitest + Miniflare. 테스트 setup에서 D1 스키마 자동 초기화.

npm test                          # 전체 실행
npx vitest run tests/security.test.ts  # 단일 파일