Code Agent 如何使用静态分析检查 LLM 生成的错误 API 迁移代码？

Code Agent 检查 API 迁移代码时，不应只问“这段代码看起来像不像正确答案”，而应把它变成一个可以逐项核验的事实检查问题：生成结果里出现的类、常量、构造器和方法，是否真的存在于目标 API；某个方法即使存在，是否属于当前接收者类型；链式调用的返回类型，能否继续承接下一次调用。最实用的方案是在模型生成之后增加一层轻量静态分析闸门，用抽象语法树提取 API 使用点，再用官方文档或 SDK 描述文件建立的符号表进行确定性核验。

为什么 API 迁移尤其容易产生“看起来正确”的错误

API 迁移通常包含两个不同难度的步骤。第一步是识别旧 API 应该替换成哪个新 API，第二步是补齐调用新 API 所需的上下文，也就是导入、对象构造、常量选择、Builder 调用、方法链以及返回值处理。LLM 往往能选对目标 API，却会在第二步编造貌似合理的胶水代码。

这类错误可以称为脚手架幻觉。它的危险之处在于，生成补丁在词法和结构上都可能非常接近正确实现，仅仅把一个常量名、成员归属或方法链返回类型写错。基于文本相似度或语法相似度的指标会给它很高的分数，人工快速浏览也可能因为名称合理而放过它，但代码最终无法编译，或者在更隐蔽的情况下调用了错误语义的合法成员。

因此，检查目标不能笼统定义为“发现所有代码错误”。更可操作的定义是：凡是生成代码中的符号与可信 API 规范中的可验证事实冲突，就判定为 API 幻觉。这种定义把一个开放式的语义判断，收缩成静态分析能够处理的成员存在性、成员归属、签名与返回类型问题。

先区分两类可验证幻觉

第一类是原子幻觉，即模型直接发明了一个不存在的类、静态方法、导入或常量。例如目标 SDK 中只有 CONTENT_TYPE_MUSIC，生成代码却使用了名字很像的 CONTENT_TYPE_STREAM。检查这一类问题不需要复杂推理，只要拿到限定类型和符号名，在可信符号表中做成员查询即可。

第二类是作用域绑定幻觉。这里的符号可能确实存在，但不属于代码中实际的对象类型。例如 setStreamType 是旧类型的方法，模型却把它接到新 API 的 Builder 对象上；或者一个链式调用中的前一方法返回 void，模型仍继续调用下一个成员。只检查“整个 SDK 中是否存在这个方法名”会产生漏报，必须解析接收者类型并沿调用链传播返回类型。

这一区分直接决定检测器的架构。原子符号适合用常数时间的集合查询，成员调用则需要局部作用域、继承关系和返回类型共同参与判断。Code Agent 在收到诊断结果时也能据此选择修复动作：不存在的常量需要从候选常量中重新检索，成员归属错误则需要重建对象或改写方法链。

用官方规范构建确定性 API Oracle

静态检查的可信度取决于知识库。最优先的数据源不是搜索摘要，也不是让另一个模型回忆 API，而是目标版本随 SDK 发布的机器可读规范，例如 XML 描述、类型存根、头文件、接口元数据或由官方文档生成的索引。它们代表公开可调用契约，还能避免把源码中的内部成员误判为公共 API。

索引阶段应为每个类型记录公开构造器、字段、常量、方法签名、静态属性、参数类型和返回类型，并提前展开继承层次。展开后，一个类型的可用成员可以直接放入哈希表，检查时不必反复遍历父类。索引还必须绑定 API 版本，因为“成员存在”只有在明确版本下才有意义；迁移目标为 Android API 35 时，不能用最新版在线文档替代实际构建环境。

工程上可以把 Oracle 产物做成带版本指纹的只读文件，并记录 SDK 版本、生成时间、输入规范摘要和索引器版本。CI 中若依赖版本改变，就先刷新索引再检查生成补丁。这样可以把“模型知识是否过期”从判断链路中移除，让诊断能够复现。

三段式静态检查流水线

第一段是解析。检测器将生成补丁连同必要的文件级上下文送入语言解析器，构建抽象语法树或具体语法树。使用 Tree-sitter 一类容错解析器的好处是，即使 Agent 只生成了局部片段、代码尚未完全可编译，也能提取大部分结构。解析失败不能简单当作无幻觉，而应单独返回“上下文不足”或“语法无效”。

第二段是符号提取。遍历语法树，收集导入、类型实例化、静态字段、普通方法调用和链式调用，并建立局部变量到类型的映射。对于每个检查单元，至少保留源代码位置、接收者表达式、成员名、参数数量和当前推断类型，便于后续生成精确诊断，而不是只返回一个布尔值。

第三段是 Oracle 核验。原子符号直接检查限定类型中是否存在目标成员；方法调用先解析根接收者，再从左到右遍历调用链。每次调用都在当前类型的成员集合中查询：成员不存在时标记为 Phantom Member；成员存在则把当前类型更新为该方法的返回类型；若返回 void 后仍有后续调用，就标记为 Broken Chain。

def inspect_chain(root, calls, scope, oracle):
    current_type = resolve_root_type(root, scope)
    findings = []

    for index, call in enumerate(calls):
        member = oracle.lookup(current_type, call.name)
        if member is None:
            findings.append({
                "kind": "phantom_member",
                "receiver_type": current_type,
                "member": call.name,
                "location": call.location,
            })
            break

        if member.return_type == "void" and index < len(calls) - 1:
            findings.append({
                "kind": "broken_chain",
                "member": call.name,
                "location": call.location,
            })
            break

        current_type = member.return_type

    return findings

真实实现不能只按方法名查询，还应逐步加入参数数量、重载签名、泛型替换、静态与实例修饰符、可见性和可空性。可以先用名称与返回类型建立高精度核心，再将复杂签名检查作为独立规则逐步扩展，以免一个不成熟的全量类型系统制造大量误报。

把检测器接入 Code Agent 修复循环

检测器最适合部署为生成后的确定性闸门。Agent 先生成候选迁移补丁，静态检查器只分析新增和修改的 API 使用点；没有发现问题时，再进入编译、单元测试和集成测试。发现问题时，将结构化诊断返回给 Agent，要求它仅修复被标记的符号，并重新运行检查。

{
  "kind": "phantom_member",
  "receiver_type": "AudioAttributes.Builder",
  "member": "setStreamType",
  "api_level": 35,
  "message": "该成员不属于当前接收者类型，请依据目标版本 API 重新构造调用链"
}

修复提示中应包含接收者类型、目标 API 版本、出错位置和规则类别，但不要让检测器随意推荐一个“最像”的替代方法。静态事实检查擅长证明当前写法与规范冲突，不一定能证明哪个替代方案满足业务语义。候选 API 的选择仍需结合迁移规则、调用上下文、官方示例与测试。

循环还需要退出条件。建议限制自动修复次数，并对同一位置重复出现的诊断做去重。如果连续两轮只是替换不同的虚构成员，应升级为人工复核，而不是让两个概率模型互相说服。每轮保留补丁、诊断和 Oracle 版本，方便审计 Agent 为什么接受或拒绝某次迁移。

为什么不能只用 CodeBLEU 或 LLM Judge

研究中的 51 组 Android API 迁移显示，错误补丁与正确答案可能只有一个符号不同，因此包含脚手架幻觉的代码也能获得接近 0.96 的相似度分数。正确样本与幻觉样本的 CodeBLEU 分布高度重叠，无法找到一个既拦住错误又不误伤正确代码的可靠阈值。

让另一个 LLM 充当裁判同样存在概率性偏差。它可能因为代码表面流畅而批准不存在的成员，也可能过度纠正并拒绝合法调用。论文实验中，确定性检查器针对两种生成模型的精确率都是 1.00，召回率分别为 0.73 和 0.90，F1 分别为 0.84 和 0.95；相对地，LLM 裁判的 F1 分别只有 0.67 和 0.53。

这些结果支持的不是“静态分析可以替代所有评审”，而是它适合作为事实层裁判。相似度可用于衡量迁移结构变化，LLM Judge 可辅助解释意图，编译与测试负责更完整的语义验证，Oracle 静态检查则专门回答符号是否符合公开契约。把不同工具放在各自擅长的层次，比寻找一个万能评分更可靠。

当前方法的边界与补强方式

名称和返回类型检查仍会漏掉若干问题。一个方法名真实存在，但参数类型或重载选择错误，基础检测器可能放行；回调接口需要同时验证被调用方声明和回调实现签名；生成片段缺少变量声明或导入时，局部类型传播也会中断。合法符号被用在错误业务语境中，更不属于“符号是否存在”能够解决的问题。

因此，生产流水线应按层增加保障。第一层用 API Oracle 拦截虚构符号和错误成员归属；第二层运行语言编译器或类型检查器，覆盖重载、参数和泛型；第三层执行针对迁移行为的单元测试；第四层对权限、生命周期、线程模型和弃用策略做领域规则检查。任何一层失败，都应把机器可读反馈送回 Agent，而不是只附上一大段构建日志。

对于大型仓库，还应扩大类型解析范围，但要控制延迟。可以先在补丁局部运行快速检查，只有根类型无法解析时才加载所属文件、模块依赖或项目索引。依赖库的 Oracle 按坐标和版本缓存，增量检查只分析变更节点。这样既保留轻量检测的速度，也能减少片段上下文不足造成的漏报。

落地时应监控哪些指标

上线后不要只统计“拦截了多少次”。至少要记录精确率、召回率、各规则命中数、无法解析比例、人工推翻率、修复轮数和最终编译通过率。高精确率非常重要，因为错误告警会让 Agent 反复修改本来正确的代码；召回率则需要通过新增签名规则、扩展项目上下文和真实失败样本持续提高。

评估集应区分一般 API 误用与可验证幻觉。使用了真实但语义不合适的常量属于误用，编造不存在的常量才属于幻觉。若把所有迁移失败都标成正例，会让检测器的能力边界变得模糊，也无法判断某条规则究竟在发现事实冲突，还是在猜测业务意图。

可执行的实施顺序

第一阶段选择一个语言和一个明确版本的 SDK，从官方规范生成符号表，实现类、常量和静态成员的原子检查。第二阶段加入局部变量类型映射、继承展开和从左到右的方法链返回类型传播。第三阶段把结构化诊断接入 Code Agent 的有限次数修复循环，并在修复后强制重新检查。

第四阶段再增加完整签名、静态修饰符、回调与跨文件类型解析，同时用编译和测试结果校准漏报。整个过程中，应固定 Oracle 来源和版本、保留诊断证据，并把不确定情况标记为无法判定。这样构建的检查器不是另一个会“凭感觉”评分的模型，而是一道围绕 API 公共契约工作的、可复现且可审计的事实检查闸门。