Changelog 收集工具

目标

帮助开发者收集 Ant Design 两个版本之间的 Changelog，处理临时文件并更新到官方 CHANGELOG.zh-CN.md 和 CHANGELOG.en-US.md 文件中。

触发方式

当用户提到以下关键词时使用此 skill：

• 收集 changelog
• 生成 changelog
• 更新 changelog
• 版本对比
• 处理 changelog

核心流程

阶段一：通过 gh CLI 收集 PR 信息

使用 GitHub CLI 直接收集两个版本/分支之间的 PR 信息。

1.1 获取可用的 Tags

执行 git fetch --tags 确保最新，然后获取所有 tags：

git tag --list | grep -v -E '(experimental|alpha|resource)' | sort -V | tail -20

过滤规则：

• 排除包含 experimental、alpha、resource 的 tag
• 保留最近的 20 个有效版本 tag

1.2 选择起始版本和目标分支

交互式询问用户：

🏷 请选择起始版本（tag）：
- [列表显示最近的 tag]
- [自定义输入]

🔀 请选择目标分支：
- master
- feature
- 自定义输入

1.3 确定版本号

重要：在开始收集 PR 信息之前，必须先确定版本号并写入 ~changelog.md 的头部。

根据起始版本自动计算新版本（默认按 minor 升级）：

当前选择: 6.3.1 → master

请确认版本号：
- [minor] 升级到 6.4.0（次版本号）
- [patch] 升级到 6.3.2（修订版本号）
- [自定义] 输入具体版本号

用户确认后，立即初始化 ~changelog.md 文件，写入版本信息：

# Changelog Temp File

# Version: 6.4.0

# Generated: 2026-03-09T...

---

这样在后续收集 PR 信息时，每次追加写入都能保证 ~changelog.md 是完整可用的。

1.4 获取 commit 列表

git log <from-tag>..<to-branch> --oneline

解析每个 commit，提取 PR 编号（匹配 #12345 格式）。

1.5 并行获取每个 PR 的详情

使用并行 subagent 同时获取所有 PR 详情，而不是顺序逐个请求。

将所有 PR 编号分批（每批最多 10 个），为每批 dispatch 一个 subagent，并行执行：

[主流程]
  ├── subagent-1: gh pr view 56001 56002 56003 ... 56010
  ├── subagent-2: gh pr view 56011 56012 56013 ... 56020
  └── subagent-3: gh pr view 56021 56022 ...

每个 subagent 执行的命令：

gh pr view <pr-number> --json title,body,author,number

返回字段：

• title: PR 标题
• body: PR 描述（可能包含中英文 changelog）
• author: 提交者
• number: PR 编号

所有 subagent 返回后，汇总结果，再统一进行描述提取和写入。

每处理完一个 PR 后，立即追加写入 ~changelog.md。

追加写入内容：

## abc1234

- PR: 56976
- Committer: zombieJ
- Commit: fix: Select height issue
- Category: Select
- English: Fix Select incorrect height when value is empty
- Chinese: 修复 Select value 为空时高度不正确的问题

从 PR body 提取并校验中英文描述

PR body 中的 changelog 作为参考，以实际改动为准。 PR 作者的描述可能不准确，需结合实际改动判断，必要时重新撰写。

PR body 中提取 changelog 的模式：

🇺🇸 English
- Fix Select incorrect height when value is empty

🇨🇳 Chinese
- 修复 Select value 为空时高度不正确的问题

或者：

English:
- Fix Select incorrect height when value is empty

Chinese:
- 修复 Select value 为空时高度不正确的问题

提取规则：

• 识别 🇺🇸 English 或 English: 标记后的 - 行作为英文描述
• 识别 🇨🇳 Chinese 或 Chinese: 标记后的 - 行作为中文描述

提取后必须按照 antd changelog 规范进行校验，不合规则改写（见下方"Changelog 合规校验"）。

如果 PR body 中没有 changelog 内容，则根据 PR title、body 描述和 commit 信息自动生成符合规范的描述（见下方"无 changelog 时自动生成"）。

过滤规则：哪些 PR 不写入 changelog

以下改动不应出现在 changelog 中（用户无感知）：

• 纯内部重构（不影响 API 和行为）
• 纯测试更新（新增/修改测试用例，无功能变更）
• CI/工具链/依赖升级（与组件无关）
• 文档/站点样式微调（不影响组件本身）
• chore、build、ci 类型的 commit

依赖升级默认跳过，但不能机械按 chore 跳过。遇到 rc-component、@ant-design/icons 或其他运行时依赖升级时，必须额外核查是否带来以下用户可感知影响；如果有，必须保留并解释影响：

• 组件新增能力、行为变化或可访问性变化
• TypeScript 定义外露变化（例如 antd props 继承到的新属性、回调参数或语义化类型）
• 包体积收益或运行时代码减少
• 默认图标、样式或交互变化

遇到上述类型，在 ~changelog.md 中标记 Skip: true，最终写入时过滤掉。

Changelog 合规校验

对从 PR body 提取的描述，逐条检查以下规范，不符合的必须改写：

规则	正确示例	错误示例
Emoji 必须在行首	🐞 Fix Select height	Fix Select height 🐞
必须以动作动词开头（Emoji 之后）	🐞 修复 Select ... / 🆕 新增 Button ...	Select 修复...
正文必须包含组件名	🐞 Fix Select height issue	🐞 Fix height issue
组件名不加反引号	Fix Select height	Fix \Select` height`
属性名/API 用反引号	Fix Select \value` prop`	Fix Select value prop
组件名后不加冒号	🐞 Fix Select height	🐞 Fix Select: height
中文与英文/数字之间保留空格	修复 Select 在暗色主题的问题	修复Select在暗色主题的问题
每条只选一个 Emoji，不叠加	🐞 Fix Select ...	🐞🆕 Fix Select ...
描述开发者影响，不描述实现细节	Fix Select height when empty	Remove minHeight CSS property
新组件必须描述功能用途	🔥 Add BorderBeam component for animated border beam effect along container edges.	🔥 Add BorderBeam component.
新属性必须说明用途或效果	🆕 Add Input \allowClear.disabled` prop to disable the clear button while keeping it visible.`	🆕 Add Input \allowClear.disabled` support.`
从用户/开发者视角描述效果	📖 Improve AI agent support for ant.design.	📖 Add .well-known metadata.
Token 改动列出具体 token	🆕 Add Collapse \headerPaddingSM` and `contentPaddingSM` tokens.`	🆕 Add Collapse size tokens.

文案校验时逐条追问："用户或开发者看到的变化是什么？" 如果答案只是"传递某配置"、"修改某 runtime"、"增加某 metadata"、"调整内部结构"，说明文案仍是实现视角，必须改写为可感知效果。

Emoji 规范（完整版，从 AGENTS.md 同步）：

Emoji	用途
🐞	修复 Bug
💄	样式更新或 token 更新
🆕	新增特性 / 新增属性
🔥	极其值得关注的新增特性
🇺🇸🇨🇳🇬🇧	国际化改动
📖 📝	文档或网站改进
✅	新增或更新测试用例
🛎	更新警告/提示信息
⌨️ ♿	可访问性增强
🗑	废弃或移除
🛠	重构或工具链优化
⚡️	性能提升

commit 类型 → Emoji / 动词 映射：

commit 前缀	中文动词	英文动词	Emoji
fix: / bug:	修复	Fix	🐞
feat: / feature:	新增	Add	🆕
style: / ui:	优化	Improve	💄
refactor:	重构	Refactor	🛠
perf:	提升性能	Improve performance	⚡️
docs:	更新文档	Update docs	📝
i18n: / locale:	更新国际化	Update i18n	🇺🇸
deprecate:	废弃	Deprecate	🗑
chore: / test: / ci:	—	—	跳过，不写入

无 changelog 时自动生成

当 PR body 中没有 changelog 内容（无 English/Chinese 标记）时，根据以下信息生成：

1. 优先使用 PR title（经过格式标准化，不能原文照抄）
2. 参考 PR body 的描述内容（提取关键改动点，描述对开发者的影响）
3. 如有必要，查看 git show <hash> 的 diff 内容辅助理解改动

生成规则：

• 根据 PR title 前缀或内容判断动作类型（fix/feat/style 等）
• Emoji 置于行首，选择对应的 Emoji 和动词
• 格式：Emoji 动词 组件名 改动描述（中英文各一条）
• 描述"对开发者的影响"，而非"具体的实现细节"

示例：

PR title: fix(Select): fix height issue when value is empty
↓ 自动生成
English: 🐞 Fix Select incorrect height when value is empty
Chinese: 🐞 修复 Select value 为空时高度不正确的问题

识别组件 Category

从 PR title 和 body 中识别组件名：

const componentNames = [
  'Button',
  'Checkbox',
  'Radio',
  'Switch',
  'Input',
  'Select',
  'TreeSelect',
  'Cascader',
  'DatePicker',
  'TimePicker',
  'Calendar',
  'Upload',
  'Modal',
  'Drawer',
  'Message',
  'Notification',
  'Popconfirm',
  'Tooltip',
  'Popover',
  'Table',
  'List',
  'Tree',
  'Tabs',
  'Steps',
  'Progress',
  'Spin',
  'Avatar',
  'Badge',
  'Tag',
  'Card',
  'Collapse',
  'Carousel',
  'Breadcrumb',
  'Pagination',
  'Menu',
  'Dropdown',
  'Form',
  'Descriptions',
  'Skeleton',
  'Empty',
  'Result',
  'Alert',
  'Typography',
  'Layout',
  'Grid',
  'Space',
  'Flex',
  'ConfigProvider',
  'App',
  'Watermark',
  'ColorPicker',
  'QRCode',
  'Segmented',
];

匹配规则：大小写不敏感，包含匹配。

阶段二：处理临时文件

读取 ~changelog.md 后，按以下规范处理：

临时文件格式：

# Changelog Temp File

# Version: 6.4.0

# Generated: 2026-03-09T...

---

## abc1234

- PR: 56976
- Committer: zombieJ
- Commit: fix: Select height issue
- Category: Select
- English: Fix Select incorrect height when value is empty
- Chinese: 修复 Select value 为空时高度不正确的问题

**AGENTS.md 规范引用：**参考项目根目录 AGENTS.md 中的 Changelog 规范（核心原则、格式规范、Emoji 规范、句式规范）。

根据规范，对 ~changelog.md 中的条目进行过滤、分组、格式检查，并在必要时进行交互式确认和修改。

过滤规则

• 跳过 chore:、test:、ci:、build: 类型的 commit
• 跳过纯文档/站点改动（不影响组件 API 和行为的）
• 跳过纯测试更新和工具链升级
• 依赖升级默认跳过；但 rc-component、@ant-design/icons 或其他运行时依赖升级如果带来组件能力、运行时行为、可访问性、TypeScript 外露类型或包体积收益，必须保留并写清用户/开发者影响

发布重点提炼

正式发布版本 changelog 不只是 PR 列表，必须先提炼跨版本亮点并放在普通组件条目前面。优先寻找并置顶这些类型：

• 影响产品定位或使用方式的跨版本能力，例如 DESIGN.md、AI 设计工具支持、agent discovery、LLMs/MCP/CLI 能力
• 用户能直接感知的重要视觉资产或内置能力，例如新增 Icon 集合，并列出具体新增图标
• 明确的包体积、性能或运行时收益
• 多个 PR 共同构成的一项能力，合并成一条重点说明，并列出相关 PR

重点条目可以使用 🔥，但每条仍只能选择一个 Emoji。

体积分析流程

当发布版本出现明显 size-limit 变化，或依赖升级可能影响体积时，必须先分析再写 changelog：

1. 拉取当前 release PR 和上一个 release PR 的 size-limit 评论，记录最终 antd.min.js、antd-with-locales.min.js 等关键包体积数值。
2. 计算相对上个版本的最终差值，不只记录单个 PR 的增减。
3. 扫描本版本区间内各 PR 的 size-limit 评论，定位主要增减来源。
4. 检查 package.json 运行时依赖升级，尤其是 rc-component、@ant-design/icons、picker/select/upload/icon 相关包。
5. 必要时对比 npm 包或构建产物，避免把全部收益错误归因给某个单独 PR（例如只写 Icon，而忽略 picker 精简运行时代码）。
6. Changelog 里写最终用户/开发者能理解的收益和主要来源，例如"完整包体积下降，主要来自 DatePicker/TimePicker runtime 精简与 Icon/Upload 默认图标优化"。

分组逻辑

• 分组必须以最终有效 changelog 条目数量为准：同一组件最终有 2 条及以上时，才使用 - 组件名 分组；最终只有 1 条时，必须输出为顶层单行条目，即使组件名已出现在条目正文中，也不单独写 - 组件名 分组行。
• 完成过滤、合并、移动条目后，必须重新统计每个分组；移动到 Icon、跨组件、TypeScript、文档/网站等分类后的原组件也要重新统计，拆平所有只剩 1 条的组件分组。
• 组件分组排序按有效条目数降序排列；条目数相同再按重要性和现有 changelog 风格排序。
• 发布版本整体排序按影响优先：跨版本重点变化最前，其次是条目较多或影响较大的组件分组，再是普通单行条目。

示例（多条）：

- Select
  - 🐞 Fix Select incorrect height when value is empty. [#56976](https://github.com/ant-design/ant-design/pull/56976) [@zombieJ](https://github.com/zombieJ)
  - 💄 Improve Select dropdown animation. [#56980](https://github.com/ant-design/ant-design/pull/56980) [@afc163](https://github.com/afc163)
- 🐞 Fix Button style in Safari. [#56901](https://github.com/ant-design/ant-design/pull/56901) [@li](https://github.com/li)

描述与署名补充规则

• Emoji 在行首，动词紧跟其后
• 组件名不加反引号；属性名、API 名用反引号
• 描述"对开发者的影响"，而非"具体实现细节"
• 每条 changelog 统一补充 PR 链接 和 PR 作者链接，顺序为先 PR 后作者（如 [#56976](https://github.com/ant-design/ant-design/pull/56976) [@username](https://github.com/username)），不区分是否团队成员

阶段三：写入文件并校验

在 --- front matter 之后、第一个版本标题之前插入新内容：

1. 读取 CHANGELOG.zh-CN.md
2. 找到 --- 之后的位置
3. 插入生成的中文 changelog
4. 写入文件

同样流程处理 CHANGELOG.en-US.md

写入后必须运行 lint 校验：

npm run lint:changelog

如果 lint 报错，根据错误信息修正对应的 changelog 条目，重新写入，直到 lint 通过。常见错误类型：

• Emoji 格式不符
• 中英文空格缺失
• 组件名使用了反引号
• 版本格式或日期格式不对

版本确认（可选）

版本号已在阶段一确定。如需更新 package.json，在写入 changelog 前询问：

是否需要同步更新 package.json 中的版本号？

当前版本: 6.3.1 → changelog 版本: 6.4.0
选项:
- [更新] 执行 npm version minor/patch
- [跳过] 保持 package.json 不变

写入确认（交互式）

预览确认：

请确认以下内容即将写入 CHANGELOG.zh-CN.md 和 CHANGELOG.en-US.md：

版本: 6.4.0
日期: 2026-03-09
条目数: 12

[预览完整内容] [直接写入] [取消]

完整交互流程

1. 获取可用 tags，选择起始版本
   ↓
2. 选择目标分支（master/feature/自定义）
   ↓
3. **立即确定版本号**（minor/patch/自定义）
   ↓
4. 初始化 ~changelog.md 头部（写入版本信息）
   ↓
5. git log 获取两个版本间的 commits，提取所有 PR 编号
   ↓
6. **并行 dispatch subagents** 批量获取 PR 详情（每批最多 10 个）
   ↓
7. 汇总所有 PR 结果，逐条处理：
   ├── 有 changelog → 提取 → **校验合规性** → 不合规则改写
   └── 无 changelog → 根据 PR title/body/diff **自动生成**符合规范的描述
   ↓
8. 核查运行时依赖升级（尤其 rc-component / icons）是否带来能力、类型或体积收益
   ↓
9. 识别组件 category
   ↓
10. 追加写入 ~changelog.md
    ↓
11. 过滤无效 commit（交互确认）
    ↓
12. 提炼发布重点（DESIGN.md、Icon、包体积、AI agent 支持等跨版本亮点）
    ↓
13. 如存在明显体积变化，按体积分析流程归因并补充说明
    ↓
14. 分组处理并排序（按最终有效条目数重算，单条组件拆平）
    ↓
15. 检查描述规范性（交互确认）
    ↓
16. 重新生成不符合规范的描述（如需要）
    ↓
17. 预览确认（交互确认）
    ↓
18. 可选：更新 package.json 版本（npm version）
    ↓
19. 写入 CHANGELOG.zh-CN.md 和 CHANGELOG.en-US.md
    ↓
20. **运行 `npm run lint:changelog` 校验，有报错则修正并重新写入**
    ↓
21. 清理临时文件 ~changelog.md
    ↓
22. （可选）创建发布 PR，PR body 中直接包含完整的中英文 changelog 内容

所需命令

此 skill 需要以下命令可用：

• git tag --list - 获取版本标签
• git log <from>..<to> --oneline - 获取版本间 commits
• gh pr view <pr-number> --json title,body,author,number - 获取 PR 详情
• git show <hash> - 查看 commit 详情（用于无 changelog 时辅助生成描述）
• npm version minor - 升级次版本号（6.3.1 → 6.4.0）
• npm version patch - 升级修订版本号（6.3.1 → 6.3.2）
• cat >> ~changelog.md 或 Node.js fs.appendFileSync - 追加写入
• npm run lint:changelog - 校验 changelog 格式（写入后必须运行）

注意事项

• 需要 gh CLI 认证（运行 gh auth login）
• 写入前必须预览确认
• 保持中英文同步更新
• 描述以动作开头，并保证正文包含组件名（如 修复 Select ...、Fix Select ...）
• 统一添加 PR 作者链接（不区分是否团队成员）
• PR body 有 changelog 时，以 PR body 为准，但必须校验并按 antd 规范改写不合规内容
• PR body 无 changelog 时，根据 PR title/body/diff 自动生成，不能只用 PR title 原文照抄