# 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`

示意：

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

### 7.2 执行结果侧

建议统一返回：

```json
{
  "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 最小闭环完成时，当前应以以下标准为准：

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

---

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

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

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

当前 **尚未具备**：

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

这意味着：

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