接口提取先靠静态分析，再让 AI 补缺

让 AI 从代码生成 API 文档，最麻烦的错误，是把不存在的接口写得像真的一样。后续的 Mock、测试场景和评审一旦照着走，错误就会沿着接口契约继续传播。

作者给出的方案是：先用确定性扫描找出路由，再让 AI 补充扫描明确标出的未知项。Powerduck 按这个边界组织工具流程。它值得讨论的地方，是如何限制 AI 的修改权限，以及这些限制能证明什么、不能证明什么。

路径是否存在，为什么不能交给模型决定

原文把两类工作分开：一类是确认有哪些路由、使用什么 HTTP 方法、对应什么路径；另一类是解释某个已发现处理函数中尚未解析的信息。

前一类交给框架追踪和抽象语法树（AST）分析。工具沿着实际代码解析结构，路由列表由扫描结果产生，模型没有创建路由的权限。

原因很直接：模型一旦能生成路径，就可能生成一个并不存在的路径。这个错误进入 OpenAPI 文档后，看起来仍然是一份完整、规范的接口定义，下游使用者很难仅凭文档识别真假。

接口结构必须来自代码证据，AI 只能处理已经命名的未知项。

不过，确定性不等于扫描一定完整。原文没有说明支持哪些框架，也没有交代动态路由注册、复杂封装等情况如何处理。这里能确认的是职责边界，不能据此认定工具能找到所有接口。

AI 补的是一个缺口，不是一份自由发挥的文档

作者所说的缺口（gap），是某个处理函数（handler）上的具体未解析项，例如无法确定的响应字段。完整性关卡（completeness gate）会把它绑定到一个缺口代码（gap code）和对应的 handler。

这里的「关卡」可以理解成一份有明确归属的待办清单：哪个处理函数缺了哪项信息，先由扫描器标出来，再交给模型。

一次补全的流程是：

1. 扫描器标记缺口，并记录 gap code 和 handler。
2. AI 只返回该缺口对应的一小段补充内容。
3. 补充内容继续挂在原来的缺口上，不能扩展出新路由。
4. 使用者对照源码审核，通过后才采纳。

原文举的是一个 POST 接口：扫描已经确认路由和请求体，却无法解析错误响应的结构。模型可以参考 handler 的错误分支，提出这个响应的 schema，但不能顺手增加第二个路径，也不能添加 DELETE 方法。

补全前后，路由数量保持一致。如果建议的 schema 对不上实际错误分支，审核就应拒绝它。

模型生成的内容在核验前仍是假设，不能自动升级为已确认的事实。

这也解释了为什么只在提示词里写「不要编造」还不够。作者描述的约束落在工具流程和补全对象上：模型拿到的是一个受限任务，结果也必须归属于原来的缺口。

我的判断

我认同把路由提取和 AI 补全分开的方向。相比让模型直接生成整份接口文档，这种做法缩小了它能影响的范围，也让审核有了具体对象：检查某个错误响应是否符合代码，比重新核查一整份文档更容易定位问题。

但原文没有给出准确率、漏检率、耗时或对照实验。「模型处理具体未知项比人更快」是作者的判断，文中没有实测数据支撑。Powerduck 如何在内部强制执行这些限制，也没有展示实现细节。

还要分清两件事：扫描确认了路由结构，不代表实现行为已经符合文档；AI 补齐了一个 schema，也不代表所有运行时分支都经过验证。原文明确承认，扫描成功不能证明实现符合规范。

与手工维护 OpenAPI 或从显式 schema 生成文档相比，这种方案更依赖扫描器对代码结构的理解，也保留了人工审核成本。原文没有提供这些方案的比较结果，不能直接判断哪一种更省事。

另外，静态扫描不需要模型密钥，源码默认不会发送到外部。这说明提取路由可以独立运行；启用 AI 补全后具体发送哪些内容，原文没有说清。

能拿来做什么

• 给 Node 服务生成 OpenAPI 时，可以先固定扫描得到的路径和方法，再把无法解析的请求或响应信息列成缺口，让 AI 逐项处理。
• 审核 AI 生成的错误响应 schema 时，应对照 handler 的实际错误分支，检查字段和返回条件是否有代码依据。
• 前端准备依据文档生成 Mock 或测试场景前，可以要求区分已确认内容与待审核补全，避免把模型推测当成接口契约。
• 自建文档生成流水线时，可以把「AI 补全前后路由数量、方法和路径保持不变」设为校验条件，同时保留人工核对补全内容的步骤。