fischer-agentkit/docs/plans/2026-06-24-003-feat-expert-team-pm-collaboration-plan.md

---
date: 2026-06-24
plan_id: 2026-06-24-003
type: feat
title: "feat: 专家团项目经理模式协同"
status: active
origin: docs/brainstorms/2026-06-24-expert-team-project-manager-collaboration-requirements.md
---

# 专家团项目经理模式协同 — 实现计划

## Summary

将专家团 Lead 从"甩手掌柜"升级为"项目经理"——制定计划时定义协作契约，执行过程中监控进展，阶段完成后验收成果（不合格可返工），冲突时协调。专家间通过协作契约实现"可见+可协助"。前端以协作关系图可视化专家间互动。基于 U1-U6 辩论机制基础增量构建。

## Problem Frame

当前专家团执行模式（`src/agentkit/experts/orchestrator.py`）：Lead 分解任务 → 拓扑排序 → 专家孤立执行（仅看到 dependency_outputs）→ Lead 汇总。Lead 是甩手掌柜，专家间无直接通信（`team.py` 注释明确写了"No inter-agent communication"）。

U1-U6 引入了辩论机制（DEBATE phase + 分歧检测 + 用户干预），但辩论是异常处理，不是常态协作。用户的核心痛点是：**当前体现不出多 agent 协同工作**——无论是执行效果还是 UI/UE。

需求文档（`docs/brainstorms/2026-06-24-expert-team-project-manager-collaboration-requirements.md`）定义了项目经理模式：Lead 全程主导（制定计划、安排任务、冲突协调、成果验收），专家间通过协作契约实现可见+可协助。

## Requirements

本计划覆盖需求文档中的 R1-R17，按以下映射组织：

| 需求 ID | 描述 | 实现单元 |
|---------|------|---------|
| R1, R2 | Lead 项目经理角色 + 协作契约定义 | U1 |
| R3, R6, R7 | Lead 监控 + 专家可见 + 主动通知 | U2 |
| R4 | 冲突协调（复用 U1-U6 辩论） | 已有基础 |
| R5, R10, R11 | 验收 + 返工 + 上限 | U3 |
| R8, R9 | 风险标记 + 请求协助 | U4 |
| R12, R13, R14 | 前端协作关系图 + 验收状态 + 实时互动 | U5 |
| R15, R16 | 与私董会区分 | 架构固有 |
| R17 | CLI 协同事件渲染 | U6 |

## Key Technical Decisions

**KTD1: 协作契约嵌入 PlanPhase 而非独立实体。** 协作契约是阶段的属性，不是独立的生命周期对象。每个 PlanPhase 携带 `collaboration_contracts: list[CollaborationContract]`，定义该阶段中哪些专家需要协作、协作内容是什么。理由：契约与阶段强绑定，独立实体增加不必要的复杂度。

**KTD2: 专家可见范围限定在协作契约内。** 打破 KTD3 的完全上下文隔离，但不是完全开放——专家只能看到协作契约中指定的相关专家输出，而非所有专家的所有工作。理由：平衡"可见"需求与信息过载风险。

**KTD3: 验收作为阶段完成的门控。** 在 `_execute_execution_phase` 完成后、标记 COMPLETED 前，插入 `_review_phase_output` 步骤。Lead 用 LLM 判断输出是否满足要求。理由：验收是项目经理的核心职责，也是质量保证的关键环节。

**KTD4: 返工通过阶段状态回退实现。** 验收不合格时，将阶段状态从 RUNNING 回退到 PENDING，附带 Lead 的修改要求，重新执行。返工次数上限 MAX_REWORKS=2，超过则标记 FAILED。理由：复用现有执行流程，不引入新的执行路径。

**KTD5: 风险标记通过 WS 事件 + Lead 决策实现。** 专家在执行过程中可通过输出中的特殊标记（如 `[RISK: ...]`）标记风险。Orchestrator 解析标记，发出 `risk_flagged` 事件，Lead 决定是否调整计划。理由：不改变专家的执行流程，通过输出解析实现风险标记。

**KTD6: 前端协作关系图用 SVG 实现。** 节点=专家（圆形+头像），边=协作关系（实线=契约，虚线=数据流向），验收状态用颜色标记。理由：SVG 足够表达这种关系图，无需引入 Canvas/WebGL 的复杂度。

## High-Level Technical Design

### 项目经理模式执行流程

```
用户发送 @team <task>
  │
  ▼
Lead 制定计划（含协作契约）  ◄── U1
  │  ── collaboration_contract_defined 事件
  ▼
拓扑排序 → 层执行
  │
  ▼
专家执行阶段  ◄── U2
  │  ├── 按协作契约读取相关专家输出（可见）
  │  ├── 执行任务
  │  ├── 完成后按协作契约通知相关专家（可协助）
  │  │   ── collaboration_notice 事件
  │  └── 可标记风险  ◄── U4
  │      ── risk_flagged 事件 → Lead 决策
  ▼
Lead 验收  ◄── U3
  │  ├── 合格 → 标记 COMPLETED，进入下一阶段
  │  │   ── review_result 事件（passed）
  │  └── 不合格 → 返工（回退到 PENDING，附修改要求）
  │      ── review_result 事件（failed + feedback）
  │      返工次数 > MAX_REWORKS → 标记 FAILED
  ▼
分歧检测（复用 U3 辩论机制）
  │  └── 检测到分歧 → 插入 DEBATE phase
  ▼
所有阶段完成 → Lead 汇总 → 团队解散
```

### 协作契约数据流

```
Lead 分解任务
  │
  ├── Phase A (后端): collaboration_contracts = [
  │     {to_expert: "前端", content: "API 定义", status: "pending"}
  │   ]
  │
  └── Phase B (前端): collaboration_contracts = [
        {from_expert: "后端", content: "API 定义", status: "pending"}
      ]

Phase A 执行完成
  │
  ├── 后端输出写入 SharedWorkspace
  ├── 后端按契约通知前端 ── collaboration_notice 事件
  │
  ▼
Phase B 执行时
  │
  └── 前端按契约从 SharedWorkspace 读取后端输出（可见）
```

## Implementation Units

### U1. 协作契约数据模型 + Lead 生成契约

**Goal:** 在 PlanPhase 中添加协作契约字段，修改 Lead 分解任务的 prompt 和解析逻辑，使 Lead 在制定计划时定义专家间的协作关系。

**Requirements:** R1, R2

**Dependencies:** 无（基于 U1-U6 辩论基础）

**Files:**
- `src/agentkit/experts/plan.py` — 添加 CollaborationContract dataclass，PlanPhase 添加 collaboration_contracts 字段
- `src/agentkit/experts/orchestrator.py` — 修改 `_decompose_task` prompt，修改 `_parse_phases` 解析契约
- `tests/unit/experts/test_plan.py` — 协作契约数据模型测试
- `tests/unit/experts/test_pm_collaboration.py` — Lead 生成契约测试

**Approach:**
1. 定义 `CollaborationContract` dataclass：`from_expert: str`, `to_expert: str`, `content_description: str`, `status: str`（pending/delivered/received）
2. PlanPhase 添加 `collaboration_contracts: list[CollaborationContract]` 字段，更新 to_dict/from_dict
3. 修改 `_decompose_task` 的 prompt，要求 Lead 在分解任务时为每个阶段定义协作契约
4. 修改 `_parse_phases` 解析 LLM 返回的协作契约信息
5. 在 plan_update 事件中包含协作契约信息

**Patterns to follow:** PhaseType + debate_config 的添加模式（U1 辩论基础）

**Test scenarios:**
- **Happy path:** CollaborationContract 序列化/反序列化正确
- **Happy path:** PlanPhase 携带 collaboration_contracts 序列化/反序列化正确
- **Happy path:** Lead 分解任务时生成的 phases 包含协作契约
- **Edge case:** 协作契约为空列表时正常工作
- **Edge case:** LLM 返回的协作契约格式不正确时优雅降级（空契约列表）
- **Integration:** plan_update 事件包含协作契约信息

**Verification:** Lead 分解任务后，每个 PlanPhase 携带协作契约；前端能从 plan_update 事件中获取协作契约信息。

---

### U2. 协作契约执行 — 专家可见 + 主动通知

**Goal:** 专家执行时按协作契约读取相关专家的输出（可见），完成后按契约主动通知相关专家（可协助）。

**Requirements:** R3, R6, R7

**Dependencies:** U1

**Files:**
- `src/agentkit/experts/orchestrator.py` — 修改 `_execute_execution_phase`，添加 `_notify_collaborators` 方法
- `tests/unit/experts/test_pm_collaboration.py` — 协作契约执行测试

**Approach:**
1. 修改 `_execute_execution_phase`：除了 dependency_outputs，还按协作契约中的 `from_expert` 读取相关专家的输出，注入到专家的 context 中
2. 专家完成后，调用 `_notify_collaborators`：遍历当前阶段的 collaboration_contracts，对每个 `to_expert` 发出 `collaboration_notice` 事件
3. 更新契约状态为 delivered
4. `collaboration_notice` 事件包含：from_expert, to_expert, content_description, phase_id, output_key

**Patterns to follow:** `_execute_execution_phase` 中 dependency_outputs 的读取模式

**Test scenarios:**
- **Happy path:** 专家执行时能读到协作契约中 from_expert 的输出
- **Happy path:** 专家完成后，协作契约中的 to_expert 收到 collaboration_notice 事件
- **Happy path:** 契约状态从 pending 更新为 delivered
- **Edge case:** 协作契约中 from_expert 的输出不存在时，专家仍能正常执行（无额外 context）
- **Edge case:** 协作契约为空时，行为与当前一致（向后兼容）
- **Integration:** collaboration_notice 事件被正确广播

**Verification:** 专家执行时能看到协作契约中相关专家的输出；完成后相关专家收到通知。

---

### U3. Lead 验收环节 + 返工机制

**Goal:** 每个阶段完成后，Lead 验收输出质量。合格则进入下一阶段，不合格则要求返工，返工有次数上限。

**Requirements:** R5, R10, R11

**Dependencies:** U1

**Files:**
- `src/agentkit/experts/orchestrator.py` — 添加 `_review_phase_output` 方法，修改 `_execute_execution_phase` 插入验收步骤
- `tests/unit/experts/test_pm_collaboration.py` — 验收与返工测试

**Approach:**
1. 添加 `MAX_REWORKS = 2` 类常量
2. 在 PlanPhase 中添加 `rework_count: int = 0` 字段和 `review_feedback: str | None = None` 字段
3. 添加 `_review_phase_output(phase, result) -> tuple[bool, str]` 方法：Lead 用 LLM 判断输出是否满足阶段要求，返回 (passed, feedback)
4. 在 `_execute_execution_phase` 中，专家执行完成后、标记 COMPLETED 前，调用 `_review_phase_output`
5. 验收合格 → 标记 COMPLETED，发出 `review_result` 事件（passed）
6. 验收不合格 → rework_count += 1，若未超上限则回退状态到 PENDING，附 feedback，重新执行；若超上限则标记 FAILED
7. 发出 `review_result` 事件（passed/failed + feedback）

**Patterns to follow:** `_detect_divergence` 的 LLM 判断模式（U3 辩论基础）

**Test scenarios:**
- **Happy path:** 验收合格时，阶段标记 COMPLETED，发出 review_result（passed）事件
- **Happy path:** 验收不合格时，阶段回退到 PENDING，附 feedback，重新执行
- **Edge case:** 返工次数达到 MAX_REWORKS 仍不合格，标记 FAILED
- **Edge case:** Lead LLM 不可用时，跳过验收直接标记 COMPLETED（优雅降级）
- **Integration:** review_result 事件被正确广播，包含 feedback

**Verification:** 阶段完成后 Lead 验收；不合格可返工；返工超限标记失败。

---

### U4. 专家风险标记 + Lead 调整

**Goal:** 专家执行时可标记风险，Lead 收到风险标记后决定是否调整计划（插入辩论、要求返工、或接受风险继续）。

**Requirements:** R8, R9

**Dependencies:** U1

**Files:**
- `src/agentkit/experts/orchestrator.py` — 添加 `_parse_risk_flags` 方法，修改 `_execute_execution_phase` 解析风险标记
- `tests/unit/experts/test_pm_collaboration.py` — 风险标记测试

**Approach:**
1. 定义风险标记格式：专家输出中包含 `[RISK: <风险描述>]` 标记
2. 添加 `_parse_risk_flags(content) -> list[str]` 方法：从专家输出中解析风险标记
3. 在 `_execute_execution_phase` 中，专家执行完成后，解析输出中的风险标记
4. 若有风险标记，发出 `risk_flagged` 事件（expert, risk_description, phase_id）
5. Lead 收到风险标记后，用 LLM 决策：接受风险继续 / 插入辩论协调 / 要求返工
6. 风险标记不影响阶段状态（仍可 COMPLETED），但 Lead 的决策可能触发后续动作

**Patterns to follow:** `_detect_divergence` 的 LLM 判断模式

**Test scenarios:**
- **Happy path:** 专家输出包含 `[RISK: ...]` 标记时，risk_flagged 事件被发出
- **Happy path:** 专家输出不包含风险标记时，无 risk_flagged 事件
- **Edge case:** 多个风险标记都被解析
- **Edge case:** 风险标记格式不正确时被忽略
- **Integration:** risk_flagged 事件包含专家名称和风险描述

**Verification:** 专家可标记风险；Lead 收到风险标记后做出决策。

---

### U5. 前端协作关系图

**Goal:** 前端以协作关系图可视化专家间互动——节点为专家，边为协作关系和数据流向，验收状态用颜色标记。

**Requirements:** R12, R13, R14

**Dependencies:** U1, U2, U3, U4

**Files:**
- `src/agentkit/server/frontend/src/api/types.ts` — 新增 WS 事件类型和数据接口
- `src/agentkit/server/frontend/src/stores/chat.ts` — 新增 collaborationState ref，处理新事件
- `src/agentkit/server/frontend/src/components/chat/messages/CollaborationGraphCard.vue` — 新建协作关系图组件
- `src/agentkit/server/frontend/src/components/chat/messages/ReviewResultCard.vue` — 新建验收结果卡片
- `src/agentkit/server/frontend/src/components/chat/messages/RiskFlagCard.vue` — 新建风险标记卡片
- `src/agentkit/server/frontend/src/components/chat/messages/index.ts` — 新增导出
- `src/agentkit/server/frontend/src/components/chat/helpers/useMessageRenderer.ts` — 新增视图类型

**Approach:**
1. 在 `types.ts` 中新增 WS 事件类型：`collaboration_contract_defined`, `collaboration_notice`, `review_result`, `risk_flagged`
2. 新增数据接口：`ICollaborationContract`, `ICollaborationNotice`, `IReviewResult`, `IRiskFlag`
3. 在 `chat.ts` 中新增 `collaborationState` ref，存储协作契约、通知、验收结果、风险标记
4. 新增 switch case 处理 4 种新事件
5. `CollaborationGraphCard.vue`：SVG 绘制节点（专家圆形+头像）和边（实线=契约，虚线=数据流向），验收状态用颜色标记（绿=通过，黄=待验收，红=返工/失败）
6. `ReviewResultCard.vue`：展示验收结果（passed/failed + feedback）
7. `RiskFlagCard.vue`：展示风险标记（专家 + 风险描述）
8. 在 `useMessageRenderer.ts` 中新增视图类型和渲染规格

**Patterns to follow:** U5 辩论可视化的 BoardState 模式（debateState ref + 事件 switch case + 专用卡片组件）

**Test scenarios:**
- **Happy path:** collaboration_contract_defined 事件触发协作关系图渲染
- **Happy path:** collaboration_notice 事件在图上显示数据流向（虚线动画）
- **Happy path:** review_result 事件更新节点颜色（绿=通过，红=返工）
- **Happy path:** risk_flagged 事件显示风险标记卡片
- **Edge case:** 无协作契约时，协作关系图显示空状态
- **Edge case:** 多个协作契约同时存在时，图正确渲染所有边

**Verification:** 前端能渲染协作关系图；验收状态和风险标记实时可见。

---

### U6. CLI 协同事件渲染

**Goal:** CLI 支持项目经理模式的协同事件渲染，延续 U6 辩论 Rich 渲染模式。

**Requirements:** R17

**Dependencies:** U1, U2, U3, U4

**Files:**
- `src/agentkit/cli/chat.py` — 在 `_execute_team_cli` 中添加协同事件渲染
- `tests/unit/cli/test_chat_multiagent.py` — 扩展测试

**Approach:**
1. 在 `_execute_team_cli` 的事件处理循环中，新增 4 种事件的处理：
   - `collaboration_contract_defined`：用 Panel 展示协作契约列表
   - `collaboration_notice`：用带颜色的文本展示"专家A → 专家B: 内容描述"
   - `review_result`：用绿色（passed）或红色（failed）Panel 展示验收结果和 feedback
   - `risk_flagged`：用黄色 Panel 展示风险标记
2. 更新 `_print_help` 帮助文本，说明项目经理模式的协同特性

**Patterns to follow:** U6 辩论事件的 Rich 渲染模式（Panel/Markdown/colored text）

**Test scenarios:**
- **Happy path:** collaboration_contract_defined 事件正确渲染为 Panel
- **Happy path:** collaboration_notice 事件正确渲染为带颜色的文本
- **Happy path:** review_result 事件正确渲染（passed=绿色，failed=红色）
- **Happy path:** risk_flagged 事件正确渲染为黄色 Panel
- **Edge case:** 事件数据缺失时优雅降级
- **Integration:** _print_help 包含项目经理模式说明

**Verification:** CLI 能渲染 4 种协同事件；帮助文本包含项目经理模式说明。

---

## Scope Boundaries

### In Scope

- 协作契约数据模型 + Lead 生成契约（U1）
- 专家按契约可见 + 主动通知（U2）
- Lead 验收 + 返工机制（U3）
- 专家风险标记 + Lead 调整（U4）
- 前端协作关系图（U5）
- CLI 协同事件渲染（U6）

### Deferred to Follow-Up Work

- 实时协作面板（Figma/Google Docs 式）——协作关系图已满足当前需求
- 专家完全自主互动（无固定协议）——当前保持协作契约的结构化协作
- 协作关系图的拖拽交互——当前只做可视化展示
- 专家请求协助的主动通信——当前只做风险标记，请求协助作为后续迭代

### Outside this Product's Identity

- 私董会模式融合——专家团和私董会是两种根本不同的协同方式
- 去中心化协作（共享黑板模式）——与私董会界限模糊

## Risks & Dependencies

**依赖 U1-U6 辩论机制：** 冲突协调复用 DEBATE phase 机制，不重新建设。U1-U6 的分歧检测、用户干预通道等基础设施可直接复用。

**LLM 调用次数显著增加：** Lead 不只分解+汇总，还要定义协作契约、验收成果、决策风险。每个阶段至少多 1-2 次 LLM 调用（验收 + 风险决策）。需评估成本影响，必要时可配置开关。

**上下文隔离被打破：** 专家需看到协作契约中相关专家的工作，KTD3 的完全隔离不再成立。通过限定可见范围（仅协作契约内的专家）控制信息过载。

**协作契约质量依赖 Lead 能力：** 如果 Lead 定义的协作契约不好，协同会退化回当前的孤立执行。可通过 prompt engineering 优化，但本质依赖 LLM 能力。

**返工循环风险：** 验收不合格可能触发返工循环。MAX_REWORKS=2 上限防止无限循环，但极端情况下仍可能导致执行时间过长。

## Open Questions

### Deferred to Implementation

- 协作契约的 LLM prompt 具体措辞——需在实现时调试
- 验收 LLM 判断的准确率——需在实现时验证
- 风险标记的解析规则是否需要更灵活——当前用 `[RISK: ...]` 格式，实现时可能需要调整
- 前端协作关系图的布局算法——当前用简单的圆形布局，实现时可能需要力导向布局