# Jarvis Agents 2 天融合改造计划

日期：2026-04-03
状态：草案
目标：在 **2 天内** 完成一版最小可落地的 Jarvis Agents 2.0 融合改造方案，不追求一步到位，只做最有价值、最能落地、风险最低的部分。

---

## 1. 这 2 天要完成什么

这 2 天不做完整的 swarm 化改造，也不做复杂 UI。

这 2 天的核心目标只有 4 个：

1. 把升级方向真正落到当前 Jarvis 代码结构上
2. 先完成 **Phase 1 的最小闭环**
3. 为 **Phase 2 的受控协作** 预埋接口
4. 保证当前 reminder / task / search 主路径不被破坏

换句话说：

> 这 2 天的重点不是“把终态做完”，而是“把融合路径打通”。

---

## 2. 融合原则

融合这套方案时，必须遵守下面 5 个原则：

### 原则 1：不推翻当前 graph
当前 `backend/app/agents/graph.py` 是现有稳定主链，不能直接大改成全新框架。

策略：

- 保留现有 direct path
- 只新增最小的 collaboration 入口

### 原则 2：先补底座，再谈动态协作
先做：

- verifier
- task schema
- event schema
- tool metadata

后做：

- coordinator
- agent message
- 动态 create_agent

### 原则 3：先做内部能力，不急着做前台可视化
即使未来要做 Swarm 风格可观察性，也不应该在这 2 天里优先做 UI。

先把：

- 事件结构
- 任务结构
- 协作状态

定义清楚。

### 原则 4：优先保障现有业务稳定
本次融合不能影响当前已有优势：

- continuity
- clarification
- native tool / fallback
- schedule / task / search 主流程

### 原则 5：每一步都要可测试
只要动到：

- state
- graph
- tools
- prompts

就必须补测试，不允许只写方案不验证。

---

## 3. 第 1 天计划：补底座，完成最小 Phase 1

第 1 天目标：

> 让 Jarvis 拥有 verifier、task schema、event schema、tool metadata 这些基础设施，但不引入复杂动态协作。

---

### 3.1 第 1 天工作目标

完成以下结果：

1. state 能表达 direct / collaboration 两种模式
2. verifier 成为独立角色
3. task schema 初版可用
4. event schema 初版可用
5. tool metadata 初版可用
6. 现有主路径测试不回退

---

### 3.2 第 1 天建议改动文件

重点落在这些文件：

- `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/test_graph.py`
- 新增若干 schema / tests 文件

---

### 3.3 第 1 天详细任务分解

#### 任务 1：定义最小 task schema
建议新增最小任务结构，字段控制在必要范围：

- `task_id`
- `title`
- `status`
- `owner_agent_id`
- `evidence`
- `result_summary`

目的：

- 不马上实现完整 task runtime
- 先让 graph 和 verifier 有统一结构可依赖

#### 任务 2：定义最小 event schema
建议先定义最小事件：

- `agent.tool.start`
- `agent.tool.result`
- `agent.verify.started`
- `agent.verify.completed`
- `agent.error`

目的：

- 先建立可观察性的“格式标准”
- 后面要不要落 DB / log / stream，可以再扩展

#### 任务 3：扩展 state
给现有 state 增加：

- `execution_mode`
- `verification_status`
- `active_tasks`
- `task_results`
- 预算字段占位

注意：

- 不要破坏现有 continuity 字段
- 尽量以新增字段为主

#### 任务 4：新增 verifier prompt
在 `prompts.py` 中新增 verifier 的职责说明：

- 不判断“写得像不像完成”
- 只判断“是否真正满足请求 + 是否有证据”

#### 任务 5：graph 中插入 verifier 分支
第一天不做复杂 coordinator。

只做：

- 在适当复杂输出后增加 verifier 节点
- direct path 仍保持主导

#### 任务 6：给 tools 增加 metadata
当前工具补充：

- `permission_class`
- `side_effect_scope`
- `supports_retry`
- `idempotent`
- `safe_for_parallel_use`

#### 任务 7：补测试
至少补下面几类测试：

- state 扩展兼容性
- verifier 执行路径
- tool metadata 存在性
- event schema 生成正确性
- 主流程无回退

---

### 3.4 第 1 天验收标准

第 1 天结束时必须满足：

1. 当前 reminder/task/search 流程测试继续通过
2. verifier 已成为独立角色，而不是写在注释里的计划
3. 有 task schema 和 event schema 初版
4. 每个关键工具已有 metadata
5. 当前系统还没有开始无限动态 agent

---

### 3.5 第 1 天风险控制

1. 不做动态 create_agent
2. 不做 message bus 全量落地
3. 不做 UI
4. 不做大规模 registry 重构
5. 不改当前主路径的核心业务判断逻辑

---

## 4. 第 2 天计划：引入最小协作能力，完成 Phase 2 的雏形

第 2 天目标：

> 在第 1 天底座稳定的基础上，引入最小的 coordinator + task decomposition + worker assignment 能力，让 Jarvis 开始具备“受控协作”的雏形。

---

### 4.1 第 2 天工作目标

完成以下结果：

1. graph 能识别复杂请求并切到 collaboration mode
2. coordinator 能做最小任务拆分
3. worker assignment 能按角色分发任务
4. worker 输出能回收到统一 task result 结构里
5. verifier 能对协作结果验收

---

### 4.2 第 2 天建议改动文件

重点还是这些：

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

如有必要，可新增：

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

---

### 4.3 第 2 天详细任务分解

#### 任务 1：增加 request_mode_selector
判断当前请求是：

- direct mode
- collaboration mode

判定标准先做简单版，例如：

- 是否明显是多步骤任务
- 是否跨多个领域
- 是否需要多个角色协作

#### 任务 2：增加 coordinator prompt
coordinator 只负责：

- 理解任务
- 决定是否拆分
- 输出小任务列表

限制：

- 最多拆 2~4 个任务
- 不允许无限递归拆分

#### 任务 3：增加最小 task decomposition
输出结构建议包含：

- `task_id`
- `title`
- `role`
- `goal`
- `expected_evidence`

#### 任务 4：增加 worker assignment
先不要做 agent-to-agent 自由通信。

由系统分配即可：

- schedule 类给 scheduler
- retrieval 类给 retriever
- analysis 类给 analyst
- execution 类给 executor

#### 任务 5：增加 task result 回收
每个 worker 返回统一结果：

- `task_id`
- `status`
- `summary`
- `evidence`
- `next_action`（可选）

#### 任务 6：verifier 统一验收
协作模式最终必须经过 verifier：

- 看任务是否完成
- 看证据是否足够
- 看是否仍需补做某个子任务

#### 任务 7：补协作测试
至少补：

- 多任务拆分测试
- 角色分配测试
- task result 汇总测试
- verifier 拒绝不完整结果测试

---

### 4.4 第 2 天验收标准

第 2 天结束时必须满足：

1. graph 能区分 direct / collaboration
2. 简单请求仍然走旧路径
3. 复杂请求可以被拆分成多个子任务
4. 子任务可以按角色执行
5. verifier 能拦住不完整结果
6. 结果汇总不是单点硬编码，而是基于 task result

---

### 4.5 第 2 天风险控制

1. 先不做真正动态 create_agent
2. 先不做无限 message channel
3. 先不做 parent/child agent tree
4. 先不做可视化 UI
5. 先保证协作模式只是“受控编排”，不是“自由蜂群”

---

## 5. 2 天之后的融合状态

如果这 2 天按计划完成，Jarvis 会到达一个很关键的中间状态：

### 已具备的能力

- direct / collaboration 双模式
- verifier 独立角色
- task schema
- event schema
- tool metadata
- coordinator 雏形
- 最小任务拆分与角色分配
- 协作结果结构化回收

### 还没做的部分

- 动态 create_agent
- parent / child agent 树
- 内部消息线程
- 可视化协作面板
- 隔离执行 / worktree

这意味着：

> 2 天之后，Jarvis 还不是终态，但已经完成了“从静态路由走向协作运行时”的第一轮关键融合。

---

## 6. 2 天后的下一步建议

2 天融合完成后，下一步最合理的顺序是：

1. 补 `Phase 3` 详细设计
2. 设计受限 `create_agent`
3. 设计内部消息线程模型
4. 设计 parent / child state
5. 最后再考虑可视化与隔离执行

---

## 7. 一句话结论

这 2 天不要想着“做完 Jarvis 2.0”，而应该明确目标：

> 第 1 天补底座，第 2 天接编排，把最关键的融合路径打通。

只要这条路径打通，后面无论你更偏向 Swarm、Claude Code CLI 还是 Claw 的方向，都能继续演进。