From c91b46b3ac385158683f0248ee5e5ab799ee6996 Mon Sep 17 00:00:00 2001 From: kappa Date: Mon, 26 Jan 2026 14:18:45 +0900 Subject: [PATCH] docs: add Server Expert AI documentation CLAUDE.md: - Add server-agent.ts to Core Services table - Add Server Expert AI Flow architecture section - Document session management (KV-based, 1hr TTL) - Add search_trends/lookup_framework_docs tools - Update KV Namespace and Bindings tables README.md: - Add server recommendation AI consultation to features - Add SESSION_KV creation command Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- README.md | 12 ++++++--- 2 files changed, 84 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 01ac7ca..2972d20 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -197,8 +197,12 @@ npm run test:coverage # 커버리지 리포트 **KV Namespace 생성 (최초 1회):** ```bash -# Rate Limiting용 KV Namespace 생성 +# Rate Limiting용 KV Namespace 생성 (필수) wrangler kv:namespace create RATE_LIMIT_KV + +# 서버 상담 세션용 KV Namespace 생성 (서버 추천 기능 사용 시 필수) +wrangler kv:namespace create SESSION_KV + # 출력된 id를 wrangler.toml의 [[kv_namespaces]] 섹션에 입력 ``` @@ -690,6 +694,7 @@ Telegram Webhook → Security Validation → Command/Message Router | `openai-service.ts` | AI 응답 + Function Calling | `generateResponse()`, `executeFunctionCall()` | | `summary-service.ts` | 프로필 시스템 | `updateSummary()`, `getConversationContext()` | | `deposit-agent.ts` | 예치금 함수 (코드 직접 처리) | `executeDepositFunction()` | +| `server-agent.ts` | 서버 전문가 AI 상담 | `processServerConsultation()`, `callServerExpertAI()` | | `security.ts` | Webhook 보안, Rate Limiting (KV) | `validateWebhook()`, `checkRateLimit()` | | `services/notification.ts` | 관리자 알림 (Circuit Breaker, Retry 실패) | `notifyAdmin()` | | `commands.ts` | 봇 명령어 | `handleCommand()` | @@ -727,7 +732,7 @@ end(); // duration 자동 기록 | 도메인 | `manage_domain` | 코드 직접 처리 → Namecheap | 도메인, 네임서버, WHOIS | | 도메인 추천 | `suggest_domains` | GPT + Namecheap | **도메인 추천, 도메인 제안, 도메인 아이디어** | | 예치금 | `manage_deposit` | 코드 직접 처리 | **입금, 충전, 잔액, 계좌, 송금** | -| 서버 | `manage_server` | Cloud Orchestrator (Service Binding) | **서버, VPS, 클라우드, 호스팅** | +| 서버 | `manage_server` | Server Expert AI (세션 기반 상담) | **서버, VPS, 클라우드, 호스팅, 추천** | **Data Layer (D1 SQLite):** | 테이블 | 용도 | 주요 컬럼 | @@ -785,6 +790,72 @@ Rate Limit 초과 → 경고 메시지 전송 + return **로그:** `[ToolSelector] 카테고리: domain, utility / 선택된 도구: manage_domain, ...` +### Server Expert AI Flow + +**목적:** 30년 경력 시니어 아키텍트 페르소나 기반 대화형 서버 추천 + +``` +사용자: "서버 추천해줘" + ↓ +메인 AI → manage_server(action="start_consultation") + ↓ +KV 세션 생성 (server_session:{userId}, TTL 1h) + ↓ +Server Expert AI (gpt-4o-mini + Function Calling) + ├── 페르소나: 30년 경력 클라우드 아키텍트 + ├── 용도/규모 파악 (최대 2번 질문) + ├── [선택] search_trends 호출 (최신 트렌드) + ├── [선택] lookup_framework_docs 호출 (공식 권장 스펙) + └── JSON 응답 {action, message, collectedInfo} + ↓ +┌──────────────────┬──────────────────┐ +│ action="question"│ action="recommend"| +├──────────────────┼──────────────────┤ +│ 추가 정보 수집 │ 자동 스펙 추론 │ +│ (용도, 규모) │ (tech_stack 등) │ +│ 세션 유지 │ Cloud Orchestrator│ +│ │ API 호출 │ +│ │ 세션 삭제 │ +└──────────────────┴──────────────────┘ + ↓ +서버 추천 결과 반환 +``` + +**세션 관리:** +- KV Namespace: `SESSION_KV` +- Key: `server_session:{userId}` +- TTL: 1시간 (자동 만료) +- 상태: `gathering` → `recommending` → `completed` + +**Function Calling 도구:** +| 도구 | 설명 | 용도 | +|------|------|------| +| `search_trends` | Brave Search API | 최신 기술 트렌드, 서버 요구사항 검색 | +| `lookup_framework_docs` | Context7 API | 프레임워크 공식 문서에서 권장 스펙 조회 | + +**자동 추론 (30년 경험 기반):** +| 용도 | 추론된 tech_stack | 추론된 expected_users | +|------|-------------------|---------------------| +| 블로그 / WordPress | `['wordpress']` | 100명 (개인용) | +| 쇼핑몰 / 이커머스 | `['ecommerce']` | 500명 (사업용) | +| 커뮤니티 / 게시판 | `['php', 'mysql']` | - | +| API / 백엔드 | `['nodejs', 'express']` | - | +| 기본값 | `['web']` | 100명 | + +**특징:** +- 경쟁사 (AWS, GCP, Azure, Vultr, Linode) 언급 금지 +- Anvil 서버만 추천 +- 최대 3회 도구 호출 (무한 루프 방지) +- "모르겠어요", "아무거나" → 즉시 추천 (기본값) +- 질문 최대 2번, 이후 자동 추천 + +**관련 파일:** +| 파일 | 역할 | +|------|------| +| `server-agent.ts` | 세션 관리 + Server Expert AI 호출 | +| `tools/server-tool.ts` | Cloud Orchestrator API 연동 | +| `tools/search-tool.ts` | search_trends, lookup_framework_docs 구현 | + --- ## Key Patterns @@ -921,6 +992,7 @@ case 'new_tool': | Binding | 설명 | 생성 명령 | |---------|------|----------| | `RATE_LIMIT_KV` | Rate Limiting 저장소 | `wrangler kv:namespace create RATE_LIMIT_KV` | +| `SESSION_KV` | 서버 상담 세션 저장소 | `wrangler kv:namespace create SESSION_KV` | **Bindings:** | Binding | 타입 | 용도 | @@ -928,6 +1000,7 @@ case 'new_tool': | `DB` | D1 Database | 사용자/메시지/예치금 데이터 | | `AI` | Workers AI | OpenAI 폴백용 | | `RATE_LIMIT_KV` | KV Namespace | 사용자별 Rate Limiting (30 req/60s) | +| `SESSION_KV` | KV Namespace | 서버 상담 세션 저장 (1시간 TTL) | --- @@ -958,6 +1031,7 @@ case 'new_tool': - TLD 가격: 1시간 TTL - Rate Limiting: 사용자별 60초 윈도우 - 알림 Rate Limit: 1시간 (같은 타입) +- 서버 상담 세션: 1시간 TTL (자동 만료) --- diff --git a/README.md b/README.md index 79b7143..2923c36 100644 --- a/README.md +++ b/README.md @@ -21,8 +21,8 @@ * 🛠 **Function Calling**: 날씨, 검색, 계산, 시간 등 다양한 도구를 자연어로 호출 * 💰 **예치금 시스템**: 은행 SMS 자동 파싱(AI 폴백 지원) 및 양방향 매칭을 통한 자동 충전 * 🌐 **도메인 관리**: 도메인 검색, 추천(AI), 가격 조회, 등록, DNS 관리 통합 -* 🖥️ **서버 관리 (Queue 기반)**: Linode/Vultr 인스턴스 검색, 비교, 주문, 비동기 프로비저닝 -* ⚡ **서버리스**: Cloudflare Workers + Queues로 긴 작업도 안정적 처리 +* 🤖 **서버 추천 AI 상담**: 30년 경력 전문가 페르소나 기반 대화형 서버 추천, 최신 트렌드 검색 지원 (KV 세션 관리) +* ⚡ **서버리스**: Cloudflare Workers + KV로 긴 작업도 안정적 처리 * 🌐 **웹 채팅 UI**: 브라우저와 API로 봇 테스트 가능 ([telegram-cli](./telegram-cli/README.md)) ### 🚀 성능 최적화 @@ -57,6 +57,10 @@ npx wrangler d1 execute telegram-conversations --file=schema.sql ```bash # Rate Limiting용 KV Namespace 생성 (필수) npx wrangler kv:namespace create RATE_LIMIT_KV + +# 서버 상담 세션 저장용 KV Namespace 생성 (서버 추천 기능 사용 시 필수) +npx wrangler kv:namespace create SESSION_KV + # 출력된 id를 wrangler.toml의 [[kv_namespaces]] 섹션에 입력 ``` @@ -166,8 +170,8 @@ curl "https:///setup-webhook?token=${BOT_TOKEN}&secret=${WEBHOO #### ⚠️ 주의사항 - **WEBHOOK_SECRET 필수**: 미설정 시 모든 webhook 요청이 거부됩니다. -- **KV Namespace 필수**: 미생성 시 Rate Limiting이 비활성화되어 DoS 공격에 취약합니다. -- **Queue 필수 (서버 기능 사용 시)**: 미생성 시 서버 프로비저닝 기능이 동작하지 않습니다. +- **RATE_LIMIT_KV 필수**: 미생성 시 Rate Limiting이 비활성화되어 DoS 공격에 취약합니다. +- **SESSION_KV 필수 (서버 추천 기능 사용 시)**: 미생성 시 서버 상담 세션 관리가 동작하지 않습니다. - **환경변수 기본값**: 대부분의 외부 API URL은 기본값이 설정되어 있습니다. 프로덕션 환경에서는 기본값을 그대로 사용하거나, 필요시에만 override하세요. ---