深入phi的Sloppy Edits:锚定模糊补丁为何比整文件重写更可靠(格式与Go实现解析)

原创2026-10-31 21:08:102,223 阅读

深入phi的Sloppy Edits:锚定模糊补丁为何比整文件重写更可靠(格式与Go实现解析)

phi 是一个用 Go 编写的高速 coding agent(终端 AI 编程代理),它的 edit 工具没有让模型整文件重写,而是设计了一套 Sloppy Edits(锚定模糊补丁) 格式:模型只需引用文件中的当前文本(锚点),引擎通过"字节精确 → 空白容忍 → 模糊匹配"三级阶梯定位锚点,再以原子方式批量应用修改。本文带你读懂这套补丁格式的语法与 Go 实现细节,看看它为什么比整文件重写更省 token、更不易出错。

phi TUI 编辑界面:agent 思考、执行命令与锚定补丁编辑过程的完整对话

一、为什么整文件重写不可靠?

让大模型直接输出"改完之后的整个文件"听起来简单,实际却有三个硬伤:

问题 整文件重写 phi 的锚定模糊补丁
Token 成本 输出整个文件,改动一行也要全量重写 只输出锚点 + 变更片段
幻觉风险 未读过的部分可能被"凭记忆"改写 锚点必须与当前文件匹配,否则整体失败
Diff 噪音 行号偏移、换行符差异全部混入 只产生真实改动的精确 diff

phi 的工程文化直接把它写进了开发准则 AGENTS.md:

Keep edit fail-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)实际是一个三级阶梯,只有前一级无果时才放宽:

  1. Raw(字节精确):逐字节匹配,候选由 search.go 的字面量回溯搜索生成;
  2. Normalized(空白与排版容忍):先把文件和锚点一起映射到"匹配空间"——normalize.go 的 normalizeText 会丢弃所有空白,并把弯引号 “ ” 折回直引号、破折号变体折成 -、≠ 折成 !=。于是"缩进不同、复制时带入了排版符号"的锚点也能命中,且通过映射表把匹配偏移精确还原回源文件字节位置;
  3. 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 区间。这一步带来两个重要保证:

  1. 锚点互不干扰:所有 FIND 都针对读入时的原文解析,前面的修改绝不会"移动"后面操作的锚点——即使你在一个 payload 里连续改同一文件 5 处;
  2. 原子性:Apply 中任何一处失败,所有文件一个字节都不写,错误信息统一以 No operations were applied — ops apply atomically 开头(payload.go 保证多文件 payload 同样原子)。

应用阶段按偏移从后往前拼接,避免前面的 splice 使后面的偏移失效;空 PUT 的删除还会自动吃掉整行缩进和接缝空行(expandFullLineDeletion),让删行后不留"鬼影空行"。写盘时若源文件是 CRLF 换行,会先还原回 CRLF 再写回(edit.go),细节上照顾了 Windows 用户。

应用成功后,工具把每个文件的变更以标准 diff 形式回传给模型——phi 的 TUI 也有原生 diff 审阅视图:

phi 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"敢在真实仓库里高频改文件而不怕翻车的底气所在。

登录后查看全文
phi