18 KiB

Raw Blame History

date	plan_id	type	title	status	origin
2026-06-24	2026-06-24-003	feat	feat: 专家团项目经理模式协同	active	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:

定义 CollaborationContract dataclass：from_expert: str, to_expert: str, content_description: str, status: str（pending/delivered/received）
PlanPhase 添加 collaboration_contracts: list[CollaborationContract] 字段，更新 to_dict/from_dict
修改 _decompose_task 的 prompt，要求 Lead 在分解任务时为每个阶段定义协作契约
修改 _parse_phases 解析 LLM 返回的协作契约信息
在 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:

修改 _execute_execution_phase：除了 dependency_outputs，还按协作契约中的 from_expert 读取相关专家的输出，注入到专家的 context 中
专家完成后，调用 _notify_collaborators：遍历当前阶段的 collaboration_contracts，对每个 to_expert 发出 collaboration_notice 事件
更新契约状态为 delivered
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:

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

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

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

在 _execute_team_cli 的事件处理循环中，新增 4 种事件的处理：
- collaboration_contract_defined：用 Panel 展示协作契约列表
- collaboration_notice：用带颜色的文本展示"专家A → 专家B: 内容描述"
- review_result：用绿色（passed）或红色（failed）Panel 展示验收结果和 feedback
- risk_flagged：用黄色 Panel 展示风险标记
更新 _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: ...] 格式，实现时可能需要调整
前端协作关系图的布局算法——当前用简单的圆形布局，实现时可能需要力导向布局

18 KiB Raw Blame History Unescape Escape

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

Summary

Problem Frame

Requirements

Key Technical Decisions

High-Level Technical Design

项目经理模式执行流程

协作契约数据流

Implementation Units

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

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

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

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

U5. 前端协作关系图

U6. CLI 协同事件渲染

Scope Boundaries

In Scope

Deferred to Follow-Up Work

Outside this Product's Identity

Risks & Dependencies

Open Questions

Deferred to Implementation

18 KiB

Raw Blame History