开发者与客户语气预设相同的提交

为什么要分开语气预设？

我开始这个项目是因为我看到团队浪费时间重写相同的变更日志条目给两个不同的读者。工程师需要看到代码中发生了什么变化，哪些文件被修改，以及任何破坏性的内部API。产品经理、支持人员和最终用户关心变化对他们的意义：新功能、修复的bug、改进的性能或删除的限制。单一的语气不能很好地服务于两个群体。通过创建两个不同的预设，它们操作相同的提交列表，我们保持源真实性不变，同时提供定制的消息。这种方法还允许SemVer标签保持单一的合同含义来源，因为标签附加到提交组，而不是文字。

开发者语气预设：详细优先

提交级别的详细信息

当开发者预设激活时，AI 会将每个提交扩展为一个包含文件路径、修改的函数或类以及更改性质（添加、删除、重构）的句子。例如，修复 src/api/user.go 中的空指针异常的提交变为："在 GetUserByID 中修复了空指针异常，当传入的 ID 为零时，添加了防护子句和单元测试。"

链接到跟踪系统

如果提交消息包含问题 ID（例如 ABC-123），则预设会将其包裹在跟踪器的链接中，假设团队已配置了基础 URL。这允许工程师在不离开变更日志的情况下跳转到讨论或设计文档。

包含技术背景

预设添加了在提交相关的 CI 运行中出现的任何相关编译器警告、测试覆盖率更改或性能基准 delta。这为修改的区域提供了快速的健康检查。

LLM 输出的安全性和合规性检查

由于文本是由语言模型生成的，我会将其传递通过一个轻量级的安全过滤器，检查是否存在不允许的内容。过滤器参考了 OWASP LLM Top 10 以获取提示注入风险，并参考了 NIST AI 风险管理框架以获取管理幻觉和偏见的指导。如果一个段落触发了规则，则会在发布前标记为人工审查。

典型发布的示例列表

- 在 src/retry/policy.go 中添加了 RetryPolicy 接口，以允许可插拔的回退策略。 - 从 src/cache/legacy.go 中删除了已弃用的 LegacyCache 结构；所有调用者已迁移到 LRUCache。 - 修复了 WorkerPool.Start 中的竞争条件，其中 nil 通道可能会被关闭两次；添加了互斥守护。 - 更新了 Go 模块 github.com/stretchr/testify 从 v1.7.0 到 v1.8.2，以获取 assert 包的安全补丁。 - 添加了 JSONEncoder 的基准测试，显示了对负载小于 10KB 的有效载荷的分配大小减少了 12%。

客户语气预设：以益处为先

结果导向语言

使用客户预设，AI 会将每个提交重写为一个句子，描述用户现在可以做什么或解决了什么问题。技术术语被替换为简单的术语。同样的空指针修复变成了： “用户在用户查找字段中输入零值 ID 时将不再看到错误。”

避免内部标识符

提交哈希、分支名称和内部问题编号除非是公共功能标志或版本化 API 端点的一部分，否则会被省略。目标是保持噪音低。

突出用户影响

如果提交提高了性能，预设会将基准收益转换为用户可见的语句： “页面加载时间现在在移动设备上快了多达 15%。” 如果提交删除了限制，它会读取： “您现在可以上传文件大小最多为 100 MB，而不是之前的 25 MB 限制。”

链接到公共文档

当更改涉及公共 API 端点或配置选项时，预设会添加一个链接到相关文档部分，假设文档站点遵循可预测的 URL 模式（例如 https://docs.example.com/api/v2/users）。

相同版本的示例列表

- 重试逻辑现在适应临时网络故障，减少了在不稳定连接上上传失败的次数。 - 删除了旧的缓存实现；新的缓存使用的内存更少，并且会自动清除过期的条目。 - 修复了当多个工作线程同时启动时可能发生的罕见崩溃。 - 更新了第三方库以解决安全通知；您无需执行任何操作。 - JSON 响应现在更轻量，这降低了在计量连接上使用的数据量。

从提交差异到两个叙述

解析和分组

该流水线首先运行 git log --pretty=format:%H %s %b --since="1 周前" 以收集自上次标签以来提交的内容。每个提交都被解析为其约定提交类型（feat、fix、perf、refactor 等）和范围。具有相同类型和 SemVer 含义的提交被分组在一起，因为它们将共享相同的版本增加。

应用语气特定提示

对于每个组，我构建两个提示：一个针对开发人员预设，一个针对客户预设。开发人员提示要求“包含文件名、符号和任何相关测试或基准更改的详细技术描述”。客户提示要求“避免内部术语，专注于用户体验的简洁、面向利益的解释”。同一个提交列表同时用于两个提示，以确保底层事实保持相同。

人工审查

AI 输出进入草稿编辑器，维护人员可以接受、编辑或拒绝每个句子。我发现，大多数编辑都是对单词的轻微调整，而不是事实上的更改，这表明该模型在保持对源差异的忠实度方面很好。在审查后，草稿被渲染为 Markdown 和 HTML 以进行发布。

表格：将约定提交类型映射到语气短语

提交类型 | 开发人员短语示例 | 客户短语示例 feat | 添加 ReportService 的 ExportCSV 方法以流式传输行并减少内存使用。 | 您现在可以直接从导出按钮下载报告作为 CSV 文件。 fix | 解决 JobQueue.Push 中的死锁，当高负载下排队 nil 作业时。 | 作业将不再在系统繁忙时卡住。 perf | 用哈希表替换 TagIndex.Find 中的 O(n²) 查找，减少 10k 标签的延迟从 12ms 到 0.8ms。 | 标签搜索现在显著更快，尤其是对于大型库。 refactor | 从 AuthHandler 中提取 PasswordValidator 接口以允许可插拔的强度规则。 | 密码要求现在可以在不更改核心登录代码的情况下进行调整。 docs | 更新 API.md 以包含新的 PATCH /users/:id 端点描述和示例有效负载。 | 帮助中心现在显示如何部分更新用户配置文件。

跨语气保持SemVer含义

版本更新规则保持与提交的锚定

SemVer标签仅由提交组中的传统提交类型决定：feat触发次要更新，fix触发补丁更新，breaking change触发主要更新。由于语气预设不会改变提交消息或其类型，因此无论阅读开发者版本还是客户版本，生成的版本号都是相同的。

契约一致性

我将SemVer标签视为软件生产者和消费者之间的契约。更改日志只是该契约的可读表达。通过保持契约不变，团队可以依赖自动化工具（如发布机器人或依赖项检查器）来正确解释版本，同时双语气更改日志为两个受众服务而不会产生歧义。

主要版本示例

假设提交添加BREAKING CHANGE：删除遗留v1 API。开发者预设将记录确切的文件删除和所需的迁移步骤。客户预设将解释旧API端点不再可用，并将用户指向v2文档。在两种情况下，版本都从2.4.1更新到3.0.0，保持契约含义。

什么这不是

我想明确说明这种方法的局限性，以便您可以设定现实的期望。

- 它不能保证每个生成的句子在语气方面都是完美的；偶尔会出现过于技术化的措辞，或者在开发者草稿中出现模糊的益处语言。仍然需要人工审查。 - 它不是专职技术作家或产品营销人员的100%替代品。AI加速了第一次草稿，但细微差别、品牌声音和法律免责声明仍然需要人工处理。 - 它不会消除清晰的提交卫生的需要。如果提交消息模糊或缺乏常规提交结构，分组将会不够准确，输出将会不那么有用。 - 它不是一个可以自动满足每个监管机构或无障碍指南的魔术工具。我添加的安全检查是基本的；您仍然应该运行自己的合规性审查。 - 它不能保证变更日志永远不会错过任何更改。如果提交被省略在git日志范围之外（例如，由于浅克隆或错误过滤），它将不会出现在任一语气中。

参考资料

- OWASP LLM 前10名 - NIST AI 风险管理框架

相关阅读

- 从提交中分组的更改日志（不是原始git日志）— Changelog AI - LX AI微型SaaS主题矩阵