# 隔离舱（Isolation Pod）功能需求规格说明书

| 项目 | 内容 |
|---|---|
| 文档类型 | 功能需求规格（**基线**：只描述功能行为，不含实现方案） |
| 文档状态 | 冻结：不随实现版本修订；实现与本文档的差异集中登记在别处（见 §1） |
| 读者 | 需求方、验收方、实现者 |
| 规范用语 | 「应当」「不得」「可以」 |
| 相关文档 | [`README.md`](README.md)（安装 / 原理 / 接口）、[`使用教程.md`](使用教程.md)（操作走查）、[`CHANGELOG.md`](CHANGELOG.md)（版本记录） |

## 1. 文档说明

本文档描述“隔离舱（Isolation Pod）”插件的功能需求。文档仅描述该插件应当具备的功能行为，不涉及任何技术实现方案、目录结构、运行环境或具体代码设计。所有条目使用“应当”“不得”“可以”等规范用语。

> **文档定位**：本文档是**需求基线**，不随实现版本修订。当前实现与本文档的有意差异
> （多轮对话、清理范围、撤销范围、并发与 preset 配置、平台限定、工具白名单口径）逐条列在
> [`README.md`](README.md) 的「规格与本实现的差异」一节，验收时请两份对照阅读。
>
> **验收**：逐条走查清单见 [`使用教程.md`](使用教程.md) 的附录 C（对应本文 §6）。

---

## 2. 术语定义

| 术语 | 含义 |
|---|---|
| 隔离舱 | 本插件的名称，指代该插件整体。 |
| 主会话 | 用户当前正在使用的对话会话，包含对话历史、模型上下文和界面消息流。 |
| 隔离环境 | 由隔离舱插件创建的、在主会话之外独立运行的执行环境，用于执行任务、运行代码、生成文件。 |
| 沙箱目录 | 用户手动指定的本地目录，隔离环境唯一可写入的位置。 |
| 工作区 | 主会话当前关联的项目目录或文件系统区域。 |
| 主会话无感 | 主会话的对话历史、模型上下文、界面消息流中，不自动出现任何与隔离任务相关的内容。 |
| 用户手动确认 | 由用户主动触发并明确选择的操作，不能由插件或隔离环境自动完成。 |
| 返回主会话 | 将用户选定的内容注入主会话，使其出现在对话历史或模型上下文中。 |
| 导出到工作区 | 将沙箱目录中的文件复制或移动到用户指定的工作区路径。 |
| 单次授权 | 每一次操作都需要用户重新确认，上一次确认不自动延续到下一次。 |

---

## 3. 总体目标

隔离舱插件应当为用户提供一个主会话之外的隔离执行环境。该环境可以：

1. 只读地了解主会话当前在讨论什么；
2. 自主编写并执行代码、运行命令、生成文件；
3. 将所有生成物限制在用户手动指定的沙箱目录内；
4. 默认不向主会话注入任何内容；
5. 仅在用户手动确认后，才将指定内容返回主会话，或将指定文件导出到工作区。

最终效果：

- 主会话的对话历史不被修改；
- 主会话的模型上下文不被污染；
- 主会话的界面消息流不出现隔离任务相关提示；
- 主会话的工作区不被自动写入陌生文件；
- 隔离任务对主会话默认完全不可见；
- 用户想拿回什么、想导出什么，均由用户手动决定。

---

## 4. 功能需求

### 4.1 上下文读取

1. 隔离舱应当能够读取当前主会话的历史消息，至少包括已完成的对话轮次。
2. 读取必须是只读的：不得修改、追加、删除主会话中的任何消息。
3. 读取到的上下文仅用于帮助隔离环境理解当前讨论内容，不得反向影响主会话。
4. 用户应当可以配置是否开启上下文读取，默认开启。
5. 关闭上下文读取后，隔离环境仅根据本次任务描述工作。
6. 开启上下文读取时，隔离环境应当能理解主会话中的指代、背景和已有结论，而不是将任务视为孤立的一句话。

---

### 4.2 隔离执行

1. 隔离舱应当在主会话之外创建一个独立的执行环境。
2. 隔离环境应当拥有自己的执行过程、工具调用和中间输出。
3. 隔离环境的执行过程不得写入主会话的对话历史。
4. 主会话的模型上下文中，不得自动出现任何与隔离任务相关的内容，包括但不限于：
   - 任务被触发；
   - 任务正在执行；
   - 任务已完成；
   - 任务失败；
   - 结果待查看；
   - 任何状态提示、通知或占位消息。
5. 主会话的界面消息流中，不得自动出现上述任何内容。
6. 隔离环境执行失败、超时或崩溃，不得使主会话产生任何自动消息或上下文变化。
7. 隔离环境应当拥有完成任务所需的完整能力，包括代码执行、文件读写等，但这些能力必须受沙箱规则约束。

---

### 4.3 代码与命令执行

1. 隔离环境应当能够编写并执行代码，至少支持 Python。
2. 根据配置，隔离环境也可以支持 Node.js、Shell 或其他命令。
3. 执行结果，包括标准输出、标准错误、退出码，应当在隔离环境内部可见，用于判断任务是否完成。
4. 执行过程中产生的临时文件、缓存文件、日志文件，均应当落在沙箱目录内，不得散落到工作区或其他位置。
5. 用户应当可以配置允许隔离环境使用哪些工具。未允许的工具，隔离环境不得调用。
6. 用户应当可以设置超时时间，防止任务无限运行。

---

### 4.4 文件沙箱

1. 隔离舱不得自动将沙箱目录设置在工作区、项目目录或任何默认位置。
2. 沙箱根目录必须由用户手动指定。
3. 如果用户未指定沙箱根目录，隔离舱应当拒绝执行任务，并明确提示用户先配置。
4. 沙箱目录内允许读写。
5. 沙箱目录外一律只读：隔离环境不得在沙箱目录之外创建、修改、删除或重命名任何文件。
6. 如果任务试图在沙箱外写入，隔离舱应当拒绝该操作，或将其重定向到沙箱内，并给出提示。相关提示仅出现在隔离界面，不得进入主会话。
7. 隔离环境可以读取任意路径，包括整个工作区以及工作区外的其他位置。不要求用户配置“允许读取路径”，也不禁止扫描整个工作区。
8. 用户可以为每个任务指定一个沙箱子目录，以便将不同任务的输出分开存放。
9. 沙箱根目录可以随时修改。修改后，新任务使用新目录，旧沙箱内容不受影响。
10. 沙箱目录本身可以由隔离舱创建，但位置必须来自用户手动配置，不能自动选在工作区中。

---

### 4.5 工作区文件复制到沙箱

1. 隔离环境可以自主读取任意路径，并根据任务需要将文件或目录复制到沙箱内。
2. 复制操作中，源文件只读：不得修改、删除或重命名源文件。
3. 复制目标必须位于沙箱目录内。
4. 隔离环境可以根据任务需要自主选择读取和复制哪些文件或目录，无需用户逐一指定。
5. 不要求用户配置“允许读取路径”，也不禁止扫描整个工作区。
6. 所有读取、扫描和复制行为，均不得让主会话产生任何自动消息、提示、状态更新或上下文变化。
7. 主会话不得知道隔离任务读取了什么、复制了什么。

---

### 4.6 结果返回主会话

1. 隔离环境执行完毕后，默认不向主会话返回任何内容。
2. 主会话的对话历史、模型上下文和界面消息流中，不得自动出现任何提示，包括“隔离任务已执行”“结果待查看”等占位或通知。
3. 主会话不得知道隔离任务存在过、执行过、成功或失败。
4. 用户应当可以在独立界面或独立面板中查看隔离环境的执行结果、生成的文件和完整日志。
5. 只有用户明确选择“返回主会话”时，才将指定内容注入主会话。
6. 返回内容应当可选，例如：
   - 只返回最后一条结论；
   - 返回某个指定文件的内容；
   - 返回一段摘要；
   - 返回任务是否成功。
7. 返回内容应当尽量精简，不包含完整代码、冗长日志或无关文件列表，避免再次污染主会话。
8. 用户可以选择“不返回任何内容”，只将结果留在沙箱中。此时主会话永远不知道隔离任务存在过。
9. 返回操作必须由用户手动触发，不得自动发生。

---

### 4.7 手动导出沙箱文件到工作区

1. 隔离环境在沙箱内生成的文件，默认不会自动出现在主会话工作区。
2. 用户可以在隔离界面中查看沙箱内生成的文件列表。
3. 用户可以选择一个或多个文件，也可以选择一个目录。
4. 用户必须手动触发“导出到工作区”操作，并指定工作区中的目标位置。
5. 导出操作只有在用户明确确认后才执行，不得自动发生。
6. 导出时，文件从沙箱复制或移动到用户指定的工作区路径。
7. 导出操作本身不得自动向主会话注入任何消息、提示、状态更新或上下文变化。
8. 主会话默认不知道文件已被导出到工作区。
9. 导出文件与返回主会话是两个独立操作，互不自动绑定：
   - 导出文件不自动触发返回消息；
   - 返回消息不自动触发文件导出。
10. 导出目标必须由用户指定，不得由隔离舱或隔离环境自动决定。
11. 如果目标路径已存在同名文件，应当由用户决定覆盖、跳过或重命名。
12. 导出操作不得修改沙箱内的源文件，除非用户明确选择“移动”而非“复制”。
13. 导出操作不得写入工作区以外的其他位置，除非用户明确指定了其他路径并确认。
14. 隔离环境自身不得直接写入工作区。导出动作由隔离舱在用户确认后执行。
15. 用户应当能够查看导出记录，包括导出了哪些文件、导出到了哪里、何时导出。
16. 导出操作应当可以取消或撤销，但撤销不得影响主会话，也不得自动向主会话注入消息。
17. **导出默认按单次授权处理**：每次导出都必须由用户手动触发并明确确认目标路径。
18. **不得自动延续权限**：不得因用户曾确认过一次导出，就自动允许后续导出。
19. **可选“记住本次选择”**：若提供“记住本次选择”或“本次会话内允许导出到该路径”等选项，必须由用户显式勾选，默认不开启，且用户可随时撤销。撤销后，后续导出重新回到单次确认。
20. **导出与返回相互独立**：导出文件与返回主会话相互独立，互不自动授权。用户选择返回结果，不等于允许导出文件；用户选择导出文件，也不等于允许将内容返回主会话。

---

### 4.8 配置功能

隔离舱应当提供以下可配置项：

1. **沙箱根目录（必填）**：用户手动指定，未指定则拒绝执行。
2. **是否允许文件写入**：可开关，默认允许，但限制在沙箱内。
3. **允许使用的工具列表**：用户可勾选隔离环境能调用哪些工具。
4. **超时时间**：防止任务无限运行。
5. **是否读取主会话上下文**：可开关，默认开启。
6. **返回内容策略**：用户手动返回时，可以选择返回什么。
7. **每个任务的沙箱子目录**：可选，用于分类存放输出。
8. **沙箱清理策略**：例如手动清理、按时间过期清理等。
9. **是否启用导出到工作区功能**：可开关，默认启用。启用时，导出仍必须由用户手动确认，并默认为单次授权。
10. **是否允许“记住本次选择”**：可开关，默认关闭。开启后，用户仍需显式勾选，且可随时撤销。

---

### 4.9 触发与交互

1. 隔离舱应当以单个插件的形式交付，不需要用户手动组合多个插件。
2. 用户应当可以通过一个独立入口触发隔离任务，该入口不得在主会话对话流中留下任何自动痕迹。
3. 触发时，用户至少可以传入：
   - 任务描述；
   - 可选的沙箱子目录名称。
4. 触发动作本身、执行状态、完成状态，均不得自动进入主会话的对话历史或模型上下文。
5. 任务执行期间，用户应当能在独立界面查看进度，而不是在主会话中刷屏。
6. 任务结束后，用户可以在独立界面查看结果，并手动决定是否返回主会话或导出文件。
7. 如果用户选择不返回、不导出，主会话应当保持完全无感，就像隔离任务从未发生过。

---

### 4.10 隔离与安全行为

1. 主会话的对话历史不被修改。
2. 主会话的模型上下文不被隔离任务相关过程污染。
3. 主会话的工作目录不被自动写入陌生文件，除非用户手动导出。
4. 隔离环境不得突破沙箱目录进行写入。
5. 隔离环境不得调用未授权的工具。
6. 隔离环境不得执行危险操作，除非用户明确允许。
7. 所有生成物应当可追溯、可清理、可手动管理。
8. 沙箱外只读意味着隔离环境可以读取敏感文件，但不会修改它们，也不会自动将内容带回主会话，除非用户手动返回。

---

### 4.11 可查看与可清理

1. 用户应当能查看隔离环境的完整执行记录。
2. 用户应当能查看沙箱目录中生成了哪些文件。
3. 用户应当能手动清理某个任务或整个沙箱的内容。
4. 清理操作不得影响主会话，也不得影响沙箱外的文件。

---

## 5. 权限模型总结

| 位置 | 隔离环境自身 | 用户手动操作 |
|---|---|---|
| 沙箱目录内 | 可读写 | 可读写 |
| 沙箱目录外 | 只读 | 默认只读 |
| 工作区（导出目标） | 不可写 | 用户确认后可写入，默认为单次授权 |
| 主会话对话历史 | 不可注入 | 用户确认后可注入指定内容 |
| 主会话模型上下文 | 不可注入 | 用户确认后可注入指定内容 |
| 主会话界面消息流 | 不可注入 | 用户确认后可注入指定内容 |

一句话总结：

**沙箱内可读写，沙箱外只读；读取范围不设限，写入严格限制在沙箱内；想拿回工作区或告诉主会话，必须用户手动确认；导出默认单次授权，不得自动延续；返回消息与导出文件相互独立，互不自动触发；隔离任务对主会话默认完全不可见。**

---

## 6. 验收标准

- 未配置沙箱根目录时，调用隔离舱应报错并提示配置，不得自动使用工作区或项目目录。
- 配置沙箱根目录后，执行任务“用 Python 生成一个 CSV 文件”，主会话工作区没有新增任何文件。
- 指定沙箱目录中出现了生成的 CSV 文件。
- 主会话对话历史、模型上下文、界面消息流中，没有自动出现任何与隔离任务相关的内容。
- 用户可以在独立界面查看隔离环境的完整执行记录和生成文件。
- 用户手动选择“返回主会话”后，主会话才出现一条精简结果。
- 用户手动选择“导出到工作区”后，文件才出现在用户指定的工作区路径。
- 导出文件与返回消息互不自动触发。
- 每次导出都需要用户重新确认，不存在自动延续权限。
- 若开启“记住本次选择”，仍需用户显式勾选，且可随时撤销。
- 隔离环境无法在沙箱目录之外写入文件。
- 隔离环境可以读取工作区及工作区外的任意路径，但不会修改源文件。
- 沙箱根目录可以修改，修改后新任务使用新目录，旧沙箱不受影响。
- 用户选择不返回、不导出时，主会话完全无感。

---

以上为“隔离舱（Isolation Pod）”的完整功能需求文档。全文仅描述功能行为，不包含任何技术实现方案。