deerflow-code/frontend-web/docs/position-roundtable-delivery-workflow-plan.md

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

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

## 实施核对（2026-07-21）

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

```text
任务信息 → 情报分析岗识别并确认意图 → 启动校验并冻结业务链
→ 分阶段席位直接问答/交付 Markdown → 全部有效交付
→ 方案总结智能体（roundtable-summary）→ 行动规划智能体（position-action-planner）
→ 可随时返回交付产物驳回 → 后续阶段及内置产物级联失效 → 重做后重新收口
```

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

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

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

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