---
name: cl
description: 审计自上次发版以来的提交，把遗漏的「用户可见变更」补进 CHANGELOG.md 的 [Unreleased]；可选地把 [Unreleased] 收口成正式版本节
---

帮我审计并维护 [CHANGELOG.md](../../../CHANGELOG.md)，确保自上次发版以来的所有「用户可见变更」都被记录。规则以 [AGENTS.md](../../../AGENTS.md) 的 **Changelog** 章节为准。

参数约定：

- **留空** → 只做「审计 + 补漏」：把遗漏的条目补进顶部的 `## [Unreleased]`，**不**收口、**不**改版本号。
- **传版本号**（如 `1.3.3`）→ 在补漏之后再做「发版收口」：把 `## [Unreleased]` 落成 `## <版本> - <今天日期>`，并在顶部补一个新的空 `## [Unreleased]`。

## 工作流

### 1. 划定审计区间
- 读取 [CHANGELOG.md](../../../CHANGELOG.md)，找到最近一个已发布版本节（如 `## 1.3.2 - 2026-06-14`）和它的日期。
- 在终端用 `git log` 取出自该版本以来的提交（项目历史是线性的、**无 git tag**，按日期或上一条 release commit 划界即可）。例：
  `git log --no-pager --pretty=format:'%h %ad %s' --date=short --since=<上次发版日期>`
- 同时读完整个现有 `## [Unreleased]`，记下已经记过的条目，避免重复。

### 2. 逐条判定「记 / 不记」
对区间内每个提交，按 Changelog 章节的「记什么」判断：

- **记**：新功能、行为变化、Bug 修复、面向用户的破坏性变更。
- **不记**：纯重构、测试、构建、CI、文档、内部依赖升级（除非影响用户的可感知行为）。
- 拿不准时，问自己「终端用户能不能感知到这条变更」——能则记，不能则跳过。
- 一个提交可能对应一条或多条用户可见变更；反之多个琐碎提交可合并成一条。

### 3. 写入 [Unreleased]
- 归入正确小节：`### 新增 / Added`、`### 变更 / Changed`、`### 修复 / Fixed`、`### 移除 / Removed`、`### 破坏性变更 / Breaking Changes`（按需创建，不重复建小节）。
- **双语排版**：每个小节正文先列**全部中文条目**，空一行，再列**全部对应英文条目**（顺序一一对应）。不要逐行中英并排，不用 `/` 在条目内分隔中英。
- 来自 issue 的变更在中、英两条末尾都附 `(#编号)`。
- 措辞从用户视角写，描述「带来什么变化」，不要照抄 commit message 的实现术语。
- **只动 `## [Unreleased]`**，绝不修改任何已发布版本节。

### 4.（仅当传了版本号）发版收口
- 把 `## [Unreleased]` 标题改成 `## <版本号> - <今天的日期 YYYY-MM-DD>`。
- 在文件顶部、紧跟头部约定说明之后，补一个新的空 `## [Unreleased]`。
- **不要**在这里改 [package.json](../../../package.json) 的版本号——版本号 bump 由发版提交单独处理，本指令只管 Changelog。

## 输出

- 先报告：审计了哪个区间（从哪个版本到 HEAD）、扫了多少提交。
- 列出本次**新增/合并**了哪些条目、**有意跳过**了哪些提交（一句话说明为什么跳过，便于我复核取舍）。
- 如果做了发版收口，说明落成了哪个版本节、日期是多少。
- 遇到拿不准要不要记、或某条变更措辞没把握的，直接告诉我，不要擅自下判断。