Merge branch 'dhk-1' into 'master'
代码修改 See merge request knowledge-base-bj/deerflow-server!52
This commit is contained in:
董宏凯 committed
commit
48de418d21
20 files changed
+1380
-5450
No files matched your search
Whitespace-only changes.
@@ -1,140 +0,0 @@
|
||||
# App.tsx 路由与页面结构重构需求（首页与业务页分离）
|
||||
|
||||
## 一、需求背景
|
||||
|
||||
当前 `frontend-web/src/App.tsx` 同时承载了：
|
||||
|
||||
1. 登录/首页相关路由（如 `/login`、`/landing`）
|
||||
2. 工作台业务相关路由（如 `/workspace/chats`、`/workspace/agents`、`/workspace/scheduled/*`）
|
||||
3. 业务页所需布局与运行时包装（`WorkspaceLayout`、`ChatRuntime`）
|
||||
|
||||
这会导致 `App.tsx` 过重，职责不够单一，不利于后续维护和扩展。
|
||||
|
||||
---
|
||||
|
||||
## 二、目标（你提出的核心诉求）
|
||||
|
||||
你希望：
|
||||
|
||||
1. **除了登录与首页入口内容外**，将 `App.tsx` 中其余业务页面路由整体迁移到 `pages` 下一个新组件中。
|
||||
2. 再创建一个“承接导航/入口”的页面（或路由容器），用于放置这些导航逻辑。
|
||||
3. `App.tsx` 最终只保留顶层路由分发和基础 Provider，变得更薄。
|
||||
|
||||
> 你提到“`App.tsx 74-75 login`”，可理解为：保留登录/首页相关入口，其他工作台内容抽离。
|
||||
|
||||
---
|
||||
|
||||
## 三、重构范围
|
||||
|
||||
### 1）保留在 `App.tsx` 的内容
|
||||
|
||||
- 全局 Provider：`HashRouter`、`AppProviders`
|
||||
- 登录/首页路由：
|
||||
- `/`
|
||||
- `/login`
|
||||
- `/login/:username`
|
||||
- `/landing`
|
||||
- 404 路由（可留在 `App.tsx` 或交给新路由容器统一处理，二选一）
|
||||
|
||||
### 2）迁移出 `App.tsx` 的内容
|
||||
|
||||
将以下与工作台有关的路由从 `App.tsx` 抽离：
|
||||
|
||||
- `/workspace`（重定向）
|
||||
- `/workspace/chats`
|
||||
- `/workspace/chats/:thread_id`
|
||||
- `/workspace/agents`
|
||||
- `/workspace/agents/new`
|
||||
- `/workspace/agents/:agent_id/chats`（重定向）
|
||||
- `/workspace/agents/:agent_id/chats/:thread_id`
|
||||
- `/workspace/scheduled`
|
||||
- `/workspace/scheduled/tasks`
|
||||
- `/workspace/scheduled/runs/:run_id`
|
||||
|
||||
以及配套的包装组件职责：
|
||||
|
||||
- `WorkspaceLayout`
|
||||
- `ChatRuntime`
|
||||
|
||||
---
|
||||
|
||||
## 四、建议的新结构（方案）
|
||||
|
||||
## 方案 A（推荐）：新增“业务路由容器组件”
|
||||
|
||||
在 `pages` 下新增一个路由容器组件，例如：
|
||||
|
||||
- `src/pages/WorkspaceRoutes.tsx`（或 `src/pages/AppWorkspaceRoutes.tsx`）
|
||||
|
||||
职责：
|
||||
- 专门维护 `/workspace/*` 相关路由
|
||||
- 内部统一使用 `WorkspaceLayout` 与 `ChatRuntime`
|
||||
- 输出一个可被 `App.tsx` 挂载的路由节点
|
||||
|
||||
同时在 `App.tsx` 里只保留：
|
||||
- 登录/首页/404
|
||||
- 一个 `Route path="/workspace/*" element={<WorkspaceRoutes />} />`
|
||||
|
||||
---
|
||||
|
||||
## 五、“再建立一个页面放置导航”的落地解释
|
||||
|
||||
你说的“建立一个页面放置这些导航”，可以有两种理解：
|
||||
|
||||
1. **路由容器页（推荐）**：
|
||||
- 不强调视觉 UI，重点是集中管理导航与路由跳转规则。
|
||||
- 即上面的 `WorkspaceRoutes.tsx`。
|
||||
|
||||
2. **可见的导航页（可选）**：
|
||||
- 例如新建 `WorkspaceHomePage.tsx`，展示聊天/Agents/定时任务入口按钮。
|
||||
- 路由上把 `/workspace` 指向该页，而不是直接重定向到 `/workspace/chats/new`。
|
||||
|
||||
当前从你的描述看，优先建议第 1 种（先做结构整理），之后若有产品需求再做第 2 种可见导航页。
|
||||
|
||||
---
|
||||
|
||||
## 六、实施步骤（开发任务拆解）
|
||||
|
||||
1. 新建 `WorkspaceRoutes` 组件（`pages` 目录下）。
|
||||
2. 把所有 `/workspace/*` 路由从 `App.tsx` 搬入该组件。
|
||||
3. 把 `WorkspaceLayout` 与 `ChatRuntime` 移入该组件（或抽到共享 layout/runtime 文件）。
|
||||
4. 在 `App.tsx` 中保留登录/首页路由，并挂载 `/workspace/*` 到新组件。
|
||||
5. 校验以下访问路径行为一致：
|
||||
- `/workspace` 重定向
|
||||
- chats/agents/scheduled 各页面可正常进入
|
||||
- 动态参数路由（`thread_id`、`agent_id`、`run_id`）正常
|
||||
- 404 不受影响
|
||||
6. 运行前端并做手工回归。
|
||||
|
||||
---
|
||||
|
||||
## 七、验收标准
|
||||
|
||||
1. `App.tsx` 明显瘦身，主要负责顶层入口路由。
|
||||
2. `/workspace/*` 全部由新建组件统一管理。
|
||||
3. 功能行为与改造前一致（或符合新定义）。
|
||||
4. 代码可读性提升：登录入口与业务入口职责分离。
|
||||
|
||||
---
|
||||
|
||||
## 八、注意事项
|
||||
|
||||
1. 当前项目使用 `HashRouter`，路由写法需保持兼容。
|
||||
2. `Navigate` 重定向逻辑要完整迁移，避免出现死循环或空白页。
|
||||
3. `WorkspaceLayout` 与 `ChatRuntime` 的包裹层级不能错，否则可能影响侧边栏、输入区、子任务/Artifacts 状态。
|
||||
4. 若后续再加模块（例如 `/workspace/settings`），优先在 `WorkspaceRoutes` 中扩展。
|
||||
|
||||
---
|
||||
|
||||
## 九、建议的命名（可直接采用）
|
||||
|
||||
- 新增组件文件：`src/pages/WorkspaceRoutes.tsx`
|
||||
- （可选）可见导航页：`src/pages/WorkspaceHomePage.tsx`
|
||||
|
||||
---
|
||||
|
||||
## 十、后续可选优化
|
||||
|
||||
1. 将 `WorkspaceLayout` 抽到 `src/layouts/WorkspaceLayout.tsx`。
|
||||
2. 将 `ChatRuntime` 抽到 `src/runtime/ChatRuntime.tsx`。
|
||||
3. 把路由常量集中到 `src/core/router/paths.ts`，减少硬编码路径。
|
||||
@@ -1,14 +1,47 @@
|
||||
# 多智能体圆桌研讨 · 后端开发文档
|
||||
|
||||
本文档面向需要维护或扩展"多智能体圆桌研讨"功能后端的开发者。前端 API 速查请看 `multi-agent-api.md`,此文档关注**实现细节、设计取舍、性能特征**。
|
||||
本文档面向需要维护或扩展「多智能体圆桌研讨」功能后端的开发者。前端 API 速查见 `multi-agent-api.md`、`multi-agent-step1-api.md`、`multi-agent-step3-api.md`；推荐弹窗见 `recommend-agents-progress.md`；前端实现见 `multi-agent-frontend-dev.md`。本文关注**实现细节、协议帧、设计取舍**。
|
||||
|
||||
源码内另有中文模块级注释（`app/gateway/routers/intent.py`、`recommend.py`、`multi_agent.py` 及 `clarification_utils.py`），与本文互为补充。
|
||||
|
||||
---
|
||||
|
||||
## 1. 功能定位
|
||||
## 1. 功能定位与三步数据流
|
||||
|
||||
把"任务目标 + 用户约束"丢给一个**协调智能体**,由它通过 `agent_orchestration` 技能调度 6 个固定职能的子智能体（情报收集 / 环境评估 / 方案设计 / 风险审查 / 执行规划 / 总结陈述）协同产出方案,直到协调智能体认为信息足够、停止派活并输出最终结论为止。
|
||||
对应前端页面：`/page/roundtable/planning`（`RoundtablePlanningPage.tsx`）的三个步骤。
|
||||
|
||||
对应前端页面：`/page/roundtable/planning` 的 **Step 2 多智能体研讨**。
|
||||
```
|
||||
Step 1 任务意图理解
|
||||
POST /api/intent/init → 建 thread，绑定内置 roundtable-intent
|
||||
POST /api/intent/stream (多轮) → 澄清对话，终态 [INTENT_READY] + summary
|
||||
|
||||
↓ intentReady { objective, constraints, assumptions }
|
||||
|
||||
推荐弹窗（Step 1 → Step 2 之间，可选）
|
||||
POST /api/recommend/stream → 从候选池选 2–6 个席位，[RECOMMEND_READY] + picks
|
||||
|
||||
↓ selectedAgents[]
|
||||
|
||||
Step 2 多智能体圆桌研讨
|
||||
POST /api/multi-agent/init (SSE) → 协调智能体 + 各席位 thread（席位列表由前端传入）
|
||||
POST /api/multi-agent/run/stream → leader 派活 / special 执行 / 澄清
|
||||
|
||||
↓ lastLeaderContent、各席位交付、hasConsensus
|
||||
|
||||
Step 3 最终方案展示
|
||||
GET /api/threads/{tid}/artifacts → 列出 outputs/ 产出文件
|
||||
GET /api/threads/{tid}/artifacts/{path} → 预览或下载
|
||||
（总控结论、席位文本主要来自 Step 2 前端内存，一般不再调 run/stream）
|
||||
```
|
||||
|
||||
| 步骤 | 前端 `currentStep` | 专属 Router | 内置 Agent |
|
||||
|------|-------------------|-------------|------------|
|
||||
| 1 | 1 | `intent.py` | `roundtable-intent`（固定 id，复用） |
|
||||
| 1→2 | 推荐弹窗 | `recommend.py` | `roundtable-recommender`（每请求新建 thread） |
|
||||
| 2 | 2 | `multi_agent.py` | 协调智能体（每次新建）+ 用户选定的 `roundtable-*` 席位 |
|
||||
| 3 | 3 | `artifacts.py`（通用） | 无新 agent |
|
||||
|
||||
所有接口需 `Authorization: Bearer <JWT>`。Loopback 调用统一 `trust_env=False`，避免本机 `HTTP_PROXY` 把 `127.0.0.1` 指到不可达代理（症状：单次请求卡住 40s+）。
|
||||
|
||||
---
|
||||
|
||||
@@ -17,13 +50,16 @@
|
||||
```
|
||||
offline-backend-20260512/backend/
|
||||
├── app/gateway/
|
||||
│ ├── app.py # 注册 multi_agent.router
|
||||
│ ├── app.py # include_router: multi_agent, intent, recommend
|
||||
│ └── routers/
|
||||
│ └── multi_agent.py # 本功能唯一新增的 router
|
||||
│ ├── multi_agent.py # Step 2：init(SSE) + run/stream
|
||||
│ ├── intent.py # Step 1：init + stream
|
||||
│ ├── recommend.py # Step 1→2：推荐 stream
|
||||
│ └── artifacts.py # Step 3：列出/下载 thread 产出
|
||||
└── .deer-flow/agents/
|
||||
├── roundtable-intelligence/ # 6 个内置子智能体目录
|
||||
│ ├── config.yaml # ├── id / name / description
|
||||
│ └── SOUL.md # └── 角色 prompt
|
||||
├── roundtable-intent/ # Step 1 任务理解（SOUL 含完整工作流，可不挂 Skill）
|
||||
├── roundtable-recommender/ # 推荐智能体
|
||||
├── roundtable-intelligence/ # 默认可选席位（6 个，前端可替换）
|
||||
├── roundtable-environment/
|
||||
├── roundtable-solution-design/
|
||||
├── roundtable-risk-review/
|
||||
@@ -31,329 +67,371 @@ offline-backend-20260512/backend/
|
||||
└── roundtable-summary/
|
||||
```
|
||||
|
||||
**零代码改动构造内置 agent**：6 个目录通过既有的 `_sync_legacy_agents()`（`app/gateway/routers/agents.py`）在下次任意 `/api/agents` 请求时自动 upsert 进 `agents` 表,`user_id IS NULL` 标记为内置。
|
||||
**内置 agent 注册**：各 `roundtable-*` 目录通过 `_sync_legacy_agents()`（`app/gateway/routers/agents.py`）在下次 `/api/agents` 请求时 upsert 进 `agents` 表，`user_id IS NULL` 表示内置。
|
||||
|
||||
**共享工具逻辑**：`packages/harness/deerflow/tools/builtins/clarification_utils.py` 中的 `resolve_allow_multiple()` 被 `intent.py`、`multi_agent.py` 与 `ClarificationMiddleware` 共用，决定选项卡片默认单选还是多选。
|
||||
|
||||
---
|
||||
|
||||
## 3. 接口总览
|
||||
|
||||
路由前缀 `/api/multi-agent`，所有接口需要 `Authorization: Bearer <JWT>`。
|
||||
| 方法 | 路径 | 步骤 | 用途 |
|
||||
|------|------|------|------|
|
||||
| POST | `/api/intent/init` | 1 | 创建意图澄清 thread |
|
||||
| POST | `/api/intent/stream` | 1 | SSE，一轮用户对话 |
|
||||
| POST | `/api/recommend/stream` | 1→2 | SSE，一次性推荐席位 |
|
||||
| POST | `/api/multi-agent/init` | 2 | SSE，并行拉起席位 + 协调智能体 |
|
||||
| POST | `/api/multi-agent/run/stream` | 2 | SSE，leader 或 special 一轮 |
|
||||
| GET | `/api/threads/{thread_id}/artifacts` | 3 | 列出该 thread 的 outputs 文件 |
|
||||
| GET | `/api/threads/{thread_id}/artifacts/{path}` | 3 | 预览/下载单个产出 |
|
||||
|
||||
| 方法 | 路径 | 用途 |
|
||||
|---|---|---|
|
||||
| POST | `/api/multi-agent/init` | 一次性创建协调智能体 + 6 个子席位线程,返回 `thread_ids` 映射 |
|
||||
| POST | `/api/multi-agent/run/stream` | SSE 流式驱动一次 leader 或 special 调用 |
|
||||
|
||||
字段细节见 `multi-agent-api.md`,这里不重复。
|
||||
字段级请求/响应见各 step 的 API 文档；下文只写**后端实现语义**。
|
||||
|
||||
---
|
||||
|
||||
## 4. 内部实现详解
|
||||
## 4. Step 1：任务理解（`intent.py`）
|
||||
|
||||
### 4.1 `/init` 内部流程
|
||||
### 4.1 定位
|
||||
|
||||
```
|
||||
[阶段1] 并行准备 6 个子智能体席位 (asyncio.gather)
|
||||
├─ GET /api/agents/{id} × 6 → 取 name + description
|
||||
└─ POST /api/threads × 6 → 建新 thread
|
||||
轻量包装 Lead Agent 运行时，固定跑内置 `roundtable-intent`。不做 broadcast、不派活；每轮用户消息对应一次 `/stream`。
|
||||
|
||||
[阶段2] 创建协调智能体
|
||||
├─ POST /api/threads → 协调智能体的 thread
|
||||
└─ POST /api/agents (with model + skills=[agent_orchestration] + soul)
|
||||
└─ soul 里包含可调度的 6 个 agent_name + description 列表
|
||||
### 4.2 `POST /api/intent/init`
|
||||
|
||||
1. `_create_thread()` → LangGraph thread
|
||||
2. 返回固定 `agent_id: "roundtable-intent"`（**不**每次新建 agent）
|
||||
|
||||
与 Step 2 `/init` 的区别：无协调智能体、无 `agent_names` 列表。
|
||||
|
||||
### 4.3 `POST /api/intent/stream`
|
||||
|
||||
**上游**：`_run_payload(agent_name=roundtable-intent, excluded_tools=[...])`，硬排除 `agent_orchestration`、`write_file`、`web_search` 等，**仅保留** `ask_clarification` 等澄清能力，防止模型写方案文档。
|
||||
|
||||
**流式**：透传 LangGraph SSE → 解析 `_parse_last_messages(captured)`。
|
||||
|
||||
**终态帧判定顺序（重要）**：
|
||||
|
||||
1. **先**扫描全部 AI 消息中的 `[INTENT_READY]\n\`\`\`json {...}\`\`\``（正则 `_INTENT_READY_PATTERN`）
|
||||
- 命中 → `status: "done"`，`summary` 为解析后的 JSON，`content` 为含标记的整段文本
|
||||
- **优先于** `ask_clarification`，避免「已汇总仍被当成待澄清」
|
||||
|
||||
2. 否则查最后一则带 `tool_calls` 的 AIMessage 是否含 `ask_clarification`
|
||||
- 命中 → `status: "clarification"`，附带结构化字段供前端选项卡片：
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "clarification",
|
||||
"content": "<引导语/前言>",
|
||||
"question": "...",
|
||||
"clarification_type": "missing_info",
|
||||
"clarification_context": "...",
|
||||
"options": ["..."],
|
||||
"allow_custom": true,
|
||||
"allow_multiple": false,
|
||||
"summary": null
|
||||
}
|
||||
```
|
||||
|
||||
**协调智能体 SOUL 是动态拼出来的**(`multi_agent.py:216-224`):
|
||||
`allow_multiple` 由 `resolve_allow_multiple(cargs)` 决定：**默认单选**（点击即发送）；仅模型显式传 `allow_multiple: true` 时为多选。
|
||||
|
||||
```python
|
||||
soul = (
|
||||
"#核心定位：\n"
|
||||
"用途：根据用户的任务目标,调用其他智能体干活,只负责协调汇总,...\n"
|
||||
"#调度方法：\n"
|
||||
"通过使用agent_orchestration技能调用其他智能体干活,...\n"
|
||||
"#可调度智能体：\n"
|
||||
f"{descriptions}" # ← 6 个子席位的 name+description
|
||||
)
|
||||
3. 否则 → `status: "asking"`（继续对话，无结构化澄清）
|
||||
|
||||
**`summary` 形状**（`done` 时）：
|
||||
|
||||
```json
|
||||
{
|
||||
"objective": "一句话目标",
|
||||
"constraints": ["硬约束 1", "..."],
|
||||
"assumptions": ["可选假设"]
|
||||
}
|
||||
```
|
||||
|
||||
由于 `main_agent_name` 由前端每次新建（`roundtable-coordinator-{timestamp36}`）,所以协调智能体本身是一次性的、用完即弃。
|
||||
### 4.4 内置 Agent：`roundtable-intent`
|
||||
|
||||
### 4.2 `/run/stream` 内部流程
|
||||
- 配置：`.deer-flow/agents/roundtable-intent/config.yaml` + `SOUL.md`
|
||||
- SOUL 内写清：工作流、`ask_clarification` 用法、`[INTENT_READY]` 格式、禁止派活/写文件
|
||||
- **可不配置 `skills`**；若配置 Skill，SOUL 要求不得偏离澄清与结束协议
|
||||
|
||||
接收 `agent_type` 后走两条分支：
|
||||
---
|
||||
|
||||
#### `agent_type = "leader"` (协调智能体)
|
||||
## 5. 推荐智能体（`recommend.py`，Step 1 → 2）
|
||||
|
||||
### 5.1 定位
|
||||
|
||||
无状态单次调用：每次请求内部 `_create_thread()`，不暴露 `/init`。前端传入 Step 1 的 `intent` + 过滤后的 `candidates`（排除 `roundtable-intent`、`roundtable-recommender`、历史 `roundtable-coordinator-*`）。
|
||||
|
||||
### 5.2 `POST /api/recommend/stream`
|
||||
|
||||
**入参校验**：
|
||||
|
||||
- `intent.objective` 必填
|
||||
- `candidates` 非空，且至少一个有效 `agent_id`
|
||||
|
||||
**Prompt 拼装**（`_build_prompt`）：把 objective/constraints/assumptions 与候选池格式化为一条 user message。
|
||||
|
||||
**上游**：`roundtable-recommender`，`excluded_tools` 含 `ask_clarification`、`agent_orchestration` 等（纯判断，不调工具）。
|
||||
|
||||
**终态**：
|
||||
|
||||
- 解析 `[RECOMMEND_READY]\n\`\`\`json {"picks":[{"agent_id","reason"},...]}\`\`\``
|
||||
- `_validate_picks()`：只保留候选池内的 id、去重、数量 clamp 到 2–6
|
||||
- 有效 picks ≥ 2 → `status: "done"`，`picks` 有值
|
||||
- 否则 → `status: "asking"`（前端回退默认席位列表）
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "done",
|
||||
"content": "<自然语言推荐理由>",
|
||||
"picks": [{"agent_id": "roundtable-risk-review", "reason": "..."}]
|
||||
}
|
||||
```
|
||||
|
||||
**前端流式展示**：自然语言理由与 JSON 由 `[RECOMMEND_READY]` 分界；`TitleMiddleware` 产生的标题增量会在客户端过滤，避免污染推荐理由区。
|
||||
|
||||
---
|
||||
|
||||
## 6. Step 2：多智能体研讨（`multi_agent.py`）
|
||||
|
||||
### 6.1 `/init` 内部流程（SSE，非一次性 JSON）
|
||||
|
||||
当前实现为 **流式 init**，便于前端按席位点亮 UI：
|
||||
|
||||
```
|
||||
1. broadcast「总控收到用户消息」到所有非自己线程 (asyncio.gather)
|
||||
2. 拼 RunCreateRequest,转发到 POST /api/threads/{coordinator}/runs/stream
|
||||
asyncio.as_completed(各席位 _prepare_sub_agent)
|
||||
每完成一个 → data: {"event":"seat_ready","agent_name","thread_id","display_name","description"}
|
||||
|
||||
协调智能体：
|
||||
POST /api/threads → coord_thread
|
||||
POST /api/agents（skills=[agent_orchestration]，SOUL 动态拼入可调度列表）
|
||||
→ data: {"event":"coordinator_ready","main_agent_name","thread_id"}
|
||||
|
||||
→ data: {"event":"init_done","main_agent_name","thread_ids":{...}}
|
||||
失败 → data: {"event":"error","detail":"..."}
|
||||
```
|
||||
|
||||
**席位列表**：由前端 `agent_names` 传入（推荐弹窗确认后的 2–6 个 id），不再写死 6 个。
|
||||
|
||||
**协调智能体 SOUL**（动态拼接）包含：只负责协调汇总、通过 `agent_orchestration` 派活、`agent_name` 必须用英文 id（不要用中文显示名）。
|
||||
|
||||
### 6.2 `/run/stream` — `agent_type = "leader"`
|
||||
|
||||
```
|
||||
1. （可选）pre_broadcast：总控收到用户消息 → 广播到非自己的 thread
|
||||
2. POST /api/threads/{coordinator}/runs/stream
|
||||
- excluded_tools: ["web_search"]
|
||||
- context.model_name = 用户传的 model
|
||||
3. 流式透传 LangGraph 事件给前端
|
||||
4. 流结束后从最后一帧 values 取最末一条 message
|
||||
5. 解析 message.tool_calls (agent_orchestration 技能调用):
|
||||
- 用 _extract_name_task() 提取 [agent_name, task_text]
|
||||
- 对每个 [agent_name, task]:
|
||||
broadcast「总控给 X 派活,内容为: ...」到所有非派活双方
|
||||
6. 末尾追加状态帧:
|
||||
{
|
||||
"status": [["agent_name", "task"], ...], // 空数组 = 共识达成
|
||||
"content": "<leader 最终文本>",
|
||||
"agent_name": "<coordinator>"
|
||||
}
|
||||
3. 透传 LangGraph 事件
|
||||
4. 解析 messages → tool_calls
|
||||
|
||||
分支 A — ask_clarification：
|
||||
status: "clarification"
|
||||
+ question / options / allow_multiple / clarification_type / clarification_context
|
||||
（空 dispatched 不等于共识，前端展示澄清卡片并暂停自动派活循环）
|
||||
|
||||
分支 B — 有 agent_orchestration 派活：
|
||||
并发 _broadcast 派活消息到相关 thread
|
||||
status: [["sub_agent_id", "task_text"], ...]
|
||||
|
||||
分支 C — 无 tool_calls：
|
||||
status: [] // 共识达成，content 为总控最终文本
|
||||
```
|
||||
|
||||
#### `agent_type = "special"` (子智能体)
|
||||
### 6.3 `/run/stream` — `agent_type = "special"`
|
||||
|
||||
```
|
||||
1. 拼 RunCreateRequest,转发到 POST /api/threads/{sub_agent}/runs/stream
|
||||
- excluded_tools: ["web_search","ask_clarification","present_files","view_image"]
|
||||
2. 流式透传 LangGraph 事件
|
||||
3. 流结束后从最后一帧 values 取交付内容 (content)
|
||||
4. broadcast「子智能体 X 完成 Y 工作,交付内容为: ...」到所有非自己线程
|
||||
5. 末尾追加状态帧:
|
||||
{
|
||||
"status": "子智能体 X 完成 Y 工作",
|
||||
"content": "<交付内容>",
|
||||
"agent_name": "<sub agent>"
|
||||
}
|
||||
1. POST /api/threads/{sub}/runs/stream
|
||||
- excluded_tools: web_search, ask_clarification, present_files, view_image, agent_orchestration
|
||||
2. 透传 + 解析最后 AI 文本
|
||||
3. post_broadcast：子智能体完成交付 → 广播到非自己的 thread
|
||||
4. status: "<完成提示字符串>" 或业务自定义；content 为交付正文；agent_name 为子 agent id
|
||||
```
|
||||
|
||||
### 4.3 _broadcast 机制
|
||||
### 6.4 `_broadcast` 机制
|
||||
|
||||
```python
|
||||
async def _broadcast(client, base, headers, message, agent_threads, skip):
|
||||
targets = [tid for name, tid in agent_threads.items() if name not in skip]
|
||||
await asyncio.gather(*(_append_thread_message(...) for tid in targets))
|
||||
# 对每个 target: GET state → append human message → POST state
|
||||
```
|
||||
|
||||
`_append_thread_message` 对每个目标 thread:
|
||||
目的：各 thread 对话历史里保留「谁派活、谁交付」的群聊上下文。`skip` 通常含发起方与接收方，避免回声。
|
||||
|
||||
```
|
||||
GET /api/threads/{id}/state # 拿当前 messages 列表
|
||||
state.values.messages.append({"type":"human","content":...})
|
||||
POST /api/threads/{id}/state # 写回完整 state
|
||||
```
|
||||
### 6.5 终态帧协议（leader / special / clarification）
|
||||
|
||||
这是**为了让每个子线程的对话历史里都能看到全局上下文**（其他席位说了什么、协调智能体怎么派活的）。子智能体下次被调用时,模型自然能基于这份"群消息回放"做判断。
|
||||
前端 `streamMultiAgent` 用 `isFinalStatusFrame()` 识别：**同时存在 `status` 与 `content`**。
|
||||
|
||||
**关键不变量**:`skip` 列表通常包含发起方和接收方,避免发起方收到回声、接收方收到重复消息。
|
||||
| `status` 类型 | 含义 |
|
||||
|---------------|------|
|
||||
| `[["agent","task"],...]` | 派活列表；`[]` = 共识 |
|
||||
| `"clarification"` | 总控追问，需用户回复后再 leader |
|
||||
| `"子智能体 X 完成..."` | special 完成（字符串） |
|
||||
| `"error"` | 异常 |
|
||||
|
||||
与 Step 1 的 `clarification` 帧字段对齐（`question`、`options`、`allow_multiple` 等），便于复用选项卡片组件。
|
||||
|
||||
---
|
||||
|
||||
## 5. 6 个内置 agent SOUL 设计要点
|
||||
## 7. Step 3：产出文件（`artifacts.py`，通用 Thread API）
|
||||
|
||||
每个 `roundtable-*` 的 SOUL.md 遵循统一结构：
|
||||
Step 3 **没有** 单独的 `multi_agent` 路由；使用既有 artifacts 能力。
|
||||
|
||||
```
|
||||
# {席位名}
|
||||
### 7.1 `GET /api/threads/{thread_id}/artifacts`
|
||||
|
||||
## 角色定位
|
||||
你是"多智能体圆桌研讨"会议的 **{席位}** 席位。会议由"总控协调智能体"统一调度,
|
||||
你只在被派到任务时发言,不需要主动推动议程。
|
||||
|
||||
## 核心职责
|
||||
- ...具体职责...
|
||||
|
||||
## 输出风格
|
||||
- 每次发言以 {emoji} 开头
|
||||
- 第一句直接给结论
|
||||
- 不超过 4 句
|
||||
|
||||
## 边界
|
||||
- 只产出 {本席位输出}
|
||||
- 不替其他席位做 {其他席位输出}
|
||||
- 任务结束后停下,等待总控派下一个任务
|
||||
|
||||
## 示例输出
|
||||
> ...
|
||||
```
|
||||
|
||||
| 席位 | agent_id | emoji | 核心职责 |
|
||||
|---|---|---|---|
|
||||
| 情报收集 | `roundtable-intelligence` | 📢 | 同类案例 + 历史风险预警 |
|
||||
| 环境评估 | `roundtable-environment` | 🌍 | 硬件容量 + 量化承载力 |
|
||||
| 方案设计 | `roundtable-solution-design` | 📐 | 主备方案 + 关键路径 |
|
||||
| 风险审查 | `roundtable-risk-review` | ⚠️ | 合规红线 + 收敛建议 |
|
||||
| 执行规划 | `roundtable-execution-plan` | 📅 | 里程碑 + 资源排布 |
|
||||
| 总结陈述 | `roundtable-summary` | 🎤 | 归纳 + 冲突标记 + 盖印 |
|
||||
|
||||
**为什么不让子智能体自己调度**：所有 SOUL 都明文写了"只在被点到时发言,由总控协调智能体派活"。子智能体不装 `agent_orchestration` 技能。只有协调智能体装。这是单调度源,避免多智能体相互抢调度权造成的死循环。
|
||||
|
||||
---
|
||||
|
||||
## 6. 关键设计决策
|
||||
|
||||
### 6.1 为什么用 HTTP loopback 而不是内部函数调用
|
||||
|
||||
`multi_agent.py` 调用 `/api/threads`、`/api/agents`、`/api/threads/.../runs/stream` 都是用 `httpx` 走 `http://localhost:8001/...` 自身循环回来,而不是直接 `from app.gateway.services import ...`。
|
||||
|
||||
**好处**:
|
||||
- 自动复用 Gateway 的鉴权 + CSRF + permission 中间件,不用再手写
|
||||
- 复用既有路由的请求验证（Pydantic）和错误响应
|
||||
- `Authorization` 头透传,被调端自然知道是哪个用户在调
|
||||
|
||||
**代价**: 每次调用都有一次额外的 TCP+JWT 解析开销（~10-50ms）。但因为 init 已经做了并行优化（A）、broadcast 已经省掉（C）,目前总体耗时是可接受的。
|
||||
|
||||
如未来需要进一步优化,可改为直接调用 `app/gateway/services.py` 里的内部函数,绕过 HTTP 一层。
|
||||
|
||||
### 6.2 为什么协调智能体每次新建
|
||||
|
||||
前端在每次进入 step 2 时生成 `roundtable-coordinator-{Date.now().toString(36)}`,作为 `main_agent_name`。
|
||||
|
||||
**好处**:
|
||||
- 不同会话/不同用户/同一用户不同任务之间完全隔离
|
||||
- 协调智能体的对话历史就是本次研讨的全部上下文,不会被上次任务污染
|
||||
- SOUL 不会被"上次的可调度列表"覆盖（虽然现在 6 个席位是固定的）
|
||||
|
||||
**代价**: 每次都要在 `agents` 表插一行,`.deer-flow/agents/<id>/` 下生成新目录。长期会累积大量协调智能体目录,**未来需要清理脚本**（标记 description 以 "你是总控控制协调智能体" 开头的 agent 自动 GC）。
|
||||
|
||||
### 6.3 子智能体席位为什么固定 6 个
|
||||
|
||||
- 圆桌的 6 个角色定位是产品级强约束（情报/环境/方案/风险/执行/总结）
|
||||
- 写在后端 SOUL.md 一处维护,跟其他内置 agent 同等地位
|
||||
- 前端只需要把 6 个 hyphen-case 名作为 `agent_names` 传过来即可
|
||||
|
||||
如果后续要支持"用户自选席位",在前端加 mapping 面板让用户从 `GET /api/agents` 里挑,不动后端。
|
||||
|
||||
### 6.4 为什么 SSE 末尾还要追加一个 `{status:...}` 帧
|
||||
|
||||
LangGraph 原生 SSE 里没有"调度结果"这种语义,前端只能从最后一帧 values 里去翻 tool_calls。如果由前端解析,前后端协议会绑死 LangGraph 内部数据形状,迁移成本高。所以后端在流末尾追加一个**协议层的总结帧**:
|
||||
- 鉴权：`threads:read`，owner 校验
|
||||
- 扫描：`users/{user_id}/threads/{thread_id}/user-data/outputs/`（`collect_outputs_listing`）
|
||||
- 目录不存在 → `files: []`（非 404）
|
||||
|
||||
```json
|
||||
{
|
||||
"status": [["agent_name", "task"], ...] | "<完成提示>",
|
||||
"content": "<最终 AI 文本>",
|
||||
"agent_name": "<本轮 agent>"
|
||||
"thread_id": "...",
|
||||
"files": [
|
||||
{
|
||||
"path": "mnt/user-data/outputs/report.md",
|
||||
"name": "report.md",
|
||||
"size_bytes": 12480,
|
||||
"mime_type": "text/markdown",
|
||||
"modified_at": "2026-05-23T14:32:30.123Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
前端 `streamMultiAgent` helper 通过 `isFinalStatusFrame()` 识别该帧（必须同时有 `status` + `content` 键）,与其他 LangGraph 帧区分。
|
||||
前端 `listSessionArtifacts(threadId)` 封装此接口；Step 3 可对协调 thread 与各席位 thread 分别拉取，合并为下载清单。
|
||||
|
||||
### 7.2 `GET /api/threads/{thread_id}/artifacts/{path}`
|
||||
|
||||
- 虚拟路径前缀 `mnt/user-data/outputs/...`
|
||||
- 路径穿越防护；`download=true` 强制附件下载
|
||||
- HTML/XHTML/SVG 等 active content 始终按下载处理
|
||||
|
||||
**总控结论、各席位最终段落**：主要来自 Step 2 已缓存的 `lastLeaderContent`、`step2RoundtableDialogues`；无需为 Step 3 新增聚合接口（可选优化见 `multi-agent-step3-api.md` 中的 `sessions/summary` 草案）。
|
||||
|
||||
---
|
||||
|
||||
## 7. 性能特征
|
||||
## 8. 内置席位 SOUL 设计要点
|
||||
|
||||
### 7.1 已应用的优化
|
||||
每个 `roundtable-*`（除 intent / recommender）遵循统一结构：角色定位、核心职责、输出风格（emoji + 简短结论）、边界（只产出本席位、等总控派活）。
|
||||
|
||||
| ID | 优化 | 收益 |
|
||||
|---|---|---|
|
||||
| **A** | `/init` 阶段 1 并行化（`asyncio.gather`） | 阶段 1 从 2-4s 降到 0.3-0.7s |
|
||||
| **C** | 删除 `/init` 末尾的 intro 广播（SOUL 已含定位） | 阶段 3 整段消失,省 1-2s |
|
||||
| 席位 | agent_id | emoji | 核心职责 |
|
||||
|------|----------|-------|----------|
|
||||
| 情报收集 | `roundtable-intelligence` | 📢 | 同类案例 + 历史风险 |
|
||||
| 环境评估 | `roundtable-environment` | 🌍 | 硬件容量 + 承载力 |
|
||||
| 方案设计 | `roundtable-solution-design` | 📐 | 主备方案 + 关键路径 |
|
||||
| 风险审查 | `roundtable-risk-review` | ⚠️ | 合规红线 + 收敛建议 |
|
||||
| 执行规划 | `roundtable-execution-plan` | 📅 | 里程碑 + 资源 |
|
||||
| 总结陈述 | `roundtable-summary` | 🎤 | 归纳 + 冲突标记 |
|
||||
|
||||
应用前 `/init` 耗时 **3-8s**,应用后 **0.5-1.2s**。
|
||||
|
||||
### 7.2 仍然存在的开销点
|
||||
|
||||
| 调用 | 单次耗时 | 主因 |
|
||||
|---|---|---|
|
||||
| `GET /api/agents/{id}` | 50-300ms | 每次触发 `_sync_legacy_agents()` 扫整个 `.deer-flow/agents/` 目录(目前 30+ 项) |
|
||||
| `POST /api/threads` | 100-200ms | LangGraph thread 表插入 + 默认 state 初始化 |
|
||||
| `POST /api/agents` | 100-300ms | 文件系统写入 SOUL.md + config.yaml + agents 表 |
|
||||
| `GET/POST /state` | 50-150ms × 2 | checkpointer 读写 |
|
||||
| `POST /runs/stream` 启动 | 50-100ms | RunManager + StreamBridge 初始化 |
|
||||
| LLM 推理 | **数百毫秒~数十秒** | 取决于 model + 上下文长度 |
|
||||
|
||||
**LLM 推理才是绝对大头**,基础设施开销在十几个百分点以内。
|
||||
|
||||
### 7.3 未来可探索
|
||||
|
||||
- **B**(已识别未做): broadcast 跳过 GET-state,直接 POST 新建态。但 POST 需要构造完整的 state shape,改造成本不小。
|
||||
- **D**(已识别未做): loopback HTTP → 内部函数调用。代码改动大,但能省掉 ~20-30 次 HTTP 解析开销。
|
||||
子智能体**不**安装 `agent_orchestration`；仅协调智能体安装，保证单调度源。
|
||||
|
||||
---
|
||||
|
||||
## 8. 依赖与扩展点
|
||||
## 9. 关键设计决策
|
||||
|
||||
### 8.1 `agent_orchestration` 技能
|
||||
### 9.1 HTTP loopback
|
||||
|
||||
协调智能体强依赖此技能,SOUL 里硬编码:
|
||||
三个 router 均通过 `httpx` 调本机 Gateway（`127.0.0.1`），复用鉴权与 LangGraph 路由，代价是额外 HTTP 开销；init 已用 `asyncio.as_completed` 并行化席位准备。
|
||||
|
||||
```
|
||||
通过使用agent_orchestration技能调用其他智能体干活,使用技能时传入agent_name和需要做的活
|
||||
```
|
||||
### 9.2 协调智能体每次新建
|
||||
|
||||
技能的实际派活产物是一个形如 `python3 scripts/agent_orchestration.py "agent_name" "task"` 的 shell 调用文本,后端用正则提取：
|
||||
`main_agent_name` 形如 `roundtable-coordinator-{timestamp36}`，会话隔离；长期会累积 agent 目录，需后续 GC 策略。
|
||||
|
||||
```python
|
||||
_TOOL_CALL_PATTERN = re.compile(r'\.py\s+"([^"]*)"\s+"([^"]*)"')
|
||||
```
|
||||
### 9.3 澄清协议统一
|
||||
|
||||
**若该技能被删除/改名**,leader 流程会拿不到 `tool_calls`,直接走"无派活=共识达成"分支。注意 `skills/` 下必须保留此技能。
|
||||
Step 1 与 Step 2 leader 均通过 `ask_clarification` + 终态 `clarification` 帧驱动选项卡片；`[INTENT_READY]` / 派活列表 / `[]` 各自表示阶段结束语义，互不混用。
|
||||
|
||||
### 8.2 模型选择
|
||||
### 9.4 选项单选默认
|
||||
|
||||
前端通过 `GET /api/models` 拿到列表,在 `model` 字段传 `Model.name` (与 `config.yaml.models[].name` 对应)。
|
||||
`resolve_allow_multiple()`：**未传则 false**（单选、点击发送）；仅显式 `allow_multiple: true` 时多选。降低模型把 `missing_info` 全标成多选导致 UX 混乱的概率。
|
||||
|
||||
- `/init` 的 `model` 字段 → 协调智能体的默认模型 (写进 agents 配置)
|
||||
- `/run/stream` 的 `model` 字段 → 该次具体运行用什么模型 (写进 `context.model_name`)
|
||||
### 9.5 SSE 末尾状态帧
|
||||
|
||||
前端允许"逐席位覆盖模型",由前端在 special 调用时按 `agentConfigs[seat].model` 传入。后端不感知"席位"概念,只看到 `model` 字段。
|
||||
|
||||
### 8.3 自定义新席位
|
||||
|
||||
如果要加第 7 个席位（比如"成本测算"）:
|
||||
|
||||
1. `.deer-flow/agents/roundtable-cost/` 加 `config.yaml` + `SOUL.md`
|
||||
2. 前端 `RoundtablePlanningPage.tsx` 的 `ROUNDTABLE_ROLE_TEMPLATES` + `AGENT_NAME_TO_ROLE` 加映射
|
||||
3. 圆桌可视化（圆圈环形图）加一个气泡 + 头像
|
||||
|
||||
**后端代码完全不需要改**。
|
||||
LangGraph 原生流不含「派活结果 / 意图 summary / 推荐 picks」；各 router 在流末追加 JSON `data:` 帧，前端与 LangGraph 帧区分解析。
|
||||
|
||||
---
|
||||
|
||||
## 9. 故障排查
|
||||
## 10. 性能特征
|
||||
|
||||
| 阶段 | 已做优化 | 典型耗时 |
|
||||
|------|----------|----------|
|
||||
| Step 2 `/init` | 席位 `as_completed` + 去掉 intro 广播 | 约 0.5–1.2s（视席位数） |
|
||||
| LLM `/run/stream` | — | 数百 ms～数十秒（主因） |
|
||||
| Step 1/推荐 | 单 thread，无 broadcast | 与模型相关 |
|
||||
|
||||
仍存在的开销：`GET /api/agents/{id}` 触发 legacy sync 扫目录、`GET/POST /state` 广播等。未来可考虑 loopback 改内部函数调用（见原 B/D 优化项）。
|
||||
|
||||
---
|
||||
|
||||
## 11. 依赖与扩展点
|
||||
|
||||
### 11.1 `agent_orchestration` 技能
|
||||
|
||||
协调智能体派活依赖此技能；正则 `_TOOL_CALL_PATTERN` 从 tool 输出提取 `agent_name` 与 task。技能缺失时 leader 易变成「无 tool_calls → 空 status → 前端误判共识」。
|
||||
|
||||
### 11.2 模型
|
||||
|
||||
`model` 写入 run 的 `context.model_name`；前端可按席位覆盖 special 调用的模型。
|
||||
|
||||
### 11.3 新增席位
|
||||
|
||||
1. `.deer-flow/agents/roundtable-xxx/` 增加 `config.yaml` + `SOUL.md`
|
||||
2. 前端候选池 / 推荐逻辑纳入该 id
|
||||
3. Step 2 `agent_names` 传入即可 — **multi_agent 路由无需改**
|
||||
|
||||
### 11.4 新增 Step 1 工具
|
||||
|
||||
若需新工具，须同步修改 `intent.py` 的 `excluded_tools` 白名单逻辑（当前为黑名单，仅 `ask_clarification` 实际可用）。
|
||||
|
||||
---
|
||||
|
||||
## 12. 故障排查
|
||||
|
||||
| 现象 | 可能原因 | 排查 |
|
||||
|---|---|---|
|
||||
| `/init` 500 "create coordinator agent failed" | `agent_orchestration` 技能不存在 / config.yaml 写入失败 | 看后端日志 `multi_agent` logger;检查 `skills/` 目录 |
|
||||
| `/run/stream` 502 "upstream returned HTTP 4xx" | JWT 过期 / 转发到上游时鉴权挂了 | 前端检查 Authorization 头是否带上 |
|
||||
| leader 永远 `status: []` 立即结束 | 协调智能体没产生 `tool_calls`,直接给文本回答 | 协调智能体 SOUL 不够强、或模型不支持工具调用,换 model |
|
||||
| special 内容为空 | 子智能体被 `excluded_tools` 限制到无可用工具 / 模型无文本输出 | 看上游 `runs/stream` 的 values 帧 messages.last.content |
|
||||
| 进入 step 2 卡住转圈 | `/init` 超时或失败 | F12 Network 看 `/api/multi-agent/init` 状态码与响应体 |
|
||||
|------|----------|------|
|
||||
| Step 1 一直有澄清、无法进入 Step 2 | 未产出 `[INTENT_READY]` 或终态被 `clarification` 覆盖 | 看 SOUL、最后一帧 `status`；确认 intent 先扫 READY |
|
||||
| 选项全是多选 | 旧前端默认 `allow_multiple !== false` | 确认 `allow_multiple` 字段与 `resolve_allow_multiple` |
|
||||
| Step 2 init SSE `error` | 协调 agent 创建失败 / agent_orchestration 缺失 | Network + 后端 `multi_agent` 日志 |
|
||||
| leader 立即 `status: []` | 未调用 orchestration 技能 | 换模型或加强 SOUL |
|
||||
| 推荐 picks 为空 | 未输出 `[RECOMMEND_READY]` 或 picks 不在候选池 | 看 recommend 终态帧 |
|
||||
| Step 3 无文件 | 子 agent 未写 outputs | `GET .../artifacts` 对子 thread_id 逐个查 |
|
||||
|
||||
### 服务端日志关键字
|
||||
### 日志关键字
|
||||
|
||||
```bash
|
||||
# multi_agent 路由的日志
|
||||
grep "multi_agent" .runtime/logs/*.log
|
||||
|
||||
# 派活解析失败
|
||||
grep "intent stream" .runtime/logs/*.log
|
||||
grep "multi_agent\|multi-agent" .runtime/logs/*.log
|
||||
grep "recommend stream" .runtime/logs/*.log
|
||||
grep "dispatch failed" .runtime/logs/*.log
|
||||
|
||||
# 广播失败（通常无害）
|
||||
grep "update state .* failed" .runtime/logs/*.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 测试入口
|
||||
|
||||
后端目前没有针对本功能的单测。建议补：
|
||||
## 13. 测试建议
|
||||
|
||||
```
|
||||
backend/tests/test_multi_agent.py
|
||||
- test_init_creates_threads_for_all_subagents
|
||||
- test_init_creates_coordinator_with_orchestration_skill
|
||||
- test_init_returns_400_when_agent_names_empty
|
||||
- test_stream_leader_emits_status_frame_with_content
|
||||
- test_stream_special_emits_status_frame_with_content
|
||||
- test_extract_name_task_parses_orchestration_skill_output
|
||||
- test_broadcast_skips_listed_agents
|
||||
backend/tests/test_intent.py # init、INTENT_READY、clarification 优先级
|
||||
backend/tests/test_recommend.py # picks 校验、候选池过滤
|
||||
backend/tests/test_multi_agent.py # init SSE 事件、leader/special 终态、clarification
|
||||
```
|
||||
|
||||
可用 `httpx.MockTransport` 拦截 loopback 请求,不依赖真实 Gateway。
|
||||
可用 `httpx.MockTransport` 模拟 loopback，不依赖真实 Gateway。
|
||||
|
||||
---
|
||||
|
||||
## 11. 路径速查
|
||||
## 14. 路径速查
|
||||
|
||||
| 资源 | 路径 |
|
||||
|---|---|
|
||||
| 路由实现 | `offline-backend-20260512/backend/app/gateway/routers/multi_agent.py` |
|
||||
| 路由注册 | `offline-backend-20260512/backend/app/gateway/app.py`(`include_router(multi_agent.router)`) |
|
||||
| 6 个内置 agent | `offline-backend-20260512/backend/.deer-flow/agents/roundtable-*/` |
|
||||
| `agent_orchestration` 技能定义 | `skills/public/agent_orchestration/`(若存在) |
|
||||
| 前端 API helper | `frontend-web/src/roundtable-planning/api/multi-agent.ts` |
|
||||
|------|------|
|
||||
| Step 1 路由 | `offline-backend-20260512/backend/app/gateway/routers/intent.py` |
|
||||
| 推荐路由 | `offline-backend-20260512/backend/app/gateway/routers/recommend.py` |
|
||||
| Step 2 路由 | `offline-backend-20260512/backend/app/gateway/routers/multi_agent.py` |
|
||||
| Step 3 列出/下载 | `offline-backend-20260512/backend/app/gateway/routers/artifacts.py` |
|
||||
| 路由注册 | `offline-backend-20260512/backend/app/gateway/app.py` |
|
||||
| 澄清单选/多选 | `packages/harness/deerflow/tools/builtins/clarification_utils.py` |
|
||||
| 任务理解 Agent | `.deer-flow/agents/roundtable-intent/` |
|
||||
| 推荐 Agent | `.deer-flow/agents/roundtable-recommender/` |
|
||||
| 圆桌席位 | `.deer-flow/agents/roundtable-*/` |
|
||||
| 前端 Step 1 API | `frontend-web/src/roundtable-planning/api/intent.ts` |
|
||||
| 前端推荐 API | `frontend-web/src/roundtable-planning/api/recommend.ts` |
|
||||
| 前端 Step 2 API | `frontend-web/src/roundtable-planning/api/multi-agent.ts` |
|
||||
| 前端页面 | `frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx` |
|
||||
| 前端 API 速查 | `frontend-web/docs/multi-agent-api.md` |
|
||||
| API 速查 | `frontend-web/docs/multi-agent-api.md` |
|
||||
| Step 1 API 说明 | `frontend-web/docs/multi-agent-step1-api.md` |
|
||||
| Step 3 API 说明 | `frontend-web/docs/multi-agent-step3-api.md` |
|
||||
@@ -0,0 +1,659 @@
|
||||
# 多智能体圆桌研讨 · 前端开发文档
|
||||
|
||||
本文档面向维护 `frontend-web` 圆桌规划功能的开发者。后端实现见 `multi-agent-backend-dev.md`；HTTP 字段速查见 `multi-agent-api.md`；推荐弹窗专项进度见 `recommend-agents-progress.md`（若不存在则为待补文件）。
|
||||
|
||||
> ⚠️ 历史版本曾引用 `multi-agent-step1-api.md`、`multi-agent-step3-api.md`，当前仓库未提供这两份文件；Step 1（intent）/ Step 3（artifacts）的接口签名直接参考本页第 4 节即可。
|
||||
|
||||
---
|
||||
|
||||
## 0. 速读：你需要先知道的事
|
||||
|
||||
- **整页只有一个文件**：`RoundtablePlanningPage.tsx`（≈ 3 621 行）。三步 UI 通过 `currentStep ∈ {1,2,3}` 切换，不使用 React Router 子路由。
|
||||
- **不使用 LangGraph SDK**：所有 API 都是自研的 `apiFetch` + `ReadableStream` SSE 解析（见 `api/intent.ts`、`api/recommend.ts`、`api/multi-agent.ts`）。
|
||||
- **唯一默认模型**：`DEFAULT_MODEL = "deepseek-chat"`（页面常量，写在 `RoundtablePlanningPage.tsx`）。`useModels()` 只用于 Persona 抽屉的下拉选项。
|
||||
- **席位区间硬约束**：推荐弹窗要求 **2 ≤ 选中数 ≤ 8**（`MIN_SELECTED` / `MAX_SELECTED`）。
|
||||
- **总控编排循环上限**：`MAX_CYCLES = 8`，超出后强制停止并 toast。
|
||||
- **席位派活策略**：**顺序**（不是并行）。旧实现并行触发多路 SSE 会让浏览器卡顿，现已改为顺序。
|
||||
- **调试开关**：`window.__MULTI_AGENT_INIT_TIMING__` 与 `window.__MULTI_AGENT_DEBUG__`（**不是** `__MULTI_AGENT_STREAM_DEBUG__`，文档历史版本有误）。
|
||||
|
||||
---
|
||||
|
||||
## 1. 功能定位
|
||||
|
||||
**页面路由**：`/page/workspace/roundtable/planning`（侧栏「圆桌规划」）
|
||||
|
||||
**入口组件**：`src/roundtable-planning/pages/RoundtablePlanningPage.tsx`
|
||||
|
||||
**核心能力**：
|
||||
|
||||
| 步骤 | 用户目标 | 真实后端对接 |
|
||||
|------|----------|--------------|
|
||||
| 1 | 与「任务理解智能体」多轮澄清，得到结构化意图 | `intent.ts` |
|
||||
| 1→2 | 从候选池选 2–8 个研讨席位 | `recommend.ts` + `RecommendAgentsDialog` |
|
||||
| 2 | 总控派活、子智能体顺序交付、可澄清/挂起 | `multi-agent.ts` + 编排循环 |
|
||||
| 3 | 查看总控结论、席位交付、产出文件下载 | `HighFidelityReport` + `listSessionArtifacts` |
|
||||
|
||||
**步骤门禁**：
|
||||
|
||||
- **Step 2**：`intentReady` 非空才可点击（顶栏按钮禁用 + toast 提示）。
|
||||
- **Step 3**：`hasConsensus === true` 才可点击。Leader 派活返回空数组才会自然收敛触发 `hasConsensus`，手动跳转的「达成共识生成全案成果」按钮也会校验。
|
||||
|
||||
---
|
||||
|
||||
## 2. 目录结构
|
||||
|
||||
```
|
||||
frontend-web/src/roundtable-planning/
|
||||
├── index.ts # 导出 RoundtablePlanningPage、HighFidelityReport
|
||||
├── pages/
|
||||
│ └── RoundtablePlanningPage.tsx # 三步主页面 + 状态机 + 编排循环（≈3600 行）
|
||||
├── api/
|
||||
│ ├── intent.ts # Step 1：initIntent、streamIntent
|
||||
│ ├── recommend.ts # 推荐：streamRecommend、filterRecommendCandidates、parseRecommendStreamContent
|
||||
│ └── multi-agent.ts # Step 2/3：initMultiAgent、streamMultiAgent、listSessionArtifacts、buildArtifactDownloadUrl
|
||||
├── components/
|
||||
│ ├── IntentClarificationCard.tsx # Step 1 选项卡片（单选/多选）+ formatIntentClarificationAnswer
|
||||
│ ├── RecommendAgentsDialog.tsx # Step 1→2 推荐弹窗（含流式 rationale + 候选筛选）
|
||||
│ ├── HighFidelityReport.tsx # Step 3 报告 + 文件清单
|
||||
│ ├── ArtifactPreviewModal.tsx # Markdown/纯文本/JSON/CSV/YAML 等文本类文件 in-app 预览
|
||||
│ └── ScrollToBottomButton.tsx # 对话区「回到底部」浮动按钮
|
||||
├── hooks/
|
||||
│ └── useAutoScroll.ts # 滚动跟随 + 用户上滑暂停跟随
|
||||
├── lib/
|
||||
│ └── clarification.ts # resolveAllowMultiple（单选/多选解析），与主聊天 ClarificationCard 对齐
|
||||
├── utils/
|
||||
│ └── drafts.ts # localStorage 草稿存档（list / upsert / get / delete / rename / deriveName）
|
||||
└── styles/
|
||||
└── roundtable-planning.css # 页面主题变量（浅红品牌色 + 深色覆盖）
|
||||
```
|
||||
|
||||
**路由注册**（`src/pages/WorkspaceRoutes.tsx`）：
|
||||
|
||||
```tsx
|
||||
<Route path="roundtable/planning" element={<WorkspaceLayout><RoundtablePlanningPage /></WorkspaceLayout>} />
|
||||
```
|
||||
|
||||
侧栏入口：`src/components/page-sidebar.tsx` → `/page/roundtable/planning`。
|
||||
|
||||
**环境变量**（由 `scripts/start-frontend.sh` 注入）：
|
||||
|
||||
- `VITE_BACKEND_BASE_URL` → `getBackendBaseURL()`，所有 API 前缀
|
||||
- `VITE_LANGGRAPH_BASE_URL` → 本功能**不**直接用 LangGraph SDK，全部走 Gateway 封装
|
||||
|
||||
---
|
||||
|
||||
## 3. 三步数据流（前端视角）
|
||||
|
||||
```
|
||||
[进入 Step 1]
|
||||
useEffect → runStep1Init()
|
||||
initIntent(model) → { agent_id, thread_id }
|
||||
setIntentThreadId、setTimelineEntries
|
||||
interactiveMessages seed 欢迎语（本地 seed，非 API）
|
||||
|
||||
[用户发送 / 选项卡片提交]
|
||||
sendIntentMessage(text)
|
||||
追加 user 气泡 + agent 占位（streaming + phase）
|
||||
streamIntent({ onTextDelta, onPhaseChange, signal })
|
||||
终态：
|
||||
done + summary → setIntentReady，解锁 Step 2 / 推荐弹窗
|
||||
clarification → IntentClarificationCard + pendingIntentClarificationMsgId
|
||||
asking → 继续对话
|
||||
error → toast + 红色 (错误) 文案
|
||||
|
||||
[点击「进入多智能体研讨」且 intentReady]
|
||||
setIsRecommendDialogOpen(true)
|
||||
RecommendAgentsDialog
|
||||
listAgents() → filterRecommendCandidates()
|
||||
streamRecommend({ onRationaleUpdate, onPicksUpdate, onPhaseChange })
|
||||
用户勾选 2–8 个 → onConfirm(agentIds)
|
||||
handleConfirmAgents
|
||||
setSelectedAgents(agentIds.map(...))
|
||||
step2InitRef.current = false // 复位 Step 2 init 闸门
|
||||
setCurrentStep(2)
|
||||
|
||||
[进入 Step 2]
|
||||
useEffect（step2InitRef 闸门）→ initMultiAgent(SSE)
|
||||
onSeatReady：右侧席位面板逐个「在线」
|
||||
onCoordinatorReady / init_done → threadIds + coordinatorName
|
||||
runOrchestration(buildInitialIntent(), threadIds, coordinatorName)
|
||||
while !cancelled && cycles<8:
|
||||
leader stream → 若 clarification：暂停循环，展示 Step 2 底部澄清条
|
||||
否则 dispatched[] → **顺序** streamMultiAgent(special) → 再 leader 综合…
|
||||
dispatched.length === 0 → hasConsensus = true，可进 Step 3
|
||||
|
||||
[进入 Step 3]
|
||||
HighFidelityReport
|
||||
consensusText ← lastLeaderContent
|
||||
seatDeliveries ← step2RoundtableDialogues.filter(d => d.confidence === "子智能体交付")
|
||||
Object.entries(threadIds).filter(name !== coordinatorName).map → listSessionArtifacts(threadId)
|
||||
文本类文件 → ArtifactPreviewModal；其它 → window.open(downloadUrl)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. API 层
|
||||
|
||||
### 4.1 `api/intent.ts` — Step 1
|
||||
|
||||
| 函数 | 说明 |
|
||||
|------|------|
|
||||
| `initIntent(model?)` | `POST /api/intent/init` → `{ status, agent_id, thread_id }` |
|
||||
| `streamIntent(req)` | `POST /api/intent/stream`，读 SSE 至终态帧 |
|
||||
|
||||
**`StreamIntentRequest` 重要字段**：
|
||||
|
||||
- `threadId`：必填，跨多轮对话保持
|
||||
- `signal`：必填（页面通过 `intentAborterRef` 控制暂停 / 切步取消）
|
||||
- `onTextDelta(text, messageId)`：每个 AI 文本增量
|
||||
- `onPhaseChange(phase, toolName?)`：`connecting → connected → streaming|tool_calling`
|
||||
|
||||
**`StreamIntentResult`**：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `status` | `"asking" \| "clarification" \| "done" \| "error"` | 终态分支 |
|
||||
| `content` | `string` | 完整 AI 文本（含 `[INTENT_READY]` 块） |
|
||||
| `summary` | `IntentSummary \| null` | 仅 `done` 有；前端 fallback 也会从 `content` 里用 `splitIntentReadyBlock` 解 |
|
||||
| `clarification` | `ClarificationPayload \| null` | 仅 `clarification` 有 |
|
||||
|
||||
**SSE 解析要点**：
|
||||
|
||||
- `event: metadata` → phase `connected`
|
||||
- `event: messages` + `extractAiTextDelta` → `onTextDelta`
|
||||
- tool call 帧（`tool_calls` / `tool_call_chunks` 非空）→ phase `tool_calling`（含 `ask_clarification` 工具名）
|
||||
- 终态帧识别：`isFinalIntentFrame`（必须有 `status` + `content`）
|
||||
|
||||
**Abort 行为**：
|
||||
|
||||
- `sendIntentMessage` 内建 `AbortController`，保存到 `intentAborterRef`
|
||||
- `stopIntentStream()` 用于「暂停」按钮、`currentStep !== 1` 自动调用、`handleStartNewTask`、`handleLoadDraft`
|
||||
- 触发 AbortError 时不当作错误：在气泡尾部追加「(已暂停)」并 toast「⏸️ 已暂停任务理解回复」
|
||||
|
||||
### 4.2 `api/recommend.ts` — 推荐弹窗
|
||||
|
||||
| 函数 | 说明 |
|
||||
|------|------|
|
||||
| `filterRecommendCandidates(agents)` | 从 `GET /api/agents` 结果剔除 intent / recommender / `roundtable-coordinator-*` |
|
||||
| `streamRecommend(req)` | `POST /api/recommend/stream`，无 init（一次性、无状态） |
|
||||
| `parseRecommendStreamContent(raw)` | 将累计文本拆成 `{ rationale, picks[] }`，供边流边渲染 |
|
||||
|
||||
**`EXCLUDED_AGENT_IDS`** 内置常量（仅 `recommend.ts` 内可见）：
|
||||
|
||||
- `roundtable-intent`
|
||||
- `roundtable-recommender`
|
||||
- 任何以 `roundtable-coordinator-` 开头的 agent_id（动态创建的协调器壳）
|
||||
|
||||
**流式 UI 拆分**（与主聊天的 `[RECOMMEND_READY]` 分界类似）：
|
||||
|
||||
- 标记常量：`RECOMMEND_READY_MARKER = "[RECOMMEND_READY]"`
|
||||
- `parseRecommendStreamContent(raw)`：用 `PICK_OBJECT_PATTERN` 正则增量匹配出已完成的 `{agent_id, reason}` 对象
|
||||
- `onRationaleUpdate`：仅 marker 之前的自然语言（弹窗顶部展示）
|
||||
- `onPicksUpdate`：从部分 JSON 增量解析 `picks[]`（卡片边流边出，过滤已见 id）
|
||||
- 过滤 `TitleMiddleware` 产生的标题增量（`langgraph_node` 含 `TitleMiddleware` 或 `tags` 含 `middleware:title`）
|
||||
|
||||
**终态语义**：
|
||||
|
||||
- `status === "done"` 且 `picks.length >= 2` → 弹窗用 picks 作为默认勾选
|
||||
- 否则 → `phase: "fallback"`，使用 `FALLBACK_AGENT_IDS`（6 个内置 roundtable-* 席位）与候选池交集
|
||||
|
||||
### 4.3 `api/multi-agent.ts` — Step 2 & Step 3 文件
|
||||
|
||||
| 函数 | 说明 |
|
||||
|------|------|
|
||||
| `initMultiAgent(payload)` | SSE：`seat_ready`(N 次) → `coordinator_ready` → `init_done` |
|
||||
| `streamMultiAgent(req)` | leader / special 一轮 |
|
||||
| `listSessionArtifacts(threadId)` | `GET /api/threads/{id}/artifacts` |
|
||||
| `buildArtifactDownloadUrl(threadId, virtualPath, { download? })` | 预览或附件下载 URL |
|
||||
|
||||
**`initMultiAgent` 事件**（`data:` JSON 的 `event` 字段）：
|
||||
|
||||
```ts
|
||||
{ event: "seat_ready", agent_name, thread_id, display_name, description }
|
||||
{ event: "coordinator_ready", main_agent_name, thread_id }
|
||||
{ event: "init_done", main_agent_name, thread_ids } // thread_ids: Record<agent_name, thread_id>
|
||||
{ event: "error", detail }
|
||||
```
|
||||
|
||||
**`streamMultiAgent` 终态**（`isFinalStatusFrame`）：
|
||||
|
||||
| `status` | 含义 | 前端处理 |
|
||||
|----------|------|----------|
|
||||
| `[["agent","task"], ...]` | 派活列表（数组形态） | **顺序**触发 special；最终用 `nextLeaderTask` 综合 |
|
||||
| `[]` | 共识达成（空数组） | `hasConsensus = true`，跳出循环 |
|
||||
| `"clarification"` | 总控追问 | `setPendingClarification`，暂停循环 |
|
||||
| `"子智能体 X 完成..."` | special 完成 | 更新对应对话气泡 confidence |
|
||||
| `"error"` | 失败 | toast + 红色气泡 |
|
||||
|
||||
**为什么 special 是顺序而不是并行**：旧版并行触发多路 SSE，每路都在 token 级别对 `step2RoundtableDialogues` 整表 setState，N 个并行 stream 让浏览器卡顿明显。改为顺序后同一时刻只有一个 SSE 在跑，UX 平滑很多（详见 `RoundtablePlanningPage.tsx` 编排循环里的注释）。
|
||||
|
||||
**`buildArtifactDownloadUrl` 路径编码**：将 `virtualPath` 按 `/` 切段后逐段 `encodeURIComponent` 再拼回，避免文件名里的中文 / 空格触发后端 404；`download=true` 加在 query string 上而非 path。
|
||||
|
||||
**调试开关**：
|
||||
|
||||
```js
|
||||
window.__MULTI_AGENT_INIT_TIMING__ = true; // 默认开启；init 各阶段耗时（fetch.start / first-byte / seat_ready#n / coordinator_ready / init_done / total）
|
||||
window.__MULTI_AGENT_DEBUG__ = true; // 默认开启；stream 帧计数 + lastEvent + bad JSON 提示，前缀 [stream:<agentType>:<agentName>]
|
||||
```
|
||||
|
||||
> ⚠️ 文档历史版本曾写作 `__MULTI_AGENT_STREAM_DEBUG__`，**实际代码并不识别**这个名字。
|
||||
|
||||
---
|
||||
|
||||
## 5. 主页面状态（`RoundtablePlanningPage`）
|
||||
|
||||
### 5.1 步骤与门禁
|
||||
|
||||
- `currentStep`: `1 | 2 | 3`
|
||||
- **Step 2 锁定**：`intentReady == null` 时顶栏 Step 2 按钮禁用（visual + `aria-disabled`），同时点击「进入多智能体研讨」会 toast 「⚠️ 请先与任务理解智能体完成澄清…」
|
||||
- **Step 3**：`hasConsensus === false` 时顶栏 Step 3 与底部「达成共识生成全案成果」按钮均禁用
|
||||
|
||||
### 5.2 Step 1 关键 state
|
||||
|
||||
| 状态 | 用途 |
|
||||
|------|------|
|
||||
| `intentThreadId` | `/api/intent/init` 返回的线程 id；未就绪前发送按钮置灰 |
|
||||
| `intentReady` | `IntentSummary`，驱动 Step 2 初始 prompt + 右侧摘要面板 + 顶栏 step2 解锁 |
|
||||
| `interactiveMessages` | 问答气泡列表（user / agent，含 streaming/phase/clarification 元数据） |
|
||||
| `pendingIntentClarificationMsgId` | 当前可操作的 agent 消息 id（保证只有最新一条 clarification 展示可点卡片） |
|
||||
| `intentClarificationSelections` | `Map<msgId, {selectedIds, custom}>`，多选 / 多消息时各自维护 |
|
||||
| `isIntentSending` | 发送中（屏蔽双发 / 显示「暂停」按钮） |
|
||||
| `intentAborterRef` | 当前 stream 的 AbortController |
|
||||
| `intentInitError` | init 失败信息；驱动右侧角色面板「异常」状态与红色提示 |
|
||||
| `step1InitRef` | 闸门：true 即认为已 init 过 |
|
||||
| `step1InitGenRef` | **单调递增**的代数标记，详见下文 |
|
||||
| `timelineEntries` | 右侧「澄清记录」时间线（init / user 反馈 / 任务意图已明确） |
|
||||
|
||||
**`step1InitGenRef` 的存在原因**：
|
||||
|
||||
React 18 StrictMode 开发环境下，effect 会 mount → cleanup → mount 两次。早期实现用闭包 `cancelled` 标志做防抖，结果是：第二次 mount 因 `step1InitRef.current === true` 早返回，但第一次 mount 的 async 仍未完成；当它最终 resolve 时，`cancelled` 已被 cleanup 置 true，因此 `setIntentThreadId` 被跳过，右栏卡在「正在上线」。改为单调代数后：每次 `runStep1Init` 自增 `step1InitGenRef`；async 完成时检查 `myGen === step1InitGenRef.current`，等价于「我是当前最新一次 init」，否则丢弃结果。这也覆盖了「新建任务 / 加载草稿期间旧 init 晚归」的场景。
|
||||
|
||||
**`splitIntentReadyBlock(text)`**（页面内工具函数，使用 `INTENT_READY_RE` 正则）：
|
||||
|
||||
- 从气泡正文解析 `[INTENT_READY]\n```json\n{...}\n``` ` 块
|
||||
- 返回 `{ before, summary, after }`，前后文与结构化卡片分别渲染
|
||||
- 单独的 `useEffect` 监听 `interactiveMessages`：若已存在含 `[INTENT_READY]` 的 agent 消息但 `intentReady` 仍为 null（极少数终态帧丢 summary 的场景），主动 `setIntentReady`，与后端 "READY 优先" 对齐
|
||||
|
||||
### 5.3 推荐与 Step 2 席位
|
||||
|
||||
| 状态 | 用途 |
|
||||
|------|------|
|
||||
| `selectedAgents` | `{ agent_id, name }[]`，默认 `DEFAULT_SELECTED_AGENTS`（6 内置） |
|
||||
| `roleTemplates` / `roles` | 右侧席位面板（`buildRoleTemplates`，commander 占 id=1，agents 从 id=2 开始） |
|
||||
| `agentNameToRole` | 流式输出时根据 `agent_name`（小写）反查 speakerId、avatarType、displayName |
|
||||
| `roundtableAgentIds` | `selectedAgents.map(a => a.agent_id)`，传给 `/api/multi-agent/init` 的 `agent_names` |
|
||||
| `threadIds` / `coordinatorName` | `/api/multi-agent/init` 结果；离开 Step 2 **不**清空，允许回来继续看 |
|
||||
| `step2RoundtableDialogues` | Step 2 对话流（含 `streaming` / `confidence` / `time` / `avatarType`） |
|
||||
| `lastLeaderContent` / `hasConsensus` | Step 3 总控结论 + 共识标记 |
|
||||
| `pendingClarification` | Step 2 总控澄清（复用 `ClarificationPayload`） |
|
||||
| `clarificationDraft` | 底部自定义回答输入框（受 `allowCustom` 控制） |
|
||||
| `isRoundTableRunning` | 用户挂起 / 恢复协商的 UI 开关 |
|
||||
| `isOrchestrating` | 编排循环正在 run（屏蔽并发触发） |
|
||||
| `orchestrationCancelRef` | 与 `abortAllInFlight` 配合中断当前循环 |
|
||||
| `activeAbortersRef` | 当前 Step 2 所有 in-flight stream 的 AbortController 集合 |
|
||||
| `activeSpeakerId` / `activeSpeakerSet` | 圆桌可视化高亮：单 leader 时用单值，多席位并行时用 Set |
|
||||
| `selectedAgentId` | 当前 Persona 抽屉所在的席位 id（点击圆桌头像打开） |
|
||||
| `agentConfigs` | `Map<seatId, {model, weight, prompt, temp}>` Persona 覆盖；下一轮该席位的派活会用此 model |
|
||||
| `isUpperPanelCollapsed` | 是否折叠圆桌可视化 + 调控台，给对话区让出垂直空间 |
|
||||
|
||||
**协调智能体命名**：`roundtable-coordinator-${Date.now().toString(36)}`，每次 Step 2 会话新建。后端把这类壳 agent 留在 DB 中，因此 `filterRecommendCandidates` 默认过滤掉。
|
||||
|
||||
### 5.4 编排循环 `runOrchestration(seedMessage, ids, coord)`
|
||||
|
||||
伪代码：
|
||||
|
||||
```
|
||||
isOrchestrating = true
|
||||
orchestrationCancelRef = false
|
||||
nextLeaderTask = seedMessage
|
||||
cycles = 0
|
||||
MAX_CYCLES = 8
|
||||
|
||||
while !cancelled && cycles < MAX_CYCLES:
|
||||
cycles += 1
|
||||
highlight(speakerId=2) // 总控
|
||||
leaderBubble = appendStreamingDialogue("总控协调", confidence: "调度中")
|
||||
res = streamMultiAgent(leader, ids, coord, nextLeaderTask, onTextDelta, onPhaseChange)
|
||||
|
||||
if res.clarification:
|
||||
finalize(leaderBubble, content, "等待用户澄清")
|
||||
setPendingClarification(res.clarification)
|
||||
break // 等用户回复后由 submitClarification 重启循环
|
||||
|
||||
finalize(leaderBubble, content, dispatched.length === 0 ? "全案盖印" : "派活说明")
|
||||
if res.content: setLastLeaderContent(res.content)
|
||||
|
||||
if res.dispatched.length === 0:
|
||||
setHasConsensus(true); setConsensusPercentage(100); break
|
||||
|
||||
for [subName, task] of res.dispatched: // **顺序**，不是并行
|
||||
meta = agentNameToRole[subName.toLowerCase()]
|
||||
markSpeakerStreaming(meta.speakerId)
|
||||
perSeatModel = agentConfigs[meta.speakerId]?.model || DEFAULT_MODEL
|
||||
subBubble = appendStreamingDialogue(meta.displayName, confidence: "调度中")
|
||||
specRes = streamMultiAgent(special, ..., perSeatModel, signal=subAborter)
|
||||
finalize(subBubble, specRes.content, "子智能体交付")
|
||||
markSpeakerIdle(meta.speakerId)
|
||||
if cancelled: break
|
||||
|
||||
setConsensusPercentage(prev => min(95, prev + 8))
|
||||
nextLeaderTask = "各子智能体已就上一轮派活完成交付,请你结合最新结论..."
|
||||
|
||||
if cycles >= MAX_CYCLES:
|
||||
toast("⏱️ 已达到最大研讨轮次,自动停止以避免循环")
|
||||
|
||||
clearAllStreamingSpeakers()
|
||||
isOrchestrating = false
|
||||
```
|
||||
|
||||
要点：
|
||||
|
||||
- **`buildInitialIntent()`**：
|
||||
- 有 `intentReady` → 拼装 `objective / 约束条件 / 关键假设` + 「不要再反问用户」终结语
|
||||
- 无 `intentReady`（用户跳过澄清 / 顶栏直接切到 Step 2）→ 拼接 Step 1 内 `interactiveMessages` 里 sender==='user' 的内容，逐行 `用户#N: ...`，**绝不**注入 mock 的「预算 500 万 / 72 小时」数字
|
||||
- 用户输入完全为空 → 让总控先调用 `ask_clarification` 而不是凭空派活
|
||||
- **用户「干预研审」**：`handleInjectToRoundtable` 追加一个「💡 (人工指令介入) ...」气泡，然后构造 `runOrchestration("用户人工干预新指令:...", ...)`
|
||||
- **挂起 / 恢复**：
|
||||
- 挂起 = `setIsRoundTableRunning(false)` → `stopOrchestration()` → `orchestrationCancelRef = true` + `abortAllInFlight()`
|
||||
- 恢复 = `setIsRoundTableRunning(true)`，effect 触发 `runOrchestration("用户已恢复研讨,请继续上一轮的协调工作。", ...)`
|
||||
- **澄清恢复**：`submitClarification` 把用户回答拼到 prompt 里再 `runOrchestration`，不会重建 thread
|
||||
|
||||
### 5.5 Persona 抽屉（Step 2 圆桌可视化点击）
|
||||
|
||||
- 点击圆桌头像 → `setSelectedAgentId(seatId)` → 在上半部分下方展开抽屉
|
||||
- 抽屉控件：
|
||||
- **System Prompt**：仅前端记录（后端覆写未开放）
|
||||
- **Temp**：仅前端记录
|
||||
- **推理模型**：选项来自 `useModels()`，默认 `DEFAULT_MODEL`
|
||||
- 「参数覆盖并重启动算研讨」按钮 → `handleSaveAgentAndRecalculate`：
|
||||
- 把新的 `(seatId, model)` 写入 `agentConfigs`
|
||||
- 追加一条「⚡ [模型偏好已保存] ...」对话气泡
|
||||
- **不**立即重启编排；下一轮该席位被派活时 `runOrchestration` 内会读 `agentConfigs[meta.speakerId]?.model` 作为 special 调用的 `model` 参数
|
||||
|
||||
### 5.6 草稿持久化（`utils/drafts.ts`）
|
||||
|
||||
- Key：`roundtable-planning:drafts:v1`（`localStorage`）
|
||||
- 草稿快照含：`step1.{intentThreadId, intentReady, interactiveMessages, timelineEntries}`、`step2.{threadIds, coordinatorName, step2RoundtableDialogues, lastLeaderContent, hasConsensus, consensusPercentage, budgetLimit}`、`furthestStep`
|
||||
- `deriveDraftName({intentReady, interactiveMessages})`：优先用 `intentReady.objective`，否则取第一个 user 消息，否则用 `未命名草稿 <时间>`，统一截断到 40 字
|
||||
- **自动保存策略**：仅在「前进」步骤切换时保存（1→2、2→3），后退不触发，避免覆盖 `furthestStep`
|
||||
- **手动保存**：顶栏 + Step 1 底部「保存草稿」按钮均调用 `handleManualSave`
|
||||
- **加载草稿**：`handleLoadDraft`
|
||||
- 中断所有 in-flight（`abortAllInFlight + stopIntentStream`）
|
||||
- **先**置 `loadedFromDraftRef.current = true`，再 `setCurrentStep(draft.furthestStep)`，避免 step1/step2 init effect 重新调用 init 把恢复的状态打掉
|
||||
- `step1InitGenRef` 自增，淘汰可能晚归的旧 init
|
||||
- `step2InitRef.current = draft.furthestStep >= 2`：曾经走到 Step 2 才标记已 init
|
||||
- 角色面板基线状态：被恢复时全部置「在线」，否则 init 流程逐个置「在线」
|
||||
|
||||
---
|
||||
|
||||
## 6. 组件说明
|
||||
|
||||
### 6.1 `IntentClarificationCard`
|
||||
|
||||
- Props：`payload`（`ClarificationPayload`）、`selection`、`onSubmit(overrideSelection?)`、`disabled`、`submitting`、`fallbackContent`
|
||||
- **单选**（默认 `allowMultiple === false`）：`resolveAllowMultiple` 返回 false → 点击选项即 `onSubmit({selectedIds:[id], custom: ""})`，UI 不显示「发送回答」按钮（除非 `allowCustom`）
|
||||
- **多选**：勾选多个 + 输入补充，再点「发送回答」；答案格式见 `formatIntentClarificationAnswer`：
|
||||
- 仅选项 → `我选择：A、B`
|
||||
- 仅自定义 → 直接发自定义文本
|
||||
- 同时存在 → `我选择：A、B；补充：…`
|
||||
- 展示条件：`isPendingClarification && !intentReady && !parts.summary && pendingIntentClarificationMsgId === msg.id`（已出现 `[INTENT_READY]` 则隐藏可操作卡片）
|
||||
|
||||
### 6.2 `RecommendAgentsDialog`
|
||||
|
||||
- 打开时管线：`listAgents() → filterRecommendCandidates() → streamRecommend()`
|
||||
- 阶段 UI（`InternalState.phase`）：
|
||||
- `idle` → `loading_agents` → `recommending`（顶部 rationale 流；下方推荐卡 streaming=true）→ `ready` / `fallback` / `error`
|
||||
- 选择约束：`2 ≤ selected ≤ 8`；底部实时显示「至少再选 N 个」「已选 X / 8」
|
||||
- 失败兜底：候选为空 → error；status==="asking" 或 picks 不足 2 → `fallback`，自动用 `FALLBACK_AGENT_IDS` 与候选池交集勾选
|
||||
- 反竞态：内部 `generationRef`，每次 `runRecommendation` 自增，所有 setState 都校验 `myGen === generationRef.current`，避免「重新推荐」时旧 stream 写脏 state
|
||||
- `onConfirm(agentIds)` → 父组件 `handleConfirmAgents`：复位 `step2InitRef` 并 `setCurrentStep(2)`，触发 Step 2 init
|
||||
|
||||
### 6.3 `HighFidelityReport`（Step 3）
|
||||
|
||||
- 输入：`threadIds`、`coordinatorName`、`consensusText`、`hasConsensus`、`seatDeliveries`、`seatNameMap`、`onReset`
|
||||
- `seatThreadEntries`：过滤掉 `coordinatorName`，给每个 sub-thread 拉一次 `listSessionArtifacts`（`Promise.all` 并行）
|
||||
- `reloadKey`：「刷新文件清单」按钮自增，触发 effect 重新拉
|
||||
- **文件预览策略**（`shouldPreviewInModal`）：
|
||||
- 命中 → `ArtifactPreviewModal`（Markdown 用 react-markdown 渲染，其它当 plain text）
|
||||
- 不命中（pdf / png / html / 二进制）→ `window.open(buildArtifactDownloadUrl)`，交给浏览器原生 viewer
|
||||
- 命中规则：
|
||||
- mimeType 是 `text/markdown` / `text/plain` / `text/csv` / `application/json` / `text/*`
|
||||
- 或文件名后缀属于 `md / markdown / txt / json / csv / log / yml / yaml / xml`
|
||||
- 各席位最终交付（中段折叠区）数据源：父组件传入的 `seatDeliveries`，按发送者去重（后到的覆盖前者）
|
||||
- 「重新起草」→ 父组件 `handleStartNewTask`（清空并 `runStep1Init`）
|
||||
- 「打印 / 另存 PDF」→ `window.print()`，浏览器原生流程
|
||||
|
||||
### 6.4 `ArtifactPreviewModal`
|
||||
|
||||
- 通过 `buildArtifactDownloadUrl(threadId, path)`（不带 `download=true`）GET 文件正文
|
||||
- Markdown 文件（mime===`text/markdown` 或后缀 `.md/.markdown`）→ react-markdown + remark-gfm
|
||||
- 其它文本类 → `<pre>` 直出
|
||||
- 头部「下载」按钮单独走 `download=true` URL，触发浏览器附件下载
|
||||
- 关闭：Esc / 点击外层遮罩（精确匹配 `e.target === e.currentTarget`，避免内部冒泡误关）
|
||||
|
||||
### 6.5 共享 UI 模式与辅助
|
||||
|
||||
- **三段式流式气泡**：`appendStreamingDialogue` → `appendToDialogue`（仅追加增量）→ `finalizeDialogue`（设最终 content + confidence + `streaming=false`）。三函数都通过 `id` 匹配，避免数组下标错位
|
||||
- **Phase 到中文文案**：`phaseLabel(phase, agentType, toolName)`：
|
||||
- `connecting` → 「调度中」
|
||||
- `connected` → 「已连接,等待响应」
|
||||
- `tool_calling` 按 toolName：`agent_orchestration → 正在派活`、`ask_clarification → 正在提问`、`present_files → 正在交付文件`，其它 → 「调用工具:<name>」
|
||||
- `tool_result` → 「处理工具结果」
|
||||
- `streaming` → leader 时「正在派活说明」、special 时「正在输出」
|
||||
- Step 1 的 `intentPhaseLabel`：`ask_clarification → 正在生成追问`、`streaming → 正在思考问题`
|
||||
- **Markdown 渲染**：Step 1 / 2 / 3 都用 `react-markdown` + `remark-gfm`，自定义紧凑间距的 `components`（`p` 用 `my-1 whitespace-pre-wrap` 等）
|
||||
- **自动滚动**：`useAutoScroll(ref, [list])` 跟随；用户上滑后停止跟随；`ScrollToBottomButton` 一键回底
|
||||
- **`activeSpeakerSet`**：圆桌可视化里多席位同时高亮需要 Set，单 leader 时仍可用 `activeSpeakerId`；两者均触发 ring 动画
|
||||
- **状态条颜色**：`研讨中` 红 / `在线` 绿 / `已完成` 绿勾 / `正在上线` 黄旋 / 其它灰
|
||||
|
||||
---
|
||||
|
||||
## 7. 澄清交互（与主聊天对齐）
|
||||
|
||||
| 能力 | 实现位置 |
|
||||
|------|----------|
|
||||
| 结构化 payload 类型 | `multi-agent.ts` → `ClarificationPayload`（intent.ts 复用） |
|
||||
| 单选/多选 | `lib/clarification.ts` → `resolveAllowMultiple`（缺省单选） |
|
||||
| 答案拼接 | `formatIntentClarificationAnswer`（`IntentClarificationCard`） |
|
||||
| Step 1 卡片 | `IntentClarificationCard` + `submitIntentClarification` |
|
||||
| Step 2 卡片 | 页面底部 `pendingClarification` 区块 + `submitClarification` → 再 `runOrchestration` |
|
||||
| 主聊天参考 | `src/components/workspace/messages/message-list.tsx` → `ClarificationCard` |
|
||||
|
||||
后端字段 `allow_multiple` 缺省为 **false**（单选、点击即发送）。
|
||||
|
||||
**关键差异**：
|
||||
|
||||
- Step 1 用 `IntentClarificationCard` 组件（嵌在气泡里），Step 2 直接在页面底部渲染 amber 色带（**没有**抽象成独立组件，紧贴对话区）。
|
||||
- Step 2 澄清回复后**不**重建 thread；新 prompt 自带「用户已回复你刚才的澄清问题。问题:... 用户回答:...」上下文。
|
||||
|
||||
---
|
||||
|
||||
## 8. 与主聊天的差异
|
||||
|
||||
| 维度 | 主聊天 `/page/workspace/chats/new` | 圆桌规划 |
|
||||
|------|-----------------------------------|----------|
|
||||
| SDK | `@langchain/langgraph-sdk` 直连 | 自研 SSE 解析（`apiFetch` + ReadableStream） |
|
||||
| 澄清展示 | `message-list` ToolMessage `additional_kwargs` | 终态帧 `status: "clarification"` |
|
||||
| Agent | 用户可选 assistant | 内置 intent + 动态 coordinator + 可选席位 |
|
||||
| 线程 | 单 thread | Step 1 一线程；Step 2 每席位 + 协调各一线程 |
|
||||
| 终态语义 | LangGraph state | 自定义 `{status, content, ...}` 终态帧 |
|
||||
| 暂停 | LangGraph interrupt | `AbortController.abort()` |
|
||||
|
||||
复用思路：澄清卡片交互、答案文案格式；**不要**假设能直接复用 LangGraph React hooks。
|
||||
|
||||
---
|
||||
|
||||
## 9. 关键交互清单
|
||||
|
||||
| 交互 | 行为 |
|
||||
|------|------|
|
||||
| Step 1 发送 | Enter 发送（Shift+Enter 换行）；发送中显示「暂停」 |
|
||||
| Step 1 暂停 | `stopIntentStream()`，气泡尾部追加 `(已暂停)` 并 toast |
|
||||
| Step 1 进入 Step 2 | 需 `intentReady`；打开推荐弹窗而非直接切步 |
|
||||
| Step 1 跳过此项 | 仅本地追加「系统」气泡，不发请求；适合演示 |
|
||||
| Step 2 init | 首次进入自动 SSE init；离开 Step 2 **不**销毁 `threadIds`（可返回继续看，不会二次 init） |
|
||||
| Step 2 挂起/恢复 | `isRoundTableRunning` + `stopOrchestration` / 恢复时再 leader 一轮 |
|
||||
| Step 2 干预 | 底部输入框 → `runOrchestration` 新 seed，wrap 进「用户人工干预新指令:...」 prompt |
|
||||
| Step 2 Persona | 点圆桌头像打开抽屉；保存后下一轮该席位使用所选模型 |
|
||||
| 新建任务 | `handleStartNewTask`：abort 全部、清 state、`runStep1Init`，与 Step 3「重新起草」共用 |
|
||||
| 历史草稿 | 顶栏下拉：加载 / 重命名 / 删除（删除带 `window.confirm`） |
|
||||
| Step 3 预览 | 文本类 → 模态预览；其它 → 新窗口下载 |
|
||||
|
||||
---
|
||||
|
||||
## 10. 类型与常量速查
|
||||
|
||||
```ts
|
||||
// Step 1 输出 → Step 2 输入
|
||||
interface IntentSummary {
|
||||
objective: string;
|
||||
constraints: string[];
|
||||
assumptions?: string[];
|
||||
}
|
||||
|
||||
// Step 2 线程映射（init_done.thread_ids）
|
||||
type ThreadIdMap = Record<string, string>;
|
||||
|
||||
// 派活
|
||||
type LeaderDispatch = [string, string]; // [agent_name, task]
|
||||
|
||||
// 当前选中的研讨席位
|
||||
type SelectedAgent = { agent_id: string; name: string };
|
||||
|
||||
// Step 1 单条澄清问题
|
||||
interface ClarificationPayload {
|
||||
question: string;
|
||||
clarificationType: string;
|
||||
context: string;
|
||||
options: unknown[];
|
||||
allowCustom: boolean;
|
||||
allowMultiple?: boolean;
|
||||
}
|
||||
|
||||
// Step 2 stream 终态
|
||||
interface StreamMultiAgentResult {
|
||||
dispatched: LeaderDispatch[];
|
||||
message: string | null;
|
||||
content: string;
|
||||
agentName: string | null;
|
||||
clarification: ClarificationPayload | null;
|
||||
}
|
||||
```
|
||||
|
||||
**核心常量**：
|
||||
|
||||
| 常量 | 值 | 位置 |
|
||||
|------|----|------|
|
||||
| `DEFAULT_MODEL` | `"deepseek-chat"` | RoundtablePlanningPage |
|
||||
| `COMMANDER_SEAT_ID` | `1` | RoundtablePlanningPage |
|
||||
| `MAX_CYCLES` | `8` | RoundtablePlanningPage（`runOrchestration` 内） |
|
||||
| `MIN_SELECTED` / `MAX_SELECTED` | `2` / `8` | RecommendAgentsDialog |
|
||||
| `FALLBACK_AGENT_IDS` | 6 内置 roundtable-* | RecommendAgentsDialog |
|
||||
| `BUILTIN_AGENT_META` | 6 内置头像/中文名 | RoundtablePlanningPage |
|
||||
| `FALLBACK_AVATAR_TYPES` | `[blue, purple, emerald, amber, pink]` | RoundtablePlanningPage |
|
||||
| `STORAGE_KEY` | `"roundtable-planning:drafts:v1"` | drafts.ts |
|
||||
| `INTENT_READY_RE` | `/\[INTENT_READY\]\s*```json\s*(\{[\s\S]*?\})\s*```/` | RoundtablePlanningPage |
|
||||
| `RECOMMEND_READY_MARKER` | `"[RECOMMEND_READY]"` | recommend.ts |
|
||||
| `EXCLUDED_AGENT_IDS` / 前缀 | `roundtable-intent`、`roundtable-recommender`、`roundtable-coordinator-*` | recommend.ts |
|
||||
|
||||
---
|
||||
|
||||
## 11. 故障排查
|
||||
|
||||
| 现象 | 可能原因 | 排查 |
|
||||
|------|----------|------|
|
||||
| Step 1 一直「等待澄清」但气泡里出现绿色 [INTENT_READY] 摘要 | 终态帧未带 `summary` | 看 `splitIntentReadyBlock` + 同步 `useEffect`，必要时手动刷新 |
|
||||
| Step 1 角色面板卡在「正在上线」 | StrictMode 双 mount 导致 init 异步被丢弃 | 已用 `step1InitGenRef` 修复；检查是否被改坏 |
|
||||
| 选项全是多选 | `allow_multiple` 未传或为 true | Network 终态帧；`resolveAllowMultiple` |
|
||||
| Step 2 init 卡住 | init SSE error / 代理 | Network `init`；控制台 `[init-timing]` |
|
||||
| Step 2 stream 看不到任何文字 | TitleMiddleware 过滤错杀 / phase 卡在 connecting | 控制台搜 `[stream:` 前缀（需 `__MULTI_AGENT_DEBUG__`） |
|
||||
| 总控不派活 | `dispatched` 一直 `[]` 且非 clarification | 看 leader 终态帧；模型 SOUL 配置 |
|
||||
| 推荐弹窗为空 | `filterRecommendCandidates` 把所有候选都过滤了 | `GET /api/agents` 列表；检查 `EXCLUDED_AGENT_IDS` |
|
||||
| 推荐弹窗一直「等待推荐结果」 | recommender 模型死循环 | 控制台看 `[stream:` 日志，或点「重新推荐」 |
|
||||
| Step 3 各席位文件为空 | 子 agent 未写 outputs 或 thread id 错 | 对应 thread 调 `listSessionArtifacts` |
|
||||
| Step 3 预览空白 | 文件不是文本类，但被错误命中 `shouldPreviewInModal` | 检查 mime + 后缀；不在白名单的应该跳 `window.open` |
|
||||
| Step 3 文件名乱码 / 404 | `buildArtifactDownloadUrl` 编码错 | 看 path 是否被分段 encode；不能整体 encode（会把 `/` 也编了） |
|
||||
| 草稿加载后重复 init | `loadedFromDraftRef` 未置位 | `handleLoadDraft` 流程，注意 ref 必须先于 `setCurrentStep` |
|
||||
| 顶栏 Step 2 / Step 3 一直灰 | `intentReady` / `hasConsensus` 没设上 | 看终态帧；leader.dispatched 是否真为 `[]` |
|
||||
| Persona 抽屉改模型不生效 | 下一轮才生效 / 抽屉 model 未传给 streamMultiAgent | 看 `agentConfigs[meta.speakerId]?.model` 的传递路径 |
|
||||
| 并行 SSE 卡顿 | 误改为 parallel 派活 | 保持顺序 dispatch，详见 §5.4 注释 |
|
||||
|
||||
**本地调试开关**：
|
||||
|
||||
```js
|
||||
window.__MULTI_AGENT_INIT_TIMING__ = true; // init 各阶段耗时（默认开）
|
||||
window.__MULTI_AGENT_DEBUG__ = true; // stream 帧计数（默认开）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. 扩展指南
|
||||
|
||||
### 12.1 新增默认研讨席位
|
||||
|
||||
1. 后端 `.deer-flow/agents/roundtable-xxx/`
|
||||
2. `BUILTIN_AGENT_META` + `DEFAULT_SELECTED_AGENTS` + `RecommendAgentsDialog` 的 `FALLBACK_AGENT_IDS`
|
||||
3. 无需改 API 层（`agent_names` 由推荐结果传入）
|
||||
|
||||
### 12.2 调整 Step 1 澄清轮次上限
|
||||
|
||||
逻辑在 agent SOUL，不在前端；前端只需处理任意轮 `asking` / `clarification` / `done`。
|
||||
|
||||
### 12.3 调整 Step 2 编排上限
|
||||
|
||||
`RoundtablePlanningPage.tsx` 内 `MAX_CYCLES = 8`，超出会 toast「⏱️ 已达到最大研讨轮次,自动停止以避免循环」。若放宽：注意 `step2RoundtableDialogues` 数组会线性增长，超长讨论需要考虑虚拟滚动。
|
||||
|
||||
### 12.4 把 special 改回并行
|
||||
|
||||
不推荐；若一定要做：
|
||||
|
||||
- 把 `for ... of leaderRes.dispatched` 改成 `await Promise.all(leaderRes.dispatched.map(...))`
|
||||
- 评估浏览器性能：每 token 一次 `setStep2RoundtableDialogues(prev => prev.map(...))`，N=6 时实测明显掉帧
|
||||
- 用更高效的派发结构（如按 id 分桶 `Map<id, Bubble>` + ref 缓存）改善之后再启用
|
||||
|
||||
### 12.5 接入真实 Persona 覆盖
|
||||
|
||||
当前 prompt / temp 只在前端记录；要落地需：
|
||||
|
||||
- 后端开放 per-agent override 接口或在 `streamMultiAgent` 新增 `prompt_override` / `temperature` 字段
|
||||
- 前端：`agentConfigs[meta.speakerId]` 一并传入
|
||||
|
||||
### 12.6 拆分页面
|
||||
|
||||
当前刻意单文件维护三步。若拆分建议：
|
||||
|
||||
- `useRoundtableStep1.ts` / `useRoundtableStep2.ts` — 状态与副作用
|
||||
- 保持 `api/*` 不变
|
||||
- 保持 `roundtable-planning.css` 主题变量
|
||||
|
||||
### 12.7 文档协同
|
||||
|
||||
`@/roundtable-planning/` 内一切公共 API 都应当：
|
||||
|
||||
1. 在 `api/*.ts` 文件级注释里说明 endpoint
|
||||
2. 在本页第 4 节 / 第 10 节同步对照
|
||||
3. 后端字段变化（如 `init_done` 字段名）需要同步改 `initMultiAgent` 解析逻辑 + `multi-agent-api.md`
|
||||
|
||||
---
|
||||
|
||||
## 13. 路径速查
|
||||
|
||||
| 资源 | 路径 |
|
||||
|------|------|
|
||||
| 主页面 | `frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx` |
|
||||
| Step 1 API | `frontend-web/src/roundtable-planning/api/intent.ts` |
|
||||
| 推荐 API | `frontend-web/src/roundtable-planning/api/recommend.ts` |
|
||||
| Step 2/3 API | `frontend-web/src/roundtable-planning/api/multi-agent.ts` |
|
||||
| 澄清卡片 | `frontend-web/src/roundtable-planning/components/IntentClarificationCard.tsx` |
|
||||
| 推荐弹窗 | `frontend-web/src/roundtable-planning/components/RecommendAgentsDialog.tsx` |
|
||||
| Step 3 报告 | `frontend-web/src/roundtable-planning/components/HighFidelityReport.tsx` |
|
||||
| 文件预览 | `frontend-web/src/roundtable-planning/components/ArtifactPreviewModal.tsx` |
|
||||
| 回底按钮 | `frontend-web/src/roundtable-planning/components/ScrollToBottomButton.tsx` |
|
||||
| 滚动跟随 | `frontend-web/src/roundtable-planning/hooks/useAutoScroll.ts` |
|
||||
| 澄清单选逻辑 | `frontend-web/src/roundtable-planning/lib/clarification.ts` |
|
||||
| 草稿存档 | `frontend-web/src/roundtable-planning/utils/drafts.ts` |
|
||||
| 路由 | `frontend-web/src/pages/WorkspaceRoutes.tsx` |
|
||||
| 样式 | `frontend-web/src/roundtable-planning/styles/roundtable-planning.css` |
|
||||
| 主聊天澄清参考 | `frontend-web/src/components/workspace/messages/message-list.tsx` |
|
||||
| 后端开发文档 | `frontend-web/docs/multi-agent-backend-dev.md` |
|
||||
| API 速查 | `frontend-web/docs/multi-agent-api.md` |
|
||||
@@ -1,492 +0,0 @@
|
||||
# 多智能体圆桌 · Step 1 · 任务理解智能体接口与实现
|
||||
|
||||
> Step 1（`/page/roundtable/planning` 的"任务意图与澄清"页）对应 `RoundtablePlanningPage.tsx` 里 `currentStep === 1` 的渲染分支。当前它是纯前端 mock —— 用户发消息后 `setTimeout(1500)` 拼一段固定话术回。本文档定义一个**内置任务理解智能体 + 2 个轻量接口**，让 step 1 跑起来真正的对话，为 step 2 输入更高质量的"任务目标 + 约束"。
|
||||
>
|
||||
> 整体风格直接参照 `multi-agent-api.md` / `multi-agent-backend-dev.md`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标与边界
|
||||
|
||||
### ✅ 要做的事
|
||||
- 内置一个智能体：**任务理解智能体**（`roundtable-intent`），跟 6 个 roundtable 席位同等地位
|
||||
- 提供 2 个接口：`/api/intent/init` 和 `/api/intent/stream`
|
||||
- 复用 step 2 的 SSE 协议风格（前端只需 1 个新 helper）
|
||||
- 让用户跟智能体多轮澄清后，把最终"目标 + 约束"传给 step 2 的 `runOrchestration`
|
||||
|
||||
### ❌ 不做的事
|
||||
- 不重新设计澄清协议（直接用 `ask_clarification` 工具 + ClarificationMiddleware 现成机制，跟 step 2 leader 一样）
|
||||
- 不做"自动跳过"按钮的真实业务逻辑（保留前端按钮形态即可）
|
||||
- 不做时间线（timelineEntries）的后端持久化（前端临时状态够用）
|
||||
- 不做"评分/置信度"等假指标
|
||||
- 不做单独的"任务理解专员模型选择"——直接用全局 `DEFAULT_MODEL`
|
||||
|
||||
---
|
||||
|
||||
## 2. 数据流概览
|
||||
|
||||
```
|
||||
[Step 1 入口]
|
||||
↓
|
||||
前端：POST /api/intent/init
|
||||
← {agent_id: "roundtable-intent", thread_id: "..."}
|
||||
|
||||
用户输入第一句话："帮我规划一个生产系统安全改造方案"
|
||||
↓
|
||||
前端：POST /api/intent/stream (SSE)
|
||||
← (流式 AI 文本) "好的，预算大致是多少？"
|
||||
← {status: "asking", content: "..."} ← 智能体反问中,需要用户继续
|
||||
|
||||
用户回："500 万左右"
|
||||
↓
|
||||
前端再次 POST /api/intent/stream
|
||||
← (流式) "明白，还有什么时间约束吗？"
|
||||
← {status: "asking", ...}
|
||||
|
||||
...对话进行几轮 ...
|
||||
|
||||
用户：可以了
|
||||
↓
|
||||
前端再 POST /api/intent/stream
|
||||
← (流式) "好，我理解的任务是: <汇总>"
|
||||
← {status: "done", content: "<最终汇总文本>", summary: {...}} ← 信息充分,可进入 step 2
|
||||
|
||||
[Step 1 完成 → Step 2 init]
|
||||
前端把 summary.objective + summary.constraints 拼成 step 2 的 buildInitialIntent()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 接口设计
|
||||
|
||||
跟 step 2 完全同构。`/api/intent/init` 简化版（只建 1 个 thread + 1 个 agent，没有"协调"概念）；`/api/intent/stream` 跟 `/api/multi-agent/run/stream` 的 special 分支几乎一样。
|
||||
|
||||
### 3.1 `POST /api/intent/init`
|
||||
|
||||
**请求体**
|
||||
```json
|
||||
{
|
||||
"model": "deepseek-chat" // 可选,默认全局 DEFAULT_MODEL
|
||||
}
|
||||
```
|
||||
|
||||
**响应 200**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"agent_id": "roundtable-intent",
|
||||
"thread_id": "<langgraph_thread_id>"
|
||||
}
|
||||
```
|
||||
|
||||
**行为**：
|
||||
1. 鉴权（透传 `Authorization`）
|
||||
2. 调上游 `POST /api/threads` 建 1 个 thread
|
||||
3. 直接返回 `agent_id = "roundtable-intent"`（**这是内置 agent,不需要每次新建**）
|
||||
|
||||
**与 step 2 `/init` 的区别**：
|
||||
- 没有"协调智能体"概念，只有 1 个 agent
|
||||
- 没有 6 个 sub 席位，只有 1 个 thread
|
||||
- 不需要传 `agent_names` 数组
|
||||
- `agent_id` 是固定字符串 `"roundtable-intent"`，不带 timestamp 后缀（智能体本身是内置、长期、复用的）
|
||||
|
||||
### 3.2 `POST /api/intent/stream`
|
||||
|
||||
**请求体**
|
||||
```json
|
||||
{
|
||||
"thread_id": "<from /init>",
|
||||
"message": "用户这一轮要说的话",
|
||||
"model": "deepseek-chat" // 可选
|
||||
}
|
||||
```
|
||||
|
||||
**响应**：`text/event-stream`，SSE 流式。
|
||||
|
||||
**SSE 帧组成**：
|
||||
1. 透传上游 LangGraph 的所有帧（`event: metadata` / `event: messages` / `event: values`）—— 前端用现有的 `extractAiTextDelta` 解析 AI 文本增量
|
||||
2. 流末追加一个**状态帧**（跟 step 2 同样模式）：
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "asking" | "done" | "error",
|
||||
"content": "<本轮 AI 文本>",
|
||||
"summary": {
|
||||
"objective": "...", // 仅 status=done 时有: 任务目标
|
||||
"constraints": ["...", ...], // 仅 status=done 时有: 约束清单
|
||||
"assumptions": ["...", ...] // 仅 status=done 时有: 关键假设
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**`status` 取值**：
|
||||
- `"asking"` —— 智能体还在追问，前端应该把焦点放回输入框
|
||||
- `"done"` —— 智能体宣布"信息已充分"，前端就可以亮起"进入下一步"按钮，并拿 `summary` 拼 step 2 的初始 intent
|
||||
- `"error"` —— 上游异常，`content` 里是错误信息
|
||||
|
||||
**判定 done/asking 的简单策略**（后端实现）：
|
||||
- 智能体在 SOUL 里被告知：信息已充分时**必须**调 `present_intent_summary` 工具（或直接在 AIMessage 里用一个固定标记 `[INTENT_READY]`），后端识别后发 `done` 帧
|
||||
- 否则一律是 `asking`
|
||||
|
||||
> 上面"summary 工具"是新增的内置工具吗？不一定。最省事的做法是**让模型用 JSON 块输出**，后端用正则提取：
|
||||
>
|
||||
> ```
|
||||
> [INTENT_READY]
|
||||
> ```json
|
||||
> {"objective": "...", "constraints": ["..."], "assumptions": ["..."]}
|
||||
> ```
|
||||
> ```
|
||||
>
|
||||
> 后端流末扫一下最末 AIMessage 里有没有这个标记，有就 parse JSON 出来填到 summary，发 `done`；没有就发 `asking`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 内置智能体配置
|
||||
|
||||
**位置**：`offline-backend-20260512/backend/.deer-flow/agents/roundtable-intent/`
|
||||
|
||||
### 4.1 `config.yaml`
|
||||
```yaml
|
||||
id: roundtable-intent
|
||||
name: 任务理解智能体
|
||||
description: 帮助用户明确任务目标、约束、关键假设,为后续多智能体圆桌研讨准备结构化输入。
|
||||
```
|
||||
|
||||
### 4.2 `SOUL.md`
|
||||
|
||||
```markdown
|
||||
# 任务理解智能体
|
||||
|
||||
## 角色定位
|
||||
你是多智能体圆桌研讨的"任务理解专员"。你的工作是在用户和 6 个圆桌席位之间架一座桥:
|
||||
通过 2-5 轮简短追问,把用户模糊的需求转化成结构化的「任务目标 + 约束 + 关键假设」。
|
||||
|
||||
## 核心职责
|
||||
- 用清晰、简短的问题引导用户补全关键信息(优先级: 目标 > 硬约束 > 软偏好)
|
||||
- 不要追问已经清楚的事
|
||||
- 不要做方案,不要给具体技术建议——那是后面 6 个席位的工作
|
||||
- 信息足够后,立即停止追问,产出结构化汇总
|
||||
|
||||
## 信息充分性判定
|
||||
当满足以下条件时,认为信息已充分:
|
||||
1. 明确的任务目标(至少能写出一句 "用户希望实现 X")
|
||||
2. 至少 1 条硬约束(预算/时间/合规/范围之一)
|
||||
3. 没有明显的歧义点
|
||||
|
||||
## 信息汇总产出
|
||||
信息充分时,你必须在回复末尾输出**精确的标记 + JSON 块**(给后端识别用):
|
||||
|
||||
```
|
||||
[INTENT_READY]
|
||||
```json
|
||||
{
|
||||
"objective": "用一句话写出用户最终要做的事",
|
||||
"constraints": ["预算 ≤ XXX 万", "时间 ≤ XXX 天", ...],
|
||||
"assumptions": ["假设 1", "假设 2", ...]
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
输出前可以先用自然语言总结一遍给用户看(让用户能 review 内容),再附上述标记 + JSON。
|
||||
|
||||
## 输出风格
|
||||
- 一次回复不超过 3 句话
|
||||
- 提问要具体,不要"还有什么补充吗"这种空问
|
||||
- 用 emoji 简短点缀(❓ 表示问题, ✅ 表示明确, 📋 表示汇总)
|
||||
|
||||
## 边界
|
||||
- 不调用 agent_orchestration(这是 step 2 的协调智能体的事)
|
||||
- 不写文件、不做计算、不联网
|
||||
- 用户消息歧义大时,优先调 ask_clarification 工具引导
|
||||
```
|
||||
|
||||
### 4.3 注册方式
|
||||
|
||||
跟现有 6 个 `roundtable-*` 一样,通过 `_sync_legacy_agents()`(`app/gateway/routers/agents.py`)在下次任意 `/api/agents` 请求时自动 upsert 进 `agents` 表,`user_id IS NULL` 标记为内置。**零代码改动**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 后端实现要点
|
||||
|
||||
### 5.1 新建 router 文件
|
||||
**位置**：`offline-backend-20260512/backend/app/gateway/routers/intent.py`
|
||||
|
||||
```python
|
||||
"""任务理解智能体接口 - Step 1 的极简包装。
|
||||
|
||||
跟 multi_agent.py 同构但简化:
|
||||
- 没有 broadcast(单 thread,无需广播)
|
||||
- 没有派活逻辑
|
||||
- 没有 leader/special 分支,只有一种调用方式
|
||||
- 流末状态帧解析 [INTENT_READY] 标记决定 status=done/asking
|
||||
"""
|
||||
|
||||
from fastapi import APIRouter, Body, HTTPException, Request
|
||||
from fastapi.responses import StreamingResponse
|
||||
import httpx, json, re, asyncio, logging
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
router = APIRouter(prefix="/api/intent", tags=["intent"])
|
||||
|
||||
# 复用 multi_agent.py 里已有的工具函数
|
||||
from app.gateway.routers.multi_agent import (
|
||||
_loopback_base, _auth_headers,
|
||||
_create_thread, _stream_upstream, _parse_last_messages,
|
||||
_flatten_content, _run_payload,
|
||||
)
|
||||
|
||||
INTENT_AGENT_ID = "roundtable-intent"
|
||||
|
||||
_INTENT_READY_PATTERN = re.compile(
|
||||
r"\[INTENT_READY\]\s*```json\s*(\{.*?\})\s*```",
|
||||
re.DOTALL,
|
||||
)
|
||||
|
||||
|
||||
@router.post("/init")
|
||||
async def init_intent(request: Request, payload: dict = Body(...)) -> dict:
|
||||
base = _loopback_base(request)
|
||||
headers = _auth_headers(request)
|
||||
async with httpx.AsyncClient(timeout=None) as client:
|
||||
thread_id = await _create_thread(client, base, headers)
|
||||
return {
|
||||
"status": "success",
|
||||
"agent_id": INTENT_AGENT_ID,
|
||||
"thread_id": thread_id,
|
||||
}
|
||||
|
||||
|
||||
@router.post("/stream")
|
||||
async def stream_intent(request: Request, payload: dict = Body(...)) -> StreamingResponse:
|
||||
thread_id = str(payload.get("thread_id") or "").strip()
|
||||
message = str(payload.get("message") or "").strip()
|
||||
model_name = str(payload.get("model") or "deepseek-chat")
|
||||
if not thread_id or not message:
|
||||
raise HTTPException(status_code=400, detail="thread_id and message required")
|
||||
|
||||
base = _loopback_base(request)
|
||||
headers = _auth_headers(request)
|
||||
|
||||
async def gen():
|
||||
async with httpx.AsyncClient(timeout=None) as client:
|
||||
try:
|
||||
body = _run_payload(
|
||||
agent_name=INTENT_AGENT_ID,
|
||||
model_name=model_name,
|
||||
thread_id=thread_id,
|
||||
new_message=message,
|
||||
excluded_tools=["web_search", "present_files",
|
||||
"view_image", "agent_orchestration"],
|
||||
skill_stop_names=[],
|
||||
)
|
||||
captured = []
|
||||
async for line, done in _stream_upstream(client, base, headers, thread_id, body):
|
||||
if line is not None:
|
||||
yield (line if line.endswith("\n") else line + "\n")
|
||||
elif done is not None:
|
||||
captured = done
|
||||
|
||||
messages = _parse_last_messages(captured)
|
||||
last_ai = {}
|
||||
for m in reversed(messages):
|
||||
if isinstance(m, dict) and (m.get("type") or "").lower() in ("ai", "aimessage", "aimessagechunk"):
|
||||
last_ai = m
|
||||
break
|
||||
content = _flatten_content(last_ai.get("content", ""))
|
||||
|
||||
# 检测 [INTENT_READY] 标记
|
||||
match = _INTENT_READY_PATTERN.search(content)
|
||||
if match:
|
||||
try:
|
||||
summary = json.loads(match.group(1))
|
||||
except json.JSONDecodeError:
|
||||
summary = None
|
||||
frame = {"status": "done", "content": content, "summary": summary}
|
||||
else:
|
||||
frame = {"status": "asking", "content": content}
|
||||
yield f"data: {json.dumps(frame, ensure_ascii=False)}\n\n"
|
||||
except HTTPException as exc:
|
||||
yield f"data: {json.dumps({'status':'error','content':f'[{exc.status_code}] {exc.detail}'}, ensure_ascii=False)}\n\n"
|
||||
except Exception as exc:
|
||||
logger.exception("intent stream failure")
|
||||
yield f"data: {json.dumps({'status':'error','content':f'unexpected: {exc!r}'}, ensure_ascii=False)}\n\n"
|
||||
|
||||
return StreamingResponse(
|
||||
gen(),
|
||||
media_type="text/event-stream",
|
||||
headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no", "Connection": "keep-alive"},
|
||||
)
|
||||
```
|
||||
|
||||
### 5.2 在 `app/gateway/app.py` 注册
|
||||
```python
|
||||
from app.gateway.routers import intent
|
||||
app.include_router(intent.router)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 前端实现要点
|
||||
|
||||
### 6.1 新增 API helper
|
||||
**位置**：`frontend-web/src/roundtable-planning/api/intent.ts`
|
||||
|
||||
```ts
|
||||
import { apiFetch } from "@/core/api/fetch-client";
|
||||
import { getBackendBaseURL } from "@/core/config";
|
||||
|
||||
export interface IntentInitResponse {
|
||||
status: "success";
|
||||
agent_id: string;
|
||||
thread_id: string;
|
||||
}
|
||||
|
||||
export async function initIntent(model?: string): Promise<IntentInitResponse> {
|
||||
const res = await apiFetch(`${getBackendBaseURL()}/api/intent/init`, {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ model }),
|
||||
});
|
||||
if (!res.ok) throw new Error(`init intent failed (${res.status}): ${await res.text()}`);
|
||||
return res.json();
|
||||
}
|
||||
|
||||
export interface IntentSummary {
|
||||
objective: string;
|
||||
constraints: string[];
|
||||
assumptions?: string[];
|
||||
}
|
||||
|
||||
export interface StreamIntentRequest {
|
||||
threadId: string;
|
||||
message: string;
|
||||
model?: string;
|
||||
signal?: AbortSignal;
|
||||
onTextDelta?: (text: string, id: string) => void;
|
||||
}
|
||||
|
||||
export interface StreamIntentResult {
|
||||
status: "asking" | "done" | "error";
|
||||
content: string;
|
||||
summary: IntentSummary | null;
|
||||
}
|
||||
|
||||
export async function streamIntent(req: StreamIntentRequest): Promise<StreamIntentResult> {
|
||||
// 实现:reader 循环跟 streamMultiAgent 几乎一样,只是状态帧解析改成
|
||||
// {status, content, summary?} 格式。
|
||||
// ...(参考 multi-agent.ts 的 streamMultiAgent 改写,简化 80%)
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 改造 `RoundtablePlanningPage.tsx` 的 step1 渲染
|
||||
|
||||
替换 `handleSendMessage`:
|
||||
|
||||
```ts
|
||||
const [intentThreadId, setIntentThreadId] = useState<string | null>(null);
|
||||
const [intentReady, setIntentReady] = useState<IntentSummary | null>(null);
|
||||
|
||||
useEffect(() => {
|
||||
if (currentStep === 1 && !intentThreadId) {
|
||||
initIntent(DEFAULT_MODEL).then(r => setIntentThreadId(r.thread_id));
|
||||
}
|
||||
}, [currentStep]);
|
||||
|
||||
const handleSendMessage = async () => {
|
||||
if (!inputText.trim() || !intentThreadId) return;
|
||||
const userText = inputText.trim();
|
||||
// (push user msg to interactiveMessages 略)
|
||||
setInputText("");
|
||||
|
||||
// 占位 agent 气泡
|
||||
const agentMsgId = pushAgentPlaceholder("任务理解智能体");
|
||||
|
||||
const res = await streamIntent({
|
||||
threadId: intentThreadId,
|
||||
message: userText,
|
||||
model: DEFAULT_MODEL,
|
||||
onTextDelta: (delta) => appendToAgentMsg(agentMsgId, delta),
|
||||
});
|
||||
|
||||
finalizeAgentMsg(agentMsgId, res.content);
|
||||
if (res.status === "done" && res.summary) {
|
||||
setIntentReady(res.summary);
|
||||
triggerToast("✅ 任务理解完成,可以进入圆桌研讨");
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### 6.3 "进入 step 2"按钮的联动
|
||||
|
||||
- 当前页面已有"完成澄清/进入下一步"按钮（应该是路由到 `currentStep === 2`）
|
||||
- 改造：只有 `intentReady !== null` 时该按钮才 enabled
|
||||
- 点击后：把 `intentReady.objective + intentReady.constraints` 写入 `buildInitialIntent()` 的源（替换现在按 `interactiveMessages` 找最后一条 user msg + budgetLimit 拼接的逻辑）
|
||||
|
||||
```ts
|
||||
const buildInitialIntent = useCallback(() => {
|
||||
if (intentReady) {
|
||||
return `${intentReady.objective}\n\n约束条件:\n${intentReady.constraints.map(c => `- ${c}`).join("\n")}\n\n请基于上述目标与约束,在圆桌内调度合适的子智能体完成研讨。`;
|
||||
}
|
||||
// fallback: 旧逻辑保留兜底
|
||||
const lastUserMessage = [...interactiveMessages].reverse().find(m => m.sender === "user");
|
||||
const userIntent = lastUserMessage?.content ?? "请围绕给定任务展开圆桌研讨";
|
||||
const constraints = `预算硬约束:${budgetLimit} 万元`;
|
||||
return `${userIntent}\n\n约束条件:${constraints}\n\n请基于上述目标与约束,在圆桌内调度合适的子智能体完成研讨。`;
|
||||
}, [interactiveMessages, budgetLimit, intentReady]);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 实施清单
|
||||
|
||||
| 优先级 | 项 | 文件 |
|
||||
|---|---|---|
|
||||
| P0 | 内置 agent 目录 | `backend/.deer-flow/agents/roundtable-intent/{config.yaml,SOUL.md}` |
|
||||
| P0 | 新 router | `backend/app/gateway/routers/intent.py` |
|
||||
| P0 | 注册 router | `backend/app/gateway/app.py`（一行 `include_router`） |
|
||||
| P0 | 前端 helper | `frontend-web/src/roundtable-planning/api/intent.ts` |
|
||||
| P0 | 前端页面改造 | `frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx`（handleSendMessage + buildInitialIntent + 入口 useEffect） |
|
||||
| P1 | step 1 进入下一步按钮 disabled 状态联动 `intentReady` | 同上 |
|
||||
| P2 | 单测 | `backend/tests/test_intent.py`（init 返回 agent_id 固定值, stream 识别 INTENT_READY 标记） |
|
||||
| P3 | 失败兜底（INTENT_READY 标记被模型遗漏时的"用户手动确认进入下一步"按钮） | 前端 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 与 step 2 的衔接
|
||||
|
||||
```
|
||||
step 1 输出: intentReady.objective + intentReady.constraints
|
||||
↓
|
||||
step 2 入口: buildInitialIntent() 拼成 leader 的 new_message
|
||||
↓
|
||||
step 2 leader 不再需要主动反问澄清(因为 step1 已经清完了),
|
||||
除非模型遇到完全意料之外的歧义
|
||||
↓
|
||||
研讨更聚焦,减少 step2 阶段的 clarification 轮次
|
||||
```
|
||||
|
||||
副产物：协调智能体的 SOUL 可以稍微调整（参考 `multi_agent.py:soul = "#核心定位..."` 那段），加一句"用户已经经过任务理解智能体澄清，task 描述里包含目标+约束，请直接开始派活而不是再反问"，进一步减少 step2 的反问。
|
||||
|
||||
---
|
||||
|
||||
## 9. 路径速查
|
||||
|
||||
| 资源 | 位置 |
|
||||
|---|---|
|
||||
| Step 1 渲染 | `RoundtablePlanningPage.tsx` 内 `currentStep === 1` 分支(约 line 1418+) |
|
||||
| 新增前端 helper | `frontend-web/src/roundtable-planning/api/intent.ts` |
|
||||
| 新增后端 router | `offline-backend-20260512/backend/app/gateway/routers/intent.py` |
|
||||
| 内置 agent | `offline-backend-20260512/backend/.deer-flow/agents/roundtable-intent/` |
|
||||
| 路由注册 | `offline-backend-20260512/backend/app/gateway/app.py` |
|
||||
| 参照实现 | `multi_agent.py`（接口模式、SSE 包装、状态帧） |
|
||||
|
||||
---
|
||||
|
||||
## 10. 验收清单
|
||||
|
||||
- [ ] 进入 step 1 自动调 `/api/intent/init`，拿到 thread_id
|
||||
- [ ] 用户每次发消息后，任务理解智能体真实流式输出（不是 setTimeout）
|
||||
- [ ] 智能体能在 2-5 轮对话后自动停止追问，发 `status: done` 帧并附 summary
|
||||
- [ ] step 2 的初始 intent 用 step1 的 summary 拼接，不再依赖 `budgetLimit` 这种页面状态
|
||||
- [ ] 离开/重新进入 step 1 时，thread_id 状态干净（不会带着上次的对话）
|
||||
- [ ] 任何接口失败都不让 step 1 卡死（容错的"用旧 mock 兜底"或者明确错误提示）
|
||||
@@ -1,264 +0,0 @@
|
||||
# 多智能体圆桌 · Step 3 · 接口与对接说明
|
||||
|
||||
> Step 3（`/page/roundtable/planning` 的"最终方案展示"页）对应 `frontend-web/src/roundtable-planning/components/HighFidelityReport.tsx`。当前页面是产品早期的"展厅效果"，绝大多数内容是硬编码 mock。本文档梳理**真正需要的数据**、**用哪些接口**、**前后端怎么对接**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 改造方向（在做什么，不做什么）
|
||||
|
||||
### ✅ 保留并对接真实数据
|
||||
|
||||
| 区块 | 现状 | 改造后 |
|
||||
|---|---|---|
|
||||
| 标题栏 + 生成时间 | 硬编码"2026-05-21 11:01:12" | 用本地 `Date.now()` 或 init/最后一次 leader 完成时刻 |
|
||||
| "已达成共识"徽章 | 静态显示 | step2 自然收敛（`leaderRes.dispatched.length === 0`）后才显示 |
|
||||
| **总控最终结论** | 完全是 mock 文本 | 取最后一次 `leaderRes.content`（已经在 step2 拿到了） |
|
||||
| **各席位最终交付（折叠卡片）** | 当前 step3 没渲染 | 取每个 sub 线程的最后一条 AIMessage 文本 |
|
||||
| **生成的报告文件清单** | 5 张假"档案" | 真实列出 `outputs/` 目录里的所有产出（markdown / pdf / csv 等） |
|
||||
| **文件下载** | 假 toast | 用现有 `GET /api/threads/{tid}/artifacts/{path}` |
|
||||
| "重新起草新规划" | 调用 `setCurrentStep(1)` 重置 | **保留**，含义就是回到 step1 重新开始 |
|
||||
|
||||
### ❌ 不做（直接删 / 不接口）
|
||||
|
||||
| 区块 | 原因 |
|
||||
|---|---|
|
||||
| 4 张 metric 卡片（设计全要素通过率 99.4% / Tier III+ / 终审共识度 42 轮研商 / 90.3分）| 全是按 `budgetLimit` 编出来的"展厅指标"，没有真实数据源 |
|
||||
| 三阶段推进路线图（0-24h / 24-60h / 60-72h 三张卡）| 假设业务必然是 72 小时交付，写死场景，不通用 |
|
||||
| "采纳理由与最终裁定判词"段 | 整段都是模板话术，没接口能算出"90.3 分总评" |
|
||||
| "12 轮极限对抗研商" 数据 | 当前没记录"轮次"语义，临时就用 leader 实际轮数代替即可，不值得为它出接口 |
|
||||
| "签发起草成果并投产运行" 按钮 | 无对应业务动作（不是要部署、不是要审批），删掉 |
|
||||
| "执行摘要" 段写死的 3 个 bullet | 模板话术，跟实际任务无关 |
|
||||
|
||||
最终 step3 页面只保留四块：**头部状态 + 总控结论 + 席位交付列表 + 文件下载清单**，再加底部"重新起草"。
|
||||
|
||||
---
|
||||
|
||||
## 2. 数据来源全景
|
||||
|
||||
```
|
||||
┌───────────────────────────────────────────────────────────┐
|
||||
│ step2 全程结束时，前端手里已经有的本地状态 │
|
||||
├───────────────────────────────────────────────────────────┤
|
||||
│ coordinatorName: "roundtable-coordinator-xxx" │
|
||||
│ threadIds: { [agent_name]: thread_id, ... } │ ← /init 返回
|
||||
│ step2RoundtableDialogues: [...所有气泡, 含每个 sub 最终 │
|
||||
│ 交付的 content...] │
|
||||
│ leaderRes.content (最后一次 leader 的 final text) │
|
||||
└───────────────────────────────────────────────────────────┘
|
||||
|
||||
后端权威数据（需要时从后端拉）:
|
||||
- 每个 sub 线程的完整 state → GET /api/threads/{tid}/state
|
||||
- 单个 outputs 文件内容/下载 → GET /api/threads/{tid}/artifacts/{path}
|
||||
- outputs 目录文件清单 ❗暂无 → 新增接口（见 §3）
|
||||
```
|
||||
|
||||
**关键判断**：席位最终交付文本 + 总控结论文本 **已经在 step2 内存里**，无需重新调接口。文件清单是**目前唯一缺失**的数据源。
|
||||
|
||||
---
|
||||
|
||||
## 3. 接口需求
|
||||
|
||||
### 3.1 新增（**必需**）：列出某 thread 的产出文件
|
||||
|
||||
```
|
||||
GET /api/multi-agent/sessions/artifacts?thread_id=<sub_thread_id>
|
||||
```
|
||||
|
||||
或者更通用、放进 artifacts 路由下：
|
||||
|
||||
```
|
||||
GET /api/threads/{thread_id}/artifacts
|
||||
```
|
||||
|
||||
**为什么需要**：现有 artifacts endpoint 只能"按已知路径下载文件"，没有"列出目录"功能。Step 3 需要知道 sub-agent 写到 `/mnt/user-data/outputs/` 下哪些文件，才能在前端列出可下载清单。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"thread_id": "<sub_thread_id>",
|
||||
"files": [
|
||||
{
|
||||
"path": "mnt/user-data/outputs/方案设计报告_生产系统安全改造技术方案.md",
|
||||
"name": "方案设计报告_生产系统安全改造技术方案.md",
|
||||
"size_bytes": 12480,
|
||||
"mime_type": "text/markdown",
|
||||
"modified_at": "2026-05-23T14:32:30.123Z"
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**实现建议**：
|
||||
- 列 `backend/.deer-flow/users/{user_id}/threads/{thread_id}/user-data/outputs/` 下的文件
|
||||
- 鉴权复用 `@require_permission("threads", "read", owner_check=True)`
|
||||
- 路径要做 traversal 保护（虚拟路径仅限 `mnt/user-data/outputs/`）
|
||||
|
||||
### 3.2 新增（**可选，体感优化**）：一次性聚合 step3 数据
|
||||
|
||||
```
|
||||
POST /api/multi-agent/sessions/summary
|
||||
Body: {
|
||||
"main_agent_name": "roundtable-coordinator-xxx",
|
||||
"thread_ids": { "<agent_name>": "<thread_id>", ... }
|
||||
}
|
||||
```
|
||||
|
||||
**为什么可选**：不加这个接口的话，前端需要为每个席位发一次 `GET /state` + 一次 `GET /artifacts`（共 7-13 次 round-trip）。加了这个接口，**一次返回所有数据**。
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"main_agent_name": "roundtable-coordinator-xxx",
|
||||
"coordinator": {
|
||||
"thread_id": "...",
|
||||
"final_text": "...", // 最后一条 AIMessage content
|
||||
"dispatch_rounds": 3 // leader 派活的轮数（可选展示）
|
||||
},
|
||||
"seats": [
|
||||
{
|
||||
"agent_name": "roundtable-intelligence",
|
||||
"thread_id": "...",
|
||||
"display_name": "情报收集",
|
||||
"final_text": "...", // 最后一条 AIMessage content
|
||||
"files": [ // 该席位写到 outputs/ 的文件
|
||||
{ "path": "...", "name": "...", "size_bytes": ..., "mime_type": "..." }
|
||||
]
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**取舍**：
|
||||
- 优点：1 次请求 vs 13 次；体验更顺
|
||||
- 缺点：等于把 3.1 + N 次 state 读放到一个 endpoint，实现稍复杂
|
||||
- 推荐：**先做 3.1，3.2 暂缓**；前端用现有 endpoint 串起来够用
|
||||
|
||||
### 3.3 复用（**无需改动**）
|
||||
|
||||
| Endpoint | 用途 |
|
||||
|---|---|
|
||||
| `GET /api/threads/{tid}/state` | 取席位 / 总控线程的完整状态，提取最后一条 AIMessage content |
|
||||
| `GET /api/threads/{tid}/artifacts/{path}` | 点击文件名预览或下载（已有 `?download=true` 支持） |
|
||||
|
||||
> Note: 这两个 endpoint 已经在 `app.gateway.routers.threads` / `app.gateway.routers.artifacts` 里实现，前端 `fetch-client` 也有现成调用方式。
|
||||
|
||||
---
|
||||
|
||||
## 4. 前后端对接流程
|
||||
|
||||
### 4.1 进入 step3 时
|
||||
|
||||
```ts
|
||||
// 触发条件：runOrchestration 自然结束（leaderRes.dispatched.length === 0
|
||||
// 且无 clarification），用户点"达成共识生成全案成果"按钮 / 自动跳转。
|
||||
|
||||
// 前端手里已有：threadIds, coordinatorName, 最后的 leaderRes
|
||||
// 1. 总控结论文本 — 已在内存，直接用
|
||||
const consensusText = lastLeaderRes.content;
|
||||
|
||||
// 2. 各席位交付 — 已在 step2RoundtableDialogues 里，过滤"子智能体交付"的卡片
|
||||
const seatDeliveries = step2RoundtableDialogues
|
||||
.filter(d => d.confidence === "子智能体交付")
|
||||
.map(d => ({ sender: d.sender, content: d.content }));
|
||||
|
||||
// 3. 文件清单 — 调新接口
|
||||
const filesPerSeat = await Promise.all(
|
||||
Object.entries(threadIds)
|
||||
.filter(([name]) => name !== coordinatorName)
|
||||
.map(async ([name, tid]) => ({
|
||||
agentName: name,
|
||||
files: (await fetch(`/api/threads/${tid}/artifacts`).then(r => r.json())).files,
|
||||
})),
|
||||
);
|
||||
```
|
||||
|
||||
### 4.2 用户点击文件时
|
||||
|
||||
```ts
|
||||
// 在线预览（mime 是 markdown/text/pdf 自动 inline）
|
||||
window.open(`/api/threads/${threadId}/artifacts/${encodeURIComponent(filePath)}`);
|
||||
|
||||
// 强制下载
|
||||
window.open(`/api/threads/${threadId}/artifacts/${encodeURIComponent(filePath)}?download=true`);
|
||||
```
|
||||
|
||||
### 4.3 "重新起草新规划" 按钮
|
||||
|
||||
```ts
|
||||
// 跟现在一样，纯前端：清掉 dialogues + 跳 step1
|
||||
setCurrentStep(1);
|
||||
setInteractiveMessages(...); // 已有逻辑
|
||||
setStep2RoundtableDialogues([]);
|
||||
// 不需要调任何接口
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 改造前端的具体文件清单
|
||||
|
||||
| 文件 | 改动 |
|
||||
|---|---|
|
||||
| `frontend-web/src/roundtable-planning/components/HighFidelityReport.tsx` | **大改**。删除四张 metric 卡 / 三阶段路线图 / 论证要件 / 裁定判词；新增结论卡 + 席位折叠列表 + 文件清单 |
|
||||
| `frontend-web/src/roundtable-planning/api/multi-agent.ts` | 新增 `listSessionArtifacts(threadId)` helper（封装 §3.1 接口） |
|
||||
| `frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx` | 把 `threadIds` / `coordinatorName` / `lastLeaderContent` 传进 `HighFidelityReport` 的 props（目前没传） |
|
||||
|
||||
---
|
||||
|
||||
## 6. 改造后端的具体文件清单
|
||||
|
||||
| 文件 | 改动 |
|
||||
|---|---|
|
||||
| `offline-backend-20260512/backend/app/gateway/routers/artifacts.py` | 新增 `GET /api/threads/{tid}/artifacts`（不带 path，列目录） |
|
||||
| `offline-backend-20260512/backend/CLAUDE.md` | 在 artifacts 路由表里增加新条目说明 |
|
||||
| `offline-backend-20260512/backend/tests/test_artifacts_list.py` | 列目录新接口的单测（覆盖：空目录返回 [];traversal 路径返回 403;不存在 thread 返回 404）|
|
||||
|
||||
---
|
||||
|
||||
## 7. 实施优先级
|
||||
|
||||
| 优先级 | 项 | 备注 |
|
||||
|---|---|---|
|
||||
| P0 | 新增 `GET /api/threads/{tid}/artifacts` 列文件接口 | 必需，没它前端无法列文件 |
|
||||
| P0 | step3 大改：删 mock 区块、加结论/席位/文件三块 | 主要价值改造 |
|
||||
| P1 | 前端 helper `listSessionArtifacts` | 封装 fetch + 类型 |
|
||||
| P2 | 单测 `test_artifacts_list.py` | 上线后跟进 |
|
||||
| P3 | `POST /api/multi-agent/sessions/summary` 聚合接口 | 13 次→1 次，体感优化，**非必需** |
|
||||
|
||||
---
|
||||
|
||||
## 8. 显式不做的事 ❌
|
||||
|
||||
1. **不做"PDF 导出"**：后端没有现成 PDF 渲染管线，要做就是单独的项目。当前页面那个 `导出方案 PDF` 按钮直接删掉，或者保留按钮但点击只触发 `window.print()`（让浏览器自己生成 PDF）。
|
||||
2. **不做"安全分享"**：项目里已有 `/api/thread-shares`（per-thread 分享）和 `/api/public/shares`（公开页面），但那是针对单个 thread 的，不是多 thread 会话的。要做"多 thread 整合分享"是新功能，远超 step3 的范围。
|
||||
3. **不做"指标雷达图"**（什么 90.3 分总评）：没有真实数据源，强行加只会变成下一个 mock。
|
||||
4. **不做"签发投产"**：纯展示按钮，不接业务系统，删。
|
||||
5. **不做"轮次/对抗次数"显示**：除非前端记一下 `dispatch_count`，否则后端没现成统计。如果真要展示，用现成的"派活了几次"代替"对抗 N 轮"。
|
||||
|
||||
---
|
||||
|
||||
## 9. 验收清单
|
||||
|
||||
step3 改造完成后应该能：
|
||||
|
||||
- [ ] 看到当前 session 的总控最终结论，markdown 渲染
|
||||
- [ ] 看到 6 个席位各自的最终交付内容（默认折叠，点击展开）
|
||||
- [ ] 看到所有 sub-agent 写到 outputs 的文件列表，含文件名、大小、类型 icon
|
||||
- [ ] 点击文件名能在线预览（markdown / pdf / 图片）
|
||||
- [ ] 点击下载按钮能下载（带正确文件名）
|
||||
- [ ] 点"重新起草新规划"能回到 step1 且 step2 内存清空
|
||||
- [ ] 页面不再包含任何来自 `budgetLimit` 的"假指标"
|
||||
|
||||
---
|
||||
|
||||
## 10. 路径速查
|
||||
|
||||
| 资源 | 位置 |
|
||||
|---|---|
|
||||
| Step 3 组件 | `frontend-web/src/roundtable-planning/components/HighFidelityReport.tsx` |
|
||||
| 父页面 (state 持有者) | `frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx` |
|
||||
| 前端 API helper | `frontend-web/src/roundtable-planning/api/multi-agent.ts` |
|
||||
| 后端 artifacts 路由 | `offline-backend-20260512/backend/app/gateway/routers/artifacts.py` |
|
||||
| 后端 multi-agent 路由 | `offline-backend-20260512/backend/app/gateway/routers/multi_agent.py` |
|
||||
| 物理 outputs 目录 | `backend/.deer-flow/users/{user_id}/threads/{thread_id}/user-data/outputs/` |
|
||||
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
@@ -1,312 +0,0 @@
|
||||
# Open Canvas 集成进度文档
|
||||
|
||||
> 最后更新：2026-05-16
|
||||
> 当前分支：dhk-1
|
||||
|
||||
---
|
||||
|
||||
## 一、整体进度概览
|
||||
|
||||
### Canvas 系统（双栏写作/编码工作区）
|
||||
|
||||
| 阶段 | 名称 | 状态 |
|
||||
|------|------|------|
|
||||
| 阶段一 | 前端路由与目录骨架 | ✅ 已完成 |
|
||||
| 阶段二 | Canvas 双栏布局 | ✅ 已完成 |
|
||||
| 阶段三 | 前端 artifact 类型定义 | ✅ 已完成 |
|
||||
| 阶段四 | 后端 ThreadState 扩展 | ✅ 已完成 |
|
||||
| 阶段五 | canvas_agent 注册 + 最小节点闭环 | ✅ 已完成 |
|
||||
| 阶段六 | 前后端流式同步 | ✅ 已完成 |
|
||||
| 阶段七 | 版本历史导航 | ✅ 已完成 |
|
||||
| 阶段八 | 局部选区改写（Writing Editor 级） | ✅ 已完成 |
|
||||
| 阶段九 | 快捷动作系统 | ✅ 已完成 |
|
||||
| 阶段十 | 本地模型选择支持 | ✅ 已完成 |
|
||||
|
||||
### AI Writing Editor（文本 artifact 编辑器内置 AI 改写）
|
||||
|
||||
| 步骤 | 名称 | 状态 |
|
||||
|------|------|------|
|
||||
| Step 1 | Tiptap 编辑器核心 | ✅ 已完成 |
|
||||
| Step 2 | 写作工具栏 + 模型选择器 | ✅ 已完成 |
|
||||
| Step 3a | 气泡菜单（选区 AI 改写入口） | ✅ 已完成 |
|
||||
| Step 3b | 段落悬停按钮（整段 AI 改写入口） | ✅ 已完成 |
|
||||
| Step 4 | AI 改写菜单 + SSE 流式接口 | ✅ 已完成 |
|
||||
| Step 5 | 候选结果预览 + 替换/插入 | ✅ 已完成 |
|
||||
| Step 6 | 后端 `POST /api/writing/rewrite`（SSE，思考分离） | ✅ 已完成 |
|
||||
| Step 7 | 视觉精修（字体、间距、排版） | ✅ 已完成 |
|
||||
|
||||
**当前状态：全部功能已完成 🎉**
|
||||
|
||||
---
|
||||
|
||||
## 二、已完成工作详情
|
||||
|
||||
### 2.1 前端核心文件结构
|
||||
|
||||
```
|
||||
frontend-web/src/open-canvas/
|
||||
├── api/
|
||||
│ ├── client.ts # LangGraph SDK 客户端实例
|
||||
│ ├── models.ts # 模型列表 API
|
||||
│ ├── rewrite.ts # AI 改写 SSE 流（streamRewrite，parseSse）
|
||||
│ ├── runs.ts # streamCanvasRun（老的直接 API，已停用）
|
||||
│ └── threads.ts # createCanvasThread、getCanvasThread
|
||||
├── components/
|
||||
│ ├── artifact/
|
||||
│ │ ├── CanvasArtifactHeader.tsx # 右栏顶部：标题、语言、版本导航
|
||||
│ │ ├── CanvasArtifactPanel.tsx # 右栏：流式预览 / 编辑器 / 空状态
|
||||
│ │ ├── CanvasArtifactVersionNav.tsx # prev/next 版本切换
|
||||
│ │ ├── CanvasEmptyState.tsx # 5 种快速开始模板
|
||||
│ │ ├── CanvasQuickActionBar.tsx # 快捷动作按钮栏
|
||||
│ │ ├── CodeArtifactRenderer.tsx # CodeMirror 代码编辑器
|
||||
│ │ ├── TextArtifactRenderer.tsx # Tiptap 文本编辑器 + AI 改写流程
|
||||
│ │ ├── WritingAiMenu.tsx # AI 改写动作菜单（polish/expand/shorten/tone）
|
||||
│ │ ├── WritingBubbleMenu.tsx # 选区气泡菜单（portal 实现）
|
||||
│ │ ├── WritingParagraphMenu.tsx # 段落悬停 AI 改写按钮
|
||||
│ │ ├── WritingRewritePreview.tsx # 改写结果预览面板（含思考过程展开）
|
||||
│ │ └── WritingToolbar.tsx # 格式工具栏（含模型选择器）
|
||||
│ ├── chat/
|
||||
│ │ └── CanvasChatPanel.tsx # 左栏：消息列表 + 输入框
|
||||
│ ├── layout/
|
||||
│ │ ├── CanvasHeader.tsx # 顶部栏：返回、折叠、流式指示
|
||||
│ │ ├── CanvasResizableLayout.tsx # 左右可拖拽双栏（含 CanvasStreamProvider）
|
||||
│ │ └── CanvasShell.tsx # 顶层壳：加载已有线程状态
|
||||
│ └── selectors/
|
||||
│ └── CanvasModelSelector.tsx # 模型下拉选择器
|
||||
├── contexts/
|
||||
│ ├── CanvasGraphContext.tsx # artifact、streamingArtifact、isStreaming
|
||||
│ ├── CanvasStreamContext.tsx # 共享 useCanvasThreadStream 实例（sendMessage）
|
||||
│ ├── CanvasThreadContext.tsx # threadId、modelName
|
||||
│ └── CanvasUIContext.tsx # isChatCollapsed、writingSelection
|
||||
├── editor/
|
||||
│ ├── TiptapEditor.tsx # EditorContent 包装器
|
||||
│ └── TiptapExtensions.ts # StarterKit + Underline + Placeholder + Markdown
|
||||
├── hooks/
|
||||
│ ├── useCanvasArtifact.ts # artifact 初始化工具
|
||||
│ ├── useCanvasQuickActions.ts # 快捷动作触发（走 CanvasStreamContext）
|
||||
│ ├── useCanvasSelection.ts # 文字/代码选区状态
|
||||
│ ├── useCanvasStream.ts # 旧直接 API 流（已停用，保留备用）
|
||||
│ ├── useCanvasThread.ts # 线程加载工具
|
||||
│ ├── useCanvasThreadStream.ts # LangGraph SDK useStream hook（主流）
|
||||
│ ├── useWritingEditor.ts # Tiptap editor 实例管理
|
||||
│ └── useWritingRewrite.ts # AI 改写状态机（ThinkTagParser、AbortController）
|
||||
├── pages/
|
||||
│ ├── CanvasHomePage.tsx # 欢迎页 + 快速开始
|
||||
│ └── CanvasThreadPage.tsx # Provider 装配层
|
||||
├── routes/
|
||||
│ └── OpenCanvasRoutes.tsx # /page/canvas/* 子路由
|
||||
├── types/
|
||||
│ ├── artifact.ts # CanvasArtifact、CanvasArtifactText、CanvasArtifactCode
|
||||
│ ├── model.ts # CanvasModel
|
||||
│ ├── quick-action.ts # QuickAction、QuickActionId
|
||||
│ ├── selection.ts # CanvasTextSelection、CanvasCodeSelection
|
||||
│ └── thread.ts # CanvasMessage、CanvasThreadValues
|
||||
└── utils/
|
||||
├── apply-rewrite.ts # applyReplace、applyInsert（Tiptap 事务）
|
||||
├── artifact.ts # getCurrentArtifactContent、setCurrentArtifactIndex 等
|
||||
├── quick-actions.ts # buildQuickActionMessage（含 artifact 内容注入）
|
||||
├── selection.ts # buildMessageWithSelection
|
||||
├── stream.ts # 流式工具
|
||||
└── thread.ts # 线程工具
|
||||
```
|
||||
|
||||
### 2.2 后端核心文件结构
|
||||
|
||||
```
|
||||
offline-backend-20260512/backend/
|
||||
├── packages/harness/deerflow/agents/
|
||||
│ ├── canvas_agent/
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── agent.py # make_canvas_agent()：LangGraph graph 工厂
|
||||
│ │ ├── prompt.py # build_canvas_system_prompt()：含 selection_rewrite + quick_actions
|
||||
│ │ └── tools.py # update_artifact_tool：创建/追加 artifact 版本
|
||||
│ └── thread_state.py # ThreadState（含 artifact 字段、CanvasArtifact TypedDict）
|
||||
└── app/gateway/
|
||||
├── app.py # 注册 writing router
|
||||
└── routers/
|
||||
└── writing.py # POST /api/writing/rewrite（SSE 流式）
|
||||
```
|
||||
|
||||
**langgraph.json** 注册了两个 graph：
|
||||
- `lead_agent` → 主聊天 Agent
|
||||
- `canvas_agent` → Canvas 写作 Agent
|
||||
|
||||
### 2.3 关键 Context 层级
|
||||
|
||||
```
|
||||
CanvasThreadPage
|
||||
├── CanvasThreadProvider # threadId、modelName
|
||||
│ ├── CanvasGraphProvider # artifact、streamingArtifact、isStreaming
|
||||
│ │ └── CanvasUIProvider # isChatCollapsed、writingSelection
|
||||
│ │ └── CanvasShell
|
||||
│ │ └── CanvasResizableLayout
|
||||
│ │ └── CanvasStreamProvider ← 持有 useCanvasThreadStream 单例
|
||||
│ │ ├── CanvasChatPanel # 读 useCanvasStreamContext()
|
||||
│ │ └── CanvasArtifactPanel
|
||||
│ │ └── CanvasQuickActionBar # 读 useCanvasStreamContext()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、关键架构决策与注意事项
|
||||
|
||||
### 3.1 流式架构：单例流（重要）
|
||||
|
||||
**问题**：原先 `CanvasChatPanel` 调 `useCanvasThreadStream()`，`CanvasQuickActionBar` 调 `useCanvasStream()`（旧的直接 API），两套流互不相通，快捷动作响应不出现在聊天面板。
|
||||
|
||||
**解决方案**：新增 `CanvasStreamContext`，在 `CanvasResizableLayout` 中调用 `useCanvasThreadStream()` 一次，通过 Context 共享给所有子组件。`CanvasChatPanel` 和 `useCanvasQuickActions` 都从 `useCanvasStreamContext()` 取 `sendMessage`。
|
||||
|
||||
```
|
||||
useCanvasStream（旧，已停用） ← 不再被调用，保留备用
|
||||
useCanvasThreadStream（新，LangGraph SDK） ← 通过 CanvasStreamContext 统一共享
|
||||
```
|
||||
|
||||
### 3.2 artifact 内容注入机制（重要）
|
||||
|
||||
**问题**：LangGraph `create_agent` 只把 `state.messages` 传给 LLM，`state.artifact` 字段不会自动可见。Agent 做 expand/shorten 等操作时看不到要改写的内容。
|
||||
|
||||
**解决方案**：在每次 `sendMessage` 时，把当前 artifact 内容以 `<artifact>` 标签嵌入人类消息末尾。
|
||||
|
||||
- 普通聊天：`sendMessage` 内部自动追加（仅当消息里还没有 `<artifact>` 时）
|
||||
- 快捷动作：`buildQuickActionMessage(id, content)` 在构建时就包含内容
|
||||
- 聊天面板显示时：`message-list-item.tsx` 调 `stripArtifactTag()` 剥掉标签，用户看不到
|
||||
|
||||
```typescript
|
||||
// utils/quick-actions.ts
|
||||
export function buildQuickActionMessage(id, content) {
|
||||
const body = isCodeArtifact(content) ? content.code : content.fullMarkdown;
|
||||
return `${instruction}\n\n<artifact ${tag}>\n${body}\n</artifact>`;
|
||||
}
|
||||
|
||||
// core/messages/utils.ts
|
||||
export function stripArtifactTag(content: string): string {
|
||||
return content.replace(/<artifact[^>]*>[\s\S]*?<\/artifact>/g, "").trim();
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 ThinkTagParser（AI 改写思考过程解析）
|
||||
|
||||
后端支持两种思考格式：
|
||||
- Anthropic：独立 thinking block，以 `event: thinking` SSE 事件传输
|
||||
- DeepSeek：把思考过程内联在文本里：`<think>...</think>content`
|
||||
|
||||
前端 `useWritingRewrite.ts` 的 `ThinkTagParser` 是流式状态机，处理跨 chunk 边界的 `<think>` 标签。
|
||||
|
||||
### 3.4 版本历史：本地切换
|
||||
|
||||
`CanvasArtifactVersionNav` 的 prev/next 只修改本地 `CanvasGraphContext.artifact.currentIndex`，不写回后端。刷新后 currentIndex 重置为后端存储的最新值（这是有意的简化设计）。
|
||||
|
||||
### 3.5 Writing Editor 流程（三阶段状态机）
|
||||
|
||||
```
|
||||
idle → menu → preview → idle
|
||||
↑ ↓
|
||||
openAiMenu closeAll
|
||||
```
|
||||
|
||||
- **idle**：正常编辑
|
||||
- **menu**：显示 `WritingAiMenu`（选择 polish/expand/shorten/tone）
|
||||
- **preview**：显示 `WritingRewritePreview`（SSE 流式结果 + 思考过程 + 替换/插入按钮）
|
||||
|
||||
---
|
||||
|
||||
## 四、已解决的技术难题
|
||||
|
||||
| 问题 | 解法 |
|
||||
|------|------|
|
||||
| react-resizable-panels v4 API 变更（`orientation` 不是 `direction`，`groupRef` 不是 `ref`，`setLayout` 参数为 `{id: size}` 对象） | 参考 v4 文档，逐一修正 |
|
||||
| Flex 高度链底部裁剪 | 在 wrapper div 加 `min-h-0`，配合 `flex-1 overflow-hidden` |
|
||||
| Tiptap v3 BubbleMenu 已从 React 组件改为纯 Extension | 自定义 portal 实现：监听 `selectionUpdate`，手动计算位置 |
|
||||
| 段落悬停按钮鼠标桥接：鼠标经过 6px 间隙时按钮消失 | 文档级 `mousemove` 监听 + 380ms 延迟隐藏，判断鼠标是否在扩展热区内 |
|
||||
| 弹窗超出屏幕底部 | 检测 `spaceBelow` vs `spaceAbove`，空间不足时翻转到光标上方 |
|
||||
| DeepSeek 在文本流里混入 `<think>` 标签 | `ThinkTagParser` 状态机，保留最后 6/7 字节防止跨 chunk 分割 |
|
||||
| loading→success 状态转换检测（stale closure） | 用 `prevStatusRef` + `useEffect` 检测 status 变化，取代直接读 state |
|
||||
| 快捷动作响应不出现在聊天面板 | `CanvasStreamContext` 统一 `sendMessage` 入口 |
|
||||
| LLM 看不到 artifact 内容（只有 state.messages） | 消息里直接嵌入 `<artifact>` 标签，显示时剥离 |
|
||||
| `<artifact>` 标签在聊天面板里显示 | `message-list-item.tsx` 调 `stripArtifactTag()` |
|
||||
|
||||
---
|
||||
|
||||
## 五、当前已知限制（非 bug，设计取舍）
|
||||
|
||||
1. **版本切换不持久化**：切换 artifact 版本后刷新页面会回到最新版本
|
||||
2. **useCanvasStream 孤立**：旧的直接 API 流 hook 保留但未被调用，可后续清理
|
||||
3. **CanvasShell 的 setMessages 冗余**：加载旧线程时 `setMessages` 写入 CanvasGraphContext，但 `CanvasChatPanel` 读的是 `thread.messages`（来自 useStream + fetchStateHistory）。setArtifact 仍有效
|
||||
4. **artifact 内容随消息发送**：大文档每条消息都附带全文，token 消耗较大。当前规模可接受
|
||||
|
||||
---
|
||||
|
||||
## 六、快速开始下一次工作
|
||||
|
||||
### 启动服务
|
||||
|
||||
```bash
|
||||
# 后端（从 offline-backend-20260512/backend/）
|
||||
make dev # 启动 Gateway API on port 8001
|
||||
|
||||
# 前端（从 frontend-web/）
|
||||
pnpm dev # 启动 Vite on port 5174
|
||||
```
|
||||
|
||||
### 访问路径
|
||||
|
||||
- 主页：`http://localhost:5174`
|
||||
- Canvas 入口：点击左侧导航 → Canvas，或直接访问 `http://localhost:5174/page/canvas`
|
||||
|
||||
### 类型检查
|
||||
|
||||
```bash
|
||||
cd frontend-web && pnpm typecheck
|
||||
# 预期：只有 CodeArtifactRenderer.tsx 的 CodeMirror 版本冲突错误（预存 bug，不影响运行）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、如需继续开发的潜在方向
|
||||
|
||||
| 方向 | 描述 | 优先级 |
|
||||
|------|------|------|
|
||||
| 版本切换持久化 | 将 currentIndex 变更写回后端 ThreadState | 低 |
|
||||
| artifact 内容 token 优化 | 仅发送 diff 或用 summary 代替全文 | 低 |
|
||||
| 清理 useCanvasStream | 删除未被调用的旧 hook | 低 |
|
||||
| 代码 artifact 的 AI 改写 | CodeArtifactRenderer 也接入 WritingAiMenu 流程 | 中 |
|
||||
| Canvas 选区→聊天（高级） | 用户在右栏选中文字后在左栏输入指令，自动带选区上下文 | 中 |
|
||||
| Tiptap 扩展（表格、任务列表） | 增加 Table、TaskList extension | 低 |
|
||||
|
||||
---
|
||||
|
||||
## 八、关键文件速查
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `frontend-web/docs/openCanvas-progress.md` | **本文档** |
|
||||
| `frontend-web/src/open-canvas/contexts/CanvasStreamContext.tsx` | 流单例 Context |
|
||||
| `frontend-web/src/open-canvas/hooks/useCanvasThreadStream.ts` | 主流 hook（LangGraph SDK） |
|
||||
| `frontend-web/src/open-canvas/hooks/useWritingRewrite.ts` | AI 改写状态机 |
|
||||
| `frontend-web/src/open-canvas/api/rewrite.ts` | 改写 SSE 客户端 |
|
||||
| `frontend-web/src/open-canvas/utils/quick-actions.ts` | 快捷动作消息构建 |
|
||||
| `frontend-web/src/core/messages/utils.ts` | `stripArtifactTag` 在此 |
|
||||
| `frontend-web/src/components/workspace/messages/message-list-item.tsx` | 调用 stripArtifactTag 的位置 |
|
||||
| `frontend-web/src/styles/globals.css` | Tiptap 写作编辑器样式（`.tiptap-writing-editor`） |
|
||||
| `offline-backend-20260512/backend/packages/harness/deerflow/agents/canvas_agent/agent.py` | canvas_agent 工厂 |
|
||||
| `offline-backend-20260512/backend/packages/harness/deerflow/agents/canvas_agent/tools.py` | update_artifact_tool |
|
||||
| `offline-backend-20260512/backend/packages/harness/deerflow/agents/canvas_agent/prompt.py` | 系统提示词 |
|
||||
| `offline-backend-20260512/backend/app/gateway/routers/writing.py` | AI 改写后端接口 |
|
||||
| `offline-backend-20260512/backend/langgraph.json` | canvas_agent 注册 |
|
||||
|
||||
---
|
||||
|
||||
## 九、开始新对话的推荐提示词
|
||||
|
||||
```
|
||||
我们在开发 DeerFlow 的 Canvas 写作模式（open-canvas 集成）。
|
||||
详细进度见：frontend-web/docs/openCanvas-progress.md
|
||||
|
||||
当前全部功能已完成，包括：
|
||||
- Canvas 双栏布局、canvas_agent、版本历史
|
||||
- AI Writing Editor（Tiptap + SSE 改写 + 思考过程展开）
|
||||
- 快捷动作（通过 CanvasStreamContext 统一流）
|
||||
- artifact 内容注入（消息里嵌入 <artifact> 标签，显示时剥离）
|
||||
|
||||
请根据进度文档第七节"潜在开发方向"或我指定的任务继续开发。
|
||||
```
|
||||
@@ -1,950 +0,0 @@
|
||||
# Open Canvas 模式需求拆解文档
|
||||
|
||||
## 1. 文档目标
|
||||
|
||||
本文档用于指导 DeerFlow 在现有架构中新增一个 `open-canvas` 风格的 Canvas 模式。
|
||||
|
||||
目标不是直接照搬 `langchain-ai/open-canvas` 的 Next.js + LangGraph.js 实现，而是在当前项目技术栈内完成一套等价能力的实现：
|
||||
|
||||
- 前端：基于 `React 19 + Vite + react-router-dom`
|
||||
- 后端：基于 `Python + FastAPI + LangGraph`
|
||||
- 模型层：支持云模型与本地模型自由配置
|
||||
- 状态层：支持结构化 artifact、版本历史、局部改写、快速动作、画布编辑
|
||||
|
||||
本文档重点是把需求拆成“可实现、可排期、可验收”的阶段性任务。
|
||||
|
||||
---
|
||||
|
||||
## 2. 最终目标
|
||||
|
||||
### 2.1 用户视角目标
|
||||
|
||||
用户进入一个新的 Canvas 工作模式后，可以获得与 open-canvas 接近的体验：
|
||||
|
||||
- 左侧是聊天区，右侧是 Canvas 编辑区
|
||||
- 可以从空白文本或代码模板快速开始
|
||||
- 可以通过聊天让 AI 生成一份结构化 artifact
|
||||
- 可以对 artifact 整体重写，也可以对选中的局部内容进行改写
|
||||
- artifact 支持版本历史切换
|
||||
- artifact 支持文本和代码两种主要类型
|
||||
- 支持快速动作，例如扩写、压缩、改风格、改语气、加注释、修 bug、换语言
|
||||
- 支持启用 Web 搜索增强
|
||||
- 支持切换模型
|
||||
- 支持使用本地模型，例如 Ollama 或 OpenAI-compatible 本地服务
|
||||
|
||||
### 2.2 工程视角目标
|
||||
|
||||
新增的 Canvas 模式需要满足以下工程原则：
|
||||
|
||||
- 不破坏现有 DeerFlow 工作区
|
||||
- 不影响现有基于 `artifacts: string[]` 的文件产物功能
|
||||
- 可逐阶段上线
|
||||
- 前后端状态协议清晰
|
||||
- 可兼容现有 LangGraph 线程、消息流、认证和模型接口
|
||||
|
||||
---
|
||||
|
||||
## 3. 范围定义
|
||||
|
||||
### 3.1 本次需求包含
|
||||
|
||||
- 前端新增 `open-canvas` 专用目录
|
||||
- 在 [PageRoutes.tsx](../src/pages/PageRoutes.tsx) 中引入新的 Canvas 路由
|
||||
- 前端新增 Canvas 页面、上下文、组件、状态管理
|
||||
- 后端新增 Canvas 专用线程状态字段
|
||||
- 后端新增 Canvas Agent 图或在现有 Agent 体系中新增 Canvas 模式分支
|
||||
- 模型配置统一为 DeerFlow 后端配置驱动
|
||||
- 支持本地大模型配置与模型列表动态下发
|
||||
- 支持结构化 artifact 的保存、读取、更新、版本切换
|
||||
|
||||
### 3.2 本次需求不包含
|
||||
|
||||
- 一次性复刻 open-canvas 全部 UI 细节
|
||||
- 完整照搬 Supabase 鉴权体系
|
||||
- 直接复用 open-canvas 的 Next.js API Route
|
||||
- 直接运行 open-canvas 的 LangGraph.js 后端
|
||||
- 首阶段就实现所有快捷动作、所有富文本效果、所有搜索增强能力
|
||||
|
||||
### 3.3 迁移原则
|
||||
|
||||
- 借鉴 open-canvas 的能力模型，不直接迁移其运行时架构
|
||||
- 前端尽量复用其交互设计和数据结构
|
||||
- 后端以 Python 实现同等能力
|
||||
- 配置以 DeerFlow 为真源，不以 open-canvas 的 TS 文件为真源
|
||||
|
||||
---
|
||||
|
||||
## 4. 总体设计思路
|
||||
|
||||
### 4.1 前端设计思路
|
||||
|
||||
在现有 `frontend-web/src` 下新增一个专用目录，例如：
|
||||
|
||||
```text
|
||||
src/
|
||||
open-canvas/
|
||||
pages/
|
||||
routes/
|
||||
components/
|
||||
contexts/
|
||||
hooks/
|
||||
types/
|
||||
api/
|
||||
utils/
|
||||
constants/
|
||||
```
|
||||
|
||||
建议将 Canvas 模式作为一个独立的页面子系统接入，而不是把现有工作区页面强行改造成 Canvas。
|
||||
|
||||
建议路由形式：
|
||||
|
||||
- `/canvas`
|
||||
- `/canvas/:threadId`
|
||||
|
||||
也可以挂在现有页面布局下，例如：
|
||||
|
||||
- `/workspace/canvas`
|
||||
- `/workspace/canvas/:threadId`
|
||||
|
||||
推荐优先采用独立一级功能路由：
|
||||
|
||||
- 逻辑更清晰
|
||||
- 状态隔离更容易
|
||||
- 不容易污染现有 `workspace` 功能
|
||||
|
||||
### 4.2 后端设计思路
|
||||
|
||||
后端不建议直接改造现有通用 Agent 去同时承担全部 Canvas 行为，而是建议采用以下两种方案之一：
|
||||
|
||||
#### 方案 A：新增独立 Canvas Assistant
|
||||
|
||||
- 新增 `canvas_agent`
|
||||
- 使用单独的 LangGraph 状态定义
|
||||
- 前端调用时通过 `assistant_id=canvas_agent`
|
||||
|
||||
优点：
|
||||
|
||||
- 与现有 `lead_agent` 隔离
|
||||
- 风险更低
|
||||
- 更容易对齐 open-canvas 的图结构
|
||||
|
||||
缺点：
|
||||
|
||||
- 会产生一套新的 Agent 图维护成本
|
||||
|
||||
#### 方案 B：在现有 Lead Agent 中增加 Canvas 模式分支
|
||||
|
||||
- 在 thread metadata 或 configurable 中增加 `ui_mode=canvas`
|
||||
- Agent 根据模式进入 Canvas 路径
|
||||
|
||||
优点：
|
||||
|
||||
- 统一入口
|
||||
|
||||
缺点：
|
||||
|
||||
- 会显著增加现有 Agent 复杂度
|
||||
- 容易影响现有聊天和文件产物模式
|
||||
|
||||
推荐先做方案 A。
|
||||
|
||||
### 4.3 模型配置设计思路
|
||||
|
||||
模型配置统一以 DeerFlow 后端 `config.yaml` 为真源。
|
||||
|
||||
前端不维护固定模型常量列表，而是通过 `/api/models` 获取模型能力元数据。
|
||||
|
||||
为了实现 open-canvas 风格体验，需要后端模型接口至少返回：
|
||||
|
||||
- `name`
|
||||
- `display_name`
|
||||
- `provider`
|
||||
- `supports_thinking`
|
||||
- `supports_reasoning_effort`
|
||||
- `supports_vision`
|
||||
- `supports_tool_calling`
|
||||
- `supports_artifact_editing`
|
||||
- `supports_code_editing`
|
||||
- `temperature_range`
|
||||
- `max_tokens_range`
|
||||
- `base_url_source` 或 provider 标识
|
||||
- `is_local`
|
||||
|
||||
---
|
||||
|
||||
## 5. 与当前项目的关键差异
|
||||
|
||||
### 5.1 当前 DeerFlow 现状
|
||||
|
||||
当前 DeerFlow 线程状态中的 artifact 主要是文件路径列表：
|
||||
|
||||
- `artifacts: string[]`
|
||||
|
||||
这更接近“生成文件产物”的工作模式。
|
||||
|
||||
前端当前 artifact 面板也主要是：
|
||||
|
||||
- 文件列表
|
||||
- 文件详情
|
||||
- 文件下载/预览
|
||||
|
||||
### 5.2 open-canvas 的关键能力
|
||||
|
||||
open-canvas 的核心不是“生成文件”，而是“维护一个结构化的当前文档对象”：
|
||||
|
||||
- 一个 conversation 对应一个主 artifact
|
||||
- artifact 具有类型、标题、内容、版本
|
||||
- 用户可以选中部分内容让 AI 改写
|
||||
- 每次改写都会生成新版本
|
||||
|
||||
### 5.3 需要新增的核心能力
|
||||
|
||||
为支持 Canvas 模式，需要在 DeerFlow 中新增一套结构化 artifact 状态：
|
||||
|
||||
- 当前 artifact
|
||||
- 当前版本索引
|
||||
- 历史版本列表
|
||||
- 选区信息
|
||||
- 当前编辑模式
|
||||
- 快速动作状态
|
||||
- Web 搜索结果状态
|
||||
|
||||
---
|
||||
|
||||
## 6. 分阶段实施方案
|
||||
|
||||
以下为推荐的 8 个阶段，每个阶段都可单独开发、联调和验收。
|
||||
|
||||
---
|
||||
|
||||
## 7. 阶段一：前端路由与目录骨架
|
||||
|
||||
### 7.1 目标
|
||||
|
||||
在不影响现有页面的前提下，建立 Canvas 模式的前端骨架。
|
||||
|
||||
### 7.2 需求
|
||||
|
||||
- 新增 `src/open-canvas/` 目录
|
||||
- 新增 Canvas 页面路由
|
||||
- 将路由接入 [PageRoutes.tsx](../src/pages/PageRoutes.tsx)
|
||||
- 提供 Canvas 首页和 Canvas Thread 页
|
||||
- 支持空状态展示
|
||||
|
||||
### 7.3 建议目录
|
||||
|
||||
```text
|
||||
src/open-canvas/
|
||||
api/
|
||||
threads.ts
|
||||
runs.ts
|
||||
models.ts
|
||||
components/
|
||||
layout/
|
||||
chat/
|
||||
canvas/
|
||||
artifacts/
|
||||
quick-actions/
|
||||
selectors/
|
||||
contexts/
|
||||
CanvasThreadContext.tsx
|
||||
CanvasGraphContext.tsx
|
||||
CanvasUIContext.tsx
|
||||
hooks/
|
||||
useCanvasThread.ts
|
||||
useCanvasStream.ts
|
||||
useCanvasArtifact.ts
|
||||
pages/
|
||||
CanvasHomePage.tsx
|
||||
CanvasThreadPage.tsx
|
||||
routes/
|
||||
OpenCanvasRoutes.tsx
|
||||
types/
|
||||
artifact.ts
|
||||
thread.ts
|
||||
model.ts
|
||||
utils/
|
||||
artifact.ts
|
||||
selection.ts
|
||||
stream.ts
|
||||
constants/
|
||||
index.ts
|
||||
```
|
||||
|
||||
### 7.4 路由建议
|
||||
|
||||
- 在 `PageRoutes.tsx` 中新增 `canvas/*`
|
||||
- 在 `src/open-canvas/routes/OpenCanvasRoutes.tsx` 中维护子路由
|
||||
|
||||
建议形式：
|
||||
|
||||
```text
|
||||
/canvas
|
||||
/canvas/:threadId
|
||||
```
|
||||
|
||||
### 7.5 验收标准
|
||||
|
||||
- 能访问 Canvas 首页
|
||||
- 能访问指定 thread 的 Canvas 页面
|
||||
- 不影响现有 `workspace/*` 与 `strategy/*`
|
||||
- 页面有独立布局骨架
|
||||
|
||||
---
|
||||
|
||||
## 8. 阶段二：前端 Canvas 布局与交互容器
|
||||
|
||||
### 8.1 目标
|
||||
|
||||
先做出“左聊天、右画布”的基础容器，不接真实 AI 改写逻辑。
|
||||
|
||||
### 8.2 需求
|
||||
|
||||
- 左侧聊天区
|
||||
- 右侧画布区
|
||||
- 支持面板拖拽或折叠
|
||||
- 初始空状态
|
||||
- 支持“快速开始”：
|
||||
- 新建空白文本 artifact
|
||||
- 新建代码 artifact
|
||||
|
||||
### 8.3 组件拆分建议
|
||||
|
||||
- `CanvasShell`
|
||||
- `CanvasSidebar`
|
||||
- `CanvasChatPanel`
|
||||
- `CanvasArtifactPanel`
|
||||
- `CanvasEmptyState`
|
||||
- `QuickStartActions`
|
||||
|
||||
### 8.4 快速开始能力
|
||||
|
||||
用户进入空线程时可以选择：
|
||||
|
||||
- 开始写文章
|
||||
- 开始写代码
|
||||
- 从模板开始
|
||||
|
||||
首版模板可只做最小集：
|
||||
|
||||
- 空白文档
|
||||
- HTML 模板
|
||||
- React 组件模板
|
||||
- Python 脚本模板
|
||||
|
||||
### 8.5 验收标准
|
||||
|
||||
- 页面可稳定展示双栏布局
|
||||
- 快速开始能创建前端本地 artifact 状态
|
||||
- 代码和文本可分别进入不同渲染器
|
||||
|
||||
---
|
||||
|
||||
## 9. 阶段三：结构化 Artifact 数据模型
|
||||
|
||||
### 9.1 目标
|
||||
|
||||
定义 DeerFlow 的 Canvas Artifact 协议，作为前后端统一契约。
|
||||
|
||||
### 9.2 核心要求
|
||||
|
||||
需要支持以下能力：
|
||||
|
||||
- 文本 artifact
|
||||
- 代码 artifact
|
||||
- 标题
|
||||
- 当前版本索引
|
||||
- 版本历史
|
||||
- 当前选中版本切换
|
||||
- 后续支持局部高亮编辑
|
||||
|
||||
### 9.3 建议数据结构
|
||||
|
||||
```ts
|
||||
type CanvasArtifact = {
|
||||
currentIndex: number;
|
||||
contents: Array<CanvasArtifactText | CanvasArtifactCode>;
|
||||
};
|
||||
|
||||
type CanvasArtifactText = {
|
||||
index: number;
|
||||
type: "text";
|
||||
title: string;
|
||||
fullMarkdown: string;
|
||||
};
|
||||
|
||||
type CanvasArtifactCode = {
|
||||
index: number;
|
||||
type: "code";
|
||||
title: string;
|
||||
language: string;
|
||||
code: string;
|
||||
};
|
||||
```
|
||||
|
||||
### 9.4 线程状态建议新增字段
|
||||
|
||||
前端与后端需共同支持：
|
||||
|
||||
- `artifact`
|
||||
- `highlighted_text`
|
||||
- `highlighted_code`
|
||||
- `canvas_mode`
|
||||
- `web_search_enabled`
|
||||
- `web_search_results`
|
||||
- `quick_action_id`
|
||||
|
||||
### 9.5 与现有 `artifacts: string[]` 的关系
|
||||
|
||||
建议保留现有 `artifacts: string[]` 不动。
|
||||
|
||||
新增字段：
|
||||
|
||||
- `artifact` 用于 Canvas 主文档
|
||||
- `artifacts` 继续用于文件产物
|
||||
|
||||
这样可以兼容未来“Canvas 生成网页文件、导出文件、保存文件”的场景。
|
||||
|
||||
### 9.6 验收标准
|
||||
|
||||
- 前端类型定义完成
|
||||
- 后端状态字段设计完成
|
||||
- 确认与现有线程状态兼容
|
||||
|
||||
---
|
||||
|
||||
## 10. 阶段四：后端线程状态与 API 扩展
|
||||
|
||||
### 10.1 目标
|
||||
|
||||
让后端线程状态可以安全存储和返回 Canvas Artifact。
|
||||
|
||||
### 10.2 需求
|
||||
|
||||
- 扩展 Python `ThreadState`
|
||||
- 扩展状态序列化逻辑
|
||||
- 确保 `/api/threads/*` 返回结构化 `artifact`
|
||||
- 确保 LangGraph 流中可带上 `artifact` 更新
|
||||
|
||||
### 10.3 后端改造点
|
||||
|
||||
建议关注以下模块：
|
||||
|
||||
- `packages/harness/deerflow/agents/thread_state.py`
|
||||
- 线程 state serializer
|
||||
- `app/gateway/routers/threads.py`
|
||||
- 流事件适配层
|
||||
|
||||
### 10.4 注意事项
|
||||
|
||||
- 旧线程没有 `artifact` 字段时必须兼容
|
||||
- 状态更新不能破坏现有消息结构
|
||||
- 必须确保 JSON 可序列化
|
||||
|
||||
### 10.5 验收标准
|
||||
|
||||
- 新建线程可写入 `artifact`
|
||||
- 读取线程时可返回 `artifact`
|
||||
- 不影响现有线程读取
|
||||
- 前端能从线程 state 中恢复 Canvas 内容
|
||||
|
||||
---
|
||||
|
||||
## 11. 阶段五：Canvas 专用 Agent 图
|
||||
|
||||
### 11.1 目标
|
||||
|
||||
实现与 open-canvas 类似的 AI 路由能力。
|
||||
|
||||
### 11.2 推荐方案
|
||||
|
||||
新增 `canvas_agent`，单独维护图逻辑。
|
||||
|
||||
### 11.3 节点拆分建议
|
||||
|
||||
首版建议至少拆成这些节点：
|
||||
|
||||
- `route_user_intent`
|
||||
- `reply_general_input`
|
||||
- `generate_artifact`
|
||||
- `rewrite_artifact`
|
||||
- `update_highlighted_text`
|
||||
- `update_highlighted_code`
|
||||
- `generate_followup`
|
||||
|
||||
二期可加：
|
||||
|
||||
- `rewrite_artifact_theme`
|
||||
- `rewrite_code_theme`
|
||||
- `change_length`
|
||||
- `change_reading_level`
|
||||
- `translate_artifact`
|
||||
- `add_comments`
|
||||
- `add_logs`
|
||||
- `fix_bugs`
|
||||
- `port_language`
|
||||
- `web_search_enrich`
|
||||
|
||||
### 11.4 路由逻辑要求
|
||||
|
||||
系统需要能判断：
|
||||
|
||||
- 用户是在闲聊
|
||||
- 用户要新生成 artifact
|
||||
- 用户要整体重写当前 artifact
|
||||
- 用户要局部修改当前 artifact
|
||||
- 用户要执行某个快捷动作
|
||||
|
||||
### 11.5 状态输入要求
|
||||
|
||||
节点需要读取：
|
||||
|
||||
- 当前消息历史
|
||||
- 当前 artifact
|
||||
- 当前选区
|
||||
- 当前模型配置
|
||||
- Web 搜索开关
|
||||
|
||||
### 11.6 输出要求
|
||||
|
||||
节点输出必须能更新：
|
||||
|
||||
- `messages`
|
||||
- `artifact`
|
||||
- `web_search_results`
|
||||
- `followup`
|
||||
|
||||
### 11.7 验收标准
|
||||
|
||||
- 能根据输入创建新 artifact
|
||||
- 能根据输入整体改写 artifact
|
||||
- 能保留版本历史
|
||||
- 能在改写后返回自然语言 followup
|
||||
|
||||
---
|
||||
|
||||
## 12. 阶段六：前端流式同步与版本管理
|
||||
|
||||
### 12.1 目标
|
||||
|
||||
让前端能像 open-canvas 一样在流式过程中更新画布与聊天。
|
||||
|
||||
### 12.2 需求
|
||||
|
||||
- 复用现有 LangGraph stream client
|
||||
- 在 Canvas 模式中解析 `artifact` 更新
|
||||
- 支持流式文本更新
|
||||
- 支持版本切换
|
||||
- 支持断线后恢复线程状态
|
||||
|
||||
### 12.3 前端状态层建议
|
||||
|
||||
- `CanvasThreadContext`：线程基础信息
|
||||
- `CanvasGraphContext`：消息、artifact、streaming 状态
|
||||
- `CanvasUIContext`：面板、编辑态、选中态
|
||||
|
||||
### 12.4 关键能力
|
||||
|
||||
- 当前版本切换
|
||||
- 新版本创建后自动定位到最新版本
|
||||
- 手动编辑内容后保存
|
||||
- 流结束后线程状态持久化
|
||||
|
||||
### 12.5 验收标准
|
||||
|
||||
- 发送消息时聊天和画布可同步更新
|
||||
- 版本数会增加
|
||||
- 切换历史版本稳定
|
||||
- 刷新页面后线程状态能恢复
|
||||
|
||||
---
|
||||
|
||||
## 13. 阶段七：局部选区改写
|
||||
|
||||
### 13.1 目标
|
||||
|
||||
实现 Canvas 模式最关键的差异化能力之一：选中局部内容进行 AI 改写。
|
||||
|
||||
### 13.2 文本选区需求
|
||||
|
||||
- 支持在 Markdown 文本中选择一段文本
|
||||
- 记录选区位置与原始文本
|
||||
- 用户发出修改请求后，仅重写该选区
|
||||
- 将选区结果合并为新版本 artifact
|
||||
|
||||
### 13.3 代码选区需求
|
||||
|
||||
- 支持在代码编辑器中选择一段代码
|
||||
- 记录 start/end index 或行列信息
|
||||
- AI 只返回替换片段
|
||||
- 前端或后端负责将新片段拼接回完整代码
|
||||
|
||||
### 13.4 实现建议
|
||||
|
||||
首版建议：
|
||||
|
||||
- 文本：前端记录纯文本字符位置
|
||||
- 代码：使用 CodeMirror selection 信息
|
||||
|
||||
不建议首版就做复杂块级富文本局部编辑。
|
||||
|
||||
### 13.5 风险
|
||||
|
||||
- Markdown 渲染态与源码态位置映射复杂
|
||||
- 富文本块级位置难维护
|
||||
- 流式更新中选区同步容易错位
|
||||
|
||||
### 13.6 首版折中方案
|
||||
|
||||
首版文本只基于 `fullMarkdown` 纯文本改写，不做 BlockNote 富文本块定位。
|
||||
|
||||
### 13.7 验收标准
|
||||
|
||||
- 文本局部改写成功
|
||||
- 代码局部改写成功
|
||||
- 原内容未改动部分保持不变
|
||||
- 新版本正确入历史
|
||||
|
||||
---
|
||||
|
||||
## 14. 阶段八：快捷动作系统
|
||||
|
||||
### 14.1 目标
|
||||
|
||||
实现 open-canvas 风格的快捷动作体系。
|
||||
|
||||
### 14.2 首批推荐动作
|
||||
|
||||
文本类：
|
||||
|
||||
- 扩写
|
||||
- 精简
|
||||
- 改正式语气
|
||||
- 改口语语气
|
||||
- 改阅读难度
|
||||
- 翻译
|
||||
|
||||
代码类：
|
||||
|
||||
- 加注释
|
||||
- 加日志
|
||||
- 修复 bug
|
||||
- 优化代码
|
||||
- 转换语言
|
||||
|
||||
### 14.3 设计方式
|
||||
|
||||
快捷动作不要直接写死在 UI，建议配置化：
|
||||
|
||||
- `id`
|
||||
- `label`
|
||||
- `type`
|
||||
- `applicable_to`
|
||||
- `prompt_template`
|
||||
|
||||
### 14.4 后端设计
|
||||
|
||||
快捷动作可通过：
|
||||
|
||||
- 前端传 `quick_action_id`
|
||||
- 后端路由节点根据动作 id 选择 prompt
|
||||
|
||||
### 14.5 验收标准
|
||||
|
||||
- 文本动作可执行
|
||||
- 代码动作可执行
|
||||
- 结果进入新版本
|
||||
- 不同动作提示词可扩展
|
||||
|
||||
---
|
||||
|
||||
## 15. 阶段九：模型配置统一与本地模型支持
|
||||
|
||||
### 15.1 目标
|
||||
|
||||
让 Canvas 模式支持和主系统统一的模型选择，并且能自由配置本地大模型。
|
||||
|
||||
### 15.2 原则
|
||||
|
||||
- 后端 `config.yaml` 为真源
|
||||
- 前端只展示后端暴露的模型信息
|
||||
- 不维护一份脱离后端的前端常量模型表
|
||||
|
||||
### 15.3 本地模型支持范围
|
||||
|
||||
建议优先支持两类：
|
||||
|
||||
- `Ollama`
|
||||
- OpenAI-compatible 本地服务
|
||||
- LM Studio
|
||||
- vLLM
|
||||
- LocalAI
|
||||
- one-api 风格代理
|
||||
|
||||
### 15.4 后端配置建议
|
||||
|
||||
后端模型配置应至少支持：
|
||||
|
||||
- `name`
|
||||
- `display_name`
|
||||
- `use`
|
||||
- `model`
|
||||
- `api_key`
|
||||
- `base_url`
|
||||
- `supports_vision`
|
||||
- `supports_thinking`
|
||||
- `supports_tool_calling`
|
||||
- `is_local`
|
||||
- `canvas_capabilities`
|
||||
|
||||
### 15.5 Canvas 模式额外要求
|
||||
|
||||
由于不是所有模型都适合 Canvas 改写任务，建议增加能力标识：
|
||||
|
||||
- `supports_canvas_generation`
|
||||
- `supports_canvas_rewrite`
|
||||
- `supports_canvas_code_edit`
|
||||
- `supports_streaming_text`
|
||||
- `supports_streaming_tool_calls`
|
||||
|
||||
### 15.6 与 open-canvas 的关系
|
||||
|
||||
可以借鉴其命名习惯和能力分层，但不建议直接依赖其 `packages/shared/src/models.ts` 作为配置源。
|
||||
|
||||
### 15.7 验收标准
|
||||
|
||||
- 前端模型选择器可显示后端返回模型
|
||||
- 可切换本地模型
|
||||
- Canvas 模式能用本地模型生成和改写
|
||||
|
||||
---
|
||||
|
||||
## 16. 阶段十：Web 搜索增强
|
||||
|
||||
### 16.1 目标
|
||||
|
||||
实现类似 open-canvas 的可选 Web 搜索增强。
|
||||
|
||||
### 16.2 需求
|
||||
|
||||
- UI 提供 Web 搜索开关
|
||||
- 后端在需要时走搜索节点
|
||||
- 搜索结果写入线程状态
|
||||
- 结果可在画布旁侧栏展示
|
||||
|
||||
### 16.3 首版建议
|
||||
|
||||
只做：
|
||||
|
||||
- 开关
|
||||
- 搜索结果列表
|
||||
- 搜索结果用于生成 artifact
|
||||
|
||||
暂不做复杂网页抓取编辑链路。
|
||||
|
||||
### 16.4 验收标准
|
||||
|
||||
- 打开搜索后可返回搜索结果
|
||||
- 搜索结果可参与 artifact 生成
|
||||
- 结果展示不阻塞主画布
|
||||
|
||||
---
|
||||
|
||||
## 17. 阶段十一：持久化、导出与文件产物联动
|
||||
|
||||
### 17.1 目标
|
||||
|
||||
让 Canvas 文档与 DeerFlow 原有文件能力协同。
|
||||
|
||||
### 17.2 需求
|
||||
|
||||
- artifact 持久化在线程 state 中
|
||||
- 可手动导出为文件
|
||||
- 可生成真实 HTML/Markdown/代码文件到现有 outputs
|
||||
- Canvas artifact 与 `artifacts: string[]` 可双向关联
|
||||
|
||||
### 17.3 推荐能力
|
||||
|
||||
- 导出 Markdown
|
||||
- 导出代码文件
|
||||
- 另存为 artifact file
|
||||
- 从 artifact file 回填到 Canvas
|
||||
|
||||
### 17.4 验收标准
|
||||
|
||||
- 当前版本可导出
|
||||
- 导出文件可在现有文件面板查看
|
||||
- 文件型 artifact 和 Canvas artifact 能共存
|
||||
|
||||
---
|
||||
|
||||
## 18. 推荐开发顺序
|
||||
|
||||
建议严格按以下顺序推进：
|
||||
|
||||
1. 路由和目录骨架
|
||||
2. Canvas 页面布局
|
||||
3. 前端 artifact 数据模型
|
||||
4. 后端线程状态扩展
|
||||
5. 新建 Canvas Agent 图
|
||||
6. 前后端流式同步
|
||||
7. 整体生成与整体改写
|
||||
8. 局部选区改写
|
||||
9. 快捷动作
|
||||
10. 本地模型支持完善
|
||||
11. Web 搜索增强
|
||||
12. 导出与文件联动
|
||||
|
||||
不要先做局部改写和快捷动作，否则前面的状态与路由契约不稳定，返工会很多。
|
||||
|
||||
---
|
||||
|
||||
## 19. 里程碑定义
|
||||
|
||||
### M1：页面可进入
|
||||
|
||||
- 路由接通
|
||||
- 双栏布局完成
|
||||
- 本地 mock artifact 可渲染
|
||||
|
||||
### M2：后端状态打通
|
||||
|
||||
- 线程可保存结构化 artifact
|
||||
- 页面刷新后能恢复
|
||||
|
||||
### M3：AI 生成可用
|
||||
|
||||
- 可新建文本/代码 artifact
|
||||
- 可整体改写
|
||||
- 可产生版本历史
|
||||
|
||||
### M4：核心体验可用
|
||||
|
||||
- 选区改写可用
|
||||
- 快捷动作可用
|
||||
- 模型切换可用
|
||||
|
||||
### M5：增强能力完整
|
||||
|
||||
- 本地模型支持完善
|
||||
- Web 搜索增强
|
||||
- 导出和文件联动
|
||||
|
||||
---
|
||||
|
||||
## 20. 风险与难点
|
||||
|
||||
### 20.1 最大难点
|
||||
|
||||
- 结构化 artifact 状态从无到有
|
||||
- 局部选区改写的精确性
|
||||
- 流式状态与版本管理的一致性
|
||||
- 不破坏现有 DeerFlow 文件型 artifact 体系
|
||||
|
||||
### 20.2 技术风险
|
||||
|
||||
- 线程 state JSON 结构过大
|
||||
- 大模型对局部改写指令遵循不稳定
|
||||
- 本地模型 tool calling 与流式能力差异大
|
||||
- 文本渲染态与源码态位置映射复杂
|
||||
|
||||
### 20.3 规避建议
|
||||
|
||||
- 首版只支持 Markdown 源码态编辑，不做复杂富文本编辑
|
||||
- 首版只支持文本和代码两种 artifact 类型
|
||||
- 首版先做整体生成和整体改写，再做局部改写
|
||||
- 本地模型先支持“能生成、能重写”的最小能力，不强求与顶级闭源模型完全同效
|
||||
|
||||
---
|
||||
|
||||
## 21. 验收总清单
|
||||
|
||||
### 21.1 前端
|
||||
|
||||
- 有独立 Canvas 路由
|
||||
- 有专用目录和模块边界
|
||||
- 双栏布局可用
|
||||
- 文本和代码两类 artifact 可渲染
|
||||
- 历史版本可切换
|
||||
- 选区改写可交互
|
||||
- 快捷动作可触发
|
||||
- 模型可切换
|
||||
|
||||
### 21.2 后端
|
||||
|
||||
- 线程状态支持 `artifact`
|
||||
- 新增 `canvas_agent` 或等价模式
|
||||
- 生成、重写、局部改写可用
|
||||
- 流式返回稳定
|
||||
- 模型列表接口支持 Canvas 能力元数据
|
||||
|
||||
### 21.3 本地模型
|
||||
|
||||
- 可配置 Ollama
|
||||
- 可配置 OpenAI-compatible 本地服务
|
||||
- 前端可见并可切换
|
||||
- 至少能完成文本生成和整体改写
|
||||
|
||||
---
|
||||
|
||||
## 22. 推荐首版最小可交付范围
|
||||
|
||||
如果要控制风险，建议首版只交付以下内容：
|
||||
|
||||
- 新增 `canvas/*` 路由
|
||||
- 双栏布局
|
||||
- 结构化 `artifact`
|
||||
- `canvas_agent`
|
||||
- 文本/代码 artifact 新建
|
||||
- 整体生成
|
||||
- 整体改写
|
||||
- 历史版本切换
|
||||
- 后端模型动态加载
|
||||
- Ollama 或本地 OpenAI-compatible 至少一种可用
|
||||
|
||||
先不要把以下内容放进首版强制目标：
|
||||
|
||||
- 富文本块级精确编辑
|
||||
- 全量快捷动作
|
||||
- 复杂 Web 搜索增强
|
||||
- 多 artifact 并行管理
|
||||
|
||||
---
|
||||
|
||||
## 23. 后续实施建议
|
||||
|
||||
建议下一步基于本文档继续输出两份落地文档：
|
||||
|
||||
### 23.1 前端实施清单
|
||||
|
||||
逐文件列出：
|
||||
|
||||
- 要新建哪些文件
|
||||
- 哪些组件可复用
|
||||
- 哪些页面要接入路由
|
||||
- 哪些状态要从现有 hooks 抽离
|
||||
|
||||
### 23.2 后端实施清单
|
||||
|
||||
逐模块列出：
|
||||
|
||||
- 要改哪些 Python 文件
|
||||
- 新增哪些状态字段
|
||||
- 新增哪些 Agent 节点
|
||||
- 哪些 API 需要扩展
|
||||
|
||||
---
|
||||
|
||||
## 24. 结论
|
||||
|
||||
这个需求很大，但完全可拆。
|
||||
|
||||
正确做法不是“先抄 UI”，而是按下面的主线推进：
|
||||
|
||||
- 先建前端 Canvas 子系统
|
||||
- 再建结构化 artifact 状态
|
||||
- 再建 Canvas Agent 图
|
||||
- 再补局部改写和快捷动作
|
||||
- 最后统一本地模型能力
|
||||
|
||||
只要按本文档阶段推进，这个需求是可以落地的，而且能和你现在的 DeerFlow 架构保持长期兼容。
|
||||
@@ -1,268 +0,0 @@
|
||||
# 智能体推荐弹窗功能 — 开发进度
|
||||
|
||||
> 分支: `dhk-1`
|
||||
> 最后更新: 2026-05-25
|
||||
> 状态: **全部完成 ✅**
|
||||
|
||||
---
|
||||
|
||||
## 功能概述
|
||||
|
||||
在圆桌规划流程的 Step 1（任务意图理解）和 Step 2（多智能体圆桌研讨）之间，插入一个**推荐弹窗**：
|
||||
|
||||
1. 用户完成任务澄清后，点击"进入多智能体研讨"→ 弹出推荐弹窗
|
||||
2. 弹窗拉取 `GET /api/agents` 候选池，调用 `roundtable-recommender` 智能体流式推荐 2-6 个最合适的智能体
|
||||
3. 推荐结果默认勾选，用户可取消勾选 / 从候选池增选（总选 2-8 个）
|
||||
4. 确认后 Step 2 使用用户最终选定的智能体列表，不再硬编码 6 个圆桌席位
|
||||
|
||||
---
|
||||
|
||||
## 已完成的所有步骤
|
||||
|
||||
### Step 1 — 后端：新建 `roundtable-recommender` 智能体 ✅
|
||||
|
||||
**文件：**
|
||||
- `offline-backend-20260512/backend/.deer-flow/agents/roundtable-recommender/config.yaml`
|
||||
- `offline-backend-20260512/backend/.deer-flow/agents/roundtable-recommender/SOUL.md`
|
||||
|
||||
**要点：**
|
||||
- `id: roundtable-recommender`，`name: 智能体推荐`
|
||||
- SOUL.md 规定输出协议：自然语言推理 + `[RECOMMEND_READY]` 标记 + ` ```json {"picks": [...]} ``` ` 块
|
||||
- 每个 pick: `{"agent_id": "...", "reason": "..."}`，agent_id 必须来自候选池
|
||||
- 约束：2 ≤ picks ≤ 6，禁止使用任何工具
|
||||
|
||||
---
|
||||
|
||||
### Step 2 — 后端：新建 `/api/recommend/stream` 接口 ✅
|
||||
|
||||
**文件：**
|
||||
- `offline-backend-20260512/backend/app/gateway/routers/recommend.py`（新建）
|
||||
- `offline-backend-20260512/backend/app/gateway/app.py`（注册路由）
|
||||
|
||||
**接口规格：**
|
||||
```
|
||||
POST /api/recommend/stream
|
||||
Content-Type: application/json
|
||||
|
||||
Body:
|
||||
{
|
||||
"intent": { "objective": "...", "constraints": [...], "assumptions": [...] },
|
||||
"candidates": [{ "agent_id": "...", "name": "...", "description": "..." }, ...],
|
||||
"model": "deepseek-chat" // 可选
|
||||
}
|
||||
|
||||
SSE 流：透传上游 LangGraph frames + 最终状态帧
|
||||
最终帧: { "status": "done"|"asking"|"error", "content": "...", "picks": [...] | null }
|
||||
```
|
||||
|
||||
**关键实现：**
|
||||
- 无 `/init`，每次请求内部创建新 thread（stateless）
|
||||
- `_validate_picks()`：对比候选池 id、去重、夹断到 2-6，< 2 返回 `[]`
|
||||
- `_build_prompt()`：将 intent + 候选池渲染为单条 user message
|
||||
- `_RECOMMEND_READY_PATTERN`：正则提取 `[RECOMMEND_READY]` 后的 JSON 块
|
||||
- `httpx.AsyncClient(trust_env=False)`：防止 loopback 被代理拦截
|
||||
- 复用 `multi_agent.py` 的 `_auth_headers`, `_create_thread`, `_stream_upstream` 等
|
||||
|
||||
**app.py 注册：**
|
||||
```python
|
||||
from app.gateway.routers import recommend
|
||||
app.include_router(recommend.router)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 3 — 前端：`recommend.ts` API 客户端 ✅
|
||||
|
||||
**文件：** `src/roundtable-planning/api/recommend.ts`
|
||||
|
||||
**导出：**
|
||||
```typescript
|
||||
// 类型
|
||||
export interface RecommendPick { agent_id: string; reason: string }
|
||||
export interface StreamRecommendResult { status: "done"|"asking"|"error"; content: string; picks: RecommendPick[]|null }
|
||||
export type RecommendStreamPhase = "connecting"|"connected"|"streaming"
|
||||
export interface RecommendCandidate { agent_id: string; name: string; description: string }
|
||||
|
||||
// 候选池过滤（排除规则集中管理）
|
||||
export function filterRecommendCandidates(agents: Agent[]): RecommendCandidate[]
|
||||
|
||||
// 流式推荐
|
||||
export async function streamRecommend(req: StreamRecommendRequest): Promise<StreamRecommendResult>
|
||||
```
|
||||
|
||||
**排除规则（`filterRecommendCandidates`）：**
|
||||
- `roundtable-intent` — Step 1 澄清专员
|
||||
- `roundtable-recommender` — 推荐者自身
|
||||
- 前缀 `roundtable-coordinator-` — 每 session 生成的一次性协调器
|
||||
|
||||
---
|
||||
|
||||
### Step 4 — 前端：`RecommendAgentsDialog.tsx` 弹窗组件 ✅
|
||||
|
||||
**文件：** `src/roundtable-planning/components/RecommendAgentsDialog.tsx`
|
||||
|
||||
**Props：**
|
||||
```typescript
|
||||
export interface RecommendAgentsDialogProps {
|
||||
open: boolean;
|
||||
intent: IntentSummary | null;
|
||||
model?: string;
|
||||
onCancel: () => void;
|
||||
onConfirm: (agentIds: string[]) => void;
|
||||
}
|
||||
```
|
||||
|
||||
**内部阶段机器：**
|
||||
```
|
||||
"idle" → "loading_agents" → "recommending" → "ready"
|
||||
↘ "fallback" (推荐失败，兜底)
|
||||
↘ "error"
|
||||
```
|
||||
|
||||
**UI 分区：**
|
||||
- **推荐参会**（默认全选）：推荐智能体卡片，带 reason 说明
|
||||
- **其他候选**（默认未选）：可增选，补足 8 个上限
|
||||
|
||||
**选择约束：** min 2，max 8；确认按钮在范围外 disabled
|
||||
|
||||
**安全机制：**
|
||||
- `generationRef` 计数器防止 stale async 污染状态
|
||||
- `AbortController` 取消在途推荐请求
|
||||
- `intersectInOrder()`：前端二次验证推荐 id 在候选池中存在
|
||||
- 兜底列表 `FALLBACK_AGENT_IDS`：6 个内置 roundtable-* 智能体
|
||||
|
||||
**确认顺序：** 推荐且已选 → 用户增选（按交互顺序）
|
||||
|
||||
---
|
||||
|
||||
### Step 5 — 前端：`RoundtablePlanningPage.tsx` 动态 Agent 角色 ✅
|
||||
|
||||
**删除：** `ROUNDTABLE_ROLE_TEMPLATES`, `makeRoles`, `ROUNDTABLE_AGENT_IDS`, `AGENT_NAME_TO_ROLE`（全部硬编码常量）
|
||||
|
||||
**新增模块级：**
|
||||
```typescript
|
||||
const COMMANDER_SEAT_ID = 1
|
||||
type SelectedAgent = { agent_id: string; name: string }
|
||||
const BUILTIN_AGENT_META: Record<string, { avatarType: string; displayName: string }>
|
||||
const FALLBACK_AVATAR_TYPES = ["blue","purple","emerald","amber","pink"]
|
||||
function getAvatarTypeFor(agentId, index): string
|
||||
function getDisplayNameFor(agent: SelectedAgent): string
|
||||
function buildRoleTemplates(agents): ReadonlyArray<Omit<RoleEntry,"status">>
|
||||
function makeRolesFromTemplates(templates, defaultStatus, overrides?): RoleEntry[]
|
||||
function buildAgentNameToRole(agents): Record<string, {speakerId,avatarType,displayName}>
|
||||
const DEFAULT_SELECTED_AGENTS: SelectedAgent[] // 原 6 个内置席位
|
||||
```
|
||||
|
||||
**新增 state + useMemo：**
|
||||
```typescript
|
||||
const [selectedAgents, setSelectedAgents] = useState<SelectedAgent[]>(DEFAULT_SELECTED_AGENTS);
|
||||
const roleTemplates = useMemo(() => buildRoleTemplates(selectedAgents), [selectedAgents]);
|
||||
const agentNameToRole = useMemo(() => buildAgentNameToRole(selectedAgents), [selectedAgents]);
|
||||
const roundtableAgentIds = useMemo(() => selectedAgents.map(a => a.agent_id), [selectedAgents]);
|
||||
```
|
||||
|
||||
**替换调用点：**
|
||||
| 替换前 | 替换后 |
|
||||
|---|---|
|
||||
| `AGENT_NAME_TO_ROLE[name]` | `agentNameToRole[name]` |
|
||||
| `ROUNDTABLE_AGENT_IDS` | `roundtableAgentIds` |
|
||||
| `makeRoles(status, ...)` | `makeRolesFromTemplates(roleTemplates, status, ...)` |
|
||||
| 角色面板 `role.id === 2 ? <RobotAvatar ...>` 链 | `getAvatar(agentNameToRole[role.agentId]?.avatarType ?? "blue", "h-7 w-7")` |
|
||||
| `HighFidelityReport seatNameMap` 用 `AGENT_NAME_TO_ROLE` | 用 `agentNameToRole` |
|
||||
| useEffect 依赖 | 加入 `roleTemplates` |
|
||||
| dispatch useCallback 依赖 | 加入 `agentNameToRole` |
|
||||
|
||||
---
|
||||
|
||||
### Step 6 — 前端：弹窗接入页面 ✅
|
||||
|
||||
**新增 import：**
|
||||
```typescript
|
||||
import { RecommendAgentsDialog } from "@/roundtable-planning/components/RecommendAgentsDialog";
|
||||
```
|
||||
|
||||
**新增 state：**
|
||||
```typescript
|
||||
const [isRecommendDialogOpen, setIsRecommendDialogOpen] = useState<boolean>(false);
|
||||
```
|
||||
|
||||
**新增 callback `handleConfirmAgents`：**
|
||||
```typescript
|
||||
const handleConfirmAgents = useCallback((agentIds: string[]) => {
|
||||
setSelectedAgents(
|
||||
agentIds.map(id => ({
|
||||
agent_id: id,
|
||||
name: BUILTIN_AGENT_META[id]?.displayName ?? id,
|
||||
})),
|
||||
);
|
||||
step2InitRef.current = false; // 重置 Step 2，让新 coordinator 按新名单初始化
|
||||
setIsRecommendDialogOpen(false);
|
||||
setCurrentStep(2);
|
||||
setShowToast("成功确认！已切换至第二阶段圆桌研讨系统");
|
||||
}, []);
|
||||
```
|
||||
|
||||
**两个"进入多智能体研讨"按钮改为：**
|
||||
```typescript
|
||||
onClick={() => setIsRecommendDialogOpen(true)}
|
||||
```
|
||||
|
||||
**JSX 渲染（在 showToast 之前）：**
|
||||
```tsx
|
||||
<RecommendAgentsDialog
|
||||
open={isRecommendDialogOpen}
|
||||
intent={intentReady}
|
||||
model={DEFAULT_MODEL}
|
||||
onCancel={() => setIsRecommendDialogOpen(false)}
|
||||
onConfirm={handleConfirmAgents}
|
||||
/>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 文件清单（本次改动）
|
||||
|
||||
### 后端（新建）
|
||||
| 文件 | 说明 |
|
||||
|---|---|
|
||||
| `.deer-flow/agents/roundtable-recommender/config.yaml` | 推荐智能体元数据 |
|
||||
| `.deer-flow/agents/roundtable-recommender/SOUL.md` | 推荐智能体系统提示 |
|
||||
| `app/gateway/routers/recommend.py` | `/api/recommend/stream` 接口 |
|
||||
|
||||
### 后端（修改）
|
||||
| 文件 | 说明 |
|
||||
|---|---|
|
||||
| `app/gateway/app.py` | 注册 `recommend.router` |
|
||||
|
||||
### 前端（新建）
|
||||
| 文件 | 说明 |
|
||||
|---|---|
|
||||
| `src/roundtable-planning/api/recommend.ts` | 前端 SSE 客户端 |
|
||||
| `src/roundtable-planning/components/RecommendAgentsDialog.tsx` | 推荐弹窗组件 |
|
||||
|
||||
### 前端（修改）
|
||||
| 文件 | 说明 |
|
||||
|---|---|
|
||||
| `src/roundtable-planning/pages/RoundtablePlanningPage.tsx` | 动态 Agent 角色 + 弹窗接入 |
|
||||
|
||||
---
|
||||
|
||||
## 下次开始前检查项
|
||||
|
||||
1. **后端是否已重启** — `recommend.router` 注册需重启 FastAPI（`make dev` 或 `./scripts/restart-all.sh`）
|
||||
2. **`roundtable-recommender` 智能体已注册** — 访问 `GET /api/agents` 确认列表里有 `roundtable-recommender`
|
||||
3. **typecheck 干净** — `pnpm typecheck 2>&1 | grep roundtable-planning` 无输出
|
||||
4. **弹窗流程端到端测试**：
|
||||
- Step 1 完成意图澄清 → `intentReady` 不为 null
|
||||
- 点击"进入多智能体研讨"→ 弹窗出现，开始加载智能体列表
|
||||
- 弹窗展示推荐结果（流式文字 + 卡片列表）
|
||||
- 调整勾选 → 确认 → Step 2 用所选智能体初始化
|
||||
|
||||
---
|
||||
|
||||
## 潜在后续工作（未列入本次范围）
|
||||
|
||||
- 弹窗内显示每个候选智能体的完整 description（目前从 `/api/agents` 取，已有字段）
|
||||
- 推荐失败时的 Toast 提示（目前静默兜底）
|
||||
- 推荐理由（reason）在 Step 2 角色面板中展示
|
||||
- `HighFidelityReport` 的 `avatarType` 字段按新选角色动态渲染
|
||||
@@ -1,243 +0,0 @@
|
||||
# 素材专家检索 —— 内网接口对接说明
|
||||
|
||||
本文档说明 AI 智能写作中「素材收集专家」的检索机制、内网知识库接口的对接逻辑、
|
||||
涉及的代码文件，以及常见错误的排查方式。
|
||||
|
||||
---
|
||||
|
||||
## 1. 检索来源切换
|
||||
|
||||
素材专家支持多种检索来源，通过**后端配置文件**统一切换，**无需改动任何代码**。
|
||||
|
||||
配置位置：`offline-backend-20260512/backend/config.yaml`
|
||||
|
||||
```yaml
|
||||
ai_writing:
|
||||
# 检索来源开关：internet=互联网检索（默认）/ intranet=内网知识库 / tavily / demo
|
||||
search_provider: internet
|
||||
# 以下两项仅在 search_provider=intranet 时生效
|
||||
intranet_search_url: http://10.106.57.180:7863/knowledge_base/search_docs_es
|
||||
intranet_knowledge_base: samples
|
||||
```
|
||||
|
||||
| `search_provider` 取值 | 含义 |
|
||||
|---|---|
|
||||
| `internet` | 互联网检索（DuckDuckGo），失败时回退到 demo 演示素材。**当前默认值** |
|
||||
| `intranet` | 内网知识库检索（调用 `search_docs_es` 接口） |
|
||||
| `tavily` | Tavily 互联网检索 |
|
||||
| `demo` | 内置演示素材，仅用于本地调试 |
|
||||
|
||||
> 内网接口联通后，把 `search_provider` 改为 `intranet` 即可切换。
|
||||
> 配置文件支持热加载（`get_app_config()` 按 mtime 自动重载），改完一般无需重启后端。
|
||||
|
||||
---
|
||||
|
||||
## 1.5 检索关键词数量
|
||||
|
||||
素材专家的检索词数量由**用户在写作表单中指定**（「检索关键词数量」输入框，
|
||||
范围 `1~10`，默认 `6`）。数量越多素材越全面，但检索与排序更耗时。
|
||||
|
||||
- 该参数随 `POST /api/ai-writing/start` 的 `keyword_count` 字段传入，写入 `AIWritingState.keyword_count`。
|
||||
- `researcher_node` 用它决定让 LLM 生成多少个检索词、并发检索多少个方向
|
||||
（`EXTRACT_KEYWORDS_USER` prompt 按该数量格式化，`search_keywords = keywords[:keyword_count]`）。
|
||||
- 非法值（缺省 / 越界 / 非数字）由前后端双重兜底：后端 `_resolve_keyword_count()`
|
||||
规整到 `[1, 10]`，越界回退默认 `6`。
|
||||
- 补充搜索（`re_search`）时用户额外添加的关键词不会被该上限截断。
|
||||
|
||||
---
|
||||
|
||||
## 1.6 素材总量上限
|
||||
|
||||
素材收集专家最终保留的素材**总条数**由后端配置文件统一控制，并按检索词数**均分**到每个词。
|
||||
|
||||
配置位置：`offline-backend-20260512/backend/config.yaml` 的 `ai_writing` 段：
|
||||
|
||||
```yaml
|
||||
ai_writing:
|
||||
# 素材总量上限，范围 1~100，非法值回退 20
|
||||
max_materials: 20
|
||||
```
|
||||
|
||||
均分规则 —— `每个检索词的检索条数 = ⌈ max_materials / 实际检索词数 ⌉`（向上取整）：
|
||||
|
||||
| `max_materials` | 检索词数 | 每词检索条数 |
|
||||
|---|---|---|
|
||||
| 20 | 1 | 20 |
|
||||
| 20 | 2 | 10 |
|
||||
| 20 | 3 | 7（共 21，合并后截断到 20） |
|
||||
| 20 | 5 | 4 |
|
||||
|
||||
- 各检索词按上表条数检索 → 合并去重 → 最终统一截断到 `max_materials`。
|
||||
- 向上取整是为了保证去重后素材数仍能接近上限；去重后实际条数可能略少于上限（不同词命中同一篇），属正常。
|
||||
- 与 [1.5](#15-检索关键词数量) 的关系：`keyword_count` 决定**搜几个词**，`max_materials` 决定**总共要多少条**，两者相除得到每词条数。
|
||||
- 涉及代码：`researcher.py` 的 `_resolve_max_materials()`（读配置 + 规整）与 `_per_keyword_limit()`（均分计算）。
|
||||
|
||||
> `config.yaml` 支持热加载，改完一般无需重启后端。
|
||||
|
||||
---
|
||||
|
||||
## 2. 内网接口规格
|
||||
|
||||
- **地址**：`http://10.106.57.180:7863/knowledge_base/search_docs_es`
|
||||
- **方法**：`POST`
|
||||
- **请求体**：
|
||||
|
||||
```json
|
||||
{
|
||||
"query": "检索关键词",
|
||||
"knowledge_base_name": "samples",
|
||||
"ts": "yes"
|
||||
}
|
||||
```
|
||||
|
||||
- **响应体**：一个数组，每个元素结构如下：
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"page_content": "正文片段",
|
||||
"metadata": {
|
||||
"m_title": "标题",
|
||||
"content": "内容",
|
||||
"recUuid": "原文id",
|
||||
"m_publish":"发布时间",
|
||||
"source1": "来源"
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
我们需要的字段都在 `metadata` 里。
|
||||
|
||||
### 字段映射
|
||||
|
||||
后端把内网响应映射为统一的 `SearchResult` 结构：
|
||||
|
||||
| 内网响应字段 | SearchResult 字段 | 说明 |
|
||||
|--------------------------|--------------------|------|
|
||||
| `metadata.m_title` | `title` | 标题，缺省为「（无标题）」 |
|
||||
| `metadata.content` | `content` | 内容，截断到 500 字 |
|
||||
| `metadata.source1` | `source` | 来源，缺省为「内网知识库」 |
|
||||
| `metadata.m_publish` | `published_at` | 发布时间 |
|
||||
| `metadata.recUuid` | `recUuid` | 原文 id，用于前端拼接「查看原文」链接 |
|
||||
| — | `url` | 固定为空，原文地址由前端依据 `recUuid` 拼接 |
|
||||
| — | `relevance_score` | 接口不返回分值，按返回顺序赋递减分以保留 ES 排序 |
|
||||
| — | `source_type` | 固定为 `"intranet"` |
|
||||
|
||||
---
|
||||
|
||||
## 3. 对接逻辑与涉及文件
|
||||
|
||||
### 后端
|
||||
|
||||
| 文件 | 作用 |
|
||||
|------|------|
|
||||
| `packages/harness/deerflow/agents/ai_writing/search/intranet_stub.py` | **内网检索适配器** `IntranetSearchProvider`。发起 POST 请求、解析响应、映射为 `SearchResult` |
|
||||
| `packages/harness/deerflow/agents/ai_writing/search/__init__.py` | `get_search_provider()` 工厂函数，依据 `search_provider` 配置返回对应 provider |
|
||||
| `packages/harness/deerflow/agents/ai_writing/search/base.py` | `SearchResult` 数据结构 + `BaseSearchProvider` 抽象基类 |
|
||||
| `packages/harness/deerflow/agents/ai_writing/nodes/researcher.py` | 素材收集专家节点，调用 provider 检索并把结果合并、排序为素材包 |
|
||||
| `app/gateway/routers/ai_writing.py` | `_ai_writing_config()` 读取 `config.yaml` 的 `ai_writing` 段，经 `_make_config()` 注入运行时 |
|
||||
| `config.yaml` | `ai_writing` 段，检索来源开关与内网接口地址 |
|
||||
|
||||
调用链：
|
||||
|
||||
```
|
||||
ai_writing.py(_make_config 注入 ai_writing_config)
|
||||
→ researcher_node
|
||||
→ get_search_provider(ai_writing_config) # 依据 search_provider 选择
|
||||
→ IntranetSearchProvider.search() # POST search_docs_es
|
||||
→ SearchResult[] # 字段映射
|
||||
```
|
||||
|
||||
### 前端
|
||||
|
||||
| 文件 | 作用 |
|
||||
|------|------|
|
||||
| `src/core/config/index.ts` | `INTRANET_SOURCE_URL_BASE` 原文详情页地址前缀 + `buildIntranetSourceUrl()` 构造函数 |
|
||||
| `src/open-canvas/components/ai-writing/MaterialItem.tsx` | 素材卡片，`recUuid` 非空时显示「查看原文」按钮 |
|
||||
| `src/open-canvas/components/ai-writing/CompletedInterventionCard.tsx` | 历史回显的素材卡，「原文」链接同样基于 `recUuid` |
|
||||
| `src/open-canvas/api/ai-writing.ts` | `normalizeMaterial()` 把后端 snake_case 字段转为前端 camelCase（含 `recUuid`） |
|
||||
|
||||
「查看原文」链接拼接规则：
|
||||
|
||||
```
|
||||
INTRANET_SOURCE_URL_BASE + recUuid
|
||||
= https://chlib.b.uat.4.cn/knowlibrary/#/knowledge/mid_detail?recUuid={recUuid}
|
||||
```
|
||||
|
||||
- 仅当素材的 `recUuid` **非空**时才显示「查看原文」按钮。
|
||||
- 点击直接 `window.open(...)` 新标签页打开，不做站内跳转。
|
||||
|
||||
---
|
||||
|
||||
## 4. 错误处理与排查
|
||||
|
||||
### 4.1 内网检索返回空 / 调不通
|
||||
|
||||
**现象**：切到 `intranet` 后，素材专家时间线出现琥珀色告警「ES 波动导致检索异常」，
|
||||
下方显示真实报错原因；若完全无结果，再提示「未检索到任何素材」。
|
||||
|
||||
`IntranetSearchProvider.search()` 对所有异常（连接失败、超时、非 2xx、JSON 解析失败）
|
||||
都做了兜底：**捕获后记录 warning 日志、把原因收集到 `provider.errors`，并返回空列表**，
|
||||
不会让整个写作流程崩溃。`researcher_node` 在检索结束后取出 `provider.errors`，
|
||||
以非致命的 `notice` 事件推送到前端时间线（标题「ES 波动导致检索异常」+ 真实原因），
|
||||
**接口报错不影响写作流程继续**。
|
||||
|
||||
> 容错相关代码：
|
||||
> - 检索异常收集：`intranet_stub.py` / `duckduckgo_search.py` 的 `errors` 列表
|
||||
> - 告警事件发出：`researcher.py` 的 `_notice()` 与 `progress_events`
|
||||
> - 模型调用异常：`researcher.py`（检索词/排序）、`writer_outline.py` / `writer_draft.py` /
|
||||
> `editor.py` 均会发出「模型错误」事件（致命错误用 `error`，可兜底的用 `notice`）
|
||||
> - 前端展示：`TimelineStep.tsx` 渲染 `notice`（琥珀）/ `error`（红色）的标题 + 真实原因
|
||||
|
||||
排查步骤：
|
||||
|
||||
1. **确认网络可达**：在后端所在机器执行
|
||||
`curl -X POST http://10.106.57.180:7863/knowledge_base/search_docs_es -H "Content-Type: application/json" -d "{\"query\":\"测试\",\"knowledge_base_name\":\"samples\",\"ts\":\"yes\"}"`
|
||||
2. **查看后端日志**：搜索关键字 `intranet search failed`，会打印具体异常（连接超时 / DNS / 401 等）。
|
||||
3. **确认配置**：`config.yaml` 的 `intranet_search_url`、`intranet_knowledge_base` 是否正确。
|
||||
|
||||
空结果时前端已有兜底：素材确认卡会弹出「未检索到任何素材，是否在无素材的情况下继续写作」，
|
||||
用户可以选择「重新搜索」或「无数据继续写作」。
|
||||
|
||||
### 4.2 字段缺失 / 响应结构变化
|
||||
|
||||
`search()` 对每个字段都用 `or` 兜底（如 `m_title` 缺失时回退为「（无标题）」），
|
||||
单条数据字段缺失不会导致整批失败。
|
||||
|
||||
若内网接口改为「数组外包一层 `data`/`results`」的结构，适配器已兼容；
|
||||
若改成其它结构，需修改 `intranet_stub.py` 中解析 `items` 的逻辑。
|
||||
|
||||
### 4.3 「查看原文」按钮不显示
|
||||
|
||||
**原因**：该素材的 `recUuid` 为空。这是预期行为 —— 只有内网知识库素材才带 `recUuid`，
|
||||
互联网检索（`internet`/`tavily`/`demo`）的素材没有 `recUuid`，不显示「查看原文」。
|
||||
|
||||
如需让互联网素材也能跳转，需另行调整 `MaterialItem.tsx` 的显示条件。
|
||||
|
||||
### 4.4 原文链接打不开 / 地址不对
|
||||
|
||||
「查看原文」地址前缀写在 `src/core/config/index.ts` 的 `INTRANET_SOURCE_URL_BASE`。
|
||||
若内网原文详情页地址有变，只改这一个常量即可。
|
||||
|
||||
### 4.5 检索到的素材全是无关内容
|
||||
|
||||
**现象**：素材卡片内容与写作意图完全不沾边。
|
||||
|
||||
**排查**：检查后端日志里素材专家实际用的检索词。常见原因是模型把关键词提取
|
||||
提示词模板里的占位符（如「关键词1」「...」）当成真关键词去检索了。
|
||||
|
||||
`researcher.py` 的 `_clean_keywords()` 已对此做防御：剔除 `关键词\d*` / `keyword\d*` /
|
||||
`...` 等占位符，全部被滤掉时回退为写作意图本身。若仍出现，检查
|
||||
`researcher_prompts.py` 的 `EXTRACT_KEYWORDS` 提示词是否又引入了易被误抄的示例占位符。
|
||||
|
||||
---
|
||||
|
||||
## 5. 联调上线步骤
|
||||
|
||||
1. 确认后端机器能访问 `10.106.57.180:7863`。
|
||||
2. 把 `config.yaml` 的 `ai_writing.search_provider` 改为 `intranet`。
|
||||
3. 后端配置热加载生效（或重启后端）。
|
||||
4. 进入 AI 智能写作页面，发起一次写作，观察素材收集专家是否返回内网素材。
|
||||
5. 校验素材卡片的标题/来源/时间显示正确，「查看原文」能跳到内网详情页。
|
||||
6. 如检索为空，按 [4.1](#41-内网检索返回空--调不通) 排查。
|
||||
@@ -1,2 +1,10 @@
|
||||
/**
|
||||
* 圆桌规划（Roundtable Planning）模块入口。
|
||||
*
|
||||
* 详细架构 / API 字段速查见 `frontend-web/docs/multi-agent-frontend-dev.md`。
|
||||
* 这里只暴露两个外部使用的组件：
|
||||
* - `RoundtablePlanningPage`：三步合一的主页面（任务理解 → 多智能体研讨 → 方案展示）。
|
||||
* - `HighFidelityReport`：Step 3 报告视图，可单独嵌入其它面板（如未来的「方案对比」）。
|
||||
*/
|
||||
export { default as RoundtablePlanningPage } from "./pages/RoundtablePlanningPage";
|
||||
export { HighFidelityReport } from "./components/HighFidelityReport";
|
||||
@@ -1,4 +1,38 @@
|
||||
import React, { useState, useEffect, useRef, useCallback, useMemo } from "react";
|
||||
/**
|
||||
* 圆桌规划主页面（三步合一）。
|
||||
*
|
||||
* 这是一个约 3 600 行的单文件页面，通过 `currentStep ∈ {1,2,3}` 在同一容器内切换
|
||||
* 三步 UI。架构 / 状态机 / SSE 终态语义请先读 `frontend-web/docs/multi-agent-frontend-dev.md`，
|
||||
* 这里只补充阅读源码时最容易忽略的几条规则：
|
||||
*
|
||||
* 1) **不要并行派活**：编排循环 `runOrchestration` 内 `for (const [subName, task] of dispatched)`
|
||||
* 是**顺序**而非并行——历史上并行触发 N 路 SSE，每路 token 级 setState 整表会卡顿；保持顺序。
|
||||
*
|
||||
* 2) **三段式流式气泡**：`appendStreamingDialogue` → `appendToDialogue`（仅增量）→
|
||||
* `finalizeDialogue`（最终文本 + confidence + `streaming=false`）。三个函数都按 `id`
|
||||
* 匹配，绝不要用数组下标。
|
||||
*
|
||||
* 3) **Step 1 init 防 StrictMode 双 mount**：用单调代数 `step1InitGenRef` 而不是闭包 cancelled
|
||||
* 标志。任何 setState 完成前都要校验 `myGen === step1InitGenRef.current`。同样模式见
|
||||
* `RecommendAgentsDialog` 的 `generationRef`。
|
||||
*
|
||||
* 4) **离开 Step 2 不销毁线程**：`step2InitRef`/`threadIds` 保留，允许用户回到 Step 2 继续看
|
||||
* 完整讨论。只有「新建任务 / 加载草稿 / 推荐确认」会复位 `step2InitRef`。
|
||||
*
|
||||
* 5) **草稿自动保存只在前进切换时触发**（1→2、2→3），后退不保存，避免覆盖 `furthestStep`。
|
||||
*
|
||||
* 6) **顶栏门禁**：Step 2 需 `intentReady`；Step 3 需 `hasConsensus`（leader.dispatched===[]）。
|
||||
*
|
||||
* 7) **Persona 抽屉**改的 model 不会立即重启编排，下一轮该席位被派活时由 `runOrchestration`
|
||||
* 读 `agentConfigs[meta.speakerId]?.model` 传入 special。prompt / temp 当前**仅前端记录**。
|
||||
*
|
||||
* 8) **常量**：`DEFAULT_MODEL`、`MAX_CYCLES=8`、`COMMANDER_SEAT_ID=1`、`INTENT_READY_RE`。
|
||||
*
|
||||
* 调试开关（默认开启）：
|
||||
* window.__MULTI_AGENT_INIT_TIMING__ // /api/multi-agent/init 各阶段耗时
|
||||
* window.__MULTI_AGENT_DEBUG__ // streamMultiAgent 帧计数 + lastEvent
|
||||
*/
|
||||
import React, { useState, useEffect, useRef, useCallback, useMemo } from "react";
|
||||
import ReactMarkdown from "react-markdown";
|
||||
import remarkGfm from "remark-gfm";
|
||||
import { HighFidelityReport } from "@/roundtable-planning/components/HighFidelityReport";
|
||||
@@ -436,7 +470,6 @@ export default function RoundtablePlanningPage() {
|
||||
const [step2RoundtableDialogues, setStep2RoundtableDialogues] = useState<any[]>([]);
|
||||
|
||||
// Inputs for Step 2 conversation simulation controls
|
||||
const [roundTableSpeed, setRoundTableSpeed] = useState<string>("正常");
|
||||
const [isRoundTableRunning, setIsRoundTableRunning] = useState<boolean>(true);
|
||||
const [customAgentInput, setCustomAgentInput] = useState<string>("");
|
||||
// Whether the roundtable visualizer + constraint console panel is collapsed.
|
||||
@@ -465,6 +498,7 @@ export default function RoundtablePlanningPage() {
|
||||
// early-returned because the ref was already set; net result: the async
|
||||
// landed but its setState got skipped, leaving intentThreadId null forever).
|
||||
const step1InitGenRef = useRef<number>(0);
|
||||
const intentAborterRef = useRef<AbortController | null>(null);
|
||||
|
||||
// Multi-agent orchestration state (lives only for one step-2 visit).
|
||||
const [threadIds, setThreadIds] = useState<ThreadIdMap | null>(null);
|
||||
@@ -516,6 +550,17 @@ export default function RoundtablePlanningPage() {
|
||||
activeAbortersRef.current.clear();
|
||||
}, []);
|
||||
|
||||
const stopIntentStream = useCallback(() => {
|
||||
if (intentAborterRef.current) {
|
||||
try {
|
||||
intentAborterRef.current.abort();
|
||||
} catch {
|
||||
/* noop */
|
||||
}
|
||||
intentAborterRef.current = null;
|
||||
}
|
||||
}, []);
|
||||
|
||||
// Toast auto-dismiss logic
|
||||
useEffect(() => {
|
||||
if (showToast) {
|
||||
@@ -524,6 +569,11 @@ export default function RoundtablePlanningPage() {
|
||||
}
|
||||
}, [showToast]);
|
||||
|
||||
useEffect(() => {
|
||||
if (currentStep === 1) return;
|
||||
stopIntentStream();
|
||||
}, [currentStep, stopIntentStream]);
|
||||
|
||||
// Auto-follow the streamed conversations: track scroll position, stop
|
||||
// following when the user scrolls up, expose a `回到底部` button that
|
||||
// re-engages auto-follow. Same hook for both steps.
|
||||
@@ -842,6 +892,10 @@ export default function RoundtablePlanningPage() {
|
||||
// parallel meant N concurrent SSE streams each triggering a full-list
|
||||
// setState on every token delta, which made the browser stutter badly
|
||||
// when the leader 派活给多个席位。改为顺序后,同一时刻只有一个 SSE 在跑。
|
||||
//
|
||||
// ⚠️ 不要改回 Promise.all 并行 —— 详见 multi-agent-frontend-dev.md §5.4
|
||||
// 与 §12.4。如果未来要并行,先把 step2RoundtableDialogues 换成 Map<id, Bubble>
|
||||
// 或基于 ref 的局部更新,再放开 N 路 SSE。
|
||||
for (const [subName, task] of leaderRes.dispatched) {
|
||||
if (orchestrationCancelRef.current) break;
|
||||
const meta = agentNameToRole[subName.toLowerCase()];
|
||||
@@ -1039,7 +1093,11 @@ export default function RoundtablePlanningPage() {
|
||||
// eslint-disable-next-line react-hooks/exhaustive-deps
|
||||
}, [isRoundTableRunning]);
|
||||
|
||||
// Adjust budget constraint dynamically
|
||||
// Budget slider — UI demo only.
|
||||
// 这是一段**未对接后端**的演示逻辑:滑动预算条只会本地 setBudgetLimit 并 1.5 秒后追加一条
|
||||
// 模拟智能体口吻的气泡(根据档位选话术)。真实研讨里预算属于约束条件,应由 Step 1 的
|
||||
// intent.summary.constraints 承载、由总控派活时透传给 sub-agent,而不是这条单滑块。
|
||||
// 重写此功能前请同步考虑:1) 是否真的需要可调约束;2) 若需要,改成走 runOrchestration 注入新 prompt。
|
||||
const handleBudgetChange = (newVal: number) => {
|
||||
setBudgetLimit(newVal);
|
||||
triggerToast(`💰 研商经费调优约束变更为 ${newVal} 万！各大智能体启动资源重算...`);
|
||||
@@ -1082,6 +1140,10 @@ export default function RoundtablePlanningPage() {
|
||||
// Save per-seat agent config overrides. We persist locally only — the next
|
||||
// time the orchestration loop dispatches to this seat it will read the
|
||||
// chosen model out of `agentConfigs` and pass it on the streaming call.
|
||||
//
|
||||
// 目前 prompt / temp 两个字段**仅前端保留**,后端尚未开放 per-agent override 接口。
|
||||
// 当后端开放时,应在 streamMultiAgent 的 special 调用上同时传 prompt_override / temperature,
|
||||
// 而不是改这里的本地存储结构(后者会被 useState 重置)。
|
||||
const handleSaveAgentAndRecalculate = (id: number) => {
|
||||
const role = roles.find(r => r.id === id);
|
||||
const roleName = role?.name || "专家智能体";
|
||||
@@ -1172,6 +1234,7 @@ export default function RoundtablePlanningPage() {
|
||||
// Stop anything in flight before swapping state out.
|
||||
orchestrationCancelRef.current = true;
|
||||
abortAllInFlight();
|
||||
stopIntentStream();
|
||||
setIsOrchestrating(false);
|
||||
setIsInitializing(false);
|
||||
setPendingClarification(null);
|
||||
@@ -1201,7 +1264,7 @@ export default function RoundtablePlanningPage() {
|
||||
// doesn't change and the effect wouldn't re-fire.
|
||||
runStep1Init();
|
||||
triggerToast("✨ 已开始新任务,请在第一步与任务理解智能体澄清需求");
|
||||
}, [abortAllInFlight, runStep1Init]);
|
||||
}, [abortAllInFlight, runStep1Init, stopIntentStream]);
|
||||
|
||||
// ── Draft helpers ──────────────────────────────────────────────────────
|
||||
// Build a fresh snapshot of the current in-memory session. Called by every
|
||||
@@ -1307,6 +1370,7 @@ export default function RoundtablePlanningPage() {
|
||||
// Cancel anything in-flight before swapping state out from under it.
|
||||
orchestrationCancelRef.current = true;
|
||||
abortAllInFlight();
|
||||
stopIntentStream();
|
||||
setIsOrchestrating(false);
|
||||
setIsInitializing(false);
|
||||
setPendingClarification(null);
|
||||
@@ -1347,7 +1411,7 @@ export default function RoundtablePlanningPage() {
|
||||
setCurrentStep(draft.furthestStep);
|
||||
triggerToast(`📂 已加载草稿:${draft.name}`);
|
||||
},
|
||||
[drafts, abortAllInFlight],
|
||||
[drafts, abortAllInFlight, stopIntentStream],
|
||||
);
|
||||
|
||||
const handleDeleteDraft = useCallback(
|
||||
@@ -1470,11 +1534,14 @@ export default function RoundtablePlanningPage() {
|
||||
};
|
||||
|
||||
setIsIntentSending(true);
|
||||
const aborter = new AbortController();
|
||||
intentAborterRef.current = aborter;
|
||||
try {
|
||||
const res = await streamIntent({
|
||||
threadId: intentThreadId,
|
||||
message: trimmed,
|
||||
model: DEFAULT_MODEL,
|
||||
signal: aborter.signal,
|
||||
onTextDelta: (delta) => {
|
||||
setInteractiveMessages(prev =>
|
||||
prev.map(m => (m.id === agentMsgId ? { ...m, content: (m.content ?? "") + delta } : m)),
|
||||
@@ -1529,16 +1596,36 @@ export default function RoundtablePlanningPage() {
|
||||
triggerToast(`❌ 智能体调用失败: ${res.content}`);
|
||||
}
|
||||
} catch (err) {
|
||||
console.error("intent stream failed:", err);
|
||||
setInteractiveMessages(prev =>
|
||||
prev.map(m =>
|
||||
m.id === agentMsgId
|
||||
? { ...m, content: `(错误) ${(err as Error).message}`, streaming: false } as any
|
||||
: m,
|
||||
),
|
||||
);
|
||||
triggerToast(`❌ 发送失败: ${(err as Error).message}`);
|
||||
if ((err as Error).name === "AbortError" || aborter.signal.aborted) {
|
||||
setInteractiveMessages(prev =>
|
||||
prev.map(m =>
|
||||
m.id === agentMsgId
|
||||
? {
|
||||
...m,
|
||||
content: (m.content ?? "").trim()
|
||||
? `${m.content ?? ""}\n\n(已暂停)`
|
||||
: "(已暂停)",
|
||||
streaming: false,
|
||||
} as any
|
||||
: m,
|
||||
),
|
||||
);
|
||||
triggerToast("⏸️ 已暂停任务理解回复");
|
||||
} else {
|
||||
console.error("intent stream failed:", err);
|
||||
setInteractiveMessages(prev =>
|
||||
prev.map(m =>
|
||||
m.id === agentMsgId
|
||||
? { ...m, content: `(错误) ${(err as Error).message}`, streaming: false } as any
|
||||
: m,
|
||||
),
|
||||
);
|
||||
triggerToast(`❌ 发送失败: ${(err as Error).message}`);
|
||||
}
|
||||
} finally {
|
||||
if (intentAborterRef.current === aborter) {
|
||||
intentAborterRef.current = null;
|
||||
}
|
||||
setIsIntentSending(false);
|
||||
}
|
||||
};
|
||||
@@ -2603,6 +2690,18 @@ export default function RoundtablePlanningPage() {
|
||||
{isIntentSending ? "发送中" : "发送"}
|
||||
</button>
|
||||
|
||||
{isIntentSending && (
|
||||
<button
|
||||
id="pause-intent-btn"
|
||||
type="button"
|
||||
onClick={() => stopIntentStream()}
|
||||
className="bg-amber-100 hover:bg-amber-200 text-amber-800 text-xs font-bold px-3 py-2.5 rounded-xl flex items-center gap-1.5 transition border border-amber-200/40 shadow-sm active:scale-95"
|
||||
>
|
||||
<Pause className="w-3 h-3" />
|
||||
暂停
|
||||
</button>
|
||||
)}
|
||||
|
||||
<button
|
||||
id="suggest-followup-btn"
|
||||
onClick={handleAgentFollowUp}
|
||||
@@ -2676,23 +2775,6 @@ export default function RoundtablePlanningPage() {
|
||||
</div>
|
||||
</div>
|
||||
<div className="flex items-center gap-2.5">
|
||||
{/* Interactive speed controls */}
|
||||
<div className="flex items-center bg-slate-50 border border-slate-200 rounded-xl p-0.5 text-[10px] shrink-0 font-bold font-sans shadow-inner">
|
||||
<span className="px-2 text-slate-400 font-semibold selection:bg-transparent">研商步长</span>
|
||||
<button
|
||||
onClick={() => { setRoundTableSpeed("慢速"); triggerToast("🐌 已切换为 0.5x 慢速拟合监听模式"); }}
|
||||
className={`px-1.5 py-0.5 rounded transition ${roundTableSpeed === "慢速" ? "bg-white text-primary font-extrabold shadow-sm" : "text-slate-500 hover:text-slate-800"}`}
|
||||
>慢速</button>
|
||||
<button
|
||||
onClick={() => { setRoundTableSpeed("正常"); triggerToast("⏱️ 已恢复为 1.0x 标准协商状态值"); }}
|
||||
className={`px-1.5 py-0.5 rounded transition ${roundTableSpeed === "正常" ? "bg-white text-primary font-extrabold shadow-sm" : "text-slate-500 hover:text-slate-800"}`}
|
||||
>正常</button>
|
||||
<button
|
||||
onClick={() => { setRoundTableSpeed("极速"); triggerToast("🚀 已并行为 2.5x 极速算力重算模式"); }}
|
||||
className={`px-1.5 py-0.5 rounded transition ${roundTableSpeed === "极速" ? "bg-white text-primary font-extrabold shadow-sm" : "text-slate-500 hover:text-slate-800"}`}
|
||||
>极速</button>
|
||||
</div>
|
||||
|
||||
{/* Suspend / resume button visibility:
|
||||
- Show "挂起协商" only while a run is actually in flight
|
||||
(isOrchestrating + still nominally running). When the
|
||||
@@ -2937,7 +3019,14 @@ export default function RoundtablePlanningPage() {
|
||||
</div>
|
||||
)}
|
||||
|
||||
{/* Selected Agent Persona Config Drawer / Drawer dialog box */}
|
||||
{/* Selected Agent Persona Config Drawer / Drawer dialog box
|
||||
────────────────────────────────────────────────────────
|
||||
点击圆桌可视化里的某个智能体头像后展开,允许覆写该席位的:
|
||||
- System Prompt (本地记录,后端覆写未开放)
|
||||
- 推理模型 (下一轮派活时 runOrchestration 会读 agentConfigs[id].model)
|
||||
- Temperature (本地记录,后端覆写未开放)
|
||||
保存按钮 = handleSaveAgentAndRecalculate,不会立即重启编排,只更新
|
||||
agentConfigs;真正生效在下一次该席位被 leader 派活时。 */}
|
||||
{selectedAgentId && (
|
||||
<div className="mx-6 mb-4 p-4.5 bg-gradient-to-r from-[var(--brand-200)]/50 via-[var(--brand-200)]/15 to-white border-2 border-primary rounded-2xl shadow-[0_8px_30px_rgba(245,34,45,0.06)] relative animate-fade-in">
|
||||
<button
|
||||
|
||||
@@ -863,19 +863,13 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
|
||||
# Stateless Runs API (stream/wait without a pre-existing thread)
|
||||
app.include_router(runs.router)
|
||||
|
||||
# Multi-agent orchestration (coordinator + sub-agent broadcast/dispatch)
|
||||
app.include_router(multi_agent.router)
|
||||
|
||||
# Task-intent agent (Step 1 of the roundtable flow): single built-in
|
||||
# agent runs a 2-5 turn clarification dialogue, then hands a structured
|
||||
# {objective, constraints, assumptions} summary off to the multi-agent
|
||||
# roundtable as its initial intent.
|
||||
app.include_router(intent.router)
|
||||
|
||||
# Agent recommendation (between Step 1 and Step 2): given the intent
|
||||
# summary + a frontend-filtered candidate pool, the built-in
|
||||
# roundtable-recommender picks 2-6 agents most relevant to the task.
|
||||
app.include_router(recommend.router)
|
||||
# --- 圆桌规划三步流（前端 /page/workspace/roundtable/planning）---
|
||||
# 实现见 app/gateway/routers/{multi_agent,intent,recommend}.py；
|
||||
# 文档见 frontend-web/docs/multi-agent-backend-dev.md
|
||||
app.include_router(multi_agent.router) # Step 2：init(SSE) + run/stream(leader|special)
|
||||
app.include_router(intent.router) # Step 1：/api/intent/init + /stream
|
||||
app.include_router(recommend.router) # Step 1→2：/api/recommend/stream（无 init）
|
||||
# Step 3 产物列表/下载复用下方 artifacts.router（/api/threads/{id}/artifacts）
|
||||
|
||||
@app.get("/health", tags=["health"])
|
||||
async def health_check() -> dict:
|
||||
|
||||
@@ -142,11 +142,18 @@ def collect_outputs_listing(outputs_dir: Path) -> list[dict]:
|
||||
)
|
||||
@require_permission("threads", "read", owner_check=True)
|
||||
async def list_artifacts(thread_id: str, request: Request) -> dict:
|
||||
"""List artifact files generated by the agent under outputs/.
|
||||
"""列出 thread 在 ``outputs/`` 下生成的产物文件。
|
||||
|
||||
Walks ``backend/.deer-flow/users/{user_id}/threads/{thread_id}/user-data/outputs/``
|
||||
recursively. Returns an empty list if the directory does not exist (e.g. the
|
||||
thread has not produced any artifacts yet).
|
||||
圆桌 Step 3（``HighFidelityReport``）对每个**子席位** thread_id 调用本接口，
|
||||
展示各智能体写入沙箱 ``mnt/user-data/outputs/`` 的文件；协调智能体 thread
|
||||
通常无独立交付文件。
|
||||
|
||||
遍历路径::
|
||||
|
||||
.deer-flow/users/{user_id}/threads/{thread_id}/user-data/outputs/
|
||||
|
||||
返回 ``{ "thread_id", "files": [{ path, name, size_bytes, mime_type, modified_at }] }``，
|
||||
目录不存在时 ``files`` 为空数组（非 404）。
|
||||
"""
|
||||
outputs_dir = get_paths().sandbox_outputs_dir(thread_id, user_id=get_effective_user_id())
|
||||
return {"thread_id": thread_id, "files": collect_outputs_listing(outputs_dir)}
|
||||
|
||||
@@ -1,13 +1,52 @@
|
||||
"""Task-intent agent endpoints (Step 1 of the roundtable flow).
|
||||
"""圆桌规划 · 第一步「任务理解」Gateway 路由。
|
||||
|
||||
Lightweight wrapper around the lead-agent runtime that runs a single built-in
|
||||
agent (``roundtable-intent``) on its own thread. The agent's job is to do 2-5
|
||||
clarifying turns with the user and then emit a structured
|
||||
``{objective, constraints, assumptions}`` summary the frontend hands off to
|
||||
the multi-agent roundtable as its initial intent.
|
||||
前端页面：``/page/workspace/roundtable/planning`` Step 1
|
||||
前端模块：``frontend-web/src/roundtable-planning/api/intent.ts``
|
||||
|
||||
Same SSE shape as ``multi_agent.py`` (transparent passthrough + appended
|
||||
status frame), so the frontend can reuse the same reader pattern.
|
||||
职责
|
||||
----
|
||||
在独立 thread 上运行内置智能体 ``roundtable-intent``（SOUL 见
|
||||
``.deer-flow/agents/roundtable-intent/SOUL.md``），与用户进行 2–5 轮澄清，
|
||||
最终输出结构化意图 ``{objective, constraints, assumptions}``，供 Step 2
|
||||
总控协调智能体作为初始 prompt。
|
||||
|
||||
与 ``multi_agent.py`` 的关系
|
||||
---------------------------
|
||||
- **复用**同一套 loopback 工具：``_stream_upstream``、``_run_payload``、
|
||||
``_parse_last_messages`` 等，保证 SSE 透传 + 末尾状态帧的解析逻辑一致。
|
||||
- **不复用** ``/init`` 的协调智能体创建逻辑：intent 是长期注册的内置 agent，
|
||||
只需 ``POST /api/intent/init`` 创建 thread 即可。
|
||||
|
||||
SSE 协议（与前端 ``streamIntent`` 对齐）
|
||||
--------------------------------------
|
||||
1. 透传 LangGraph ``/api/threads/{id}/runs/stream`` 的全部 ``data:`` 行
|
||||
（含 ``messages-tuple`` 增量，供 UI 流式打字）。
|
||||
2. 流结束后追加**一条** JSON 状态帧（``data: {...}\\n\\n``），字段：
|
||||
|
||||
``status`` — 终态枚举：
|
||||
- ``asking``：本轮无 ``ask_clarification``，模型仍在追问或闲聊；
|
||||
- ``clarification``：本轮以澄清工具结束，需用户选选项/自定义输入；
|
||||
- ``done``：已解析 ``[INTENT_READY]`` + JSON 块，``summary`` 有值；
|
||||
- ``error``：上游或网关异常。
|
||||
|
||||
``content`` — 展示用 AI 正文（澄清时优先用 tool 后的 follow-up 文本）。
|
||||
|
||||
仅 ``status == "done"`` 时带 ``summary``；澄清时还带
|
||||
``question``、``clarification_type``、``clarification_context``、
|
||||
``options``、``allow_custom``、``allow_multiple``（见 ``resolve_allow_multiple``）。
|
||||
|
||||
终态判定优先级（实现细节，勿随意调整）
|
||||
------------------------------------
|
||||
1. **``[INTENT_READY]`` 优先**：从最新消息向前扫描 AIMessage，正则匹配
|
||||
SOUL 规定的 ``[INTENT_READY]\\n```json {...} `````；即使最后一条消息仍带
|
||||
过期的 ``ask_clarification`` tool_call，也返回 ``done``（避免前端卡在澄清 UI）。
|
||||
2. 否则看最后一条带 ``tool_calls`` 的 AIMessage 是否含 ``ask_clarification``。
|
||||
3. 否则 ``asking``。
|
||||
|
||||
工具白名单
|
||||
----------
|
||||
``excluded_tools`` 屏蔽除 ``ask_clarification`` 外的一切工具，防止模型偏离
|
||||
澄清任务去写文件、派活等（SOUL 文字约束不可靠，硬排除更稳）。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -40,11 +79,11 @@ from deerflow.tools.builtins.clarification_utils import resolve_allow_multiple
|
||||
logger = logging.getLogger(__name__)
|
||||
router = APIRouter(prefix="/api/intent", tags=["intent"])
|
||||
|
||||
# 内置 agent 目录名，须与 ``.deer-flow/agents/roundtable-intent/`` 一致。
|
||||
INTENT_AGENT_ID = "roundtable-intent"
|
||||
|
||||
# Matches the SOUL-mandated handoff signal: a [INTENT_READY] line followed by
|
||||
# a ```json ... ``` block. The model is told to emit this only when it judges
|
||||
# the user's task is fully specified.
|
||||
# SOUL 规定的交接信号：``[INTENT_READY]`` + markdown json 代码块。
|
||||
# group(1) 解析为 IntentSummary；解析失败则继续走澄清/asking 分支。
|
||||
_INTENT_READY_PATTERN = re.compile(
|
||||
r"\[INTENT_READY\]\s*```json\s*(\{.*?\})\s*```",
|
||||
re.DOTALL,
|
||||
@@ -53,12 +92,17 @@ _INTENT_READY_PATTERN = re.compile(
|
||||
|
||||
@router.post("/init")
|
||||
async def init_intent(request: Request, payload: dict = Body(...)) -> dict[str, Any]:
|
||||
"""Create a fresh thread for an intent-clarification session.
|
||||
"""创建任务理解会话用的空 thread。
|
||||
|
||||
Returns the stable built-in ``agent_id`` so the frontend doesn't need to
|
||||
know it. Unlike multi-agent ``/init``, no coordinator is built — the
|
||||
intent agent is long-lived and already registered via the legacy
|
||||
agent-sync path on disk.
|
||||
请求体：``{ "model": "deepseek-chat" }``（可选，当前 init 未把 model 写入 thread，
|
||||
实际模型在 ``/stream`` 的每次 run 里指定）。
|
||||
|
||||
响应::
|
||||
|
||||
{ "status": "success", "agent_id": "roundtable-intent", "thread_id": "<uuid>" }
|
||||
|
||||
与 ``POST /api/multi-agent/init`` 的区别：不创建协调智能体、不建多席位
|
||||
thread 映射；agent 本身已通过磁盘 ``.deer-flow/agents/`` 同步注册。
|
||||
"""
|
||||
base = _loopback_base(request)
|
||||
headers = _auth_headers(request)
|
||||
@@ -119,6 +163,7 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
# everything else so the model can't drift into solutioning
|
||||
# (e.g. saving a design doc with write_file) — the model
|
||||
# tends to ignore SOUL prose, hard exclusion is reliable.
|
||||
# 仅保留 ask_clarification；其余工具见模块 docstring「工具白名单」。
|
||||
excluded_tools=[
|
||||
"web_search",
|
||||
"present_files",
|
||||
@@ -139,6 +184,7 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
skill_stop_names=[],
|
||||
)
|
||||
|
||||
# captured：上游 SSE 全部 data 行，用于流结束后从 values 快照取 messages。
|
||||
captured: list[str] = []
|
||||
async for line, done in _stream_upstream(client, base, headers, thread_id, body):
|
||||
if line is not None:
|
||||
@@ -148,9 +194,10 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
|
||||
messages = _parse_last_messages(captured)
|
||||
|
||||
# [INTENT_READY] wins over ask_clarification: the model may emit
|
||||
# the handoff marker in an earlier AI message while the latest
|
||||
# dispatch still carries a stale clarification tool call.
|
||||
# --- 终态分支 1：结构化意图已就绪（最高优先级）---
|
||||
# 模型可能在较早的 AIMessage 里已输出 [INTENT_READY]，而最后一轮
|
||||
# 仍残留 ask_clarification 的 tool_calls；必须先扫 READY，否则前端
|
||||
# 会错误展示澄清卡片且 intentReady 无法解锁 Step 2。
|
||||
summary: dict[str, Any] | None = None
|
||||
ready_text: str = ""
|
||||
for msg in reversed(messages):
|
||||
@@ -177,9 +224,9 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
yield f"data: {json.dumps(final_frame, ensure_ascii=False)}\n\n"
|
||||
return
|
||||
|
||||
# Find the latest AIMessage with tool_calls (typically
|
||||
# ask_clarification) — falls back to the latest plain
|
||||
# AIMessage when the model produced no tool call.
|
||||
# --- 终态分支 2：本轮以 ask_clarification 结束 ---
|
||||
# _find_dispatch_message：从后往前找带 tool_calls 的 AIMessage
|
||||
# （SkillStop/澄清 ToolMessage 之后的那条 AI 消息）。
|
||||
dispatch_msg = _find_dispatch_message(messages)
|
||||
content = _flatten_content(dispatch_msg.get("content", ""))
|
||||
tool_calls = dispatch_msg.get("tool_calls") or []
|
||||
@@ -191,6 +238,8 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
if clarification_call is not None:
|
||||
cargs = clarification_call.get("args") or {}
|
||||
question = str(cargs.get("question") or "").strip()
|
||||
# ClarificationMiddleware 常在 tool 之后还有一条纯文本 AIMessage，
|
||||
# 比 tool_call 旁的短 preamble 更适合作为气泡正文。
|
||||
follow_up = _find_trailing_ai_text(messages, exclude_text=content)
|
||||
display_content = follow_up or content or question
|
||||
final_frame: dict[str, Any] = {
|
||||
@@ -207,6 +256,7 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
yield f"data: {json.dumps(final_frame, ensure_ascii=False)}\n\n"
|
||||
return
|
||||
|
||||
# --- 终态分支 3：普通 AI 回复，继续多轮对话 ---
|
||||
final_frame: dict[str, Any] = {
|
||||
"status": "asking",
|
||||
"content": content,
|
||||
|
||||
@@ -1,18 +1,47 @@
|
||||
"""Multi-agent orchestration endpoints.
|
||||
"""圆桌规划 · Step 2「多智能体研讨」Gateway 路由。
|
||||
|
||||
Wraps the legacy ``newpython/OUT.py`` demo into the Gateway. Provides:
|
||||
前端页面：``RoundtablePlanningPage`` Step 2
|
||||
前端模块：``frontend-web/src/roundtable-planning/api/multi-agent.ts``
|
||||
|
||||
* ``POST /api/multi-agent/init`` — create a coordinator agent and per-sub-agent
|
||||
threads. Returns the ``{agent_name: thread_id}`` map the client passes back
|
||||
on subsequent calls.
|
||||
* ``POST /api/multi-agent/run/stream`` — drive a *leader* or *special* agent
|
||||
via SSE. The leader dispatches work to sub-agents through the
|
||||
``agent_orchestration`` skill; sub-agents execute and broadcast their result.
|
||||
本模块把原 ``newpython/OUT.py`` 演示编排进 FastAPI Gateway，通过 **HTTP loopback**
|
||||
（``127.0.0.1`` + 调用方 ``Authorization``）复用既有 ``/api/threads``、
|
||||
``/api/agents``、``/api/threads/{id}/runs/stream``，不再硬编码 token。
|
||||
|
||||
Internal calls loop back to the same Gateway over HTTP, reusing the caller's
|
||||
``Authorization`` header — so the demo's hard-coded ``get_token("ji")`` is gone.
|
||||
The model used by both the coordinator agent and every streamed run is taken
|
||||
from the request's ``model`` field.
|
||||
对外接口
|
||||
--------
|
||||
1. ``POST /api/multi-agent/init``（SSE）
|
||||
- 为每个研讨席位（``agent_names``）并行创建 thread，按完成顺序推送
|
||||
``seat_ready``；
|
||||
- 动态创建**当次会话**的总控协调智能体（``main_agent_name``，如
|
||||
``roundtable-coordinator-xxx``），写入席位列表 SOUL + ``agent_orchestration`` skill；
|
||||
- 结束帧 ``init_done`` 携带 ``thread_ids: { agent_name: thread_id, ... }``，
|
||||
含协调智能体自身 thread。
|
||||
|
||||
2. ``POST /api/multi-agent/run/stream``（SSE）
|
||||
- ``agent_type=leader``：总控一轮——可能派活、可能澄清、可能共识（空 dispatch）；
|
||||
- ``agent_type=special``：单席位子智能体执行一轮交付。
|
||||
|
||||
跨席位「广播」语义
|
||||
------------------
|
||||
通过 ``_append_thread_message`` 向其它 thread 的 checkpoint ``messages`` 追加
|
||||
**只读上下文**的 human 消息（非触发 run），使各席位 LangGraph 状态里能看到
|
||||
总控派活/用户干预/子 agent 完成摘要。前端编排循环仍靠显式多次 ``/run/stream``
|
||||
驱动各 agent 真正推理。
|
||||
|
||||
Leader 终态帧（前端 ``isFinalStatusFrame``）
|
||||
-------------------------------------------
|
||||
- ``status: [[agent_name, task], ...]`` — 派活列表，前端并行 special run；
|
||||
- ``status: []`` — 无 tool_calls，视为共识，可进 Step 3；
|
||||
- ``status: "clarification"`` — 总控 ``ask_clarification``，前端暂停编排展示澄清条；
|
||||
- ``status: "子智能体 X 完成..."`` — special 完成（字符串状态）；
|
||||
- ``status: "error"`` — 失败。
|
||||
|
||||
共享导出
|
||||
--------
|
||||
``intent.py`` / ``recommend.py`` 从此模块 import 底层流式与消息解析函数，
|
||||
勿在 intent/recommend 中重复实现 loopback 逻辑。
|
||||
|
||||
相关文档：``frontend-web/docs/multi-agent-backend-dev.md``
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -34,11 +63,12 @@ router = APIRouter(prefix="/api/multi-agent", tags=["multi-agent"])
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Loopback helpers
|
||||
# Loopback 辅助函数（Gateway → Gateway，同进程）
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _loopback_base(request: Request) -> str:
|
||||
"""当前请求的 scheme+host，用于 httpx 打回本机 Gateway。"""
|
||||
return f"{request.url.scheme}://{request.url.netloc}"
|
||||
|
||||
|
||||
@@ -50,6 +80,7 @@ def _auth_headers(request: Request) -> dict[str, str]:
|
||||
|
||||
|
||||
async def _create_thread(client: httpx.AsyncClient, base: str, headers: dict[str, str]) -> str:
|
||||
"""``POST /api/threads`` → 新 thread_id（intent/recommend/init 席位均用）。"""
|
||||
resp = await client.post(f"{base}/api/threads", json={}, headers=headers)
|
||||
resp.raise_for_status()
|
||||
return resp.json()["thread_id"]
|
||||
@@ -93,6 +124,11 @@ async def _append_thread_message(
|
||||
thread_id: str,
|
||||
content: str,
|
||||
) -> None:
|
||||
"""向指定 thread 的 checkpoint 追加一条 human 消息（广播上下文，不触发 LLM run）。
|
||||
|
||||
失败只打 warning，不阻断主流程——广播是 best-effort，席位真正干活仍靠
|
||||
前端对该席位 thread 发起的 ``/run/stream``。
|
||||
"""
|
||||
state_url = f"{base}/api/threads/{thread_id}/state"
|
||||
get_resp = await client.get(state_url, headers=headers)
|
||||
if get_resp.status_code != 200:
|
||||
@@ -118,6 +154,7 @@ async def _broadcast(
|
||||
agent_threads: dict[str, str],
|
||||
skip: list[str],
|
||||
) -> None:
|
||||
"""并行向 ``agent_threads`` 中除 ``skip`` 外的所有 thread 追加同一条 human 消息。"""
|
||||
targets = [tid for name, tid in agent_threads.items() if name not in skip]
|
||||
if not targets:
|
||||
return
|
||||
@@ -214,6 +251,13 @@ def _run_payload(
|
||||
excluded_tools: list[str],
|
||||
skill_stop_names: list[str],
|
||||
) -> dict[str, Any]:
|
||||
"""构造 ``POST /api/threads/{thread_id}/runs/stream`` 的请求体。
|
||||
|
||||
- ``context.agent_name``：本次 run 使用的 agent（内置 id 或 init 创建的 coordinator id）。
|
||||
- ``excluded_tools``：按路由裁剪工具面（intent 仅澄清、special 禁派活等）。
|
||||
- ``skill_stop_names``：leader 侧配合 SkillStopMiddleware 在 ``agent_orchestration``
|
||||
调用后截断图，以便网关从 AIMessage.tool_calls 解析派活列表。
|
||||
"""
|
||||
return {
|
||||
"input": {
|
||||
"messages": [
|
||||
@@ -246,26 +290,31 @@ def _run_payload(
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Init endpoint
|
||||
# POST /api/multi-agent/init — Step 2 席位 + 总控初始化（SSE）
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@router.post("/init")
|
||||
async def init_multi_agent(request: Request, payload: dict = Body(...)) -> StreamingResponse:
|
||||
"""Streaming /init.
|
||||
"""流式初始化圆桌 Step 2 所需的 thread 映射与协调智能体。
|
||||
|
||||
Emits text/event-stream frames as each seat/coordinator becomes ready, so
|
||||
the frontend can visualize the parallel bring-up rather than blocking on
|
||||
one bulk JSON. Frames:
|
||||
请求体::
|
||||
|
||||
data: {"event":"seat_ready","agent_name":"...","thread_id":"...","display_name":"...","description":"..."}
|
||||
data: {"event":"coordinator_ready","main_agent_name":"...","thread_id":"..."}
|
||||
data: {"event":"init_done","main_agent_name":"...","thread_ids":{...}}
|
||||
data: {"event":"error","detail":"..."} # on failure
|
||||
{
|
||||
"agent_names": ["roundtable-intelligence", ...], // 用户选的席位 id
|
||||
"main_agent_name": "roundtable-coordinator-xxx", // 当次总控 id，前端生成
|
||||
"model": "deepseek-chat" // 可选，写入 coordinator agent
|
||||
}
|
||||
|
||||
Validation errors (missing agent_names, bad id pattern) still raise
|
||||
HTTPException synchronously so the connection fails fast with a real 4xx
|
||||
instead of a 200 SSE that just carries an error frame.
|
||||
SSE 事件（每条 ``data: {...}\\n\\n``）::
|
||||
|
||||
seat_ready — 某一席位 thread 已创建（``asyncio.as_completed`` 顺序，先完先发）
|
||||
coordinator_ready — 总控 agent + thread 已就绪
|
||||
init_done — ``thread_ids`` 全量映射，前端存 ``threadIds`` 并开始编排
|
||||
error — 失败详情（同步校验失败则直接 HTTP 4xx，不进 SSE）
|
||||
|
||||
协调智能体 SOUL 在运行时根据各席位 ``GET /api/agents/{id}`` 的 name/description 拼接，
|
||||
强调 ``agent_name`` 必须用英文 id（``roundtable-intelligence``），禁止带中文括号后缀。
|
||||
"""
|
||||
agent_names_in = payload.get("agent_names") or []
|
||||
agent_names: list[str] = [str(name).lower() for name in agent_names_in]
|
||||
@@ -330,6 +379,7 @@ async def init_multi_agent(request: Request, payload: dict = Body(...)) -> Strea
|
||||
for sid, _, display_name, description in prepared
|
||||
]
|
||||
|
||||
# 动态 SOUL：把本次 init 的席位列表写进总控 prompt，供 agent_orchestration 派活。
|
||||
soul = (
|
||||
"#核心定位：\n"
|
||||
"用途：根据用户的任务目标,调用其他智能体干活,只负责协调汇总,"
|
||||
@@ -388,7 +438,7 @@ async def init_multi_agent(request: Request, payload: dict = Body(...)) -> Strea
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Stream endpoint
|
||||
# 上游 LangGraph SSE 透传（intent / recommend / leader / special 共用）
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@@ -399,7 +449,15 @@ async def _stream_upstream(
|
||||
thread_id: str,
|
||||
body: dict[str, Any],
|
||||
) -> AsyncIterator[tuple[str | None, list[str] | None]]:
|
||||
"""Yield (raw_line, None) for each SSE line, then ``(None, captured_data_lines)`` once."""
|
||||
"""消费 ``/api/threads/{thread_id}/runs/stream``，逐行 yield 原始 SSE。
|
||||
|
||||
产出元组：
|
||||
- ``(line, None)`` — 可原样转发给浏览器（含 ``event:`` / ``data:`` 行）；
|
||||
- ``(None, captured)`` — 流结束，``captured`` 为所有 ``data:`` 行文本列表，
|
||||
供 ``_parse_last_messages`` 从倒数 values 快照提取 ``messages``。
|
||||
|
||||
日志 ``[upstream-timing]``：排查首 token 慢、代理导致 loopback 超时（见 trust_env=False）。
|
||||
"""
|
||||
|
||||
url = f"{base}/api/threads/{thread_id}/runs/stream"
|
||||
captured: list[str] = []
|
||||
@@ -521,12 +579,19 @@ async def _leader_run(
|
||||
skill_stop_names: list[str],
|
||||
model_name: str,
|
||||
) -> AsyncIterator[str | dict[str, Any]]:
|
||||
# Fine-grained timing for the leader path. The user reported the
|
||||
# coordinator "stalls before output" — we log each major await so we can
|
||||
# see whether the wait is in pre-broadcast scheduling, upstream stream
|
||||
# setup, first-token latency, or post-stream parsing.
|
||||
"""总控（leader）单轮：透传上游 SSE + 末尾 yield 一个 dict 状态帧（由路由层 ``json.dumps``）。
|
||||
|
||||
时序要点：
|
||||
1. **预广播**（与 LLM 并行）：把用户/综合消息写入其它席位 thread，skip 总控自身；
|
||||
2. 跑总控 thread 的 stream，yield 每一行原始 SSE；
|
||||
3. 解析 messages → 澄清 / 空 dispatch（共识）/ 派活列表；
|
||||
4. 若有派活，**派活广播**后再 yield ``{status: dispatched, ...}``。
|
||||
|
||||
``skill_stop_names`` 会与 ``agent_orchestration`` 合并，确保 middleware 在工具调用后停图。
|
||||
"""
|
||||
t0 = time.perf_counter()
|
||||
|
||||
# 与上游 LLM 并行，减少「总控已开始想但席位 thread 里还没有用户消息」的窗口。
|
||||
pre_broadcast_task = asyncio.create_task(
|
||||
_broadcast(client, base, headers, "总控智能体收到用户消息:" + new_message, agent_threads, [agent_name])
|
||||
)
|
||||
@@ -595,12 +660,8 @@ async def _leader_run(
|
||||
leader_text = _flatten_content(dispatch_msg.get("content", ""))
|
||||
tool_calls = dispatch_msg.get("tool_calls") or []
|
||||
|
||||
# Clarification branch: the coordinator called ask_clarification. The
|
||||
# ClarificationMiddleware intercepts with Command(goto=END) and stashes
|
||||
# the structured question in the tool_call args; sometimes a richer
|
||||
# follow-up AIMessage is also produced after the ToolMessage. Emit a
|
||||
# dedicated frame so the frontend can render it as a question instead of
|
||||
# treating an empty dispatch as "consensus reached".
|
||||
# 澄清分支：与 intent.py 相同字段；status 为字符串 "clarification"（非数组），
|
||||
# 前端据此暂停 runOrchestration 循环，展示 Step 2 澄清条。
|
||||
clarification_call = next(
|
||||
(tc for tc in tool_calls if (tc.get("name") or "").lower() == "ask_clarification"),
|
||||
None,
|
||||
@@ -623,10 +684,11 @@ async def _leader_run(
|
||||
return
|
||||
|
||||
if not tool_calls:
|
||||
# 空 status 数组 = 总控不再派活，前端视为共识（hasConsensus）。
|
||||
yield {"status": [], "content": leader_text, "agent_name": agent_name}
|
||||
return
|
||||
|
||||
# Run all dispatch broadcasts concurrently — they target disjoint thread
|
||||
# 派活广播：告知各席位「总控给 X 派了什么活」，与即将发起的 special run 配合。
|
||||
# sets and we don't care about ordering, so serializing them just
|
||||
# multiplied latency before the frontend could start a sub-agent run.
|
||||
dispatched: list[list[str]] = []
|
||||
@@ -673,7 +735,13 @@ async def _special_run(
|
||||
skill_stop_names: list[str],
|
||||
model_name: str,
|
||||
) -> AsyncIterator[str | dict[str, Any]]:
|
||||
# Same instrumentation as _leader_run so all 6 seats are diagnosable.
|
||||
"""子智能体（special）单轮：执行总控下发的 task 文本，交付 content。
|
||||
|
||||
- ``excluded_tools`` 禁用派活/澄清等，避免席位抢总控活；
|
||||
- 终态 ``status`` 为描述性字符串（非数组），``content`` 为交付正文；
|
||||
- **后广播**在 yield 终态帧之后 await，保证其它席位 state 里有完成摘要，
|
||||
同时尽量让前端先收到结果关闭 loading。
|
||||
"""
|
||||
t0 = time.perf_counter()
|
||||
thread_id = agent_threads[agent_name]
|
||||
body = _run_payload(
|
||||
@@ -759,8 +827,29 @@ async def _special_run(
|
||||
)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# POST /api/multi-agent/run/stream — leader / special 单轮 SSE
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@router.post("/run/stream")
|
||||
async def run_multi_agent_stream(request: Request, payload: dict = Body(...)) -> StreamingResponse:
|
||||
"""驱动总控或子智能体的一轮 LangGraph run。
|
||||
|
||||
请求体::
|
||||
|
||||
{
|
||||
"agent_type": "leader" | "special",
|
||||
"d_agent_thread_id": { "<agent_id>": "<thread_id>", ... }, // init_done.thread_ids
|
||||
"agent_name": "<本次运行的 agent_id>",
|
||||
"new_message": "<用户消息或派活 task 文本>",
|
||||
"model": "deepseek-chat",
|
||||
"skill_stop_names": [] // 可选，leader 一般留空，由网关注入 agent_orchestration
|
||||
}
|
||||
|
||||
响应：上游 SSE 行透传 + 末尾一条 ``data:`` JSON（leader 为 dict，special 同上）。
|
||||
客户端应使用 AbortSignal 支持「挂起协商」时取消 in-flight 请求。
|
||||
"""
|
||||
agent_type: str = str(payload.get("agent_type") or "leader").lower()
|
||||
agent_threads: dict[str, str] = payload.get("d_agent_thread_id") or {}
|
||||
agent_name: str = str(payload.get("agent_name") or "").lower()
|
||||
|
||||
@@ -1,20 +1,39 @@
|
||||
"""Agent recommendation endpoint (between Step 1 and Step 2 of the roundtable flow).
|
||||
"""圆桌规划 · Step 1→2 之间「智能体推荐」Gateway 路由。
|
||||
|
||||
Given the Step-1 intent summary (``objective`` + ``constraints`` + ``assumptions``)
|
||||
and a frontend-filtered candidate agent pool, drives the built-in
|
||||
``roundtable-recommender`` agent to pick 2-6 agents most relevant to the task
|
||||
and explain why.
|
||||
前端页面：推荐弹窗 ``RecommendAgentsDialog``
|
||||
前端模块：``frontend-web/src/roundtable-planning/api/recommend.ts``
|
||||
|
||||
Single one-shot endpoint — no ``/init`` is exposed because the recommendation
|
||||
is stateless: the agent never needs the prior turn's history. We create a
|
||||
fresh thread internally per request and let the LangGraph runtime clean it up
|
||||
in the background. The frontend handles filtering ``roundtable-intent`` /
|
||||
``roundtable-recommender`` / ``roundtable-coordinator-*`` out of the candidate
|
||||
pool before calling here.
|
||||
职责
|
||||
----
|
||||
根据 Step 1 的 ``IntentSummary`` 与前端过滤后的候选池，驱动内置
|
||||
``roundtable-recommender``（SOUL 见 ``.deer-flow/agents/roundtable-recommender/``），
|
||||
输出 2–6 个 ``{agent_id, reason}`` 推荐席位。
|
||||
|
||||
SSE shape is the same family as ``intent.py`` / ``multi_agent.py``:
|
||||
transparent passthrough of the upstream LangGraph stream, then a single
|
||||
status frame appended at the end so the frontend can finalize.
|
||||
设计为**无状态单次调用**：
|
||||
- **不暴露** ``/init``：每次请求内部 ``_create_thread``，推荐 agent 不需要历史轮次。
|
||||
- 候选池过滤由前端完成（剔除 ``roundtable-intent``、``roundtable-recommender``、
|
||||
``roundtable-coordinator-*``），本路由只做校验与 clamp。
|
||||
|
||||
SSE 协议
|
||||
--------
|
||||
1. 透传上游 LangGraph 流（前端用 ``parseRecommendStreamContent`` 把正文拆成
|
||||
``[RECOMMEND_READY]`` 前的 ``rationale`` 与 JSON 里的 ``picks``，实现卡片增量渲染）。
|
||||
2. 末尾状态帧::
|
||||
|
||||
{ "status": "done"|"asking"|"error", "content": "<全文>", "picks": [...]|null }
|
||||
|
||||
- ``done``：``picks`` 经 ``_validate_picks`` 后 ≥2 条且 id 均在候选池内；
|
||||
- ``asking``：未匹配 ``[RECOMMEND_READY]`` 或校验后不足 2 条（前端走 FALLBACK 默认 6 席）；
|
||||
- ``error``：HTTP/未捕获异常。
|
||||
|
||||
与 SOUL 的契约
|
||||
--------------
|
||||
模型须在自然语言思路后输出::
|
||||
|
||||
[RECOMMEND_READY]
|
||||
```json
|
||||
{"picks": [{"agent_id": "...", "reason": "..."}, ...]}
|
||||
```
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -43,15 +62,14 @@ router = APIRouter(prefix="/api/recommend", tags=["recommend"])
|
||||
|
||||
RECOMMENDER_AGENT_ID = "roundtable-recommender"
|
||||
|
||||
# Matches the SOUL-mandated handoff signal: a [RECOMMEND_READY] line followed
|
||||
# by a ```json ... ``` block carrying {"picks": [{agent_id, reason}, ...]}.
|
||||
# 从模型最终 AIMessage 全文提取 picks；非贪婪 ``.*?`` 只匹配第一个 json 块。
|
||||
_RECOMMEND_READY_PATTERN = re.compile(
|
||||
r"\[RECOMMEND_READY\]\s*```json\s*(\{.*?\})\s*```",
|
||||
re.DOTALL,
|
||||
)
|
||||
|
||||
# Mirrors the SOUL constraint so a misbehaving model can't push >6 picks to
|
||||
# the frontend or fall below the "this isn't a roundtable" floor.
|
||||
# 与 SOUL / 前端 ``RecommendAgentsDialog`` 一致：少于 2 无法成桌，多于 6 由网关截断。
|
||||
# 前端确认按钮另限制 2≤N≤8（用户可手动多选），后端此处只负责模型输出校验。
|
||||
_MIN_PICKS = 2
|
||||
_MAX_PICKS = 6
|
||||
|
||||
@@ -178,8 +196,7 @@ async def stream_recommend(request: Request, payload: dict = Body(...)) -> Strea
|
||||
# proxy and wait ~40 seconds for timeout before falling back.
|
||||
async with httpx.AsyncClient(timeout=None, trust_env=False) as client:
|
||||
try:
|
||||
# One-shot recommendation: spin up a fresh thread per request.
|
||||
# The recommender never needs to see prior turns.
|
||||
# 每次推荐独立 thread；prompt 已包含完整 intent + 候选列表，无需多轮。
|
||||
thread_id = await _create_thread(client, base, headers)
|
||||
|
||||
body = _run_payload(
|
||||
@@ -187,7 +204,7 @@ async def stream_recommend(request: Request, payload: dict = Body(...)) -> Strea
|
||||
model_name=model_name,
|
||||
thread_id=thread_id,
|
||||
new_message=prompt,
|
||||
# Recommender is pure judgment: no tools, no dispatching.
|
||||
# 推荐只做判断：禁止澄清、派活、文件等，避免跑题或二次追问。
|
||||
excluded_tools=[
|
||||
"web_search",
|
||||
"present_files",
|
||||
@@ -217,6 +234,7 @@ async def stream_recommend(request: Request, payload: dict = Body(...)) -> Strea
|
||||
last_ai_content = text
|
||||
break
|
||||
|
||||
# 只扫描「最后一条非空 AIMessage」：推荐 agent 单轮输出，无多轮 READY 问题。
|
||||
picks: list[dict[str, str]] = []
|
||||
match = _RECOMMEND_READY_PATTERN.search(last_ai_content)
|
||||
if match:
|
||||
@@ -228,6 +246,7 @@ async def stream_recommend(request: Request, payload: dict = Body(...)) -> Strea
|
||||
if isinstance(parsed, dict):
|
||||
picks = _validate_picks(parsed.get("picks"), candidate_ids)
|
||||
|
||||
# asking ≠ 模型在追问用户，而是「网关未能产出合法 picks」，由前端 fallback。
|
||||
status_value = "done" if picks else "asking"
|
||||
final_frame: dict[str, Any] = {
|
||||
"status": status_value,
|
||||
|
||||
+13
-3
@@ -1,10 +1,20 @@
|
||||
"""Shared helpers for ask_clarification option selection mode."""
|
||||
"""ask_clarification 工具参数的共享解析（Harness + Gateway）。
|
||||
|
||||
圆桌 Step 1（``intent.py``）与 Step 2 总控（``multi_agent.py``）在 SSE 终态帧里
|
||||
都会带上 ``allow_multiple``，供前端 ``resolveAllowMultiple`` 决定选项卡片是
|
||||
「点击即发送（单选）」还是「多选 + 发送按钮」。
|
||||
|
||||
约定（与前端 ``roundtable-planning/lib/clarification.ts`` 一致）：
|
||||
- 模型**未传** ``allow_multiple`` 或传 ``null`` → **False**（单选）；
|
||||
- 仅当模型显式传 ``true`` 时才多选；
|
||||
- 不再根据 ``clarification_type`` 推断多选（旧逻辑已移除）。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
|
||||
def coerce_bool(value: object | None, *, default: bool) -> bool:
|
||||
"""Parse model/tool args that may arrive as bool, number, or string."""
|
||||
"""把 LLM tool args 里可能出现的 bool/数字/字符串统一成 bool。"""
|
||||
if value is None:
|
||||
return default
|
||||
if isinstance(value, bool):
|
||||
@@ -21,7 +31,7 @@ def coerce_bool(value: object | None, *, default: bool) -> bool:
|
||||
|
||||
|
||||
def resolve_allow_multiple(args: dict) -> bool:
|
||||
"""Return True only when the model explicitly requests multi-select."""
|
||||
"""是否允许多选。仅 ``args["allow_multiple"]`` 显式为真时返回 True。"""
|
||||
if "allow_multiple" in args and args["allow_multiple"] is not None:
|
||||
return coerce_bool(args["allow_multiple"], default=False)
|
||||
return False
|
||||
Reference in new issue
Block a user