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 路由 + Enterprise Agent 工具调用，支持知识库检索、工单查询、网络搜索、代码沙盒执行，前端通过 useStream 实时渲染 Gen-UI 卡片。

## Development Machine

- **开发机**: `ssh xiaohei@192.168.30.30` (密码: xiaohei, sudo 同密码)
- **项目路径**: `~/SOC/`
- **Docker 部署**: `cd ~/SOC && make dev`
- **代码同步**: 本地 `git push gitee main` → 开发机 `cd ~/SOC && git pull`
- **Gitee 仓库**: `http://gitee.ath.cx:3000/xiaohei/socaichat.git` (用户: xiaohei, 密码: By@123456)
- **SSH 工具**: `sshpass -p xiaohei ssh xiaohei@192.168.30.30`

### 开发机端口
- 前端 (dev): `http://192.168.30.30:5173`
- LangGraph API: `http://192.168.30.30:2024`

## Commands

### 后端（LangGraph Server）
```bash
cd langgraph
pnpm install
pnpm run agent          # langgraphjs dev --no-browser (port 2024)
```

### 前端（Vite SPA）
```bash
cd langgraph
pnpm install
pnpm run build          # tsc -b && vite build
```

### Deployment
```bash
# Push to main branch — GitHub Actions auto-deploys:
# - deploy-langgraph.yml: ACR build → Web App container update
# - deploy-langgraph-ui.yml: pnpm vite build → Azure Static Web Apps
git push origin main
```

## 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)
  ├── KB Agent (Azure AI Search)
  ├── Gongdan 工单 API
  ├── Jina Search/Reader
  ├── Serper Google Search
  └── Daytona Sandbox
```

### Agent Graph
```
Supervisor (Gemini 2.0 Flash) → router
  ├── enterprise → Enterprise Agent (Azure OpenAI gpt-5.4, 6 tools, Gen-UI cards)
  └── generalInput → 通用对话
```

### Enterprise Agent Tools (src/agent/enterprise/nodes/tools.ts)
| Tool Name | External Service | UI Component |
|-----------|-----------------|--------------|
| `kb_search` | KB Agent (Azure AI Search) | `knowledge-result` |
| `ticket_list` | Gongdan API | `ticket-summary` |
| `ticket_detail` | Gongdan API | `ticket-detail` |
| `web_search` | Jina Search + Reader | `search-result` |
| `google_search` | Serper API | `search-result` |
| `sandbox_run` | Daytona REST API | `sandbox-result` |

### Model Mode Filtering
- `flash`: 排除 `web_search`（太慢），保留 `google_search`
- `pro`: 排除 `google_search`，使用深度 `web_search`
- `auto`: 保留全部工具

### Request Flow
```
Frontend useStream → LangGraph SSE
  → Supervisor router (Gemini Flash) → route to enterprise or generalInput
  → Enterprise tools node: LLM bindTools → call external APIs → ui.push() Gen-UI cards → LLM final answer
  → SSE stream with messages + UI components
```

## Repository Structure
```
so-c-chat-clone/
├── langgraph/                              ← 唯一代码目录
│   ├── src/agent/supervisor/               ← Supervisor Agent（路由）
│   │   ├── index.ts                        ← StateGraph + checkpointer
│   │   ├── nodes/router.ts                 ← Gemini Flash 意图路由
│   │   └── nodes/general-input.ts          ← 通用对话节点
│   ├── src/agent/enterprise/               ← Enterprise Agent
│   │   ├── index.ts                        ← StateGraph (START → tools)
│   │   ├── nodes/tools.ts                  ← 6 tools + LLM + ui.push()
│   │   ├── tools/soc-client.ts             ← 外部 API 客户端
│   │   └── types.ts                        ← EnterpriseAnnotation
│   ├── src/agent/chat-agent/index.ts       ← 简单聊天 Agent
│   ├── src/agent/utils/                    ← checkpointer, format-messages
│   ├── src/agent-uis/enterprise/           ← 5 个 Gen-UI 卡片组件
│   │   ├── knowledge-result/
│   │   ├── ticket-summary/
│   │   ├── ticket-detail/
│   │   ├── search-result/
│   │   └── sandbox-result/
│   ├── src/main.tsx                        ← Chat UI 入口（useStream）
│   ├── langgraph.json                      ← LangGraph 配置
│   ├── startup.sh                          ← Azure Web App 启动脚本
│   ├── Dockerfile                          ← 后端容器
│   ├── Dockerfile.frontend                 ← 前端容器（未使用）
│   └── package.json                        ← pnpm, Node.js 20
├── .github/workflows/
│   ├── deploy-langgraph.yml                ← ACR build → Web App
│   └── deploy-langgraph-ui.yml             ← Vite build → Static Web App
├── doc/                                    ← 文档
└── CLAUDE.md
```

## Configuration

环境变量通过 Azure Web App 应用设置配置，本地通过 `langgraph/.env`：

```
# Azure OpenAI
AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_VERSION, AZURE_OPENAI_DEPLOYMENT

# Google (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 资源组
- **App Service Plan**: soc-langgraph-plan
- **启动命令**: `bash startup.sh`（pnpm install + langgraphjs dev --port $PORT）
- **WEBSITES_PORT**: 2024
- **CI/CD**: ACR cloud build → container update → restart

### 前端 (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 Web App, soc-frontend Static Web App, Container App