# 使用指南

[English](usage.md) | 中文

## 撤回与撤销

点击用户消息复制按钮旁的箭头，确认框会显示工作目录和受影响文件。会话运行中需先停止并重新检查，其他会话不会自动停止。

选中消息及之后的对话原地撤回，文字、图片和文件回填输入框。撤销撤回会恢复此前的对话、文件及输入草稿。操作期间新编辑的草稿会保留，可稍后回填撤回内容；未发送的浏览器附件遵循宿主的草稿生命周期。

原生任务清单随同一历史截点恢复，包括任务记录内的完成状态、原话节选和验证证据。撤回到首项任务之前会清空当前清单；撤销撤回和中断恢复同样还原对应的整份记录。恢复证据不等于重新执行验证。仅保存消息、没有事件截点的旧撤销备份会保留当前任务清单。

发送新消息后，先撤回新消息，再撤销之前的操作。避免同时运行多个修改会话历史的 rewind 插件。

## 快捷键与命令

会话空闲时，在当前对话中连按两次 **Esc**，输入框上方会打开原生回退列表。也可输入 **`/rewind`** 打开相同列表；**`/undo`** 打开撤销上一次撤回的确认框。命令不会发给模型，选择消息后仍需确认。命令不接受额外参数。

列表从最近的消息开始，每页最多 100 条，可以搜索本页或翻看更早的历史，包括压缩前的消息。仅打开列表不扫描工作区、不建立额外文件快照；关闭列表保留未发送的草稿和附件。没有文件检查点的消息标记为“仅对话”。

运行中双击 Esc 保留 DSH 的停止行为，停止后再次双击可打开列表。菜单、确认框、输入法和终端优先处理自己的按键；长按 Esc 不算双击。其他插件已占用的 `/rewind` 或 `/undo` 不会被覆盖，仍可使用消息按钮和快捷键。

## 文件范围

捕获工具执行前后的文件变化，覆盖同步 Shell 和同工作区子代理。Git 工作区包含已跟踪文件和未忽略的新文件；普通目录排除 `.git`、`node_modules`。记录二进制内容、新增、删除、符号链接本身和可移植权限位。

恢复前检查文件是否有新改动，并在备份读取完成、逐个替换或删除文件前再次核对；中断恢复也遵循同一检查。无法区分的并发修改、跨工作目录的修改不会被自动覆盖。脱离工具执行的后台进程、数据库和远端操作不属于文件恢复范围。安装前或快照已过期的消息仍可仅撤回对话。

原会话日志只追加、不删除。恢复结果可跨重启保留，恢复过程不调用模型。中断事务保留备份；发现无法解决的外部改动时停止恢复，保护当前文件。

## 存储

纯聊天只建立轻量检查点，不扫描项目；文件在工具执行前捕获。未变化的内容直接复用，大文件采用 4 MiB 分块、SHA-256 去重及按需压缩。

工具执行前，备份维护和工作区锁各最多等待 30 秒。超时会返回明确错误，工具不会在没有锁的情况下继续执行；正在回退或恢复的工作区也会拒绝新工具。取消可退出尚未开始的排队，已开始的备份仍会完成收尾。无法确认归属的旧锁会保留，不会强制删除其他进程的锁。

每个会话最多保留 100 个检查点、20 次撤销记录，闲置会话的文件备份约 30 天后过期。空闲时自动回收无引用内容，并按 2 GiB 软目标滚动清理较早记录；目标包含备份内容、索引与恢复元数据。当前确认、未完成事务和最近的恢复记录优先保留，软目标本身不拒绝新备份；另有默认 4 GiB 的备份内容与索引写入上限，在共享写锁内核对实际占用，限制单次大工作区和多个实例共同产生的新增备份。达到上限停止该轮文件备份并记录缺口，正常工具继续执行。现有恢复记录不会为满足写入上限被强删；恢复元数据及整理临时副本另计。

这不是整个 DSH 目录的硬上限。工具执行前后会捕获整个可扫描工作区，未改动的文件也可能先写入备份、在空闲清理时释放，因此大工作区的瞬时占用可能超过目标。原生会话日志及临时文件系统开销另计；宿主原日志不会被删除。备份目录为 `$DSH_HOME/rewind-plus/v1`，卸载时保留。恢复期间不要手动删除该目录。

空闲清理会按时调度，短操作不会不断推迟已排定的清理；其他实例忙碌时稍后重试。写入备份包、整理备份和恢复临时文件前检查磁盘空间，保留至少 512 MiB 可用空间。空间不足时停止新增备份，不阻断正常工具，并明确记录该段文件变化无法安全回退；恢复过程中空间不足则保留中断事务。先删除无引用备份包，空间不足时延后需要临时副本的整理。工作区与备份目录通过真实路径核对，符号链接／目录联接不能绕过重叠保护。

## 更新与卸载

更新时在原 profile 中安装新的固定 Release 包，任务结束后重启对应实例。卸载可在插件管理页移除，或执行：

```sh
dsh plugin --profile web remove @gulagala001/dsh-undo-plugin
```

卸载不会删除已有备份；如仍需撤销之前的操作，请先完成恢复。不要与其他会话历史回退插件同时启用。

## 开发

```sh
npm ci
npm run build
npm test
npm pack
```

开发时使用隔离的 DSH profile。在安装目录执行 `node scripts/cleanup.mjs` 可预览清理，增加 `--apply` 手动执行。

当前发行精确适配 DSH 0.2.2-rc.1。已在 macOS 验证原生安装、恢复和浏览器交互，Windows／Linux 实机流程尚未验证。