dsh-time-machine

使用

会话标题栏面板

在任意顶层会话的标题栏右侧会出现「时光机」按钮：

• 时间线：按时间倒序列出还原点，标出自动/手动/安全点/恢复后、轮次、文件数与行数；其他会话的还原点会带标记。
• 恢复：点某一行的「恢复」，选择：
  • 覆盖文件：写回文件，不删除新增文件；
  • 精确还原：写回文件并删除新增文件（需要勾选确认）。 预览会展示写入/删除数量、行数、示例文件与警告；确认后执行。
• 新建还原点：随时手动留点。
• 设置：自动记录开关、轮前/轮后记录、保留数量与天数、快照超时、额外排除。
• 会话运行中恢复会被锁定（避免与 Agent 的写入竞争）；自动记录继续。

面板会显示最近 50 个还原点；更多可用 CLI 查看。

/rewind 命令

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

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

恢复在会话空闲时执行；恢复前的安全点、恢复后的快照 id 会显示在结果里。命令输出只给用户看，不会自动注入模型上下文；继续工作前请让 Agent 重新读取已回滚的文件。

time_machine 工具

模型可调用：

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

• 工具描述要求模型只在用户明确要求回滚时调用 restore，不得自行决定；
• 工具恢复固定为「覆盖文件」模式，不删除新增文件；精确恢复只对人类入口开放；
• 工具恢复允许发生在它自己的轮次里（模型正等待工具结果，不会与其他写入重叠）；有其他会话在同一工作区运行时仍会拒绝；
• 每次恢复前都会创建安全点。

CLI

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 才执行。
• recover 无参数时列出未完成恢复日志；--workspace --plan --yes 执行回滚。
• doctor 检查工作区记录、缺失快照对象、恢复日志、对象体积与陈旧临时索引。
• 数据目录覆盖：DSH_TIME_MACHINE_DATA_DIR；关闭自动记录：DSH_TIME_MACHINE_DISABLE=1。

HTTP 接口

面板使用的同源接口（只接受回环请求；写操作带进程内控制密钥）：

方法	路径	作用
GET	/plugins/dsh-time-machine/status?sessionId=	工作区、还原点、忙碌状态、配置、控制密钥
POST	/plugins/dsh-time-machine/checkpoint	手动还原点
POST	/plugins/dsh-time-machine/plan	计算恢复影响，返回短期计划 id
POST	/plugins/dsh-time-machine/restore	执行计划（需要确认短语 RESTORE）
POST	/plugins/dsh-time-machine/config	修改全局配置

配置

配置保存在 $DSH_HOME/.dsh-time-machine/settings.json（或 DSH_TIME_MACHINE_DATA_DIR 下的同名文件），面板设置页可改：

字段	默认	说明
auto	true	总开关；关闭后不自动记录，手动/恢复仍可用
beforeTurn	true	轮前快照
afterTurn	true	轮后快照
maxCheckpoints	120	每个工作区保留数量（最少 5，最多 1000）
maxAgeDays	14	超过天数的旧还原点进入清理
timeoutMs	30000	单条快照 Git 命令超时
restoreTimeoutMs	120000	恢复/回滚命令超时
maxRestoreFileBytes	67108864	单文件恢复上限；超过则拒绝该次计划
autoGc	true	清理旧引用后偶尔运行 git gc 回收对象
excludes	.git/, node_modules/, .dsh-time-machine/	额外 gitignore 规则

环境变量：

• DSH_TIME_MACHINE_DATA_DIR：覆盖数据目录（CLI 与宿主都读）；
• DSH_TIME_MACHINE_DISABLE：非空时关闭自动记录（手动/恢复仍可用）。