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

适用场景

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

1. 基于该增量块生成「变更概述」，并写回中文文件
2. 将该增量版本整段翻译到英文 Changelog 文件

不要替用户从零生成完整 issue 明细；默认假设中文明细已存在。

核心原则：只处理增量

Changelog 是增量维护的：每次只处理当前新增的那一个版本块。

文件约定

新版本块通常位于文件顶部 <!-- 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 前缀、不加模块小标题
• 面向终端用户；内部优化默认不进概述

特性筛选

同一主题多条必须合并为 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：翻译为英文（仅增量块）

翻译对象 = 本次中文增量块全文（含刚插入的概述 + 原有明细）。

章节标题映射

条目标签映射

英文概述模板

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