wsk/deerflow-code
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
b638b541d0
deerflow-code/frontend-web/docs/position-roundtable-delivery-workflow-plan.md
gozeros b638b541d0 初始化
2026-09-07 18:24:55 +08:00

19 KiB
Raw Blame History

岗位会商交付闭环与内置智能体实现计划

页面：/page/strategy/qa/position-roundtable

目标：在现有岗位会商基础上补齐“产物交付、查看、驳回、方案总结、行动规划”的完整闭环，同时继续保持原多智能体会商页面不受影响。

实施核对（2026-07-21）

本计划已按“岗位会商独立路由、无总控、各席位直接问答”的边界完成第一轮闭环。实际流程调整为：

任务信息 → 情报分析岗识别并确认意图 → 启动校验并冻结业务链
→ 分阶段席位直接问答/交付 Markdown → 全部有效交付
→ 方案总结智能体（roundtable-summary）→ 行动规划智能体（position-action-planner）
→ 可随时返回交付产物驳回 → 后续阶段及内置产物级联失效 → 重做后重新收口
  • 情报意图、业务链选择、席位岗位归属和席位智能体配置均在启动前校验；启动后保存业务链快照。
  • 普通席位直接调用各自分配的智能体，并注入任务、意图及已完成上游席位的问答/产物；不经过总控智能体。
  • 普通席位必须在 outputs 中交付 Markdown 才会完成；情报分析岗以确认的结构化意图完成为准。
  • 节点、交付卡片、流程图和大图弹窗均展示 locked / ready / running / done / rejected / stale / error 状态，并可回看节点会话和产物。
  • 驳回要求标题和理由；当前节点转为 rejected，后续阶段按依赖转为 stale/locked，总结和行动规划同时失效，历史内容保留可查看。
  • 被驳回或失效的普通席位必须写入一份新的或已改写 Markdown 才能再次完成；单纯继续问答且没有新交付不会误使下游产物失效。
  • 方案总结复用 roundtable-summary 的真实流式线程；行动规划新增 position-action-planner，强制输出 Markdown 报告和 action-plan-subtasks.json。
  • 两个内置智能体的线程、产物快照和来源节点版本栅栏均持久化；流式期间若上游版本变化，旧运行不能覆盖最新状态。
  • 右侧“交付产物”可查看内置节点结果、继续同一线程问答/修改交付，并在打开 Markdown 沙箱时自动收起右栏。

设计收敛：当前版本以节点的 artifact_manifest、latest_answer、版本、驳回记录及 Session 内置快照作为唯一事实来源，已能覆盖统一产物卡片和级联逻辑，因此不新增重复的 position_roundtable_deliverables 表。若后续需要“单个文件独立驳回、跨会话检索或完整版本对比”，再将清单归一化为独立产物表，避免现在的双写一致性风险。

数据持久化与灾难恢复（2026-07-23）

岗位会商现在使用“两层持久化”，两层职责不同：

  1. LangGraph checkpoint/thread 是智能体继续推理与流式问答的执行源。
  2. position_roundtable_sessions / position_roundtable_nodes 是页面历史的数据库恢复源。

数据库恢复源会保存：

  • 情报分析岗完整消息、步骤时间线和未发送输入草稿；
  • 每个业务链岗位的完整消息和未发送输入草稿；
  • 方案总结、行动规划两个收口智能体的完整消息和未发送输入草稿；
  • 已确认意图、冻结任务与业务链快照、节点状态、版本、驳回记录；
  • Markdown / JSON 等文本产物正文（单文件最多 400 万字符）和文件元数据。

因此即使线上重启后 checkpoint 或沙箱 outputs 卷丢失，历史页仍能从数据库展示对话与产物正文，后续收口智能体也能继续读取数据库中的有效上游交付。新任务在意图识别开始前就会创建 Session，用户不必等到“启动业务链”才获得持久化保护。历史下拉支持删除，删除会显式清理 Session 与全部节点恢复快照，不依赖 SQLite 外键开关。

对应迁移：20260723_05_position_roundtable_conversations.py。部署时必须执行到 Alembic head。

0. 核心结论

  • 方案总结智能体建议复用现有会商里的 roundtable-summary 能力，但不要直接搬整套 Step 3 页面流程。
    • 可复用：内置智能体 ID、总结报告 prompt 组织方式、Markdown 报告产物、流式对话、报告续问与文件预览能力。
    • 需要改造：输入材料从“总控共识 + 各席位交付”改成“任务信息 + 意图结果 + 已通过的岗位产物 + 业务链快照”，并把结果存到岗位会商 Session 下。
  • 行动规划智能体建议作为新的内置智能体新增。
    • 输入：方案总结报告、各岗位最终有效产物、业务链阶段信息、任务意图。
    • 输出：行动规划报告、结构化子任务清单。
  • 这个模式仍然不需要总控智能体。情报分析岗负责意图识别，业务链节点直接调用各自配置的智能体，最终再由内置总结/规划智能体收口。
  • 驳回不删除历史内容，只改变“当前有效版本”的状态；被驳回节点和后续节点需要重新交付，既保留可追溯性，也方便后续返回查看。

1. 目标业务流程

  1. 情报分析岗进入页面，查看任务信息并完成意图识别。
  2. 用户点击“确认意图并启动业务链”。
  3. 启动前做校验：
    • 未选择业务链：提示“请先选择业务链”。
    • 业务链存在未配置岗位的席位：提示并引导去业务链配置页。
    • 业务链席位缺少智能体：提示具体席位名称。
    • 意图尚未完成：提示先完成任务意图识别。
  4. 校验通过后冻结业务链快照，初始化岗位会商节点。
  5. 各岗位只对分配给本岗位的智能体进行问答。
  6. 节点问答完成后形成交付产物，右侧产物卡片显示“已完成 / 未完成 / 进行中 / 已驳回 / 已失效”。
  7. 左侧流程图显示各节点状态，节点可点击查看该节点对话与产物。
  8. 流程图右上角提供“查看”按钮，打开弹窗展示更完整的业务链流程图。
  9. 当业务链中所有岗位产物都处于有效已交付状态后，开放“方案总结”。
  10. 方案总结完成后开放“行动规划”。
  11. 即使进入方案总结或行动规划，用户仍可返回产物列表执行驳回。
  12. 若驳回早期阶段产物，后续阶段产物、方案总结、行动规划都一起失效并回到待重新完成状态。

2. 状态设计

2.1 节点状态

现有节点状态需要扩展或映射为更贴近页面的展示状态：

展示状态 建议内部状态 含义
未完成 ready / locked / rejected 尚未有效交付，或被驳回后等待重做
进行中 running 当前智能体正在回答或产物正在生成
已完成 done 当前节点已有有效交付
已失效 stale 上游被更新或驳回，当前结果不可作为最终材料
异常 error 生成或保存失败

建议新增 rejected 状态，便于区分“从未完成”和“被驳回后待重做”。如果第一轮想少改后端，也可以先用 ready + rejection_record 表示被驳回。

2.2 产物状态

产物状态建议独立于节点状态保存，因为一个节点可能同时有回答文本和多个文件产物。

状态 含义
pending 还没有交付
running 正在生成
delivered 已交付且当前有效
rejected 被用户驳回
stale 受上游驳回或重做影响，已经失效

2.3 内置收口节点

在流程图中把两个内置节点追加到业务链末尾：

  1. builtin:summary：方案总结智能体。
  2. builtin:action-plan：行动规划智能体。

这两个节点不属于普通业务链席位，但要和普通节点一样显示状态、支持点击查看结果。

3. 数据模型调整

3.1 Session 扩展

position_roundtable_sessions 已使用下列持久化字段：

字段 含义
status intent_pending / active / completed / archived；总结/规划运行态由前端瞬时状态与对应快照的 status 表示，避免一次运行中断后留下伪运行态
summary_thread_id 方案总结智能体线程
summary_snapshot 最新有效总结报告快照
action_plan_thread_id 行动规划智能体线程
action_plan_snapshot 最新有效行动规划快照
invalidated_at 记录在 summary_snapshot / action_plan_snapshot 内，包含 invalidated_by，无需重复写 Session 字段

3.2 Node 扩展

position_roundtable_nodes 已使用下列字段（展示状态由前端按状态映射）：

字段 含义
status locked / ready / running / done / stale / rejected / error，前端直接映射为展示状态
rejection_count 当前节点累计驳回次数
last_rejection 最新驳回标题、理由、操作者、时间
revision 当前有效交付版本
invalidated_by 导致当前节点失效的上游节点 key

3.3 Deliverable 新表（后续可选）

当需要“单个文件独立驳回、跨会话检索或完整版本对比”时，再新增 position_roundtable_deliverables，不要只依赖 artifact_manifest。

字段 含义
id 产物 ID
session_id 会话 ID
node_key 来源节点
agent_id 来源智能体
position_id 来源岗位
title 产物名称
kind answer / file / summary / action_plan
content 文本产物内容摘要或正文
artifact_path 文件产物虚拟路径
thread_id 所属线程
status pending / running / delivered / rejected / stale
revision 来源节点版本
rejection_title 驳回标题
rejection_reason 驳回理由
created_at 创建时间
updated_at 更新时间

当前第一轮不新增这张表：右侧产物卡片、驳回记录、总结输入材料从节点 artifact_manifest、节点版本/驳回记录和 Session 快照聚合，避免节点表与产物表双写。后续引入该表时，应把它提升为唯一事实来源，而不是并行维护两套状态。

4. 驳回与级联失效规则

4.1 基本驳回

用户点击产物卡片的“驳回”后弹窗填写：

  • 驳回标题。
  • 驳回理由。

提交后：

  • 当前产物状态改为 rejected。
  • 当前节点状态改为 rejected 或 ready。
  • 当前节点的 latest_answer 和历史文件不删除，但不再作为有效交付输入。
  • 记录 last_rejection，用于页面展示和后续追踪。

4.2 级联失效

如果驳回的节点位于第 N 阶段：

  • 同阶段其他节点不自动驳回，除非业务链未来明确配置了依赖关系。
  • 第 N+1 阶段及之后所有节点的有效产物全部标记为 stale。
  • 后续节点状态回到未完成展示态。
  • builtin:summary 和 builtin:action-plan 如果已经生成，也标记为 stale。
  • 页面允许用户继续查看旧报告和旧行动规划，但必须提示“上游产物已变更，需要重新生成”。

4.3 重新交付

被驳回节点重新问答并完成后：

  • 当前节点产生新的 revision。
  • 当前节点产物状态变为 delivered。
  • 只有当该阶段所有必要节点都重新有效交付后，下一阶段才重新解锁。
  • 方案总结和行动规划必须基于最新有效产物重新生成。

5. 接口规划

5.1 启动与校验

方法 路径 用途
POST /api/position-roundtable/sessions/{id}/validate-activation 校验业务链、岗位、智能体、意图状态
POST /api/position-roundtable/sessions/{id}/activate 校验通过后冻结链条并初始化节点

第一轮也可以先把校验合并在 activate 内，前端根据后端返回的错误码提示。

5.2 产物

方法 路径 用途
GET /api/position-roundtable/sessions/{id}/results 获取右侧统一产物来源节点（前端聚合文件与内置快照）
GET /api/position-roundtable/sessions/{id}/nodes/{node_key} 获取节点详情；文件正文由既有线程产物预览接口读取
POST /api/position-roundtable/sessions/{id}/nodes/{node_key}/reject 驳回当前节点交付并触发级联失效
POST /api/position-roundtable/sessions/{id}/nodes/{node_key}/complete-turn 节点回答结束后同步回答与产物

5.3 方案总结与行动规划

方法 路径 用途
POST /api/position-roundtable/sessions/{id}/summary/prepare 服务端准备版本锁定的总结材料和线程信息
POST /api/position-roundtable/sessions/{id}/summary/ask 服务端准备总结的同线程续问材料
POST /api/position-roundtable/sessions/{id}/summary/complete 校验 Markdown 交付与来源版本后持久化总结快照
POST /api/position-roundtable/sessions/{id}/action-plan/prepare 服务端准备行动规划材料和线程信息
POST /api/position-roundtable/sessions/{id}/action-plan/ask 服务端准备行动规划同线程续问材料
POST /api/position-roundtable/sessions/{id}/action-plan/complete 校验 Markdown + JSON 交付与来源版本后持久化行动规划快照

可以复用现有 streamMultiAgent 流式协议，但建议在岗位会商下包一层 API，由后端负责拼装岗位会商材料，前端不直接拼长 prompt。

6. 前端实施步骤

阶段 1：状态与启动校验（已完成）

  • 扩展 PositionNodeStatus 和状态显示映射。
  • “确认意图并启动业务链”前补齐校验提示。
  • 后端 activate 返回未配置岗位、缺智能体、未选择链条等具体错误。
  • 左侧流程图节点右上角添加状态小图标。
  • 节点样式调整为上方智能体名称、下方岗位名称，移除左侧 logo。

验收标准：未选择业务链、岗位未配齐、意图未完成时都能准确阻止启动；启动后流程图能显示各节点状态。

阶段 2：流程图弹窗（已完成）

  • 左侧保留小型从上到下流程图。
  • 流程图右上角增加“查看”按钮。
  • 点击后打开弹窗，展示更大的流程图。
  • 弹窗内支持点击节点查看对话与产物，保持和主页面选中节点同步。

验收标准：小图不挤占左侧空间，大图能完整展示业务链和两个内置收口节点。

阶段 3：产物卡片与预览（已完成）

  • 右侧新增或改造“分析结果”Tab 为“交付产物”列表。
  • 卡片展示智能体名称、产物名称、岗位名称、时间、状态。
  • 点击卡片打开详情弹窗。
  • 文本产物直接展示正文，文件产物复用现有 ArtifactPreviewModal。
  • 每个有效产物提供“驳回”入口。

验收标准：节点回答和文件产物能进入统一产物列表；点击可查看详情。

阶段 4：驳回弹窗与级联失效（已完成）

  • 新增 RejectDeliverableDialog。
  • 驳回表单包含标题和理由，均必填。
  • 后端事务内完成当前产物驳回、当前节点状态更新、后续阶段级联失效、总结和行动规划失效。
  • 前端刷新 Session、Node、Deliverable 和流程图状态。
  • 被驳回节点在对话区显示驳回信息，提示用户重新交付。

验收标准：驳回第一阶段任意节点后，第二阶段及之后产物都显示未完成或已失效；旧内容可查看但不能作为总结输入。

阶段 5：方案总结智能体（已完成）

  • 封装 usePositionSummary，内部复用 roundtable-summary 的线程初始化、流式输出和 Markdown 产物预览能力。
  • 输入材料改为岗位会商材料：
    • 任务信息。
    • 情报分析岗意图结果。
    • 业务链快照。
    • 所有状态为 delivered 的岗位产物。
    • 已驳回或失效产物只作为历史参考，不进入默认总结材料。
  • 方案总结节点追加到流程图末尾。
  • 所有产物有效交付后才允许点击“生成方案总结”。
  • 总结结果写入 summary_snapshot，同时进入产物列表。

验收标准：总结报告使用现有方案总结能力生成 Markdown；刷新页面后可恢复；上游驳回后总结标记失效。

阶段 6：行动规划智能体（已完成）

  • 新增内置智能体 ID，建议先命名为 position-action-planner。
  • 新增行动规划 prompt：
    • 读取方案总结报告。
    • 读取各岗位最终有效产物。
    • 拆解为若干子任务。
    • 每个子任务包含名称、目标、输入依据、责任岗位建议、前置依赖、交付物、验收标准。
  • 输出两类产物：
    • 行动规划报告.md。
    • action-plan-subtasks.json。
  • 行动规划节点追加到方案总结之后。
  • 方案总结有效完成后才允许启动行动规划。

验收标准：行动规划能生成可读报告和结构化子任务；刷新可恢复；上游驳回后自动失效。

阶段 7：返回修改与重新生成（已完成）

  • 用户在方案总结或行动规划视图中仍可切回“交付产物”。
  • 驳回后自动显示需要重做的节点。
  • 重做节点完成后，允许重新生成方案总结和行动规划。
  • 旧总结、旧行动规划保留历史查看，但状态显示“已失效”。

验收标准：不会因为进入总结/规划阶段而锁死前序产物；前序重做后能形成新版本闭环。

阶段 8：测试与回归（已完成）

  • 后端测试：
    • activate 校验。
    • 节点完成后产物入库。
    • 驳回当前节点。
    • 驳回第一阶段时后续阶段级联失效。
    • 总结和行动规划失效。
  • 前端测试：
    • 启动校验提示。
    • 状态图标显示。
    • 产物卡片筛选和预览。
    • 驳回弹窗必填校验。
  • 回归验证：
    • 原多智能体会商页面不受影响。
    • 业务链普通配置入口不显示岗位配置。
    • 岗位会商页面刷新恢复正常。
    • 深色模式和嵌入模式布局不溢出。

7. 推荐提交拆分

  1. feat(position-roundtable): add delivery status model
  2. feat(position-roundtable): validate chain activation
  3. feat(position-roundtable): add workflow status graph
  4. feat(position-roundtable): add deliverable cards and preview
  5. feat(position-roundtable): support rejection cascade
  6. feat(position-roundtable): add summary builtin node
  7. feat(position-roundtable): add action planning builtin node
  8. test(position-roundtable): cover delivery workflow

8. 第一轮建议范围

第一轮优先做最小可闭环：

意图识别
→ 启动校验
→ 业务链节点状态
→ 节点产物列表
→ 产物详情查看
→ 驳回与级联失效
→ 全部交付后生成方案总结
→ 基于总结生成行动规划

如果时间紧，行动规划可以先生成 Markdown 报告，结构化 subtasks.json 放到第二轮；但数据模型和 UI 入口第一轮就要预留，否则后面会返工。