Files

WIN-JHFT4D3SIVT\caoxiaozhu a3fe4d24fc feat(agents): Phase 7-10 hook system, plugins, skills, orchestration

Phase 7: Built-in Hooks (audit_log, dangerous_confirmation, security_scan)
Phase 8: Plugin system (PluginManager, PluginSandbox, PluginManifest)
Phase 9: Skills registry (SkillRegistry, local/plugin/MCP loaders)
Phase 10: TeamLeader, RemoteTransport, BackgroundTaskManager

2026-04-04 22:56:27 +08:00

22 KiB

Raw Permalink Blame History

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 运行时，主要优势包括：

有主控层级
- 存在类似 master 的顶层入口
- 已按业务领域拆分出不同 agent / sub-commander
有明确的工具调用策略
- 支持 native tool calling
- 也支持 JSON fallback
有连续性和澄清机制
- 支持 clarification
- 支持 pending action / continuity
- 对 reminder / task 这类业务很重要
状态模型较完整
- 不是纯临时 prompt 拼接
- 已有显式 state 管理
测试基础较好
- 当前 agent runtime 已有可观测试覆盖

2.2 当前短板

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

本质上仍是静态路由系统
- 单轮请求通常只会选一条主路径执行
- agent 关系是预先设计好的，不是运行时动态演化的
没有真正的 agent-to-agent 通信原语
- 现在更多是系统内部调度
- 不是 agent 之间显式发消息、协作、转交任务
没有显式 task/team 运行时
- 缺少任务对象、所有权、依赖关系、完成状态
缺少独立 verifier 角色
- 当前执行者通常也是完成判断者
- 缺少“执行”和“验收”分离
可观察性还不够强
- 系统内部做了很多判断，但外部很难完整看到 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 核心原则

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

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

重点

不是替换当前 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 风险点

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

7.1.6 验收标准

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

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

7.1.7 推荐实施顺序

定义 task schema
定义 event schema
扩展 state
扩展 tool metadata
加 verifier prompt
在 graph 中插 verifier 分支
补测试

阶段二：受控协作阶段（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 风险点

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

7.2.6 验收标准

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

7.2.7 推荐实施顺序

增加 coordinator prompt
增加 task decomposition schema
增加 delegation router
增加最小通信原语
增加 verifier 回收
补整套协作测试

阶段三：动态协作阶段（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 风险点

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

7.3.6 验收标准

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

7.3.7 推荐实施顺序

建 parent / child state
建 spawn budget / message budget
实现受限 create_agent
实现内部消息线程
实现 interrupt / recovery
加事件回放和调试日志

阶段四：可视化与隔离执行阶段（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 风险点

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

7.4.6 验收标准

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

7.4.7 推荐实施顺序

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

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

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

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

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

9. 推荐优先级

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

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

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. 建议后续继续拆分的文档

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

development-doc/jarvis-agents-phase-a-design.md
development-doc/jarvis-agent-event-schema.md
development-doc/jarvis-agent-task-schema.md
development-doc/jarvis-agent-role-permissions.md
development-doc/jarvis-verifier-integration-plan.md

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

Phase A 详细设计文档

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

22 KiB Raw Permalink Blame History Unescape Escape

Jarvis Agents 2.0 升级方案

1. 文档目标

2. 当前 Jarvis 的现状

2.1 当前优势

2.2 当前短板

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

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

值得借鉴的点

1）协作原语非常简单，但表达力非常强

2）agent 间通信是一等能力

3）人类可以直接介入任意子 agent

4）事件流和可观察性很强

不能直接照搬的点

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

值得借鉴的点

1）coordinator-worker 分层非常清晰

2）有明确的 task / team 概念

3）验证是独立通道

4）并行执行强调隔离

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

值得借鉴的点

1）运行时分层清晰

2）工具注册表可以更强

3）权限模型显式化

4）插件 / Hook 扩展点应该尽早预留

4. Jarvis 2.0 的总体目标架构

4.1 核心原则

4.2 总体分层

第一层：请求模式选择层

第二层：协调层

第三层：工作层

第四层：协作底座

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

5.1 一等的 agent 通信原语

作用

注意

5.2 结构化 task 运行时

作用

5.3 事件总线 Event Bus

作用

5.4 verifier 角色

职责

意义

5.5 工具权限模型

意义

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

6.1 backend/app/agents/state.py

目标

建议新增字段

重点

6.2 backend/app/agents/graph.py

目标

建议新增节点

推荐行为

简单请求

复杂请求

重点

6.3 backend/app/agents/prompts.py

目标

需要新增的角色 prompt

协调者 prompt 应强调

verifier prompt 应强调

6.4 backend/app/agents/registry/*

目标

建议补充

建议角色分类

6.5 backend/app/agents/tools/*

目标

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

建议新增模块

7. 升级阶段设计

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

7.1.1 阶段目标

7.1.2 这一阶段要解决的问题

7.1.3 范围

7.1.4 核心改动

改动 1：新增 execution_mode

改动 2：新增 verifier 角色

改动 3：新增事件总线抽象

22 KiB

Raw Permalink Blame History

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

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

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

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

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

改动 1：新增 `execution_mode`