前言¶
在 DeepSeek Harness（DSH）里跑智能体会话时，常见情况是：某一轮回答方向不对，但后面几轮已经叠在上面；若只在当前会话里「截断重来」，原对话和证据一起消失，也不方便对照。另一种做法是手动改文件、开新会话，成本高且容易漏改。
dsh-rewind-branch 针对的是「这一轮想当作没发生过，但不想丢掉原会话」的需求：在每轮回答结束后提供 Rewind to before this prompt（回到这轮提问前），把该轮经 DSH 文件工具改过的文件恢复到提问前，再从该消息边界 fork 出新分支会话并切过去；来源会话保持原样。
这是什么¶
- 定位：DSH 工作流类插件，按轮次做「文件回退 + 会话分支」，不依赖 Git 仓库即可完成工作区文件恢复。
- 维护者：shutongcao1-design（仓库 shutongcao1-design/dsh-rewind-branch）。
- 社区目录：SkillHub 插件页（独立社区目录，与 DeepSeek / 幻方无官方从属关系）。
当前 package 版本为 0.1.0，许可证 MIT。
核心功能¶
每轮尾部动作¶
每一轮助手回答结束后，在该轮回复下方会出现动作 Rewind to before this prompt。点击后流程为：
- 向 Host 请求一份 plan：该轮改动了哪些文件、新建了哪些、是否存在冲突、有哪些风险；
- 你确认后，先把当前内容做备份，再把这些文件恢复到该轮提问之前的状态；
- 在该消息边界 fork 出新分支会话并切换过去。
原会话不会被删除：日志、消息与后续 continuation 都保留。新分支保留到 rewind 点之前的对话内容。
为何分支而不是原地回退¶
原地回退会截断当前会话。分支保留原会话作为对照，回退仍可逆——旧会话仍可继续或对比。文件恢复不要求 Git：Host 在 DSH 文件工具写入前把目标文件的 pre-write 字节写入内容寻址存储；无仓库或存在无关未提交改动的工作区，也可按文件逐条恢复，而不是 reset 整个仓库。
捕获范围与限制¶
会捕获（每文件 pre-write 字节与 post-write 快照）：write、edit、str_replace_editor、multi_edit 等通过 DSH 写文件的工具。
不会捕获：bash、pwsh、终端工具、run_code 等 shell/代码执行器。若所选轮次跑过这类工具，预览会告警，其改动的文件不会恢复；已捕获的文件仍会恢复。
此外：符号链接、目录、大于 4 MiB 的文件会跳过；文件 mode、ACL、硬链接、子模块内容不恢复。
冲突与安全¶
- Host 将当前文件与最新 post-write 快照对比；若不一致（手改或 shell 改过），该文件跳过并列入冲突，不会覆盖。
- 写入前当前内容备份到
<data>/safety/<timestamp>/（manifest.json与各文件.bin）。 - 确认对话框打开期间若文件再变（TOCTOU），会重新校验，变更文件跳过而非覆盖。
- 写入经临时文件再 rename，避免半写覆盖好文件。
数据目录：<DSH_HOME>/dsh-rewind-branch/（journal.jsonl、blobs/、safety/）。部分 Desktop 构建若 Host 未继承 DSH_HOME，则落在包旁的 data/。journal 仅追加，约 64 MB 轮转（journal.1.jsonl）。
HTTP 路由 /preview、/rewind、/client.js 仅同源；非本 profile 认证页面请求会 403。插件不做外网调用；恢复仅在 Host 进程内、在你点击确认后，且只触及 journal 中为该轮记录的绝对路径。
安装与启用¶
要求 DeepSeek Harness 0.2.1-rc.3 或更新（在 dsh.engines 中声明）。无依赖、无构建步骤，纯 JavaScript。未发布到 npm，需从 GitHub 安装。
dsh plugin --profile <profile> add "git+https://github.com/shutongcao1-design/dsh-rewind-branch.git"
dsh plugin 会安装包并选中 bundle。安装后需完全退出 DSH 再启动（完整 quit，不是只刷新页面），以便 Host 侧启动且轮尾动作到达客户端。
插件以当前 DSH 进程权限运行；安装前建议自行查看仓库源码与 MIT 许可证。
典型用法¶
- 等待某一轮 agent 回答结束，会话处于 idle。
- 在该轮回复下方点击 Rewind to before this prompt。
- 审阅 plan：待恢复文件、待删除文件、冲突与警告。
- 点击 Confirm——文件恢复并打开新分支会话。
注意：
- 会话的第一轮没有更早 checkpoint，不能回退。
- 正在运行的轮次会拒绝回退（
session-running），需等结束。 - 插件安装前或禁用期间产生的轮次没有快照。
- 若该轮做过 Git commit，commit 仍会保留，预览会提示；插件不改动 Git index、HEAD、refs 与 commits。
适用场景与注意¶
适合：想从某一轮提问前重新试路径，又希望保留原会话完整记录；工作区未必是 Git 仓库，或不想用 reset 搅乱无关改动；主要依赖 DSH 内置文件工具改代码的场景。
局限：shell/终端/代码_runner 造成的改动无法自动回退；大文件与目录结构类变更不在捕获范围内；仅 DSH Web 客户端与 DSH Desktop（提供 Web GUI 的部署）兼容。
DSH 生态理念是「一切皆插件」；本插件属于社区工作流扩展，可按 SkillHub 目录页与 GitHub README（含 README.zh.md）核对细节。
结尾¶
dsh-rewind-branch 把「这一轮文件状态」和「会话历史」拆开处理：文件按轮次快照恢复，对话在原会话保留并在边界 fork 新分支继续，适合需要可逆试错、又不想丢上下文的 DSH 开发工作流。
- 目录页：https://www.skillhub.cn/plugins/shutongcao1-design/dsh-rewind-branch
- GitHub：https://github.com/shutongcao1-design/dsh-rewind-branch
