接口评审 · Agent 执行

接口兼容性审查

审查旧客户端升级到新服务端会在哪里失效，区分合同破坏与条件风险，给出最小反例、迁移方案和回归清单。

下载完整技能包查看 SKILL.md

网页展示方法和成果样例；任务由你的 Agent 结合实际材料执行，不在此页面发送接口请求。

输入什么，得到什么

需要的材料

旧版与新版接口合同；有调用方源码时可进一步确认影响。

交付成果

得到带变化位置和失败条件的报告，知道哪些字段需要迁移、哪些风险还需读取消费者确认。

响应样例只能证明观测变化；不把新增字段一律判成兼容，也不把静态审查当作上线验证。

完整输入样例

以下为合成演示材料，不代表真实业务数据。

比较方向：旧客户端调用新服务端。旧合同 POST /orders：请求 sku required，quantity integer minimum=1，note 可选。新合同：请求额外要求 warehouseId required；quantity minimum=5。旧响应合同：amount 为 required number，单位为元；status 为 required string enum[pending,paid]。新响应合同：amount 为 required string，仍为元；status 增加 refunded；新增可选 traceId。没有客户端源码。旧新定义分别标记为 old-contract 和 new-contract；未提供运行环境。

成果样例

以下为合成演示材料，不代表真实业务数据。

人工编写的静态审查样例，未执行请求。方向：旧客户端 → 新服务端。范围：POST /orders 给定的请求/响应约束；消费者未知。 3 项合同破坏，2 项依赖消费者的条件风险；未评估仓库权限和幂等，不能据此建议直接上线。

项目	分类与依据	最小反例	影响与迁移
warehouseId 新增必填	合同破坏：old-contract 请求无该必填，new-contract 要求	{"sku":"A","quantity":5} 旧合法、新缺字段	旧客户端必须补仓库选择，或经确认设计过渡版本；不能随便填默认仓库
quantity 下限 1→5	合同破坏：请求接受范围收窄	{"sku":"A","quantity":1,"warehouseId":"W"}	1–4 件旧请求失效；确认是否真要改变购买规则
amount number→string	合同破坏：响应类型更换	旧 {"amount":12.5}；新 {"amount":"12.50"}	数值型消费者可能解析失败；保持旧字段类型或新版本迁移，单独确认精度策略
status 新增 refunded	条件风险：响应枚举扩展	{"amount":"12.50","status":"refunded"}	未知客户端是否穷尽分支/拒绝未知枚举；须读取消费者后确认
可选 traceId 新增	条件风险：额外响应字段	同一旧响应增加 traceId	宽松消费者通常接受；严格 schema 校验/签名逻辑可能受影响，不能直接判阻断

必须补的回归

旧请求不带 warehouseId；记录新服务实际状态码和业务码，不预设为 400。
quantity=1、4、5 分别执行，仓库字段等其他条件保持合法。
旧客户端解析数字 amount 与字符串 amount；检验计算/显示，而非只检查 JSON 可解析。
将 refunded 和 traceId 分别单独引入，定位客户端反序列化或分支问题。

发布前需找到旧客户端消费者并完成以上验证。保留旧版本接口是候选迁移方案，不代表已实现。报告未核对部署、精度实现及真实用户影响规模。

回归用例样例

以下为合成演示材料，不代表真实业务数据。

准备两版服务或合同校验器，以及同一份旧客户端；合成资源、测试环境和调用授权到位后执行。没有运行时只能做合同校验，不记录实际通过。

ID	目的	控制条件	观察与断言依据
C01	新增必填影响	sku=A、quantity=5，不传 warehouseId	旧合同允许、新合同拒绝缺失字段；运行时精确错误码未给定
C02	最小购买量变化	warehouseId=W，分别 quantity=1、4、5，其余不变	1、4 旧允许新拒绝，5 两版允许；新增字段合法以隔离下限影响
C03	金额类型影响	其余字段相同且 status=paid，只改 amount:12.5→"12.50"	运行旧客户端的反序列化、计算与展示；合同类型已变化，客户端实际行为尚未知
C04	未知状态分支	保留旧响应的数字 amount，只将 status:paid→refunded	隔离枚举影响；具体退款行为需产品合同确认。混合样本用于消费者单因素测试，不声称满足新服务端完整合同
C05	额外字段处理	完整旧合法响应增加 traceId，其他保持不变	检查严格 schema、签名和解析策略；无消费者证据时记录条件风险

恢复：撤销测试创建的订单并核对库存与金额；仅使用获准的测试资源。接口语义及授权未确认前不发送创建请求。

使用指令

请阅读 api-compatibility-review/SKILL.md，审查下面两版接口。方向是旧客户端调用新服务端。输出 compatibility-report.md 和 regression-cases.md；区分合同破坏、条件风险与证据缺口，每项提供最小反例。旧版：
（材料或文件路径）
新版：
（材料或文件路径）
消费者：
（已知调用方；未知就保留未知）

完整方法与执行规则

以“旧客户端继续请求新服务端”为默认方向。用户要求其他升级方向时按其要求分析，并在报告开头写清。没有客户端或调用证据时可以判断合同风险，但不要声称已确认某客户端故障。

确定比较范围

记录旧/新合同版本、方法与路径、请求与响应媒体类型、鉴权、状态码及已知消费者。定位 OpenAPI $ref、DTO 和序列化配置的实际定义；引用到的公共 schema 需追到它使用的每个请求和响应位置。

只给两份响应样例时，报告“观测变化”，不能把出现过当必填，把没出现当删除，也不能从一次返回推断枚举全集。请求与响应的同名字段分开审查。OpenAPI 3.0 / 3.1 的 null 表达需按版本解释。

判定

阅读 references/compatibility-rules.md。先区分合同可确定的变化与依赖消费者的风险，再解释触发条件：哪一种以前有效的请求不再可用，或旧客户端以前不必处理的返回现在可能出现。

对每个重要变化提供：

旧定义与新定义的文件位置或 schema 路径。
最小反例请求/响应，不用无关大对象掩盖差异。
受影响消费者与证据；未知时明确写未知。
迁移方式和回归用例。区分临时兼容与最终合同，不建议静默强转金额或长期双义字段。

用源码确认消费者时，追到解析、条件分支和实际使用点；生成类型、页面展示和服务端 DTO 不是同一层。不要仅凭同名字段就认定调用关系。

交付

输出 compatibility-report.md 和 regression-cases.md，默认目录 artifacts/api-compatibility/：

摘要：比较方向、材料覆盖、已确认的合同破坏、条件风险、观测差异、未知项分别计数；不提供无依据百分制评分。
变化表：证据位置、方向、旧/新约束、最小反例、影响条件、建议与验证状态。
发布建议：哪些消费者需同步迁移，哪些可保留旧字段或版本接口过渡；给出退出兼容层的可验证条件。
覆盖边界：未解析引用、没有比较的接口、未读取的消费者或运行配置。

没有阻断问题只能说“在已审范围内未发现”，不能替代上线验收。默认只审查、生成报告与用例，不自动发布、改库或修改调用方。

验收

每个“破坏”都有方向和反例；新增字段、枚举扩展等条件风险不能一概判安全或一概阻断。样例不能冒充合同，报告不能把本地静态分析写成线上验证。

演示见 examples/input.md、examples/result.md 和 examples/regression-cases.md。