JARVIS/development-doc/plan/agent-update/jarvis-agents-8-day-work-checklist.md

# Jarvis Agents 8 天工作计划（可勾选执行版）

日期：2026-04-03  
状态：执行清单  
适用范围：基于 `phase-0` ~ `phase-5` 及现有融合方案整理  
借鉴来源：Claude Code CLI、Swarm-IDE、Claw Code、VCPToolBox

---

## 使用说明

- 完成前使用 `- [ ]`
- 完成后改成 `- [x]`
- Day 2 默认依赖 Day 1 的核心底座完成后再推进
- Day 3 默认依赖 Day 2 的最小协作闭环完成后再推进
- Day 4 默认依赖 Day 3 的动态协作完成后再推进
- Day 5 默认依赖 Day 4 的可见性 API 完成后再推进
- Day 6 默认依赖 Day 5 的隔离执行完成后再推进
- Day 7 默认依赖 Day 6 的成本监控完成后再推进

---

## Day 1：补底座，完成 Phase 1 最小闭环

Day 1 目标：先把 Jarvis 从"只有静态路由"补成"有任务结构、有事件结构、有 verifier、有工具治理信息"的可扩展底座，同时不破坏当前 direct 主路径。

- [x] 新增最小 `task schema`
  改造内容：新增 `backend/app/agents/schemas/task.py`，统一 `task_id`、`title`、`status`、`owner_agent_id`、`evidence`、`result_summary`，并补 `role`、`goal`、`expected_evidence`、`created_at`、`updated_at`；状态固定为 `pending`、`in_progress`、`completed`、`failed`、`blocked`。

- [x] 新增最小 `event schema`
  改造内容：新增 `backend/app/agents/schemas/event.py`，统一 `event_id`、`event_type`、`timestamp`、`conversation_id`、`agent_id`、`sub_commander_id`、`task_id`、`payload`、`severity`；首批事件类型覆盖 `agent.tool.start`、`agent.tool.result`、`agent.verify.started`、`agent.verify.completed`、`agent.error`。

- [x] 扩展 `backend/app/agents/state.py` 的运行时字段
  改造内容：新增 `execution_mode`、`verification_status`、`verification_summary`、`verification_evidence`、`active_tasks`、`task_results`、`event_trace`、`budget_state`；默认值保持兼容 `initial_state()`，不替换现有 `pending_tasks`、`completed_tasks`、`tool_calls`。

- [x] 扩展 capability / tool metadata 模型
  改造内容：在 `backend/app/agents/registry/models.py` 增加 `permission_class`、`side_effect_scope`、`supports_retry`、`idempotent`、`safe_for_parallel_use`、`requires_confirmation`；至少先固化 `read` / `write` / `external` 和 `none` / `local_state` / `db_write` / `network` 两组枚举语义。

- [x] 回填 builtin tools 的静态 metadata
  改造内容：在 `backend/app/agents/registry/builtins.py` 和需要的 `backend/app/agents/tools/__init__.py` 中，把 search / retrieval 类工具标成偏 `read`，create / update 类工具标成偏 `write`，外部检索类工具标成 `external`，并补充是否可重试、是否幂等、是否适合并行等标记。

- [x] 新增 verifier 角色定义
  改造内容：在 `backend/app/agents/prompts.py` 增加 verifier prompt，明确 verifier 只负责验收，不负责重新规划；验收点聚焦"是否真正满足请求""是否有明确证据""是否把失败伪装成成功"。

- [x] 落地 verifier 模块
  改造内容：新增 `backend/app/agents/verifier.py`，支持 `passed`、`failed`、`skipped` 三类最小结论，先服务于工具调用后的复杂输出，知识检索结果和分析型汇总输出，不接管纯闲聊路径。

- [x] 在 `backend/app/agents/graph.py` 接入最小 event trace 与 verifier helper
  改造内容：给 `_execute_tool_calls()` 增加 tool start / result / error 事件写入；给收尾阶段增加 verifier helper 调用；给 `_run_sub_commander()` 增加 task result 摘要写入，但暂时不重构主图为完整协作编排图。

- [x] 补 Phase 1 单元测试与回归测试
  改造内容：新增 `backend/tests/backend/app/agents/test_agent_schemas.py`、`backend/tests/backend/app/agents/test_verifier.py`，并扩展 `test_graph.py`，覆盖 state 兼容性、schema 合法性、tool metadata 存在性、verifier 判定、主流程不回退。

- [x] 完成 Day 1 验收
  改造内容：确认 reminder / task / search 主流程继续通过；确认 verifier 已能独立运行；确认 event schema 与 task schema 已落代码；确认 direct 仍是默认主路径；确认未引入动态 `create_agent`、message bus 全链路和 UI。

---

## Day 2：引入最小协作能力，完成 Phase 2 雏形

Day 2 目标：在 Day 1 底座稳定的基础上，给 Jarvis 增加"复杂请求可拆分、可分配、可回收、可验收"的最小受控协作能力，但仍然不进入自由 swarm。

- [x] 增加 `request_mode_selector`
  改造内容：在 `backend/app/agents/graph.py` 中增加 direct / collaboration 模式选择逻辑；简单请求继续走旧路径，只有明显多步骤、跨领域、需要多角色配合的请求才进入 collaboration mode。

- [x] 新增 coordinator prompt
  改造内容：在 `backend/app/agents/prompts.py` 中定义 coordinator 角色，职责限定为"判断是否拆解""输出 2~4 个清晰子任务""分配角色建议""汇总任务结果"；明确禁止无限递归拆分。

- [x] 新增最小 task decomposition 结构
  改造内容：基于 Day 1 的 task schema 扩展最小拆分结构，至少输出 `task_id`、`title`、`role`、`goal`、`expected_evidence`，让复杂请求能以结构化任务列表进入后续执行。

- [x] 增加 role -> existing agent assignment
  改造内容：先复用当前已有 top-level agent，不新增独立 worker runtime；把 schedule 类任务映射给 `schedule_planner`，retrieval 类任务映射给 `librarian`，analysis 类任务映射给 `analyst`，execution 类任务映射给 `executor`。

- [x] 建立统一 task result 回收结构
  改造内容：约束每个角色统一返回 `task_id`、`status`、`summary`、`evidence`、`next_action`（可选），并把结果写回 `task_results`，避免最终结果继续依赖单点硬编码拼接。

- [x] 让 verifier 强制参与协作结果收尾
  改造内容：在 collaboration mode 下，所有复杂请求返回前都必须经过 verifier；verifier 有权拒绝证据不足、结果不完整，子任务未闭环的响应。

- [x] 补 Phase 2 协作测试与回归测试
  改造内容：覆盖复杂请求拆分测试、角色分配测试、task result 汇总测试、verifier 拒绝不完整结果测试，并再次确认 direct 模式原有流程不回退。

- [x] 完成 Day 2 验收
  改造内容：确认 graph 已能区分 direct / collaboration；确认复杂请求可拆成 2~4 个子任务；确认每个子任务有 owner 和 evidence；确认最终答案基于 task result 汇总；确认系统仍未进入无限动态 agent 模式。

---

## Day 3：引入受限动态协作能力，完成 Phase 3 最小闭环

Day 3 目标：在 Day 2 已具备最小协作编排能力的基础上，让 Jarvis 获得"可追踪、可中断、可恢复、受预算约束"的动态协作 runtime，但依然不进入无限自由 swarm。

当前实现状态（2026-04-03）：Day 3 最小闭环已基本落地。`backend/app/agents/state.py` 已补齐协作树、thread/message、interrupt/recovery、budget 相关 runtime 字段；`backend/app/agents/graph.py` 已接入受限 child agent 创建、message trace、spawn budget guardrail、interrupt / recovery 最小闭环与协作结果回收；`backend/app/agents/registry/*` 已补齐 spawn role policy 并接入 graph 校验。

- [x] 扩展 `backend/app/agents/state.py` 记录协作树基础字段
  当前状态：`state.py` 已补齐 `agent_id`、`parent_agent_id`、`root_agent_id`、`collaboration_depth`、`spawned_agent_ids`、`interrupted_tasks`、`recovery_points`、`message_trace` 等 Day 3 runtime 字段，并由 `initial_state()` 完成兼容初始化。

- [x] 定义动态协作 budget state
  当前状态：已新增 `CollaborationBudget` schema，并在 graph 中通过 `budget_state` / `collaboration_budget_history` 落地 `max_spawn_depth`、`max_child_agents`、`max_messages_per_thread`、`max_messages_per_turn`、`max_parallel_collaborators`、`recovery_attempt_limit` 等 guardrail metadata。

- [x] 增加受限 `create_agent` 运行时原语
  改造内容：新增最小动态创建能力，仅允许在 collaboration mode 下、由受限角色、在 budget 允许时创建 child agent；创建过程会记录 parent / child 关系，并在受限时转入 interrupt / recovery 回退路径。

- [x] 增加 agent spawn permission / role policy
  改造内容：已在 `backend/app/agents/registry/*` 中补齐角色 spawn policy，并通过 registry indexes 接入 `graph.py` 的运行时权限校验，禁止任意角色无限派生。

- [x] 新增最小 message / thread schema
  改造内容：已补齐 `message_id`、`thread_id`、`from_agent_id`、`to_agent_id`、`task_id`、`reply_to_message_id`、`message_type`、`content_summary`、`created_at` 等结构，支持 `task_request`、`task_update`、`handoff`、`verification_request`、`verification_feedback`、`interrupt_notice`。

- [x] 在 `backend/app/agents/graph.py` 接入受限动态协作分支
  改造内容：coordinator / worker 在满足条件时可以请求受限协作；graph 已接入 child agent 创建、message thread 写入、spawn budget 校验与回收逻辑，简单请求仍优先走 direct 路径。

- [x] 扩展 event trace 覆盖动态协作生命周期
  改造内容：event trace 已覆盖 `agent.created`、`agent.spawn.blocked`、`agent.message.sent`、`agent.message.received`、`agent.interrupt.requested`、`agent.interrupt.completed`、`agent.recovery.started`、`agent.recovery.completed` 等关键事件。

- [x] 增加 interrupt / recovery 最小闭环
  改造内容：已支持中断协作任务、记录中断点，并基于 `task_id` / `thread_id` / budget 进行最小恢复路径记录与回退。

- [x] 增加 Day 3 测试与回归验证
  改造内容：补充 parent / child tracking、spawn role policy、message thread、interrupt / recovery、动态协作事件记录等测试，并继续确认 direct 主路径不回退。

- [x] 完成 Day 3 验收
  改造内容：系统已支持受限动态创建 agent，协作树和 message thread 可追踪，interrupt / recovery 可跑最小闭环，动态能力受 budget 与 role policy 约束，且仍不是自由蜂群式协作。

---

## Day 4：引入可见性 API，完成 Phase 4 可视化方向

Day 4 目标：在 Phase 1-3 已具备协作 runtime 的基础上，让 Jarvis 获得"可看、可查、可调试"的可见性 API，为后续复杂任务调试和执行打下基础。

当前实现状态（2026-04-04）：Phase 1-3 最小闭环已基本落地；Day 4 后端可见性最小闭环已完成。可见性 API 直接读取 continuity snapshot 中保存的 runtime state（如 `event_trace`、`message_trace`、`active_tasks`、`task_results`、`task_hierarchy`、`verification_*`、`tool_outcomes`），并已补 focused API 测试。

- [x] 固化可见性数据源并增加 events 查询 API
  改造内容：已在 `backend/app/routers/agent.py` 暴露 `GET /api/agents/visibility/events`，支持按 `conversation_id` / `thread_id` / `agent_id` / `event_type` 过滤 `event_trace`，并支持分页与时间范围查询。

- [x] 新增协作链路拓扑查询 API
  改造内容：已新增 `GET /api/agents/visibility/topology`，基于 state 中的 `spawned_agent_ids`、`task_hierarchy`、`root_agent_id`、`active_tasks`、`task_results` 构建协作拓扑视图，返回 agent 节点、父子边与 task 摘要。

- [x] 新增 task 执行证据查询 API
  改造内容：已新增 `GET /api/agents/visibility/tasks/{task_id}/evidence`，基于 state 中的 `task_results`、`tool_outcomes`、`verification_*` 返回指定 task 的执行证据链。

- [x] 新增 message thread 查询 API
  改造内容：已新增 `GET /api/agents/visibility/threads/{thread_id}/messages`，基于 `message_trace` 返回指定 thread 内所有消息的方向、摘要、时间和关联 task。

- [x] 新增 verifier 结果查询 API
  改造内容：已新增 `GET /api/agents/visibility/verifier`，基于 `verification_status`、`verification_summary`、`verification_evidence` 返回当前协作会话的验收结论和证据。

- [x] 补 Day 4 可见性 API 测试
  改造内容：已新增 `backend/tests/backend/app/agents/test_visibility_api.py`，覆盖 event filter / pagination、topology 构建、evidence 查询、thread 消息重建、verifier 查询、非法 datetime 参数校验等场景。

- [x] 完成 Day 4 验收
  改造内容：已确认 visibility API 可查询事件、拓扑、task evidence、thread 消息与 verifier 结果；并已确认原有 reminder / task / search 主路径不在 Day 4 范围内被改坏。

---

## Day 5：升级 operator/debug surface（已完成）

Day 5 目标：把 Day 4 的只读可见性 API 真正接到前端 Agents 页面，形成最小 operator/debug surface。

- [x] 接入 runtime summary API 到前端 `agentApi`
  改造内容：在 `frontend/src/api/agent.ts` 增加 runtime summary 类型与 `getRuntimeSummary()` 查询方法。

- [x] 在 Agents 页面展示 phase/checkpoint/verifier/isolation/cost 摘要
  改造内容：在 `frontend/src/pages/agents/index.vue` 与 `useAgentsPage.ts` 中加入 runtime summary HUD，展示 execution mode、phase、checkpoint、verifier、isolation、token/cost、task/node 统计。

- [x] 让 Agents 页面使用当前会话 `conversation_id`
  改造内容：复用 `frontend/src/stores/conversation.ts` 的 `currentConversationId`，不再使用伪造的 `latest` 占位值。

- [x] 修复 Agents 页面关键乱码与兜底文案
  改造内容：修复配置抽屉、状态文案、master task 文案等可见乱码，并为未选会话场景提供清晰提示。

- [x] 补前端运行时面板测试
  改造内容：补 `frontend/src/pages/agents/agentsPage.test.ts`，覆盖 runtime summary 渲染、无会话提示、会话 ID 传递。

- [x] 完成 Day 5 验收
  改造内容：确认 Agents 页面已经是可用的 operator/debug 入口，而不是只显示静态演示图。

---

## Day 6：推进 isolation runtime MVP（90 分主线）

Day 6 目标：把 Day 4 的 isolation 设计从文档推进到最小运行时闭环，只做 `none / session / worktree` 三层。

当前实现状态（2026-04-04）：Day 6 已落地 isolation runtime MVP。后端已新增 `strategy_selector.py`、`session_isolation.py`、`worktree_isolation.py`，并在 `graph.py` 中接入基于任务语义与 tool metadata 的 `none / session / worktree` 选择逻辑；隔离 metadata 会进入 state、event trace、task evidence 与 runtime summary，Agents 页面也可展示 workspace / isolation 状态。

- [x] 实现 IsolationStrategySelector
  改造内容：新增 `backend/app/agents/isolation/strategy_selector.py`，根据任务类型与 tool metadata 自动选择 `none / session / worktree`。
  当前状态：已新增 `backend/app/agents/isolation/strategy_selector.py`，可基于用户请求语义、role 与 capability metadata 自动选择 `none / session / worktree`。

- [x] 实现 Session 隔离
  改造内容：新增 `backend/app/agents/isolation/session_isolation.py`，支持上下文隔离、中间态隔离与 evidence 回传。
  当前状态：已新增 `backend/app/agents/isolation/session_isolation.py`，会生成独立 session isolation metadata，并把 parent conversation / role / sub commander / capability 信息写回 runtime state。

- [x] 实现 Worktree 隔离
  改造内容：新增 `backend/app/agents/isolation/worktree_isolation.py`，基于 git worktree 创建独立工作目录，回传 workspace/branch/cleanup metadata。
  当前状态：已新增 `backend/app/agents/isolation/worktree_isolation.py`，支持基于 git worktree 创建独立工作目录，回传 branch / repo_root / cleanup_status 等 metadata；创建失败时可回退到 session isolation。

- [x] 集成隔离策略到 graph
  改造内容：在 `backend/app/agents/graph.py` 中接入策略选择与 evidence 输出，不做自动 merge-back。
  当前状态：`backend/app/agents/graph.py` 已接入 isolation selector / executor，运行时会记录 `agent.isolation.selected` / `agent.isolation.fallback` 事件，并把 isolation metadata 写入 evidence 与 task result。

- [x] 补 Day 6 隔离测试
  改造内容：新增隔离策略与 metadata 传播测试，覆盖 session/worktree 选择和 runtime summary 展示。
  当前状态：已在 `backend/tests/backend/app/agents/test_graph.py` 中补充 isolation selector / worktree fallback / runtime cost 联动测试；`test_visibility_api.py` 继续覆盖 runtime summary 中的 isolation 暴露。

- [x] 完成 Day 6 验收
  改造内容：确认高副作用任务可进入 worktree，低副作用任务保持 direct/session 路径，主流程无回退。
  当前状态：高副作用、代码/仓库语义请求可进入 worktree；普通状态写入或分析路径保持 session / direct；主流程回归测试已通过 `test_graph.py`。

---

## Day 7：推进 cost governance MVP（90 分主线）

Day 7 目标：把 token/cost 从静态估算升级为会话级可治理能力。

当前实现状态（2026-04-04）：Day 7 已从“静态展示”推进到最小 cost governance 闭环。`graph.py` 已稳定累计 `input_tokens` / `output_tokens` / `estimated_cost`，并按 conversation / child agent 维度写入 `cost_by_agent`；budget threshold 会触发 `agent.cost.updated` / `agent.cost.warning` 事件，后端也已暴露 conversation scoped cost API。

- [x] 固化 runtime token 字段写入
  改造内容：在 graph / service 层稳定记录 `input_tokens`、`output_tokens`、`estimated_cost`、`budget_warning`。
  当前状态：`backend/app/agents/graph.py` 已在每次 LLM 响应后提取 usage metadata，并稳定写入 `input_tokens`、`output_tokens`、`estimated_cost`、`budget_warning`。

- [x] 集成成本累计到 conversation / child agent 维度
  改造内容：把协作 run 的 token/cost 汇总到 conversation summary，并保留子 agent 维度的来源信息。
  当前状态：state 中已新增 `cost_by_agent` 与 `cost_thresholds`，并可通过 `/api/agents/visibility/cost` 返回 conversation 总量与 child agent 分摊。

- [x] 增加 budget threshold 治理逻辑
  改造内容：支持阈值警告、超额提示和 runtime summary 暴露。
  当前状态：已新增默认 cost threshold 与 state override 机制，超阈值会写入 `budget_warning` 并产生 warning 事件，runtime summary 与前端 HUD 均可见。

- [x] 新增成本查询 API
  改造内容：在现有 visibility surface 上补 conversation scoped cost 查询，而不是另起一套孤立接口。
  当前状态：已新增 `GET /api/agents/visibility/cost`，返回 conversation scoped total / thresholds / by_agent breakdown。

- [x] 补 Day 7 测试
  改造内容：覆盖成本累计、阈值预警、runtime summary 成本字段。
  当前状态：`backend/tests/backend/app/agents/test_graph.py` 已覆盖 runtime usage 写入与 threshold warning；`test_visibility_api.py` 已补 cost summary 返回结构断言。

- [x] 完成 Day 7 验收
  改造内容：确认 cost 不再只是“可估算”，而是“可观察、可告警、可治理”。
  当前状态：Day 7 当前已达到“可观察、可告警、可按会话/agent 查询”，仍未做到更高级的跨会话预算策略与持久化治理。

---

## Day 8：90 分收口与工具治理增强

Day 8 目标：把现有 runtime 补成真正可运营的 90 分闭环，并明确下一批值得升级的工具能力。

当前实现状态（2026-04-04）：Day 8 已完成 90 分主线收口。Agents 页面已从首屏 summary 升级为可查看 recent events、topology 节点摘要、verifier evidence、cost by agent 与 tool governance 的 operator/debug surface；后端也补齐了 `/visibility/tools` 能力分层查询。

- [x] 增强 topology / recent events operator surface
  改造内容：在 Agents 页面增加 recent events、拓扑摘要、verifier 证据入口，形成更完整的调试视图。
  当前状态：前端 `frontend/src/pages/agents/index.vue` 与 `useAgentsPage.ts` 已展示 recent events、topology 节点摘要与 verifier evidence 入口。

- [x] 对工具能力做治理分层
  改造内容：基于 `permission_class`、`side_effect_scope`、`requires_confirmation`、`safe_for_parallel_use` 做工具分级和后续 UI 展示规划。
  当前状态：后端已新增 `GET /api/agents/visibility/tools`，基于 `permission_class`、`side_effect_scope`、`requires_confirmation`、`safe_for_parallel_use` 返回 tool governance 视图；前端已做 operator 展示。

- [x] 识别值得升级/新增的工具能力
  改造内容：优先考虑 `worktree manager`、`cost inspector`、`runtime event drilldown`、`tool policy explorer`，暂不做 TagMemo / AgentDream。
  当前状态：operator surface 已显式暴露 `worktree_manager`、`cost_inspector`、`runtime_event_drilldown`、`tool_policy_explorer` 四项下一批 upgrade candidates。

- [x] 完成 90 分结项回归
  改造内容：统一回归 direct / collaboration / runtime summary / isolation / cost 关键路径，并更新 README / daily / checklist 结论。
  当前状态：已完成 `backend/tests/backend/app/agents/test_graph.py` 回归、`frontend/src/pages/agents/agentsPage.test.ts` 前端回归，以及不依赖 pytest tmpdir 的 visibility API 手工验证；README / checklist 已同步更新。

---

## 这 8 天明确不做

- 不做无限自由的动态 `create_agent`
- 不做无限层级的 parent / child agent tree
- 不做任意 agent 任意建群 / 广播
- 不做内部消息线程的复杂长期态治理
- 不做完整可视化调试面板（只做首屏 summary / HUD，不做完整实时 drilldown UI）
- 不做 Full Sandbox 完整实现（只做设计方案）
- 不做自由蜂群式协作
- 不做 Persistence（数据库持久化）
- 不做 Multi-turn Memory（跨会话记忆）
- 不做 Plugin System（插件系统）
- 不做 TagMemo（仿生记忆系统）
- 不做 AgentDream（仿生梦境系统）

---

## 8 天结束后的预期状态

- [x] 已具备 `direct` / `collaboration` 双模式入口
- [x] 已具备 verifier 独立验收层
- [x] 已具备 task schema / event schema / tool metadata 底座
- [x] 已具备 coordinator 雏形、任务拆分、角色分配、结果回收
- [x] 已具备受限动态协作 runtime 的最小实现闭环
- [x] 当前 reminder / task / search 主路径无明显回退
- [x] 已具备可见性 API 基础（events、topology、evidence、thread、verifier、runtime-summary）
- [x] 已具备前端 Agents operator/debug 首屏
- [x] 已具备 isolation strategy selector + session/worktree executor 的最小运行时闭环
- [x] 已具备 conversation / child agent 维度的 cost governance 最小闭环
- [ ] 尚未具备 full sandbox / persistence / realtime push
- [x] 90 分主线已明确为 isolation + cost + operator surface，而不是 TagMemo / AgentDream

---

## 后续可选特性（按需实施）

| 特性 | 预估时间 | 触发条件 |
|------|---------|---------|
| AgentDream（仿生梦境系统） | 1天 | Day 7完成后 |
| Persistence（持久化） | 2-3天 | 有审计需求时 |
| Advanced UI（完整前端面板） | 3-5天 | 有前端资源时 |
| Full Sandbox（完整沙箱） | 3-5天 | 有安全需求时 |
| Plugin System（插件系统） | 2-3天 | 有社区需求时 |

---

##