Yu-Zhuang1/dsh-workspace-snapshot-fork

DSH 工作目录快照分叉

English

dsh-workspace-snapshot-fork 是一个增强 DeepSeek Harness 原生“分叉会话”功能的第三方插件。DSH 原生分叉会复制截至所选历史轮次的会话记录；本插件在此基础上，还会为新会话创建独立工作目录，并还原该分叉点对应的文件状态，而不修改原会话的工作目录。

Alpha 版本：已在 Windows 上完成 DSH Web profile 测试，尚未验证 Linux 和 macOS。

工作方式

插件为每个完成的轮次创建不可变的 Git 快照。用户在 DSH 网页端点击历史轮次的分叉按钮时，插件复制会话日志前缀，并在新工作目录中还原该轮次的文件。

| 原工作目录 | 分叉行为 |
| --- | --- |
| 普通目录 | 从私有快照仓库还原到新目录。 |
| 已有提交的 Git 仓库根目录 | 在原仓库中创建新 worktree 和 dsh/workspace-fork/ 分支，再还原快照文件；原仓库的历史、远程、hooks 和配置保持可用。 |
| Git 仓库内的嵌套目录 | 使用私有快照方式。 |
| 没有初始提交的 Git 仓库 | 使用私有快照方式。 |

分叉点的未提交修改会在 Git 子 worktree 中显示为普通工作区修改。父目录不会被修改。

环境与兼容性

- DeepSeek Harness Web profile
- Node.js ^22.19.0 或 >=24.0.0
- PATH 中可以执行 Git

| 平台 | 状态 |
| --- | --- |
| Windows | 已支持并测试 |
| Ubuntu/Linux | 尚未验证 |
| macOS | 尚未验证 |

此版本支持 DSH 0.1.1-rc.x 系列。DeepSeek Harness 仍处于开发者预览阶段，不保证升级后继续兼容。

安装

把此版本安装到 web profile：

dsh plugin --profile web add "github:Yu-Zhuang1/dsh-workspace-snapshot-fork#v0.1.0-alpha.1"

从 DSH 源码仓库运行时，在同一条命令前加 pnpm：

pnpm dsh plugin --profile web add "github:Yu-Zhuang1/dsh-workspace-snapshot-fork#v0.1.0-alpha.1"

安装或升级包后重启 DSH。本插件只面向 Web profile；官方 headless profile 没有会话分叉 RPC 和工作区注册服务。

配置

插件自带的默认配置是：

mode: workspace
storageRoot: /workspace-snapshot-fork/snapshots
childRoot: /workspace-snapshot-fork/workspaces
exclude: [.git, node_modules, .env, .env., .DS_Store]

DSH_HOME 默认是 ~/.dsh。要覆盖 Web profile 配置，请编辑 $DSH_HOME/profiles/web/cordis.patch.yml，加入完整配置：

- id: workspace-snapshot-fork
config:
mode: workspace
storageRoot: !!js dshHomePath('workspace-snapshot-fork/snapshots')
childRoot: !!js dshHomePath('workspace-snapshot-fork/workspaces')
exclude: [.git, node_modules, .env, .env., .DS_Store]

DSH 会替换整个 config，而不是逐字段合并。因此覆盖配置时必须保留所有字段。

原生分叉模式

把完整配置中的 mode 改成 native 后，新分叉会完全委托给 DSH 原生逻辑，并停止记录新快照；归档清理仍会释放已有快照。DSH 运行时会监视 profile patch，合法配置保存后无需重启即可生效。

改回 workspace 后，只有此后完成的轮次会生成快照；native 期间的历史轮次不会被补录。

安全说明

插件使用独立的快照索引，不会把源仓库的 .gitignore 当成安全规则。被源 Git 忽略的文件，只要没有匹配本插件的 exclude，仍然会进入快照。

- 请把项目特有的凭据、密钥、隐私文件和大型生成目录加入 exclude。
- 从列表中移除 .env 或 .env. 可能把凭据写入本地快照。
- 快照是本地 Git 对象，本插件不对其加密。
- exclude 是完整替换列表，不会叠加不可见的默认项。

在敏感工作目录中使用前，请阅读 SECURITY.md。

归档与清理

归档会话时，插件删除该会话的 checkpoint 映射。只有不再被任何未归档会话映射引用时，对应 snapshot ref 才会删除。子会话会继承所选父会话前缀的 checkpoint，因此父会话归档后，子会话仍能从继承的历史轮次继续分叉。

成功创建的子工作目录、Git worktree 和 dsh/workspace-fork/ 分支不会自动删除。检查其中的未提交文件后，可以这样清理 Git 子工作区：

git -C  worktree remove
git -C  branch --delete dsh/workspace-fork/

只有明确要丢弃未提交文件时才使用 --force。成功创建的普通子目录同样由用户自行管理。

卸载

dsh plugin --profile web remove dsh-workspace-snapshot-fork

从 DSH 源码运行时，在命令前加 pnpm。卸载会停止后续快照和工作目录同步分叉，但不会删除已有快照或子工作目录。卸载后还应从 $DSH_HOME/profiles/web/cordis.patch.yml 删除插件覆盖项。

已知限制

- 只支持 Web profile，没有 headless 分叉适配器。
- DSH 分叉集成与版本相关，升级 DSH 后需要重新验证插件。
- 成功创建的子 worktree 和分支需要手动清理。
- 取消归档不会恢复归档时已清理的 checkpoint。
- 只有在 mode: workspace 生效期间完成的轮次才有 checkpoint。

开发

本包没有 npm 运行时依赖。测试只调用系统中的 Git，并在临时目录中创建测试文件。

npm run check
npm test
npm pack --dry-run

致谢

感谢 Kefei Chen 在 AgentRewind/replay 项目中围绕 Git 工作区状态监控与回退机制所做的工作。相关实现经验为本插件的工作目录状态同步提供了参考。

许可证

MIT