JARVIS/development-doc/plan/agent-update/phase-4-visibility-and-isolation.md

Phase 4：可视化与隔离执行阶段（Visibility + Isolation）

日期：2026-04-03 状态：Day 4-5 最小闭环已完成（后端可见性 API + runtime summary + Agents 页面首屏接入 + 隔离设计）

---

1. 阶段目标

把 Jarvis 的多 agent 系统从“内部能跑”升级为“可看、可查、可调试、可规划隔离执行”的系统。

本阶段分两部分：

• 可见性：把 runtime state 中已经存在的协作数据稳定对外暴露
• 隔离执行设计：先明确最小可落地方案，不在 Day 4 内强行做完整实现

---

2. Day 4 已落地范围

2.1 可见性数据源

Day 4 已明确：可见性 API 的单一数据源是 conversation continuity snapshot 中保存的 runtime state，而不是数据库推断或日志二次解析。

当前已作为读取基础的数据包括：

• event_trace：关键生命周期事件
• message_trace：thread / message 流向
• active_tasks：当前任务清单
• task_results：任务执行结果
• task_hierarchy：父子任务关系
• verification_status
• verification_summary
• verification_evidence
• thread_id
• agent_id
• root_agent_id
• spawned_agent_ids
• tool_outcomes

2.2 已实现的只读 API

当前已经在 backend/app/routers/agent.py 下提供以下只读接口：

• GET /api/agents/visibility/events
  • 支持 conversation_id、agent_id、thread_id、event_type、时间范围、分页过滤
• GET /api/agents/visibility/topology
  • 返回当前协作拓扑、节点、边、任务摘要、task hierarchy
• GET /api/agents/visibility/tasks/{task_id}/evidence
  • 返回 task、task result、关联 tool outcomes、verifier 结果
• GET /api/agents/visibility/threads/{thread_id}/messages
  • 返回指定 thread 的消息历史
• GET /api/agents/visibility/verifier
  • 返回当前会话 verifier 状态、摘要、证据
• GET /api/agents/visibility/runtime-summary
  • 返回 execution mode、phase/checkpoint、verifier、isolation、cost、recent events 聚合摘要

2.3 已补测试

Day 4 已新增后端 API 测试文件：

• backend/tests/backend/app/agents/test_visibility_api.py

覆盖场景包括：

• event filter + pagination
• topology 构建
• task evidence 查询
• thread message 重建
• verifier 查询
• 非法 datetime 参数校验

---

3. 当前实现边界

Day 4 已经完成的是后端可见性最小闭环，但有意不做以下内容：

• 不做前端调试面板 UI
• 不做 SSE / WebSocket 实时推送
• 不做独立新的 visibility 存储层
• 不做完整 worktree / sandbox 执行实现
• 不做自由蜂群式调度

因此 Day 4 的定位应是：

已具备可见性查询 API 与隔离执行设计，不等于已经具备完整实时调试平台或完整隔离执行运行时。

---

4. 隔离执行最小方案

4.1 设计目标

对于更复杂、可能污染主工作目录或需要更强安全边界的任务，Day 4 先定义一个清晰的隔离分层策略，供后续 Phase 4+ 实现使用。

4.2 隔离级别

级别	名称	适用场景	Day 4 状态
L0	无隔离	普通问答、轻量检索、只读分析	已存在
L1	Session State 隔离	需要隔离上下文/记忆但不改文件	设计完成
L2	Worktree 隔离	代码修改、文件写入、需要独立目录	推荐主方案
L3	Sandbox Container	高风险命令、需要更强 OS 级边界	仅保留扩展位

4.3 技术选型结论

Day 4 的最小技术选型如下：

首选：Git worktree 隔离

适用：

• 代码生成
• 批量重构
• 多 agent 并行改文件
• 需要避免污染主工作目录的执行型任务

原因：

• 与当前 git 仓库工作流天然兼容
• 可以复用已有分支 / review / merge 流程
• 隔离成本低于容器
• 更适合作为 Jarvis 当前阶段的最小可落地方案

次选：Session state 隔离

适用：

• 多轮复杂分析
• 需要隔离上下文污染
• 只读或低风险任务

原因：

• 实现成本低
• 不依赖文件系统隔离
• 可先于完整 worktree runtime 落地

暂不在 Day 4 实现：Sandbox container

适用：

• 高风险 shell 命令
• 潜在破坏性任务
• 需要系统级资源控制

结论：

• Phase 4 不做完整容器运行时
• 仅保留接口和策略位置，后续再做

---

5. Session State 隔离策略

Session state 隔离的最小原则：

1. 每个隔离 worker 拥有独立的 memory / turn context
2. 默认不继承完整 message history，只注入必要共享上下文
3. 输出只回传：
   • task result
   • evidence
   • verifier-ready summary
4. 不把中间临时推理状态直接合并回主 state

建议最小 state 结构：

• isolation_mode: none | session | worktree | sandbox
• isolation_id
• isolation_parent_conversation_id
• isolation_workspace_path（如适用）
• isolation_metadata

---

6. Worktree 隔离策略

Worktree 隔离的最小原则：

1. 每个执行型 worker 对应独立 worktree
2. worktree 使用独立 branch 命名
3. 主工作目录不直接写入
4. 结果通过 diff / changed files / task result 回收
5. 清理策略必须可控，避免遗留脏目录

建议目录模式：

• .worktrees/jarvis/<conversation-or-run-id>/<worker-id>/

建议 branch 模式：

• jarvis/<conversation-or-run-id>/<worker-id>

最小回收物：

• modified_files
• git_diff_summary
• task_result
• verification_evidence

---

7. 最小 Isolation Execution API 定义

Day 4 先定义接口边界，不要求马上完整实现。

7.1 任务执行请求侧

建议未来 runtime 接口至少支持：

• isolation_mode
• workspace_strategy
• allow_merge_back
• cleanup_policy

示意：

{
  "task_id": "task-123",
  "goal": "refactor agent router",
  "isolation_mode": "worktree",
  "workspace_strategy": "ephemeral",
  "allow_merge_back": false,
  "cleanup_policy": "on_success"
}

7.2 执行结果侧

建议统一返回：

{
  "task_id": "task-123",
  "status": "completed",
  "isolation": {
    "mode": "worktree",
    "workspace_path": ".worktrees/jarvis/run-1/worker-2",
    "branch": "jarvis/run-1/worker-2",
    "cleanup_status": "pending"
  },
  "evidence": [],
  "summary": "Refactor completed"
}

---

8. 验收结论

Day 4 最小闭环完成时，当前应以以下标准为准：

• 可按条件查询 event trace
• 可查询协作拓扑与任务摘要
• 可查询 task 执行证据
• 可重建 thread message 历史
• 可查询 verifier 结果
• 有 Day 4 后端 API 测试覆盖
• 有隔离执行最小设计方案
• 不包含实时 SSE/UI
• 不包含完整 worktree/sandbox runtime 实现

---

9. 本阶段完成后的真实状态

完成 Day 4 后，Jarvis 当前具备：

• 受限多 agent runtime 的可见性查询能力
• 面向调试与验收的后端只读 API
• 基于 continuity snapshot 的稳定可见性数据源
• 面向后续实现的 isolation strategy 设计

当前 尚未具备：

• 实时事件推送平台
• 前端可视化调试面板
• 完整 worktree 执行编排
• 容器级 sandbox 执行器

这意味着：

Day 4 已完成最小闭环，但后续仍可继续扩展为完整可视化 UI 和隔离执行 runtime。