社区维修站准备开放预约接口。网页负责收集申请，值班平板查看当日队列，合作站点每天同步一次结果。三个消费方上线节奏不同。后端即使通过自己的单元测试，也可能让旧平板因枚举变化读不出预约，或让合作站点读到不属于自己的记录。团队把交付拆成接口契约、验收证据和可复现的文档包，三者使用同一个版本号。
先把业务决定写入接口契约
先用一句话说明资源和操作。预约记录属于一个站点，由访客提交，值班员确认，合作站点只能读取本辖区的同步结果。记录每个操作的调用者、状态前提、输入字段、成功结果与失败结果。例如创建预约需要站点编号、预约时段与器材类别，创建后返回预约编号和初始状态。客户用于重试的请求键独立于预约编号。重复使用同一个键和相同输入时返回已有预约，换了时段却沿用原键时返回明确冲突。服务方与消费方在写代码前签下这两条约定。
为每个字段写类型、单位、是否必填、允许为空的情形和示例。时段使用带时区的值，窗口的结束点是否包含要单独定义。错误响应包含稳定的机器可读代码和请求编号，客户端可按代码区分缺字段、时段已满、越权和临时不可用。为几个容易混淆的状态补上前后关系，比如已取消的预约能否重新确认，确认失败后是否保留原状态。契约还应说明分页游标是否可在筛选条件变化后继续使用，以及同步接口如何处理同一时间戳上的多条记录。
先拿三条虚构预约走一遍评审。网页提交一条，值班员确认一条，合作站点按游标读一页。每一步都给出实际请求和预期响应，确认客户端能从返回结果得出下一步操作。对于没有决定的细节，比如重复提交冲突能否返回原预约编号，在评审记录中标明负责人。生成设计草稿的工具可以填齐字段结构和示例。是否暴露业务数据、是否承诺幂等、哪些状态可回退仍由团队决定。
识别消费方，逐项检查兼容性
建立消费方清单，记录当前部署版本、使用的端点和字段、发布时间、联系人以及是否能快速回退。网页每周发布，值班平板可能数月才更新一次。同步脚本没有界面，若遇到未知状态可能直接退出。为每一项改动写预期影响。删除响应字段会影响仍读取它的脚本，新增可选字段也可能碰到拒绝未知字段的客户端。把兼容性声明与实际消费方测试结果放在一起，减少依赖直觉。
例如团队打算增加“等待器材”状态。先用旧平板回放带新状态的响应，观察它是展示未知状态、隐藏整行还是崩溃。若旧客户端无法处理，可以让旧契约继续返回兼容视图，新契约按约定提供更细粒度的状态。明确状态映射会损失什么信息，以及旧版停止支持前需要哪些消费方升级证据。若分页顺序也要变化，把它作为单独变更评审，以免查到漏单时无法区分原因。
用契约比较工具列出端点、字段、枚举和错误的变化。再让各消费方用冻结的真实请求形状运行测试。即使结构差异检查通过，也要确认默认行为。例如同步端点仍返回相同字段，但默认从全量改成只读当天，就可能让原有同步静默漏数据。为依赖默认行为的请求保留一条回归用例。每个差异记录消费方、观察到的行为、是否需要迁移及上线条件。
在隔离环境测试鉴权与错误
构造两个站点，各有一条名称相同、编号不同的预约。准备访客、站点值班员、只读同步账号三种最小权限身份。先证明每种身份能完成自己获准的操作，再测试修改请求中的站点号或预约号。访客不应确认其他人的预约，同步账号不应写入，站点甲的值班员不能读取站点乙的详情。对每次拒绝记录返回代码、请求编号和测试后台是否保持原状态。错误中不要带出别的站点的预约内容。
分别测试未登录、过期凭据和已登录但缺少权限，确认客户端能区分重新登录和提示权限不足。凭据存放在测试环境约定的位置，报告只记录角色、作用域和请求编号。创建端点还要验证同一请求键并发提交、服务已落库但客户端超时、时段容量边界。超时后检查服务端记录，再从客户端发起同键重试，预期只存在一个有效预约。请求层测试用来核对响应和副作用，网页测试用来确认界面如何呈现错误与恢复状态，二者各自记录证据。
使用测试生成能力时提供契约、权限表和样例数据，要求每条用例写明初始状态、凭据角色、请求、预期响应和最终业务状态。优先审查涉及跨站点访问和重复写入的用例。若脚本只检查状态码，补充对返回内容和记录数的断言。失败信息应能指向具体用例和契约版本。测试结束后清理本轮的虚构记录，避免下次执行从错误的初始容量开始。
用消费方验收决定上线和回退
先在测试环境让三个消费方各跑一条完整路径。网页提交预约后得到编号，平板按编号查到预约并确认，合作站点翻页同步时看见最终状态。验收同时保留旧平板构建和旧同步脚本，回放它们曾经通过的请求。每个消费方给出通过证据和剩余问题。若只有新网页通过，发布结论还需要说明旧端的处理方式。
上线前写清停止条件。比如同步结果出现重复记录或旧平板无法读取当天队列，就暂停新版流量，并从日志定位是契约变化还是部署差异。旧版路由和客户端配置应在上线前演练过恢复。若新版写入了旧版不认识的状态，先确认旧版是否能读取或映射这些数据。只切回程序版本可能仍让旧接口读到未知状态。将数据兼容检查和程序回退演练写进同一份清单，并由能访问测试数据的人复核。
一次演练中，新游标用预约时间排序，测试记录恰好有两条预约在同一分钟。同步脚本的第二页漏了一条。先保存请求顺序、游标和实际返回，再重跑只包含这两条记录的样例。修复后确认顺序稳定、分页不重复也不丢失，然后再让旧脚本执行其原有分页用例。发布说明记录修复影响的契约版本，避免把测试通过误当成所有客户端都已升级。
从契约生成面向消费方的文档
文档与实现采用同一版本的接口描述。用它生成端点、参数和类型表，再补充认证准备、首次请求、常见错误、分页与重试建议。说明示例使用虚构站点和测试账号。对每个请求样例执行一次，将响应与契约约束比较。若文档里展示的是特意裁剪后的响应，在示例旁说明省略了哪些字段。不要让文档编写工具替团队决定某个字段是否可选。
交付包包含版本化契约、可运行样例、消费方验收结果和迁移说明。迁移说明按使用者写清改哪些请求、何时切换，以及失败时如何回到兼容版本。部署后抽查公开文档是否指向发布版本，示例是否仍可在约定的测试环境运行。若示例报错，区分示例过时、访问设置错误和线上行为不符合契约。修复应落到负责该问题的版本化产物，再重新生成受影响的文档。
如何挑选合适的 Skill
先按工作步骤检索。接口设计阶段找能输出可审阅契约的能力，检查支持的描述格式、是否会自动修改项目文件以及如何处理未定字段。验收阶段找能读取契约并生成鉴权、边界和消费方用例的能力，核对目标环境与凭据来源。文档阶段找能从版本化描述生成样例的能力，并验证是否可在本地重现。检索时可从目录页面按具体操作搜，或在 Agent 中使用已核实来源的技能检索入口。候选技能需要打开详情、查看维护来源和运行前提，再用最小样例试跑。
试跑时给所有候选同一份三端点契约和两个有意设置的错误。检查哪个能指出缺失的失败响应、哪个能定位权限角色遗漏、哪个能保留精确的来源和版本。只保留输出可审查、修改范围可控制的能力。若一个工具会直接调用服务，先在隔离地址运行并检查实际发出的请求。将选择理由、命令前提和退出条件写进交接文档。
常见问题
已经有接口实现，还需要补契约吗？
先从生产行为与消费方依赖反推现有约定。收集三类代表性请求，在测试环境重放，标注代码、文档与实际结果不一致的地方。让负责人决定哪种行为是承诺，再把确认结果写进版本化契约。这样补文档时不会无意中承诺仍未实现的行为。
通过契约校验就能发布吗？
契约能证明结构符合约定。状态流转、权限和旧客户端对未知字段的反应还需要消费方验收。发布决定应结合两类结果，并检查回退能否处理新版本已经写入的数据。
一个错误响应应该写多详细？
给调用者稳定的错误代码、能采取的下一步和便于追踪的请求编号。详细内部原因留在授权日志。比如容量已满可以让用户选其他时段，跨站点请求则按契约返回拒绝，避免通过错误内容泄露记录是否存在。
怎样避免每次都重新写一份文档？
在同一处维护字段和响应示例，发布时用同一版本的契约驱动校验、样例执行与文档生成。人工补充迁移与业务语义。为示例设置可重跑的测试数据，让后续编辑者能明确验证示例和说明是否仍然准确。 对网页消费方，可用关联的 Webapp Testing 执行预约、错误反馈和重试恢复。提供获准访问的测试网址、虚构账号与预期页面结果。保存失败截图和复现路径，服务端记录数仍用独立断言核实。