27｜贯穿案例：修复exclude，从原始失败到可恢复交付

目标：将输入、检索、补丁、工具、状态、测试和报告串成一个可运行案例。所有代码与样本为本书原创；控制器按脚本给出补丁，不是模型自主发现Bug，也不是对用户真实PSBuild仓库的审查。

继续看相关机制：F30 · 代码检索不能只靠“语义相近”F35 · 读指标，先问它的分母是谁

1. 为什么选这个问题

exclude看起来只是字符串匹配，却包含路径契约、目录边界、平台分隔符、用户输入与回归。这使任务足够小，可以完整展示，又足以暴露“只看起来写好了”的问题。生产实现若支持glob、gitignore、大小写或符号链接，需要另行定义；本例不暗中扩展范围。

契约是：路径相对仓库根；普通规则精确匹配；以斜杠结尾的规则匹配目录及后代；统一反斜杠分隔符；拒绝父级跳转。示例src/a.py不应被规则a.py排除，vendor/a.py应被vendor/排除，而vendor2/a.py不应被误排除。

2. 初始缺陷与失败证据

初始函数先取PurePosixPath(path).name，再检查规则列表。它丢掉目录，导致嵌套精确路径失配，也会误排除其他目录同名文件。只测试顶层a.py会漏掉这些错误。

实际运行8项测试，初始有5项失败，涉及嵌套路径、同名边界、目录规则、Windows分隔符与父级跳转。测试stdout、退出码和工件版本保存在reports/test_results.json的capstone字段。这些数字对应配套运行记录，不是预期结果。

检索阶段用Python AST返回函数范围；它仅帮助定位，并未完成类型推断或跨文件调用图。读取工具返回完整小文件及其版本，使补丁可以绑定已知前置状态。

3. 实施：只改需要改的行为

修复将路径规范化为相对POSIX表示，拒绝越界形式；普通规则比较完整相对路径；目录规则比较相等或prefix + '/'前缀，避免vendor误匹配vendor2。没有引入新的路由服务、全局配置层或通用匹配框架。

更新通过动作日志的CAS入口提交。expected必须等于刚读到的内容，防止覆盖并发修改；操作ID重复但参数不一致会被拒绝。工具写入范围限制在matcher.py，测试文件由教学Harness创建并固定执行。

这不是防御恶意Agent的完整隔离。生产中不可信代码与测试应在沙箱运行，验证资源可能要放在工作区外；本例重点证明正常故障窗口与版本新鲜度。

4. 验证：绿色结果必须属于当前文件

修改后再次运行相同8项测试，全部通过。随后调用完成检查，确认当前文件版本与最近通过测试的版本一致。实验再追加一条注释，故意使工件变化；再次finish被拒绝，说明旧绿色结果不会自动套到新文件。

对真实工程，注释变更是否需要重跑全部测试可以按风险优化，但必须先建立可信复用条件。不能让模型仅凭“改动很小”决定沿用陈旧验证。本例采取保守策略便于理解。

所列测试没有覆盖完整glob语义、文件系统符号链接、Unicode规范化、超大规则集性能或所有Windows路径格式。它的成功只相对于明确契约与列出的测试，不应被称为完整生产exclude库。

5. 另一个真实实验：写后崩溃

RecoveryTests.test_real_crash_and_reconcile在独立子进程中调用文件更新器，在os.replace之后、SQLite标记完成之前立即退出。父进程观察退出码75，再恢复同一操作。当前文件已等于目标版本，因此系统标记reconciled，不再次写入。

这个实验回答的是“本地副作用成功但日志未完成，如何恢复”。它与上面的功能Bug是两个独立维度。通过功能测试不能证明恢复可靠；通过恢复测试也不能证明匹配语义正确。高级实验要把这些维度分别验证。

6. 与真正LLM Agent的差距

离线Harness的动作是作者预先编排，因此没有测模型能否发现根因、选择工具、生成正确补丁或抵抗上下文干扰。它证明执行边界和验证机制可运行。用户不能把这份报告读成“某模型修复成功率100%”。

可选live_readonly.py展示真实API接入结构，但只允许只读文件分析，该入口未实测。若要升级为真实写代码评测，应先在可销毁仓库中提供受限patch工具、外部验收与预算，记录模型输出和全部调用，再多次运行。不要直接让未验证的适配器修改生产项目。

7. 读者应完成的扩展

扩展一：用户在read与replace之间改文件，验证系统返回stale而不覆盖。扩展二：测试命令超时，检查finish不能通过。扩展三：加入目录名相似、绝对路径和空规则的契约样本。扩展四：在不同候选补丁下比较功能正确性与复杂度，而不是只选代码最长者。

扩展五：增加真实模型只读分析，评价它是否提出正确根因，并把结果与脚本控制分开报告。扩展六：把无关长历史加入输入，测试是否影响约束和定位。这些是未运行的练习，不会预填成功结果。

8. 一份合格的交付报告示例

“修复了basename比较导致的相对路径误判；目录匹配增加边界分隔符；在当前工件上8项契约测试通过；同时验证了陈旧结果拒绝。未实现glob及完整跨平台路径库，也未验证生产性能。”

这段报告短，但知道做了什么、为什么、如何证明和边界在哪里。相比“全面优化、质量显著提升”，它更符合资深工程工作的证据标准。