# Angular 对接 DeerFlow 智能体对话页

本文说明如何在 **其它 Angular 项目** 中对接 DeerFlow 智能体对话能力，对标页面：

```
http://localhost:5173/#/page/workspace/agents/roundtable-structure/chats/new
```

对应前端路由：`#/page/workspace/agents/{agent_id}/chats/{thread_id}`  
其中 `agent_id = roundtable-structure`（展示名「结构化抽取」），`thread_id = new` 表示新建会话。

本文覆盖：**登录拿 Token → 列模型/切模型 → 建会话/存聊天记录 → 流式对话 → 思考内容 → 步骤条（含创建脚本/执行脚本/写入文件及全部工具）→ 用户协助卡片 → 消息列表渲染 → 停止/重连/上传/产物**。  
**不包含**智能体配置（创建/编辑智能体、技能绑定等）。

路径约定（均相对本仓库根目录 `deerflow-server/`）：

- 前端：`frontend-web/src/…`
- 后端：`offline-backend-20260512/backend/…`（下文若写 `app/`、`deerflow/`，都在这个 backend 目录下）
- 每节末尾有 **参考代码**；文末第 20 节是总索引。

---

## 0. 先看这一页

对接本质不是「调一个聊天 HTTP」，而是复用本系统的 **LangGraph 兼容协议**：

| 能力 | 走哪条线 | Base URL |
|------|----------|----------|
| 登录、模型列表、上传、产物、追问建议 | Gateway REST | `{GATEWAY}`，例如 `http://host:8001` |
| 会话 / 流式对话 / 取消 | LangGraph Platform 兼容 API | `{GATEWAY}/api` |

本仓库前端环境变量：

- `VITE_BACKEND_BASE_URL` → `{GATEWAY}`
- `VITE_LANGGRAPH_BASE_URL` → `{GATEWAY}/api`

开发机前端常见端口是 **5173 或 5174**（Vite 被占用会换端口），Gateway 默认 **8001**。  
下文用：

```text
GATEWAY = http://localhost:8001
LG      = http://localhost:8001/api
```

所有对话接口都要带：

```http
Authorization: Bearer <access_token>
Content-Type: application/json
```

用 Bearer **不必**再带 CSRF。不要用 cookie 登录（`/login/local` 只把 JWT 写进 HttpOnly cookie，不适合 Angular 跨域 API 客户端）。

**参考代码**

| 说明 | 路径 |
|------|------|
| 前端两个 Base URL | `frontend-web/src/core/config/index.ts`（`getBackendBaseURL` / `getLangGraphBaseURL`） |
| 环境变量注入 | `frontend-web/src/env.ts` |
| LangGraph SDK 客户端（自动带 Bearer） | `frontend-web/src/core/api/api-client.ts` |
| Gateway fetch 自动带 Authorization | `frontend-web/src/core/api/fetch-client.ts` |
| CSRF：有 Bearer 则跳过 | `offline-backend-20260512/backend/app/gateway/csrf_middleware.py` |
| 登录接口白名单 | `offline-backend-20260512/backend/app/gateway/auth_middleware.py` |

---

## 1. 架构与端到端流程

```mermaid
sequenceDiagram
  participant A as Angular
  participant G as Gateway :8001
  participant R as RunManager / Lead Agent

  A->>G: POST /api/v1/auth/login/username
  G-->>A: access_token (JWT, ~7 天)
  A->>G: GET /api/models
  G-->>A: models[]
  A->>G: POST /api/threads  metadata.agent_id=roundtable-structure
  G-->>A: thread_id
  A->>G: POST /api/threads/{id}/runs/stream (SSE)
  G->>R: start_run(assistant_id, context.model_name, ...)
  loop 流式
    R-->>A: event: metadata / messages / values / custom / end
  end
  Note over A: 按消息分组渲染气泡 + 步骤条 + 协助卡片
  A->>G: GET /api/threads/{id}/state  （刷新后还原聊天记录）
```

`roundtable-structure` 与其它自定义智能体共用 **同一套 Lead Agent 图**。  
真正选中哪个智能体靠三层同时带上（缺一不可，建议都传）：

1. 请求体 `assistant_id = "roundtable-structure"`（文件系统/库表里的 **id**，不是中文名）
2. `context.agent_id = "roundtable-structure"`
3. 会话 `metadata.agent_id = "roundtable-structure"`（历史列表按此过滤）

**参考代码**

| 说明 | 路径 |
|------|------|
| 路由挂载 AgentChatPage | `frontend-web/src/pages/WorkspaceRoutes.tsx`（`agents/:agent_id/chats/:thread_id`） |
| 对话页：`assistantId` + `context.agent_id` | `frontend-web/src/pages/AgentChatPage.tsx` |
| 聊天气泡壳 | `frontend-web/src/components/workspace/chats/chat-box.tsx` |
| 发消息时写入 metadata.agent_id | `frontend-web/src/core/threads/hooks.ts`（`onCreated` / `thread.submit`） |
| 非内置 assistant_id → agent_id | `offline-backend-20260512/backend/app/gateway/services.py`（`build_run_config`） |
| Lead Agent 工厂 | `offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/agent.py` |
| 智能体种子（id / 中文名 / 技能） | `offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed_assets/roundtable-structure/config.yaml` |
| 智能体 SOUL | `offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed_assets/roundtable-structure/SOUL.md` |

---

## 2. CORS / 跨域（Angular 必读）

Gateway 默认放行的浏览器 Origin 只有：

- `http://localhost:5173` / `5174` / `3000` / `8080`（及对应 `127.0.0.1`）

**Angular CLI 默认是 `http://localhost:4200`，不在白名单里。**  
部署或本地对接时必须把 Angular 源加进环境变量，例如：

```bash
GATEWAY_CORS_ORIGINS=http://localhost:4200,http://127.0.0.1:4200,https://your-angular-host
```

或开发期临时 `GATEWAY_CORS_ALLOW_ALL=1`（勿用于生产）。

**参考代码**：`offline-backend-20260512/backend/app/gateway/app.py`（搜 `GATEWAY_CORS_ORIGINS` / `local_vite_origins` / `cors_expose_headers`）。回归：`offline-backend-20260512/backend/tests/test_taskcop_cors.py`。

浏览器跨域读 SSE 还需要暴露这些响应头（Gateway 已配）：

- `Content-Location`（从中解析 `run_id`，取消/重连要用）
- `Location`、`Content-Disposition`

请求请带 `credentials: include` 也可以，但 **Bearer 才是主认证**。

---

## 3. 登录：如何拿到 Token

登录接口 **不需要** JWT。前缀：`/api/v1/auth`。

推荐 Angular 用 **用户名登录** 或 **上游 Token 换票**。不要用 `/login/local`。

### 3.1 用户名登录（推荐）

```http
POST {GATEWAY}/api/v1/auth/login/username?password=OPTIONAL
Content-Type: application/json

{ "username": "alice" }
```

- 若该账号在后台配了「登录口令」，**必须**带匹配的 `?password=`
- 若开了全局共享口令门（`config.yaml → auth_login.username_login.require_password`），未配个人口令的账号也要带共享口令
- 未开密码门且无个人口令时，可省略 `password`

成功响应：

```json
{
  "access_token": "<jwt>",
  "token_type": "bearer",
  "expires_in": 604800,
  "user_id": "<uuid>",
  "email": "alice@deerflow.local",
  "system_role": "user",
  "needs_setup": false,
  "created": false,
  "username": "alice"
}
```

`expires_in` 默认 **7 天（604800 秒）**。系统 **没有 refresh 接口**，过期后重新登录。  
JWT payload：`{ sub: user_id, exp, iat, ver }`，HS256。改密码会 bump `token_version`，旧票立刻失效。

后续所有请求：

```http
Authorization: Bearer <access_token>
```

即 ``${token_type} ${access_token}``。

校验当前用户：

```http
GET {GATEWAY}/api/v1/auth/me
Authorization: Bearer <jwt>
```

```json
{ "id": "...", "email": "...", "system_role": "user", "needs_setup": false }
```

401 → 清本地 token，回到登录。

### 3.2 上游 Token 换票

适用于已有统一认证、URL 里带 `authToken` 的场景：

```http
POST {GATEWAY}/api/v1/auth/login/token?token=<upstreamToken>
Content-Type: application/json
```

响应形状与用户名登录相同。上游时钟偏差可能导致短暂 401，本系统前端会重试最多 3 次、间隔 3 秒；Angular 建议同样处理。

开关：`config.yaml → auth_login.token_login.enabled`。

### 3.3 登录失败

`detail` 可能是字符串、`{ code, message }`、或校验数组。请按字符串抽取，不要直接 `String(object)`。

常见：

| HTTP | 含义 |
|------|------|
| 401 | 口令错误 / 上游 token 无效 |
| 403 `{ code: "PENDING_APPROVAL" }` | 管理员取消了该账号放行 |
| 429 | 限流 |

### 3.4 Angular 存储建议

```ts
const AUTH_KEY = 'deerflow.auth';

interface LoginResponse {
  access_token: string;
  token_type: string;
  expires_in: number;
  user_id: string;
  email: string;
  system_role: string;
  username?: string;
}

function authHeader(): HttpHeaders {
  const auth = JSON.parse(localStorage.getItem(AUTH_KEY) || 'null') as LoginResponse | null;
  return new HttpHeaders({
    Authorization: `${auth?.token_type || 'Bearer'} ${auth?.access_token || ''}`,
  });
}
```

**参考代码**

| 说明 | 路径 |
|------|------|
| 前端登录 API | `frontend-web/src/core/auth/api.ts`（`loginByUsername` / `loginByToken`） |
| Token 存取、拼 Bearer | `frontend-web/src/core/auth/index.ts`（`getAuthorizationHeaderValue` / `setStoredAuth`） |
| 类型 `LoginByUsernameResponse` | `frontend-web/src/core/auth/index.ts` |
| 登录页（含 token 换票） | `frontend-web/src/pages/LoginPage.tsx` |
| 后端登录路由 | `offline-backend-20260512/backend/app/gateway/routers/auth.py`（`/login/username`、`/login/token`、`/me`） |
| JWT 签发 | `offline-backend-20260512/backend/app/gateway/auth/jwt.py` |
| 请求里解析 cookie / Bearer | `offline-backend-20260512/backend/app/gateway/deps.py`（`get_current_user`） |
| 登录配置（口令门 / token_login） | `offline-backend-20260512/backend/config.yaml` → `auth_login`；schema：`deerflow/config/login_config.py` |
| 登录契约说明 | `offline-backend-20260512/backend/docs/AUTH_LOGIN.md` |

---

## 4. 模型列表与切换

智能体配置不用做；**对话时选哪个大模型**要做。

### 4.1 拉模型

```http
GET {GATEWAY}/api/models
Authorization: Bearer <jwt>
```

```json
{
  "models": [
    {
      "name": "deepseek-chat",
      "model": "deepseek-chat",
      "display_name": "DeepSeek Chat",
      "supports_thinking": true,
      "supports_reasoning_effort": false,
      "supports_vision": false,
      "supports_tool_calling": true,
      "is_local": false,
      "provider": "openai"
    }
  ],
  "token_usage": { "enabled": false }
}
```

下拉框展示 `display_name`，提交时传 **`name`（不是 `model`）** 到 `context.model_name`。

### 4.2 思考档位（本系统输入框的 flash / thinking / pro / ultra）

每轮 `runs/stream` 的 `context` 里带这些开关（后端白名单字段，未列入的会被丢掉）：

| 档位 | `thinking_enabled` | `is_plan_mode` | `subagent_enabled` | `reasoning_effort` | 效果 |
|------|--------------------|----------------|--------------------|--------------------|------|
| flash | false | false | false | — | 快答，尽量不思考 |
| thinking | true | false | false | `low` | 出思考块 |
| pro | true | true | false | `medium` | 思考 + 计划 Todo |
| ultra | true | true | true | `high` | 再加子任务委派 |

若所选模型 `supports_thinking === false`，请强制 flash。  
内网部分 vLLM/Qwen 只声明了 `supports_thinking`，关思考时建议额外传 `thinking_force_disabled: true`，否则可能关不干净。

模型解析顺序（后端）：

1. 本轮 `context.model_name`
2. 智能体自己的 `config.yaml → model`
3. 系统配置的第一个模型

每轮都可以换模型；换了只影响 **下一轮**，不会改写历史。

**参考代码**

| 说明 | 路径 |
|------|------|
| 前端拉模型 | `frontend-web/src/core/models/api.ts`、`frontend-web/src/core/models/types.ts` |
| 输入框模型下拉 + 档位 | `frontend-web/src/components/workspace/input-box.tsx`（`InputMode`、`ModelSelector`） |
| 档位写入 context | `frontend-web/src/core/threads/hooks.ts`（`thread.submit` 的 `context`：`thinking_enabled` / `is_plan_mode` / `subagent_enabled`） |
| 本地记住所选模型 | `frontend-web/src/core/settings/local.ts`（`deerflow.thread-model.{threadId}`） |
| 后端模型列表 | `offline-backend-20260512/backend/app/gateway/routers/models.py` |
| context 白名单 | `offline-backend-20260512/backend/app/gateway/services.py`（`_CONTEXT_CONFIGURABLE_KEYS`） |
| 本轮实际用哪个模型 | `offline-backend-20260512/backend/app/gateway/services.py`（`_resolve_effective_run_model_name`） |
| 创建 ChatModel、关思考 | `offline-backend-20260512/backend/packages/harness/deerflow/models/factory.py` |
| 模型配置源 | `offline-backend-20260512/backend/config.yaml` → `models[]` |

---

## 5. 会话（Thread）= 聊天记录的存储单位

聊天记录 **不用 Angular 自己建库**。Gateway 用 LangGraph checkpointer 存消息，用 `threads_meta` 存索引（标题、owner、metadata）。

物理目录（了解即可）：`.deer-flow/users/{user_id}/threads/{thread_id}/user-data/{workspace,uploads,outputs}`。

### 5.1 新建会话

```http
POST {LG}/threads
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "assistant_id": "roundtable-structure",
  "metadata": { "agent_id": "roundtable-structure" }
}
```

```json
{
  "thread_id": "3f2a…",
  "status": "idle",
  "created_at": "2026-08-18T09:00:00+08:00",
  "updated_at": "…",
  "metadata": { "agent_id": "roundtable-structure" },
  "values": {},
  "interrupts": {}
}
```

也可以不先 create：`runs/stream` 带 `if_not_exists: "create"` 时会自动建。本系统前端就是 **第一次发消息时** 由 SDK 建 thread，再 `PATCH` 写入 `metadata.agent_id`。建议 Angular **显式 create**，方便先上传文件、再发问。

### 5.2 补 metadata（必须，否则历史列表滤不出来）

```http
PATCH {LG}/threads/{thread_id}
{ "metadata": { "agent_id": "roundtable-structure" } }
```

为 merge，不会整表覆盖。

### 5.3 历史列表（按智能体过滤）

```http
POST {LG}/threads/search
{
  "metadata": { "agent_id": "roundtable-structure" },
  "limit": 50,
  "offset": 0,
  "query": null,
  "status": null
}
```

返回 `ThreadResponse[]`。标题在 `values.title`（来自库里的 `display_name`）。  
`query` 按标题模糊搜。系统会话（调度、会商工人线程）默认排除。

条数：

```http
POST {LG}/threads/count
（body 同上，limit/offset 忽略）
→ { "total": 12 }
```

列表项建议展示：

1. `values.title`；没有则用该会话第一条用户消息截断 50 字
2. `updated_at`

打开某条：跳到自己的路由并 `GET …/state` 拉消息。

### 5.4 打开已有会话（还原聊天记录）

优先：

```http
GET {LG}/threads/{thread_id}/state
```

`values` 里至少有：

```json
{
  "title": "抽取方案结构",
  "title_provisional": false,
  "messages": [ /* 见第 8 节 */ ],
  "artifacts": ["/mnt/user-data/outputs/flow.json"],
  "todos": [{ "content": "…", "status": "in_progress" }]
}
```

也可：

```http
GET {LG}/threads/{thread_id}
```

带 metadata + 当前 `values`（含 messages）。

checkpoint 历史（一般不需要）：

```http
POST {LG}/threads/{thread_id}/history
{ "limit": 10, "before": null }
```

只在最新一条 history 上带 `messages`，避免重复。

### 5.5 删除会话

两步都做才干净：

```http
DELETE {LG}/threads/{thread_id}
```

这会删 checkpoint / meta / 磁盘目录。本系统前端 SDK 删除后再打一次 Gateway 同路径，确保本地文件清掉。

### 5.6 会话状态

`status`：`idle` | `busy` | `interrupted` | `error`  
正在跑时为 `busy`。同一会话再发会被 `multitask_strategy: "reject"` 打回 **HTTP 409**。

**参考代码**

| 说明 | 路径 |
|------|------|
| 线程类型 / context 类型 | `frontend-web/src/core/threads/types.ts` |
| 列表、标题、路由 | `frontend-web/src/core/threads/utils.ts`（`titleOfThread` / `pathOfThread`） |
| 分页搜索 | `frontend-web/src/core/threads/hooks.ts`（`useThreadsPage`） |
| 智能体最近对话 | `frontend-web/src/components/workspace/agents/agent-recent-chats.tsx` |
| 工作区会话列表 UI | `frontend-web/src/components/workspace/workspace-nav-chat-list.tsx` |
| 建/搜/改/删/state/history | `offline-backend-20260512/backend/app/gateway/routers/threads.py` |
| ThreadResponse / Search 模型 | 同上文件内 `ThreadResponse`、`ThreadCreateRequest`、`ThreadSearchRequest` |
| 删除时清本地目录 | `frontend-web/src/core/threads/hooks.ts`（delete 后再调 Gateway DELETE） |
| 409 中文文案 | `offline-backend-20260512/backend/app/gateway/services.py`（`create_or_reject` / RunManager） |

---

## 6. 发起智能体对话（核心）

```http
POST {LG}/threads/{thread_id}/runs/stream
Authorization: Bearer <jwt>
Content-Type: application/json
Accept: text/event-stream
```

### 6.1 请求体（与本系统 AgentChatPage 对齐）

```json
{
  "assistant_id": "roundtable-structure",
  "input": {
    "messages": [
      {
        "type": "human",
        "content": [{ "type": "text", "text": "请根据这份方案抽取流程图" }],
        "additional_kwargs": {
          "client_ts": "2026-08-18T09:00:00.000Z"
        }
      }
    ]
  },
  "context": {
    "agent_id": "roundtable-structure",
    "model_name": "deepseek-chat",
    "thinking_enabled": true,
    "thinking_force_disabled": false,
    "is_plan_mode": false,
    "subagent_enabled": false,
    "reasoning_effort": "low",
    "memory_injection_enabled": true,
    "rag_mode_enabled": false,
    "summarization_enabled": false,
    "thread_id": "<thread_id>"
  },
  "config": { "recursion_limit": 1000 },
  "stream_mode": ["values", "messages-tuple", "updates", "custom"],
  "stream_subgraphs": true,
  "stream_resumable": true,
  "on_disconnect": "cancel",
  "multitask_strategy": "reject",
  "if_not_exists": "create"
}
```

要点：

- `input.messages` **只传本轮新的 human**，不要把历史整包再塞一遍（服务端 checkpointer 会拼）
- `content` 可以是纯字符串 `"你好"`，也可以是上面的 text block 数组
- `client_ts` 可选，前端用来显示提问时间
- `stream_mode` 里写 `messages-tuple`（LangGraph Platform 名）；服务端会转成内部 `messages` 再以 SSE `event: messages` 吐出
- `on_disconnect: "cancel"`：浏览器关 SSE 就停服务端；若希望关页后台继续跑，改 `"continue"`
- `multitask_strategy: "reject"`：会话已有进行中的 run → **409**，文案类似「当前对话还在生成回答…」

响应头：

```http
Content-Type: text/event-stream
Content-Location: /api/threads/{thread_id}/runs/{run_id}
```

**立刻把 `run_id` 存下来**（停止、重连都靠它）。SSE 第一帧 `event: metadata` 里也会再给一次。

### 6.2 纯文本以外的用户消息

图片（模型 `supports_vision` 时）：

```json
{
  "type": "human",
  "content": [
    { "type": "text", "text": "看看这张图" },
    { "type": "image_url", "image_url": { "url": "https://…/a.png" } }
  ]
}
```

附件：先上传（第 15 节），再在 `additional_kwargs.files` 里带虚拟路径。

协助卡片的回复：**不要**调 LangGraph `Command(resume)`，当成 **普通新一轮 human 消息** 再 `runs/stream`（见第 12 节）。

### 6.3 停止生成

只关 EventSource **不够**，服务端可能还在跑。

```http
POST {LG}/threads/{thread_id}/runs/{run_id}/cancel?action=interrupt&wait=false
```

- 202：已受理；`wait=true` 等到停完返回 204
- `action=interrupt`：停下，保留当前 checkpoint（可继续聊）
- `action=rollback`：回滚到本轮开始前

列出该会话的 run：

```http
GET {LG}/threads/{thread_id}/runs
GET {LG}/threads/{thread_id}/runs/{run_id}
```

### 6.4 断线重连

SSE 帧带 `id:`。重连时：

```http
GET {LG}/threads/{thread_id}/runs/{run_id}/join
Last-Event-ID: <上一帧 id>
```

或 POST stream 时带 `stream_resumable: true` 后由 SDK 自动 join。Gateway 重启后 join 会立刻 `event: end`，此时改拉 `/state` 渲染历史即可。

心跳是注释行：`: heartbeat`，忽略即可。

**参考代码**

| 说明 | 路径 |
|------|------|
| 前端 `useStream` + `thread.submit` | `frontend-web/src/core/threads/hooks.ts`（`useThreadStream`、构造 `messages` / `context`） |
| SDK 包装 | `frontend-web/src/core/api/api-client.ts` |
| stream_mode 规范化 | `frontend-web/src/core/api/stream-mode.ts` |
| 停止：`thread.stop` / `runs.cancel` | `frontend-web/src/core/threads/hooks.ts`（`stopThreadRun`） |
| 输入框停止按钮 | `frontend-web/src/components/workspace/input-box.tsx` |
| 后端 stream / cancel / join | `offline-backend-20260512/backend/app/gateway/routers/thread_runs.py`（`RunCreateRequest`、`stream_run`、`cancel_run`、`join_run`） |
| 真正起跑 | `offline-backend-20260512/backend/app/gateway/services.py`（`start_run`） |
| 后台跑图 + 发 SSE | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/runs/worker.py`（`run_agent`） |
| Run 生命周期 | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/runs/manager.py` |
| 流式设计说明 | `offline-backend-20260512/backend/docs/STREAMING.md` |

---

## 7. SSE 事件协议（Angular 必须自己解析 POST 流）

**`EventSource` 只支持 GET，不能用来 POST `/runs/stream`。**  
Angular 请用 `fetch` + `ReadableStream`（或封装好的 SSE parser）。不要用 `HttpClient` 的默认 JSON 解析。

### 7.1 线格式

```
event: metadata
data: {"run_id":"…","thread_id":"…"}
id: 1

event: messages
data: [{...chunk...}, {...meta...}]
id: 2

event: values
data: {"title":"…","messages":[...],"artifacts":[],"todos":[]}
id: 3

event: custom
data: {"type":"task_running","task_id":"…","message":"…"}
id: 4

event: end
data: null
id: 5
```

字段顺序：`event:` → `data:` → `id:` → 空行。`data` 是一行 JSON（`ensure_ascii=false`，中文直接出）。

### 7.2 各事件怎么用

| `event` | `data` | UI 该做什么 |
|---------|--------|-------------|
| `metadata` | `{ run_id, thread_id }` | 保存 run_id |
| `messages` | `[chunk, meta]` | **token 级增量**：拼 AI 正文、思考、tool_call 参数 |
| `values` | 完整 state | **权威快照**：用 `messages[]` 替换本地列表（标题、todos、artifacts 也在这） |
| `updates` | `{ nodeName: writes }` | 可忽略；或用来知道刚跑完哪个节点 |
| `custom` | 见下表 | toast / 子任务状态 |
| `end` | `null` | 结束本轮，关 loading |
| `error` | 错误对象 | 展示错误 |

`custom` 常见：

```json
{ "type": "task_running", "task_id": "…", "message": "正在检索…" }
{ "type": "llm_retry", "message": "模型调用失败，正在重试…" }
{ "type": "context_compacting", "message": "正在压缩上下文…" }
```

后两个弹 toast 即可，不要当消息气泡。

### 7.3 `event: messages` 的 chunk（最重要）

`data` 是二元组：

```json
[
  {
    "type": "AIMessageChunk",
    "id": "run-abc-0",
    "content": "正在",
    "additional_kwargs": {
      "reasoning_content": "用户想抽取结构，我先读文件…"
    },
    "tool_call_chunks": [
      {
        "index": 0,
        "id": "call_xxx",
        "name": "bash",
        "args": "{\"description\": \"创建脚本\""
      }
    ]
  },
  {
    "langgraph_node": "model",
    "ls_provider": "…",
    "ls_model_name": "…"
  }
]
```

合并规则（按 `chunk.id` 分桶）：

1. **正文**：把每次 `content`（字符串）往后拼；如果是 block 数组，只拼 `type==="text"` 的 `text`
2. **思考**：`additional_kwargs.reasoning_content` 一般是 **累计全文**（以最新一帧为准）；若是 delta 则拼接。同时要从正文里剥 `<think>…</think>`（见第 10 节）
3. **工具调用**：按 `tool_call_chunks[].index` 拼 `name` / `args`（args 是 JSON **字符串碎片**，拼完再 `JSON.parse`）
4. **工具结果**：会出现 `type: "tool"` / `ToolMessage`，`tool_call_id` 对上上面的 `id`，`name` 为工具名，`content` 为结果

`values.messages` 到来后，用快照覆盖增量状态，避免拼错。

### 7.4 Angular 解析骨架

```ts
async function streamRun(
  lgBase: string,
  threadId: string,
  body: unknown,
  token: string,
  onEvent: (event: string, data: unknown) => void,
): Promise<string | undefined> {
  const res = await fetch(`${lgBase}/threads/${threadId}/runs/stream`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
      Accept: 'text/event-stream',
    },
    body: JSON.stringify(body),
  });
  if (res.status === 409) throw new Error('当前对话还在生成回答，请稍候再发送');
  if (!res.ok) throw new Error(`HTTP ${res.status}`);

  const location = res.headers.get('Content-Location') || '';
  const runId = location.split('/runs/')[1];

  const reader = res.body!.getReader();
  const decoder = new TextDecoder();
  let buf = '';
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    buf += decoder.decode(value, { stream: true });
    const parts = buf.split('\n\n');
    buf = parts.pop() || '';
    for (const block of parts) {
      if (block.startsWith(':')) continue; // heartbeat
      let event = 'message';
      let data = '';
      for (const line of block.split('\n')) {
        if (line.startsWith('event:')) event = line.slice(6).trim();
        else if (line.startsWith('data:')) data += line.slice(5).trim();
      }
      if (!data) continue;
      onEvent(event, data === 'null' ? null : JSON.parse(data));
    }
  }
  return runId;
}
```

**参考代码**

| 说明 | 路径 |
|------|------|
| SSE 组帧（`event:` / `data:` / `id:`） | `offline-backend-20260512/backend/app/gateway/services.py`（`format_sse`、`sse_consumer`） |
| 心跳 / 订阅 | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/stream_bridge.py` |
| 首帧 `event: metadata` | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/runs/worker.py`（`bridge.publish(..., "metadata", {run_id, thread_id})`） |
| `messages-tuple` → 内部 `messages` | 同上 `run_agent`；SSE 事件名 `_lg_mode_to_sse_event` |
| chunk 序列化成 `[chunk, meta]` | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/serialization.py`（`serialize_messages_tuple` / `serialize_channel_values`） |
| 前端消费：onCustomEvent / onUpdateEvent | `frontend-web/src/core/threads/hooks.ts` |
| 协议说明 | `offline-backend-20260512/backend/docs/STREAMING.md` |

---

## 8. 消息数据结构（历史 + 实时共用）

`values.messages[]` 每条大致如下（LangChain 序列化后）：

```json
{
  "type": "human | ai | tool",
  "id": "uuid-or-run-id",
  "name": "ask_clarification | bash | …",
  "content": "字符串 或 content block 数组",
  "tool_calls": [
    { "id": "call_xxx", "name": "bash", "args": { "description": "执行脚本", "command": "python3 a.py" } }
  ],
  "tool_call_id": "call_xxx",
  "additional_kwargs": {
    "reasoning_content": "…",
    "clarification": { },
    "files": [ ],
    "client_ts": "…",
    "hide_from_ui": false
  }
}
```

### 8.1 `content` 形态

| 形态 | 含义 |
|------|------|
| `"一段文本"` | 最常见 |
| `[{ "type": "text", "text": "…" }]` | 多段文本 |
| `[{ "type": "image_url", "image_url": { "url": "…" } }]` | 用户图 / 模型回图 |
| `[{ "type": "thinking", "thinking": "…" }]` | Anthropic 风格思考 |
| `[{ "type": "json", "json": { } }]` | 工具结构化结果 |

### 8.2 必须隐藏、不要渲染的消息

- `additional_kwargs.hide_from_ui === true`（摘要压缩等）
- `name === "summary"`
- `name === "todo_reminder"`
- `type === "system"`（一般不会出现在 UI 列表）

### 8.3 角色怎么画

| `type` | 默认 UI |
|--------|---------|
| `human` | 右侧用户气泡，Markdown 可关，展示附件 chips |
| `ai` 且无 `tool_calls`、有正文 | 左侧助手最终回答（Markdown） |
| `ai` 有 `tool_calls` 或仅有思考 | **不单独当最终气泡**，进入步骤条 |
| `tool` | **几乎不单独成气泡**，并进步骤条 / 协助卡片 |

**参考代码**

| 说明 | 路径 |
|------|------|
| 分组、抽文本、抽思考、隐藏消息 | `frontend-web/src/core/messages/utils.ts`（`groupMessages` / `extractContentFromMessage` / `extractReasoningContentFromMessage` / `isHiddenFromUIMessage`） |
| 检索结果识别 | `frontend-web/src/core/messages/search-results.ts` |
| 序列化后的 message dict | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/serialization.py` |

---

## 9. 消息列表如何分组渲染

本系统 `groupMessages()` 的规则，Angular 请原样移植，否则步骤条和协助卡片会对不齐。

从前往后扫 `messages`（已过滤隐藏消息）：

1. `human` → 一组 `human`
2. `ai` 且 `tool_calls` 含 `present_files` → `assistant:present-files`（正文 + 文件卡片）
3. `ai` 且 `tool_calls` 含 `task` → `assistant:subagent`（子任务卡）
4. `ai` 有思考或有其它 tool_calls → 并入（或新建）`assistant:processing`（**步骤条**）
5. 同一条 `ai` **既有思考又有最终正文、且没有 tool_calls** → processing 一组 **再** 出一组 `assistant` 气泡
6. `tool` 且 `name === ask_clarification` → 先塞进当前 processing，再单独开 `assistant:clarification`
7. 其它 `tool` → 塞进当前 processing（用 `tool_call_id` 填步骤的 result）

渲染顺序示例（一轮典型技能执行）：

```text
[用户] 请抽取结构
[步骤条]
  思考
  读取文件  SKILL.md
  创建脚本
  执行脚本
  写入文件  /mnt/user-data/outputs/flow.json
  展示文件
[助手] 已生成 flow-json，可在右侧预览。
```

若中途问用户：

```text
[步骤条] … 需要你的协助
[协助卡片] 需要你的确认
（等待用户下一轮 human）
```

### 9.1 用户气泡

- 文本：`extractContentFromMessage`，去掉 `<uploaded_files>…</uploaded_files>` 这类内部标记
- 附件：`additional_kwargs.files[]` → `{ filename, size, path, status }`
- 图片 block → `<img>`
- 可选：编辑/删除（删除要改 checkpoint，对接初期可不做）

### 9.2 助手最终回答

- Markdown（GFM 表格/代码块）
- 流式时按 token 追加；`values` 快照到达后用完整 `content` 替换
- 正文里的 `<think>` 必须剥掉（见第 10 节）
- 引用：技能检索结果会在步骤里展开，正文里可能有 `[n]` 引用角标
- 复制 / 导出 Word 可选

### 9.3 流式指示

`busy` 且还没有最终 `assistant` 气泡时，在列表底部显示跳动的「正在生成」。  
上传文件未完成时可插一条 mock AI：`additional_kwargs.element === "task"`，文案「文件上传中，请稍候...」。

**参考代码**

| 说明 | 路径 |
|------|------|
| 列表入口、分组渲染 | `frontend-web/src/components/workspace/messages/message-list.tsx` |
| 单条用户/助手气泡 | `frontend-web/src/components/workspace/messages/message-list-item.tsx` |
| Markdown | `frontend-web/src/components/workspace/messages/markdown-content.tsx` |
| 气泡/会话滚动容器 | `frontend-web/src/components/ai-elements/message.tsx`、`conversation.tsx` |
| 跳动「正在生成」 | `frontend-web/src/components/workspace/streaming-indicator.tsx` |
| 技能来源展示 | `frontend-web/src/core/skill-display/runtime.ts` |
| 导出 | `frontend-web/src/core/threads/export.ts`；Word：`frontend-web/src/components/workspace/messages/download-word-button.tsx` |
| 删除消息 | `frontend-web/src/components/workspace/messages/delete-message-button.tsx` |
| 问题跳转 | `frontend-web/src/components/workspace/question-navigator.tsx` |

---

## 10. 思考内容如何对接

思考 **没有** 独立 SSE 事件名，混在 AI 消息里。按优先级取：

1. `additional_kwargs.reasoning_content`（字符串，多数内网模型走这条）
2. content block `{ type: "thinking", thinking: "…" }`
3. 正文里的 `<think>…</think>`（含流式 **未闭合** 的 `<think>`）

### 10.1 剥离算法（请直接用）

```ts
const THINK_RE = /<think>\s*([\s\S]*?)\s*<\/think>/g;
const THINK_OPEN = '<think>';

function splitThink(content: string): { answer: string; thinking: string | null } {
  const parts: string[] = [];
  let working = content.replace(THINK_RE, (_, t: string) => {
    const s = t.trim();
    if (s) parts.push(s);
    return '';
  });
  const i = working.indexOf(THINK_OPEN);
  if (i !== -1 && !working.slice(i).includes('</think>')) {
    const partial = working.slice(i + THINK_OPEN.length).trim();
    if (partial) parts.push(partial);
    working = working.slice(0, i);
  }
  return { answer: working.trim(), thinking: parts.length ? parts.join('\n\n') : null };
}
```

展示用 `answer`，思考区用 `reasoning_content || thinking`。

### 10.2 UI 约定（与现网一致）

- 步骤条里：思考是一种 step，标题 **「思考」**，可折叠，灯泡图标
- 只有思考、还没有工具、还没有最终正文时：单独一块可折叠「思考」，流式时默认展开，结束后可自动收起
- **历史刷新后思考仍在**（写在 checkpoint 的 AI 消息上），不要丢
- 不要把思考当作用户可见的最终答案

`thinking_enabled: false` 时模型不应再吐思考；若仍出现 `<think>`，继续剥掉以免露标签。

**参考代码**

| 说明 | 路径 |
|------|------|
| 抽思考 / 剥 `<think>`（含未闭合） | `frontend-web/src/core/messages/utils.ts`（`extractReasoningContentFromMessage`、`splitInlineReasoning`） |
| 步骤条里的思考步 | `frontend-web/src/components/workspace/messages/message-group.tsx`（`convertToSteps` 的 `reasoning`） |
| 独立思考折叠块 | `frontend-web/src/components/ai-elements/reasoning.tsx` |
| 文案「思考」 | `frontend-web/src/core/i18n/locales/zh-CN.ts`（`t.common.thinking`） |
| 模型思考流字段 | `offline-backend-20260512/backend/packages/harness/deerflow/models/vllm_provider.py` |
| 关思考注入 extra_body | `offline-backend-20260512/backend/packages/harness/deerflow/models/factory.py` |

---

## 11. 步骤条（Chain of Thought）— 请做全

步骤条只渲染 `assistant:processing` 组。内部只有两类 step：

- `reasoning`：思考文本
- `toolCall`：一次工具调用（`task` 子任务除外，走独立卡片）

### 11.1 从消息抽出 steps

对组内每条 `ai`：

1. 若有思考 → push `{ type: "reasoning", reasoning }`
2. 遍历 `tool_calls`，跳过 `name === "task"`
3. 用 `tool_call.id` 在组内找对应 `type==="tool"` 的消息，作为 `result`
4. `result.content` 若是 JSON 字符串就 parse

UI：

- 默认只展示 **最后一个工具步骤** + 其后的思考
- 上方折叠：「查看其他 N 个步骤」/「隐藏步骤」
- 进行中：该步 status=`active`（转圈）；有 result 后 `complete`（对勾）
- 工具参数还在流式拼接时，label 用已有 `args.description` 或占位「正在调用工具…」

### 11.2 步骤标题怎么来（「创建脚本 / 执行脚本 / 写入文件」在这里）

**系统没有名为 `create_script` / `execute_script` 的工具。**  
模型调用沙箱工具时 **必须先填 `args.description`**（短中文说明），步骤条 **优先展示 description**。所以你会看到：

| 用户看到的步骤 | 实际 `tool_calls[].name` | `args` |
|----------------|--------------------------|--------|
| 创建脚本 | `bash` | `{ description: "创建脚本", command: "cat > /tmp/a.py <<'EOF' …" }` |
| 执行脚本 | `bash` | `{ description: "执行脚本", command: "python3 /tmp/a.py" }` |
| 写入文件 | `write_file` 或 `str_replace` | `{ description: "写入文件", path: "/mnt/user-data/outputs/flow.json", content: "…" }` |
| 读取技能说明 | `read_file` | `{ description: "读取技能说明", path: "/mnt/skills/public/…/SKILL.md" }` |

`description` 是模型写的，文案不固定。没有 description 时再用下表中文底稿。

### 11.3 全量工具 → 步骤条映射

与现网 `message-group.tsx` + `zh-CN.ts toolCalls` 对齐。未知 MCP/技能脚本一律走最后一行。

| `name` | 默认中文标题 | 图标建议 | 展开区 |
|--------|--------------|----------|--------|
| （reasoning step） | 思考 | 灯泡 | Markdown/纯文本思考 |
| `web_search` | `知识库检索 "{query}"`；无 query 则为「知识库检索」 | 搜索 | 结果列表（title/snippet/url），可折叠「N 条检索结果」 |
| 任意工具但 result 长得像检索 `{ results: [...] }` | `搜索 “{query}”` 或「搜索相关信息」 | 搜索 | 同上 |
| 技能展示/RAG 引用模式 | 「检索参考来源」或「获取 N 条结果」 | 搜索 | 来源卡片（title/snippet/原文） |
| `image_search` | `搜索相关图片 “{query}”` | 搜索 | 缩略图网格，点开 `source_url` |
| `web_fetch` | 查看网页 | 地球 | 链接，标题从返回 Markdown 的 `# title` 抽 |
| `ls` | `args.description` 或 **列出文件夹** | 文件夹 | path chip |
| `read_file` | `args.description` 或 **读取文件** | 书本 | path chip |
| `write_file` | `args.description` 或 **写入文件** | 笔记本 | path；点击打开产物预览 |
| `str_replace` | 同上（默认也叫写入文件） | 笔记本 | path |
| `bash` | **必须用 `args.description`**；没有则 **执行命令** | 终端 | 展示 `command` 的 bash 代码块（不一定展示 stdout，stdout 在 tool result 里） |
| `glob` | `args.description` 或 `使用 “glob” 工具` | 扳手 | 可选 path/pattern |
| `grep` | `args.description` 或 `使用 “grep” 工具` | 扳手 | pattern / path |
| `browser_fetch_page` | `args.description` 或 `使用 “browser_fetch_page” 工具` | 扳手 | url |
| `browser_act` | `args.description` 或 `使用 “browser_act” 工具` | 扳手 | 动作说明 |
| `ask_clarification` | **需要你的协助** | 问号 | 空（真正交互在卡片） |
| `write_todos` | **更新 To-do 列表** | 清单 | 空；完整列表见输入框上方 Todo 面板 |
| `present_files` | 一般不进步骤条，进「展示文件」组 | 文件 | 见 13.1 |
| `update_artifact` | `args.title` 或「生成代码」/「生成文档」 | 笔 | 「代码文件」或「Markdown 文档」 |
| `view_image` | `args.description` 或 `使用 “view_image” 工具` | 扳手 | 图片路径 |
| `skill_list` | `args.description` 或 `使用 “skill_list” 工具` | 扳手 | — |
| `skill_view` | 读取某个技能 | 扳手 | 技能名 |
| `search_skills` | 检索可用技能 | 扳手 | 关键词 |
| `memory` / `hindsight_*` | 记忆读写 | 扳手 | — |
| `deep_research_progress` | `args.label` 或「正在撰写研究报告」 | 转圈/对勾 | detail + 可折叠「模型思考」；`status!=="complete"` 为进行中 |
| `task` | **不要**画在步骤条 | — | 见 13.2 子任务卡 |
| **其它 MCP / 自定义工具** | `args.description` **或** `使用 “{name}” 工具` | 扳手 | 有 path/url 可展示 |

`roundtable-structure` 常走技能 `knowledge-base-ingest`，因此一轮里会密集出现：`read_file`（SKILL.md）→ `bash`（创建/执行脚本）→ `write_file`（产物）→ `present_files`。把 `bash.description` 原样显示，就能覆盖「创建脚本」「执行脚本」。

### 11.4 工具参数字段（沙箱类）

所有沙箱工具的 **第一个参数都是 `description`**：

```ts
interface BashArgs { description: string; command: string }
interface LsArgs { description: string; path: string }
interface ReadFileArgs { description: string; path: string }
interface WriteFileArgs { description: string; path: string; content: string }
interface StrReplaceArgs { description: string; path: string; old_str: string; new_str: string }
interface GlobArgs { description: string; pattern: string; path?: string }
interface GrepArgs { description: string; pattern: string; path?: string }
interface WebSearchArgs { query: string }
interface WebFetchArgs { url: string }
```

`write_file` 流式时 `content` 会变长，可做实时预览（现网点击步骤打开右侧产物面板）。

### 11.5 检索结果 result 形状（web_search / 技能）

常见：

```json
{
  "success": true,
  "query": "台湾滨海防卫",
  "count": 10,
  "results": [
    {
      "title": "…",
      "content_preview": "…",
      "url": "https://…",
      "recUuid": "…",
      "score": 0.8
    }
  ]
}
```

字段名不统一（`content` / `page_content` / `snippet` / `m_title` / `name`），展示时做并集兜底。

**参考代码**

| 说明 | 路径 |
|------|------|
| **步骤条主实现（必看）** | `frontend-web/src/components/workspace/messages/message-group.tsx`（`convertToSteps`、按 `name` 分支、`ArtifactWriteToolCall`） |
| ChainOfThought 组件 | `frontend-web/src/components/ai-elements/chain-of-thought.tsx` |
| 中文底稿 | `frontend-web/src/core/i18n/locales/zh-CN.ts` → `toolCalls`；类型 `frontend-web/src/core/i18n/locales/types.ts` |
| 工具一句话说明 | `frontend-web/src/core/tools/utils.ts`（`explainToolCall`） |
| 检索结果卡片 | `frontend-web/src/core/messages/search-results.ts` |
| 写文件实时预览 | `frontend-web/src/core/artifacts/streaming-write-preview.ts` |
| bash / ls / read / write / glob / grep | `offline-backend-20260512/backend/packages/harness/deerflow/sandbox/tools.py`（参数都要求先填 `description`） |
| 工具装配（含 MCP、内置） | `offline-backend-20260512/backend/packages/harness/deerflow/tools/tools.py` |
| present_files | `offline-backend-20260512/backend/packages/harness/deerflow/tools/builtins/present_file_tool.py` |
| skill_list / skill_view / search_skills | `offline-backend-20260512/backend/packages/harness/deerflow/tools/builtins/skill_tools.py` |
| 启用哪些工具 | `offline-backend-20260512/backend/config.yaml` → `tools[]` |
| 会商页步骤条（对照用，对话页以 message-group 为准） | `frontend-web/src/roundtable-planning/lib/step-display.tsx` |

---

## 12. 用户协助卡片（ask_clarification）

当模型信息不够、有多种做法、或要确认风险时，会调用工具 `ask_clarification`。  
**ClarificationMiddleware 会截住该工具，写入 ToolMessage，并 `goto=END` 结束本轮。**  
这 **不是** LangGraph `interrupt()` / `Command(resume)`。用户点选项后，发 **新的 human 消息** 即可，智能体会带着选择继续。

### 12.1 如何识别

`message.type === "tool" && message.name === "ask_clarification"`

结构化数据在：

```json
{
  "additional_kwargs": {
    "clarification": {
      "question": "流程图层级按哪套业务？",
      "clarification_type": "approach_choice",
      "context": "报告里同时出现了任务链和目的链。",
      "options": [
        { "id": "option-0", "label": "任务→目的→行为体", "description": "可选" },
        { "id": "option-1", "label": "按报告原标题层级" }
      ],
      "allow_custom": true,
      "allow_multiple": false
    }
  },
  "content": "（Markdown 兜底文案，无结构化数据时用这个渲染）"
}
```

`clarification_type`：

- `missing_info` 缺信息
- `ambiguous_requirement` 需求有歧义
- `approach_choice` 方案选择
- `risk_confirmation` 风险确认
- `suggestion` 建议确认

同一轮可以有 **多张** 独立卡片（多个 tool call）。只统计 **上一条 human 之后** 的 clarification 为「待答」。

### 12.2 UI（与现网文案）

- 标题：**需要你的确认**；多张时显示 `1/N`
- 展示 `context`、`question`
- 选项做成按钮
- `allow_multiple !== true`：单选。**仅一张待答卡时，点击即提交**；多张时只记录选择，点最后一张上的「全部发送」
- `allow_multiple === true`：多选 + 必须点提交
- `allow_custom !== false`（后端恒为 true）：额外文本框
- 按钮：「发送回答」/ 多张时「全部发送」
- 历史里已答过的卡：禁用，只读回显

步骤条里对应一步标题仍是「需要你的协助」。

### 12.3 提交内容格式（必须按这个拼，模型才认）

单张：

```text
我选择：任务→目的→行为体
我选择：A、B；补充：用户打的字
（只有自定义）用户打的字
```

多张：

```text
问题1「……」：我选择：A
问题2「……」：补充：……
```

然后：

```http
POST …/runs/stream
input.messages = [{ type: "human", content: "<上面拼好的文本>" }]
```

不要调 `/state` 的 resume，也不要自己造 ToolMessage。

**参考代码**

| 说明 | 路径 |
|------|------|
| 卡片 UI、拼「我选择：」、多卡合并提交 | `frontend-web/src/components/workspace/messages/message-list.tsx`（`ClarificationCard`、`handleSubmitAllClarifications`） |
| 识别 tool 消息 | `frontend-web/src/core/messages/utils.ts`（`isClarificationToolMessage`） |
| 工具定义 | `offline-backend-20260512/backend/packages/harness/deerflow/tools/builtins/clarification_tool.py` |
| 截住工具、写 `additional_kwargs.clarification`、goto END | `offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/clarification_middleware.py`（`_build_payload`） |
| `allow_multiple` 解析 | `offline-backend-20260512/backend/packages/harness/deerflow/tools/builtins/clarification_utils.py` |
| 提交后又走同一套 sendMessage | `frontend-web/src/pages/AgentChatPage.tsx`、`frontend-web/src/core/threads/hooks.ts`（**不是** Command resume） |

---

## 13. 其它卡片与面板

### 13.1 展示文件 `present_files`

AI `tool_calls` 含 `name: "present_files"`，`args.filepaths: string[]`（必须是 `/mnt/user-data/outputs/…`）。

UI：Markdown 摘要 + 文件卡片。点击后：

```http
GET {GATEWAY}/api/threads/{thread_id}/artifacts/{path}
```

`path` 例：`mnt/user-data/outputs/flow.json`（虚拟前缀，不要用 Windows 盘符）。  
`?download=true` 强制下载。HTML/SVG 会当附件，降低 XSS。

列表：

```http
GET {GATEWAY}/api/threads/{thread_id}/artifacts
→ { "thread_id", "files": [{ path, name, size_bytes, mime_type, modified_at }] }
```

state 里的 `artifacts: string[]` 是虚拟路径列表，可与卡片同步。

### 13.2 子任务 `task`（ultra 档）

`tool_calls[].name === "task"`，`args` 含 `description` / `prompt` / `subagent_type`。  
组类型 `assistant:subagent`，标题「执行 N 个子任务」（N>1 时「并行执行」）。  
`custom` 事件 `task_running` 更新进行中文案。终态看对应 tool 结果。

`roundtable-structure` 默认不必开 ultra；对接时可先不做，遇到 `task` 当普通扳手步骤也行。

### 13.3 Todo 面板（pro / ultra）

`write_todos` 出现在步骤条；完整列表在 `values.todos`：

```ts
interface Todo { content?: string; status?: 'pending' | 'in_progress' | 'completed' }
```

现网浮在输入框上方。一轮只应有一个 `in_progress`。

### 13.4 创建智能体 / 写作审批卡

`setup_agent` / `setup_writing` 带 approval kwargs。普通 `roundtable-structure` 对话 **不会出现**，可忽略。  
Deep Research 的 `setup_research_approval` 同理。

**参考代码**

| 说明 | 路径 |
|------|------|
| present_files 分组渲染 | `frontend-web/src/components/workspace/messages/message-list.tsx`（`assistant:present-files`） |
| 产物 API | `offline-backend-20260512/backend/app/gateway/routers/artifacts.py` |
| 产物前端 | `frontend-web/src/components/workspace/artifacts/`（如 `artifact-file-detail.tsx`） |
| 子任务卡 | `frontend-web/src/components/workspace/messages/subtask-card.tsx` |
| `task` 工具 / 子代理 | `offline-backend-20260512/backend/packages/harness/deerflow/subagents/` |
| Todo 面板 | `frontend-web/src/components/workspace/todo-list.tsx`；类型 `frontend-web/src/core/todos/types.ts` |
| write_todos 中间件装配 | `offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/agent.py`（`_build_middlewares`） |

---

## 14. 标题、追问、错误态

### 14.1 自动标题

第一轮用户消息到达后，TitleMiddleware 先用问题字面做 **临时标题**（`title_provisional: true`），再异步 LLM 生成最终标题。  
听 `event: values` 的 `title` 即可，刷新列表。

### 14.2 追问建议（一轮结束后）

```http
POST {GATEWAY}/api/threads/{thread_id}/suggestions
{
  "messages": [
    { "role": "user", "content": "…" },
    { "role": "assistant", "content": "…" }
  ],
  "n": 3,
  "model_name": "deepseek-chat"
}
```

```json
{ "suggestions": ["是否导出 JSON？", "按另一套层级再抽一次"] }
```

点建议 = 再发一条 human。失败时返回空数组，不要报错挡 UI。

### 14.3 错误与限流

| 情况 | 表现 | UI |
|------|------|----|
| 会话已在生成 | HTTP 409 | toast：「当前对话还在生成回答…」，不要红框 |
| 全局并发打满 | HTTP 429 | toast 提示稍后再试 |
| 模型失败重试 | `custom.llm_retry` | 轻提示 |
| 上下文压缩 | `custom.context_compacting` | 「正在压缩上下文…」 |
| 会话不属于当前用户 | 403/404 | 回到新建 |

**参考代码**

| 说明 | 路径 |
|------|------|
| 标题展示 | `frontend-web/src/components/workspace/thread-title.tsx` |
| 列表用 title | `frontend-web/src/core/threads/utils.ts`（`titleOfThread`） |
| 临时标题 + LLM 标题 | `offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/title_middleware.py` |
| 追问 API 调用 | `frontend-web/src/components/workspace/input-box.tsx`（`/api/threads/${threadId}/suggestions`） |
| 追问后端 | `offline-backend-20260512/backend/app/gateway/routers/suggestions.py` |
| 409 toast | `frontend-web/src/core/threads/hooks.ts`（`isActiveRunConflictError` / `onError`） |
| 压缩 toast | `offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/summarization_middleware.py`（`custom.context_compacting`） |

---

## 15. 文件上传（用户侧）

先有 `thread_id`（可先 create 空会话）。

```http
POST {GATEWAY}/api/threads/{thread_id}/uploads
Authorization: Bearer <jwt>
Content-Type: multipart/form-data
```

字段名 `files`，可多文件。默认上限约 10 个、单文件 50MB、合计 100MB。  
PDF/PPT/Excel/Word 会转成 Markdown 一并放入 uploads。

```json
{
  "success": true,
  "message": "Successfully uploaded 1 file(s)",
  "files": [
    {
      "filename": "report.docx",
      "virtual_path": "/mnt/user-data/uploads/report.docx",
      "markdown_virtual_path": "/mnt/user-data/uploads/report.md"
    }
  ],
  "skipped_files": []
}
```

发消息时：

```json
"additional_kwargs": {
  "files": [
    { "filename": "report.md", "path": "/mnt/user-data/uploads/report.md", "status": "uploaded" }
  ]
}
```

限额：`GET /api/threads/{thread_id}/uploads/limits`。  
列表/删除：`GET …/uploads/list`，`DELETE …/uploads/{filename}`。

**参考代码**

| 说明 | 路径 |
|------|------|
| 前端上传 | `frontend-web/src/components/workspace/input-box.tsx`；预览 `frontend-web/src/components/workspace/messages/uploaded-file-preview-dialog.tsx` |
| 后端上传路由 | `offline-backend-20260512/backend/app/gateway/routers/uploads.py` |
| 目录与虚拟路径 | `offline-backend-20260512/backend/packages/harness/deerflow/uploads/manager.py` |
| 文档转 Markdown | `offline-backend-20260512/backend/packages/harness/deerflow/utils/file_conversion.py` |
| 说明文档 | `offline-backend-20260512/backend/docs/FILE_UPLOAD.md` |

---

## 16. 推荐的页面结构（对标 AgentChatPage）

不必做智能体配置侧栏。最小工作台：

```
┌─ 左：会话列表（threads/search by agent_id）─┬─ 中：消息列表 ─┬─ 右：产物预览 ─┐
│  新建对话                                      │  标题（values.title）│  artifacts     │
│  每条 title + 时间                             │  用户/步骤条/卡片/回答│                │
│                                                │  Todo（可选）        │                │
│                                                │  输入框：模型+档位+停止│                │
└────────────────────────────────────────────────┴─────────────────────┴────────────────┘
```

输入框建议：

- 模型 Select（`GET /api/models`）
- 档位：快速 / 思考 / 规划（对应 flash / thinking / pro）；ultra 可隐藏
- 发送、停止（streaming 时）
- 可选：上传、追问 chips

`roundtable-structure` 是「结构化抽取」智能体：给它方案报告或席位交付，产出 flow-json 流程图数据，常伴随写文件 + 展示文件。不要当成多智能体会商编排页（`/roundtable` 是另一套 API）。

**参考代码**

| 说明 | 路径 |
|------|------|
| 对话页整页 | `frontend-web/src/pages/AgentChatPage.tsx` |
| 路由 | `frontend-web/src/pages/WorkspaceRoutes.tsx` |
| ChatBox（标题栏 + 列表 + 输入） | `frontend-web/src/components/workspace/chats/chat-box.tsx` |
| 输入框 | `frontend-web/src/components/workspace/input-box.tsx` |
| 左栏最近会话 | `frontend-web/src/components/workspace/agents/agent-chat-sidebar.tsx`、`agent-recent-chats.tsx` |
| 欢迎/推荐问题 | `frontend-web/src/components/workspace/agent-welcome.tsx`、`agents/agent-question-chips.tsx` |
| 智能体种子 | `offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed_assets/roundtable-structure/` |
| 会商编排（不要和本页搞混） | `frontend-web/src/roundtable-planning/`、`offline-backend-20260512/backend/app/gateway/routers/multi_agent.py` |
| iframe 嵌现网 UI（备选） | `frontend-web/docs/embed-iframe-chat.md` |

---

## 17. 最小对接顺序（验收清单）

1. `POST /api/v1/auth/login/username` → 存 JWT  
2. CORS 已包含 Angular Origin  
3. `GET /api/models` → 下拉，选中项的 `name` 写入 `context.model_name`  
4. `POST /api/threads` + `metadata.agent_id=roundtable-structure`  
5. `POST /api/threads/{id}/runs/stream`，`assistant_id` 与 `context.agent_id` 都等于 `roundtable-structure`  
6. 解析 SSE：`metadata` → `messages` 增量 → `values` 覆盖 → `end`  
7. 消息分组：用户气泡 / 步骤条 / 协助卡片 / 最终 Markdown  
8. 步骤条至少覆盖：`bash`（description=创建脚本/执行脚本）、`write_file`（写入文件）、`read_file`、`ls`、`web_search`、未知工具  
9. 思考：`reasoning_content` + `<think>` 剥离  
10. 协助卡片：选项 → 拼「我选择：」→ 新一轮 human  
11. `POST /threads/search` 还原列表；`GET /state` 还原消息（含思考与步骤）  
12. 停止：`POST …/runs/{run_id}/cancel`  
13. 409 toast  
14. `present_files` → `GET …/artifacts/{path}`  

---

## 18. 接口速查

Base：`{GATEWAY} = http://host:8001`，LangGraph `{LG} = {GATEWAY}/api`。  
除登录外均需 `Authorization: Bearer`。

| 方法 | 路径 | 用途 |
|------|------|------|
| POST | `/api/v1/auth/login/username` | 用户名登录 |
| POST | `/api/v1/auth/login/token?token=` | 上游 token 换票 |
| GET | `/api/v1/auth/me` | 当前用户 |
| GET | `/api/models` | 模型列表 |
| POST | `/api/threads` | 建会话 |
| POST | `/api/threads/search` | 历史列表 |
| POST | `/api/threads/count` | 历史条数 |
| GET | `/api/threads/{id}` | 会话摘要 + values |
| GET | `/api/threads/{id}/state` | 最新 checkpoint |
| PATCH | `/api/threads/{id}` | 改 metadata |
| DELETE | `/api/threads/{id}` | 删除会话 |
| POST | `/api/threads/{id}/history` | checkpoint 历史 |
| POST | `/api/threads/{id}/runs/stream` | **流式对话** |
| POST | `/api/threads/{id}/runs/{rid}/cancel` | 停止 |
| GET | `/api/threads/{id}/runs` | run 列表 |
| GET | `/api/threads/{id}/runs/{rid}/join` | 重连 SSE |
| POST | `/api/threads/{id}/uploads` | 上传 |
| GET | `/api/threads/{id}/artifacts` | 产物列表 |
| GET | `/api/threads/{id}/artifacts/{path}` | 读产物 |
| POST | `/api/threads/{id}/suggestions` | 追问 |

可选简化入口（**无登录、不落聊天记录、没有步骤条协议**，不建议用来复刻本页）：

- `POST /api/open/chat` / `/api/open/chat/stream`（`agent_id` 或中文 `agent_name`）

可选 iframe 嵌现网 UI（不自己画步骤条）：见 `frontend-web/docs/embed-iframe-chat.md`。那是通用工作台 `/embed/chats`，不是 `agents/roundtable-structure` 路由；若必须嵌本页，可用：

```
{FRONTEND}/#/page/workspace/agents/roundtable-structure/chats/new?embed=1
```

仍要先登录；iframe 跨域时走 `?embed=1` 可隐藏外壳。要完全自绘 UI，请走本文 REST + SSE。

---

## 19. Angular 工程注意

1. **POST SSE 用 fetch**，不要 `HttpClient.get` + EventSource  
2. `run_id` 从 `Content-Location` 或 `event: metadata` 取；取消必须打 cancel  
3. `assistant_id` 用 **`roundtable-structure`**，不要传「结构化抽取」  
4. 历史过滤靠 `metadata.agent_id`，第一轮后务必 PATCH  
5. 同一 thread 未 `end` 不要再发，否则 409  
6. JWT 约 7 天，无 refresh  
7. 把 `localhost:4200` 加入 `GATEWAY_CORS_ORIGINS`  
8. 可用 npm 包 `@langchain/langgraph-sdk` 的 `Client`（`apiUrl: LG, defaultHeaders: { Authorization }`）少写 SSE 细节；UI 仍要自己做分组/步骤条/卡片  
9. 不要把思考、tool 结果、协助卡当成三条普通聊天记录平铺，观感会和现网差很多  
10. 步骤条 label **永远优先 `args.description`**，这样才能显示「创建脚本」「执行脚本」「写入文件」

---

## 20. 参考实现总索引

路径均相对仓库根 `deerflow-server/`。后端根目录 = `offline-backend-20260512/backend/`。  
各节正文末尾也有对应表；这里按主题汇总，加粗的是对接时优先打开的文件。

### 20.1 前端：页面与 UI

| 主题 | 路径 |
|------|------|
| **智能体对话页** | `frontend-web/src/pages/AgentChatPage.tsx` |
| 路由 `agents/:agent_id/chats/:thread_id` | `frontend-web/src/pages/WorkspaceRoutes.tsx` |
| 对话壳（标题 / 列表 / 输入 / 产物入口） | `frontend-web/src/components/workspace/chats/chat-box.tsx` |
| **消息列表 + 协助卡片** | `frontend-web/src/components/workspace/messages/message-list.tsx` |
| 用户/助手气泡 | `frontend-web/src/components/workspace/messages/message-list-item.tsx` |
| **步骤条（创建脚本/执行脚本/写入文件等）** | `frontend-web/src/components/workspace/messages/message-group.tsx` |
| Markdown | `frontend-web/src/components/workspace/messages/markdown-content.tsx` |
| 子任务卡 | `frontend-web/src/components/workspace/messages/subtask-card.tsx` |
| 思考折叠块 | `frontend-web/src/components/ai-elements/reasoning.tsx` |
| ChainOfThought 控件 | `frontend-web/src/components/ai-elements/chain-of-thought.tsx` |
| 输入框（模型、档位、发送、停止、追问、上传） | `frontend-web/src/components/workspace/input-box.tsx` |
| Todo 条 | `frontend-web/src/components/workspace/todo-list.tsx` |
| 会话标题 | `frontend-web/src/components/workspace/thread-title.tsx` |
| 正在生成 | `frontend-web/src/components/workspace/streaming-indicator.tsx` |
| 会话列表 UI | `frontend-web/src/components/workspace/workspace-nav-chat-list.tsx` |
| 该智能体最近对话 | `frontend-web/src/components/workspace/agents/agent-recent-chats.tsx` |
| 左栏 | `frontend-web/src/components/workspace/agents/agent-chat-sidebar.tsx` |
| 产物预览 | `frontend-web/src/components/workspace/artifacts/` |
| 中文步骤文案 `toolCalls.*` | `frontend-web/src/core/i18n/locales/zh-CN.ts` |

### 20.2 前端：协议与状态

| 主题 | 路径 |
|------|------|
| **发消息 / useStream / cancel / 409** | `frontend-web/src/core/threads/hooks.ts` |
| 线程类型 | `frontend-web/src/core/threads/types.ts` |
| 标题与路由 | `frontend-web/src/core/threads/utils.ts` |
| **消息分组、思考、隐藏** | `frontend-web/src/core/messages/utils.ts` |
| 检索结果归一化 | `frontend-web/src/core/messages/search-results.ts` |
| **登录 API** | `frontend-web/src/core/auth/api.ts` |
| Bearer 存取 | `frontend-web/src/core/auth/index.ts` |
| 模型 API / 类型 | `frontend-web/src/core/models/api.ts`、`frontend-web/src/core/models/types.ts` |
| LangGraph Client | `frontend-web/src/core/api/api-client.ts` |
| Gateway fetch + 401 | `frontend-web/src/core/api/fetch-client.ts` |
| Base URL | `frontend-web/src/core/config/index.ts`、`frontend-web/src/env.ts` |
| 写文件流式预览 | `frontend-web/src/core/artifacts/streaming-write-preview.ts` |
| 工具一句话 | `frontend-web/src/core/tools/utils.ts` |

### 20.3 后端：HTTP

| 主题 | 路径 |
|------|------|
| **登录 /me** | `offline-backend-20260512/backend/app/gateway/routers/auth.py` |
| JWT | `offline-backend-20260512/backend/app/gateway/auth/jwt.py` |
| **CORS** | `offline-backend-20260512/backend/app/gateway/app.py` |
| 鉴权中间件 | `offline-backend-20260512/backend/app/gateway/auth_middleware.py` |
| **模型列表** | `offline-backend-20260512/backend/app/gateway/routers/models.py` |
| **会话 CRUD / search / state** | `offline-backend-20260512/backend/app/gateway/routers/threads.py` |
| **runs/stream / cancel / join** | `offline-backend-20260512/backend/app/gateway/routers/thread_runs.py` |
| start_run、SSE、context 白名单 | `offline-backend-20260512/backend/app/gateway/services.py` |
| 上传 | `offline-backend-20260512/backend/app/gateway/routers/uploads.py` |
| 产物 | `offline-backend-20260512/backend/app/gateway/routers/artifacts.py` |
| 追问 | `offline-backend-20260512/backend/app/gateway/routers/suggestions.py` |
| 简化开放聊天（不要用来复刻本页） | `offline-backend-20260512/backend/app/gateway/routers/open_chat.py` |

### 20.4 后端：运行时与工具

| 主题 | 路径 |
|------|------|
| **跑图 + 发 SSE 事件** | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/runs/worker.py` |
| RunManager | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/runs/manager.py` |
| StreamBridge | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/stream_bridge.py` |
| 消息序列化 | `offline-backend-20260512/backend/packages/harness/deerflow/runtime/serialization.py` |
| Lead Agent | `offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/agent.py` |
| **协助卡中间件** | `offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/clarification_middleware.py` |
| 协助工具 | `offline-backend-20260512/backend/packages/harness/deerflow/tools/builtins/clarification_tool.py` |
| **bash / write_file 等（description）** | `offline-backend-20260512/backend/packages/harness/deerflow/sandbox/tools.py` |
| 工具总装 | `offline-backend-20260512/backend/packages/harness/deerflow/tools/tools.py` |
| present_files | `offline-backend-20260512/backend/packages/harness/deerflow/tools/builtins/present_file_tool.py` |
| 标题 | `offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/title_middleware.py` |
| 模型工厂 | `offline-backend-20260512/backend/packages/harness/deerflow/models/factory.py` |

### 20.5 配置、种子、文档

| 主题 | 路径 |
|------|------|
| **roundtable-structure 种子** | `offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed_assets/roundtable-structure/config.yaml` |
| 同上 SOUL | `offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed_assets/roundtable-structure/SOUL.md` |
| 模型 / 工具开关 | `offline-backend-20260512/backend/config.yaml` |
| 流式协议 | `offline-backend-20260512/backend/docs/STREAMING.md` |
| 登录契约 | `offline-backend-20260512/backend/docs/AUTH_LOGIN.md` |
| 上传 | `offline-backend-20260512/backend/docs/FILE_UPLOAD.md` |
| iframe 嵌入备选 | `frontend-web/docs/embed-iframe-chat.md` |