changelog-release-notes

name	changelog-release-notes
description	BK-CI 发版 Changelog 增量处理：仅针对本次新增版本块生成「变更概述」并写回中文文件， 再将该增量版本翻译到英文 CHANGELOG。当用户提到发版摘要、变更概述、CHANGELOG 翻译、 中英文 changelog、vX.Y.Z-rc、补充概述、同步英文日志时使用。

Changelog 发版说明工作流（增量）

适用场景

用户已完成中文 Changelog 某一版本的明细生成（如 # v4.2.0-rc.4），需要 Agent：

1. 基于该增量块生成「变更概述」，并写回中文文件
2. 将该增量版本整段翻译到英文 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 已写好，补概述并同步英文」
• 「只生成概述，先别写英文」
• 「概述已有，只翻译英文」

完成检查清单

• 只读写了目标版本增量块，未改历史版本
• 中文仅新增了「变更概述」，明细未动
• 特性 5～8 条、Bug 2～4 条，无 issue 链接
• 英文仅新增了对应一版，历史英文未改
• 章节 / 标签已按映射表转换
• 链接与版本号未丢失
• 中英文概述条数一致

注意

• 默认不创建 git commit；除非用户明确要求提交
• 不要主动修改历史版本的概述或翻译
• 对拿不准是否进入概述的条目，默认不进；可在回复末尾用一句话列出「可选补充项」供用户决定