Code Agent 的 Codex 风格 apply_patch 如何校验上下文并反馈解析失败？

Code Agent 使用 Codex 风格 apply_patch 时，可靠性来自两道不同的校验。第一道由解析器确认补丁信封、文件操作头和每行前缀符合语法；第二道在真正修改文件前，用补丁中的旧行和上下文定位当前文件。前者失败说明模型输出的补丁格式无效，后者失败说明补丁与工作区状态不一致。工具必须把两类失败分开反馈，因为它们需要完全不同的恢复动作。

Codex 风格补丁包含什么

senpi 的内置扩展为 GPT 模型提供自由格式的 apply_patch。补丁以 *** Begin Patch 开始，以 *** End Patch 结束，中间可以组合新增、删除、更新和移动文件。更新块使用 @@ 上下文标记，并要求内容行以空格、加号或减号开头。

这种格式比只提交 old text 和 new text 更适合一次表达多文件修改，也让预览、权限检查和 diff 展示拥有统一输入。但自由格式文本可能被模型漏写标记、错写行前缀或截断，因此解析必须在文件写入之前完成。

解析器先检查完整信封

parsePatch 先统一 CRLF、CR 与 LF 换行，并可剥离模型偶尔附带的 heredoc 外壳。随后检查第一行是否为开始标记，最后一行是否为结束标记。任一条件不满足，就返回“预期完整补丁信封”的错误。

信封校验能识别流式输出被截断、模型只生成半个 patch，或调用者误把说明文字当成工具参数。没有结束标记时继续解析尤其危险，因为系统无法知道模型是否还打算追加其他文件操作。

文件操作头如何校验

信封内只有 Add File、Delete File 和 Update File 三种合法头，更新操作还可紧跟 Move to。遇到未知的星号头，解析器会在错误中列出允许的头格式，而不是忽略未知操作。这可以及时暴露模型拼错标记或使用了不受支持的语法。

新增文件的每一行都必须以加号开头。更新块里的上下文行、删除行和新增行分别以空格、减号和加号开头。若第一条内容行没有合法前缀，错误会指出意外行并说明允许的三种前缀。空更新块和没有任何内容的 hunk 也会被拒绝。

应用层还会拒绝只有开始与结束标记的空补丁。这样即使语法解析得到零个操作，也不会把“什么都没做”误报为成功。

解析失败为什么不应重读文件

缺少结束标记、错误的 hunk 头或非法行前缀，都来自补丁文本本身。重新读取目标文件不会修复格式，因此恢复策略应该让模型根据错误重建 patch。若 Agent 对所有失败都机械重读，会浪费上下文，甚至在多文件任务中重复读取大量已知内容。

解析错误应尽量包含局部原因：哪一行不合法、需要什么前缀、哪个更新块为空。模型可以只修正结构，不必重新规划业务修改。流式解析器也使用对应规则，在参数尚未生成完时展示已解析内容；流结束仍缺少结束标记才形成明确错误。

上下文校验发生在什么阶段

解析成功只说明补丁形状合法，不代表旧代码仍存在。更新文件时，replaceChunks 会把文件拆成行，先处理 @@ 后的 change context，再查找 hunk 中的 old lines。每个块都从前一个命中位置之后继续搜索，从而保持多个块在文件中的顺序。

若 change context 找不到，工具返回包含具体上下文和文件路径的失败；若旧行序列找不到，则返回“无法找到预期行”，并附上补丁期望删除或保留的旧行。错误让模型知道需要重新读取哪个文件、哪个片段。

有限模糊不等于任意猜测

senpi 的 seekSequenceWithFuzz 按四档顺序搜索。第一档逐行完全相等；第二档只忽略行尾空白；第三档忽略两端空白；第四档还会统一弯引号、不同 Unicode 横线和若干特殊空格。每档都要求整个行序列连续匹配。

这是一种有边界的文本归一化，不是基于相似度随意选择候选。工具记录累积 fuzz 值，调用者能看出补丁是否依赖了宽松匹配。项目说明特别强调不要为了方便退回非严格 seek，因为这会掩盖真实的补丁语法或上下文问题。

为什么要保留上下文行

只给出要删除的一行，可能在同一文件中命中多个相似片段。补丁中的前后上下文缩小了定位范围，也让工具验证修改仍处于模型读取时的结构。函数名、分支条件和相邻语句比行号更能抵抗文件前部增删造成的位置漂移。

上下文也不应无限扩大。复制整个文件会增加 Token，并让无关格式变化导致失败。实务上应提供足以唯一定位的几行；失败后读取最新片段，再围绕目标生成新的 hunk。

文件系统错误需要另一种恢复

文件不存在、权限不足、路径不是目录等错误，不一定是上下文漂移。senpi 保留 Node 文件系统错误码，例如 ENOENT、EACCES、EPERM、ENOTDIR 和 EISDIR。恢复模块将带错误码的失败排除在“必须重读”之外，因为重复读取不能解决路径或权限问题。

Agent 应根据错误码检查相对路径、工作目录、目标类型和权限。把所有应用失败都简化成“context mismatch”，会给模型错误指令并延长失败循环。

多文件补丁可能部分成功

该实现逐个应用文件操作，并记录成功文件和失败详情，因此后面的操作失败时，前面的操作可能已经写入。错误文本会明确写出是整体失败还是部分失败，并提示“此前文件操作已经应用”。这比只抛出最后一个异常更安全。

恢复指令把文件分为必须重读、无需重读和失败文件。没有错误码的上下文失败进入必须重读集合；已经成功且与失败无关的文件进入不应重读集合。Agent 重试时只重新构造失败操作，避免把成功 hunk 再应用一次。

这里的部分成功并非数据库事务式原子补丁。调用者若要求全有或全无，需要在更高层建立工作树快照或回滚机制。工具的职责是准确报告已发生的状态，而不是假装整批操作从未执行。

写盘阶段如何降低损坏风险

更新和新增文本先写入带进程号与随机后缀的临时文件，再通过 rename 替换目标。这样比直接打开目标并覆盖更能避免进程中断留下半个文件。对同一路径的修改还进入文件 mutation queue；移动操作会对源与目标路径按稳定顺序排队，降低并发冲突。

原子写文件解决的是单次文件替换完整性，不代表整个多文件补丁原子。删除、移动和多个文件操作之间仍可能出现部分成功，所以结构化进度与失败清单不可省略。

错误信息怎样设计才可恢复

• 解析失败指出缺失的信封、非法操作头、错误行前缀或空 hunk。
• 上下文失败包含目标文件和未找到的上下文或预期旧行。
• 文件系统失败保留稳定错误码，避免建议无效的重新读取。
• 多文件失败列出每个文件、操作类型和具体消息。
• 结果明确说明是否已有操作成功，防止无条件重放整份补丁。
• 恢复指令只要求读取真正发生上下文失配的文件。

Agent 的推荐处理流程

收到解析错误时，先修复 patch 结构：检查开始和结束标记、文件操作头、每行前缀与空块。收到上下文错误时，只读取错误指出的文件和片段，基于当前文本重建 hunk。收到路径或权限错误时，检查环境而不是反复改上下文。

若结果显示部分成功，应先把已成功操作从重试补丁中移除，再处理失败文件。新的 patch 应再次预览，确认路径和 diff，然后运行格式化、类型检查及相关测试。工具应用成功只证明文本变更落盘，不证明软件行为正确。

结论

Codex 风格 apply_patch 的可靠性，不只取决于能否解析加减号。完整实现先验证语法信封和 hunk 结构，再用有边界的上下文匹配校验工作区状态，同时区分解析、定位、路径与权限错误。

最关键的设计是让错误直接指向恢复动作：格式错误重建补丁，上下文错误重读失败文件，系统错误检查环境，部分成功则只重试未完成操作。清晰反馈把失败从模糊异常变成 Agent 可以纠正的状态，也避免为了提高表面成功率而把错误补丁写进代码库。