JARVIS/development-doc/plan/agent-update/phase-2-controlled-collaboration.md

Phase 2：受控协作阶段（Controlled Collaboration）

日期：2026-04-03 状态：已实现基线，进入增量完善

---

1. 阶段目标

让 Jarvis 具备复杂请求下的结构化协作编排能力，而不是所有请求都走单一路由或单 agent 顺序执行。

Phase 2 的核心不是“无限协作”，而是：

• 复杂请求可切换到 collaboration 模式
• 请求会被拆成有 owner 的子任务
• 子任务结果会被结构化回收
• 最终输出必须经过 verifier 收尾
• Direct Mode 继续保持独立稳定

---

2. 当前代码中已落地的能力

当前 Jarvis 后端已经在 backend/app/agents/graph.py 中实现了 Phase 2 的最小闭环。

2.1 Mode 切换

已具备：

• master_node() 根据请求复杂度选择 direct 或 collaboration
• _select_request_mode() 会结合角色数量、多步骤信号、显式协作表达进行判断
• 简单请求保持 Direct Mode，不被协作逻辑污染

2.2 任务拆解

已具备：

• _build_collaboration_tasks() 将复杂请求拆成 2~4 个结构化子任务
• 每个 task 带有：
  • task_id
  • role
  • owner_agent_id
  • goal
  • expected_evidence
  • 父子任务关系

2.3 Owner 分配与执行

已具备：

• 每个 task 在构建时已有明确 owner
• _assign_agent_for_task_role() 将 task role 映射到具体执行角色
• _run_collaboration_flow() 逐个调度子任务执行

2.4 结果回收

已具备：

• _collect_task_result() 汇总单 task 的 summary / evidence / status
• _apply_task_result_to_state() 将结果写回 runtime state
• task_results / active_tasks / task_hierarchy 形成结构化回收链路

2.5 verifier 收尾

已具备：

• _verify_collaboration_results() 对协作结果做完整性验证
• 若任务缺失 / evidence 缺失 / 有失败任务，则 verifier 会给出 failed verdict
• 最终结果统一写入：
  • verification_status
  • verification_summary
  • verification_evidence

---

3. 本次补强：Phase / Checkpoint 显式化

本次实现不是从零做 Phase 2，而是把已经存在的协作流程显式建模。

3.1 新增 runtime phase 字段

在 backend/app/agents/state.py 中补充：

• current_phase
• phase_history
• current_checkpoint
• checkpoint_history

初始化默认值：

• current_phase = "phase_0_bootstrap"
• current_checkpoint = "bootstrap.initialized"

3.2 新增 Phase 2 关键 checkpoint

在 _run_collaboration_flow() 中，当前已记录：

• collaboration.tasks_planning
• collaboration.tasks_ready
• collaboration.task_dispatch
• collaboration.task_result_collected

这使得 Phase 2 不再只是“逻辑存在”，而是已经具备阶段感知和关键节点回溯能力。

---

4. 当前实现对应关系

设计目标	当前状态	落点
Mode 切换	已实现	master_node, _select_request_mode
任务拆解	已实现	_build_collaboration_tasks
Owner 分配	已实现	task schema + role assignment
结果回收	已实现	task_results, _collect_task_result
verifier 收尾	已实现	_verify_collaboration_results
Phase/Checkpoint 显式化	已实现	state.py, graph.py
独立 Coordinator 类	未单独抽出	当前仍内嵌在 graph.py
独立 MessageBus 实例	未单独抽出	当前以 message_trace 代替

---

5. 与原方案相比的调整

原文档把 Coordinator、MessageBus、Assigner 设计成独立模块；当前代码并未完全按该物理结构落地，而是采用了先在 graph 内完成闭环，再逐步抽象模块的路线。

因此文档需要调整为：

已有基线

• 结构化协作逻辑已可运行
• message trace / task trace / verifier trace 已存在
• 不需要为了“Phase 2 完成”而强行拆出新文件

后续可选增强

• 将 _run_collaboration_flow() 中的分解 / 分配 / 汇总逻辑抽成 coordinator.py
• 将 message trace 提升为显式 message_bus.py
• 将 task decomposition 策略独立为 collaboration/decomposer.py

---

6. 验收结论

当前 Phase 2 可以按“已实现基线”验收：

• 复杂请求会进入协作模式
• 子任务具备结构化 task schema
• 每个子任务有明确 owner
• 子任务结果可被统一回收
• verifier 强制参与结果收尾
• Direct Mode 保持独立
• phase / checkpoint 已可记录
• 仍未拆成独立 coordinator/message bus 模块

---

7. 真实边界

当前 Phase 2 已经不是草案，但也还不是最终工程形态。

它目前代表的是：

Jarvis 已经具备受控协作运行能力，并且这条协作链路已经进入“可追踪、可验证、可持续增强”的状态。

仍未完成的，只是工程层面的进一步解耦，而不是能力从 0 到 1。