210 lines
8.4 KiB
Markdown
210 lines
8.4 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Overview
|
||
|
||
so-c-chat-clone — 企业级对话系统，基于 LangGraph.js Gen-UI 架构。Supervisor Agent 意图路由到 5 个专用 Sub-Agent，每个 Agent 调用外部 API 并通过 `ui.push()` 推送 Gen-UI 卡片，前端 useStream 实时渲染。
|
||
|
||
## Development Machine
|
||
|
||
- **开发机**: `sshpass -p xiaohei ssh xiaohei@192.168.30.30`（sudo 密码同）
|
||
- **项目路径**: `~/SOC/`
|
||
- **Docker 部署**: `cd ~/SOC && make dev`
|
||
- **代码同步**: 本地 `git push gitee main` → 开发机 `cd ~/SOC && git pull origin main`
|
||
- **Gitee 仓库**: `http://gitee.ath.cx:3000/xiaohei/socaichat.git`（用户: xiaohei, 密码: By@123456）
|
||
|
||
### 开发机端口
|
||
- 前端 (dev): `http://192.168.30.30:5173`
|
||
- LangGraph API: `http://192.168.30.30:2024`
|
||
|
||
## Commands
|
||
|
||
```bash
|
||
cd langgraph
|
||
pnpm install
|
||
pnpm run agent # 启动后端 langgraphjs dev (port 2024)
|
||
pnpm run build # tsc -b && vite build（前端）
|
||
```
|
||
|
||
开发机一键重启：
|
||
```bash
|
||
sshpass -p xiaohei ssh xiaohei@192.168.30.30 "cd ~/SOC && make dev"
|
||
```
|
||
|
||
## Architecture
|
||
|
||
### System Overview
|
||
```
|
||
用户浏览器
|
||
↓
|
||
[Azure Static Web App] soc-langgraph-ui (eastasia)
|
||
salmon-mushroom-0d8872e00.7.azurestaticapps.net
|
||
Vite SPA + @langchain/langgraph-sdk/react useStream
|
||
↓ SSE
|
||
[Azure Web App] soc-langgraph (southeastasia)
|
||
soc-langgraph.azurewebsites.net
|
||
Node.js 20 LTS + langgraphjs dev (port 2024)
|
||
↓ HTTP
|
||
[外部服务]
|
||
├── Azure OpenAI (gpt-5.4) ← 所有 Agent LLM（含 Supervisor 路由）
|
||
├── KB Agent (Azure AI Search)
|
||
├── Gongdan 工单 API
|
||
├── Jina Search/Reader/Rerank
|
||
├── Serper Google Search
|
||
└── Daytona Sandbox (process/execute endpoint)
|
||
```
|
||
|
||
### Agent Graph
|
||
```
|
||
Supervisor (Gemini 2.0 Flash) → intent router
|
||
├── enterprise → KB检索 + 工单查询（ReAct，MAX_ITERATIONS=6）
|
||
├── searcher → Google搜索 + Jina深度搜索
|
||
├── coder → 代码执行（Daytona sandbox）
|
||
├── writer → Canvas文档 + 报告生成 + 回复草稿
|
||
└── generalInput → 通用对话
|
||
```
|
||
|
||
路由基于**意图**而非关键词：writer=文档/报告/话术，coder=代码/计算，searcher=最新信息/新闻，enterprise=内部知识/工单，generalInput=其他。
|
||
|
||
### Agent 文件模式
|
||
|
||
每个 Sub-Agent 的目录结构一致：
|
||
```
|
||
src/agent/{name}/
|
||
index.ts ← StateGraph 定义（START → agent → route → tool-executor → agent）
|
||
types.ts ← State annotation
|
||
nodes/
|
||
agent.ts ← LLM bindTools + system prompt
|
||
tool-executor.ts ← 执行工具调用，ui.push() Gen-UI 卡片
|
||
tool-defs.ts ← Zod schema + ALL_TOOLS 定义（writer/enterprise）
|
||
```
|
||
|
||
### Tool → Gen-UI 卡片映射
|
||
|
||
| Agent | Tool | Gen-UI 卡片 | 说明 |
|
||
|-------|------|------------|------|
|
||
| enterprise | `kb_search` | `knowledge-result` | 含 citations，KB失败自动fallback到google_search |
|
||
| enterprise | `ticket_list` | `ticket-summary` + `chart-result` | 同时推状态/优先级分布图 |
|
||
| enterprise | `ticket_detail` | `ticket-detail` | TK-xxxx格式自动解析为UUID |
|
||
| searcher | `google_search` | `search-result` | 结果<3条自动补Jina搜索，含citations |
|
||
| searcher | `web_search_deep` | `search-result` | Jina Search+Reader+Rerank，含citations |
|
||
| coder | `code_execute` | `sandbox-result` | Daytona /sandbox + /toolbox/{id}/process/execute |
|
||
| writer | `doc_create/edit/translate` | `canvas-doc` | CanvasPanel右侧抽屉 |
|
||
| writer | `report_generate` | `canvas-doc` | 结构化报告模板 |
|
||
| writer | `reply_draft` | `reply-draft` | customer/internal双模式 |
|
||
| enterprise (自动) | — | `next-actions` | 工具成功后自动附带2-3条推荐动作 |
|
||
|
||
所有卡片 props 包含 `sourceType`（internal_kb/ticket_system/external_web/code_execution/generated_doc）和 `confidence`（high/medium/low）。
|
||
|
||
### 关键工具函数
|
||
|
||
- `src/agent/utils/retry.ts` — `executeWithRetry(fn, retries, {backoffMs, exponential})`，`formatToolError(name, e)`
|
||
- `src/agent/utils/truncate-messages.ts` — 上下文压缩
|
||
- `src/agent/utils/file-service.ts` — PDF/图片/Excel/文本解析 + Azure Blob
|
||
- `src/agent/utils/checkpointer.ts` — PostgresSaver，Gen-UI ui items 随 checkpoint 持久化恢复
|
||
|
||
### Frontend 关键文件
|
||
|
||
- `src/main.tsx` — Chat UI 主入口，useStream，`deduplicateUiItems()`（按card_id合并loading→complete）
|
||
- `src/components/ToolCallStatus.tsx` — 工具调用状态（loading旋转/green✓/red✗），支持展开查看Gen-UI结果+骨架屏
|
||
- `src/components/ActionBar.tsx` — 卡片底部追问/快捷动作，dispatch `soc:prefill-input` CustomEvent
|
||
- `src/components/SourceBadge.tsx` — 来源类型徽章（颜色+置信度图标）
|
||
- `src/components/MessageBubble.tsx` — ReactMarkdown + KaTeX + Prism，>800字自动显示摘要块
|
||
- `src/components/CanvasPanel.tsx` — 右侧文档编辑抽屉，监听 `open-canvas` CustomEvent
|
||
- `src/agent-uis/index.tsx` — Gen-UI 组件注册表（ComponentMap）
|
||
|
||
## Gen-UI 卡片开发规范
|
||
|
||
新增卡片需要：
|
||
1. 创建 `src/agent-uis/enterprise/{name}/index.tsx`（参考 knowledge-result 结构）
|
||
2. 在 `src/agent-uis/index.tsx` 的 ComponentMap 注册
|
||
3. 后端 `tool-executor.ts` 中 `ui.push({ name: "{name}", props: {...} }, { message: lastAiMessage })`
|
||
|
||
props 必须包含 `sourceType` 和 `confidence`（来自 retry.ts 的工具执行结果），可选 `errorMessage`（触发红色 error 态）。
|
||
|
||
## Daytona Sandbox 注意事项
|
||
|
||
Daytona API 正确端点：
|
||
- 创建: `POST {DAYTONA_API_URL}/sandbox`，body: `{ autoStopInterval: 5, autoDeleteInterval: 0 }`
|
||
- 执行: `POST https://proxy.app.daytona.io/toolbox/{sandboxId}/process/execute`，body: `{ command: "python3 -c '...'" }`
|
||
- 删除: `DELETE {DAYTONA_API_URL}/sandbox/{sandboxId}`
|
||
|
||
## Repository Structure
|
||
|
||
```
|
||
so-c-chat-clone/
|
||
├── langgraph/ ← 唯一代码目录
|
||
│ ├── src/agent/
|
||
│ │ ├── supervisor/ ← 路由 + generalInput
|
||
│ │ ├── enterprise/ ← KB + 工单（ReAct）
|
||
│ │ ├── searcher/ ← Google + Jina
|
||
│ │ ├── coder/ ← Daytona 沙盒
|
||
│ │ ├── writer/ ← Canvas + 报告 + 草稿
|
||
│ │ └── utils/ ← retry, checkpointer, file-service, truncate
|
||
│ ├── src/agent-uis/enterprise/ ← 9 个 Gen-UI 卡片组件
|
||
│ ├── src/components/ ← 通用 UI 组件
|
||
│ ├── src/main.tsx ← Chat UI 入口
|
||
│ ├── langgraph.json ← LangGraph 配置
|
||
│ ├── Dockerfile ← 后端容器
|
||
│ └── startup.sh ← Azure Web App 启动脚本
|
||
├── .github/workflows/
|
||
│ ├── deploy-langgraph.yml ← ACR build → Web App
|
||
│ └── deploy-langgraph-ui.yml ← Vite build → Static Web App
|
||
└── CLAUDE.md
|
||
```
|
||
|
||
## Configuration
|
||
|
||
环境变量通过 Azure Web App 应用设置配置，本地通过 `langgraph/.env`：
|
||
|
||
```
|
||
# Azure OpenAI (Sub-Agent LLM)
|
||
AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_VERSION, AZURE_OPENAI_DEPLOYMENT
|
||
|
||
# Google Gemini (Supervisor router)
|
||
GOOGLE_API_KEY
|
||
|
||
# KB Agent
|
||
KB_AGENT_URL, KB_AGENT_API_KEY, KB_AGENT_SEARCH_PATH
|
||
|
||
# Gongdan 工单
|
||
GONGDAN_API_BASE, GONGDAN_API_KEY
|
||
|
||
# Jina
|
||
JINA_API_KEY
|
||
|
||
# Serper
|
||
SERPER_API_KEY
|
||
|
||
# Daytona
|
||
DAYTONA_API_KEY, DAYTONA_API_URL
|
||
|
||
# Frontend (Vite build-time)
|
||
VITE_LANGGRAPH_URL=https://soc-langgraph.azurewebsites.net
|
||
```
|
||
|
||
## Deployment
|
||
|
||
### 后端 (soc-langgraph)
|
||
- **Azure Web App**: Node.js 20, B1 Linux, Southeast Asia, Operation 资源组
|
||
- **启动命令**: `bash startup.sh`（pnpm install + langgraphjs dev --port $PORT）
|
||
- **WEBSITES_PORT**: 2024
|
||
- **CI/CD**: ACR cloud build → Web App container update
|
||
|
||
### 前端 (soc-langgraph-ui)
|
||
- **Azure Static Web App**: East Asia
|
||
- **URL**: salmon-mushroom-0d8872e00.7.azurestaticapps.net
|
||
- **CI/CD**: pnpm vite build → SWA upload
|
||
|
||
### CI/CD 认证
|
||
- OIDC: azure/login@v2 + Federated Identity (oidc-msi-8ac6)
|
||
- SWA Token: secrets.SWA_LANGGRAPH_TOKEN
|
||
|
||
## Constraints
|
||
|
||
- **Azure 资源组**: 仅允许操作 `Operation` 和 `AuthData`，所有 `az` 命令必须带 `--resource-group`
|
||
- **禁止删除已存在的 Azure 资源**
|
||
- **GitHub**: Fasthei/so-c-chat-clone，main 分支
|
||
- **已废弃**: backend/ (Python), frontend/ (Next.js), soc-backend/soc-frontend Web Apps, Container App
|