---
title: "变更日志"
description: "变更记录指南——带日期、分类的条目标记破坏性变更并深度链接到文档。包含清单和搭建命令。"
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 变更日志

> **需求**
>
> 在工作中查阅——读者维护着一个昨天还能用的集成（被忽视的"维护"工作）。他们的问题是：*"有什么变化，会破坏我吗，我该怎么办？"* 不传达变更的文档到下个季度就会过时——而且对智能体来说风险更高，因为变更日志是模型的陈旧先验被纠正的地方。

<h2 id="when-to-use-it">何时使用</h2>

每个产品一个变更日志（或每个明确版本化的接口一个）。两个承重区分：

- **记录 vs. 策略：** 带日期的变更记录在这里；版本化工作方式和迁移方法在它们自己的页面上，从每个破坏性条目链接过去。
- **两种体裁，按读者关注点选择：**
- **按日期开头**——用于持续发布的产品接口。按发布日期分节；条目以变更内容为标题。
- **按版本开头**——用于版本化的制品（SDK、命名的 API 版本）：按版本分节（`## [2.14.0] — 2026-06-18`，库项目加一个 `Unreleased` 章节）。以下的条目规则适用于每个版本章节*内部*。维护者的问题"2.13 和 2.14 之间有什么变化？"在按日期开头的日志中无法回答——如果读者固定版本，按版本开头。

变更日志不是：

- **提交日志。** 变更日志是为人类（现在还有智能体）编写的——精心策划的、以收益为先的条目，而非合并信息的堆砌。如果一个变更不值得解释，就不值得列出。
- **发布营销。** 发布帖是说服；变更日志条目是告知。如果存在发布帖，从条目中链接——不要用发布帖替代条目。
- **迁移指南。** 条目说明*有什么*破坏了并链接出去；迁移的逐步操作是操作指南（或大的迁移用专门的迁移指南）。

<h2 id="title--description">标题和描述</h2>

- **页面标题：** "Changelog"——固定的、预期的字符串。
- **条目标题：变更本身，具体且自成一体。** "Retry backoff is now configurable per endpoint"——不是 "Improvements to delivery"（什么都没说），也不是裸版本号（版本用作章节标题，不是条目标题）。
- **描述公式（页面）：** "*产品*的每个值得注意的变更，带日期，标记破坏性变更。"

<h2 id="scaffold-this-page">搭建此页面</h2>

安装指南——你的编码智能体会读取完整的骨架和清单，并将其适配到你的产品：

```sh
npx add content-changelog
pnpm dlx add content-changelog
yarn dlx add content-changelog
bunx add content-changelog
```

<h2 id="component-guidance">组件指导</h2>

- **章节标题（日期或版本）+ 条目子标题**是结构。**破坏性标记以粗体开启条目正文**（`**Deprecated · Breaking, effective 2026-09-18**`）——扫读者和 feed 阅读器看到的第一件事，不污染标题的锚点。在渲染页面中，标题行上的 Badge 组件可以呼应它。
- **分类标签**（六个标准分类：Added / Changed / Deprecated / Removed / Fixed / Security）作为一致的粗体前缀——它们使页面可按肉眼和机器筛选。
- **不适用：** Steps（迁移步骤在链接的指南中）、Cards、截图（改为链接展示新 UI 的文档——变更日志中的截图会永远原地腐烂）。

<h2 id="ending">结尾</h2>

变更日志不结束；它累积。契约在*顶部*（策略链接、订阅频道）和每个条目（链接到描述新状态的页面）。已发布的条目永远不*悄悄*改写：如果条目被证明有误——一个破坏性变更未标记——修正原条目*并*发布一个带日期的修正条目，这样按版本扫描的升级者和按时间线阅读的读者都能看到。

<h2 id="thresholds">阈值</h2>

- **条目正文 ≤ 3 句。** 超出此深度的内容放在链接的详情页、迁移指南或发布帖中。
- **改变已记录行为的条目链接到更新后的文档页面。** Fixed 和 Security 条目在存在时链接到相关参考或故障排除页面——文档从未记录过的行为修复没有可指向的地方，这没关系。
- **每个破坏性/废弃条目包含：受影响者、应对措施、日期。** 缺少三者中的任何一个，都不适合发布。

<h2 id="links--freshness">链接和新鲜度</h2>

变更日志是站点的新鲜度层——条目深度链接到稳定的文档锚点，这也是参考锚点永远不移动的另一个原因（[参考指南](/writing/recipes/reference)）。发布条目和更新它链接的页面是*一个*动作，而非两个：一个宣布参考中尚未展示的字段的条目记录的是一个不存在的产品。条目标题本身是其他人引用的永久链接——用同样的稳定性规则对待它们。

<h2 id="agent-notes">智能体备注</h2>

- 变更日志是**先验纠正接口**：废弃的内容在训练数据中延续，所以 Deprecated/Removed 条目是阻止智能体推荐它们的东西。写成智能体可以执行的扁平声明："`attempt_count` 已废弃；使用 `attempt`。"
- 日期使用 ISO 格式（`2026-06-18`）；"上个月"在检索到的块中毫无意义。
- 每个条目自成一体：完整的字段名、完整的功能名——单独检索的条目必须单独有意义。
- 永远不要用个性替代事实。没有具体内容的俏皮话是任何读者或智能体都无法执行的非陈述；如果想要语感，加在事实*之后*，而非替代事实。

<h2 id="checklist">清单</h2>

建议性——供作者或智能体自查，不是构建门禁：

- [ ] 体裁有意选择：按日期开头（持续发布接口）或按版本开头（固定制品，库项目有 Unreleased）
- [ ] 条目以变更为标题，自成一体，逆序排列
- [ ] 已分类：Added / Changed / Deprecated / Removed / Fixed / Security
- [ ] 破坏性标记开启条目正文，包含受影响者 + 应对措施 + 日期
- [ ] 废弃和移除作为两个独立条目宣布；永不悄悄进行
- [ ] 改变行为的条目链接到更新后的文档页面（Fixed/Security 在有目标时链接）
- [ ] 条目正文 ≤ 3 句；影响在机制之前；深度放在链接页面上
- [ ] 链接的文档页面在发布时已更新
- [ ] 修正既修正原条目又添加带日期的修正条目
- [ ] 订阅频道（至少 RSS）链接在顶部；条目锚点稳定

Source: https://nimbus-docs.cn/writing/recipes/changelog/index.mdx