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
parent e5bd492d74
commit a3fe4d24fc
35 changed files with 8501 additions and 0 deletions
--- a/development-doc/plan/agent-update/phase-0-current-state-and-target.md
+++ b/development-doc/plan/agent-update/phase-0-current-state-and-target.md
@@ -0,0 +1,322 @@
+# 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] 不直接在本阶段进行代码改造
+