Gemini CLI Preview 发布变更日志模板：preview_template.md 的结构、占位符与生成机制

本文围绕 Gemini CLI 仓库中的 preview_template.md 展开，解析这个预览版（preview channel）变更日志模板的完整结构、每个占位符的语义与填充规则，并结合 docs-changelog 技能定义、已生成的真实变更日志 与发布流程文档，说明该模板如何从原始发布数据被自动填充为最终的 docs/changelogs/preview.md 页面。读完后，你可以完整掌握预览版变更日志的版式规范、高亮点（Highlights）写作约束，以及 minor 版本与 patch 版本两条不同的落盘路径。

模板定位：它属于 docs-changelog 技能的一环

Gemini CLI 用一套 Agent Skill 来标准化“新版本发布后如何更新变更日志”这一流程，该技能定义在 SKILL.md 中，目标是统一更新三个文件：latest.md（稳定版）、preview.md（预览版）和 index.md（发布公告页）。preview_template.md 是其中负责预览版新 minor 版本页面的“骨架模板”，它的同级参考资料包括：

• latest_template.md：稳定版的对应模板，结构几乎一致，仅头部文案（“Latest stable release”）与安装命令（不带 @preview 标签）不同；
• index_template.md：用于 index.md 顶部发布公告（Announcements）条目的模板；
• highlights_examples.md：Highlights 栏目的四组风格范例。

模板的完整结构与逐行解读

模板全文如下（来自 preview_template.md），共 22 行：

# Preview release: {{version}}

Released: {{release_date_month_dd_yyyy}}

Our preview release includes the latest, new, and experimental features. This
release may not be as stable as our [latest weekly release](https://gitcode.com/GitHub_Trending/gemi/gemini-cli/blob/3c311beac2e78336816dd4a123db39743f9fbf85/docs/changelogs/latest.md?utm_source=gitcode_repo_files).

To install the preview release:

npm install -g @google/gemini-cli@preview

## Highlights

{{highlights_content}}

## What's Changed

{{changelog_list}}

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

模板分为四个部分：

1. 标题与发布日期。一级标题固定为 # Preview release: {{version}}，发布日期固定为 Released: {{release_date_month_dd_yyyy}}，即“Month dd, yyyy”英文格式。对照真实产物 preview.md 可以看到填充后的样子：# Preview release: v0.58.0-preview.0 与 Released: August 25, 2026。
2. 稳定性声明与内部链接。模板中声明预览版“包含最新、新特性与实验性功能，可能不如最新周版本稳定”，并通过相对链接指向 latest.md。由于该相对链接在仓库最终文档中的实际位置是 docs/changelogs/，对应的仓库根路径为 docs/changelogs/latest.md。
3. 安装命令。固定为 npm install -g @google/gemini-cli@preview。这与 releases.md 中定义的 npm dist-tag 机制一一对应：@preview 标签指向当前预览通道版本，与稳定版（@latest）、每日构建（@nightly）并列。包名 @google/gemini-cli 与 package.json 中的 name 字段一致，该包要求 Node.js >=20.0.0（见 engines 字段）。
4. 两个内容区块加一个尾链。## Highlights 与 ## What's Changed 分别承接人工提炼的高亮与机器生成的变更列表；末尾的 **Full Changelog**: {{full_changelog_link}} 指向跨版本 compare 链接。

五个占位符的语义与数据来源

占位符	语义	数据来源与格式约束
{{version}}	发布版本号	技能输入 version，如 v0.29.0-preview.0、v0.29.0-preview.3
{{release_date_month_dd_yyyy}}	发布日期	技能输入 TIME（如 2026-02-12T20:33:15Z）转换后的 Month dd, yyyy 格式
{{highlights_content}}	3–5 条高亮要点	由 Agent 依据 SKILL.md 的高亮指南从变更列表中提炼生成
{{changelog_list}}	完整变更列表	输入 BODY（原始 markdown 发布说明）经预处理后的 “What's Changed” 内容
{{full_changelog_link}}	全量变更链接	BODY 中保留的 “Full Changelog” 链接，指向两个版本之间的 compare URL

技能定义（SKILL.md）规定了三项输入：version、TIME、BODY（原始 markdown 发布说明，包含 “What's Changed” 与 “Full Changelog” 链接）。其中 TIME 会被转换为两种格式备用：yyyy-mm-dd（供 index.md 公告条目使用）与 Month dd, yyyy（供本模板使用）。BODY 会先落入临时文件做三项预处理：

1. 将 “What's Changed” 中所有 PR 裸 URL 重写为“PR 编号作为文本”的 markdown 链接，例如 #12345；
2. 删除 “New Contributors” 小节（预览/稳定版页面均不保留该节）；
3. 原样保留 “Full Changelog” 链接，供尾链占位符使用。

模板的两条使用路径：minor 版本整页替换，patch 版本增量编辑

技能根据版本号将流程分为两条主路径，而 preview_template.md 只在预览版 minor 新版本的场景中作为整页骨架：

路径 A.2 —— 预览版新 minor 版本（版本以 .0 结尾，如 v0.29.0-preview.0）：

1. 按高亮指南生成 Highlights；
2. 取 preview_template.md 的内容，填入 version、release_date、生成的 highlights 与预处理后的临时文件内容；
3. 完整替换（Completely replace）docs/changelogs/preview.md 的全部内容。

路径 B.2 —— 预览版 patch 版本（版本不以 .0 结尾，如 v0.29.0-preview.3）：此时不再使用模板，而是对现存的 preview.md 做四处增量编辑：

1. 头部版本行改为 # Preview release: {{version}}；
2. 日期行改为 Released: {{release_date_month_dd_yyyy}}；
3. 若临时文件中存在 “What's Changed” 小节，将其 前置追加（Prepend）到现有列表头部——只增不改，不替换原有列表；
4. 仅修改 “Full Changelog” URL 的尾部版本段。SKILL.md 给出的示例是：假设 patch 版本为 v0.29.0-preview.1，将 compare URL 结尾的 ...v0.29.0-preview.0 更新为 ...v0.29.0-preview.1。

这一设计的实际效果可以在 preview.md 中验证：其 “What's Changed” 列表的首条是 “Changelog for v0.57.0-preview.0 by @gemini-cli-robot” 这类版本切换记录，随后依次累积各次 patch 的变更条目；而 “Full Changelog” 尾链始终保持 v0.57.0-preview.1...v0.58.0-preview.0 这种“minor 起点…当前版本”的区间形态，与 B.2 第 4 步的规则一致。

Highlights 写作规范：模板质量的关键约束

{{highlights_content}} 不是原文搬运，而是有严格风格约束的提炼产物。SKILL.md 中的指南要求：

• 控制在 3–5 条要点；
• 每条以加粗标题开头概括变更方向，例如 **Sandbox Security Enhancements**: Isolated Docker and container runtime sockets...；
• 新特性优先：相比 bug 修复、chore 类变更，优先总结新增功能；
• 稳定版（latest.md）中避免提及“experimental”或“in preview”的功能——预览版页面则相反，实验性内容正是其定位；
• 不得在高亮中出现 PR 编号、链接或作者名。

highlights_examples.md 提供了四组范例，覆盖了 **Plan Mode Enhancements**、**Event-Driven Architecture**、**Background Shell Commands** 等条目风格，均遵循“加粗主题短语 + 一句概括”的模式。值得注意的是，这一规范与 index.md 的公告格式形成对比：index_template.md 的公告条目要求附 1–2 个 PR 链接与作者（如 (#nnnnn by @author)），两者互为镜像约束。

真实产物对照：填充后的 preview.md

docs/changelogs/preview.md 是一次完整填充的产物，可与模板逐段对照：

# Preview release: v0.58.0-preview.0

Released: August 25, 2026

...

## Highlights

- **Sandbox Security Enhancements**: Isolated Docker and container runtime
  sockets and binaries in macOS Seatbelt to improve sandbox safety.
- **Core Path Resolution Fixes**: Ensured consistent symlink evaluation in
  ignore path handling within core services.
...（共 5 条，符合 3–5 条约束）

## What's Changed

- fix(sandbox): isolate Docker and container runtime sockets and binaries in
  macOS Seatbelt by @josebalius in
  #28935
...（PR URL 已重写为“编号即文本”的 markdown 链接）

**Full Changelog**:
https://github.com/google-gemini/gemini-cli/compare/v0.57.0-preview.1...v0.58.0-preview.0

可以看到：Highlights 恰好 5 条且全部以加粗标题开头、不含任何 PR 号或作者；What's Changed 中每条变更都带作者与 markdown 化的 PR 链接；Full Changelog 尾链保留为跨版本 compare URL——与模板占位符及预处理规则完全吻合。

与发布通道的关系：为什么模板固定了 @preview 安装命令

模板中硬编码的 npm install -g @google/gemini-cli@preview 并非装饰，它直接对应变更日志所在通道的 npm dist-tag。releases.md 定义的发布节奏是：main 分支每晚推送 nightly；代码进入 preview 通道观察约一周后晋升 stable；三个通道各自按需产出 patch。每周二由值班工程师触发 “Promote Release” 工作流，自动完成“preview 晋升 stable、nightly 晋升 preview、main 版本 bump”三步，并以 NPM 注册表的 dist-tags 作为版本事实来源，同时校验对应 git tag 与 GitHub Release 的存在，不一致即中止。因此 preview.md 页面所记录的版本（模板中的 {{version}}）总是与 npm 上 preview 标签指向的版本保持一致，页面尾部的安装命令让用户可以直接复现该通道版本。页面本身也是这一通道定位的说明载体：预览版“未经完全验证，可能包含回归”（releases.md 原文措辞），这正是模板中稳定性声明一句的由来。

小结

preview_template.md 虽然只有 22 行，但它是 Gemini CLI 预览版变更日志流水线中约束力最强的环节：固定的标题、日期格式、稳定性声明与 @preview 安装命令保证了 docs/changelogs/preview.md 在每次 minor 发布时版式一致；五个占位符则把“机器生成的变更列表”与“人工风格约束下的高亮提炼”分离开，前者来自预处理后的发布说明 BODY，后者受 3–5 条、加粗标题、无 PR 号等规则约束。理解了模板本身、SKILL.md 的 A.2/B.2 两条填充路径，以及 releases.md 的 dist-tag 机制，就能完整解释仓库中任何一份预览版变更日志的来源与形态。