44% 的开发者只能直接翻源码理解 API 行为 · 过时文档的利息,在客户联调卡住那一刻到期
研发与开发者文档 · 真实业务触发
优选百货的集成联调群炸了:客户开发者按文档示例调 `/settlement/reconcile`,返回的 `amount` 字段在文档里是字符串、实际是数字,联调直接报错——排查发现该端点在 v2.1 灰度中改了返回结构,文档站还停在 v2.0;技术负责人要求本周内给出「还有多少个端点是这样的」的完整答案。
不是流程描述,是调研出来的真痛点 —— 每条可点开核对出处
变化不在「快」,在「参与的角色」和「覆盖的范围」
5 步 · 每一步的产出都是下一步的输入
痛感 4 × AI 适配 4 ÷ 落地难度 2 = 8.8
最大差异点 · 不是「帮开发者写文档」:巡检的输入是文档站、OpenAPI 规范、近期合并记录三方对照,输出是逐端点的漂移清单(参数/返回/示例/状态码四类漂移)+ 每条的影响面(哪些客户在用这个端点——来自联调工单与集成登记表)。修复优先级按「客户在用的漂移优先」排,而不是按发现顺序排。
评分口径:痛感看「这事没做好谁会生气、生气到什么程度」; AI 适配看「输入是否非结构化、是否要跨部门取数、错了能不能当场看出来」; 落地难度是分母 —— 需要客户先做数据治理的场景,分数会被压得很低。
判断标准只有一个:这份东西能不能直接进企业的流程
巡检只对照「文档/规范/代码实际行为」三方给出漂移清单,不直接改文档——修复由研发在评审后执行;生产环境的实际行为验证只用只读调用,不碰数据;示例代码的核对以「可运行」为准,风格问题不进清单。
Live Demo 里有一个完整案例的每一步,包括 Agent 在哪一步拦住了