hashline — 用内容锚点，而不是脆弱行号，改代码

简介

AI 编码助手的 edit 工具有一个根本矛盾：模型用行号描述改哪里，但行号在真实世界里极不稳定。用户随手改文件、上一轮 edit 插入删除、未读全文件却对「以为存在」的行号下手，都会造成静默写错。

@piex-dev/hashline 用内容锚点覆盖 pi 内置 edit：读时打 tag、改时校验，拒绝未见过的行。

技术原理

读文件时注入 [path#TAG] 并记录 seen-lines；编辑必须携带同一 tag。全文件 4-hex tag 像乐观锁：任意外部改动即失效，强制 re-read。相对逐行哈希更严，但换来 tree-sitter 块操作与 boundary repair。

[src/main.ts#A3F2]
SWAP 2.=2:
+const x = 2;

Phase 1 容错：连续 3 次 byte-identical noop → [E_NOOP_LOOP]；成功后同 payload 且文件未变 → [E_DUPLICATE_EDIT]；CRLF / 代码块围栏等方言归一化。

使用说明

安装

pi install npm:@piex-dev/hashline

安装后即生效：hashline 覆盖 pi 内置 edit 工具，并 hook read 结果。无需额外开关，无需配置文件。

仓库源码：extensions/hashline

配置

开箱即用，无必填配置。本地开发需先安装运行时依赖：

cd extensions/hashline && npm install && cd ../..

依赖：@oh-my-pi/hashline ^16.4.0（运行时）、@earendil-works/pi-coding-agent（peer）、typebox（peer）。

工作流

1. LLM 调用 read /tmp/file.js
2. hashline hook → 注入 header: [/tmp/file.js#A1B2]
3. LLM 收到带 tag 的文件内容
4. LLM 生成 hashline patch
5. Patcher 验证 #A1B2 匹配 + seen-lines 检查 → 应用编辑
6. 返回新 tag: #C3D4

验证

pi -e ./extensions/hashline/src/hashline.ts -p "what is 1+1" --no-session

实现方案

封装 @oh-my-pi/hashline：hashline.ts 覆盖 edit 并 hook read；PiexNodeFilesystem 直连 node:fs + realpath；EditGuard 管 noop/duplicate；Bun polyfill 只补 xxHash32。

设计参考

核心取舍：选择整体文件 tag（严格简单），放弃逐行 tag（局部可用），用封装层补容错。三个阶段：Phase 1 容错（done）→ Phase 2 恢复 → Phase 3 undo/LSP 联动。

迭代记录

路线图

冲突策略偏拒绝（安全但贵）→ 接 3-way merge / Recovery；快照偏薄 → 多版本 LRU + 锚点 Grep；duplicate 按 section 细化；封装层单测与可选 LSP 联动。

Phase 1 ✅  Noop Loop / Duplicate Edit / 方言归一化
Phase 2    Stale 恢复 · 多版本快照 · 锚点 Grep
Phase 3    Undo · Auto/Raw Read · LSP 联动 · 测试网

版本记录

附录：与其它 hashline 实现的对比

行业三条路线：oh-my-pi 全文件 tag、pi-hashline-edit 上下文逐行哈希、pi-hashline-edit-pro stable mapping。piex 选前者做引擎，容错借鉴后者。完整对照见源稿。