Hashline 内容哈希编辑协议

Hashline 内容哈希编辑协议

什么是 Harness Problem

在 AI Agent 编码工具中，「Harness Problem」是指：编辑工具没有为模型提供稳定的、可验证的行标识符。模型只能依靠复述它之前看到的内容来定位要修改的行。当内容不匹配时（空白差异、编码差异、中间修改），编辑就会失败。用户看到的结果是模型被指责为「不会改代码」，但实际上是编辑工具的设计缺陷。

Hashline 协议核心

Hashline 协议通过在每次文件读取时为每一行附加内容哈希，在每次编辑时验证哈希匹配，从根源解决 Harness Problem。

读取时增强

当 Agent 读取文件时，每行从标准格式：

11: function hello() {
22:   return "world";
33: }

被增强为 Hashline 格式：

11#VK| function hello() {
22#XJ|   return "world";
33#MB| }

其中 #VK、#XJ、#MB 是基于行号和内容计算的内容哈希标签。

编辑时验证

Agent 编辑文件时引用这些哈希标签：

{
  "op": "replace",
  "pos": "22#XJ",
  "lines": ["  return \"hello\";"]
}

验证流程：

1. 系统计算目标行当前的内容哈希
2. 与 Agent 提供的哈希标签比较
3. 匹配 → 应用编辑
4. 不匹配 → 拒绝编辑，提示 Agent 重新读取文件

编辑操作类型

Hashline 支持三种基本编辑操作：

操作	描述	位置引用
replace	替换指定行或行范围	pos（必选），可选 end 指定范围
append	在指定行后插入，或文件末尾	pos（可选）
prepend	在指定行前插入，或文件开头	pos（可选）

实现架构

Hashline 的实现通常采用 Hook 增强模式，而非修改核心编辑工具：

Read Enhancer Hook

拦截 read 工具的输出，将 行号: 内容 格式转换为 行号#哈希| 内容 格式。

关键设计决策：

• 仅对文本文件生效（通过检测 行号: 内容 或 行号| 内容 格式判断）
• 跳过已被截断的行（带有截断标记的行不处理）
• 支持 <content>/</content> 和 <file>/</file> 标签包裹的内容块

Write 后的行号报告

写入完成后，Hook 自动读取文件并报告实际行数：

File written successfully. 42 lines written.

这使得 Agent 能立即了解文件的新行数，而无需再次读取。

Edit Diff Enhancer

在编辑执行前捕获文件旧内容，执行后生成统一 diff：

• metadata.diff：统一 diff 字符串（供 TUI 展示）
• metadata.filediff：结构化对象（含 additions、deletions 计数）

性能数据

根据 oh-my-openagent 的实践，仅通过更换编辑工具为 Hashline，Grok Code Fast 1 的编辑成功率从 6.7% 提升至 68.3%。

陷阱与规避

陷阱 1：并发编辑冲突

问题：Agent 读取文件后、编辑前，外部进程（用户手动编辑、另一个 Agent、git 操作）修改了文件，导致哈希不匹配。

规避：

• 哈希不匹配时不是失败，而是明确要求 Agent 重新读取
• 在 Team Mode 等多 Agent 场景中，使用文件锁或 git worktree 隔离

陷阱 2：哈希算法选择

问题：过长的哈希（如 SHA-256 全串）浪费 token，过短的哈希碰撞概率高。

规避：

• 实践中使用截断哈希（2-4 字符），在 token 效率和碰撞概率之间平衡
• 行号 + 短哈希组合已足够区分，因为行号本身提供了大部分区分度

陷阱 3：空白差异

问题：不同工具对空白的处理差异（尾随空格、制表符 vs 空格）导致哈希计算不一致。

规避：

• 哈希计算使用原始内容，不做空白规范化
• 编辑时按原文匹配，不做空白模糊化
• 在 edit 失败时明确告知 Agent 空白差异是原因

陷阱 4：二进制文件

问题：对二进制文件或非文本文件应用 Hashline 格式无意义且会破坏输出。

规避：

• 检测文件是否为文本格式（检查是否匹配 行号: 内容 模式）
• 非文本文件直接透传原始输出，不做增强

与传统编辑工具的对比

维度	传统行号编辑	内容块替换	Hashline 编辑
定位方式	行号	匹配内容	行号 + 内容哈希
漂移问题	行号变化时失效	空白差异失效	内容变化时拒绝（安全失败）
可验证性	无法验证内容	依赖精确复述	哈希验证，确定性
Token 效率	低（需复述上下文）	高	中（短哈希开销）
并发安全	无	无	有（哈希不匹配即拒绝）