在 DeepSeek Harness（DSH）环境中开发智能体时，处理文件编辑常面临机械可靠性问题：同一文件经过多轮对话修改，行号可能漂移；文本在不同系统间传输可能改变换行符（CRLF/LF）。模型如果依赖绝对行号或静态文本进行替换，极易出现匹配失败。
前言¶
这是什么¶
DeepSeek Harness 哈希锚点文件编辑插件（magian1127/deepseek-harness-hashline）提供 hashline_read 和 hashline_edit 两个工具。它使用 LINE:HASH 格式作为锚点，将编辑操作绑定到模型最近读取过的具体行内容。这解决了多轮修改、原子批量修改以及换行符差异导致的编辑失败问题。
核心功能¶
该插件主要包含以下能力：
LINE:HASH读取：以LINE\|HASH 内容格式读取文件。默认使用 4 位十六进制 SHA-256 前缀，结果同时报告 EOL（换行符）和 BOM（字节顺序标记）。- 三种锚定编辑：支持
set_line（设置单行）、replace_lines（替换行段）、insert_after（在行后插入）三种操作。hashline_edit的参数edits为扁平对象数组。 - 方言回收：自动识别并回收常见的畸形传参，如忘传
op（自动推断为set_line或replace_lines）、字段提升到根级等。 - 原子批量编辑：在一次调用中校验所有锚点，拒绝重叠修改，然后原子写入。
- 版本 CAS 保护：利用 DSH 文件版本机制，防止校验后到写入前的并发覆盖。
- 文本保真：保留 UTF-8 BOM、LF/CRLF 及混合换行符，不破坏文件末尾状态。
- 失效恢复：哈希匹配失败时自动重定位到附近行，或报错回显真实锚点。
- 原生结果卡片：读取复用 DSH 原生
ReadBlock，编辑显示原生风格 diff 卡，删除/新增行以灰色 gutter 标记。 - 可逆严格替换：开启“替换内置读写”后，Agent 使用严格锚定的
read/edit，智能体操作更安全。 - 提示词中文化：可配置将工具说明、错误消息等文案改为中文。
安装与启用¶
DSH 的 bundle 按 profile 隔离，Web GUI、Open Design 和 Headless 模式需分别安装。
- Web GUI 模式
node bin/dsh-hashline.mjs install --profile web --link $PWD
- Open Design 模式
dsh plugin --profile open-design add "link:$PWD"
- Headless 模式
dsh plugin --profile headless add "link:$PWD"
注意：--link 参数必须指向本插件源码目录。安装后可使用 node bin/dsh-hashline.mjs status --profile web 等命令确认状态。
典型用法¶
读取文件时，使用 LINE|HASH 格式：
LINE\|HASH 3a2f1b 这是被锚定的内容
进行编辑时调用 hashline_edit，参数 edits 为扁平对象数组：
- 基础编辑：指定
op（可选）、anchor（锚点文本）和new_text（新文本）。
{
"edits": [
{
"op": "set_line",
"anchor": "LINE|HASH 3a2f1b",
"new_text": "新的内容"
}
]
}
- 方言简化：若不传
op，系统自动按形状推断：- 带
anchor+new_text->set_line - 带
start_anchor+end_anchor+new_text->replace_lines
- 带
若传入 old_string 或 replace 等非锚定字段，操作会被拒绝并提示改用内置 edit。
适用场景与注意¶
- 适用场景：需要高可靠性文件编辑的场景，特别是多轮对话维护同一文件，或需要确保文本格式（如保留 BOM）不被破坏时。
- 注意：
- 测试阶段：当前仍处于测试（experimental）阶段，接口、配置项和行为可能随时变更，请勿用于正式项目。
- 权限要求：Web GUI 配置卡片要求 DSH 包含
settings.register(..., { exposeToClients: true })。 - 数据安全：插件不上传数据、不维护独立数据文件。
总结¶
该插件通过哈希锚定机制，解决了 DSH 环境下文件编辑的机械可靠性问题，提供了原子性、保真度和自动容错能力。目前处于测试期，适合在隔离环境验证其稳定性与行为。
