SuperAPI AI 工具集

api-changes

编程与开发

查看项目

更新于 10-16 06:48

技能介绍

用途:当客户可见的 API 发生变更(即 api-report 下的 .md 文件与分支解析出的比较基线不同)时,引导完成发布标签、文档、审批与发布说明的检查。

主要能力与用法:

  1. 识别变更:先读取并执行 .claude/skills/comparison-base/SKILL.md(以 HEAD 作为 $REVIEW_REF),用其解析出的目标与比较提交。比较基线与工作区而非仅 HEAD,因为 API 报告常刚重新生成且未提交: git diff "$BASE_COMMIT" -- ':(glob)/api-report/*.md' git ls-files --others --exclude-standard -- ':(glob)/api-report/*.md' 两者输出并集即变更的 API 报告;未跟踪报告需整文件按新 API 面读取。随后生成含包名、变更类型、标签、是否破坏性的汇总表。若全部为 @internal,则告知无客户可见变更并停止。
  2. 检查发布标签、文档与导出可达性:新导出须有发布标签,缺失会触发 ae-missing-release-tag。标签选择:@public(稳定、完整 SemVer,仅形态最终时用)、@beta(征求反馈、生产可用需谨慎)、@alpha(实验性、不建议生产)、@internal(仅框架内部)。不确定时用 @alpha。@legacy 为配对修饰符,不用于新 API。客户可见导出须能从包公共入口(如 src/index.ts 或 src/alpha.ts、src/beta.ts 等分层入口)经各级 index.ts 桶文件可达,否则视为不完整;并须有 TSDoc(至少摘要、@param、适用时 @returns)。
  3. API Council 审批:@public、@legacy @public、@beta、@legacy @alpha 需审批,fluid-cr-api 会自动被指派为必需审阅者;仅 @alpha 不需要但鼓励提前沟通;@internal 不需要。审批与区域负责人审阅相互独立。
  4. 破坏性变更评估:@public 或 @legacy @public 的破坏性变更很可能是错误,须配合大版本发布,旧 API 至少提前 3 个月在小版本中弃用并提供替代。@beta 或 @legacy @alpha 的破坏性变更只能进入以 10 递增的小版本(2.10、2.20、2.30…),PR 须暂存在 test/breaks/client/#.#0/ 分支并等待破坏窗口,需确认合作伙伴(如 office-bohemia)是否直接使用,存疑则按使用处理并预留 12 周。仅 @alpha 虽无稳定性保证,但有非正式约定不破坏 office-bohemia,若可能破坏需走同样流程;否则每日集成流水线会捕获,FF OCE 会回滚或联系处理。
  5. 弃用清单:@deprecated TSDoc 须含弃用版本、移除版本、替代项与跟踪 issue 链接;须用“Deprecated API”模板提交 GitHub issue 作为相应跟踪 issue 的子 issue;移除代码库内使用(仅测试用途可保留并加说明);具备发布文档。
  6. 发布文档:记录新增、修改、弃用、发布级别提升与移除。使用 changeset 的组需检查分支差异与工作区中该组 .changeset 目录是否已有条目,缺失则从仓库根创建: pnpm flub changeset add --releaseGroup <releaseGroup> --empty 编辑生成文件,YAML front matter 仅列出该组中对消费者有影响的包,bump 类型用 minor,__section 取自发布说明章节。摘要行须简洁、无句末标点、无反引号、现在时,可心理前置“In this release,”验证通顺;正文可为功能、弃用与破坏性变更附代码示例。草稿须先给用户确认。
  7. 汇总:列出发现的 API 变更表、缺失的发布标签或文档、是否需要 API Council 审阅、破坏性变更警告与所需流程、弃用问题、发布文档状态,并给出明确的 go/no-go 结论。

限制:本技能依赖仓库内 .claude/skills/comparison-base/SKILL.md 与相关文档路径;具体命令、标签与流程以资料所述为准,未提供的细节暂未提供。