docs(position-roundtable): plan delivery workflow

2026-07-21 19:31:08 +08:00
1 parent 783774d3f3
commit 97ce19973d
@@ -0,0 +1,318 @@
+# 岗位会商交付闭环与内置智能体实现计划
+
+> 页面：`/page/strategy/qa/position-roundtable`
+>
+> 目标：在现有岗位会商基础上补齐“产物交付、查看、驳回、方案总结、行动规划”的完整闭环，同时继续保持原多智能体会商页面不受影响。
+
+## 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` 建议增加：
+
+| 字段 | 含义 |
+| --- | --- |
+| `workflow_status` | `intent_pending / active / summarizing / planning / completed / archived` |
+| `summary_thread_id` | 方案总结智能体线程 |
+| `summary_snapshot` | 最新有效总结报告快照 |
+| `action_plan_thread_id` | 行动规划智能体线程 |
+| `action_plan_snapshot` | 最新有效行动规划快照 |
+| `invalidated_at` | 最近一次级联失效时间，可选 |
+
+### 3.2 Node 扩展
+
+`position_roundtable_nodes` 建议增加：
+
+| 字段 | 含义 |
+| --- | --- |
+| `display_status` | 面向前端的聚合状态，可后端计算也可前端映射 |
+| `rejection_count` | 当前节点累计驳回次数 |
+| `last_rejection` | 最新驳回标题、理由、操作者、时间 |
+| `valid_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` | 更新时间 |
+
+这样右侧产物卡片、驳回记录、总结输入材料都能从同一张表聚合。
+
+## 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}/deliverables` | 获取右侧产物列表 |
+| `GET` | `/api/position-roundtable/deliverables/{deliverable_id}` | 获取产物详情 |
+| `POST` | `/api/position-roundtable/deliverables/{deliverable_id}/reject` | 驳回产物并触发级联失效 |
+| `POST` | `/api/position-roundtable/nodes/{node_id}/complete-turn` | 节点回答结束后同步回答与产物 |
+
+### 5.3 方案总结与行动规划
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| `POST` | `/api/position-roundtable/sessions/{id}/summary/start` | 启动或重启方案总结 |
+| `POST` | `/api/position-roundtable/sessions/{id}/summary/ask` | 对方案总结继续提问或修改 |
+| `POST` | `/api/position-roundtable/sessions/{id}/action-plan/start` | 基于总结和产物生成行动规划 |
+| `POST` | `/api/position-roundtable/sessions/{id}/action-plan/ask` | 对行动规划继续提问或修改 |
+
+可以复用现有 `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. 第一轮建议范围
+
+第一轮优先做最小可闭环：
+
+```text
+意图识别
+→ 启动校验
+→ 业务链节点状态
+→ 节点产物列表
+→ 产物详情查看
+→ 驳回与级联失效
+→ 全部交付后生成方案总结
+→ 基于总结生成行动规划
+```
+
+如果时间紧，行动规划可以先生成 Markdown 报告，结构化 `subtasks.json` 放到第二轮；但数据模型和 UI 入口第一轮就要预留，否则后面会返工。
@@ -1,508 +0,0 @@
-# 岗位智能体协同页面 · 分步实现计划
-
-> 页面：`/page/strategy/qa/position-roundtable`
->
-> 核心模式：**不使用总控智能体**。情报分析岗先完成意图识别；其他岗位直接与业务链中分配给本岗位的智能体问答。每个节点独立保存对话和产物，并在问答时自动获得上游节点的有效结果。
-
---
-
-## 0. 已确认的产品决策
-
- 新功能使用独立路由、独立业务状态和独立后端存储，不修改原多智能体会商页面的运行逻辑。
- 岗位先使用前端固定枚举；下拉框、选择器等表单控件使用 `tdesign-react`。
- **情报分析岗**负责任务意图识别，复用现有 `useStep1Intent`、`Step1Panel` 和意图接口。
- 其他岗位不经过总控派活，直接使用节点配置的 `agent_id` 调用对应智能体。
- 不调用原会商的 `multi-agent/init`、总控循环、后台圆桌作业和自动收口流程。
- 每个业务链节点对应一条独立智能体对话线程；同一节点可以在该线程内多轮追问。
- 当前岗位只能向分配给本岗位的节点提问；其他节点允许查看，但输入框只读。
- 节点问答时自动获得任务、意图和已完成上游节点的问答结果与产物。
- 左侧流程图从上到下排列，节点可点击，画布支持鼠标拖动；连接线保留但不显示依赖文字。
- 右侧保留“智能体配置 / 分析结果”两个标签页。
-
-### 0.1 默认实现口径
-
-以下口径在产品未另行调整前作为实现默认值：
-
- 业务链上一阶段的所有节点至少产生一次有效回答后，下一阶段节点进入 `ready` 状态。
- 同一阶段的节点互不依赖，可以分别问答。
- 上游节点产生新回答或新产物后，已经执行过的下游节点标记为 `stale`，但不删除历史。
- “分析结果”同时收录智能体最终回答和文件产物；文件产物优先展示。
- 第一版岗位下拉只是页面工作视角，不代表真实用户权限；后续接入用户岗位关系后再启用服务端岗位授权。
- 一个外部任务允许创建多个岗位协同会话；页面默认打开最近更新的一条。
-
-### 0.2 待业务最终确认
-
- 固定岗位的正式编码和名称清单。
- 情报分析岗完成意图识别后，是否还允许承担业务链节点问答。
- 下游解锁采用“上游首次有效回答”还是增加人工“提交完成”动作。
- 新任务接口提供的字段、外部任务 ID 和页面进入方式。
- 岗位是否最终与登录用户绑定，以及一名用户是否允许属于多个岗位。
-
---
-
-## 1. 目标与非目标
-
-### 1.1 本期目标
-
- 为业务链席位增加岗位分配能力，且只在从岗位协同页面进入配置时显示。
- 为岗位协同任务提供可刷新、可恢复、可跨页面重新打开的持久化会话。
- 按“任务 → 意图 → 业务链阶段 → 节点智能体”组织对话和产物。
- 当前岗位仅展示和调用本岗位被分配的智能体。
- 点击流程图节点可查看该节点完整问答和产物。
- 下游智能体自动获得上游结果，不要求用户手工复制粘贴。
- 保持现有多智能体会商、任务深链、普通智能体聊天行为不变。
-
-### 1.2 本期非目标
-
- 不保留总控智能体，不做总控派活、共识判断或自动多轮研讨。
- 不把岗位协同记录写入 `roundtable_drafts` 或 `roundtable_jobs`。
- 不自动生成最终综合报告；后续可增加按需调用总结智能体的“生成汇总”功能。
- 第一版不实现复杂条件分支、人工改线或动态跳转，只遵循现有业务链阶段顺序。
- 第一版不实现完整组织权限系统；真实岗位授权作为独立阶段接入。
-
---
-
-## 2. 目标业务流程
-
-1. 页面根据外部任务参数创建或恢复一条岗位协同会话。
-2. 情报分析岗查看任务信息并选择业务链。
-3. 情报分析岗与意图识别智能体问答，确认结构化任务意图。
-4. 系统保存任务、意图和业务链快照，初始化所有业务链节点状态。
-5. 用户切换到其他岗位，只看到分配给当前岗位的可问答智能体。
-6. 用户点击流程图节点：
-   - 本岗位节点：加载或创建该节点的智能体线程，允许问答；
-   - 其他岗位节点：加载已有线程和产物，只读查看；
-   - 尚未解锁节点：展示依赖提示，不允许发送。
-7. 每次发送问题前，系统构建隐藏上下文并注入当前智能体。
-8. 智能体回答完成后保存节点最新回答、产物清单和版本号，并重新计算下游状态。
-9. 右侧“分析结果”按时间倒序聚合全部节点回答和产物。
-
---
-
-## 3. 总体技术方案
-
-### 3.1 复用范围
-
-| 能力 | 方案 |
-|------|------|
-| 意图识别 | 复用 `useStep1Intent`、`Step1Panel`、`/api/intent/*` |
-| 智能体问答 | 复用 `useThreadStream` 和现有 Agent Chat 消息/输入组件 |
-| 消息存储 | 复用 LangGraph thread/checkpoint，不新增消息表 |
-| 文件产物 | 复用 `/api/threads/{thread_id}/artifacts` |
-| 隐藏上下文 | 复用 `task_external_context` 和 `TaskExternalContextMiddleware` |
-| 智能体详情 | 复用 `AgentDetailPanel` |
-| 业务链 | 扩展现有 `roundtable_chains.seats` JSON |
-| 页面业务状态 | 新增岗位协同 Session/Node 存储 |
-
-### 3.2 明确不复用的圆桌能力
-
- `initMultiAgent`
- `useStep2Orchestration`
- `roundtable-coordinator`
- `roundtable_jobs`
- 圆桌共识百分比与最大循环轮次
- 自动 Step 3 收口和报告绘制
-
-### 3.3 目录建议
-
-```text
-frontend-web/src/position-roundtable/
-├── api/
-│   ├── sessions.ts
-│   └── handoff.ts
-├── components/
-│   ├── PositionTaskPanel.tsx
-│   ├── PositionChainFlow.tsx
-│   ├── PositionAgentChat.tsx
-│   ├── PositionAgentList.tsx
-│   └── PositionResults.tsx
-├── hooks/
-│   ├── usePositionSession.ts
-│   ├── usePositionNodeChat.ts
-│   └── usePositionHandoff.ts
-├── lib/
-│   ├── positions.ts
-│   ├── chain-nodes.ts
-│   └── types.ts
-└── pages/
-    └── PositionRoundtablePage.tsx
-```
-
-后端建议新增：
-
-```text
-offline-backend-20260512/backend/
-├── app/gateway/routers/position_roundtable.py
-└── packages/harness/deerflow/persistence/
-    ├── position_roundtable_sessions/
-    └── position_roundtable_nodes/
-```
-
---
-
-## 4. 数据模型
-
-### 4.1 业务链席位扩展
-
-在现有 `ChainSeat` 中增加：
-
-```ts
-interface ChainSeat {
-  agent_id: string;
-  name: string;
-  description?: string;
-  position_id?: string | null;
-}
-```
-
-后端 `ChainSeatSchema` 同步增加可选 `position_id`。席位本身存储在 JSON 中，因此无需新增数据库列，但必须确保：
-
- 创建、读取、更新接口都保留该字段；
- 普通编辑模式虽然不显示岗位控件，保存时也不能删除已有岗位字段；
- 老链条没有该字段时按“未配置岗位”处理；
- 原圆桌编排忽略该字段，行为保持不变。
-
-### 4.2 岗位协同会话表
-
-`position_roundtable_sessions` 建议字段：
-
-| 字段 | 含义 |
-|------|------|
-| `id` | 岗位协同会话 ID |
-| `external_task_id` | 新任务系统提供的任务 ID，可空 |
-| `task_snapshot` | 任务信息 JSON 快照 |
-| `chain_id` | 来源业务链 ID |
-| `chain_snapshot` | 启动时业务链完整快照 |
-| `intent_thread_id` | 意图识别线程 ID |
-| `intent_snapshot` | `useStep1Intent` 快照及结构化意图 |
-| `status` | `intent_pending / active / completed / archived` |
-| `created_by` | 创建人 |
-| `created_at` | 创建时间 |
-| `updated_at` | 更新时间 |
-
-### 4.3 岗位协同节点表
-
-`position_roundtable_nodes` 建议字段：
-
-| 字段 | 含义 |
-|------|------|
-| `id` | 节点记录 ID |
-| `session_id` | 所属岗位协同会话 |
-| `node_key` | 会话内稳定节点键 |
-| `stage_index` | 所属业务链阶段 |
-| `seat_index` | 阶段内顺序 |
-| `agent_id` | 对应智能体 |
-| `position_id` | 分配岗位 |
-| `thread_id` | 对应智能体聊天线程，可空 |
-| `status` | `locked / ready / running / done / stale / error` |
-| `latest_answer` | 最新有效回答快照 |
-| `artifact_manifest` | 当前产物清单 JSON |
-| `revision` | 本节点结果版本号 |
-| `upstream_revision` | 最近一次问答使用的上游版本摘要 |
-| `created_at` | 创建时间 |
-| `updated_at` | 更新时间 |
-
-唯一约束：`(session_id, node_key)`。
-
-### 4.4 Thread metadata
-
-节点线程创建后写入：
-
-```json
-{
-  "thread_type": "position_roundtable",
-  "position_session_id": "session-id",
-  "position_node_id": "node-id",
-  "position_id": "position-code",
-  "chain_id": "chain-id",
-  "agent_id": "agent-id"
-}
-```
-
-Thread 继续保存真实消息；节点表只保存业务索引、状态和便于列表展示的快照。
-
---
-
-## 5. API 规划
-
-建议前缀：`/api/position-roundtable`。
-
-### 5.1 会话接口
-
-| 方法 | 路径 | 用途 |
-|------|------|------|
-| `POST` | `/sessions` | 根据任务创建岗位协同会话 |
-| `GET` | `/sessions/{id}` | 加载会话、意图和全部节点状态 |
-| `GET` | `/sessions?external_task_id=` | 查询任务下的会话历史 |
-| `PUT` | `/sessions/{id}/task` | 更新尚未启动的任务快照 |
-| `PUT` | `/sessions/{id}/intent` | 保存意图线程和意图快照 |
-| `POST` | `/sessions/{id}/activate` | 冻结链条快照并初始化节点 |
-| `POST` | `/sessions/{id}/archive` | 归档会话，不删除线程和产物 |
-
-### 5.2 节点接口
-
-| 方法 | 路径 | 用途 |
-|------|------|------|
-| `GET` | `/sessions/{id}/nodes/{node_key}` | 获取节点、线程、状态和产物 |
-| `POST` | `/sessions/{id}/nodes/{node_key}/thread` | 幂等创建节点智能体线程 |
-| `POST` | `/sessions/{id}/nodes/{node_key}/context` | 构建本轮隐藏上游上下文 |
-| `POST` | `/sessions/{id}/nodes/{node_key}/complete-turn` | 回答结束后同步回答、产物和版本 |
-| `GET` | `/sessions/{id}/results` | 聚合全部岗位分析结果 |
-
-### 5.3 幂等与并发要求
-
- 节点线程接口必须幂等，同一节点并发请求只能创建一个有效 thread。
- `complete-turn` 使用节点 `revision` 做乐观锁，避免旧请求覆盖新结果。
- 会话激活后不允许直接替换链条；需要重新建会话或显式“基于新链条重建”。
- 删除业务链不能删除已有会话中的链条快照。
-
---
-
-## 6. 上游结果交接规则
-
-### 6.1 上游节点计算
-
- 线性链：当前节点之前的所有已完成节点均为上游。
- 分层链：只读取当前阶段之前的已完成阶段；同阶段节点不互相引用。
- 注入顺序按 `stage_index`、`seat_index` 排列，确保每次构建稳定。
-
-### 6.2 隐藏上下文结构
-
-每次发送问题前，通过 `task_external_context` 注入：
-
-```json
-{
-  "kind": "position_roundtable_handoff",
-  "task": {},
-  "intent": {},
-  "current_node": {},
-  "upstream_nodes": [
-    {
-      "agent_id": "...",
-      "position_id": "...",
-      "latest_answer": "...",
-      "artifacts": []
-    }
-  ],
-  "upstream_revision": "..."
-}
-```
-
-### 6.3 产物传递
-
- Markdown、TXT、JSON、CSV、YAML 等文本产物：读取正文并按总字符上限注入。
- PDF、Word、Excel、图片等非纯文本产物：复制到当前节点线程的只读上游资料目录，并在上下文中提供可读虚拟路径。
- 单文件和总上下文均设置大小限制；发生截断时在上下文中标记 `truncated=true`。
- 当前节点生成的文件仍写入自己的 `/mnt/user-data/outputs/`，不写回上游线程。
-
-### 6.4 上游更新传播
-
-1. 节点完成一次回答后 `revision + 1`。
-2. 系统重新计算所有下游节点的上游版本摘要。
-3. 已问答下游节点的摘要不一致时，将状态改为 `stale`。
-4. 用户再次向该节点提问后，使用最新上下文并把状态恢复为 `done`。
-
---
-
-## 7. 分阶段实施计划
-
-### 阶段 0：边界固定与基线测试
-
-目标：明确新旧功能边界，给后续改造建立回归保护。
-
- [x] 固定岗位枚举及意图岗位编码（当前为 `intelligence` / 情报分析岗）。
- [x] 固定新任务数据适配接口：当前使用可替换的模拟任务源，后续只需替换 `mock-task-source.ts`。
- [ ] 为原圆桌路由、岗位协同路由分别增加基本渲染测试。
- [ ] 记录原圆桌业务链创建、编辑、运行的基线行为。
- [ ] 确认岗位协同模块不导入 `useStep2Orchestration` 或 `initMultiAgent`。
-
-完成标准：原会商页面无行为变化；岗位协同页面仍可独立打开。
-
-### 阶段 1：业务链岗位配置
-
-目标：业务链节点能够持久化岗位，但普通业务链编辑体验不受影响。
-
- [x] `ChainSeat`、前端 API 映射增加 `position_id`。
- [x] 后端 `ChainSeatSchema` 增加 `position_id` 并补充长度校验。
- [x] 业务链编辑器识别 `mode=position`。
- [x] 岗位模式下为每个节点增加 TDesign 岗位选择器。
- [ ] 增加“未配置岗位”提示、岗位图例和保存校验。
- [x] 普通模式隐藏岗位控件，但完整保留原岗位字段。
- [x] 岗位协同页面增加“配置岗位”入口和返回参数。
- [ ] 增加老链条、普通保存、岗位保存的前后端测试。
-
-完成标准：从岗位页面进入时可以配置岗位；从原入口进入时看不到岗位控件；两种入口交替保存不丢字段。
-
-### 阶段 2：岗位协同持久化底座
-
-目标：任务、意图、链条快照和节点状态可以跨刷新恢复。
-
- [ ] 新增 Session/Node ORM、Repository 和数据库迁移。
- [ ] 新增会话创建、查询、更新意图、激活和归档接口。
- [ ] 激活时校验链条、岗位配置和意图结果。
- [ ] 激活时根据链条快照一次性生成全部 Node 记录。
- [ ] 新增前端 `sessions.ts` API 和 `usePositionSession`。
- [ ] 用服务端 Session 替换 `POSITION_TASK_DRAFT_KEY` 主路径。
- [ ] 页面刷新后恢复任务、意图、选中链条、节点状态和当前会话。
-
-完成标准：刷新浏览器后不丢任务和意图；业务链后续编辑不改变已启动会话。
-
-### 阶段 3：情报分析岗意图流程
-
-目标：把情报分析岗固定为岗位协同的入口阶段。
-
- [ ] 将当前“组织筹划岗负责意图”调整为“情报分析岗负责意图”。
- [ ] 仅意图岗位渲染 `Step1Panel` 和意图输入能力。
- [ ] 将任务信息自动作为首轮隐藏背景或开场消息提供给意图智能体。
- [ ] 意图变化时自动保存 `intent_snapshot`。
- [ ] 增加“确认意图并启动业务链”动作。
- [ ] 启动前校验业务链已选、节点岗位已配置、意图已完成。
- [ ] 其他岗位在未启动时显示只读等待状态。
-
-完成标准：情报分析岗确认意图后成功生成节点；其他岗位不能修改意图。
-
-### 阶段 4：岗位直连智能体问答
-
-目标：去除总控，当前岗位直接与自己节点的智能体多轮问答。
-
- [ ] 抽取或封装可嵌入的 Agent Chat 主区，复用现有消息列表和输入框。
- [ ] 右侧智能体列表改为当前链条、当前岗位的交集。
- [ ] 点击智能体或流程节点时切换 `activeNodeKey`。
- [ ] 节点首次发送前幂等创建 thread，`assistantId = node.agent_id`。
- [ ] 写入岗位协同 thread metadata。
- [ ] 本岗位且状态为 `ready/running/done/stale` 时允许输入。
- [ ] 其他岗位节点和 `locked` 节点使用同一消息列表只读展示。
- [ ] 移除流程图“总控协调”节点，首部展示“情报分析岗 · 意图识别”。
-
-完成标准：页面不调用任何总控接口；不同节点对话互不串线；岗位不能向未分配节点发送问题。
-
-### 阶段 5：节点查看与流程状态
-
-目标：流程图成为对话、产物和状态的统一导航。
-
- [ ] 节点增加 `locked/ready/running/done/stale/error` 可视状态。
- [ ] 当前节点增加选中态，并与中间聊天和右侧智能体详情同步。
- [ ] 点击任意已有节点加载完整消息历史。
- [ ] 节点运行时防止重复发送并支持停止当前生成。
- [ ] 计算上一阶段完成情况并自动解锁下一阶段。
- [ ] 画布拖动时阻止节点误点击，双击空白区域复位。
- [ ] 保持左侧滚动条、固定画布高度和父容器裁剪。
-
-完成标准：用户能从流程图定位任意节点，并准确区分可问答、只读、待上游和结果过期状态。
-
-### 阶段 6：上游问答与产物自动交接
-
-目标：下游智能体真正获得上游信息，而不只是页面能够查看。
-
- [ ] 新增节点上下文构建接口。
- [ ] 读取上游节点最新有效回答和结构化意图。
- [ ] 读取上游文本产物并执行字符数限制与截断标记。
- [ ] 为非文本产物实现安全复制或只读挂载。
- [ ] 发送消息时通过 `task_external_context` 注入上下文。
- [ ] 回答结束后同步 `latest_answer`、产物清单和 `revision`。
- [ ] 上游更新时传播 `stale` 状态。
- [ ] 增加上下文顺序、截断、文件隔离和版本传播测试。
-
-完成标准：下游回答能够引用上游真实结论；不需要用户复制粘贴；不同 thread 的文件不串写。
-
-### 阶段 7：分析结果聚合
-
-目标：右侧结果页展示全部岗位、节点的真实结果。
-
- [ ] 新增 Session 结果聚合接口。
- [ ] 回答结论生成“问答结果”记录。
- [ ] 每个实际文件生成独立产物记录。
- [ ] 卡片显示智能体名称、产物名称、岗位、生成时间和状态。
- [ ] 支持按岗位、节点、产物类型筛选。
- [ ] 点击结果跳转并高亮对应流程节点。
- [ ] 文本产物复用现有预览组件，其他文件复用下载地址。
- [ ] `stale` 结果显示“上游已更新”提示，不自动隐藏旧结果。
-
-完成标准：结果数量、节点文件清单和实际线程产物一致；点击结果能回到对应对话。
-
-### 阶段 8：嵌入、权限与恢复
-
-目标：满足外部系统嵌入及多人岗位使用场景。
-
- [ ] 支持从 URL/外部任务接口恢复 `external_task_id` 和 Session。
- [ ] 复用现有 `embed=1` 模式隐藏全局侧边栏和导航外壳。
- [ ] 深浅主题下核对左、中、右三栏背景和 TDesign 控件。
- [ ] 明确岗位下拉在嵌入系统中的来源和默认值。
- [ ] 若接入真实用户岗位，新增 Session 成员/岗位授权模型。
- [ ] 服务端校验当前用户是否能向目标节点发送问题。
- [ ] 定义会话归档、任务关闭和只读历史规则。
-
-完成标准：嵌入刷新不丢会话；不同岗位用户只能写自己的节点，同时可以按规则查看上游节点。
-
-### 阶段 9：测试、回归与发布
-
-目标：新功能可上线，原功能零回归。
-
- [ ] 前端类型检查、Chrome 109 CSS 兼容检查和生产构建通过。
- [ ] 后端 Repository、Router、上下文构建和并发创建测试通过。
- [ ] 覆盖线性链、分层链、同阶段并行节点、无岗位配置和智能体被删除场景。
- [ ] 覆盖刷新恢复、重复点击、新旧上游版本、文件过大和产物为空场景。
- [ ] 回归原业务链编辑、原多智能体会商和普通 Agent Chat。
- [ ] 使用真实数据完成浅色、深色、嵌入三种视图的截图对比。
- [ ] 编写接口说明、部署迁移说明和回滚说明。
-
-完成标准：自动化测试通过；真实链条端到端走通；原页面和原接口行为不变。
-
---
-
-## 8. 建议的提交拆分
-
-每个提交保持可独立审查和回滚：
-
-1. `feat(chain): add optional position assignment to seats`
-2. `feat(position-roundtable): add session persistence`
-3. `feat(position-roundtable): persist intent workflow`
-4. `feat(position-roundtable): add direct agent node chats`
-5. `feat(position-roundtable): add interactive chain navigation`
-6. `feat(position-roundtable): inject upstream handoff context`
-7. `feat(position-roundtable): aggregate node artifacts`
-8. `test(position-roundtable): cover workflow and regressions`
-
---
-
-## 9. 验收清单
-
- [ ] 岗位协同页面与原会商页面使用不同路由和不同业务存储。
- [ ] 页面运行过程中没有创建或调用总控智能体。
- [ ] 情报分析岗能够完成并持久化意图识别。
- [ ] 业务链岗位配置只在岗位模式入口显示。
- [ ] 当前岗位的智能体列表只包含被分配的链条节点。
- [ ] 非本岗位节点可查看但不能发送消息。
- [ ] 点击节点可以恢复对应的完整聊天记录和文件产物。
- [ ] 下游智能体能够获得上游问答结果和产物内容。
- [ ] 上游更新后下游结果能够提示过期。
- [ ] 刷新、重新进入和嵌入模式下数据不丢失。
- [ ] 原业务链配置、原多智能体会商和普通智能体问答均无回归。
-
---
-
-## 10. 第一轮推荐实施范围
-
-第一轮建议完成阶段 0～4，形成可实际操作的最小闭环：
-
-```text
-岗位配置 → 创建会话 → 情报分析岗确认意图 → 生成业务链节点
-→ 切换岗位 → 点击本岗位节点 → 直接调用对应智能体问答 → 刷新恢复
-```
-
-第二轮完成阶段 5～7，把流程图查看、上游自动交接和结果聚合补齐；第三轮处理真实岗位权限、外部任务接口和上线回归。
-
-## 11. 当前实现状态（2026-07-21）
-
-已完成的首个可运行闭环：
-
- 业务链席位已支持可选 `position_id`；只有从岗位协同页面进入业务链编辑器时才显示 TDesign 岗位选择器，普通会商配置会完整保留该字段且不显示该控件。未配置岗位的席位会在业务链选择区标明，并在启动前阻止进入节点执行。
- 新任务入口已先以 `mock-task-source.ts` 提供 3 条模拟任务；页面通过 `taskId` 识别任务、自动恢复该任务最近一条未归档会话，支持“新建会话”和会话归档。正式任务接口确认后只替换这一数据源即可。
- 新增独立的 `position_roundtable_sessions` / `position_roundtable_nodes` 持久化、迁移和 `/api/position-roundtable` 接口；它不使用原会商的草稿、总控、作业或自动收口流程。
- 情报分析岗复用既有意图识别对话。确认意图后会冻结业务链、创建节点、将会话 ID 写入新页面 URL，刷新可恢复节点与其已绑定的标准聊天线程。
- 业务链节点直接调用其配置的 `agent_id`，复用原消息列表和输入框。节点问答会注入任务、意图、已完成上游的回答和产物引用；同阶段全部完成后才解锁下一阶段，上游重答会把下游标记为 `stale`。
- 节点交接接口会额外读取上游节点自身线程里的文本产物正文（Markdown、文本、JSON、CSV 等），按总量和单文件长度截断后注入下游智能体；二进制产物仍仅传递安全引用，且不会跨线程写入或共享工作目录。
- 左侧流程图、右侧岗位智能体列表和结果卡片均以当前会话节点为准；跨岗位和未解锁节点保持只读。分析结果会把每条问答、每个实际文件分别列卡，支持按岗位、节点、产物类型筛选，并对 `stale` 结果标明“上游已更新”。
- 选中流程节点或分析结果卡片后，中间对话区会同时展示该节点的产物清单；点击文件复用既有预览组件，读取的始终是该节点绑定线程下的产物。归档会话保持完整可读，但前后端均拒绝继续写入、绑定节点或生成上下文。
-
-仍需在产品/组织接口确定后替换：新任务系统的正式字段与进入方式、真实用户岗位授权、上游非文本产物的安全挂载或复制，以及使用真实登录数据的完整端到端回归。