172 lines
10 KiB
Markdown
172 lines
10 KiB
Markdown
---
|
||
date: 2026-06-24
|
||
topic: expert-team-project-manager-collaboration
|
||
---
|
||
|
||
# 专家团项目经理模式协同 — 需求文档
|
||
|
||
## Summary
|
||
|
||
将专家团（ExpertTeam）的 Lead 从"甩手掌柜"重新定义为"项目经理"——全程主导制定计划、安排任务、冲突协调、成果验收。专家间通过协作契约实现"可见+可协助"的实质性数据交换。前端以协作关系图可视化专家间互动，与私董会（Board）的平等讨论模式形成明确区分。
|
||
|
||
## Problem Frame
|
||
|
||
当前专家团的执行模式是"Lead 分解任务 → 专家孤立执行 → Lead 汇总结果"。Lead 是甩手掌柜：分解完就等结果，汇总完就交付。专家之间没有直接通信，Lead 持有所有状态（`src/agentkit/experts/team.py` 注释明确写了"专家间无直接通信"）。
|
||
|
||
U1-U6 的辩论功能在"分歧检测"时引入了一个互动点，但辩论是异常处理，不是常态协作。用户的核心痛点是：**当前体现不出多 agent 协同工作**——无论是实际执行效果还是用户看到的 UI/UE。
|
||
|
||
用户期望专家团像"项目实施团队"运作：项目经理统筹协调，制定计划，安排任务，冲突协调，成果验收。这与私董会（多轮平等讨论、观点碰撞）是两种根本不同的协同方式，必须明确区分。
|
||
|
||
## Key Decisions
|
||
|
||
**项目经理模式 over 共享黑板模式。** Lead 从"甩手掌柜"变为"全程参与的项目经理"，保持 Lead 权威和结构化协作。共享黑板模式（去中心化、专家自主）与私董会界限模糊，不符合"项目实施团队"定位。
|
||
|
||
**Lead 动态选择流程 over 固定 5 步模板。** Lead 根据任务性质从"信息收集→制定计划→规划方案→具体实施→验证回测"中选择/组合阶段，而非强制走固定流程。保留灵活性，适应不同类型的复杂任务。
|
||
|
||
**协作契约作为协同结构。** Lead 分解任务时为每个阶段定义"协作契约"——明确哪些专家需要协作、协作内容是什么。让"可见+可协助"有明确结构，而非专家自主判断何时互动。
|
||
|
||
**复用 U1-U6 辩论机制做冲突协调。** Lead 发现专家间冲突时触发辩论（复用已有 DEBATE phase 机制），避免重复建设。
|
||
|
||
**打破上下文隔离（KTD3）。** 专家需看到协作契约中相关专家的工作输出，不再完全上下文隔离。这是"可见+可协助"的前提，但增加了上下文复杂度——需控制可见范围避免信息过载。
|
||
|
||
## Actors
|
||
|
||
- A1. **Lead（项目经理）** — 统筹协调、制定计划（含协作契约）、安排任务、冲突协调、成果验收。全程主导，不再是甩手掌柜。
|
||
- A2. **专家（团队成员）** — 执行分配的任务、按协作契约主动协助相关专家、可标记风险、可请求协助。
|
||
- A3. **用户** — 发起专家团任务、可通过 U4 干预通道介入（`/stop`、`/debate`、纯文本注入上下文）。
|
||
|
||
## Requirements
|
||
|
||
### Lead 项目经理角色
|
||
|
||
- R1. Lead 全程主导任务执行，职责从"分解+汇总"扩展为"制定计划、安排任务、冲突协调、成果验收"五个方面。
|
||
- R2. Lead 制定计划时为每个阶段定义"协作契约"——明确该阶段哪些专家需要协作、协作内容是什么（如"后端向前端提供 API 定义"）。
|
||
- R3. Lead 执行过程中监控各专家进展，主动向协作契约中的相关专家推送进展信息。
|
||
- R4. Lead 发现专家间冲突时触发协调，复用 U1-U6 的 DEBATE phase 机制。
|
||
- R5. Lead 在每个阶段完成后进行验收，验收结果决定是否进入下一阶段。
|
||
|
||
### 专家协作行为
|
||
|
||
- R6. 专家执行任务时能看到协作契约中相关专家的工作输出（打破当前上下文隔离）。
|
||
- R7. 专家完成自己的输出后，按协作契约主动通知相关专家（实质性数据交换）。
|
||
- R8. 专家可主动标记风险，Lead 收到风险标记后决定是否调整计划或触发协调。
|
||
- R9. 专家可向其他专家请求协助，请求通过 Lead 中转或按协作契约直接通信。
|
||
|
||
### 验收与返工
|
||
|
||
- R10. 验收不合格时，Lead 可要求负责专家返工，返工需明确修改要求。
|
||
- R11. 返工次数有上限（建议 2 次），超过上限则标记阶段失败，触发 fallback 机制。
|
||
|
||
### 前端可视化
|
||
|
||
- R12. 前端以协作关系图展示专家间互动——节点为专家，边为协作关系和数据流向，替代当前的扁平阶段列表。
|
||
- R13. 验收状态在协作关系图上可见（通过/返工/待验收），用户一眼看出团队进展。
|
||
- R14. 专家间的协助、风险标记、请求等互动事件实时呈现在协作关系图上，让用户看到"团队在协作"而非"机器在跑任务"。
|
||
|
||
### 与私董会的区分
|
||
|
||
- R15. 专家团始终保持 Lead 主导的结构化分工协作，不退化为私董会的平等讨论模式。
|
||
- R16. 专家团的协同围绕"完成任务"展开（有验收、有返工），私董会的协同围绕"达成共识"展开（多轮发言、主持人小结）。
|
||
|
||
### CLI 支持
|
||
|
||
- R17. CLI 支持项目经理模式的协同事件渲染（协作通知、验收结果、风险标记等），延续 U6 的 Rich 渲染模式。
|
||
|
||
## Key Flows
|
||
|
||
- F1. **项目经理模式执行流程**
|
||
- **Trigger:** 用户发送 `@team <task>` 消息。
|
||
- **Actors:** A1（Lead）, A2（专家）, A3（用户）。
|
||
- **Steps:**
|
||
1. Lead 制定计划，分解为阶段，为每个阶段定义协作契约。
|
||
2. 按拓扑排序执行阶段，同层并行、层间串行。
|
||
3. 专家执行时按协作契约看到相关专家输出，完成后主动通知相关专家。
|
||
4. Lead 监控进展，发现冲突时触发辩论协调。
|
||
5. 每个阶段完成后 Lead 验收，合格则进入下一阶段，不合格则要求返工。
|
||
6. 所有阶段完成后 Lead 汇总结果，团队解散。
|
||
- **Outcome:** 任务完成，用户看到全程协作过程和最终成果。
|
||
- **Covered by:** R1, R2, R3, R5, R6, R7.
|
||
|
||
- F2. **专家主动协助**
|
||
- **Trigger:** 专家完成自己的输出，协作契约中指定了需通知的相关专家。
|
||
- **Actors:** A2（专家）。
|
||
- **Steps:**
|
||
1. 专家完成阶段输出。
|
||
2. 按协作契约，将输出推送给相关专家。
|
||
3. 相关专家收到通知，可读取输出用于自己的任务。
|
||
4. 前端协作关系图上显示数据流向。
|
||
- **Outcome:** 专家间实现实质性数据交换，协同可见。
|
||
- **Covered by:** R6, R7, R12, R14.
|
||
|
||
- F3. **验收与返工**
|
||
- **Trigger:** 阶段执行完成，Lead 进行验收。
|
||
- **Actors:** A1（Lead）, A2（专家）。
|
||
- **Steps:**
|
||
1. Lead 检查阶段输出是否满足要求。
|
||
2. 合格 → 标记阶段完成，进入下一阶段。
|
||
3. 不合格 → 向负责专家发出返工要求，明确修改点。
|
||
4. 专家返工，Lead 再次验收。
|
||
5. 返工次数超过上限 → 标记阶段失败，触发 fallback。
|
||
- **Outcome:** 阶段质量得到保证，或触发降级处理。
|
||
- **Covered by:** R5, R10, R11, R13.
|
||
|
||
## Acceptance Examples
|
||
|
||
- AE1. **验收不合格触发返工**
|
||
- **Covers R5, R10, R11.**
|
||
- **Given:** 一个阶段执行完成，Lead 验收发现输出不满足要求。
|
||
- **When:** Lead 发出返工要求，明确修改点。
|
||
- **Then:** 负责专家返工，Lead 再次验收。若返工 2 次仍不合格，标记阶段失败。
|
||
|
||
- AE2. **专家按协作契约主动协助**
|
||
- **Covers R2, R6, R7.**
|
||
- **Given:** Lead 分解任务时定义了协作契约："后端阶段完成后向前端提供 API 定义"。
|
||
- **When:** 后端专家完成 API 定义。
|
||
- **Then:** 前端专家收到 API 定义通知，可读取用于前端实现。协作关系图上显示后端→前端的数据流向。
|
||
|
||
- AE3. **专家标记风险触发 Lead 调整**
|
||
- **Covers R8, R3.**
|
||
- **Given:** 专家执行时发现上游输出有问题。
|
||
- **When:** 专家标记风险。
|
||
- **Then:** Lead 收到风险标记，决定是否调整计划（如插入辩论阶段、要求上游返工、或接受风险继续）。
|
||
|
||
- AE4. **与私董会的区分**
|
||
- **Covers R15, R16.**
|
||
- **Given:** 用户分别发起 `@team` 和 `@board` 任务。
|
||
- **When:** 两者执行时。
|
||
- **Then:** `@team` 显示协作关系图（Lead 主导、分工协作、有验收）；`@board` 显示发言流（平等讨论、主持人小结、无验收）。两者可视化形态明确不同。
|
||
|
||
## Scope Boundaries
|
||
|
||
### Deferred for later
|
||
|
||
- 实时协作面板（Figma/Google Docs 式）——协作关系图已满足当前可视化需求，实时面板是后续迭代方向。
|
||
- 专家完全自主互动（无固定协议）——当前保持协作契约的结构化协作，自主互动作为后续探索。
|
||
|
||
### Outside this product's identity
|
||
|
||
- 私董会模式融合——专家团和私董会是两种根本不同的协同方式，不合并。专家团围绕"完成任务"，私董会围绕"达成共识"。
|
||
- 去中心化协作（共享黑板模式）——与私董会界限模糊，不符合"项目实施团队"定位。
|
||
|
||
## Dependencies / Assumptions
|
||
|
||
- **依赖 U1-U6 辩论机制**：冲突协调复用 DEBATE phase 机制，不重新建设。
|
||
- **依赖 U4 用户干预通道**：用户介入复用已有的 `/stop`、`/debate`、纯文本注入机制。
|
||
- **LLM 调用次数显著增加**：Lead 不只分解+汇总，还要定义协作契约、监控进展、协调冲突、验收成果。需评估成本影响。
|
||
- **上下文隔离被打破**：专家需看到相关专家的工作，KTD3 的完全隔离不再成立。需控制可见范围（仅协作契约内的专家），避免信息过载。
|
||
- **协作契约质量依赖 Lead 能力**：如果 Lead 定义的协作契约不好，协同会退化回当前的孤立执行。
|
||
|
||
## Outstanding Questions
|
||
|
||
### Resolve Before Planning
|
||
|
||
（无——实现层面的问题已移至 Deferred to Planning）
|
||
|
||
### Deferred to Planning
|
||
|
||
- 协作契约的数据结构如何设计？是嵌入 PlanPhase 还是独立实体？（影响架构设计）
|
||
- 专家间的"可见"是实时推送还是按需读取？（影响性能和复杂度）
|
||
- 返工上限的具体数值（建议 2 次，需在实现时验证）。
|
||
- 协作关系图的前端技术选型（SVG/Canvas/WebGL）。
|
||
- CLI 协同事件的具体渲染样式。
|