commit-message-storyteller

Commit Message Storyteller

将原始 git 差异和变更说明转换为清晰、具有故事性的提交消息，并遵循 Conventional Commits 规范。你不再得到“update file.js”这样的消息，而是能传达意图、背景和影响的提交消息。

何时使用此技能

• 用户说“写一条提交消息”
• 用户粘贴 git 差异或描述代码变更
• 用户说“我应该怎么写这次提交？”或“总结一下我的差异”
• 用户想为团队或开源项目留下更好的提交历史
• 用户正在准备拉取请求，并希望提交消息更有意义

前置条件

至少准备好以下一项：

• git diff 或 git diff --staged 的输出
• 对变更内容及原因的描述
• 修改过的文件列表

工作原理

第 1 步：收集变更背景

向用户询问（或从差异中推断）以下内容：

1. 变更内容 — 受影响的文件、函数和逻辑
2. 变更原因 — 修复错误、新功能、重构、性能优化等
3. 触发因素 — 问题编号、用户请求、技术债务等

如果用户提供原始的 git diff，请自动从差异中提取这些背景信息。

第 2 步：确定提交类型

使用以下指南，将变更映射到 Conventional Commits 类型：

类型	使用场景
feat	添加新功能或能力
fix	修复错误或不正确的行为
refactor	重构代码，但不改变行为
perf	提升性能的变更
docs	仅修改文档
style	格式、空白字符、缺少分号等变更（不改变逻辑）
test	添加或更新测试
build	构建系统或依赖项变更
chore	其他不修改源代码或测试的维护工作
ci	CI/CD 流水线变更
revert	撤销之前的提交

详细示例请参阅 references/conventional-commits-guide.md。

第 3 步：撰写提交消息

遵循以下结构：

<type>(<optional scope>): <short imperative summary>

<body — the story: why this change was made, what problem it solves>

<footer — issue refs, breaking change notices>

各部分的规则

主题行（第一行）：

• 使用祈使语气：“add”“fix”“remove”，而不是“added”或“fixes”
• 最多 72 个字符
• 末尾不加句号
• 冒号后使用小写字母

正文（讲述变更故事）：

• 解释为什么，而不是是什么（差异已经展示了是什么）
• 描述此变更之前存在的问题
• 如有相关内容，提及考虑过的替代方案
• 每行不超过 100 个字符
• 与主题行之间空一行

页脚：

• 引用问题：Closes #123、Fixes #456、Refs #789
• 标记破坏性变更：BREAKING CHANGE: <description>

第 4 步：生成输出

在可复制的代码块中输出提交消息，随后用一行通俗易懂的英语解释所讲述的变更故事。

输出示例：

fix(auth): prevent token refresh loop on expired sessions

When a user's session expired mid-request, the auth middleware was
triggering a token refresh, which itself failed validation and triggered
another refresh — causing an infinite retry loop that crashed the app.

This adds a recursion guard flag that aborts the refresh cycle if a
refresh is already in progress, returning a clean 401 instead.

Closes #312

讲述的故事： 会话过期时出现的隐性无限循环导致应用崩溃；此变更会提前终止循环并返回清晰的错误。

---

根据一个差异生成多个提交

如果差异中包含逻辑上彼此独立的变更，请将它们拆分成多条提交消息并告知用户。可使用以下判断方法：

• 不同文件且用途无关 → 可能应拆分成不同提交
• 同一文件但涉及不同事项（例如修复错误 + 重构）→ 建议拆分
• 所有变更紧密相关 → 一个提交即可

---

边缘情况

情况	处理方式
用户只提供差异，没有其他背景	根据文件名和变更的符号推断类型和范围
变更涉及许多文件，且主题不明确	询问：“这是一个逻辑上的变更，还是多个？”
检测到破坏性变更	自动添加 BREAKING CHANGE: 页脚
用户说“简短一点”	省略正文，只写一条有力的主题行
没有可用的问题编号	完全省略页脚

---

快速参考

# Get your staged diff to paste into Copilot
git diff --staged

# Or get the last uncommitted working tree changes
git diff

类型示例和范围指南请参阅 references/conventional-commits-guide.md。