JARVIS/development-doc/plan/agent-update/arvis-agents-2.0-upgrade-plan.md

# Jarvis Agents 2.0 升级方案

日期：2026-04-03
状态：草案
范围：`backend/app/agents/*`、相关测试，以及后续运行时/UI 扩展

---

## 1. 文档目标

本文档用于明确 Jarvis Agents 2.0 的升级方向。方案基于以下三个 demo 项目的分析结果整理而成：

- `demo/swarm-ide-chore-specs-mvp`
- `demo/claude-code-cli-master`
- `demo/claw-code-main`

本方案的目标不是照搬任意一个项目，而是结合它们各自的优点，让 Jarvis 从当前的：

- 静态分层路由型 agent 系统

逐步升级为：

- 可控的动态协作型 agent 运行时

同时保留 Jarvis 现在已经具备的优势：

- 业务导向明确
- 提醒 / 任务 / 搜索类连续性较强
- 支持多 provider 和 fallback 策略
- 运行边界清晰，容易测试和验证

---

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

### 2.1 当前优势

Jarvis 目前已经不是简单的“单 prompt + 工具调用”系统，而是一个结构化的业务 agent 运行时，主要优势包括：

1. **有主控层级**
   - 存在类似 `master` 的顶层入口
   - 已按业务领域拆分出不同 agent / sub-commander

2. **有明确的工具调用策略**
   - 支持 native tool calling
   - 也支持 JSON fallback

3. **有连续性和澄清机制**
   - 支持 clarification
   - 支持 pending action / continuity
   - 对 reminder / task 这类业务很重要

4. **状态模型较完整**
   - 不是纯临时 prompt 拼接
   - 已有显式 state 管理

5. **测试基础较好**
   - 当前 agent runtime 已有可观测试覆盖

### 2.2 当前短板

虽然 Jarvis 已经具备结构化 agent 系统的雏形，但依旧存在几个明显上限：

1. **本质上仍是静态路由系统**
   - 单轮请求通常只会选一条主路径执行
   - agent 关系是预先设计好的，不是运行时动态演化的

2. **没有真正的 agent-to-agent 通信原语**
   - 现在更多是系统内部调度
   - 不是 agent 之间显式发消息、协作、转交任务

3. **没有显式 task/team 运行时**
   - 缺少任务对象、所有权、依赖关系、完成状态

4. **缺少独立 verifier 角色**
   - 当前执行者通常也是完成判断者
   - 缺少“执行”和“验收”分离

5. **可观察性还不够强**
   - 系统内部做了很多判断，但外部很难完整看到 agent 协作过程

---

## 3. 三个 demo 项目的借鉴重点

---

## 3.1 Swarm-IDE：最值得借鉴的协作形态

关键参考文件：

- `demo/swarm-ide-chore-specs-mvp/README.md`
- `demo/swarm-ide-chore-specs-mvp/backend/src/runtime/agent-runtime.ts`
- `demo/swarm-ide-chore-specs-mvp/backend/src/runtime/event-bus.ts`
- `demo/swarm-ide-chore-specs-mvp/backend/src/runtime/skill-loader.ts`

### 值得借鉴的点

#### 1）协作原语非常简单，但表达力非常强
Swarm 的核心原语很少，主要就是：

- 创建 agent
- 发送消息
- 建群 / 群聊
- 列出 agent / 群组 / 消息

这种设计的好处是：

- 不需要先写死很多工作流
- 复杂拓扑可以由运行时自然演化
- agent 行为更像“协作中的人”，而不是固定流程节点

#### 2）agent 间通信是一等能力
Swarm 不是让系统替 agent 决定所有事情，而是让 agent 自己拥有：

- 创建子 agent 的能力
- 和任意 agent 通信的能力
- 组群协作的能力

这比固定的 master -> domain 路由更灵活。

#### 3）人类可以直接介入任意子 agent
这点很关键。多 agent 系统最怕黑箱。一旦用户只能看到最终结果，而看不到中间代理，就很难调试和控制。

#### 4）事件流和可观察性很强
Swarm 有清晰的 runtime 事件模型，例如：

- `agent.wakeup`
- `agent.unread`
- `agent.stream`
- `agent.done`
- `agent.error`

这对后续做：

- 调试
- 可视化
- 事件回放
- 协作审计

都非常有帮助。

### 不能直接照搬的点

Swarm 的自由度也意味着风险：

- agent 无限制增殖
- 消息风暴
- token 成本失控
- 系统行为难收敛

所以 Jarvis 应该借鉴它的“机制”，而不是直接复制它的“无限自由”。

---

## 3.2 Claude Code CLI：最值得借鉴的平台级编排

关键参考文件：

- `demo/claude-code-cli-master/coordinator/coordinatorMode.ts`
- `demo/claude-code-cli-master/bootstrap/state.ts`
- `demo/claude-code-cli-master/skills/bundled/batch.ts`

### 值得借鉴的点

#### 1）coordinator-worker 分层非常清晰
这个项目不是简单地把多个 agent 拼在一起，而是明确区分：

- 协调者 coordinator
- 执行 worker
- 任务生命周期
- 结果汇总
- 后续消息和回收

这正是 Jarvis 从“路由”升级到“编排”时最需要补的能力。

#### 2）有明确的 task / team 概念
成熟的多 agent 系统不是只有“谁去做”，而是还需要：

- task id
- owner
- blocked / depends_on
- 完成状态
- worker 生命周期

#### 3）验证是独立通道
真正成熟的系统会把：

- 计划
- 执行
- 验证

分开，而不是让执行者自己宣布“我完成了”。

#### 4）并行执行强调隔离
对于复杂任务，这种平台会强调：

- 并行 worker
- 各自隔离的工作空间
- 输出清晰归属到某个 worker

这对未来 Jarvis 如果处理更复杂的编码或多步骤任务，价值很高。

---

## 3.3 Claw Code：最值得借鉴的 runtime 工程化能力

关键参考文件：

- `demo/claw-code-main/rust/crates/runtime/src/conversation.rs`
- `demo/claw-code-main/rust/crates/tools/src/lib.rs`
- `demo/claw-code-main/rust/crates/plugins/src/lib.rs`
- `demo/claw-code-main/PARITY.md`

### 值得借鉴的点

#### 1）运行时分层清晰
Claw 的优势不是协作花样最多，而是运行时拆分很自然：

- runtime loop
- tools
- commands
- plugins
- permission

Jarvis 后续也应该逐步减少 graph 与具体业务工具的强耦合。

#### 2）工具注册表可以更强
Jarvis 现在已有 registry 方向，但还不够深入。Claw 的启发是：

每个工具不只是名字和描述，还应该有：

- 权限等级
- 副作用范围
- 是否幂等
- 是否可重试
- 是否适合并行
- 是否需要确认

#### 3）权限模型显式化
一旦系统支持动态协作，就不能默认所有 worker 都能做所有事。

#### 4）插件 / Hook 扩展点应该尽早预留
即使暂时不做插件生态，也应该尽早定义扩展点，否则以后核心 runtime 会越来越难改。

---

## 4. Jarvis 2.0 的总体目标架构

Jarvis 2.0 的目标不是做成“完全自由的蜂群系统”，而是做成：

- **受控的动态协作系统**

### 4.1 核心原则

1. 简单请求继续走当前稳定路径。
2. 复杂请求才进入协作模式。
3. agent 通信必须显式、可观察、可约束。
4. 执行与验证必须分离。
5. 所有危险能力都必须被预算和权限控制。

### 4.2 总体分层

#### 第一层：请求模式选择层
每个请求先判定：

- **直接模式**：继续使用现有 `master -> domain -> sub-commander`
- **协作模式**：进入 coordinator -> task -> delegate -> verify 流程

#### 第二层：协调层
新增 coordinator，负责：

- 理解请求
- 判断是否需要拆任务
- 生成任务列表
- 分配任务给不同角色
- 回收结构化结果
- 触发 verifier

#### 第三层：工作层
worker agent 负责具体执行，例如：

- schedule 执行
- task 执行
- 检索 / 搜索
- forum 操作
- 分析 / 汇总
- 验证 / 审核

#### 第四层：协作底座
底座层应该提供：

- agent 注册
- agent identity
- task 对象
- message channel
- event stream
- budget / interrupt / recovery

---

## 5. Jarvis 2.0 需要新增的核心概念

---

## 5.1 一等的 agent 通信原语

建议在 Jarvis 内部先引入以下运行时能力：

- `create_agent(role, guidance, parent_id?)`
- `send_agent_message(to_agent_id, content, task_id?)`
- `list_agents()`
- `list_agent_threads(agent_id?)`
- `interrupt_agent(agent_id)`

### 作用

这一步完成后，Jarvis 就不再只是“从主图里选路径”，而是具备“让 agent 协作”的基础能力。

### 注意

这些能力可以先作为内部能力，不一定立刻暴露给最终用户。

---

## 5.2 结构化 task 运行时

建议引入任务对象，至少包含：

- `task_id`
- `title`
- `owner_agent_id`
- `status`：`pending` / `in_progress` / `blocked` / `completed` / `failed`
- `depends_on`
- `evidence`
- `result_summary`
- `created_by`

### 作用

一旦 task 成为系统对象，Jarvis 才能真正实现：

- 并行
- 重试
- 显式完成判断
- 进度展示

---

## 5.3 事件总线 Event Bus

建议新增统一事件流，至少包含：

- `agent.created`
- `agent.wakeup`
- `agent.message.sent`
- `agent.message.received`
- `agent.tool.start`
- `agent.tool.result`
- `agent.task.assigned`
- `agent.task.completed`
- `agent.verify.started`
- `agent.verify.completed`
- `agent.error`

### 作用

后续可以用于：

- 调试
- 日志回放
- 可视化
- agent 行为审计

---

## 5.4 verifier 角色

建议新增独立 verifier / reviewer 角色。

### 职责

- 判断是否真的满足用户请求
- 检查是否缺少工具证据
- 识别不完整执行
- 要求重新执行或补充

### 意义

这一步是 Jarvis 从“会调用工具的 assistant”升级为“可靠 agent 系统”的关键一步。

---

## 5.5 工具权限模型

每个工具建议新增如下元数据：

- `permission_class`：`read` / `write` / `external` / `dangerous`
- `side_effect_scope`：`none` / `local_state` / `remote_state`
- `safe_for_worker_roles`
- `requires_confirmation`
- `supports_retry`
- `idempotent`

### 意义

动态协作系统必须比静态路由系统有更强的治理能力。

---

## 6. 按代码区域的演进建议

---

## 6.1 `backend/app/agents/state.py`

### 目标
在现有 state 基础上扩展协作信息，而不是推翻重来。

### 建议新增字段

- `agent_id`
- `parent_agent_id`
- `task_id`
- `active_tasks`
- `task_results`
- `message_queue`
- `event_log_refs`
- `verification_status`
- `execution_mode`：`direct` / `collaboration`
- budget 字段：
  - `max_spawn_depth`
  - `max_child_agents`
  - `max_messages_per_turn`
  - `max_parallel_tasks`

### 重点

不要删除当前 continuity / clarification 相关状态，而是在它之上扩展。

---

## 6.2 `backend/app/agents/graph.py`

### 目标
从“纯路由图”升级为“路由 + 编排混合图”。

### 建议新增节点

- `request_mode_selector`
- `coordinator`
- `task_decomposer`
- `delegation_router`
- `worker_runner`
- `verifier`
- `result_synthesizer`

### 推荐行为

#### 简单请求
继续走当前路径，避免影响当前稳定业务。

#### 复杂请求
走以下流程：

1. coordinator 理解请求
2. task_decomposer 产出小任务列表
3. delegation_router 为每个任务分配角色
4. worker_runner 执行任务
5. verifier 检查产出
6. result_synthesizer 汇总最终结果

### 重点

不是替换当前 graph，而是在复杂请求上增加新的执行分支。

---

## 6.3 `backend/app/agents/prompts.py`

### 目标
新增更明确的角色 prompt，减少职责混乱。

### 需要新增的角色 prompt

- coordinator
- verifier
- critic / reviewer（可后续再加）

### 协调者 prompt 应强调

- 只有复杂任务才拆分
- 任务拆分要小而清晰
- 不要过度创建 agent
- 输出必须带证据

### verifier prompt 应强调

- 不接受模糊完成
- 检查证据是否充分
- 检查用户意图是否真正满足

---

## 6.4 `backend/app/agents/registry/*`

### 目标
让 registry 不只是描述性的，而是逐渐成为 runtime 驱动的一部分。

### 建议补充

- agent role metadata
- role capability
- role spawn permission
- tool access policy
- task suitability tags

### 建议角色分类

- coordinator
- executor
- scheduler
- retriever
- analyst
- verifier

---

## 6.5 `backend/app/agents/tools/*`

### 目标
保留现有业务工具，但为它们补全运行时治理信息。

### 每个工具建议具备的元数据

- `name`
- `description`
- `permission_class`
- `supports_retry`
- `idempotent`
- `safe_for_parallel_use`
- `returns_structured_evidence`

### 建议新增模块

可以新增：

- `backend/app/agents/tools/collaboration.py`

用于承载协作原语，例如：

- 创建 agent
- 发送内部消息
- claim task
- complete task
- request verification

---

# 7. 升级阶段设计

下面按阶段详细说明，每个阶段都包含：

- 目标
- 解决的问题
- 范围
- 核心改动
- 风险
- 验收标准
- 推荐实施顺序

---

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

### 7.1.1 阶段目标

在不破坏当前稳定业务路径的前提下，为后续多 agent 协作打底。

### 7.1.2 这一阶段要解决的问题

当前 Jarvis 的主要问题不是“不会做业务”，而是：

- 缺 verifier
- 缺 task 对象
- 缺事件流
- 缺工具权限元数据
- graph 不区分直接模式和协作模式

所以第一阶段不是追求炫技，而是先把基础设施补齐。

### 7.1.3 范围

主要涉及：

- `backend/app/agents/state.py`
- `backend/app/agents/graph.py`
- `backend/app/agents/prompts.py`
- `backend/app/agents/registry/models.py`
- `backend/app/agents/registry/builtins.py`
- `backend/app/agents/tools/__init__.py`
- `backend/tests/backend/app/agents/*`

### 7.1.4 核心改动

#### 改动 1：新增 `execution_mode`
让系统能区分：

- `direct`
- `collaboration`

#### 改动 2：新增 verifier 角色
在不改变主流程的基础上，先插入一个独立 verifier 角色。

#### 改动 3：新增事件总线抽象
哪怕先不做 UI，也要先定义事件结构和写入方式。

#### 改动 4：补工具元数据
给现有工具补权限、幂等、是否适合并行等信息。

#### 改动 5：引入 task 数据结构
哪怕暂时只在内部使用，也要先把任务结构定义出来。

### 7.1.5 风险点

1. **改 state 容易影响现有测试**
2. **verifier 插入点选错会影响现有行为**
3. **事件系统如果写得太重，会影响性能和复杂度**
4. **工具元数据定义过度，会让现有实现变复杂**

### 7.1.6 验收标准

满足以下条件才算第一阶段完成：

- 当前 reminder / task / search 主要流程测试仍通过
- 系统可以独立运行 verifier 角色
- 系统可以产生基本事件记录
- 工具权限元数据已存在并有测试
- 不引入动态 agent 创建能力

### 7.1.7 推荐实施顺序

1. 定义 task schema
2. 定义 event schema
3. 扩展 state
4. 扩展 tool metadata
5. 加 verifier prompt
6. 在 graph 中插 verifier 分支
7. 补测试

---

## 阶段二：受控协作阶段（Controlled Collaboration）

### 7.2.1 阶段目标

让 Jarvis 开始具备“拆任务、分配任务、回收结果”的能力，但仍然保持强约束。

### 7.2.2 这一阶段要解决的问题

当前系统的主要限制是：

- 复杂请求只能在一条路径里硬做
- 没法显式表达子任务
- 没法让不同角色协作完成复杂目标

第二阶段的重点，就是把“复杂请求”从“路由”升级为“编排”。

### 7.2.3 范围

主要涉及：

- `backend/app/agents/graph.py`
- `backend/app/agents/prompts.py`
- `backend/app/agents/state.py`
- `backend/app/agents/registry/*`
- 新增协作工具模块
- 新增对应测试

### 7.2.4 核心改动

#### 改动 1：新增 coordinator 节点
由 coordinator 判断是否需要拆分请求。

#### 改动 2：新增 task decomposition
复杂请求要能拆出 2~4 个清晰的子任务。

#### 改动 3：新增 worker assignment
不同子任务按角色分配给不同 worker 逻辑。

#### 改动 4：新增内部消息传递
先做最小版本的 agent-to-agent 通信，不必一开始就做复杂群聊。

#### 改动 5：完成后必须走 verifier
worker 的产出不直接作为最终结论，必须先过 verifier。

### 7.2.5 风险点

1. **任务拆得太细会增加系统复杂度**
2. **任务拆得太粗又达不到协作收益**
3. **内部通信如果没有预算，会引发回路**
4. **worker 边界不清会导致职责重叠**

### 7.2.6 验收标准

- 复杂请求可以被拆成 2~4 个子任务
- 每个子任务有明确 owner
- worker 输出带结构化 evidence
- verifier 可以拒绝不完整结果
- final result 基于任务结果汇总，而不是某个单一 worker 的主观结论

### 7.2.7 推荐实施顺序

1. 增加 coordinator prompt
2. 增加 task decomposition schema
3. 增加 delegation router
4. 增加最小通信原语
5. 增加 verifier 回收
6. 补整套协作测试

---

## 阶段三：动态协作阶段（Dynamic Collaboration）

### 7.3.1 阶段目标

在受控前提下，让 Jarvis 具备更接近 Swarm 的动态协作能力，但不是完全放飞。

### 7.3.2 这一阶段要解决的问题

第二阶段虽然已经能做任务拆分，但仍然偏“平台帮你分好工”。

第三阶段要解决的问题是：

- worker 能否在必要时请求新的协作
- 是否支持 parent / child agent 关系
- 是否支持更完整的消息通路
- 是否支持更强的中间态可观察性

### 7.3.3 范围

主要涉及：

- `backend/app/agents/state.py`
- `backend/app/agents/graph.py`
- 新增 collaboration runtime 模块
- 新增 message / thread / event 相关抽象
- 未来可能涉及前端可视化接口

### 7.3.4 核心改动

#### 改动 1：支持 parent / child agent tracking
让系统知道哪个 agent 是谁创建的。

#### 改动 2：支持有限动态创建 agent
注意：必须有限制，不允许无限递归创建。

#### 改动 3：支持有限的 agent 消息线程
先支持最小内部线程即可，不一定马上做群聊 UI。

#### 改动 4：增强事件流
把协作链路完整记录下来。

#### 改动 5：支持 interrupt / recovery
多 agent 系统没有中断与恢复，后面会很难维护。

### 7.3.5 风险点

1. **agent 增殖风险**
2. **消息风暴风险**
3. **token 成本和延迟上升**
4. **调试复杂度上升**
5. **过度动态化破坏当前稳定路径**

### 7.3.6 验收标准

- parent / child agent 关系可追踪
- 系统支持受限动态创建 agent
- agent 间通信链路可记录
- 可中断运行中的协作
- 所有动态协作都受预算限制

### 7.3.7 推荐实施顺序

1. 建 parent / child state
2. 建 spawn budget / message budget
3. 实现受限 `create_agent`
4. 实现内部消息线程
5. 实现 interrupt / recovery
6. 加事件回放和调试日志

---

## 阶段四：可视化与隔离执行阶段（Visibility + Isolation）

### 7.4.1 阶段目标

把多 agent 系统从“后台能跑”升级为“可看、可控、可调试、可隔离”。

### 7.4.2 这一阶段要解决的问题

多 agent 系统发展到一定程度后，纯日志已经不够。你会需要：

- 谁创建了谁
- 谁在做什么
- 谁给谁发了什么
- 哪个任务卡住了
- 某个 agent 为啥没完成

### 7.4.3 范围

这个阶段可能跨：

- backend runtime
- event stream API
- frontend 调试面板 / graph 面板
- 编码任务场景下的隔离执行策略

### 7.4.4 核心改动

#### 改动 1：协作链路可视化
至少包括：

- 当前 agent 列表
- parent / child 关系
- task 状态
- message 流向

#### 改动 2：agent 历史和工具证据可见
支持查看某个 agent：

- 历史消息
- 工具调用
- 工具结果
- verifier 结论

#### 改动 3：隔离执行能力
如果以后 Jarvis 要处理更复杂的 coding 任务，可以考虑：

- worker 级隔离目录
- worktree
- 独立 session state

### 7.4.5 风险点

1. **UI 一旦做太早，会分散后端核心升级精力**
2. **事件量上升后，展示层会有性能压力**
3. **隔离执行会提升工程复杂度**

### 7.4.6 验收标准

- 可以看到基本 agent 拓扑
- 可以看到任务流转和关键事件
- 可以查看某个 agent 的执行证据
- 隔离执行至少有设计方案，最好有最小实现

### 7.4.7 推荐实施顺序

1. 先把 event schema 固化
2. 再做 event stream API
3. 再做最小调试页面
4. 最后做隔离执行策略

---

## 8. 必须长期坚持的治理规则

Jarvis 不应该变成“无限自由蜂群”，而应该是“带预算的动态协作系统”。

因此必须长期保留这些约束：

1. **spawn budget**：每次请求最多允许创建多少 agent
2. **message budget**：每个任务 / 每轮最多允许多少消息
3. **max depth**：代理树最大深度
4. **verifier gate**：复杂任务必须经 verifier 才能宣布完成
5. **tool permission policy**：不同角色拥有不同工具权限
6. **interrupt / cancel 路径**：长任务必须可中断
7. **structured evidence**：没有证据就不算完成

---

## 9. 推荐优先级

如果近期只能做少量升级，推荐优先级如下：

1. verifier 角色
2. event bus / 可观察性
3. 结构化 task runtime
4. coordinator for complex requests
5. 内部 agent 通信原语
6. registry 元数据增强
7. 隔离执行能力

---

## 10. 最现实的近期落地顺序

建议按下面顺序推进，而不是同时铺开：

### 第一步
先做 verifier 的 state、prompt、graph 插入点设计。

### 第二步
定义 task schema 和 event schema。

### 第三步
给工具补元数据和权限标签。

### 第四步
在 graph 中加入 coordinator 只处理复杂请求。

### 第五步
引入最小可用的内部协作原语。

### 第六步
补一轮完整测试，确保旧路径不坏、新路径可控。

---

## 11. 最终建议

Jarvis 2.0 不应该单独模仿某一个 demo，而应该做这样的融合：

- 从 **Swarm-IDE** 学：动态通信原语、可观察性、协作拓扑
- 从 **Claude Code CLI** 学：coordinator / task / verifier 的平台化编排
- 从 **Claw Code** 学：runtime 分层、工具注册表、权限模型

一句话总结升级方向：

> 让 Jarvis 从“静态层级路由系统”升级为“受控的动态协作运行时”。

并且必须坚持一个原则：

> 简单请求保持当前稳定路径，复杂请求才启用协作编排能力。

---

## 12. 建议后续继续拆分的文档

建议在这份总方案之后，再继续补这些中文文档：

1. `development-doc/jarvis-agents-phase-a-design.md`
2. `development-doc/jarvis-agent-event-schema.md`
3. `development-doc/jarvis-agent-task-schema.md`
4. `development-doc/jarvis-agent-role-permissions.md`
5. `development-doc/jarvis-verifier-integration-plan.md`

如果继续往下做，最建议先写的是：

- **Phase A 详细设计文档**

因为它最贴近当前代码，也最容易直接转成开发任务。