# 隔离舱使用教程

> 按操作顺序排列的分步走查：安装确认 → 配置沙箱 → 第一个任务 → 官方会话界面 → 继续对话 →
> 返回/导出 → 重启恢复 → 清理/排障 → 验收。
>
> 适用版本：插件 **v0.2.0**，Host **build 2**，侧车协议/schema **1/1**，要求 **DSH 0.2.1+**。
> 功能全貌与接口见 [`README.md`](README.md)，字段级契约见 [`docs/PROTOCOL.md`](docs/PROTOCOL.md)。

## 0. 开始前

1. 确认 DSH 版本为 **0.2.1+**（桌面版 0.2.1-rc.2 已验证；0.1.7 不支持）。
2. 决定一个**工作区之外**的沙箱根目录，例如 `E:\pod-work`。不要使用项目目录或桌面。
3. 如果从 v0.1.3 升级，先按 [`docs/MIGRATION.md`](docs/MIGRATION.md) 备份并迁移。
4. 安装/升级后如果 Host 半被替换，**重启一次 DSH**；只刷新页面不一定能换掉已缓存的 Host 模块。

## 1. 安装与确认

### 1.1 安装（二选一）

**bundle（推荐）**

1. 侧边栏 →「插件」；
2. 「添加插件」→「安装第三方插件」→ 支持 npm 包、Git 仓库和本地目录；
3. 选择本仓库或 Release 解压目录的**绝对路径**，安装；
4. 确认 `dsh-isolation-pod` 已选中并启用；
5. 页面提示「请重启 DSH 使更改生效」时重启。

**patch 行（开发/回退）**

在 `<DSH_HOME>\profiles\<profile>\cordis.patch.yml` 追加：

```yaml
- insert:
    - id: dsh-isolation-pod
      name: '<仓库绝对路径>\lib\index.js'
```

两种方式不要同时启用。

### 1.2 确认

1. 侧边栏出现「隔离舱」图标；
2. 打开面板，顶部显示「隔离舱」标题；
3. 浏览器访问：

```powershell
curl.exe -s http://127.0.0.1:<port>/isolation-pod/status
```

预期：`pluginVersion: "0.2.0"`、`coreVersion: "0.2.0"`、`protocol: 1`、`schemaVersion: 1`、
`coreStatus: "ready"`、`build: 2`。
如果 `coreStatus` 不是 `ready`，先看本教程 §12 排障。

## 2. 配置沙箱根目录

1. 打开「隔离舱」面板 →「**配置**」；
2. 在「沙箱根目录」填绝对路径（例如 `E:\pod-work`），或点「选择目录」；
   - 未指定时任务会被拒绝，插件**不会**自动使用工作区；
   - 建议选在工作区之外，并使用**专用目录**；
   - 不能是文件系统根、用户主目录、`DSH_HOME`/数据库目录、当前 cwd、`SystemRoot`/`ProgramFiles`，
     也不能包含这些目录（否则报 `ROOT_PROTECTED`）；
3. 按需调整：
   - 「允许文件写入」：关闭后任务以 read-only 运行；
   - 「允许隔离环境使用的工具」：至少勾一个；未勾选调用会被 guard 拒绝；
   - 「单轮超时」「并发上限」「队列模式」；
   - 导出开关、「记住本次选择」（只预填路径）；
   - 「Agent preset」：决定隔离 Agent 的工具面；留空可能没有任何工具；
   - 「高级选项」：预览字节/字符上限、导出校验、沙箱自检模式、打开时自动恢复、日志级别；
4. 点「保存配置」。

> 配置保存时会返回被钳制/忽略的提示；preset 是否可用在**启动任务**时校验，失败会显示在新建页。
> 主会话工作区之外的沙箱根不会触发「沙箱在工作区内」的黄条。

## 3. 启动第一个任务

1. 切到「**新建**」；
2. 填写「任务描述」，例如：
   `用 Python 生成一个 CSV 文件，并核对前 5 行。`
3. （可选）填写「沙箱子目录」，例如 `task-a`；留空则任务目录使用任务 ID。
   子目录必须是相对路径，最多 8 层，每段 ≤64 字符，且不能使用 `..`、控制字符、`< > : " | ? *`
   或 Windows 保留设备名；
4. 「主会话」选择用于读取只读上下文/返回目标的主会话（默认最近的用户主会话）；
5. 点「**启动隔离任务**」。

结果：

- 成功时任务启动，自动打开官方会话；如果并发已满且队列开启，任务显示「排队中」；
- 失败时面板显示错误（常见：未配沙箱根、preset 不可用、并发满且队列关闭）。

## 4. 官方会话界面

打开任务后，DSH 主面板切换为官方 `conversation`：

- 上方是官方消息流：用户消息、助手输出、工具调用卡片、思考过程、流式输出；
- 输入框上方是**隔离舱任务操作条**：状态、任务名、面板/文件/返回/导出/停止按钮；
- 会话头部有隔离舱盾牌按钮（打开面板）；
- 如果任务会话尚未恢复，输入框位置会显示**只读恢复卡片**，而不是可输入框。

### 4.1 理解界面

| 位置 | 用途 |
|---|---|
| 官方输入框 | 正常继续对话；输入会进入同一个隔离 Agent |
| 任务操作条「面板」 | 回到隔离舱任务列表/详情 |
| 「文件」 | 查看任务目录、预览文本文件 |
| 「返回」 | 生成/编辑/确认返回主会话 |
| 「导出」 | 选择文件并导出到沙箱外 |
| 「停止」 | 取消当前轮 |
| Fork 警示 | 提醒 Fork 出的新会话不受隔离 setup 约束 |

### 4.2 查看工具是否被拒绝

未在白名单中的工具调用会以工具错误出现在官方工具卡片中；这是 guard 的预期行为。
「详情面板 → 可用工具 / 隔离环境实有」可以对照白名单上限与该 pod 实际工具面。

## 5. 继续对话与停止

- **继续**：在官方输入框输入，回车发送（Shift+回车换行）；沙箱、审批策略、
  工具 guard 与系统提示段保持不变。
- **停止**：任务操作条「停止」或官方输入框的停止；任务状态变为「已取消」。
- 停止只影响该任务，不会向主会话写入任何消息。
- 超时（默认每轮 10 分钟）会取消该轮并标记「超时」；之后仍可继续对话，下一轮重新计时。

## 6. 返回主会话

> 默认不返回任何内容。返回与导出是独立操作，不会互相触发。

1. 任务操作条「返回」，或任务详情「返回主会话」；
2. 按需勾选「包含任务状态」「包含最近结论」，可附带任务目录中的一个文本文件；
3. 点「生成预览」，得到一段可编辑文本；
4. 自由编辑（可补充说明）；
5. 点「确认返回主会话」，再在确认框中确认；
6. 主会话收到**一条**用户消息（≤ 8000 字）。

注意：

- 主会话必须当前打开（live）；否则提示 `主会话当前未打开，无法返回`；
- 二进制文件不会被注入；只接受任务目录内的文本文件；
- 返回内容尽量精简，避免把完整日志/代码带回主会话。

## 7. 导出与撤销

### 7.1 导出

1. 任务操作条「导出」或详情「导出到工作区」；
2. 勾选任务目录中的文件/目录；
3. 填/选**沙箱之外**的绝对目标目录；
4. 选择方式：复制 / 移动；
5. 选择冲突处理：覆盖 / 跳过 / 重命名；
6. 如配置开启，可勾选「记住本次选择」（只预填路径）；
7. 点「导出到工作区」，在确认框中再次确认。

导出完成后可在「导出记录」页查看逐项结果。**每次导出都要重新确认**，不存在自动延续的权限。

### 7.2 撤销

- 仅**复制**模式提供「撤销此次导出」；
- 覆盖式导出会先把原目标备份到 `<目标目录>\.isolation-pod-undo\<导出ID>\`；
- 撤销在 `exportVerify` 开启时校验目标文件的 BLAKE3 哈希（哈希在导出时总会记录）；目标被修改/
  删除/变成链接时显示冲突，不盲目删除。关闭校验或旧记录无哈希时不会校验，撤销可能直接删除目标；
- 旧版/无备份记录无法恢复被覆盖的原文件，撤销前请先手工备份；
- 移动模式不提供撤销按钮；
- 撤销只影响导出目标，不影响主会话或沙箱源文件。

## 8. 文件与预览

1. 任务操作条「文件」或任务详情「生成文件」；
2. 列出任务目录（最多 2000 项，深度 ≤ 8）；
3. 点单个文件「预览」：
   - UTF-8 / UTF-16 文本可读；
   - 二进制文件显示提示；
   - 受预览字节/字符上限限制，超出会截断/拒绝；
4. 刷新文件列表可看到新生成的文件。

## 9. 重启恢复

1. 任务运行中重启 DSH；
2. 重开后该任务显示「已中断」；
3. 打开任务：若配置 `autoResumeOnOpen=true`，Host 会尝试恢复隔离会话；
4. 恢复成功：输入框可用，可继续任务；恢复失败：显示只读恢复卡片；
5. 点「恢复隔离会话」重试；旧版迁移任务不能恢复，只保留只读记录。

> 恢复不会自动向主会话发消息，也不会自动重跑任务。

## 10. 队列

1. 同时在跑的任务数达到「并发上限」；
2. 新任务显示「排队中（第 N 位）」；
3. 前面的任务完成/取消后自动开始下一个；
4. 可取消排队中的任务；
5. 关闭「队列模式」后，没有既有队列时超限会直接返回「忙碌」；若队列里已有任务，新任务仍会排在队尾。

重启后排队中的任务也会标记「已中断」，不会自动重放。

## 11. 清理

任务详情/列表的「清理」：

- **仅删除沙箱文件**：删除该任务的任务目录，保留任务记录；
- **清理任务记录与文件**：删除记录/审计/旧日志，释放 Agent；
- **批量清理已结束任务**：只会处理终态任务，可选择是否同时删除沙箱文件；运行中/排队任务不会被批量选中。

沙箱根目录本身永远受保护；清理不会触碰主会话，也不会触碰沙箱外的文件。

## 12. 诊断与排障

### 12.1 诊断页

「诊断」页显示：

- 隔离舱核心状态/版本/协议/schema/PID；
- 数据库与二进制路径；
- 宿主兼容性（创建/恢复 Agent、沙箱策略、文件写入、会话读取、preset、HTTP、鉴权、索引注入）；
- 最近诊断日志与 stderr；
- 「重启隔离舱核心」：会中断 live 任务（标记已中断）并短暂中断面板刷新，需确认。

### 12.2 常见问题

| 现象 | 原因 | 处理 |
|---|---|---|
| 侧边栏没有隔离舱 | 插件未启用/未重启/缺 Web UI | 检查插件页与安装方式；重启；确认 profile 有 Web UI |
| `/status` 打不开 | Host 未加载/端口不对 | 用桌面版设置或 `dsh web` 打印的 URL；重启 |
| `coreStatus: missing/down/restarting/incompatible` | 二进制缺失/崩溃/版本不匹配 | 检查 `lib/bin/<platform>-<arch>/`；诊断页重启；用同一版本 Host+侧车 |
| `CORE_UNAVAILABLE` | 侧车未就绪/重启中 | 等待或诊断页重启核心 |
| 面板加载失败/令牌错误 | 页面早于插件加载/token 失效 | 重载页面；桌面版退出重开；Web 版重开 `dsh web` URL |
| 启动按钮灰色 | 未配沙箱根/主会话为空/描述为空 | 配置保存绝对路径；选择主会话 |
| 黄条「沙箱在主会话工作区内」 | 沙箱根确实在**用户主会话** cwd 内 | 移到工作区外；任务会话自身 cwd 不算 |
| 任务一直「运行中」 | 模型/工具耗时或超时 | 等或停止；检查超时设置 |
| 打开任务没有对话 | 旧版任务/会话日志被清理 | 查看旧执行记录；新任务重跑 |
| 导出目标报错 | 目标在沙箱内/非绝对路径/不存在权限 | 选沙箱外绝对目录 |
| 撤销冲突 | 目标被修改/删除，且记录有哈希可校验 | 属预期；用新复制导出重试 |
| 旧记录撤销不安全 | 旧版/无哈希记录不校验，撤销会直接删除目标；覆盖前没有备份 | 先手工备份；不要依赖旧记录撤销 |
| 两份插件入口 | bundle + patch 行同时启用 | 只留一种，重启 |
| 官方 Fork 后失去隔离 | Fork 创建了不受 setup 约束的新会话 | 不要在任务会话 Fork；回面板新建任务 |

## 附录 A：界面速查

```
侧边栏
└─ 隔离舱
   ├─ 任务：搜索/筛选/打开会话/文件/返回/导出/停止/恢复/清理/批量清理
   ├─ 新建：描述 + 子目录 + 主会话 → 启动隔离任务
   ├─ 配置：沙箱/工具/限制/导出/preset/高级
   ├─ 导出记录：目标/方式/冲突/逐项状态/撤销
   └─ 诊断：核心/兼容性/日志/重启核心

官方会话
├─ 消息流：官方渲染（工具卡片/思考/流式）
├─ 任务操作条：状态/面板/文件/返回/导出/停止/Fork 警示
├─ 头部盾牌：打开面板
└─ composer：live 时官方输入框；未恢复时只读恢复卡片
```

## 附录 B：HTTP 快速验证

令牌获取（需浏览器认证/已注入）：

1. 页面注入：`window.__DSH_IPP__.token`；
2. 或 `GET /isolation-pod/bootstrap`；
3. 或抓取同源 HTML。

调用示例：

```powershell
$token = '<token>'
$body = '{"method":"getState","args":{}}'
curl.exe -s -X POST http://127.0.0.1:<port>/isolation-pod/api `
  -H "content-type: application/json" `
  -H "x-ipp-token: $token" `
  --data $body
```

无 token 403；无 cookie 的 bootstrap 401；未知路径 404；错误方法 405；请求体 >256 KiB 413。

## 附录 C：验收清单

- [ ] 安装后 `/status`：`pluginVersion/coreVersion = "0.2.0"`、`build: 2`、`protocol/schema = 1`、
      `coreStatus: ready`；
- [ ] 未配沙箱根时启动任务被拒绝，并提示先配置；
- [ ] 配置 `E:\pod-work` 后，新建任务可打开官方会话；
- [ ] 官方会话中能看到工具卡片/思考/流式输出与任务操作条；
- [ ] 官方输入框续聊一轮，沙箱/工具限制仍在；
- [ ] 停止任务 → 状态 `cancelled`；主会话无自动消息；
- [ ] 返回主会话需手动确认，且只出现一条消息；不确认则不出现；
- [ ] 导出：复制/覆盖/跳过/重命名；复制模式撤销；有哈希记录的目标被改后撤销冲突；
- [ ] 任务运行中重启 DSH → 任务 `interrupted`；打开后可恢复并继续；
- [ ] 并发超限时任务排队，前一任务结束后自动开始；
- [ ] 主会话工作区无自动新增文件、无自动消息、无上下文污染；
- [ ] 黄条只在沙箱根确实位于**主会话**工作区内时出现；
- [ ] 清理：仅文件、记录+文件、批量；沙箱根不被删除（「只删记录」仅 HTTP `cleanup` 范围）；
- [ ] 旧 v0.1.3 数据迁移（如适用）：旧任务只读可见，`.json.bak` 存在；
- [ ] 诊断页可重启核心，任务被正确标记中断。

## 附录 D：重置与回滚

- **重置隔离舱状态**（谨慎）：退出 DSH → 备份 `<DSH_HOME>\isolation-pod\` →
  删除/改名 `pod.db` → 重启。旧 JSON 若还在会再次迁移；`.bak` 保留作回滚。
- **回滚 v0.1.3**：见 [`docs/MIGRATION.md`](docs/MIGRATION.md) §5。
- 不要在 DSH 运行中删除/编辑 `pod.db`，也不要删除仍需要回滚的 `isolation-pod.json.bak`。

## 附录 E：完成任务后

如果你不想让主会话知道任务存在：

- 不点「返回主会话」；
- 不把结果文件导出到主会话工作区；
- 只把结果留在沙箱目录，或只做清理。

此时主会话的对话历史、模型上下文和界面消息流都不会出现隔离任务相关内容。