前言¶
在 DeepSeek Harness (DSH) 的开发与调试中，通过行号或原始文本定位文件行是常见操作，但文本格式变动或行号偏移容易导致定位失效。dsh-hash-edit 旨在通过为文件每行生成稳定的哈希锚点，解决文件编辑中的定位与回滚问题，确保编辑操作基于内容而非位置。
插件定位¶
这是一个为 DeepSeek Harness (DSH) 提供哈希锚定读写、替换和撤销能力的客户端插件。它通过拦截写入、遮蔽内置工具，实现对文件行的高精度操作。插件采用 MIT 许可证，由开发者 ddv12138 维护。
核心功能¶
该插件主要实现以下行为：
- 哈希锚点机制：利用 xxHash32 算法为每行生成稳定的 3 字符 base-62 锚点。锚点通过互质位图探测解决冲突，构造性保证唯一性。
- 接管编辑：插件装载后，遮蔽内置的
edit工具，并拦截write操作，自动追加锚点块以保持文件新鲜度。 - 拒绝规则：插件拒绝过期的锚点、歧义的锚点以及无效引用，绝不进行模糊匹配。
- 持久化撤销：支持
undo_last_replace，撤销记录跨重启持久化，并支持字节级还原。
安装与启用¶
这是一个 DSH bundle（插件包），用户需将其安装进特定的 profile。
# 从 GitHub 安装
dsh plugin --profile demo add github:ddv12138/dsh-hash-edit
# 从本地安装
dsh plugin --profile demo add ./dsh-hash-edit
# 从 npm 安装
dsh plugin --profile demo add @ddv12138/dsh-hash-edit
把该 bundle 的 patch 装载进 profile 后，会插入插件行，从而接管编辑行为。由于是按 profile 安装，它能在任意 preset / profile 下工作。
使用说明¶
使用该插件时需遵守以下纪律：
- 单次编辑：一个文件每条消息只允许一次编辑。
- 纯净哈希：操作时只拷贝纯净的 3 位哈希，不包含行号或上下文。
工具调用¶
插件提供以下工具：
- read (hashline)：将行转换为
HASH│content格式，支持分页，并记录已展示区间。 - replace：使用
remove_from/remove_to（纯净 3 位哈希）指定删除区间，后接replacement_text进行替换。一次调用仅支持一处修改。 - undo_last_replace：撤销最近一次替换，内容还原精确到字节。
拒绝代码¶
操作时若遇到文件状态不符或参数错误，会返回以下拒绝代码：
[E_STALE_ANCHOR]：锚点在当前文件中不存在。[E_AMBIGUOUS_ANCHOR]：锚点匹配到多行。[E_RANGE_STALE]：文件已变更或该区间从未被展示。[E_BAD_REF]：引用不是纯净的 3 位哈希。[E_UNDO_STALE]：上次替换后文件被改动。[E_FILE_TOO_LARGE]：文件超过 238,328 行或 100 MB。
技术细节与限制¶
- 算法：锚定算法为
xxHash32(canon, seed 0) >>> 14 % 238328，生成的锚点为 base-62 字符集。 - 存储：撤销记录与快照存储在项目工作区的
.dsh-hash-edit/store.json中（已 gitignore）。 - 文件限制：插件仅支持行数 ≤ 238,328 且大小 ≤ 100 MB 的文件。
结语¶
dsh-hash-edit 提供了一种基于内容哈希的健壮文件编辑方案，适合需要精确控制文件行变更且需频繁撤销的场景。更多细节可参考 GitHub 仓库 或 社区目录。
