Code Agent 的补丁为什么会局部有效却在全局上不一致？

Code Agent 的补丁可能在局部完全有效：语法正确、类型检查通过、单元测试也全绿，却在整个仓库中不一致。原因是补丁只满足了当前文件或函数的约束，没有同步满足依赖声明、配置键、数据 Schema、资源路径、路由中间件和跨文件接口。论文把这种现象称为 patchwork problem，即每块代码单看合理，拼在一起却破坏系统结构。

局部正确与全局一致有什么区别

局部正确关注一段代码能否解析、编译并对已测输入产生预期结果。全局一致关注它与仓库其他制品之间的关系是否成立。例如新端点调用了一个看似合理的内部方法，但真实方法签名不同；代码读取了环境变量，部署配置却从未声明；响应返回 user_name，前端读取 username。

这些错误经常跨越文件类型。TypeScript 编译器能检查代码中的类型，却未必知道 Docker Compose、环境模板、数据库迁移和框架路由之间的约定。局部测试没有走到相关集成点时，补丁就会带着隐患进入部署。

为什么 Code Agent 更容易产生拼布问题

Agent 的上下文窗口有限，通常只检索与当前任务最相似的文件。它会依据常见命名和框架惯例补全缺失信息，却可能把训练数据中的惯例误当成当前仓库事实。名称越“像真的”，越容易绕过人工快速审查。

多轮修改还会放大问题：一轮新增模型，下一轮修改路由，第三轮改前端，但上下文中保留的是不同时间的仓库快照。每个 patch 都能应用，最终契约却没有对齐。

八类结构失效

论文提出八类 taxonomy。Symbol Resolution Failure 指引用名称无法在模块图和符号表中解析。Phantom Internal API 指内部函数存在，但调用参数、返回或语义与声明接口不兼容。Dependency Hallucination 指外部 import 未在依赖清单声明，甚至包注册表根本不存在。

Build/Configuration Incoherence 包括不存在的入口点、未声明环境变量、模块系统冲突和框架设置不一致。Resource Coherence Failure 覆盖缺失模板、资产、迁移、某些路径无返回值，以及生产模型缺少消费端所需字段。

Control Flow Coherence 包括不可达块、矛盾条件、错误异常流和失效错误处理。Cross-File Contract Violation 关注生产者与消费者字段、序列化、错误码和中间件注册不一致。Security Structural Regression 则指新路由没有挂上兄弟路由都有的认证或授权守卫。

为什么编译和类型检查会漏掉

动态加载的模板路径、环境变量名和依赖注册表状态不属于普通类型系统。跨服务 JSON 字段可能都被标成字符串或 any，字段名不一致仍能编译。中间件是否覆盖每条敏感路由，是框架 wiring 关系，不一定表现为类型错误。

类型检查仍然重要。论文的混合框架把符号解析和签名兼容交给 mypy、TypeScript compiler、pylint 与 ESLint 等成熟工具，因为重新实现语言长尾语义会降低精度。问题不是替换类型检查，而是补上它没有覆盖的跨制品不变量。

为什么测试也会漏掉

测试只能观察实际执行的路径。若测试注入了环境变量，就发现不了部署文件缺少声明；若路由测试绕过真实中间件，就发现不了鉴权遗漏；若 mock 返回模型期望的字段，就发现不了真实生产者使用另一名字。

局部测试通过说明已测试行为可行，不证明所有仓库关系完整。集成测试和端到端测试能扩大覆盖，但组合空间巨大，仍需要静态结构验证提供另一类证据。

SAST 为什么不是完整答案

传统 SAST 重点常在污点传播、危险函数和已知漏洞模式。配置键是否有声明、导入包是否存在、模板文件是否落盘、消费者字段是否属于生产者 Schema，并非所有工具的默认目标。

安全结构回归也可能没有明显危险数据流。一条新管理路由只是少挂了权限 decorator，函数体本身可以完全安全。检测需要比较路由图和 middleware attachment graph，验证同类敏感路由的 guard coverage。

用多图表示仓库关系

论文为生成后的完整仓库构建八种图：import、call、dependency、configuration、schema、resource、control-flow 和 routing。节点代表文件、符号、包、配置键、字段、资源或路由，边表示引用、调用、生产消费和守卫关系。

一个失效类别可能依赖多张图。例如跨文件字段不一致同时需要 call graph 与 schema graph；资源一致性需要路径引用、控制流和 Schema；依赖幻觉的结果还会影响符号解析和虚假 API 判断。这解释了为什么单一 lint pass 难以覆盖。

依赖与符号如何验证

检测器先解析 pyproject、requirements、package.json 和 lockfile，形成已声明依赖集合。外部 import 不在标准库、本地模块或清单中时，再查询 PyPI 或 npm，以区分“真实但未声明”和“注册表不存在”。

该方法也有假设边界。Python import 名与发行包名并非总是一致，例如 yaml 与 PyYAML，cv2 与 opencv-python。生产实现需要维护映射和置信度，不能把所有名称差异直接判为幻觉。

配置一致性怎样形成可证明发现

配置检测关注没有保护的严格读取，例如 Python 的方括号环境变量访问，或 TypeScript 中没有 fallback 的 process.env 使用。它会排除 try/except、成员检查和默认值保护，再与 env 示例、Compose 和框架设置里的键集合比较。

这样输出的不是“这个名字看起来可疑”，而是具体约束：代码在缺少某键时会失败，而仓库配置空间没有声明该键。证据包含文件、行号、键名和缺失位置，便于 Agent 修补代码或配置。

Schema 与跨文件契约如何检查

框架从 Pydantic、SQLAlchemy、Zod 和 Prisma 等定义提取字段，再沿调用或生产消费边比较。若消费者访问的字段不在生产者输出集合中，就报告两个位置之间的约束断裂。

同样的方法可检查 middleware 注册后是否真正被路由模块引入、是否重复注册，以及 decorator 引用的权限类是否存在。修复不能只改报错的一端，应确认哪一端才是契约来源。

Agent 应如何预防全局不一致

• 编辑前搜索符号声明、调用方、配置、Schema 和相关资源。
• 新增依赖时同时核对 manifest、lockfile 和真实注册表。
• 新增环境键时更新示例、部署配置、文档和安全默认值。
• 修改数据模型时沿生产者与消费者做双向检查。
• 新增路由时比较同类路由的认证、授权和中间件链。
• 运行类型、lint、测试后，再执行仓库级结构验证。
• 把每个发现返回为文件、行号、关系链和被破坏不变量。

验证器为什么要 precision first

大量启发式告警会让开发者忽略结果。论文框架优先报告可证明的约束违反，并把成熟语言语义交给现有分析器，只为配置、依赖、资源、安全 wiring 和跨文件契约等空白构建专用检测器。

这适合 Code Agent 的修复循环：清晰证据能指向相关文件，模型可以重新读取并生成小补丁。模糊的“架构可能不一致”很难转化为确定动作。

实验结果应怎样解读

论文 v1 报告了两个前沿模型、四种提示策略下的 336 次生成，并在 43 个真实 AI 生成仓库上外部验证。作者观察到多数结构失效逃过类型检查、测试和 SAST，而且两个模型的失效模式存在定性差异。

这些结果支持“需要专门结构验证”，但不是所有语言和框架的普遍精确率保证。实现主要覆盖 Python、TypeScript，以及 FastAPI、Django、Express、Next.js 等指定结构。应用到 Java、Rust 或自研框架时，需要重新构建提取器和验证基准。

一次完整的补丁验收流程

先验证补丁可应用、格式和类型；再运行目标测试与回归测试；随后构建仓库关系图，检查新增和变化节点周围的不变量。发现缺失依赖、配置、资源或契约时，要求 Agent修复并重新执行整条链。

最终审查不仅看 diff 中写了什么，还要看它连接了什么：新 import 指向哪里，新字段由谁生产，新环境变量在哪里声明，新路由由谁保护。部署前保留结构验证报告与测试证据。

结论

Code Agent 的补丁局部有效却全局不一致，是因为代码仓库并非独立文件集合，而是由导入、调用、依赖、配置、Schema、资源、控制流和路由关系组成的系统。局部编译和测试只覆盖其中一部分。

解决 patchwork problem 需要在传统 CI 之外增加仓库级不变量检查，并让每个发现带有可定位证据。最可靠的 Agent 不只会把代码写进正确文件，还会沿跨文件关系确认新代码真正属于当前项目。