# Changelog Release Notes

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

- Skill: `tencentblueking/changelog-release-notes` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tencentblueking/changelog-release-notes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tencentblueking/changelog-release-notes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tencentblueking (https://skillmd.com/u/tencentblueking)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tencentblueking/changelog-release-notes

---


# 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 -->` 之后，插在旧版本之前。

## 增量范围定义

「本次增量」= 中文文件中目标版本标题到下一版本标题之间的内容：

```markdown
# 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：生成变更概述

### 输出模板（中文）

```markdown
### 变更概述
当前版本主要变更特性如下:

**特性**
- ...

**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 主题）：

```bash
git log --oneline <基线tag>..<目标tag>
```

按相近 commit message 聚类，提交多的主题优先进入概述。

### Bug 筛选

只保留高影响项，例如：

- 构建无法继续 / 取消 / 重试
- 数据误删、锁未释放、状态错误
- 核心编辑或触发流程明显异常

UI 小问题、边缘场景修复留给明细，不进概述。

### 插入位置（仅改增量块）

```markdown
# 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]` |

### 英文概述模板

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