用途:以受控、显式的方式更新 API 请求/响应契约,使生产方与消费方保持对齐、破坏性变更可见且有意为之,并防止 schema 漂移。该技能只负责接口形状,不负责行为。
输入:端点或事件标识;新旧契约对比(新增/删除/变更的字段);兼容性要求(向后兼容、版本化或显式破坏性);仓库配置(优先 <repo>/REPO_PROFILE.json)。
输出:更新后的契约定义(OpenAPI/schema/类型/DTO,依仓库而定);若客户端与契约同处一地,则更新客户端接线;如仓库规范要求,在代码注释或文档中记录兼容性说明。
非目标:不实现后端行为、不实现前端 UI 逻辑、不做持久化变更。
工作流:定位契约的权威来源(schema/类型/规范);尽可能采用先加后改的增量策略;如支持则显式标记废弃字段;更新生成或手写的客户端绑定;确保不把行为假设泄漏进契约;如可用则运行 schema/类型校验;若契约变更引入条件行为或有状态流程,建议使用 system/state-machine-mapper。
检查项:契约可编译/校验通过;消费方仍能通过类型检查(或已记录显式破坏);schema 注释中未编码行为。
失败模式:未版本化的破坏性变更应阻止并上报;契约存在歧义时建议使用 meta/spec-sculptor。
遥测记录:skill: api/contract-update、change_type(additive/breaking/versioned)、endpoints_affected、outcome。