前言¶

在 DeepSeek Harness（DSH）里跑 Agent，一轮对话往往连着多次工具调用、改动分散在多个文件里。宿主侧通常能列出「这一轮改了什么」，但 diff 多半是只读的：关掉会话后对比消失，让模型「再改回去」也不稳定——可能漏改、引入新问题，或把回滚本身再改坏。

编辑器有撤销，用户 Git 仓库有 reset，可 Agent 的改动常和用户编辑混在一起，还可能发生在你离开键盘的时候。下面介绍的 dsh-time-machine（时光机）在宿主侧用独立的影子 Git 快照，给每次有实质变化的轮次留下还原点，并支持预览影响、覆盖或精确恢复；恢复前自动留安全点，失败则自动回滚。对话上下文不会跟着倒退，但工作区文件可以按点退回。

这是什么¶

dsh-time-machine 是 DSH 工作流类插件，维护者为 PinBoDHua，当前版本 0.2.0（MIT）。它解决的核心问题是：让 Agent 对工作区的每一次改动在宿主侧可逆、可验证、可持久，而不是只靠事后检查或口头让模型撤销。

数据与影子仓库落在 $DSH_HOME/.dsh-time-machine（可用环境变量 DSH_TIME_MACHINE_DATA_DIR 覆盖）。它不修改用户仓库的 index、objects、HEAD、分支和未提交改动，只用私有 Git 目录做快照与恢复。

核心功能¶

资料中明确具备的能力如下。

1. 逐轮自动还原点：在轮次开始与结束（以及 turn/end 兜底）记录；仅在工作区内容相对上一 checkpoint 有变化时落盘；tools/pre-execute 会等待轮前快照完成，避免工具写入早于基线。
2. 持久化：重启 DSH 后仍可从时间线选择还原点。
3. 两种恢复模式：
   - 覆盖恢复：写回还原点中的文件，不删除之后新增的文件；
   - 精确恢复：写回并删除还原点之后新增的文件；.gitignore 与配置的 excludes 命中的路径始终不参与快照与恢复。
4. 恢复前预览：展示将写入/删除的文件数、行数、示例路径与警告；人类入口（面板、/rewind、CLI）可选精确模式；模型调用的 time_machine 工具仅支持覆盖恢复，且描述要求仅在用户明确要求回滚时调用 restore。
5. 安全点与失败处理：恢复前自动创建安全点；任一步失败则按安全点回滚；若回滚也失败，保留 journal，可用 CLI 或 /rewind recover 再试。
6. 多入口：会话标题栏「时光机」面板、/rewind 命令、time_machine 工具、CLI（lib/bin.js）、同源 HTTP API（仅回环请求）。
7. 工作区范围：以会话工作目录为界；若位于 Git 仓库子目录，快照根取仓库根并用 pathspec 限定子树，继承仓库根 .gitignore，但不纳入工作目录外的文件。
8. 运行时：宿主侧仅使用 Node 内建模块；需系统 PATH 上可用的 git（建议 Git 2.13+）。无 git 时插件仍会加载并给出明确错误。

安装与启用¶

前置条件：DSH >= 0.2.0-rc.2，Node >= 22.6，以及可用的 git。

官方安装方式是通过仓库内脚本写入 profile，而不是凭插件名拼接 dsh plugin add。进入插件源码目录后，先预览再应用：

cd path/to/dsh-time-machine

# 预览要改什么，不写盘
node scripts/install.mjs

# 确认后执行
node scripts/install.mjs --apply

脚本会把插件复制到 profile 的 node_modules、更新 package.json 依赖与 dsh.profile.bundles，并在写盘前备份 profile 清单到 $DSH_HOME/dsh-time-machine-backup-<时间戳>/。安装完成后需完全退出并重启 DSH，宿主侧才生效。若只改了客户端产物，可执行：

node scripts/install.mjs --sync-client --apply

查看本地与已装版本可用 node scripts/install.mjs --status。

典型用法¶

会话标题栏¶

顶层会话标题栏右侧有「时光机」按钮：时间线按时间倒序展示还原点（自动/手动/安全点/恢复后等标记）；点「恢复」可选覆盖或精确还原并先看预览；可手动新建还原点，或在设置里调整自动记录、保留数量与天数等。会话运行中恢复会被锁定，自动记录仍继续。面板默认展示最近 50 个还原点。

/rewind 命令¶

命令只作用于当前会话，不产生模型消息：

/rewind                        列出最近 10 个还原点
/rewind snapshot [备注]        立即创建还原点
/rewind restore <id>           覆盖恢复（不删除新增文件）
/rewind restore <id> --exact   精确恢复（同时删除新增文件）
/rewind recover [planId]       查看/执行未完成恢复的回滚

恢复完成后，继续工作前应让 Agent 重新读取已回滚的文件；命令输出不会自动注入模型上下文。

time_machine 工具¶

模型可调用例如：

{"action": "list"}
{"action": "snapshot", "label": "before refactor"}
{"action": "restore", "checkpointId": "20261025-142105-c3d4"}

工具侧的 restore 固定为覆盖模式，不删除新增文件。

CLI¶

与 DSH 共用同一数据目录，示例：

node lib/bin.js status
node lib/bin.js list --workspace D:/Projects/some-project
node lib/bin.js snapshot --workspace D:/Projects/some-project --label "before refactor"
node lib/bin.js restore --workspace D:/Projects/some-project --checkpoint 20261025-142105-c3d4 --mode overwrite
node lib/bin.js restore --workspace D:/Projects/some-project --checkpoint 20261025-142105-c3d4 --mode exact --yes
node lib/bin.js recover
node lib/bin.js gc --workspace D:/Projects/some-project
node lib/bin.js doctor

restore 默认只打印计划，加 --yes 才执行。关闭自动记录（手动与恢复仍可用）可设 DSH_TIME_MACHINE_DISABLE=1。

全局配置保存在 $DSH_HOME/.dsh-time-machine/settings.json，常见字段包括 auto、beforeTurn、afterTurn、maxCheckpoints（默认 120）、maxAgeDays（默认 14）、excludes 等，面板设置页也可修改。

适用场景与注意¶

适合需要长时间放开 Agent 改代码、又希望在宿主侧随时退回文件状态的 DSH 用户。同一工作区多会话共享时间线；恢复要求同工作区没有其他运行中的会话。子模块按 gitlink 处理，内部内容不纳入；目录与文件路径类型冲突时计划会拒绝，需先手动腾挪。

务必知晓的边界：对话不会随还原点倒退；被 ignore 的文件不在快照里；默认单文件恢复上限 64 MiB（maxRestoreFileBytes）；Windows 上含符号链接的写入/删除计划会被拒绝。插件以当前 DSH 进程权限运行，安装前应阅读 GitHub 源码 与 MIT 许可证，确认符合你的安全策略。

DSH 生态强调「一切皆插件」；社区目录站点 skillhub.cn 上的插件页 与 DeepSeek / 幻方无官方从属关系，仅作发现与索引用途。

结尾¶

时光机把协作方式从「信任 Agent、事后检查 diff」调整为「Agent 可放手改，文件随时可退」——靠宿主侧独立、持久的影子 Git 与恢复流程，而不是依赖模型记忆。需要细节、路线图与卸载步骤时，以仓库 README 为准：

• 目录页：https://www.skillhub.cn/plugins/PinBoDHua/dsh-time-machine
• GitHub：https://github.com/PinBoDHua/dsh-time-machine