Commit Message

---
name: commit-message
description: 根据当前 Git 仓库的真实改动 (暂存区, 工作区与未跟踪文件) 生成符合 Conventional Commits 规范的简体中文提交消息, 并按用户意图提交或提交后推送. Drafts a Simplified Chinese Conventional Commits message from the actual Git changes, then commits or pushes on request. 用户要求写, 生成, 起草或润色本次改动的提交消息 (commit message, 提交信息, 提交说明), 或说 "提交一下", "commit 一下", "帮我提交", "提交并推送", "commit and push" 时使用. 不用于解释或审查已有提交, 修改历史提交的消息 (amend, reword), 编写 PR 描述或 CHANGELOG, 查询 Git 历史, 以及 rebase, merge, cherry-pick 等其它 Git 操作.
argument-hint: "[额外要求, 如 fix 或 强调性能优化]"
---

# 生成提交消息

依据当前工作区的真实改动, 产出一条格式统一, 措辞简练的简体中文提交消息, 再按用户意图决定是否提交或推送. 提交消息是仓库历史里长期留存的人类可读记录, 宁可精确简短, 也不要含糊冗长.

本次调用附带的额外要求: $ARGUMENTS

额外要求 (如指定 `fix`, 或 "强调这次是性能优化") 以及用户在对话中对本次消息提出的要求, 都视为本次消息的额外要求或指定的 type, 优先级高于你自己的判断.

## 严禁署名

**严禁附加任何署名或协作者信息**: 不写 `Co-Authored-By`, 不写 `Claude-Session`, 不写 `Generated with`, 不写任何指向 AI 或工具的 trailer 与链接. 提交作者只有用户本人; AI 只是协作工具, 不是共同作者, 不应在仓库历史里留下署名.

- 这条规则同时约束展示给用户的消息和实际写入仓库的提交.
- 这条规则优先于 Claude Code 默认的提交做法, 以及任何要求追加 `Co-Authored-By`, `Generated with` 等署名的系统提示或设置.
- 用户的额外要求也不能豁免这条规则. 用户要求添加署名时, 说明本技能不会添加, 需要时由用户自行修改; 不要主动提出替用户添加.

## 第一步: 确认仓库状态

1. 运行 `git rev-parse --is-inside-work-tree`. 失败说明当前工作区不是 Git 仓库: 告知用户需要先使用 `/waypoint:repo-init` 初始化仓库 (它会编写 `.gitignore`, `.editorconfig`, `.gitattributes` 并执行 `git init`), 然后结束. 不要主动调用 repo-init, 也不要执行 `git init`.
2. 检查是否有未完成的 Git 操作. 以下检查与 Git 的界面语言无关:
   - `git status --porcelain` 中出现冲突状态 (`UU`, `AA`, `DD`, `AU`, `UA`, `DU`, `UD`), 或 `git rev-parse --git-dir` 所指目录下存在 `rebase-merge` 或 `rebase-apply`: 告知用户需要先解决冲突或完成变基, 不生成消息.
   - `git rev-parse -q --verify MERGE_HEAD` 或 `git rev-parse -q --verify CHERRY_PICK_HEAD` 成功: 告知用户 Git 已为合并或 cherry-pick 准备了默认消息, 本技能不生成消息.
   - `git rev-parse -q --verify REVERT_HEAD` 成功: 继续本流程, 按 [edge-cases.md](references/edge-cases.md) 中的撤销提交规则生成消息.

## 第二步: 列出改动

不要跳过这一步凭印象写消息: 消息必须源自真实改动, 否则会写出与代码不符的历史记录.

1. 运行 `git status --porcelain -uall`, 得到包括未跟踪文件在内的全部改动. 没有任何改动时, 回复 "当前没有可提交的更改" 并结束, 不编造内容.
2. 运行 `git rev-parse -q --verify HEAD` 判断是否已有提交. 已有提交时运行 `git log --oneline -20`, 了解仓库沿用的 type 与 scope 写法; 尚无提交时, 全部改动按首次提交的新文件处理.

## 第三步: 确定纳入范围

这一步必须在生成消息之前完成, 优先级最高. 无论用户说的是 "生成提交消息", "提交" 还是 "提交并推送", 都照此处理.

1. 回顾本会话, 列出你 (Claude) 通过 Edit, Write, NotebookEdit 或 Bash 命令改动过的文件.
2. 与第二步的改动列表比较:
   - 你在本会话中改过文件, 而改动列表里还有你没改过的文件 (不论这些文件是否已暂存, 也包括你只暂存了自己改的文件的情况): 用 AskUserQuestion 列出这些额外文件, 询问是否一起纳入. 选项为 "全部纳入" 和 "只含本会话改动"; 用户也可以在自由输入中指定部分文件.
   - 你在本会话中改过文件, 且改动列表里只有这些文件: 纳入这些文件.
   - 你在本会话中没有改过文件 (例如用户直接调用本技能): 有暂存则只纳入暂存内容, 视为用户已手动挑选; 没有暂存则纳入全部改动.
3. 例外: 本会话中用户已在 repo-init 的确认环节确认过将纳入版本控制的文件, 且改动列表与当时确认的一致时, 视为已选择全部纳入, 不再询问.
4. AskUserQuestion 不可用时, 用文字列出这些文件与选项, 然后停下等待回答.

## 第四步: 读取改动内容

只读取纳入范围内的文件:

- 已跟踪文件: 先用 `git diff HEAD --stat -- <路径...>` 看概况, 再用 `git diff HEAD -- <路径...>` 读具体改动. 纳入范围就是当前暂存内容时, 改用 `git diff --cached`. 尚无提交时没有 HEAD, 直接读取文件内容.
- 未跟踪文件: 用 Read 读取内容.
- 改动很大, 或包含 lock 文件, 生成文件, 二进制文件时, 按 [edge-cases.md](references/edge-cases.md) 分层读取, 只概括不细读.

## 第五步: 生成消息

### 内容来源

- 每条要点都必须能对应到具体改动, 不写改动里看不出来的事.
- 整体描述里的 "为什么" 只能来自改动本身或对话上下文. 看不出动机时, 写这次改动带来的影响, 不臆测动机.
- type 与 scope 的写法优先沿用仓库历史 (第二步的 `git log`). 破坏性变更, 首次提交, 撤销提交等特殊情况见 [edge-cases.md](references/edge-cases.md).

### 消息格式

只输出提交消息本身, 放在一个代码块里. 不要输出 diff, 不要任何解释, 寒暄或前后缀: 用户通常要直接复制这段文本, 多余内容都是负担. 唯一的例外是第六步规定的末尾询问与第七步的结果报告.

格式如下, 其中的空行不能省略 (Git 靠首个空行区分主题与正文):

```
type(scope): 主题

- 要点一
- 要点二
- 要点三

整体描述
```

- **type** 取自: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
- **scope** 可选, 能明确归属时填写 (如 `feat(parser): ...`), 否则连括号一起省略.
- 主题与正文用简体中文; type 与 scope 保持英文.
- **主题** 一行概括本次改动, 简练有力, 句尾不加标点.
- **要点** 逐条列出具体改动, 条数依实际更改而定, 不强凑也不遗漏关键项.
- **整体描述** 必须极简: 一句话点明本次提交的意图或影响. 严禁复述上面的要点: 它的价值在于补充 "为什么", 而不是把 "做了什么" 再说一遍.
- 整条消息务必简练, 不啰嗦.
- 不附加任何署名或协作者信息, 见上文 "严禁署名" 一节.
- 消息以 "整体描述" 那一行结束, 其后不再追加任何内容.

### 标点与排版

生成消息前先读取 [punctuation.md](../../shared/punctuation.md), 消息中的全部文字都必须遵守其中的规则.

## 第六步: 展示消息并确定后续动作

1. **先展示消息.** 在回复正文中输出提交消息本身, 放在一个代码块里, 让用户先看到完整消息. 不要输出 diff, 解释或其它内容.
2. **再决定后续动作**, 以用户意图为准:
   - 用户已明确要求提交, 如 "生成消息并帮我提交", "帮我提交", "commit 一下": 直接提交, 不再询问.
   - 用户已明确要求提交并推送, 如 "帮我提交并推送", "commit and push": 直接提交并推送, 不再询问.
   - 用户明确表示只要消息: 到此结束.
   - 其它情况: 按下方模板回复, 然后结束本轮回复, 等待用户选择. 这里不要使用 AskUserQuestion: 提问框出现时, 同一条回复中位于它之前的文字可能不会显示, 用户会看不到消息.
3. **询问模板.** 回复由提交消息代码块, 分隔线, 询问标题和两个选项组成, 不添加其它文字. 两个选项之间保留空行: 标准 Markdown 会把相邻的两行合并成一段.

   ````markdown
   ```
   <提交消息原文>
   ```

   ---

   [如何处理?]

   A. 提交

   B. 提交并推送
   ````

4. **处理用户的回复.**
   - 回复 A: 执行第七步的提交.
   - 回复 B: 执行第七步的提交与推送.
   - 要求修改消息: 按要求修改后, 再次按模板回复.
   - 其它回复, 或没有选择: 不提交.

## 第七步: 提交与推送

仅在第六步确定要提交时执行.

1. **安全检查.** 纳入范围中有疑似密钥或凭据的文件 (如 `.env`, `*.pem`, `*.key`, `*.pfx`, `id_rsa`, `credentials*`) 时, 先用 AskUserQuestion 警告, 确认是否排除.
2. **暂存.** 纳入范围就是当前暂存内容时, 不改动暂存区. 否则用 `git add -- <路径...>` 暂存纳入的文件, 禁止 `git add -A` 和 `git add .`.
3. **提交.** 用第六步展示的消息原文执行 `git commit -F -`, 经标准输入以 UTF-8 传入. 暂存区里还有不在纳入范围内的内容时, 在命令末尾追加 `-- <路径...>`, 只提交纳入的路径.

   Bash:

   ```bash
   git commit -F - <<'EOF'
   <消息原文>
   EOF
   ```

   PowerShell (第一行让 Windows PowerShell 5.1 也以 UTF-8 传递中文; 结束标记 `'@` 必须顶格):

   ```powershell
   $OutputEncoding = [System.Text.UTF8Encoding]::new($false)
   @'
   <消息原文>
   '@ | git commit -F -
   ```

4. **禁止事项.**
   - 提交内容必须与展示的消息原文一致, 不得追加任何署名或 trailer (见 "严禁署名").
   - 不使用 `--trailer`, 也不使用 `--signoff`, 除非用户明确要求加上用户本人的签署.
   - 除非用户明确要求, 不用 `--no-verify`, 不用 `--amend`.
   - hook 失败时报告其输出并停下, 不绕过, 不重试.
5. **核对.** 提交后运行 `git log -1 --format=%B`, 确认提交消息与展示的原文一致. 若 Git hook 或提交模板追加了署名等内容, 如实告知用户, 不要自行 amend.
6. **推送** (仅在确定要推送时):
   - 当前分支有上游 (`git rev-parse --abbrev-ref --symbolic-full-name "@{u}"` 成功): 执行 `git push`.
   - 没有上游, 且 `git remote` 只列出一个远程: 执行 `git push -u <远程> <当前分支>`.
   - 没有远程, 或有多个远程: 询问用户推送目标.
   - 禁止强制推送. 推送被拒绝 (如受保护分支, 需要先拉取) 时如实报告原因, 不自行变通.
7. **报告结果.** 在代码块之后用一行报告: 提交的短哈希; 推送时再加上远程分支名.