技能介绍

要解决的问题

破坏性 API 变更一旦缺少统一模板，通知很容易只剩一句「接口要改了」。调用方既不知道改哪个字段，也不清楚兼容期到哪天、自己需要做什么，最后反复邮件确认，迁移窗口被拖长。内部团队常把面向集成方的通知写成面向终端用户的更新日志，关键动作被弱化。

技能如何工作

本技能只做一件事：把破坏性 API/契约变更整理成可发给调用方/集成方的通知草稿，固定包含六个部分：

摘要：一句话说明什么变了、为何变、要求对方做什么
破坏点清单：接口、字段或行为变化的新旧对照
影响面：按调用场景列出可能受影响的一方，不点名公司机密
兼容与时间线：兼容期、废弃日、强制切换日；未知则标 待确认
迁移步骤：调用方可执行的最少操作
联系与回滚：问询渠道；有临时回退策略时写明

使用时先澄清最少必要项，包括 变更点、旧→新行为、时间线、兼容策略、联系渠道。缺少变更点或新旧对照时会先追问，不会写空通知。随后判定是否真正破坏性：仅新增可选字段且旧客户端无感时，提示可改用常规 changelog；涉及删除字段、语义变化或必填调整时，按完整模板输出。填写时严格参照 references/notice-template.md，未确认日期只写 待确认，并在文首提醒「请补齐日期后再群发」。自检会确认调用方是否只看通知就能完成迁移、是否误写成 C 端文案、是否出现未提供的截止日期。

适用边界

适合字段废弃、错误码变更、鉴权方式变更、分页语义变更等需要预告的 breaking change。不适合面向终端用户的版本更新文案、自动推送调用方系统或网关配置调整、从零撰写完整 OpenAPI 站点。它不代发邮件或 Webhook，不访问网关、代码仓库或邮件系统，也不自动扫描调用方列表。即使只有内部服务调用，仍可把影响面写为「内部消费者」。