# 岗位智能体协同页面 · 分步实现计划

> 页面：`/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` 结果标明“上游已更新”。
- 选中流程节点或分析结果卡片后，中间对话区会同时展示该节点的产物清单；点击文件复用既有预览组件，读取的始终是该节点绑定线程下的产物。归档会话保持完整可读，但前后端均拒绝继续写入、绑定节点或生成上下文。

仍需在产品/组织接口确定后替换：新任务系统的正式字段与进入方式、真实用户岗位授权、上游非文本产物的安全挂载或复制，以及使用真实登录数据的完整端到端回归。