接口改了，旧文档仍在误导编程 Agent

一次查询参数改名，代码正常、测试全绿，changelog 也写了，公开文档却还让用户发送 limit。两周后，作者先从支持讨论里发现问题，又发现 coding agent 读了旧文档，生成了错误的客户端代码，让调用者以为 API 坏了。

作者借这次事故提出了 PaperDrift：把已发布文档和 PR 描述或 changelog 放在一起，找出过时的说法，再按影响排序。值得讨论的是，这种轻量检查能解决哪一段问题，又有哪些事情根本无法替你完成。

测试全绿，为什么客户端还是会出错

这次事故里，产品代码和文档走到了不同的时间点。查询参数已经改名，文档里的调用方式却停在旧版本。原文没有交代新参数叫什么，也没有给出具体版本号。

过去，错误文档需要经过读者理解、复制和调试，才会影响软件。现在，coding agent 可以直接读取文档并生成客户端代码。页面上的旧说法，就这样进入了另一个程序。

公开文档也是其他工具消费的接口，代码测试通过并不能证明这个接口仍然准确。

changelog 里写过一次变更，也不能替代文档修订。用户和 agent 未必会同时读两份材料，更不会自动替维护者判断该相信哪一份。

作者因此把问题缩小为一个具体任务：拿今天发布在外的文档，对照刚交付的变更，找出两者互相矛盾的地方。例如参数改名、响应字段删除、新增必填 header、端点弃用、默认值变化，以及不再适用的状态码。

这里比较的不是文字是否相同，而是文档里的某个承诺是否还成立。作者认为，难点在于找全：一篇 3,000 词的文档，即使反复读，也可能漏掉认证章节里的一句话。

为什么报告必须告诉你先改哪一条

PaperDrift 的操作很直接：粘贴已发布文档，再粘贴 PR 描述或 changelog，无需安装。它返回按严重程度排序的偏差报告，并附上修复清单。

作者希望拿到的结果，是明确指出哪些说法已经错误、其中哪些会导致客户端失败。参数改名、字段删除、认证变化、新增必填输入，通常应该优先处理；过时的默认值、截图和旧流程描述，则可能排在后面。

排序让报告变成可以分配的工作。文档负责人不用先重新分析整次发布，就能知道需要核对和修改哪些地方。

但这个顺序只是判断，不是测量。PaperDrift 不运行 API，也不执行示例，更不知道一条排得靠后的说明，是否恰好是最大客户依赖的行为。作者自己仍会阅读报告，并调整顺序。

所以，高严重程度只能说明两份输入文本之间存在值得优先检查的冲突，不能证明线上调用已经失败。

粘贴检查省了接入，也留下了盲区

「Drift」容易让人联想到持续监控，但 PaperDrift 不抓取文档站，不连接仓库，不订阅 PR，也不会主动发现变化。

它只比较你当时粘贴的两份文本。不运行就没有检查；粘贴后文档又发生变化，旧报告也随即失去时效。它还不会代写修订内容，最终编辑仍由维护者完成。

作者选择这条路线，是因为持续监控需要处理更多问题：仓库权限、哪些页面需要关注、代码变化如何映射到文档，以及每次重构带来的误报。粘贴方式则能让使用者清楚看到输入范围，发布前检查一次即可，不必引入常驻服务。

这是作者对其目标团队的取舍。原文没有提供接入成本、检出率或误报率的对照数据，无法据此判断这种方式普遍优于持续监控。

我的判断

我认同把文档中的「行为承诺」作为检查对象。前端和 Node 客户端依赖的是参数、字段、认证条件这些具体约定。只确认文档文件有没有修改，很容易漏掉散落在示例和其他章节里的旧说法。

不过，工具的有效性受输入约束。如果 PR 描述或 changelog 漏写了行为变化，仅靠这两份文本就缺少判断依据。原文也没有解释 PaperDrift 使用什么模型、怎样识别矛盾，更没有展示完整报告或准确率评估。它目前给出的是产品思路和作者经验，效果仍需验证。

和人工逐段核对相比，这种报告可能减少阅读负担；和持续监控相比，它省去接入工作，却依赖有人记得检查。对于能执行的 API 示例，运行检查还能提供文本比较没有的证据。两者适合互补，原文没有证明任何一种可以包办文档正确性。

能拿来做什么

• 修改 API 参数、响应字段或认证要求时，把当前公开文档与本次 PR 描述一起核对，尤其检查前端和 Node 客户端会直接复制的请求示例。
• 在发布检查中安排一次文档对照，并明确执行人；采用粘贴工具时，要确认输入包含相关章节和实际行为变化。
• 收到偏差报告后，先验证会导致调用失败的项目，再结合客户依赖调整优先级，不要直接把严重程度当成线上故障结论。
• 对修订后的关键调用示例实际发起请求，确认参数和认证方式可用；文本报告指出冲突之后，修改与验证仍需要人完成。