changelog

更新日志

将明确定义的变更范围转化为真实可信的版本发布说明。已交付工作的数量和重要性决定条目数量、技术深度和呈现形式。

确定范围

根据请求和代码仓库推断：

• 目标分支、标签范围、版本发布或日期窗口；
• 是否排除未提交或尚未发布的工作；
• 受众和预期的技术深度；
• 输出形式：纯文本、Markdown、HTML 卡片、图片或组合形式；
• 现有更新日志规范、模板、视觉系统和过往示例。

仅在范围或发布状态仍不明确时提问。在交接说明中记录确切范围。没有部署证据时，不要将已合并、已提交或已通过功能标记启用的工作描述为已上线。

检查变更内容

如果代码仓库中有原生版本发布工具，请优先使用。否则，检查所选范围：

git log --oneline <range>
git diff --stat <range>
git diff --name-status <range>

阅读含义不明确的差异，以及相关测试或文档。根据用户可见的行为对提交分组，而不是按提交边界分组。

如果内部变更会影响兼容性、安全性、可靠性、性能、迁移或运维人员的行为，请将其纳入。若变更对目标受众没有实际影响，则予以排除。

对于每个候选条目，记录：

• 对用户或运维人员的影响；
• 作为依据的提交或差异路径；
• 发布状态；
• 破坏性变更、迁移、安全性或限制详情；
• 置信度和缺失的部署证据。

面向受众起草

根据范围所支持的内容确定条目数量。只有在变更共同形成一个连贯结果时才合并；不要为了填满版面而凑数。

每个条目都应说明变更内容及其对受众的意义。只有当读者需要相关实现语言来采用、调试、迁移或评估此版本时，才加入这些内容。

保持产品原有的语气和大小写风格。不要强行改用小写、表情符号、标语或只强调收益的表述。如果现有模板包含图标或类别标签，请保持一致并确保易于访问。

在受影响的条目旁注明破坏性变更和所需操作。已发布文案中不得包含未经证实的部署声明；应单独报告此类声明。

计算真实可信的统计数据

仅在指标有帮助时使用，并准确标明其统计对象。不要把多个提交中变更过的文件条目当作唯一文件数。

计算 Git 范围内的唯一文件数：

git diff --name-only <range> | sort -u | wc -l

使用 git diff --numstat <range> 统计新增／删除的文本行数，并考虑二进制条目。提交数、唯一文件数或变更行数都不能代表用户价值。

按需制作视觉产物

如果用户要求制作卡片，或代码仓库已有成熟的更新日志模板：

1. 检查现有素材、CSS、尺寸和以往产物；
2. 除非用户要求修改设计，否则保留模板中锁定的代码；
3. 根据实际条目数量和文案长度选择合适的版式；
4. 按照代码仓库的命名规范创建带日期的产物；
5. 按目标尺寸渲染或截取。

如果没有模板，请依据代码仓库中的品牌信息确定字体、颜色和署名。不要默认采用深色等宽字体卡片。构建语义化 HTML，在适当情况下确保文本可选择，并支持所需的截图工具和操作系统。

如果目标平台或尺寸不明确且会影响版面构成，请提问，或提供明确标注的合理格式。

输出要求

交付用户要求的产物，并提供：

Range: [commits/tags/dates and branch]
Audience and channel: [who/where]
Release status: [verified live, released, unreleased, or mixed]
Items: [final count]
Provenance: [item -> commits or paths]
Statistics: [definitions and values, if used]
Artifacts: [paths and dimensions]
Limitations: [deployment or content facts not verified]

如果用户只要求纯文本，不要创建 HTML。如果用户要求审查，除非用户也要求修改，否则只提供审查结果和建议文案。

验证

1. 对照所选范围和发布证据，重新核查每项说法。
2. 确认没有因“面向用户”筛选而掩盖任何实质性的破坏性、安全性、兼容性或迁移变更。
3. 确认合并后的条目描述的是同一项结果，且没有任何条目只是为了凑数。
4. 使用与统计项标签相符的命令重新计算统计数据，并妥善处理二进制文件。
5. 验证日期、产品名称、链接、版本和归属信息。
6. 按目标尺寸渲染视觉内容，并检查溢出、裁切、对比度、层级和长条目的显示情况。
7. 使用可用工具打开实际输出，或提供渲染路径；不要依赖手动截图说明来验证。
8. 报告部署／线上状态是直接验证的，还是推断得出的。