# 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] 不直接在本阶段进行代码改造