# 更新日志

本项目的所有重要变更都记录在此文件。

## 书写约定

- 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循
  [语义化版本](https://semver.org/lang/zh-CN/)。
- 小节固定为 **新增 / 变更 / 修复 / 移除 / 文档 / 安全 / 说明**；没有内容的小节省略。
- 每个版本先写摘要（这一版解决什么问题、影响谁），再分小节。
- 版本一致：`package.json`、`core/Cargo.toml`、`lib/version.js` 的 `PLUGIN_VERSION`、
  本文件标题，以及附注标签 `vX.Y.Z`。协议/schema 与 [`docs/PROTOCOL.md`](docs/PROTOCOL.md) 一致。
- 已发布的版本段落视为历史记录，只追加更正说明，不改写原文。
- Host 半每次改动递增 `lib/version.js` 的 `BUILD`；Client 半改动不需要单独构建号。

## [0.2.0] - 2026-10-17

**破坏性重构版本（Host `build: 2`）**：把 v0.1.x 的「单文件 JS + JSON 状态 + 自绘转写面板」
重写为 **Rust 侧车 + JS Host 薄壳 + DSH 官方会话界面** 三层结构。持久化迁移到 SQLite；
隔离任务改为普通根会话；新增队列、重启恢复、导出校验/备份/撤销、跨平台文件操作、
中英文界面、CI 与 bundle 安装。

从 v0.1.3 升级请先读 [`docs/MIGRATION.md`](docs/MIGRATION.md)；架构见
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)，契约见 [`docs/PROTOCOL.md`](docs/PROTOCOL.md)。

### 新增

- **Rust 侧车 `core/`**（`isolation-pod-core`，release 二进制）：
  - stdio NDJSON JSON-RPC；stdout 只承载协议帧，stderr/文件日志走诊断；无网络监听；
  - SQLite WAL，schema `1`：`meta/config/tasks/task_audit/legacy_log/exports/export_items`；
  - 任务状态机（`queued/starting/running/completed/failed/timeout/cancelled/interrupted`）、
    FIFO 队列、`maxConcurrent`、每轮截止时间、租约心跳与 `STALE_LEASE`；
  - 宿主重启时把进行中/排队任务标 `interrupted`、运行中导出标 `interrupted`、清除旧租约；
  - 跨平台沙箱路径策略：绝对根归一化、分段包含判断、任务目录 `<root>/<subdir?>/<taskId>`、
    子目录/保留名/符号链接/联接点/长路径处理；
  - 文件清单/预览：深度 8、最多 2000 项、UTF-8/UTF-16 BOM、二进制识别、`previewBytes` 上限；
  - 导出：复制/移动、覆盖/跳过/重命名、BLAKE3、覆盖前备份、撤销哈希校验、5000 文件 /
    2 GiB / 单文件 1 GiB 上限；
  - v0.1.3 `isolation-pod.json` 一次性迁移（含旧日志、`.bak` 重命名、损坏容错）；
  - panic 兜底、诊断环、日志轮转（1 MiB → `core.log.1`）、`--version` / `--check`。
- **Host 薄壳 `lib/`**：
  - `core-client.js`：二进制发现、spawn、NDJSON 拆帧、超时、stderr 环形缓冲、握手、
    崩溃退避重启、shutdown；
  - `agent-runtime.js`：普通根会话创建/恢复、隔离 setup、preset 挂载、工具 guard、
    沙箱自检、首条 `任务：<描述>` 消息、turn 观察、外部 resume 安全网；
  - `state.js`：任务缓存/索引、live 句柄、诊断、revision；
  - `api.js`：`/status`、`/bootstrap`、令牌 API、18 个方法、沙箱位置判定、`returnToMain`；
  - `paths.js`：与侧车一致的同步路径判定；
  - `version.js`：版本/协议/schema/构建号/token 头/路由前缀。
- **官方会话界面**：任务会话通过 `uiWorkspace.openSession` 打开；官方消息流/工具卡片/
  输入框直接复用；注入 `conversation.input.dock` 任务操作条、`conversation.session.header.utilities`
  入口、`conversation.composer`（priority −5）只读恢复卡片；中英文 locale、主题 token、
  ErrorBoundary、轮询 2s/5s、令牌恢复链。
- **任务队列与重启恢复**：超并发自动排队；重启后可 `resumeTask`/`openTask` 恢复；
  `autoResumeOnOpen` 控制打开时是否自动恢复。
- **导出记录与撤销**：每次导出逐项记录；复制模式可撤销；覆盖前备份；撤销冲突检测。
- **bundle 与发布**：`cordis.patch.yml` + `dsh.bundle.patch` + `dsh.client` + `locale/` +
  `icon.svg`；`scripts/check-version.mjs`、`scripts/package.mjs`、`scripts/fetch-core.mjs`；
  GitHub Actions CI/Release（Windows/Linux/macOS 侧车 + Client + 校验和）。

### 变更

- **平台**：插件自身目录/导出/清理不再依赖 PowerShell，改为 Rust；DSH 文件沙箱仍是模型工具
  写入的权威边界。
- **会话模型**：任务的隔离会话从 `origin:'subagent'` 子会话改为**工作区之外的普通根会话**；
  不向主会话写消息，但可被官方 UI 打开、续聊、重启恢复。
- **存储**：`isolation-pod.json` → `<DSH_HOME>/isolation-pod/pod.db`；Host 只保留内存缓存。
- **HTTP**：`/status` 结构与方法表重写（新增 `coreStatus/protocol/schemaVersion/coreVersion/
  dbPath/binaryPath/compat`）；旧 `getTask`/`followUp` 移除。
- **配置**：新增 `queueEnabled`、`maxTasks`、`maxExports`、`retentionDays`、`previewBytes`、
  `previewChars`、`exportVerify`、`sandboxProbeMode`、`autoResumeOnOpen`、`logLevel`；
  `presetId` 默认由 `'standard'` 改为空串；`allowedTools` 默认增加 `bash`。
- **安装**：推荐 bundle；patch 行保留为开发/回退方式；两者不可同时启用。
- **文档**：README/EN/教程/架构/协议/迁移/NOTICE 全套重写。

### 修复

- **主会话位置误报**：打开任务后官方主视图会停在任务会话上，其 cwd 就是沙箱根；旧逻辑把它当
  “当前主会话”，导致沙箱根与自身比较，误显示「沙箱在当前会话工作区内」。现在 Client 只选择
  用户主会话（排除 pod 任务会话与 subagent 会话），Host 收到 pod 会话 ID 时解析回任务的
  `mainSessionId`；黄条文案改为「主会话工作区」。只有当主会话 cwd 确实包含沙箱根时才提示。
- **预览字节上限未接线**：`previewBytes` 之前只出现在配置 UI；现在侧车 `files.read` 按该值
  拒绝过大文件，`previewChars` 仍控制字符截断。
- **v0.1.x 的 PowerShell 文件操作**：目录/导出/清理改为 Rust 标准库，Linux/macOS 可用。
- **JSON 状态写坏/并发**：改为 SQLite WAL + 事务；崩溃后不会留下半写 JSON。
- **超并发直接失败**：改为默认 FIFO 队列。
- **重启后不能续聊**：任务会话改为可恢复的普通根会话。
- **路径逃逸/链接穿越**：侧车每次路径判断归一化并拒绝越界/链接穿越。
- **导出无校验/无冲突处理**：新增 BLAKE3、`exportVerify`、覆盖备份与撤销冲突检测。
- **旧记录不可见**：迁移任务以 `legacy:true` + `task.legacyLog` 只读展示。

### 移除

- 移除 v0.1.x 的 JS 执行引擎、JSON 持久化、PowerShell 文件操作、`followUp`/`getTask`
  HTTP 方法与自绘转写面板。
- 移除 `origin:'subagent'` 的任务会话形态；改为普通根会话。
- 移除 DSH 0.1.7 适配代码；v0.2.0 只支持 DSH 0.2.1+。

### 文档

- 重写 [`README.md`](README.md) / [`README.en.md`](README.en.md) / [`使用教程.md`](使用教程.md)：
  安装（bundle + patch）、官方会话、任务/队列/恢复、返回/导出/撤销、配置、HTTP、数据布局、
  平台、已知限制、故障排查、开发/发布、验证矩阵、规格差异。
- 新增 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)、[`docs/PROTOCOL.md`](docs/PROTOCOL.md)、
  [`docs/MIGRATION.md`](docs/MIGRATION.md)、[`NOTICE.md`](NOTICE.md)。
- `需求说明.md` 作为冻结基线保持不变；实现差异在 README 维护。

### 安全

- **主会话零自动写入**：任务创建/运行/失败/超时/取消都不自动写主会话；唯一入口是用户确认的
  `returnToMain`（单条 user 消息）。
- **沙箱双层**：模型工具由 DSH 文件沙箱硬拒绝；侧车自身的文件/导出按 Rust 路径策略判定。
- **启动前越界写探针**：沙箱外写入被允许时任务不启动；`skipped-no-parent` 仅限盘符根。
- **导出**：目标必须在沙箱外；每次单独确认；覆盖前备份；撤销哈希校验；不自动延续授权。
- **HTTP**：每次激活随机 token、索引注入、bootstrap 浏览器认证；`/status` 不返回完整 token（仅前 8 位前缀）。
- **侧车**：无网络、stdio、参数化 SQL、协议限额、不记录文件内容/主会话上下文/token。

### 说明

- **破坏性变更**：状态文件、HTTP 方法、会话模型、安装方式均变化；升级前读迁移文档并备份
  `<DSH_HOME>\isolation-pod.json`。
- **DSH 版本**：要求 0.2.1+；0.1.7 不再支持，v0.1.3 是 0.1.x 最后版本。
- **二进制**：Windows x64 已随仓库提供；其他平台由 CI 产出。未做代码签名。
- **已知限制**：官方 Fork 会脱离隔离 setup；DSH 临时目录在 workspace-write 下可写；旧版任务
  只读；任务会话可能出现在会话搜索但不在 workspace 列表；Linux/macOS 未做本机面板验收。
- **验证**：Rust 51 lib + 4 integration；Host 64/64；Client 41/41；真实侧车 e2e 4/4；
  `check-version`、打包与校验和通过。详见 README 验证矩阵。

## [0.1.3] - 2026-09-25

修复 v0.1.2 引入的工具面回归：隔离 Agent 的工具面被误判为空，pod 一个工具都用不了。
只有 Host 半与文档变更（`build: 8`）。

### 修复

- **工具面被误判为空**：v0.1.2 用 `agentCtx.tools.schemas()` 取面并与白名单求交，但省略 scope
  得到全局面，与 preset 分层工具没有交集，`task.allow` 被清空。现在：
  1. 以该 pod 的 agent 为 scope 调 `schemas(agent)`；
  2. 白名单只作上限，不再与 preset 求交；
  3. 以 pod 的 `request/header` 覆盖启动期探测；
  4. 面板分开显示「白名单上限」与「隔离环境实有工具」。
- **离线用例**：桩上下文驱动真实 HTTP 路由，验证只以 agent 为 scope、白名单不被清空、
  `request/header` 覆盖工具面。

### 说明

- 升级后必须重启一次应用（Host 改动，`build: 8`，Node URL 缓存）；Client/patch 改动可热生效。
- 配置无需迁移：`allowedTools` 仍是白名单。
- v0.1.3 上的产物链路（生成文件 → 导出/撤销）未复测；由 v0.2.0 的 Rust 实现与 e2e 覆盖。

## [0.1.2] - 2026-09-25

适配 DSH **0.1.7**，修复三处会让插件完全不可用的接口变更、一处沙箱根边界问题，
并补齐桌面版令牌通道（Host 累计 `build: 7`）。

### 修复

- **`ctx.shell.run` → `ctx.shell.execute`**：创建任务目录、导出、清理改用 0.1.7 的
  shell 句柄 API（`resolve` + `execute` + `handle.result()`）。
- **令牌投递**：桌面版页面由 Electron 直接发出，不经过 `webServer.renderIndex()`，旧 `tapIndex`
  不执行；改为 `webserver/index-inject` 的 `{kind:'global'}` 结构化行。
- **`followup` 消息形状**：`MessageSource` 闭合联合，来源改为 `{kind:'user'}`。
- **主会话识别**：0.1.7 会话列表不再有 `current` 字段；改用 `retainedBy.mainView > 0` 解析，
  并保留旧字段兜底。
- **沙箱根归一化/探针边界**：尾部反斜杠会让探针落回沙箱内，导致任务被误中止；现在写入/读回
  都归一化，盘符根标记 `skipped-no-parent` 并跳过探针。
- **客户端令牌恢复**：新增 `/bootstrap`、同源 HTML 抓取与单次重载路径；面板不再停在「加载中」。

### 新增

- `GET /isolation-pod/bootstrap`：对已认证浏览器页面返回 token；无 cookie 401。
- 面板显示「隔离环境实有」工具面、preset 挂载失败的 setup 提示。
- `/status` 增加 `pluginVersion` 与 `compat`（shell/indexInject/bootstrap）。

### 说明

- 需要重启一次应用加载新 Host（`build: 7`）；Client/patch 可热生效。
- 白名单与 preset 求交的实现在 0.1.3 被修正（见上）。

## [0.1.1] - 2026-09-15

面板可直接预览沙箱生成的文件内容；补齐 `LICENSE` 与英文文档。仅 Client/文档变更
（Host 未改，`build: 5`）。

### 新增

- 「生成文件」列表每个文件新增「预览」：等宽、可滚动、显示字节数、截断提示；
  单文件 ≤300 KB、每次最多 20000 字符。

### 文档

- 新增 `LICENSE`（MIT）与 `README.en.md`；中英文 README 互链；教程补充预览上限。

### 说明

- `git pull` 后浏览器自动重载面板，无需重启 dsh。

## [0.1.0] - 2026-09-14

首个可用版本：常驻 DSH 插件，在主会话之外运行受沙箱约束的隔离任务；主会话默认完全无感，
返回与导出均需手动确认。

### 新增

- **隔离执行**：每个任务创建独立子会话（`origin:'subagent'`，cwd=沙箱根）；setup 写入
  `sandbox/mode`、`approval/policy`，挂载 preset、guard 与系统提示段。
- **越界写预检**：沙箱外探针必须被拒绝才放行；失败记录 `fsDenied`。
- **工具白名单**：`tools.guard()` 权威；`restrict()` 补充；write/edit 路径归属校验。
- **HTTP**：`/status`（本地诊断）与 `/api`（14 个方法、token 门禁）。
- **持久化**：`<DSH_HOME>/isolation-pod.json`（临时文件+rename，800ms 防抖）；
  重启把 running 任务标 `interrupted`。
- **执行记录**：会话事件折叠为转写（user/prompt/assistant/tool/turn/reasoning）；
  内存 500 条/任务、落盘 80 条；可用 `sessionQuery.readSession` 回填。
- **多轮对话**：`followUp` 向同一常驻子 Agent 续发；每轮独立超时与停止。
- **面板**：侧边栏入口 + 四页签（任务/新建/配置/导出记录）；自绘对话视图。
- **返回主会话**：`previewReturn` 生成可编辑预览，`returnToMain` 注入一条消息。
- **导出**：复制/移动、覆盖/跳过/重命名；每次确认；复制可撤销。
- **令牌自愈**：403 时重抓同源 HTML token 重试。
- **沙箱告警**：沙箱根落在当前会话工作区内时提示。

### 安全

- 主会话默认零痕迹；唯一入口是手动 `returnToMain`。
- 沙箱外写入由 DSH 文件沙箱硬拒绝；清理不触碰主会话与沙箱外文件。
- 导出目标必须在沙箱外；每次导出重新确认，不自动延续授权。

### 已知限制

- 平台：Windows 专有（PowerShell 文件操作）；macOS/Linux 未验证。
- 需要带 Web UI 的 profile；不适合写入 home 级 patch（会作用于所有 profile）。
- Windows shell 沙箱为 `partial`（ACL 受限令牌）；文件系统沙箱为硬拒绝。
- 多轮对话不跨进程；重启后旧任务只能查看/导出。
- 面板只列文件清单，不做内容预览（0.1.1 提供）。

[0.2.0]: https://github.com/Teow9/dsh-isolation-pod/compare/v0.1.3...v0.2.0
[0.1.3]: https://github.com/Teow9/dsh-isolation-pod/compare/v0.1.2...v0.1.3
[0.1.2]: https://github.com/Teow9/dsh-isolation-pod/compare/v0.1.1...v0.1.2
[0.1.1]: https://github.com/Teow9/dsh-isolation-pod/compare/v0.1.0...v0.1.1
[0.1.0]: https://github.com/Teow9/dsh-isolation-pod/releases/tag/v0.1.0