socaichat/doc/enterprise-plan.md

# SOC 企业级 ChatGPT 系统 — 多 Agent 联合规划方案

> 2026-04-10 | 后端 Agent + 前端 Agent + LLM 工程师 + 部署 Agent 联合讨论产出

---

## 一、目标

基于 langgraphjs-gen-ui-examples 框架，打造无限接近 ChatGPT Enterprise 的企业对话系统，本地 Docker 部署。

## 二、系统架构（目标态）

```
用户浏览器 (localhost:3000)
    ↓ nginx 反代
[Vite SPA] React 19 + useStream + Gen-UI
    ↓ SSE
[LangGraph.js Server] (localhost:2024)
    ↓
[Supervisor] (gpt-5.4, temperature=0)
    ├── enterprise     → 知识库 + 工单（保留改造）
    ├── analyst        → 数据分析 + 图表生成（新增）
    ├── coder          → 代码解释器（新增）
    ├── writer         → Canvas 文档编辑（新增）
    ├── searcher       → 深度搜索（新增）
    ├── fileProcessor  → 文件解析 + 多模态（新增）
    ├── imageGen       → 图像生成（新增）
    ├── memory         → 用户记忆（后台服务，新增）
    └── generalInput   → 通用对话（保留）
    ↓
[基础设施 Docker]
    ├── Azure PostgreSQL  → checkpointer + 用户数据 + 记忆 (dataope.postgres.database.azure.com)
    ├── Azure Redis       → 缓存 + session + 限流 (oper.redis.cache.windows.net)
    ├── Azure Blob        → 文件存储 (authdatablol)
    └── Azure Service Bus → 异步任务 (databus.servicebus.windows.net)
    ↓
[外部 API]
    ├── Azure OpenAI (gpt-5.4)
    ├── Google Gemini Flash (router 备选)
    ├── KB Agent / Gongdan API
    ├── Jina Search + Reader / Serper
    ├── Daytona Sandbox
    ├── DALL-E 3 / Replicate FLUX
    └── Doc Creator Agent
```

---

## 三、后端架构（后端 Agent 方案）

### 3.1 新增 Sub-Agent 一览

| Agent | 对标 ChatGPT 功能 | 工具数 | Gen-UI 卡片 |
|-------|------------------|--------|------------|
| enterprise (改造) | 企业知识+工单 | 5 | knowledge-result, ticket-summary, ticket-detail |
| analyst (新增) | Advanced Data Analysis | 5 | data-preview, chart-result, stats-summary |
| coder (新增) | Code Interpreter | 5 | code-execution, code-approval |
| writer (新增) | Canvas | 7 | document-editor, document-export |
| searcher (新增) | Deep Research | 5 | search-progress, source-list, search-result |
| fileProcessor (新增) | File Upload | 6 | file-preview, image-analysis |
| imageGen (新增) | DALL-E | 3 | image-gallery, image-generation-progress |
| memory (新增) | Memory | 4 | (后台，无UI) |

### 3.2 目录结构

```
langgraph/src/agent/
├── supervisor/              ← 路由到 8 个 Agent
├── enterprise/              ← 知识库 + 工单 (改为 ReAct 循环)
├── analyst/                 ← 数据分析 (新增)
│   ├── nodes/call-model.ts, execute-tools.ts
│   └── tools/csv-parse.ts, data-query.ts, chart-generate.ts
├── coder/                   ← 代码解释器 (新增)
│   ├── nodes/call-model.ts, execute-code.ts
│   └── tools/sandbox-manager.ts (会话级 sandbox 复用)
├── writer/                  ← Canvas 文档 (新增)
│   └── nodes/call-model.ts, write-document.ts
├── searcher/                ← 深度搜索 (新增)
│   └── nodes/plan-search.ts, execute-searches.ts, synthesize.ts
├── file-processor/          ← 文件处理 (新增)
│   └── nodes/detect-type.ts, extract-text.ts, vision-analyze.ts
├── image-gen/               ← 图像生成 (新增)
│   └── nodes/generate.ts
├── memory/                  ← 用户记忆 (新增)
│   ├── recall.ts, extract.ts
└── utils/
    ├── tool-loop.ts         ← 通用 ReAct 循环抽象 (新增)
    ├── redis-client.ts      ← Redis 客户端 (新增)
    └── minio-client.ts      ← MinIO 客户端 (新增)
```

### 3.3 数据库 Schema

```sql
-- users, conversations, files, user_memories, artifacts, tool_invocations
-- 详见后端 Agent 完整方案
```

---

## 四、LLM 工程方案（LLM 工程师方案）

### 4.1 ReAct 循环（最关键改造）

当前 Enterprise Agent 是**单轮**：LLM 调一次 → 执行工具 → LLM 再调一次总结。

改造为**多轮 ReAct**：
```
START → agent (LLM 思考) → route?
                             ├── 有 tool_calls → tools (执行) → agent (继续思考)
                             └── 无 tool_calls → END
```

关键：MAX_ITERATIONS=6 防止无限循环。

### 4.2 Code Interpreter 自动修正循环

```
START → agent → generate_code → sandbox_execute → check_result
                                                    ├── 成功 → agent → END
                                                    └── 报错 → agent (看错误) → generate_code (修正)
```

- sandbox 会话级复用（30min TTL），不再每次创建/销毁
- matplotlib/plotly 图表输出为 base64 PNG → 嵌入 Gen-UI chart-result 卡片

### 4.3 记忆系统

```
对话开始 → memory_recall(user_id) → 注入 system prompt 尾部
对话结束 → memory_extract(conversation) → 持久化到 PostgreSQL
```

记忆分类：preference / fact / instruction / context

### 4.4 Supervisor 路由优化

路由 prompt 使用**结构化 tool descriptions**：
```
- enterprise: 企业内部助手：知识库查询、工单管理
- analyst: 数据分析：上传 CSV/Excel 后数据探索、统计、图表
- coder: 代码解释器：编写和执行代码、调试
- writer: 文档编辑器：创建和编辑文档（Canvas 模式）
- searcher: 深度搜索：多步互联网搜索、新闻查询
- fileProcessor: 文件处理：解析 PDF/Word/图片
- imageGen: 图像生成：根据描述生成/编辑图片
- generalInput: 通用对话
```

路由用 structured output (z.enum) 而非自由文本。

### 4.5 模型策略

| 模式 | 路由模型 | Agent 模型 | 工具过滤 |
|------|---------|-----------|---------|
| flash | gpt-5.4 (temp=0, maxTokens=50) | gpt-5.4 (temp=0.2, maxTokens=2048) | 排除 web_search |
| pro | 同上 | gpt-5.4 (temp=0.3, maxTokens=8192) | 排除 google_search |
| auto | 同上 | gpt-5.4 (temp=0.3, maxTokens=4096) | 全部 |

---

## 五、前端 UI 方案（前端 Agent 方案）

### 5.1 新增 Gen-UI 卡片

| 组件名 | Props | 场景 |
|--------|-------|------|
| `chart-result` | title, chart_type, data[], x_key, y_keys, colors, unit | 数据分析图表 |
| `canvas-doc` | doc_id, title, content, language, type | 触发 Canvas 侧面板 |
| `file-preview` | filename, file_type, size_kb, summary, row_count, preview_url | 文件解析结果 |

### 5.2 新增核心组件

| 组件 | 功能 |
|------|------|
| `MessageBubble.tsx` | AI 消息 Markdown 渲染 + 代码高亮 + LaTeX（**最高优先级**） |
| `CanvasPanel.tsx` | 右侧文档/代码编辑侧面板 (w-[480px]) |
| `FileUploadZone.tsx` | 拖拽上传 + 进度条 + 附件展示 |
| `ThemeToggle.tsx` | 暗色/亮色/系统主题切换 |
| `ToolStatusIndicator.tsx` | 工具执行动态指示器 |

### 5.3 侧边栏增强

- 搜索框（过滤对话）
- 日期分组（今天/昨天/本周/更早）
- 移动端折叠（汉堡菜单 + 滑入动画）

### 5.4 响应式布局

| 断点 | 布局 |
|------|------|
| < 768px | 侧边栏隐藏，Canvas 从底部弹出 |
| 768px | 侧边栏 w-56，折叠模式 |
| 1024px | 侧边栏 w-64，Canvas w-[480px] |
| 1280px+ | 消息区域 max-w-4xl |

---

## 六、Docker 部署方案（部署 Agent 方案）

### 6.1 设计原则

**基础设施用 Azure 云服务，本地 Docker 只运行应用**：
- PostgreSQL → Azure (dataope.postgres.database.azure.com)
- Redis → Azure (oper.redis.cache.windows.net:6380)
- Blob Storage → Azure (authdatablol)
- Service Bus → Azure (databus.servicebus.windows.net)
- LangGraph Server + Frontend → 本地 Docker

### 6.2 一键启动

```bash
cd /Users/gongzhiyong/go/SOC
make setup    # 创建 .env（已预填 Azure 服务凭据）
make dev      # 开发模式（热重载）
make prod     # 生产模式
```

### 6.3 服务矩阵

| 服务 | 位置 | 端口 | 用途 |
|------|------|------|------|
| langgraph | 本地 Docker | 2024 | LangGraph Server |
| frontend | 本地 Docker | 5173(dev)/3000(prod) | 前端 |
| PostgreSQL | Azure 云 | 5432 | checkpointer + 数据 |
| Redis | Azure 云 | 6380 (SSL) | 缓存 |
| Blob Storage | Azure 云 | — | 文件存储 |
| Service Bus | Azure 云 | — | 异步任务 |

### 6.4 开发模式特性

- 后端：src/ 目录挂载到容器，langgraphjs dev 自动监听变更
- 前端：src/ + index.html + vite.config.ts 挂载，Vite HMR 即时生效
- 无本地数据卷，所有持久化在 Azure 云端

### 6.5 已创建的文件

- `docker-compose.yml` — 轻量版，只有 langgraph + frontend
- `Dockerfile.dev` / `Dockerfile.prod` — 后端
- `Dockerfile.frontend.dev` / `Dockerfile.frontend.prod` — 前端
- `.env.docker.example` — 已预填 Azure 云服务凭据
- `Makefile` — 便捷命令

---

## 七、实施路线图

### Phase 0: 基础设施（1天）
- [x] Docker Compose（postgres + redis + minio + nginx）
- [ ] PostgreSQL schema 初始化
- [ ] MinIO buckets 初始化
- [ ] 验证 `make dev` 一键启动

### Phase 1: 核心升级（3天）
- [ ] **ReAct 循环改造** — Enterprise Agent 从单轮改为多轮 tool-calling loop
- [ ] **tool-loop 通用抽象** — 所有后续 Agent 复用
- [ ] **MessageBubble** — AI 消息 Markdown + 代码高亮渲染
- [ ] **ThemeProvider** — 暗色/亮色主题
- [ ] **chart-result 卡片** — recharts 图表渲染

### Phase 2: Agent 扩展（5天）
- [ ] **Deep Search Agent** — 从 Enterprise 剥离搜索，增加多步搜索
- [ ] **Code Interpreter Agent** — sandbox 复用 + 自动修正循环
- [ ] **Writer Agent (Canvas)** — 侧面板文档编辑 + 流式写入
- [ ] **CanvasPanel 前端组件** — 右侧抽屉 + Markdown/Code 渲染

### Phase 3: 高级功能（4天）
- [ ] **Data Analyst Agent** — CSV/Excel 分析 + pandas + 图表
- [ ] **File Processor Agent** — 文件上传 + PDF/图片解析
- [ ] **FileUploadZone 前端组件** — 拖拽上传 + 预览
- [ ] **Image Generator Agent** — DALL-E / Replicate
- [ ] **Memory Agent** — 跨会话记忆

### Phase 4: 体验打磨（2天）
- [ ] 侧边栏搜索 + 日期分组
- [ ] 移动端响应式布局
- [ ] ToolStatusIndicator 动态指示器
- [ ] 来源引用编号 [1][2]
- [ ] 自定义 GPTs UI（规划/占位）

**总计约 15 个工作日**

---

## 八、关键技术决策

| 决策 | 选择 | 原因 |
|------|------|------|
| 工具循环 | 自定义 tool-executor + ui.push | LangGraph ToolNode 不支持 typedUi.push() |
| 文件存储 | MinIO (S3 兼容) | 本地 Docker 部署，未来可无缝迁移 Azure Blob S3 兼容层 |
| 路由模型 | gpt-5.4 (temp=0, maxTokens=50) | 中文语义准确率高，成本极低 |
| Canvas 通信 | CustomEvent | Gen-UI 卡片无法接收父组件回调，CustomEvent 是唯一跨边界方案 |
| 记忆系统 | PostgreSQL + LLM extract | 透明记忆，用户无需主动说"记住"，系统自动提取 |
| sandbox 复用 | 会话级 Map + 30min TTL | 避免每次创建/销毁的 10s+ 开销 |