# Phase 3：动态协作阶段（Dynamic Collaboration）

日期：2026-04-03
状态：已实现受限基线，仍有扩展空间

---

## 1. 阶段目标

在 Phase 2 已具备任务拆解、owner 分配、结果回收、verifier 收尾的基础上，让 Jarvis 获得**受约束的动态协作能力**。

这一阶段的重点不是做成无限 swarm，而是做到：

- 协作运行时能追踪 parent / root / depth
- 动态创建行为受到权限和预算限制
- 内部消息和事件能留下轨迹
- 长流程可以中断和恢复
- 所有动态行为都可观察、可审计

---

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

当前 Jarvis 已经在 `backend/app/agents/graph.py` 中落地了 Phase 3 的核心基线。

### 2.1 Agent tree tracking

当前 state 已具备：

- `agent_id`
- `parent_agent_id`
- `root_agent_id`
- `collaboration_depth`
- `spawned_agent_ids`

这意味着当前已经可以追踪：

- 谁是根 agent
- 谁创建了谁
- 当前协作深度是多少
- 本轮生成了哪些 child agents

### 2.2 受限动态创建

当前已具备：

- `_create_child_agent()` 负责生成 child agent id
- `_spawn_permission_for_role()` 控制哪些角色可创建子 agent
- 基于 budget / role policy / depth 的限制已存在
- 若不满足条件，会记录 `agent.spawn.blocked`

换句话说，当前已经不是“自由创建”，而是**受治理的动态创建**。

### 2.3 生命周期事件

当前已具备事件类型：

- `agent.created`
- `agent.spawn.blocked`
- `agent.message.sent`
- `agent.message.received`
- `agent.interrupt.requested`
- `agent.interrupt.completed`
- `agent.recovery.started`
- `agent.recovery.completed`
- `agent.task.interrupted`
- `agent.task.recovered`
- `agent.task.reassigned`
- `agent.collaboration.budget.updated`

本次又新增：

- `agent.phase.changed`
- `agent.checkpoint.recorded`

说明当前运行时已经具备较完整的**协作生命周期可见性**。

### 2.4 Interrupt / Recovery

当前已具备：

- `_record_interrupt()`
- `_record_recovery()`
- `interrupted_tasks`
- `recovery_trace`
- `recovery_points`

这使得长流程协作已经具备最小中断 / 恢复链路，而不只是一次性执行。

---

## 3. 本次补强：Phase 3 显式阶段与检查点

本次改动把原本分散在运行时内部的动态协作过程，进一步显式化。

### 3.1 Phase 切换

在协作 flow 中，现在会显式进入：

- `phase_2_controlled_collaboration`
- `phase_3_dynamic_collaboration`
- `phase_4_visibility_and_verification`

其中 `phase_3_dynamic_collaboration` 表示：

- 子任务已进入 dispatch / spawn / child execution 阶段
- 运行时已经处于真实的动态协作执行态

### 3.2 Dynamic Collaboration checkpoints

当前已记录的关键 checkpoint 包括：

- `collaboration.task_dispatch`
- `collaboration.task_result_collected`

它们分别表示：

- 某个 task 已被派发给 child agent 执行
- 某个 task 的结果已被回收并进入统一状态

这使得 Phase 3 已经从“逻辑隐含”变成“运行时显式可追踪”。

---

## 4. 当前实现对应关系

| 设计目标 | 当前状态 | 落点 |
|------|------|------|
| Parent/root/depth 追踪 | 已实现 | `state.py` + `graph.py` |
| 受限动态创建 | 已实现 | `_create_child_agent`, `_spawn_permission_for_role` |
| 预算快照 | 已实现 | `budget_state`, `collaboration_budget_history` |
| 生命周期事件 | 已实现 | `event_trace`, `schemas/event.py` |
| 中断 / 恢复记录 | 已实现 | `_record_interrupt`, `_record_recovery` |
| phase / checkpoint 显式化 | 已实现 | `state.py`, `graph.py` |
| 独立 EventBus | 未独立落地 | 当前以 `event_trace` 代替 |
| Worker 主动发起新一轮协作 | 未完全开放 | 当前仍以受控主路径为主 |

---

## 5. 与原方案相比的调整

原方案强调：

- 独立 `event_bus.py`
- 独立 `dynamic/`
- 独立 `recovery/`

而当前代码采取的是：

- 先把动态协作基线做到 `graph.py` 内可运行
- 再通过 event_trace / recovery_trace / budget_state 稳定对外暴露
- 最后再决定是否做物理模块拆分

因此文档应调整为：

### 已完成的能力层

- 动态协作并不是未来规划，而是已存在的运行时能力
- 当前已经具备最小治理、最小动态创建、最小恢复机制

### 尚未完成的工程层

- 还没有真正的发布/订阅式 `EventBus`
- 还没有对外开放 worker 自主再委派能力
- 还没有把 dynamic / recovery 拆成单独模块目录

---

## 6. 验收结论

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

- [x] parent / root / depth 可追踪
- [x] child agent 创建行为受预算和权限约束
- [x] spawn blocked 会留下事件证据
- [x] 协作消息与事件链路可重建
- [x] interrupt / recovery 有最小闭环
- [x] phase / checkpoint 已可记录
- [ ] 尚未形成真正的发布订阅 EventBus
- [ ] 尚未开放更自由的 worker→worker 动态协作

---

## 7. 真实边界

当前 Phase 3 的真实状态是：

> Jarvis 已经具备“带约束的动态协作运行时”，但仍不是一个无限扩张、自由重组的 swarm 平台。

这正是当前阶段应该保持的边界：

- 先保证治理
- 再考虑放宽动态能力
- 先保证 trace / verifier / budget 成熟
- 再考虑更强自治