socaichat/CLAUDE.md

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

cd langgraph
pnpm install
pnpm run agent          # 启动后端 langgraphjs dev (port 2024)
pnpm run build          # tsc -b && vite build（前端）

开发机一键重启：

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 Container App] soc-langgraph (southeastasia)
  soc-langgraph.victorioussand-69befc84.southeastasia.azurecontainerapps.io
  Node.js 20 LTS + langgraphjs dev (port 8080), min 1 replica
    ↓ 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.victorioussand-69befc84.southeastasia.azurecontainerapps.io

Deployment

后端 (soc-langgraph)

• Azure Container App: Southeast Asia, Operation 资源组
• Environment: soc-cae (victorioussand-69befc84.southeastasia.azurecontainerapps.io)
• URL: https://soc-langgraph.victorioussand-69befc84.southeastasia.azurecontainerapps.io
• 容器: socsocacr.azurecr.io/soc-langgraph:latest, port 8080
• Scale: min 1 replica, max 3 replicas, CPU 1.0, Memory 2Gi
• CI/CD: ACR cloud build → Container App update (az containerapp update --image)

前端 (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