WIN-JHFT4D3SIVT\caoxiaozhu
a3fe4d24fc
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
323 lines
13 KiB
Markdown
323 lines
13 KiB
Markdown
# 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] 不直接在本阶段进行代码改造
|
||
|