# Jarvis Agents 升级计划索引

本目录用于存放 Jarvis Agents 2.0 的分阶段规划文档，同时也用于记录**当前代码真实落地状态**。

## 文档说明

| 文件 | 说明 |
|------|------|
| `README.md` | 总览、阶段关系、实施顺序、当前状态 |
| `phase-0-current-state-and-target.md` | 当前现状、问题、目标架构、ADR |
| `phase-1-safe-foundation.md` | 基础设施加固阶段 |
| `phase-2-controlled-collaboration.md` | 受控协作阶段 |
| `phase-3-dynamic-collaboration.md` | 动态协作阶段 |
| `phase-4-visibility-and-isolation.md` | 可视化与隔离执行阶段 |
| `phase-5-advanced-features.md` | 高级特性(可选) |
| `phase-6-tool-system-refactoring.md` | 工具系统重构 |
| `phase-7-hook-interception-layer.md` | Hook 拦截层 |
| `phase-8-plugin-ecosystem.md` | 插件生态 |
| `phase-9-skills-registry.md` | Skills 注册表 |
| `phase-10-advanced-orchestration.md` | 高级编排 |
| `phase-r-rag-upgrade.md` | RAG 系统升级专项(VCPToolBox 借鉴) |

---

## 当前总体状态（2026-04-04）

当前 Jarvis agent runtime 不再是“Phase 2/3/4 纯草案”，而是已经具备以下现实状态：

### 78 → 90 成熟度标尺

| 分数 | 含义 | 当前状态 |
|------|------|----------|
| 75 | 受控协作基线：task/event/verifier/collaboration/dynamic guardrail 已稳定 | 已达到 |
| 85 | visibility + verification 基线：phase/checkpoint、topology、evidence、runtime summary、operator 调试入口可用 | 基本达到 |
| 90 | isolation runtime + cost governance + operator surface：会话/工作区隔离、成本阈值治理、前端可运营面板闭环 | 已达到 |
| 95+ | full sandbox / persistence / realtime UI / advanced memory | 明确延后 |

| Phase | 当前状态 | 说明 |
|------|------|------|
| Phase 1 | 已落地 | verifier、task/event schema、基础执行模式已存在 |
| Phase 2 | 已实现基线 | collaboration mode、task decomposition、owner、result collection、verifier 收尾已运行 |
| Phase 3 | 已实现受限基线 | parent/root/depth、spawn policy、budget、interrupt/recovery、事件链路已存在 |
| Phase 4 | 已完成 90 分闭环 | visibility API、isolation runtime MVP、cost governance MVP、operator/debug surface 已落地 |
| Phase 5 | 未开始 | 保留为 full sandbox / persistence / realtime push 等可选增强 |
| Phase 6 | 待开始 | 工具系统重构（对标 claw-code） |
| Phase 7 | 待开始 | Hook 拦截层 |
| Phase 8 | 待开始 | 插件生态 |
| Phase 9 | 待开始 | Skills 注册表 |
| Phase 10 | 待开始 | 高级编排 |
| Phase R | 部分推进 | RAG 升级按专项继续推进 |

### 本次新增落地

本次补齐了一个此前缺失但非常关键的层：

- runtime 显式 phase model
- runtime checkpoint model
- phase / checkpoint history 持久化
- phase / checkpoint event trace
- 对应自动化测试

新增后，当前 runtime 已可显式追踪：

- `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`

---

## 推荐阅读顺序

1. 先读 `phase-0-current-state-and-target.md`
2. 再读 `phase-2-controlled-collaboration.md`
3. 再读 `phase-3-dynamic-collaboration.md`
4. 最后读 `phase-4-visibility-and-isolation.md`

原因：当前最重要的不是继续写理想化蓝图，而是先理解“代码里已经实现到了哪一步”。

---

## 总体升级原则

1. **保持简单请求路径稳定** - Direct Mode 不受影响
2. **复杂请求才启用协作模式** - Collaboration Mode 按需触发
3. **执行与验证分离** - Verifier 作为独立角色
4. **动态能力必须受约束** - Budget + Permission + Depth
5. **所有升级都要配套测试** - 回归测试优先
6. **优先做显式状态，不先做大拆分** - 先让运行时可观察、可验证，再抽模块

---

## 阶段关系图（按真实状态修订）

```text
Phase 0 ──────────────────────────────────────────────────────────────┐
│ 现状与目标                                                           │
│ - 当前架构分析                                                        │
│ - Demo 借鉴映射                                                      │
│ - ADR 架构决策                                                       │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
Phase 1 ──────────────────────────────────────────────────────────────┐
│ 基础设施加固 (Safe Foundation)                                        │
│ - verifier / schema / execution mode 基础                            │
│ 状态：已落地                                                          │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
Phase 2 ──────────────────────────────────────────────────────────────┐
│ 受控协作 (Controlled Collaboration)                                   │
│ - collaboration mode                                                 │
│ - 任务拆解 / owner / 结果回收 / verifier                              │
│ - 当前已补 phase + checkpoint                                         │
│ 状态：已实现基线                                                      │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
Phase 3 ──────────────────────────────────────────────────────────────┐
│ 动态协作 (Dynamic Collaboration)                                      │
│ - parent/root/depth tracking                                         │
│ - spawn policy + budget                                              │
│ - interrupt/recovery                                                 │
│ - phase + checkpoint trace                                           │
│ 状态：已实现受限基线                                                  │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
Phase 4 ──────────────────────────────────────────────────────────────┐
│ 可视化与隔离 (Visibility + Isolation)                                 │
│ - visibility 查询 API                                                 │
│ - continuity snapshot 持久化                                          │
│ - isolation strategy 设计                                             │
│ 状态：最小闭环已完成                                                  │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
Phase 5 ──────────────────────────────────────────────────────────────┐
│ 高级特性 (Advanced Features)                                          │
│ - full sandbox / persistence / cost monitoring / advanced UI         │
│ 状态：规划中，可选                                                    │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
Phase 6 ──────────────────────────────────────────────────────────────┐
│ 工具系统重构 (Tool System Refactoring)                                 │
│ - ToolRegistry / HookExecutor / StreamingToolExecutor                 │
│ - 新增工具集：Glob/Grep/LSP/Bash/PowerShell/Cron                     │
│ 状态：待开始（对标 claw-code tools/）                                 │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
Phase 7 ──────────────────────────────────────────────────────────────┐
│ Hook 拦截层 (Hook Interception Layer)                                 │
│ - PreTool/PostTool Hook 机制                                         │
│ - 危险操作确认 / 安全扫描 / 审计日志                                   │
│ 状态：待开始（依赖 Phase 6）                                          │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
Phase 8 ──────────────────────────────────────────────────────────────┐
│ 插件生态 (Plugin Ecosystem)                                           │
│ - PluginManager / 生命周期管理 / 插件市场                             │
│ 状态：待开始（依赖 Phase 6, 7）                                       │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
Phase 9 ──────────────────────────────────────────────────────────────┐
│ Skills 注册表 (Skills Registry)                                       │
│ - 动态 Skills 加载 / MCP Skill Builder / Bundled Skills               │
│ 状态：待开始（依赖 Phase 6）                                          │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
Phase 10 ─────────────────────────────────────────────────────────────┐
│ 高级编排 (Advanced Orchestration)                                      │
│ - Team Leader / Remote Transport / Session Manager / Background Tasks  │
│ 状态：待开始（对标 claw-code assistant/）                             │
└────────────────────────────────────────────────────────────────────┘
```

---

## Demo 项目借鉴映射

| Demo项目 | 主要借鉴点 | 对应 Phase |
|---------|-----------|-----------|
| **Swarm-IDE** | Event trace、Dynamic Spawn、拓扑可视化 | Phase 3, 4 |
| **Claude Code CLI** | Coordinator-worker、Verifier 分离、Tool 权限 | Phase 1, 2 |
| **Claw Code** | Runtime 分层、Port Manifest、隔离策略 | Phase 2, 4, 6, 7, 8, 9, 10 |
| **VCPToolBox** | TagMemo V6、多索引、Token 感知分块 | Phase R, Phase 5 |

### Claw Code 详细对照

| Claw Code 组件 | Jarvis Phase | 说明 |
|----------------|-------------|------|
| `tools/` | Phase 6 | 工具注册表、分层执行 |
| `StreamingToolExecutor` | Phase 6 | 流式工具执行 |
| `toolHooks.ts` | Phase 7 | Hook 拦截层 |
| `PluginLifecycle` | Phase 8 | 插件生态 |
| `skills/loadSkillsDir.ts` | Phase 9 | Skills 注册表 |
| `skills/bundledSkills.ts` | Phase 9 | Bundled Skills |
| `assistant/sessionHistory.ts` | Phase 10 | 高级会话管理 |
| `cli/structuredIO.ts` | Phase 10 | 结构化传输 |
| `cli/remoteIO.ts` | Phase 10 | 远程传输 |

---

## 本次代码落点

本次 phase/checkpoint 补强主要修改：

- `backend/app/agents/state.py`
- `backend/app/agents/graph.py`
- `backend/app/agents/schemas/event.py`
- `backend/app/services/agent_service.py`
- `backend/tests/backend/app/agents/test_graph.py`
- `backend/tests/backend/app/services/test_brain_ingestion.py`

### 新增的关键事件

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

### 新增的关键持久化字段

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

---

## 当前仍未完成的内容

虽然能力已经明显前进，但下面这些仍属于后续工作：

### 工程结构层

- 独立 `coordinator.py`
- 独立 `message_bus.py`
- 独立 `event_bus.py`
- `dynamic/` 与 `recovery/` 目录化拆分

### Claw Code 差距（Phase 6-10）

- Phase 6: 工具系统重构（ToolRegistry/HookExecutor/StreamingToolExecutor）
- Phase 7: Hook 拦截层（PreTool/PostTool）
- Phase 8: 插件生态（PluginManager/生命周期/市场）
- Phase 9: Skills 注册表（动态加载/MCP Builder）
- Phase 10: 高级编排（Team/Remote Transport/Session Manager）

### 平台能力层

- full sandbox / persistence / realtime push
- 独立 `coordinator.py` / `message_bus.py` / `event_bus.py`
- 更完整的 operator drilldown 与实时推送
- SSE / WebSocket 实时推送（延后）
- sandbox container 执行器（延后）

---

## 当前阶段结论

目前最准确的说法不是：

> “Jarvis 还在做 agent phase 规划。”

而是：

> “Jarvis 已经具备多阶段 agent runtime 的核心基线，当前工作重点已经从‘是否可行’转向‘如何把已存在能力继续工程化、可视化、隔离化’。”

这也是后续测试、验收和继续升级的正确前提。