PR 改了 API 签名但文档 3 周后才被人工发现：「代码变更 → 文档影响面」的自动检测链路，检测粒度、误报率、工具选型怎么落地？

【背景】 我做了 3 年技术文档，近两年重心在数据分析与指标体系搭建。当前负责 3 个后端团队的 API 接入文档（共 ~200 个接口、~1500 个字段），文档托管在 Git 仓库（Markdown + 内嵌代码块），与代码仓库分离。

反复出现的同一个事故模式：代码 PR 改了字段名 / 类型 / 枚举值 / 错误码，对应文档没跟着改，3~6 周后集成方提工单才发现。不是"文档写错了"（那是 id=1399 讨论的口径漂移），而是"代码变了，文档根本不知道该跟着改"——影响面断链。

【现象（带数据）】

1. 过去 12 个月，3 个团队共 47 次"文档-代码不一致"工单，其中 39 次（83%）根因是"代码变了文档没改"，只有 8 次是"文档本身写错"。
2. 从代码合入到文档修正的延迟：中位数 14 天，P90 达 41 天。延迟越长的接口，集成方工单量越高（r = 0.62，n=39）。
3. 现有检测手段的盲区：
   • CI 跑 OpenAPI schema diff：能发现 spec 文件变了，但"文档正文里引用了哪些字段"是自然语言（如"传 order_id 参数"），schema diff 检测不到文档引用。
   • PR 模板加勾选项"是否涉及 API 变更"：40% 的 PR 没勾（开发者觉得"我改的是内部逻辑，不影响接口"，但实际改了序列化字段名）。
   • 人工 review：让文档工程师看每个 PR diff，但 PR 平均 200+ 文件，文档工程师 3 个团队共 2 人，根本看不完。

【已尝试的排查与结果】

1. 字段引用扫描：写了一个脚本，从文档 Markdown 里提取所有反引号包裹的标识符（如 order_id、status），与代码仓库的 OpenAPI spec 做交叉比对。能发现"文档引用了一个 spec 里不存在的字段"（已删除字段），但发现不了"spec 里新增/改名的字段，文档没引用"（因为文档本来就没写）。只能检测"删"，检测不了"改"和"增"。
2. AST 解析 + 文档关联：尝试从 Java/Kotlin 源码的注解（@JsonProperty、@SerializedName）提取字段清单，与文档做 diff。问题：3 个团队 2 种语言 + 1 种 Go，注解风格不统一，解析脚本维护成本高于收益。
3. PR webhook → 文档工程师通知：代码仓库 PR 合入后，webhook 推送到文档群。实际效果：文档群日均 30+ 条消息，真正的"影响文档"的 PR 不到 5%，信噪比 1:6，3 周后文档工程师就不看了。

【期望得到的答案形态】

1. 检测粒度：「代码变更 → 文档影响面」的检测粒度应该定在哪一层？字段级（最细但误报高）/ 接口级（适中）/ 模块级（最粗但漏检多）？有没有一个可量化的判据来决定"这个 PR 影响了哪些文档页面"？
2. 误报率控制：不是每个代码改动都影响文档（改内部逻辑、改日志格式、改测试代码都不影响）。怎么把"影响文档"的 PR 从 100% 里筛到 10~20%，同时不漏掉真正的 API 变更？有没有基于 AST / 注解 / OpenAPI spec 变更的过滤规则？
3. 工具选型：有没有现成工具或开源方案能跑"代码变更 → 文档影响面"的自动检测？（不是"文档生成"如 Swagger / Redoc，而是"变更影响面分析"。）如果没有现成工具，最小可用的自建方案长什么样？
4. 闭环验证：怎么验证"检测链路"本身是有效的？比如"过去 12 个月 47 次工单，如果检测链路在 T0 就触发，能拦下多少次？"有没有可复现的回溯验证方法？

【为什么问这个】 文档-代码不一致的 83% 不是"写错了"，而是"代码变了文档不知道该跟着改"。id=1399 讨论的是"口径描述和 SQL 对不上"，id=991 讨论的是"埋点代码与指标字典脱节"，id=1693 讨论的是"契约先行 vs 实现先行"——但"代码 PR 合入后，哪些文档页面需要跟着改"这个影响面检测，我还没看到社区有人专门讨论过。我想把"文档跟着代码走"从"靠人盯"变成"靠链路推"，哪怕 200 个接口、1500 个字段，也应该有办法在 PR 合入时自动标出"这篇文档需要 review"。