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

13 KiB

Raw Blame History

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      │
                    │   (统一工具执行层)     │
                    └───────────────────────┘

当前优势

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

当前短板

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

短板	严重程度	当前真实状态
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 继续只依赖当前静态路由架构，会遇到以下问题：

复杂请求只能硬塞进单路径执行 → 可靠性低
无法优雅地拆分和回收多步任务 → 只能串行处理
执行与验收耦合 → 工具失败可能被误报为成功
系统内部过程不透明 → 后续难调试
无法支持真实的多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核心概念：

VCP协议 — 文本格式工具调用协议
```
<<<[TOOL_REQUEST]>>>
tool_name:「始」VSearch「末」,
SearchTopic:「始」AI医疗诊断「末」
<<<[END_TOOL_REQUEST]>>>
```
- 使用中文分隔符「始」「末」
- 支持 archery:no_reply（异步）、river:full（上下文注入）
TagMemo记忆系统 — 仿生RAG
- LIF神经元模型：脉冲传播机制
- Core Tags：核心记忆1.2-1.4x权重加成
- 遗忘曲线：不是无限存储，模拟生物遗忘
6类型插件：
- static：占位符
- messagePreprocessor：消息预处理
- synchronous：同步stdio
- asynchronous：异步回调
- service：后台服务
- hybridservice：混合模式
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│ │(独立角色)│          │ (动态创建) │
   └─────────┘ └─────────┘          └───────────┘

升级后的基本原则

简单请求继续走当前稳定路径(direct mode)
复杂请求才进入协作模式(collaboration mode)
执行与验证分离(Verifier独立)
动态能力必须有预算限制(spawn/message/depth budget)
工具能力必须有权限约束(permission_class)
全程要有可观察事件流(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. 本阶段产出要求

本阶段完成标准：

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

13 KiB Raw Blame History Unescape Escape

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

1. 本阶段目的

2. 当前 Jarvis 架构现状

当前架构精确描述

当前优势

当前短板

3. 为什么需要升级

4. 四个 Demo 的启发总结

4.1 Swarm-IDE 给我们的启发

4.2 Claude Code CLI 给我们的启发

4.3 Claw Code 给我们的启发

4.4 VCPToolBox 给我们的启发

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

ADR-001: 为什么选择LangGraph？

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

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

ADR-004: Event Schema设计选择

6. 目标架构

目标架构预览

升级后的基本原则

7. 总体分阶段策略

8. 本阶段产出要求

13 KiB

Raw Blame History