| name | changelog-release-notes |
| description | BK-CI 发版 Changelog 增量处理：仅针对本次新增版本块生成「变更概述」并写回中文文件， 再将该增量版本翻译到英文 CHANGELOG。当用户提到发版摘要、变更概述、CHANGELOG 翻译、 中英文 changelog、vX.Y.Z-rc、补充概述、同步英文日志时使用。 |
Changelog 发版说明工作流（增量）
适用场景
用户已完成中文 Changelog 某一版本的明细生成（如 # v4.2.0-rc.4），需要 Agent：
- 基于该增量块生成「变更概述」，并写回中文文件
- 将该增量版本整段翻译到英文 Changelog 文件
不要替用户从零生成完整 issue 明细；默认假设中文明细已存在。
核心原则：只处理增量
Changelog 是增量维护的：每次只处理当前新增的那一个版本块。
| 要做 | 不要做 |
|---|
只读目标版本块（如 # v4.2.0-rc.4 到下一个 # v... 之前） | 遍历 / 总结整个 CHANGELOG 文件 |
| 只在该版本块内插入「变更概述」 | 修改更旧版本的概述或明细 |
| 只把该版本块翻译并插入英文文件顶部 | 重译或覆盖英文文件里已有历史版本 |
文件约定
| 语言 | 路径模式 | 示例 |
|---|
| 中文 | CHANGELOG/zh_CN/CHANGELOG-<major.minor>.md | CHANGELOG/zh_CN/CHANGELOG-4.2.md |
| 英文 | CHANGELOG/en/CHANGELOG-<major.minor>.md | CHANGELOG/en/CHANGELOG-4.2.md |
新版本块通常位于文件顶部 <!-- NEW RELEASE NOTES ENTRY --> 之后，插在旧版本之前。
增量范围定义
「本次增量」= 中文文件中目标版本标题到下一版本标题之间的内容：
# v4.2.0-rc.4 ← 增量起点（含）
## 2026-07-16
### Changelog since v4.2.0-rc.3
...明细...
# v4.2.0-rc.3 ← 增量终点（不含）
输入确认
- 目标版本（必填）：如
v4.2.0-rc.4
- 基线版本（可选）：默认从该块的
Changelog since ... 读取
- 中文 / 英文文件路径：可按 major.minor 推断
标准流程（严格按序，仅针对增量块）
确认目标版本
↓
【1】定位并只读取该版本增量块
↓
【2】基于该块生成「变更概述」（特性 / Bug）
↓
【3】将概述写回中文文件的该版本块内
↓
【4】仅翻译该增量块为英文
↓
【5】将英文增量块插入英文文件顶部（NEW RELEASE NOTES ENTRY 之后）
↓
完成后简要汇报：概述条数、中英文写入位置
支持按需裁剪：
- 「只生成概述」→ 步骤 1～3
- 「概述已有，只翻译英文」→ 步骤 1、4、5（中文概述一并译出）
步骤2：生成变更概述
输出模板（中文）
### 变更概述
当前版本主要变更特性如下:
**特性**
- ...
**Bug 修复**
- ...
体量
- 特性：5～8 条
- Bug：2～4 条
- 宁可少，不要堆；下方已有明细，概述只展示核心
文风
对齐 CHANGELOG/zh_CN/CHANGELOG-4.1.md 的「变更概述」：
- 短句，以「支持 / 增加 / 修复」等开头
- 不写 issue 链接、不写
feat/bug/pref 前缀、不加模块小标题
- 面向终端用户；内部优化默认不进概述
特性筛选
| 优先级 | 判断标准 | 处理 |
|---|
| P0 | git tag 对比中相近 commit message 提交多；或同主题 Changelog 条目明显集中 | 合并成 1 条主推 |
| P1 | 用户可感知的新能力（触发、复制、变量、商店、环境等） | 单独成条 |
| P2 | API/OpenAPI、渠道过滤、字段补齐、OP 小改 | 默认不进 |
| P3 | 性能、缓存、监控、依赖升级 | 不进 |
同一主题多条必须合并为 1～2 条（用「支持 A、B、C」收束）。
可选辅助命令（只读，用于识别 P0 主题）：
git log --oneline <基线tag>..<目标tag>
按相近 commit message 聚类，提交多的主题优先进入概述。
Bug 筛选
只保留高影响项，例如：
- 构建无法继续 / 取消 / 重试
- 数据误删、锁未释放、状态错误
- 核心编辑或触发流程明显异常
UI 小问题、边缘场景修复留给明细，不进概述。
插入位置（仅改增量块）
# vX.Y.Z-rc.N
## YYYY-MM-DD
### Changelog since vX.Y.Z-rc.(N-1)
### 变更概述 ← 仅插这里
当前版本主要变更特性如下:
...
#### 新增 ← 用户已有明细，禁止改动
不要改动用户已写好的新增 / 优化 / 修复明细。
步骤3：写回中文文件
- 仅在目标版本块内补充「变更概述」
- 不重排、不删改已有明细条目
- 不修改更旧版本内容
- 保持原文件 TOC / MUNGE 注释结构；若项目有 TOC 生成脚本则不要手改 TOC，除非用户要求
步骤4：翻译为英文（仅增量块）
翻译对象 = 本次中文增量块全文（含刚插入的概述 + 原有明细）。
章节标题映射
| 中文 | 英文 |
|---|
| 新增 | New Features |
| 优化 | Improvements |
| 修复 | Bug Fixes |
| 流水线 | Pipeline |
| 代码库 | Repository |
| 研发商店 | Store |
| 环境管理 | Environment Management |
| 日志服务 | Log Service |
| 质量红线 | Quality Gate |
| 权限中心 | Permission Center |
| 项目管理 | Project Management |
| 调度 | Dispatch |
| 凭证管理 | Credential Management |
| Agent | Agent |
| 其他 | Others |
| 变更概述 | Summary |
| 特性 | Features |
| Bug 修复 | Bug Fixes |
条目标签映射
| 中文 | 英文 |
|---|
[新增] | [New] |
[优化] | [Improved] |
[修复] | [Fixed] |
[链接] | [Link] |
英文概述模板
### Summary
Key changes in this release:
**Features**
- ...
**Bug Fixes**
- ...
翻译要求
- 保留 issue 链接、版本号、日期结构不变
- 产品专有名词可保留：PAC、TAPD、CodeCC、BK-CI 等
- 「创作流」译为
Creation Flow
- 语序自然，避免逐字硬翻；与
CHANGELOG/en/CHANGELOG-*.md 既有文风一致
- 英文概述条目与中文概述一一对应，条数一致
步骤5：写入英文文件（增量插入）
- 将完整新版本块插入英文文件顶部（
<!-- NEW RELEASE NOTES ENTRY --> 之后、上一版本之前）
- 若英文文件尚无该版本，则新增整块
- 若已存在该版本：先询问用户，默认不覆盖
- 不要改写更旧版本的英文内容
触发话术示例
- 「按 changelog-release-notes，处理 v4.2.0-rc.4 增量」
- 「中文 rc.4 已写好，补概述并同步英文」
- 「只生成概述，先别写英文」
- 「概述已有，只翻译英文」
完成检查清单
注意
- 默认不创建 git commit；除非用户明确要求提交
- 不要主动修改历史版本的概述或翻译
- 对拿不准是否进入概述的条目，默认不进；可在回复末尾用一句话列出「可选补充项」供用户决定
