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