JARVIS/development-doc/plan/agent-update/phase-1-safe-foundation.md

# Phase 1：基础设施加固阶段（Safe Foundation）

日期：2026-04-03
状态：已落地，进入增量加固

---

## 1. 阶段目标

在不破坏当前稳定业务路径的前提下，为后续多 agent 协作补齐基础设施。

这一阶段**不追求动态 swarm，不追求并行炫技**，重点是：

- 打基础
- 控风险
- 不破坏当前功能

当前代码已经完成这条基础线：

- execution mode 已存在，Direct / Collaboration 已可区分
- verifier 收尾逻辑已存在，并参与协作结果验收
- task schema / event schema 已进入运行时
- graph 已具备可验证、可追踪、可持续增强的基础骨架

---

## 2. Demo借鉴映射

| 本Phase改动 | 借鉴来源 | 具体参考点 |
|------------|----------|-----------|
| Tool Metadata | Claude Code CLI | `tools.ts` - JSON Schema验证 + permission控制 |
| Tool 类型分类 | VCPToolBox | 6类型插件系统(SYNC/ASYNC/SERVICE) |
| Event Schema | Swarm-IDE | `event-bus.ts` - 统一事件格式 |
| Task Schema | Claude Code CLI | Task/team生命周期管理 |
| Verifier角色 | Claude Code CLI | 计划-执行-验证分离模式 |

---

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

当前 Jarvis 已经在 `backend/app/agents/graph.py`、`backend/app/agents/state.py` 与相关 schema 中完成了 Phase 1 的基础闭环。

### 3.1 Execution mode 与基础运行态

当前已具备：

- `execution_mode` 区分 `direct` 与 `collaboration`
- `master_node()` 可根据请求复杂度切换主路径
- `initial_state()` 已兼容这些字段的默认值

这意味着 Phase 1 不再只是“给 Phase 2 预留接口”，而是已经成为实际运行时入口的一部分。

### 3.2 Verifier 收尾基线

当前已具备：

- `_verify_collaboration_results()` 负责对协作结果做统一验收
- `verification_status`
- `verification_summary`
- `verification_evidence`

说明执行与验收已经形成最小分离，而不是完全耦合在执行流内部。

### 3.3 Task Schema 已落地

当前 state 与协作链路已围绕结构化 task 信息运行，包括：

- `task_id`
- `role`
- `owner_agent_id`
- `goal`
- `expected_evidence`
- `task_results`
- `task_hierarchy`
- `active_tasks`

这已经满足 Phase 1 “统一任务结构、可供 verifier 读取”的核心目标。

### 3.4 Event Schema 已落地

当前已具备统一事件模型，并用于 `event_trace`。事件类型已覆盖：

- tool / message / spawn / interrupt / recovery 相关事件
- `agent.phase.changed`
- `agent.checkpoint.recorded`
- `agent.error`

因此当前系统已经不是“没有统一 event schema”，而是已经进入“事件类型可继续扩展”的状态。

### 3.5 显式 phase / checkpoint 已补齐

在此前基础之上，本次又补齐了：

- `current_phase`
- `phase_history`
- `current_checkpoint`
- `checkpoint_history`

并在运行时中显式记录：

- `phase_0_bootstrap`
- `phase_1_routing`
- `phase_2_controlled_collaboration`
- `phase_3_dynamic_collaboration`
- `phase_4_visibility_and_verification`

以及关键 checkpoint，例如：

- `bootstrap.initialized`
- `routing.master_entered`
- `collaboration.tasks_planning`
- `collaboration.tasks_ready`
- `collaboration.task_dispatch`
- `collaboration.task_result_collected`
- `collaboration.verification_started`
- `collaboration.completed`

这意味着 Phase 1 的“可观察基础”已经不只是事件 trace，还进一步升级成了显式阶段模型。

---

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

| 设计目标 | 当前状态 | 落点 |
|------|------|------|
| Execution mode 基础分流 | 已实现 | `state.py`, `graph.py` |
| Verifier 收尾基线 | 已实现 | `_verify_collaboration_results` |
| Task Schema 基线 | 已实现 | `state.py`, `graph.py` |
| Event Schema 基线 | 已实现 | `schemas/event.py`, `event_trace` |
| Tool Metadata 基础治理 | 已实现基线 | `registry/models.py`, `registry/builtins.py` |
| Phase / Checkpoint 显式化 | 已实现 | `state.py`, `graph.py`, `agent_service.py` |

---

## 5. 本阶段核心改动与后续边界

Phase 1 现在更准确的定义不是“准备做什么”，而是“哪些基础能力已经稳定存在，哪些还要继续工程化”。

### 5.1 已经完成的核心底座

当前已经完成：

- execution mode 基础分流
- verifier 收尾基线
- task / result / evidence 结构化承载
- event schema 与 `event_trace`
- tool metadata 基础治理
- phase / checkpoint 显式建模
- continuity snapshot 持久化与恢复
- 对应自动化测试

### 5.2 这一阶段仍然保持的边界

Phase 1 仍然不等于完整多 agent 平台。它没有承诺：

- 独立 coordinator 模块
- 独立 message bus 模块
- 自由 worker-to-worker 协作
- 完整 sandbox / worktree 执行器
- 前端实时调试面板

这些内容属于 Phase 2 以后逐步增强的工程层，不影响 Phase 1 已经完成验收。

### 5.3 测试与持久化现状

当前已覆盖的关键验证包括：

- 初始 phase / checkpoint 默认值
- phase 切换与 checkpoint 记录行为
- collaboration flow 下的 phase / checkpoint 演进
- fallback 回 direct 路径时的 checkpoint 恢复
- continuity snapshot roundtrip 保留 phase / checkpoint 历史

因此当前不是“概念设计”，而是已经具备回归保护的运行时能力。

---

## 6. 风险点

| 风险 | 当前状态 / 缓解措施 |
|------|----------|
| 运行时逻辑集中在 `graph.py` | 当前可运行，但后续应继续拆分 coordinator / bus / recovery 模块 |
| visibility 已有基线但缺少实时化 | 后续通过 SSE / WebSocket / UI 面板增强 |
| 动态协作仍受严格治理 | 这是当前有意保留的边界，不是缺陷 |
| tool metadata 仍可继续细化 | 后续再补强更细粒度治理即可 |

---

## 7. 当前验收结论

当前 Phase 1 可以按“已落地”验收：

- [x] `state.py` 已承载 direct / collaboration 基础字段
- [x] verifier 已参与关键结果验收
- [x] task schema / event schema 已有代码落点
- [x] builtin tools 已具备基础 metadata 语义
- [x] graph 主流程已有回归测试保护
- [x] phase / checkpoint 已进入显式运行时模型
- [x] continuity snapshot 已可持久化这些状态
- [ ] 尚未完成进一步工程拆分与实时平台化

---

## 8. 本阶段完成后真实结果

完成 Phase 1 之后，Jarvis 已经不只是“单路由 agent”。它已经具备：

- ✅ 稳定 direct 路径
- ✅ 复杂请求切换到 collaboration 的入口基础
- ✅ 结构化任务与结果回收底座
- ✅ verifier 验收机制
- ✅ 统一事件记录与阶段追踪
- ✅ continuity 状态延续能力

**结论：Phase 1 已不是草案，而是 Jarvis 当前多阶段 runtime 的已落地基础层。**