# 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 可以按“已实现基线”验收：

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

---

## 7. 真实边界

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

它目前代表的是：

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

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