# 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 + tsx src/agent/server.ts (production mode, 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`（tsx src/agent/server.ts，production 模式）
- **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