SuperAPI AI 工具集

changesets

编程与开发

查看项目

更新于 10-20 16:21

技能介绍

changesets 是一个面向 PR 收尾阶段的变更集(changeset)技能,用于在实现范围完成且聚焦验证结束后,为整个 PR 生成或更新发布说明级别的变更记录。它的核心定位是:changeset 应被视为整个 PR 的发布说明,而不是工作过程中的日志,因此应在当前实现范围和聚焦验证完成后再最终确定。

用途方面,该技能帮助开发者系统化地判断一个 PR 是否影响已发布包、影响属于哪个级别,并据此决定需要记录变更集、更新已有变更集,还是明确说明无需变更集。它特别强调 PR 层面的合并:默认每个 PR 只保留一个 changeset 文件,一个文件可以声明多个包并汇总多个相关修复或新增;同一 PR 内后续的提示、提交和子任务都应更新该文件。只有在维护者要求拆分,或 PR 包含需要独立发布说明的独立变更时,才使用多个文件。

主要能力包括:从合并基点检查完整 diff(含 PR 已引入的 changeset 文件),识别直接受影响的已发布包;按源码类型、运行时行为、入口点、必需服务、生命周期以及持久化或传输数据分类影响;执行破坏性变更审计,覆盖名称与位置(导出、入口点、兼容导出、模块路径)、调用兼容性(参数、可接受输入、重载解析、泛型参数、默认值)、结果兼容性(返回与错误类型、输出收窄、成员、推断、必需服务)、运行时契约(默认值、失败、中断、并发、顺序、资源生命周期、获取、清理、变更)以及数据兼容性(持久化 schema、编码、数据库布局、协议、传输格式)。

使用方式上,技能要求在实现范围和聚焦验证完成后进行最终化:检查完整 diff,分类影响,执行破坏性审计,然后记录无需变更集的理由或更新 PR 已有变更集;仅在 PR 没有变更集时创建新的。需要时阅读 authoring.md。最后校验包名、frontmatter、版本提升策略以及简明、面向消费者的描述。不应包含无关的工作区变更。

适用场景为需要规范管理发布影响、避免重复变更集、确保破坏性变更记录完整的包管理项目,尤其是 JavaScript/TypeScript 生态中涉及多包发布与语义化版本管理的 PR 收尾流程。

限制与注意事项:仅测试变更、保持行为的内部重构、文档或 JSDoc 维护以及未发布的工具通常不需要变更集;当不确定时,应检查导出和消费者可见声明,而不是根据源码位置推断。新增导出、可选参数和保持行为的实现通常不算破坏性变更;恢复文档契约的修复通常也不算破坏性,但如果其运营影响对消费者可见,仍需要变更集。当重载顺序、结构可赋值性或推断使兼容性不确定时,应验证代表性的现有调用。API diff 输出只是机械证据,不是语义化版本决策。任务完成的标志是:所有受影响的契约和已发布包都已纳入考虑,且要么明确做出无变更集的决定,要么 PR 默认拥有一条合并后的有效变更集,其发布说明描述每个破坏的消费者影响和迁移方式,而不重复 PR 描述。