wsk/deerflow-code

0 Fork 0

Files

T

gozeros da6521b6cb sync: complete remaining files (source dhk-1)

2026-10-21 15:14:06 +08:00

41 KiB

Raw Blame History

多智能体会商功能与接口梳理

1. 文档范围与入口

本文梳理的是常规「多智能体会商 / 圆桌规划」页面 RoundtablePlanningPage 的完整三步流程：

任务意图理解
多智能体研讨
方案结果展示

主入口为 /page/workspace/qa/multi-agent-roundtable。它也可由任务深链 3qfx-A、rwfx-A、xdfx-A 打开，分别挂载在任务管理下的三情、任务、行动业务路由中；另有 #/embed/roundtable 嵌入入口。

任务深链会预填任务名称、任务目标、业务编码和任务 ID，并自动选择对应业务链：

深链	业务编码	嵌入路由
`3qfx-A`	`3Q`	`/page/strategy/task-management/plan-task-sentiment/roundtable`
`rwfx-A`	`6BF`	`/page/strategy/task-management/plan-task/plan-task-fx/roundtable`
`xdfx-A`	`7BF`	`/page/strategy/task-management/plan-task/plan-task-action/roundtable`

本文不展开独立的阵位会商，以及仅展示报告的 8BF 变体。8BF 复用了部分组件，但其第三步为 report-only，不属于常规三步会商主路径。

2. 公共机制

2.1 会商记录与保存

功能：

保存任务意图、研讨过程、会商结论、第三步报告及当前已完成步骤。
支持新建会商、历史记录切换、重命名、删除和从已有记录继续。
普通入口按当前用户隔离；任务深链按任务共享，进入同一任务的用户看到同一批会商和后台任务。
更新使用乐观锁；版本不一致时后端返回 409，前端应以服务端最新记录为准后再处理。

接口：

场景	接口	调用方式与参数
普通会商列表	`GET /api/roundtable-drafts`	无请求体，按当前用户返回。
新建普通会商	`POST /api/roundtable-drafts`	JSON：`{ id?, title, furthest_step, step1, step2, step3 }`。
读取/更新/删除普通会商	`GET/PUT/DELETE /api/roundtable-drafts/{draftId}`	`PUT` 传需更新字段及 `expected_version`。
任务会商列表	`GET /api/roundtable-task-drafts/by-task/{taskId}`	`taskId` 为任务 ID。
读取最新任务会商	`GET /api/roundtable-task-drafts/by-task/{taskId}/latest`	用于任务进入后恢复最近一次会商。
新建任务会商	`POST /api/roundtable-task-drafts`	JSON：`{ id?, task_id, title, furthest_step, step1, step2, step3 }`。
读取/更新/删除任务会商	`GET/PUT/DELETE /api/roundtable-task-drafts/{draftId}`	`PUT` 为局部更新并携带 `expected_version`。

参数说明：

step1、step2、step3 保存的是各步骤可恢复的完整页面状态，而不是单一文本。
furthest_step 记录用户历史上到达的最远步骤，用于恢复导航可用性。
xdfx-A 的页面记录和后台任务分区使用 URL 原始行动 ID；任务正文及任务详情仍使用解析后的实际任务 ID。

2.2 流式调用与附件

功能：

大模型回复、意图澄清、推荐、研讨、报告和流程图均通过 SSE 增量返回。
用户可停止当前流；前端按事件逐段追加正文、思考、工具调用、澄清卡片和错误信息。
有文件时先上传到对应线程，再将后端返回的虚拟路径传给后续流式接口。

附件接口：

POST /api/threads/{threadId}/uploads
Content-Type: multipart/form-data

files: <file>           # 可重复，支持多文件

响应中的 { filename, size, virtual_path } 应转换后传入流式请求：

{
  "files": [
    {
      "filename": "任务材料.docx",
      "size": 10240,
      "path": "/mnt/user-data/uploads/任务材料.docx",
      "status": "uploaded"
    }
  ]
}

所有 JSON 接口经前端 apiFetch 调用，自动携带当前登录态；流式接口使用 ReadableStream 解析 SSE。

第一步：任务意图理解

1. 功能

第一步将用户的自然语言任务转成可供多个智能体研讨的结构化意图，并确定后续参会智能体来源。

创建内置「任务意图理解」智能体会话，接收任务描述、补充材料和多轮追问。
流式展示智能体回复、思考过程和工具型澄清问题。
澄清卡支持单选、多选、自定义填写、跳过和继续追问；同一轮可返回多张澄清卡。
意图完成后生成可编辑的结构化摘要：目标（objective）、约束（constraints）、可选假设（assumptions）。
支持手工修改意图摘要后再进入下一步。
智能体选择有两条路径：
- 智能体推荐：依据意图，在可用智能体候选池中推荐参会人及理由。
- 业务链条：选择已配置的业务链条，带入席位、阶段、阶段目标、协调人提示词和席位模型策略。
任务深链模式自动加载任务卡片、预填任务上下文并自动选择业务链；普通模式在“选择参会智能体”弹窗中手工选择“我的”或“公共”业务链。

步骤流转：

输入任务 / 上传材料
        ↓
意图智能体澄清（可多轮）
        ↓
结构化意图完成并可编辑
        ↓
智能体推荐 或 选择业务链
        ↓
进入第二步

1.1 业务链功能与两个弹窗

业务链是可命名、可复用、可保存的“智能体编排模板”，不是单纯的智能体名单。一条链定义了谁参会、谁先后执行、哪些席位并行、每阶段应产出什么，以及协调人如何派发和汇总。

第一步中有两个职责不同的业务链入口：

入口	弹窗/页面	作用	是否直接开始研讨
页面顶栏“业务链条”	BusinessChainListDialog	浏览、筛选、启停、发布、进入配置页编辑业务链。	否，它是管理入口。
意图完成后点击“选择参会智能体 / 进入研讨”	RecommendAgentsDialog 的“业务链条”页签，内部为 BusinessChainPicker	从可用链中选择一条，校验席位后把编排结果带入第二步。	是，确认“进入研讨”后开始第二步。

A. 选择参会智能体弹窗中的“业务链条”页签

功能：

弹窗有“智能体推荐”和“业务链条”两个页签；切换到业务链条后不会调用推荐模型，而是读取已保存的链条。
可在“我的 / 公共”之间筛选：
- 我的：当前用户创建的业务链。
- 公共：已发布、所有账号都可查看和选用的业务链。
每张链条卡展示链条名称、描述、席位数和席位编排流：
- 线性链用“智能体 A → 智能体 B → 智能体 C”表示顺序。
- 同一阶段有多个席位时显示“并行 N”分组；阶段之间仍用箭头表示串行依赖。
- 实时智能体名称优先于链条保存时的名称快照；已删除智能体会置灰并提示。
仅启用的链条可进入选择列表；选中链条后，至少保留 2 个仍存在的可用席位 才能点击“进入研讨”。
如果链条配置了默认执行模式，弹窗顶部的执行模式会自动带入该值，用户仍可临时改为：
- flash：快速，不开启思考。
- thinking：思考，低推理强度。
- pro：专业问答，思考 + 中等推理强度。
- ultra：多智能体问答，思考 + 高推理强度，并允许席位调用子代理。
如果链条含有有效分层、阶段目标或协调人提示词，选择后按 dag 编排；否则按 chain 线性编排。
DAG 链在弹窗底部额外选择执行方式：
- 快速 · 双列禁写：同阶段席位并行，主区双列展示，并行席位不写文件。
- 沙箱 · 单列可写：同阶段仍并行，但主区单列展示，允许文件产出，右侧沙箱随当前席位切换。
“配置链条”按钮跳转到业务链编辑页；没有链条时也会显示“去配置业务链条”引导。

确认后传给第二步的运行结果可概括为：

{
  "agents": [
    {
      "agent_id": "agent-001",
      "name": "态势专家",
      "model": "该席位模型覆盖，可为空",
      "seat_skill_directive": true,
      "human_validation": false,
      "seatMode": "该席位推理深度覆盖，可为空"
    }
  ],
  "mode": "chain | dag",
  "chain": {
    "id": "chain-id",
    "title": "任务综合研判链"
  },
  "plan": {
    "stages": "仅 dag 时携带的分层执行计划"
  },
  "dagExecMode": "fast | sandbox",
  "seatMode": "本次会商的链条级执行模式",
  "gatherFirst": true
}

其中，席位数组的顺序就是线性链执行顺序；DAG 时按阶段展平。单席位的 seatMode、模型覆盖、技能识别强化和人工校验会一并继承到第二步。

B. 顶部“业务链条”管理弹窗

功能：

顶栏点击“业务链条”打开，定位为“浏览和管理”，不直接选择参会人。
支持按 我的 / 公共 / 全部（仅管理员） 筛选，再按 全部状态 / 启用 / 停用 过滤。
每张卡片展示：
- 名称、描述、席位数量；
- 公共、待审核、已停用等状态；
- 配置人和最后修改时间；
- 智能体编排流：同 Stage 的席位用“并行 N”分组，Stage 之间以箭头连接。
本人链条或管理员可在卡片上：
- 启用 / 停用；
- 发布为公共、取消发布；
- 草稿链提交审核，审核中可撤回；
- 点击“设置”跳转到该链条的编辑页。
新建和编辑页面包含：
- 基本信息：标题、描述、默认执行模式、研讨前并行取数开关、总控提示词。
- 链条编排：从候选智能体池拖拽到 Stage；可新建、删除、上下移动 Stage，移动/拆分/合并席位。
- 阶段目标：每个 Stage 可填写目标，并可使用 AI 优化；阶段目标会指导协调人该阶段产出什么、如何承接前一阶段结果。
- 总控提示词：说明协调人如何派发、汇总、收口，支持 Markdown 和 AI 优化。
- 席位级配置：模型覆盖、推理深度覆盖、会商技能识别强化、人工校验；岗位协同专用入口还可配置岗位归属和产物位置。
- 编排预览：以流程图检查“同层并行、层间串行”的最终结构。

两个业务链弹窗的页面结构：

顶部“业务链条”管理弹窗
┌ 标题和说明 ───────────────────────────────────────────────────────────┐
│ 筛选：我的 / 公共 / 全部（管理员）  ｜  全部状态 / 启用 / 停用          │
├ 业务链卡片列表 ───────────────────────────────────────────────────────┤
│ 名称、席位数、公共/待审核/停用状态、配置人、更新时间、说明              │
│ 智能体 A → [并行：智能体 B、智能体 C] → 智能体 D                       │
│ 操作：启停 / 发布或撤回 / 设置                                          │
├───────────────────────────────────────────────────────────────────────┤
│ 底部：配置（新建或跳转到业务链编辑页）                                  │
└───────────────────────────────────────────────────────────────────────┘

“选择参会智能体”弹窗的业务链页签
┌ 顶部：智能体推荐 ｜ 业务链条 ｜ 本次执行模式（快速/思考/专业/多智能体）┐
│ 筛选：我的 / 公共                                                        │
├ 链条选择卡片 ─────────────────────────────────────────────────────────┤
│ 名称、描述、席位数、线性/分层编排、已删除席位告警                         │
├───────────────────────────────────────────────────────────────────────┤
│ DAG 链：快速·双列禁写 ｜ 沙箱·单列可写                                 │
│ 底部：配置链条 ｜ 取消 ｜ 进入研讨                                      │
└───────────────────────────────────────────────────────────────────────┘

2. 接口、调用时机与传参

2.1 初始化意图会话

POST /api/intent/init
Content-Type: application/json

{
  "model": "模型标识，可选，使用页面当前模型",
  "task_context": {
    "task_id": "任务深链时的任务 ID",
    "task_name": "任务名称",
    "task_goal": "任务目标",
    "business_code": "3Q | 6BF | 7BF"
  },
  "intent_agent_id": "roundtable-intent"
}

说明：

普通会商一般省略 task_context，intent_agent_id 也可省略并由后端使用内置 roundtable-intent。
返回 { status, agent_id, thread_id }；后续上传与流式对话都使用此 thread_id。

2.2 发送任务或回答澄清问题

POST /api/intent/stream
Accept: text/event-stream

{
  "thread_id": "意图会话线程 ID",
  "message": "用户任务描述，或对澄清问题的答案",
  "model": "页面当前模型，可选",
  "intent_agent_id": "roundtable-intent",
  "task_context": {
    "task_id": "任务 ID",
    "task_name": "任务名称",
    "task_goal": "任务目标",
    "business_code": "业务编码"
  },
  "client_turn_id": "前端生成的幂等 ID",
  "files": [
    {
      "filename": "材料.pdf",
      "size": 10240,
      "path": "/mnt/user-data/uploads/材料.pdf",
      "status": "uploaded"
    }
  ]
}

主要 SSE 完成帧字段：

{
  "status": "asking | clarification | done | error",
  "content": "本轮可见回答",
  "summary": {
    "objective": "任务目标",
    "constraints": ["约束 1"],
    "assumptions": ["可选假设"]
  },
  "question": "单个澄清问题",
  "clarifications": ["多个澄清问题"],
  "clarification_type": "single | multiple | text",
  "clarification_context": {},
  "options": ["选项 A", "选项 B"],
  "allow_custom": true,
  "allow_multiple": false,
  "error_detail": "失败原因"
}

调用要点：

client_turn_id 用于避免重试或网络抖动造成同一用户轮次重复执行。
用户选项、填写的自定义答案、点击“继续/跳过”后，仍通过本接口的 message 继续同一 thread_id。
上传接口必须先于本接口调用；流式接口只传上传成功后的虚拟路径。

2.3 获取候选智能体和执行推荐

GET /api/agents

前端从返回列表中排除内置工具型智能体，将可参会的候选人整理成：

{
  "agent_id": "agent-001",
  "name": "态势研判专家",
  "description": "负责态势信息研判"
}

POST /api/recommend/stream
Accept: text/event-stream

{
  "intent": {
    "objective": "形成处置建议",
    "constraints": ["时限 24 小时"],
    "assumptions": ["数据可访问"]
  },
  "candidates": [
    {
      "agent_id": "agent-001",
      "name": "态势研判专家",
      "description": "负责态势信息研判"
    }
  ],
  "model": "页面当前模型"
}

推荐完成帧可得到：

{
  "status": "done",
  "content": "推荐过程说明",
  "picks": [
    {
      "agent_id": "agent-001",
      "reason": "与任务目标的匹配理由"
    }
  ]
}

普通会商会额外保存推荐记录，便于恢复和审计：

接口	参数
`GET /api/roundtable-drafts/{draftId}/recommendations`	无请求体，读取该草稿的推荐历史。
`POST /api/roundtable-drafts/{draftId}/recommendations`	`{ objective, status, model?, rationale?, picks, candidates }`。

2.4 读取、选择和管理业务链

接口	调用方式与参数
`GET /api/roundtable-chains?scope=public\|mine\|pending\|all`	获取业务链列表；入口页通常读取公开链。
`GET /api/roundtable-chains/{id}`	获取某条业务链完整定义。
`POST /api/roundtable-chains`	新建业务链。
`PUT /api/roundtable-chains/{id}`	更新业务链。
`DELETE /api/roundtable-chains/{id}`	删除业务链。
`POST /api/roundtable-chains/optimize-prompt`	使用模型优化总控提示词或阶段目标。

读取与弹窗行为：

“选择参会智能体”弹窗调用 GET /api/roundtable-chains（我的）或 GET /api/roundtable-chains?scope=public（公共），并同时调用 GET /api/agents 校验每个席位是否仍存在。
顶部管理弹窗在管理员身份下还可调用 scope=all；scope=pending 用于待审核链的管理场景。非管理员请求 all/pending 时后端会退化为当前用户范围。
启用状态为 false 的链条仍可在管理弹窗查看，但不会出现在“选择参会智能体”弹窗中。

创建或更新业务链的核心参数示例：

{
  "title": "任务综合研判链",
  "description": "先收集信息，再由专家研讨",
  "seats": [
    {
      "agent_id": "agent-001",
      "name": "态势专家",
      "description": "分析外部态势",
      "model": "模型标识",
      "seat_skill_directive": true,
      "human_validation": true,
      "seat_mode": "flash"
    }
  ],
  "stages": [["agent-001", "agent-002"], ["agent-003"]],
  "stage_goals": ["平行收集信息", "汇总形成判断"],
  "coordinator_prompt": "协调人需要按风险、机会、建议汇总",
  "seat_mode": "flash",
  "gather_first": true
}

其中：

链条创建时前端使用驼峰字段 stageGoals、coordinatorPrompt、seatMode、gatherFirst；请求发送前映射为接口字段 stage_goals、coordinator_prompt、seat_mode、gather_first。更新时传 null 可清除分层、阶段目标、总控提示词或默认执行模式。
stages 表示 DAG 分层：同层可并行，不同层按顺序执行。
seat_mode / 席位 seat_mode 可取 flash、thinking、pro、ultra。
model 为空时，该席位跟随第二步页面的全局模型；有值时仅覆盖该席位。
seat_skill_directive: true 会在该席位运行时强化其技能识别和使用指令；它与智能体自身同名开关任一开启即可生效。
human_validation: true 表示该席位输出后需要人工确认才可继续。
gather_first: true 表示先让全部席位平行收集信息，再进入正式研讨。

发布、审核和启停均通过更新接口发送局部字段：

操作	PUT /api/roundtable-chains/{id} 请求体
启用 / 停用	{ "enabled": true } / { "enabled": false }
直接发布 / 取消发布	{ "is_public": true } / { "is_public": false }
提交审核 / 撤回审核	{ "pending_review": true } / { "pending_review": false }
管理员审核发布	{ "is_public": true, "pending_review": false }

提示词优化接口的请求示例：

{
  "prompt_text": "当前总控提示词或阶段目标原文",
  "kind": "coordinator | stage_goal",
  "context": "链条标题、各阶段席位及已有阶段目标组成的上下文",
  "model_name": "可选模型标识"
}

{
  "optimized": "可直接回填到总控提示词或阶段目标编辑框的文本"
}

3. 页面结构

┌──────────────────────────────── 页面顶部 ────────────────────────────────┐
│ 三步导航：①任务意图理解  ②多智能体研讨  ③方案结果展示                   │
│ 业务链 / 新建或重新分析 / 保存草稿 / 历史记录 / 模型选择 / 设置          │
└───────────────────────────────────────────────────────────────────────┘
┌──────────── 左侧入口栏 ───────────┬──────────── 中间工作区 ────────────┬──── 右侧摘要栏 ────┐
│ 任务卡（仅任务深链）              │ Step1 对话面板                     │ 当前模型选择       │
│ 业务链列表与展开关系              │ - 意图智能体消息                   │ 结构化意图摘要     │
│ 会商/分析历史记录                 │ - 思考、工具、澄清卡               │ - 目标             │
│                                    │ - 输入框、附件、发送/停止/继续     │ - 约束             │
│                                    │                                    │ - 假设，均可编辑   │
└───────────────────────────────────┴────────────────────────────────────┴────────────────────┘

任务深链还会显示任务目的入口和底部 TaskJumpBar 快捷跳转栏；任务模式隐藏手工选择业务链的入口，以深链业务编码自动选择链条。

第二步：多智能体研讨

1. 功能

第二步以第一步意图和选定智能体/业务链为输入，创建协调人与多个席位智能体，进行可观察、可干预、可恢复的会商。

为每位参会智能体和协调人创建独立线程。
支持三种编排模式：
- 推荐模式（recommend）：协调人自由决定调度哪些推荐智能体。
- 链条模式（chain）：按业务链指定的席位顺序执行。
- DAG 模式（dag）：同阶段并行、跨阶段串行；可传入阶段目标和协调人提示词。
DAG 支持 fast 与 sandbox 执行视图。快速模式会限制并行席位写文件；沙箱模式可产出和预览文件。
可选“先收集后研讨”：全部席位先并行收集资料，再将有效交付共享给正式研讨。
协调人可继续派发、发起人工澄清，或在不再派发时形成共识。
用户可暂停/继续本地编排，回答协调人的澄清问题，向协调人追加文字或附件。
席位可配置人工验证点；达到验证点后需人工确认。
支持打开角色画像抽屉，在下一次运行前调整单席位模型和运行策略。
实时展示角色状态、对话、思考、工具调用、阶段流图、并行席位、文件产物和人工参与记录。
每次重新推荐或选择链条都会创建独立“研讨运行快照”；历史运行互不覆盖，可在左侧切换查看。
支持将长时间会商转入后台任务。后台任务可被同一任务的其他用户看到、跟踪、继续回答或接管。

步骤门槛：

只有第一步的 intentReady 为真时，第二步可进入。
协调人形成共识（hasConsensus）后，第三步才可进入。

2. 接口、调用时机与传参

2.1 初始化所有参会线程

POST /api/multi-agent/init
Accept: text/event-stream

{
  "agent_names": ["agent-001", "agent-002"],
  "main_agent_name": "coordinator",
  "model": "页面当前模型，可选"
}

说明：

agent_names 为选中的席位智能体标识。
main_agent_name 为协调人标识。
SSE 依次返回席位就绪、协调人就绪和初始化完成事件，最终得到线程映射：

{
  "thread_ids": {
    "agent-001": "席位线程 ID",
    "agent-002": "席位线程 ID",
    "coordinator": "协调人线程 ID"
  }
}

2.2 驱动协调人和席位研讨

POST /api/multi-agent/run/stream
Accept: text/event-stream

基础请求：

{
  "agent_type": "leader | special",
  "agent_name": "coordinator 或席位 agent ID",
  "display_name": "页面展示名称",
  "d_agent_thread_id": {
    "coordinator": "协调人线程 ID",
    "agent-001": "席位线程 ID"
  },
  "new_message": "给协调人或席位的本轮提示词",
  "model": "模型标识",
  "business_code": "3Q | 6BF | 7BF",
  "files": []
}

关键参数：

参数	适用对象	用途
`agent_type: "leader"`	协调人	由协调人分析现状、派发席位或形成共识。
`agent_type: "special"`	席位、总结/报告等专用智能体	执行专业分析、总结或文件生成。
`d_agent_thread_id`	全部	是“智能体 ID → 线程 ID”的映射，不是单一线程 ID。
`thinking_enabled?`	席位	是否启用思考。
`reasoning_effort?`	席位	推理强度。
`subagent_enabled?`	席位	是否允许席位再调用子智能体。
`seat_skill_directive?`	席位	席位特定的技能使用指令。
`parallel_no_file?`	并行席位	快速并行时限制文件写入。
`peer_deliveries?`	后续席位/协调人	传递前序席位可见交付物。
`synthesis_mode?`	协调人	指示汇总类执行。
`suppress_pre_broadcast?`	协调人	控制汇总前广播。
`skill_stop_names?`	全部	指定需要拦截/停止的技能名称。

流式完成后前端重点读取：

{
  "dispatched": ["agent-001"],
  "content": "可见回答或结论",
  "agentName": "本次完成者",
  "modelUsed": "实际使用模型",
  "clarification": {
    "question": "需要用户回答的问题",
    "options": ["选项 A"]
  },
  "invalidDelivery": false
}

编排规则：

协调人先运行并决定需调度的席位。
每个席位完成后，将其“可见回答”作为交付物回传，思考内容不作为席位交付。
链条模式按链定义的顺序运行；DAG 模式同层并行、阶段间串行。
协调人返回不再派发且无待答澄清时，前端将结果标记为共识。

2.3 产物查看与下载

接口	调用方式
`GET /api/threads/{threadId}/artifacts`	查询指定协调人或席位线程的文件产物。
`GET /api/threads/{threadId}/artifacts/{path}`	预览或下载文件；下载时前端附加 `?download=true`。

2.4 后台会商任务

开始后台任务：

POST /api/roundtable-jobs
Content-Type: application/json

{
  "requestId": "前端请求 ID",
  "draftId": "会商草稿 ID",
  "taskId": "任务深链时的任务 ID",
  "intent": {
    "objective": "任务目标",
    "constraints": ["约束"],
    "assumptions": ["假设"]
  },
  "agents": [
    {
      "agentId": "agent-001",
      "name": "态势专家"
    }
  ],
  "model": "当前模型",
  "orchestrationMode": "recommend | chain | dag",
  "chain": {
    "id": "chain-id",
    "title": "业务链名称"
  },
  "orchestrationPlan": {},
  "seedMessage": "首次给协调人的提示",
  "threadIds": {
    "coordinator": "线程 ID",
    "agent-001": "线程 ID"
  },
  "coordinatorName": "协调人名称",
  "seat_skill_directives": {
    "agent-001": true
  },
  "seat_modes": {
    "agent-001": "thinking"
  },
  "gather_first": true,
  "business_code": "3Q",
  "thinking_enabled": true,
  "reasoning_effort": "medium",
  "subagent_enabled": false
}

后台任务接口：

接口	调用方式与参数
`GET /api/roundtable-jobs?draft_id={draftId}&task_id={taskId}`	获取草稿/任务关联的后台任务列表。任务模式需带 `task_id`。
`GET /api/roundtable-jobs/{jobId}?task_id={taskId}`	获取任务快照。
`GET /api/roundtable-jobs/{jobId}/stream?task_id={taskId}`	SSE 跟踪后台任务完整进度。
`POST /api/roundtable-jobs/{jobId}/resume?task_id={taskId}`	JSON：`{ answer }`，用于回答后台任务等待的人工问题。
`POST /api/roundtable-jobs/{jobId}/cancel?task_id={taskId}`	取消后台任务；前台接管时也会先结束后台执行。

状态和阶段：

分类	枚举
任务状态	`queued`、`running`、`awaiting_input`、`done`、`error`、`cancelled`
执行阶段	`initializing`、`leader_thinking`、`dispatching`、`consensus`、`summary_writing`、`report_drawing`、`report_done`

3. 页面结构

┌──────────────────────────────── 页面顶部 ────────────────────────────────┐
│ 三步导航 / 会商记录 / 模型选择                                             │
└───────────────────────────────────────────────────────────────────────┘
┌──────────── 可收起左栏 ───────────┬──────────── 中间研讨区 ─────────────┬──── 右侧沙箱区 ────┐
│ 意图摘要                           │ 顶部：模型、暂停/继续、转后台       │ Step2SandboxLayout │
│ 角色列表与席位筛选                 │ DAG 流程缩略图、并行席位切换        │ 文件/网页预览      │
│ 人工参与/验证状态                  │ 对话时间线：协调人、席位、工具、思考 │ 产物查看和下载     │
│ 多次研讨运行快照切换               │ 澄清问题卡、人工确认卡              │ 打开时左栏自动收起 │
│ 任务概览（任务深链）               │ 底部：追加消息、附件、发送          │                    │
└───────────────────────────────────┴─────────────────────────────────────┴────────────────────┘

页面展示规则：

角色卡显示席位状态、当前轮次、模型和是否等待人工确认。
对话区可按角色筛选，思考内容默认折叠，工具调用和交付物以步骤卡展示。
DAG 研讨可打开流程面板观察阶段、依赖和并行关系。
打开沙箱/产物预览后，优先保证产物可读区域，左侧栏自动收起。

第三步：方案结果展示

1. 功能

第三步基于第一步意图、第二步席位交付和协调人共识，生成可阅读、可修改、可下载、可继续加工的最终方案。

首次进入常规会商第三步时，启动三个相互独立的产出流：
- 方案总结报告：生成 Markdown 方案，是默认主界面。
- 经典可视化报告：生成 HTML 风格报告/仪表盘。
- 结构化仪表盘：生成 report-json，由前端 DashboardApp 渲染。
三条流以约 0 / 300 / 600 ms 错峰启动，减少瞬间请求峰值，但互不等待。
已保存草稿再次打开时优先恢复既有结果，不重复生成；切换到新会商运行时会终止旧运行的活跃流。
Markdown 报告完成后，常规模式自动调用流程图提取，生成 flow-json 结构化流程图。
用户可对报告提问、要求重写、修改流程图、重新生成流程图或报告。
任务深链可根据业务链层次和业务编码生成任务 → 目的 → 行为体等结构；行动业务会使用行动名称作为根节点。
若任务和技能条件满足，可选择“现在导入 / 稍后导入 / 不再导入”，把报告和流程结构交给 roundtable-structure 进行任务结构化入库。
左侧汇集协调人共识、各席位交付和文件；右侧可预览 Markdown、流程图及沙箱产物。
支持下载会商文档和智能体产物。任务模式还可将选定产物提交到任务交付接口。

2. 接口、调用时机与传参

2.1 初始化第三步专用智能体

目标	接口	返回
Markdown 方案总结	`POST /api/multi-agent/summary/init`	`{ agent_name, thread_id }`
经典可视化报告	`POST /api/multi-agent/report/init`	`{ agent_name, thread_id }`
结构化仪表盘	`POST /api/multi-agent/dashboard/init`	`{ agent_name, thread_id }`
任务结构化入库	`POST /api/multi-agent/structure/init`	`{ agent_name, thread_id }`

初始化请求体均为：

{}

各专用智能体初始化后，均继续通过统一接口 POST /api/multi-agent/run/stream 运行。

2.2 生成或修改 Markdown 方案总结

{
  "agent_type": "special",
  "agent_name": "roundtable-summary",
  "display_name": "方案总结报告",
  "d_agent_thread_id": {
    "roundtable-summary": "总结线程 ID"
  },
  "new_message": "包含结构化意图、席位交付、协调人共识、链条提示词的生成或修改指令",
  "model": "当前模型",
  "business_code": "3Q",
  "files": []
}

功能覆盖：

首次生成 Markdown 报告。
在报告下方继续问答或下达修改指令。
支持暂停、继续、重新生成和生成后下载 Docx。
上述问答与修改沿用同一总结线程，保证上下文连续。

2.3 生成经典报告和仪表盘

经典报告请求使用 roundtable-report：

{
  "agent_type": "special",
  "agent_name": "roundtable-report",
  "d_agent_thread_id": {
    "roundtable-report": "报告线程 ID"
  },
  "new_message": "包含意图、席位交付、共识、主题模式、修订要求和已有 HTML 的提示词",
  "model": "当前模型"
}

结构化仪表盘请求使用 roundtable-dashboard：

{
  "agent_type": "special",
  "agent_name": "roundtable-dashboard",
  "d_agent_thread_id": {
    "roundtable-dashboard": "仪表盘线程 ID"
  },
  "new_message": "包含意图、席位交付、共识，或对已有仪表盘的修订要求",
  "model": "当前模型"
}

前端依据返回的 HTML 或 report-json 分别渲染经典报告和 DashboardApp，并提供全屏、在新窗口打开、继续优化以及切回经典报告的操作。

2.4 自动提取和修改流程图

POST /api/flow-extract/stream
Accept: text/event-stream

{
  "report_md": "Markdown 完整报告",
  "seat_deliveries": [
    {
      "sender": "态势专家",
      "content": "席位可见交付"
    }
  ],
  "chain_levels": [["信息收集"], ["研判决策"]],
  "coordinator_prompt": "协调人对结构层次的要求",
  "business_code": "3Q",
  "root_label": "任务根节点名称",
  "model": "当前模型",
  "current_graph": {
    "nodes": [],
    "edges": []
  },
  "instruction": "用户对当前流程图的修改要求"
}

参数使用规则：

首次自动提取可不传 current_graph 和 instruction。
修改现有图时传当前图和用户要求。
任务模式的 chain_levels 由业务链阶段目标推导；若 coordinator_prompt 明确规定层次，则优先使用该要求。

流中包含提取增量、校验过程、模型切换和最终图数据，最终形成前端 FlowGraphPanel 使用的 flow-json。

2.5 判断用户在第三步的意图

接口	请求体	返回用途
`POST /api/flow-extract/intent`	`{ message, has_report, has_flow, can_ingest, model? }`	分类为 `regenerate_report`、`modify_flow`、`regenerate_flow`、`ingest`、`qa`、`unclear`，决定继续调用哪一条流。
`POST /api/flow-extract/ingest-intent`	`{ message, model? }`	在已提示导入或稍后导入时，判断 `start_ingest`、`add_data`、`other`、`unclear`。

2.6 任务结构化入库

先检查是否可入库：

POST /api/flow-extract/ingest-eligibility

{
  "task_id": "任务 ID",
  "business_code": "3Q",
  "chain_name": "业务链名称",
  "coordinator_prompt": "协调人提示词",
  "report_title": "报告标题",
  "model": "当前模型"
}

{
  "can_ingest": true,
  "skill": "命中的入库技能",
  "reason": "是否可入库的原因"
}

符合条件且用户确认后，初始化 roundtable-structure 线程，并调用统一研讨流：

{
  "agent_type": "special",
  "agent_name": "roundtable-structure",
  "d_agent_thread_id": {
    "roundtable-structure": "结构化入库线程 ID"
  },
  "new_message": "包含 taskId、业务编码/链条/技能提示、最新 Markdown 报告、flow-json 和用户补充说明的指令",
  "model": "当前模型",
  "business_code": "3Q"
}

注意：前端不会直接调用某个入库技能，而是交给 roundtable-structure 智能体在具备完整报告和流程图上下文后执行。

2.7 任务交付物提交

任务深链启用交付配置时，第三步可以查询和更新任务产物提交状态。

接口	调用方式与参数
`GET /api/roundtable/tasks/{taskId}/artifacts?submitted=true\|false`	获取任务已提交或待提交产物。
`PUT /api/roundtable/tasks/{taskId}/artifacts/submission`	更新某个产物的提交状态。

{
  "taskId": "任务 ID",
  "submitted": true,
  "registerOnly": false,
  "submissionId": "已有提交记录 ID，可选",
  "taskDeliveryId": "外部交付 ID，可选",
  "expectedVersion": 3,
  "artifact": {
    "sessionId": "会商会话 ID",
    "threadId": "产物所属线程 ID",
    "nodeKey": "流程节点标识，可选",
    "sourceKey": "来源标识",
    "path": "/mnt/user-data/outputs/report.md",
    "name": "会商报告.md",
    "mimeType": "text/markdown",
    "revision": 1
  }
}

3. 页面结构

默认的“方案总结”视图：

┌──────────────────────────────── 页面顶部 ────────────────────────────────┐
│ 步骤导航 / 报告标题 / 模型 / 总结报告、流程图、最终方案等视图切换         │
└───────────────────────────────────────────────────────────────────────┘
┌──────────── 可收起左栏 ───────────┬──────────── 中间主内容 ─────────────┬──── 右侧结果区 ────┐
│ 协调人共识                         │ Markdown 总结报告对话流             │ Markdown 预览      │
│ 各席位交付                         │ 报告问答、修改、重生成入口           │ 或 FlowGraphPanel  │
│ 各线程文件/产物                    │ 输入框与附件                         │ 文件/沙箱预览      │
│                                    │                                     │                    │
└───────────────────────────────────┴─────────────────────────────────────┴────────────────────┘

其他结果视图：

视图	中央区域	右侧/扩展区域
最终方案	汇总后的静态方案和文件清单	可查看来源与下载产物。
经典可视化报告	报告生成对话、修订指令	HTML/沙箱预览，支持全屏和下载。
结构化仪表盘	仪表盘优化对话	`DashboardApp` 或 HTML 视图，可新窗口打开。
流程图	报告问答和流程图修改指令	`FlowGraphPanel` 显示节点、关系和层级。

常规第三步会隐藏外层研讨左导航，以扩大结果阅读区域；任务深链保留任务环境相关的交付与跳转能力。

4. 三步数据衔接

第一步
结构化意图 + 已选智能体/业务链 + 意图线程
        │
        ▼
第二步
席位线程 + 协调人线程 + 对话/交付 + 共识 + 研讨运行快照
        │
        ▼
第三步
Markdown 报告 + HTML 报告 + report-json 仪表盘 + flow-json 流程图 + 任务入库/交付

关键约束：

第一步未形成有效意图，不能开始第二步。
第二步未形成协调人共识，不能进入第三步。
第三步的所有产出都应绑定对应的第二步研讨运行快照，避免新一轮会商覆盖历史结果。
后端发生模型降级/切换时，前端应保留已收到的流内容并显示实际使用模型或切换提示。

5. 主要前端模块索引

范围	主要文件/目录
页面编排	`src/roundtable-planning/pages/RoundtablePlanningPage.tsx`
第一步	`components/Step1Panel.tsx`、`hooks/useStep1Intent.ts`、`api/intent.ts`
推荐与业务链	`api/recommend.ts`、`components/RecommendAgentsDialog.tsx`、`api/chains.ts`
第二步	`components/Step2Panel.tsx`、`components/Step2SandboxLayout.tsx`、`hooks/useStep2Orchestration.ts`
多智能体与后台任务 API	`api/multi-agent.ts`、`api/roundtable-jobs.ts`
第三步	`components/Step3Panel.tsx`、`components/HighFidelityReport.tsx`、`hooks/useStep3Summary.ts`、`hooks/useStep3Report.ts`、`hooks/useStep3Dashboard.ts`
流程图与任务入库	`api/flow-extract.ts`、`api/ingest.ts`
草稿持久化	`api/drafts.ts`、`api/task-drafts.ts`、相关草稿 hooks

41 KiB Raw Blame History Unescape Escape

多智能体会商功能与接口梳理

1. 文档范围与入口

2. 公共机制

2.1 会商记录与保存

2.2 流式调用与附件

第一步：任务意图理解

1. 功能

1.1 业务链功能与两个弹窗

A. 选择参会智能体弹窗中的“业务链条”页签

B. 顶部“业务链条”管理弹窗

2. 接口、调用时机与传参

2.1 初始化意图会话

2.2 发送任务或回答澄清问题

2.3 获取候选智能体和执行推荐

2.4 读取、选择和管理业务链

3. 页面结构

第二步：多智能体研讨

1. 功能

2. 接口、调用时机与传参

2.1 初始化所有参会线程

2.2 驱动协调人和席位研讨

2.3 产物查看与下载

2.4 后台会商任务

3. 页面结构

第三步：方案结果展示

1. 功能

2. 接口、调用时机与传参

2.1 初始化第三步专用智能体

2.2 生成或修改 Markdown 方案总结

2.3 生成经典报告和仪表盘

2.4 自动提取和修改流程图

2.5 判断用户在第三步的意图

2.6 任务结构化入库

2.7 任务交付物提交

3. 页面结构

4. 三步数据衔接

5. 主要前端模块索引

41 KiB

Raw Blame History