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 可以按“已落地”验收：

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

---

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

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

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

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