# Phase 0：当前现状与目标架构

日期：2026-04-03
状态：已更新

---

## 1. 本阶段目的

本文件不涉及具体代码实施，而是用于统一背景认知，明确：

- Jarvis 当前 agent 架构处于什么水平
- 主要短板是什么
- 为什么要升级
- 升级后的目标形态是什么
- 三个 demo 项目分别给我们什么启发
- 关键架构决策记录(ADR)

---

## 2. 当前 Jarvis 架构现状

当前核心代码集中在：

- `backend/app/agents/graph.py`
- `backend/app/agents/state.py`
- `backend/app/agents/prompts.py`
- `backend/app/agents/registry/*`
- `backend/app/agents/tools/*`
- `backend/tests/backend/app/agents/test_graph.py`

### 当前架构精确描述

```
┌─────────────────────────────────────────────────────────────┐
│                        Master Node                          │
│                   (意图识别 + 路由分发)                      │
└─────────────────┬───────────────────────────────────────────┘
                  │
        ┌─────────┴─────────┬───────────┬───────────┬─────────┐
        ▼                   ▼           ▼           ▼         │
   Schedule_Planner    Executor     Librarian   Analyst      │
   (规划分析)         (执行操作)    (知识检索)   (数据分析)   │
        │                   │           │           │         │
        └───────────────────┴───────────┴───────────┴─────────┘
                                │
                    ┌───────────┴───────────┐
                    │    Tool Executor      │
                    │   (统一工具执行层)     │
                    └───────────────────────┘
```

### 当前优势

1. ✅ LangGraph状态机结构清晰
2. ✅ 已有Master + 4个角色(sub_commander)的层级设计
3. ✅ 支持native tool calling与fallback
4. ✅ 有continuity / clarification / pending action机制
5. ✅ ReAct模式(思考→行动→观察循环)
6. ✅ 有一定测试基础
7. ✅ 流式输出支持

### 当前短板

> 注意：下面列的是**相对目标架构仍然不足的部分**，不是说这些能力完全不存在。

| 短板 | 严重程度 | 当前真实状态 |
|------|----------|------|
| Agent间直接通信原语仍不独立 | 🔴 高 | 当前以 `message_trace` / coordinator 主路径为主，尚未独立 MessageBus |
| worker 自主再委派能力仍受限 | 🔴 高 | 已有受控 spawn，但不是自由 swarm |
| EventBus / Coordinator 仍未工程拆分 | 🟡 中 | 能力在 `graph.py` 内可运行，但模块边界仍偏集中 |
| 可观察性仍缺少实时推送与前端面板 | 🟡 中 | 已有 event/phase/checkpoint/visibility API，尚无完整实时 UI |
| 隔离执行仍未完整落地 | 🟡 中 | isolation strategy 已设计，worktree / sandbox runtime 未完成 |
| 工具治理仍可继续细化 | 🟢 低 | 已有基础 metadata 与权限语义，但尚未到完整产品化治理 |

---

## 3. 为什么需要升级

如果 Jarvis 继续只依赖当前静态路由架构，会遇到以下问题：

1. **复杂请求只能硬塞进单路径执行** → 可靠性低
2. **无法优雅地拆分和回收多步任务** → 只能串行处理
3. **执行与验收耦合** → 工具失败可能被误报为成功
4. **系统内部过程不透明** → 后续难调试
5. **无法支持真实的多Agent协作** → 协作能力上限低

---

## 4. 四个 Demo 的启发总结

### 4.1 Swarm-IDE 给我们的启发

**重点学习**：

| Swarm-IDE特性 | 我们的借鉴点 | 实现位置 |
|--------------|-------------|----------|
| `create`/`send` 协作原语 | 定义Agent通信接口 | Phase 2 |
| Agent间通信作为一等能力 | MessageBus设计 | Phase 2 |
| 人类可以直接介入sub-agent | 调试/干预能力 | Phase 4 |
| Runtime event bus | 统一事件流 | Phase 3 |
| WeChat式群聊模式 | Agent群组通信 | Phase 3+ |
| 实时拓扑可视化 | 可视化调试面板 | Phase 4 |

**核心文件参考**：`swarm-ide-chore-specs-mvp/backend/src/runtime/agent-runtime.ts`

### 4.2 Claude Code CLI 给我们的启发

**重点学习**：

| Claude Code CLI特性 | 我们的借鉴点 | 实现位置 |
|-------------------|-------------|----------|
| Coordinator-worker编排模式 | Phase 2的coordinator | Phase 2 |
| Task/team生命周期管理 | Task schema + lifecycle | Phase 1 |
| 计划-执行-验证分离 | Verifier独立角色 | Phase 1 |
| 并行执行时的隔离策略 | 预算控制 | Phase 3 |
| 工具注册与权限控制 | Tool metadata | Phase 1 |

**核心文件参考**：`claude-code-cli-master/src/tools.ts`

### 4.3 Claw Code 给我们的启发

**重点学习**：

| Claw Code特性 | 我们的借鉴点 | 实现位置 |
|-------------|-------------|----------|
| Runtime分层 | 抽象runtime接口 | Phase 3 |
| Port manifest模式 | 子系统边界定义 | Phase 2 |
| 显式权限模型 | Tool permission_class | Phase 1 |
| Plugin/hook扩展点 | Registry扩展机制 | Phase 3 |

**核心文件参考**：`claw-code-main/src/port_manifest.py`

### 4.4 VCPToolBox 给我们的启发

**重点学习**：

| VCPToolBox特性 | 我们的借鉴点 | 实现位置 |
|-------------|-------------|----------|
| VCP协议 | 模型无关的工具调用格式 | Phase 2 |
| 6类型插件系统 | Tool类型分类(SYNC/ASYNC/SERVICE) | Phase 1 |
| TagMemo记忆 | 仿生遗忘曲线 + 重要性权重 | Phase 5 |
| AgentDream | AI睡眠时整理记忆 | Phase 5 |
| 分布式架构 | WebSocket星型网络 | Phase 6+ |

**VCPToolBox核心概念**：

1. **VCP协议** — 文本格式工具调用协议
   ```
   <<<[TOOL_REQUEST]>>>
   tool_name:「始」VSearch「末」,
   SearchTopic:「始」AI医疗诊断「末」
   <<<[END_TOOL_REQUEST]>>>
   ```
   - 使用中文分隔符「始」「末」
   - 支持 `archery:no_reply`（异步）、`river:full`（上下文注入）

2. **TagMemo记忆系统** — 仿生RAG
   - LIF神经元模型：脉冲传播机制
   - Core Tags：核心记忆1.2-1.4x权重加成
   - 遗忘曲线：不是无限存储，模拟生物遗忘

3. **6类型插件**：
   - `static`：占位符
   - `messagePreprocessor`：消息预处理
   - `synchronous`：同步stdio
   - `asynchronous`：异步回调
   - `service`：后台服务
   - `hybridservice`：混合模式

4. **AgentDream** — 仿生梦境系统
   - 0-7天：近期记忆，高频共振
   - 7-90天：中期记忆，弱共振
   - >90天：长期记忆，遗忘边界

**核心文件参考**：
- `demo/VCPToolBox-main/Plugin.js`
- `demo/VCPToolBox-main/KnowledgeBaseManager.js`
- `demo/VCPToolBox-main/modules/messageProcessor.js`

---

## 5. 关键架构决策记录(ADR)

### ADR-001: 为什么选择LangGraph？

**决策**：继续使用LangGraph作为状态机基础

**理由**：
- ✅ 当前已有投入，结构清晰
- ✅ 状态转移显式化，易于调试
- ✅ 支持conditional edge，可做路由
- ✅ 与LangChain生态集成良好

**替代方案考虑**：
- 自研状态机：维护成本高，不值得
- Swarm-IDE模式：过度动态，缺少可预测性
- Actor模型：引入复杂度高，收益不明显

### ADR-002: 为什么用sub_commander而非独立Agent？

**决策**：保持当前Master+sub_commander模式，不做完全独立的Agent进程

**理由**：
- ✅ 同一进程内共享上下文，开销低
- ✅ 状态传递简单直接
- ✅ 与现有LangGraph集成自然
- ✅ 更易保证事务性

**未来可选演进**：
- 复杂任务可用worktree隔离（Phase 4）
- 但默认仍是sub_commander模式

### ADR-003: 为什么先不做无限动态swarm？

**决策**：所有动态能力必须受控，不追求"无限自由"

**理由**：
- ❌ 无限动态 → token成本不可控
- ❌ 无限动态 → 调试困难
- ❌ 无限动态 → 行为不可预测

**设计原则**：
- 简单请求走direct路径（当前稳定模式）
- 复杂请求进collaboration模式（有预算约束）
- 动态spawn有深度/数量/角色限制

### ADR-004: Event Schema设计选择

**决策**：Phase 1只做内存trace，不做持久化

**理由**：
- ✅ 快速迭代，不用关心数据库schema
- ✅ 测试容易断言
- ✅ Phase 4再做SSE/持久化

**未来演进**：
- Phase 4: SSE流式推送
- Phase 5+: 可选数据库持久化

---

## 6. 目标架构

Jarvis 2.0 的目标是：

> 从静态层级路由系统，升级为**受控的动态协作运行时**。

### 目标架构预览

```
┌─────────────────────────────────────────────────────────────┐
│                      User Request                           │
└─────────────────────────┬───────────────────────────────────┘
                          │
              ┌───────────┴───────────┐
              │   Execution Mode      │
              │   Router (新增)       │
              └───────────┬───────────┘
                          │
        ┌─────────────────┴─────────────────┐
        ▼                                   ▼
   ┌─────────┐                      ┌──────────────┐
   │ Direct  │                      │ Collaboration│
   │  Mode   │                      │    Mode      │
   │(当前路径)│                      │  (Phase 2+)  │
   └────┬────┘                      └──────┬───────┘
        │                                  │
        ▼                                  ▼
   ┌─────────┐                    ┌──────────────────┐
   │  Master │                    │    Coordinator   │
   │   Node  │                    │   (新增)         │
   └────┬────┘                    └────────┬─────────┘
        │                                  │
        ▼                                  ▼
   ┌─────────┐                    ┌──────────────────┐
   │   Sub   │◄──────────────────►│    MessageBus    │
   │Commanders│                    │   (新增)         │
   └────┬────┘                    └────────┬─────────┘
        │                                  │
        │         ┌────────────────────────┤
        │         │                        │
        ▼         ▼                        ▼
   ┌─────────┐ ┌─────────┐          ┌───────────┐
   │  Tools  │ │ Verifier│          │  Workers  │
   │ Executor│ │(独立角色)│          │ (动态创建) │
   └─────────┘ └─────────┘          └───────────┘
```

### 升级后的基本原则

1. **简单请求继续走当前稳定路径(direct mode)**
2. **复杂请求才进入协作模式(collaboration mode)**
3. **执行与验证分离(Verifier独立)**
4. **动态能力必须有预算限制(spawn/message/depth budget)**
5. **工具能力必须有权限约束(permission_class)**
6. **全程要有可观察事件流(event trace)**

---

## 7. 总体分阶段策略

| Phase | 名称 | 核心目标 | 关键产出 |
|-------|------|----------|----------|
| Phase 1 | 基础设施加固 | 补底座，打基础 | Verifier, Task/Event Schema, Tool Metadata |
| Phase 2 | 受控协作 | 结构化任务编排 | Coordinator, MessageBus, Task Decomposition |
| Phase 3 | 动态协作 | 受限动态能力 | Dynamic Spawn, Thread Model, Interrupt/Recovery |
| Phase 4 | 可视化与隔离 | 可调试，可控制 | Event Stream API, Topology UI, Isolation Strategy |
| Phase 5 | 高级特性(可选) | 产品化能力 | Sandbox, Full UI, Persistence |

---

## 8. 本阶段产出要求

本阶段完成标准：

- [x] 团队对 Jarvis 当前问题和目标方向达成一致
- [x] 关键架构决策已记录
- [x] Demo借鉴点已映射到具体Phase
- [x] 后续 phase 文档能够在这个认知基础上展开
- [x] 不直接在本阶段进行代码改造

