检查接口与协作约定的缺口

这个场景能帮你做什么

接口文档只列内部字段，可能漏掉最外层响应包装、错误码和状态约定。WorkBuddy 可以对照接口、调用代码和业务流程整理契约差异，为联调准备具体问题。

开始前需要准备什么

提供接口说明、真实样例、服务端与调用端相关代码、角色权限和版本。涉及异步或多方协作时补任务归属、重复处理、超时和交接规则。

具体怎么做

第一步：完整提取接口形态

记录方法、路径、认证、请求、响应包装、字段类型、必填、空值与错误。样例与文档分开，不能用一个成功样例推断全部情况。

第二步：对照双方实现

核对字段名、层级、单位、枚举与版本，重点检查包装对象、可空值和失败返回。未知字段保留问题，不由 AI 选择一侧作为标准。

第三步：检查操作与交接

明确超时后怎样确认结果、重复提交如何识别、过期状态能否写入、哪方负责更新。规则缺失时提出设计问题，不声称工具天然保证幂等和一致性。

第四步：生成联调样例

列正常、缺项、无权限、超时和重复请求的输入与预期，注明哪些预期尚待双方确认。真实联调要在适用环境执行。

响应包装缺失怎样变成具体联调问题

以下为教学示例：文档写成功响应为 {"id":"T1","status":"done"}，调用端因此读取 response.status；服务端提供的实际样例却是 {"code":0,"data":{"id":"T1","status":"done"}}。此时应输出一条可定位的问题：

项目	文档及调用端	服务端样例	缺口与待确认动作
成功响应中的状态字段路径	response.status	response.data.status	外层包装约定不一致；双方确认目标版本、成功码与解包责任，并补充 data 为空及错误响应样例

如果调用库已经统一解包，业务代码读取 response.status 也可能正确，因此还要核对中间封装层，不能仅凭这一对样例断定代码有错。让双方确认后再修订文档、实现和测试预期；不要让 AI 自行选一种结构当成最终协议。

可以直接交给 WorkBuddy 的完整要求

核对附件接口文档、样例与双方代码，覆盖请求、最外层响应、字段、空值、错误码和版本。
列明确差异与未知约定，附双方位置。检查超时、重复、过期写入、权限和任务交接责任。
输出契约缺口及联调样例，不伪造已达成约定，不修改或调用生产接口。

完成后会得到什么

一份接口差异表、协作约定缺口和可用于测试环境联调的样例。

结果应该怎么检查

双方开发者核对真实请求响应，检查嵌套、空值和异常。确认联调预期来自约定而非 AI 猜测。

遇到这些情况怎么处理

文档落后于代码时先确认目标版本。服务端无法提供异常样例时安排测试环境验证。涉及状态不明的写入先查结果，不直接重复执行。

哪些必须人工决定

接口双方确认契约与兼容性，负责人决定变更和上线。AI 找差异，不替代联调或保证系统一致性。