由Changelog AI（LX AI）提供

从提交中分组的更改日志（不是原始git日志）

原始提交转储很嘈杂。根据功能、修复和改进进行分组符合读者扫描发布说明的方式.

为什么分组提交很重要

当读者打开发布说明时，他们会寻找影响他们的变化。一个长长的原始提交SHA-1和短消息列表会迫使读者的眼睛跳来跳去，忽略了重点。通过将提交分组到逻辑桶中，你会给读者一个快速的新功能、错误修复和内部改进地图。这个地图符合人们的浏览方式：他们首先看到标题，然后决定是否需要下面的详细信息。

读者期望

- 功能部分回答“我现在可以做什么？” - 修复部分回答“什么问题被解决了？” - 改进部分回答“什么变得更好而不改变行为？”

信号与噪音

- 原始日志包含合并提交、拼写错误修复和重构噪音。 - 分组日志仅显示对用户或下游团队重要的意图。 - 噪音减少将评估发布所需的时间从分钟缩短到秒。

将传统提交映射到组

传统提交规范提供了一个可预测的前缀，表明了意图。通过读取前缀，您可以决定提交属于哪个桶，而无需解析整个消息。

标签前缀

- feat：→ 功能桶 - fix：→ 错误修复桶 - perf：、refactor：、style：→ 改进桶 - docs：→ 文档桶（通常从用户可见的说明中省略） - test：→ 内部质量桶

自定义标签

- 团队可以添加 security：以突出显示解决漏洞的补丁。 - breaking：可用于标记需要迁移的 API 更改。 - 任何额外的前缀都应在项目的贡献指南中进行文档记录，以便生成器知道将其放在哪里。

算法：根据语义标签对提交进行聚类

我们的生成器遵循一个三步管道，将git日志转换为一组准备好供审查的组。这些步骤是确定性的，因此相同的输入始终产生相同的输出。

步骤1：解析提交消息

- 运行git log --pretty=format:%s以获取提交范围内的每个提交的主题行。

- 在第一个冒号处拆分主题以分离前缀和描述。

- 如果没有冒号，则将提交视为chore：并将其放入一个内部桶中，该桶对公共变更日志隐藏。

步骤2：按前缀分桶

- 维护一个从已知前缀（feat、fix、perf、refactor、style、docs、test、security、breaking）到提交列表的映射。

- 将每个提交追加到其前缀匹配的列表中。

- 保留每个列表内的原始提交顺序，以便后续步骤可以显示时间顺序。

步骤3：解决重叠

- 一些团队使用组合前缀，如feat(parser)：。我们去掉括号并将左侧部分视为主桶。

- 如果提交匹配多个桶（罕见，但使用自定义别名时可能发生），我们将其分配给优先列表中的第一个匹配桶：breaking > security > feat > fix > perf > refactor > style > docs > test > chore。

- 最终输出是一个有序数组，每个桶包含其提交。

步骤 | 输入 | 输出

1 | git日志主题 | 前缀 + 描述对

2 | 前缀 + 描述对 | 提交桶

3 | 提交桶 | 有序、去重的桶，准备显示

要了解算法如何在实践中工作，您可以在任何遵循约定式提交格式的存储库上尝试它。生成器将显示您手动创建的相同组，但只需一小部分时间。

审阅 UI：预览和编辑组

算法生成桶后，用户会看到一个预览，其中每个桶是一个可折叠的部分。目标是让作者在更改日志发布之前验证自动分组是否与意图匹配。

内联编辑

- 点击提交描述将其转换为可编辑的文本字段。 - 更改将保存在本地，并可以通过拖动编辑的行将提交重新分配到不同的桶中。 - 编辑的描述将作为覆盖存储，以便生成器的未来运行保持人为选择的措辞。

拖放重新排序

- 整个桶可以移动到上或下以反映所需的发布叙述。 - 在一个桶内，个别提交可以重新排序以突出显示最重要的更改。 - UI 发出一个 JSON 补丁，记录新的顺序；此补丁可以与更改日志一起提交以进行审计。

什么这不是

为了让团队设定现实的期望，必须明确工具的局限性。

不能保证完整性

- 生成器只能看到您提供的提交范围内的内容。 - 如果更改是在版本控制之外进行的（例如，手动服务器配置调整），它将不会出现。 - 我们不扫描问题跟踪器、设计文档或外部通信渠道。

不是手动审查的替代品

- 自动分组可能会错误地放置提交，如果前缀模糊或缺失。 - 作者仍应浏览生成的笔记以捕获任何错误分类的项目。 - 该工具旨在减少工作量，而不是消除对人类网关的需求。

CI/CD 集成

为了保持更新的变更日志，您可以在管道中运行生成器。该步骤会生成一个 markdown 文件，可以作为工件上传或用于创建 GitHub 发布。

GitHub 操作示例

将一个步骤添加到您的工作流中，检查代码，设置 Node，运行生成器，然后使用生成的变更日志创建发布。

- 使用：actions/checkout@v4 - 运行：npm ci - 运行：npx ai-changelog-generator --from ${{ github.event.before }} --to ${{ github.sha }} --output CHANGELOG.md - 使用：softprops/action-gh-release@v2 - 使用以下参数： - 标签名称：${{ github.ref_name }} - 名称：发布 ${{ github.ref_name }} - 正文路径：CHANGELOG.md

GitLab CI 代码段

在.gitlab-ci.yml 中添加一个任务，运行生成器并将变更日志存储为任务工件。

- 镜像：node:20 - 变量： - GIT_STRATEGY：fetch

- 运行：npm ci - 运行：npx ai-changelog-generator --from $CI_COMMIT_BEFORE_SHA --to $CI_COMMIT_SHA --output CHANGELOG.md

- 路径： - CHANGELOG.md

两个示例都使用公共的 OWASP LLM Top 10 文档作为安全相关提交的参考，并使用 NIST AI 风险管理框架作为模型安全相关提交的参考。您可以在内联中看到它们：

- https://owasp.org/www-project-top-10-for-large-language-model-applications - https://www.nist.gov/itl/ai-risk-management-framework

维护分组变更日志的最佳实践

即使使用自动化工具，一些习惯也能保持输出在项目生命周期中保持有用.

提交卫生

- 始终以约定的前缀开始提交消息. - 如果提交影响多个区域，请将其分成单独的提交，以便每个提交都有明确的意图. - 在冒号后包含一个简短的描述，以解释用户可见的影响.

定期组审查

- 在每次发布之前，打开生成的变更日志并验证每个存储桶是否包含预期的提交. - 如果您看到提交出现在错误的存储桶中，请编辑描述或添加自定义前缀来引导生成器. - 使更新贡献指南成为一种习惯，每当您添加新的自定义前缀时，以便未来的贡献者知道约定.

操作员检查清单，用于分组的更改日志（不是原始git日志）

我在每个发布版本中都保留一份书面检查清单，涉及此主题。清单故意设计得很枯燥：命名所有者，命名证据工件，命名回滚。如果一个步骤不能产生文件、票据或日志行，那么它不是一个步骤——它是一个愿望。

在您更改生产环境之前

- 冻结您将要测量的分支或配置修订版。 - 记录当前的故障模式，包括一个具体的输入和一个具体的输出。 - 确认作业运行的身份，并且该身份是否可以访问不应访问的数据。 - 打开您将要引用的主要参考资料：https://owasp.org/www-project-top-10-for-large-language-model-applications, https://www.nist.gov/itl/ai-risk-management-framework。

在您运行检查时

- 更喜欢一个可复现的路径，而不是十个传闻截图。 - 在触发工具或查询之前，写下预期的安全结果。 - 捕获正在测试的确切命令、提示、模式或正则表达式——而不是一个改述。 - 如果系统可以执行操作（发送、写入、删除、传输），则需要在同一通行中要求确认边界。

完成后

- 即使扫描结果干净，也要将残余风险与所有者和日期一起归档。 - 不要将绿色检查转换为声称完整性的销售语言。 - 当模型、工具模式或验证规则发生变化时，重新运行相同的检查清单。

ai-changelog-generator 帮助您完成可衡量的第一步。架构选择、法律签署和客户面向的声明仍然需要一个人类所有者。将检查清单中的每一行视为决策支持，而不是证书。

我如何向买家解释限制

当一个潜在客户问产品是否"涵盖一切"时，我会回答产品的边界：自动检查可以捕捉已知的模式，但新的链式和政策判断仍然需要人工审查。这份诚实可以降低支持负担，并保持博客内容与产品实际功能的一致性。

如果您需要第二个意见，请将此文档与下面的参考资料和您自己的测试环境结合起来。不要仅仅因为模型写了一个自信的总结而跳过测试步骤。

参考资料