前言¶
DeepSeek Harness (DSH) 智能体在执行过程中会频繁修改文件或调用 Shell 命令（如 sed -i、rm 等）。现有的回滚插件往往只能捕获回合边界的快照，或者只能识别文件编辑工具的参数，无法记录 Shell 命令产生的副作用。这导致一旦操作出错，难以精确还原到某个步骤之前的状态。dsh-zcode-rewind 旨在解决这一痛点，提供细粒度的、基于工具调用的检查点系统。
插件简介¶
dsh-zcode-rewind 是 DeepSeek Harness 的一个工作流插件，由 BOWLUNA 维护。它为 DSH 提供了 per-tool-call 工作区检查点功能，能够捕获每一次文件变更和 Shell 命令，以内容寻址的方式存储 Blob，并提供行级差异预览和可逆的还原操作。
核心功能¶
该插件的核心能力集中在以下几个方面：
- 全量捕获：捕获所有 mutating tool call，包括 bash、pwsh、write、edit、MCP 工具以及 subagent 工具。
- 记录变更：记录文件的删除、创建和修改，并为每个路径附带可恢复的先前内容哈希。
- 内容寻址：存储内容寻址的文件内容（SHA-256），实现跨会话和跨工作区的去重。
- 持久化日志：提供按条目顺序排列的持久化变更日志，重启 DSH 后依然存在。
- 操作支持：支持手动创建检查点，以及 undo/redo 操作。
安装与前置条件¶
安装前，请确保环境满足以下要求：
- Node.js >= 20.0.0
- DSH >= 0.1.5-alpha.1
安装命令如下：
dsh plugin --profile web add dsh-zcode-rewind
安装完成后，需要重启 DSH 才能使插件生效。可以通过 dsh --profile web --dump-config | grep workspace-rewind 验证插件是否已正确绑定。
使用方式¶
插件提供了一系列工具命令来管理检查点。以下是主要工具及其用途：
rewind_now：创建一个手动检查点，例如在执行高风险操作前。rewind_list：列出最近的记录，按时间倒序排列，显示 ID、时间、工具类型以及变更统计（+added ~modified -deleted）和路径样本。rewind_diff：预览还原计划及行级统一差异，此操作不会实际修改文件。rewind_restore：执行还原操作。mode=revert用于撤销单条记录；mode=asof用于将工作区恢复到某个检查点的时间状态。rewind_undo：撤销上一次还原操作，重复执行可切换 undo/redo 状态。rewind_status：显示存储统计信息，包括记录数、Blob 数、字节数、配额和当前配置。
配置项¶
插件支持通过配置文件调整行为。以下是一个典型的配置示例：
- insert:
- id: workspace-rewind
name: 'dsh-zcode-rewind'
config:
capture: all # 捕获模式：all | fileTools | off
maxFileBytes: 8388608 # 单文件最大字节数，超过仅记录事件
maxFiles: 20000 # 单次遍历文件数量上限
maxTotalBytes: 536870912 # 存储总字节数上限，旧 Blob 会自动清理
keepRecords: 500 # 日志保留条目数阈值
excludes: ['.git', 'node_modules', 'dist']
secretNames: ['.env', '*.pem', '*.key']
注意事项¶
- Shell 副作用捕获：与市场上其他 rewind 插件不同，本插件能捕获 Shell 命令的副作用（如
sed -i），因为其采用指纹差异对比而非解析参数。 - 检查点粒度：捕获是基于“每次工具调用”，而非“回合边界”，因此能更精确地定位问题。
- 存储位置：存储目录位于
$DSH_HOME/workspace-rewind/，位于工作区之外，不会污染 Git 仓库。 - 去重机制：由于使用 SHA-256 内容寻址，相同的文件内容在多次修改中只占用一份存储空间。
总结¶
dsh-zcode-rewind 为 DeepSeek Harness 提供了细粒度的、可逆的工作区状态管理能力。对于需要高可靠性和精确控制回滚范围的智能体开发场景，该插件是一个实用的工具。其详细文档与源码位于 GitHub。
