Gemini CLI 发布工作流详解：docs-changelog Skill 如何标准化 Changelog 生成

Gemini CLI 仓库内置了一个名为 docs-changelog 的 Agent Skill（位于 .gemini/skills/docs-changelog/SKILL.md），它把"从一次自动化 Release 的原始数据（版本号、时间戳、原始 Markdown 发布说明）生成并维护三个 Changelog 文件（latest.md、preview.md、index.md）"这一流程，固化为一套可被 LLM Agent 严格执行的标准操作程序。读完本文，你将理解该 Skill 的版本分流决策逻辑（Minor / Patch × Stable / Preview 四条路径）、Highlights 与 Announcement 的写作规范、四个参考模板的填充方式，以及它与仓库中 docs/changelogs/ 目录下真实产出文件之间的对应关系。

Skill 的目标与输入契约

该 Skill 的核心目标（Objective）是：基于自动化的发布信息，标准化地更新 Changelog 文件。它定义了一份明确的三要素输入契约：

• version：发布版本字符串，例如 v0.28.0（stable minor）、v0.29.0-preview.2（preview patch）；
• TIME：发布时间戳，例如 2026-02-12T20:33:15Z；
• BODY：原始 Markdown 格式的发布说明，包含 "What's Changed" 小节和 "Full Changelog" 链接。

这三个输入正是上游自动化流程（由 @gemini-cli-robot 自动提 PR 的发布流水线）向 Agent 传递的数据形态——从 docs/changelogs/latest.md 的 "What's Changed" 列表中可以看到大量形如 Changelog for v0.51.0-preview.0 by @gemini-cli-robot in #28150 的条目，印证了该 Skill 处于"机器人生成原始数据 → Agent 按规范整理成文档"这条链路上。

版本分析：nightly 拦截与四条处理路径

初始处理（Initial Processing）的第一步是根据版本字符串确定处理路径，这是整个 Skill 最关键的决策点：

1. 版本含 "nightly"：立即停止，不做任何文件变更。这与 docs/changelogs/index.md 中描述的三个发布通道（nightly / preview / stable）相对应——nightly 通道不落到这三个文件中。
2. 版本以 .0 结尾：走 Path A（新 Minor 版本）。
3. 版本不以 .0 结尾：走 Path B（Patch 版本）。

Path A/B 内部还要根据版本是 stable 还是 preview 进一步二选一，形成四个互斥分支：

路径	版本形态示例	目标文件	操作性质
A.1	v0.28.0（stable minor）	index.md + latest.md	新增 Announcement；整体替换 latest.md
A.2	v0.29.0-preview.0（preview minor）	preview.md	整体替换 preview.md
B.1	v0.28.1（stable patch）	latest.md	增量编辑（改头、日期、前插列表、改链接尾）
B.2	v0.29.0-preview.3（preview patch）	preview.md	增量编辑（同上）

Skill 原文特别强调：基于版本必须二选一执行 A.1 或 A.2（B.1 或 B.2），不能混用另一节的指令。这种"互斥分支 + 显式 STOP"的写法，是为了约束 LLM 在自动化执行时不产生跨分支的文件污染。

BODY 预处理：PR 链接格式化与段落裁剪

在处理时间戳与正文时，Skill 规定：

• 将 TIME 转换为两种格式备用：yyyy-mm-dd（用于 index.md 的 Announcement 标题）与 Month dd, yyyy（用于 latest.md / preview.md 的 Released: 行）。对照真实文件可以验证这一约定：docs/changelogs/index.md 的最新条目标题为 ## Announcements: v0.54.0 - 2026-08-06，而 docs/changelogs/latest.md 头部为 Released: August 11, 2026。
• 将 BODY 存入临时文件，然后对其 "What's Changed" 小节做两类清洗：
  • 把所有裸的 pull request URL 重排为"以 PR 编号为文本的 Markdown 链接"，例如 #12345——这正是 docs/changelogs/latest.md 中 #28116 这类条目的来源格式；
  • 若存在 "New Contributors" 小节则整体删除。
• 保留 **Full Changelog** 链接不动，处理后的临时文件内容供后续步骤填充模板。

Highlights 写作规范（latest.md / preview.md 共用）

A.1、A.2 两条路径都需要生成 "Highlights" 小节，Skill 给出了一套统一的内容规范：

• 目标是 3–5 条关键亮点；
• 每条亮点必须以加粗标题开头，概括变更主题，例如 **New Feature:** A brief description...；
• 优先总结新功能，其次才是 bug 修复、chore 等变更；
• 避免在 Stable Release 的 Highlights 中提及 "experimental" 或 "in preview" 的实验性功能；
• Highlights 中不得出现 PR 编号、链接或作者名。

这套规范的风格基准保存在 highlight 示例文件 中，其中收录了 4 组真实发布的高亮文案，例如 "Plan Mode Enhancements: Significant updates to Plan Mode, including new commands, support for MCP servers..." 与 "New /rewind Command: A new /rewind command has been implemented to allow users to go back in their session history." 这些示例与当前 docs/changelogs/latest.md 中 "Highlights" 小节的实际条目（如 "PR Generation & Antigravity Agent: ..."、"Model Fallback & History Filtering: ..."）在语气、句长和"主题词冒号 + 一句功能概述"的结构上完全一致。

Path A.1：Stable Minor Release 的双份摘要

A.1 要求从同一份 changelog 中生成两种不同密度的摘要，分别服务两类读者入口：

1. 为 index.md 创建 Announcement（简洁版）

• 生成简明公告，概括最重要的变更，每条同样以加粗标题开头；
• 其格式是独特的：必须以 docs/changelogs/index.md 中既有的 Announcement 条目和 index 模板 中的示例条目为参照——与 Highlights 不同，Announcement 允许且应当附带 PR 链接和作者名，但数量控制在 1–2 个 PR 链接/作者以内；
• 新公告插入到 docs/changelogs/index.md 顶部。

index 模板 的结构为：

## Announcements: {{version}} - {{release_date_yyyy_mm_dd}}

{{announcement_content}}

<!-- 示例条目（一条 highlight 可对应多条）：
  - **Highlighted Feature:** We've added a new highlighted feature ...
  (#nnnnn by @author).
-->

2. 生成 Highlights 并整体替换 latest.md

• 按 Highlights 规范生成完整的 "Highlights" 小节；
• 取 latest 模板 的内容，填充 version、release_date、生成的 highlights 以及预处理后的临时文件内容；
• 完整替换 docs/changelogs/latest.md 的全部内容。

latest 模板 的完整骨架是：

# Latest stable release: {{version}}

Released: {{release_date_month_dd_yyyy}}

For most users, our latest stable release is the recommended release.
Install the latest stable version with:

npm install -g @google/gemini-cli

## Highlights

{{highlights_content}}

## What's Changed

{{changelog_list}}

**Full Changelog**: {{full_changelog_link}}

Path A.2 与 Path B：Preview 与 Patch 的增量维护

A.2（Preview Minor，如 v0.29.0-preview.0）：生成 Highlights 后，用 preview 模板 填充同样四个占位符，然后完整替换 docs/changelogs/preview.md。该模板与 latest 模板的差异体现在头部声明与安装命令：

# Preview release: {{version}}

Our preview release includes the latest, new, and experimental features.
This release may not be as stable as our latest weekly release.

To install the preview release:
npm install -g @google/gemini-cli@preview

这与当前 docs/changelogs/preview.md 的实际头部（# Preview release: v0.58.0-preview.0，含 npm install -g @google/gemini-cli@preview 安装说明）逐行吻合。

B.1（Stable Patch，如 v0.28.1）：目标文件为 docs/changelogs/latest.md，执行五步增量编辑而非整体替换：

1. 更新主标题行为 # Latest stable release: {{version}}；
2. 更新发布日期行为 Released: {{release_date_month_dd_yyyy}}；
3. 判断临时文件中是否存在 "What's Changed" 小节，有则进入第 4 步，无则跳到第 5 步；
4. 将处理后的 "What's Changed" 列表前插（prepend）到 latest.md 现有列表的开头——注意是"只加不改"，绝不修改或替换既有条目。这一设计让 stable 通道内所有 patch 版本的变更在同一页面里累积，形成当前 latest.md 中长达数百行、跨多个小版本的 "What's Changed" 清单；
5. 在 "Full Changelog" 处只修改 URL 的结尾部分：找到形如 ...{previous_version} 的末段，替换为 ...{version}。Skill 给出的示例是：patch 版本为 v0.29.1 时，把 compare 链接从 .../compare/v0.28.2…v0.29.0 改为 .../compare/v0.28.2…v0.29.1——起点版本保持不变，仅终点滚动到新版本。当前仓库中 latest.md 的结尾即为这种形态：**Full Changelog** 指向 compare 链接 v0.53.1...v0.55.1。

B.2（Preview Patch，如 v0.29.0-preview.3）：目标文件换成 docs/changelogs/preview.md，五个步骤与 B.1 完全平行：主标题行为 # Preview release: {{version}}，日期行、What's Changed 前插、Full Changelog 尾部滚动规则一致（示例：.../compare/v0.28.2…v0.29.0-preview.0 改为 .../compare/v0.28.2…v0.29.0-preview.1）。

从源码结构看，"前插 + 尾部滚动"而非"整体替换"的 B 路径设计，使 patch 发布只需对文件做最小 diff，降低了自动化 PR 的冲突概率，也让 stable 页面天然保留了该 minor 周期内的完整变更历史。

Finalize：格式收敛与清理

所有路径执行完毕后，Skill 定义了收尾动作：

• 运行 npm run format 保证格式一致；若失败，可能需先执行 npm install 以安装全部格式依赖后再跑。对照仓库根目录 package.json 中的脚本定义，format 即 prettier --experimental-cli --write .，也就是说三个 changelog 文件最终会被 Prettier 统一排版——这也解释了为何现有文件中 **Full Changelog**: 这类行会按 80 列自动折行；
• 删除过程中创建的所有临时文件。

参考文件清单与整体流程

该 Skill 的完整资产由主文档加四份参考文件构成，均可在仓库中直接查看：

文件	作用
SKILL.md	主流程：输入契约、版本分流、四路径操作、Finalize
highlights_examples.md	Highlights 的风格/语气基准（4 组真实示例）
index_template.md	index.md Announcement 的标题格式与条目示例
latest_template.md	stable 主页面模板（替换型填充）
preview_template.md	preview 主页面模板（替换型填充）

整体数据流可以概括为：发布流水线产出 (version, TIME, BODY) 三元组 → Agent 按 SKILL.md 完成 nightly 拦截、时间格式化、PR 链接重排与 New Contributors 裁剪 → 依据版本形态进入 A.1 / A.2 / B.1 / B.2 之一 → 生成 3–5 条符合规范的 Highlights（stable minor 额外生成带 PR 链接的 Announcement）→ 填充模板或增量编辑目标文件 → npm run format 收敛格式并清理临时文件。

这套"文档即程序"（skill-as-procedure）的做法展示了 Agent Skill 在开源项目运营自动化中的一个典型应用：将易变、需要人工裁量的高光总结，与严格、可重复的文件编辑规则（版本行、日期行、前插列表、链接尾滚动）拆分开来——前者靠参考示例约束风格，后者靠编号步骤约束行为，两者结合使机器生成的 Changelog 在多个版本迭代后仍能保持 docs/changelogs/ 目录下当前所呈现的一致结构。