前言¶
在 DeepSeek Harness (DSH) 的开发环境中，智能体经常需要执行复杂的多文件重构、运行破坏性 Shell 命令或安装依赖。当意外发生回归或工作区状态损坏时，手动使用 Git 回滚不仅过程繁琐，还存在丢失未跟踪文件或破坏用户历史记录的风险。
dsh-time-machine 是为此类场景设计的 DSH 插件。它提供了一套智能检查点、工作区安全卫士和即时回滚机制，能够在后台创建轻量级的影子 Git 快照，确保工作区状态的完整性和可恢复性。
核心功能¶
该插件提供以下核心能力：
- 轻量级影子 Git 快照：在后台捕获全量工作区、暂存区及未跟踪文件，使用隔离的 Git 影子树引用，不干扰用户的提交历史、当前分支或暂存区。
- 即时安全回滚：支持将整个工作区或特定文件恢复到任意历史检查点，使用非破坏性
checkout-index操作，不移动HEAD或重写分支历史。 - 可视化快照差异检查器：提供文件级的视觉差异对比，高亮新增、删除和修改的行，并显示统计信息。
- 交互式侧边栏与设置时间轴：集成于 DSH Web UI 的侧边栏和设置标签页，以时间轴形式展示会话检查点，支持一键回滚、差异查看和删除操作。
- 命令失败自动修复：当工具或命令执行失败时，自动记录检查点以保留恢复选项。
- 选择性文件回滚与暂存安全卫士：支持单文件恢复，并在高风险操作前自动创建检查点，保护用户暂存的 Git 索引。
安装¶
使用官方命令安装该插件：
dsh plugin --profile web add @goodandready/dsh-time-machine
配置¶
在 DSH 的配置文件中添加以下内容以启用自动快照和回滚提示：
dsh-time-machine:
autoSnapshotEnabled: true # 在文件修改前自动创建检查点
maxSnapshots: 20 # 内存中保留的最大滚动检查点数量
autoHealPrompt: true # 命令失败时提示回滚
工具参考¶
插件为 Agent 提供了以下工具，可用于程序化控制：
time_machine_checkpoint_create- 描述：在执行高风险编辑或操作前创建影子 Git 工作区检查点。
- 参数：
label?: string, sessionId?: string
time_machine_checkpoint_list- 描述：列出最近的会话检查点（按时间倒序）。
- 参数：
sessionId?: string
time_machine_checkpoint_rollback- 描述：将工作区文件恢复到指定检查点。
- 参数：
id: string, confirm: boolean
time_machine_diff- 描述：计算当前工作区与目标检查点之间的统一文件差异。
- 参数：
from: string, to?: string
time_machine_checkpoint_delete- 描述：永久删除单个检查点并清除其 Git 引用。
- 参数：
id: string, confirm: boolean
time_machine_checkpoint_prune- 描述：清理会话检查点，仅保留最新的 N 个。
- 参数：
sessionId?: string, keep?: number
注意事项¶
- 运行环境：插件以当前 DSH 进程权限运行，安装前请检查源码与许可证。
- 依赖要求：需要 Node.js 20 或更高版本。
- 版本更新：
- v0.1.16：安全加固与侧边栏标签去重。修复了在特定环境下侧边栏重复注册的问题，并严格限制了 REST 路由的 HTTP 方法（仅 POST 用于修改，GET 用于读取）。
- v0.1.15：选择性文件回滚与暂存安全卫士。新增单文件恢复工具
time_machine_file_rollback及/rollback-file路由。
