深入phi的Sloppy Edits:锚定模糊补丁为何比整文件重写更可靠(格式与Go实现解析)
深入phi的Sloppy Edits:锚定模糊补丁为何比整文件重写更可靠(格式与Go实现解析)
phi 是一个用 Go 编写的高速 coding agent(终端 AI 编程代理),它的 edit 工具没有让模型整文件重写,而是设计了一套 Sloppy Edits(锚定模糊补丁) 格式:模型只需引用文件中的当前文本(锚点),引擎通过"字节精确 → 空白容忍 → 模糊匹配"三级阶梯定位锚点,再以原子方式批量应用修改。本文带你读懂这套补丁格式的语法与 Go 实现细节,看看它为什么比整文件重写更省 token、更不易出错。
一、为什么整文件重写不可靠?
让大模型直接输出"改完之后的整个文件"听起来简单,实际却有三个硬伤:
| 问题 | 整文件重写 | phi 的锚定模糊补丁 |
|---|---|---|
| Token 成本 | 输出整个文件,改动一行也要全量重写 | 只输出锚点 + 变更片段 |
| 幻觉风险 | 未读过的部分可能被"凭记忆"改写 | 锚点必须与当前文件匹配,否则整体失败 |
| Diff 噪音 | 行号偏移、换行符差异全部混入 | 只产生真实改动的精确 diff |
phi 的工程文化直接把它写进了开发准则 AGENTS.md:
Keep
editfail-closed. Edits are anchored sloppy patches applied atomically; a missing or ambiguous anchor must fail with actionable guidance, never fall back to whole-file rewrite.
也就是说:宁可失败并给出可操作的诊断,也绝不降级为整文件重写。这就是"可靠"的第一层含义。
二、30 秒看懂 Sloppy 补丁格式
整个格式只有 4 个以 *** SM: 开头的关键行,全部实现在 internal/tools/edittool/sloppy/ 包里(词法扫描见 lexer.go,解析见 parser.go):
| 关键行 | 作用 |
|---|---|
*** SM:EDIT 路径 |
打开一个目标文件(可重复出现,一个 payload 改多个文件);追加 all 表示所有匹配都改 |
*** SM:FIND |
锚点:引用文件中的当前文本,必须唯一命中 |
*** SM:PUT |
用正文整体替换 FIND 匹配到的区域;正文为空表示删除 |
*** SM:AFTER |
保留锚点,在其后插入正文 |
两个"模糊"记号是这套格式的灵魂(完整说明见 sloppy/doc.go):
…省略号(gap):捕获跳过的原文,在PUT中按顺序原样放回——改函数体不用抄整个函数;⟪old│new⟫选择符:行内原地改写,old匹配、new落盘,连PUT都省了。
一个典型的 payload(来自 edit.go 中写给模型的官方示例):
*** SM:EDIT src/users.ts
*** SM:FIND
function load(…) {
…
return old(…);
}
*** SM:PUT
function load(…) {
…
return fresh(…);
}
注意 … 的用法:FIND 里每出现一个 … 就捕获一段原文,PUT 里的 … 按出现顺序把捕获内容原样重放回去。模型因此只需写"变化的部分 + 定位的骨架",token 消耗骤降。
小改动则完全不必写 PUT:
*** SM:EDIT src/app.ts
*** SM:FIND
total := ⟪a + b│sum(a, b)⟫
if ⟪debug│verbose⟫ {
log.Printf("total=%d", total)
}
三、核心匹配阶梯:精确 → 容忍 → 模糊
"FIND 必须与文件完全一致"听起来苛刻,但 phi 的匹配层(locate.go)实际是一个三级阶梯,只有前一级无果时才放宽:
- Raw(字节精确):逐字节匹配,候选由 search.go 的字面量回溯搜索生成;
- Normalized(空白与排版容忍):先把文件和锚点一起映射到"匹配空间"——normalize.go 的
normalizeText会丢弃所有空白,并把弯引号“ ”折回直引号、破折号变体折成-、≠折成!=。于是"缩进不同、复制时带入了排版符号"的锚点也能命中,且通过映射表把匹配偏移精确还原回源文件字节位置; - Fuzzy(模糊):最后一级允许极少量字符级错误。match.go 的
fuzzyOccurrences先用"操作符签名"(剥掉标识符后剩下的运算符串)快速剪枝——运算符序列不同的文本永远不可能模糊命中——再用 Levenshtein 距离(实现见 normalize.go)筛出编辑距离 ≤ 阈值的近似匹配。阈值约为模式长度的 1/8 且封顶 3 个字符。
模糊匹配的测试用例很能说明分寸感(sloppy_apply.json):calculateVale 这种拼错一个字母的函数名能救回来;但 left && right 绝不会被模糊匹配到 left || right——改错运算符的风险被彻底封死。
只认领唯一锚点
三级阶梯放宽的是"能匹配",从不放宽"必须唯一"(除非显式声明 all):
- 命中 0 处 → 报
did not match,附上最近似的文件片段; - 命中多处 → 报
is ambiguous,列出竞争锚点并给出可直接复制的重试 payload; - 若多个候选改写后结果一致(如仅缩进差异),identicalOutcomes 会判定其"实质无歧义",避免误伤。
四、原子应用:全部成功或一处不落
所有操作先各自在原始文件内容上定位(apply.go 的 plan 阶段),再统一规划成 splice 区间。这一步带来两个重要保证:
- 锚点互不干扰:所有 FIND 都针对读入时的原文解析,前面的修改绝不会"移动"后面操作的锚点——即使你在一个 payload 里连续改同一文件 5 处;
- 原子性:Apply 中任何一处失败,所有文件一个字节都不写,错误信息统一以
No operations were applied — ops apply atomically开头(payload.go 保证多文件 payload 同样原子)。
应用阶段按偏移从后往前拼接,避免前面的 splice 使后面的偏移失效;空 PUT 的删除还会自动吃掉整行缩进和接缝空行(expandFullLineDeletion),让删行后不留"鬼影空行"。写盘时若源文件是 CRLF 换行,会先还原回 CRLF 再写回(edit.go),细节上照顾了 Windows 用户。
应用成功后,工具把每个文件的变更以标准 diff 形式回传给模型——phi 的 TUI 也有原生 diff 审阅视图:
五、失败时返回"可直接重发"的 payload
phi 的错误诊断是写给模型看的,因此自带修复路径:
- 未命中(noMatchError):指出失败的片段、文件中最接近的区域(带行号,无需重新 read),并在置信度足够时直接给出修正后可复制重发的 payload;
- 歧义(ambiguityError):列出前两个竞争锚点各附一份带上下文的重试 payload,若所有候选改写结果相同还附带
all版本; - 语法错误:
SM1xx/SM2xx编号诊断,给出 payload 行号、列号和 caret 指向(格式见 sloppy/doc.go)。
配合"一个失败全都不应用"的原子语义,模型的重试循环非常干净:拿到诊断 → 修 payload → 原样重发,而不是在文件上打补丁的补丁。
六、源码阅读地图 🗺️
| 想了解的 | 从哪里读起 |
|---|---|
| 格式全貌与容错规则 | internal/tools/edittool/sloppy/doc.go |
| 词法:如何剥掉外部补丁信封、代码围栏 | internal/tools/edittool/sloppy/lexer.go |
| 工具接线与给模型的工具描述 | internal/tools/edittool/edit.go |
| 匹配阶梯与模糊搜索 | internal/tools/edittool/locate.go、match.go |
| 空白/排版归一化 | internal/tools/edittool/normalize.go |
| 原子应用与诊断生成 | internal/tools/edittool/apply.go、locate.go |
| 行为回归用例(50+ 场景) | internal/tools/edittool/testdata/sloppy_apply.json |
| 解析性能基准 | internal/tools/edittool/sloppy/bench_test.go |
性能上,解析全程单遍扫描、零正则:头部识别用字节前缀匹配,字面量跳跃用 strings.IndexByte,token 直接引用输入子串(设计说明见 sloppy/doc.go),解析开销可以忽略不计。
七、小结
phi 的 Sloppy Edits 本质上是把"模型记不清文件细节"这一事实当作设计前提:用锚定 + 模糊容错换取定位的鲁棒,用唯一性约束 + 原子应用换取改动的安全,用可重发诊断换取重试的低成本。对新手来说记住三件事即可:FIND 抄当前文件的原文、一个 payload 里所有操作都按原文定位、失败时整包重发而不是叠加修补。这套机制也正是 phi 作为"fast coding agent"敢在真实仓库里高频改文件而不怕翻车的底气所在。

