commit

Git Commit

根据不可变证据编写语义化提交消息。让 ai-commit 负责确定性准备、提交、索引协调和推送操作。

在目标仓库的工作目录中运行每条命令。不要在 ai-commit 前后额外调用 git status、git log 或 git diff：准备阶段会为此工作流提供完整证据。仅在明确解析其稳定 TSV 记录的确定性自动化中使用 --porcelain。常规技能流程会读取人类可读的各个部分。

1. 解析参数

参数：$ARGUMENTS

• ai-commit 根据仓库配置选择消息格式。仅在明确针对单次操作覆盖时传递 --natural 或 --conventional，切勿用它们重现仓库策略。
• --all：捕获工作树和索引中的所有更改。这有意承担包含其他 Agent 工作的风险。
• --staged：准确捕获当前索引内容。不要添加会话路径。此选项与 --all 冲突。
• --natural：强制本次提交使用自然语言格式。
• --conventional：强制本次提交使用 Conventional 前缀格式。
• --push：请求在提交后推送。否则，仅在常驻指令授权时推送。
• --rebase：与 --push 配合使用时，让 ai-commit 在推送前将落后分支变基到已获取的上游分支。除非用户明确排除，否则每次经授权的推送都要传递此选项。
• --close <issue_numbers>：针对每个正十进制 issue 编号，传递一次 ai-commit commit --close <N>。接受以逗号或空格分隔的输入。ai-commit 会写入 Closes #N 行。
• --finding <finding_ids>：针对本次提交修复的每个台账 finding，传递一次 ai-commit commit --finding <id>。接受以逗号或空格分隔的输入。如果本次会话的提交修复了特定台账 finding，也要根据上下文推断该 finding。ai-commit 会写入 Finding-ID: <id> 页脚，并在提交后将该 finding 标记为已解决。切勿包含或解决本次提交实际上并未修复的 finding。
• --squash：将合并基点之后的所有分支提交替换为一个携带分支净差异的提交。助手会通过已解析的默认分支查找合并基点。Squash 模式要求工作树和索引干净，且当前分支不是默认分支，并且处于附加状态。此选项与 --all、--staged 和 --push 冲突。
• --base <branch>：覆盖默认分支检测。仅与 --squash 配合使用。
• 在 Conventional 前缀格式中，位置参数中的类型关键字会覆盖推断出的类型。在自然语言格式中，位置参数中的动词或类别关键字会覆盖推断出的动词。带引号的位置文本会覆盖推断出的描述或主题。

如果请求的操作仅是推送一个已领先的干净分支，则跳过准备步骤。检查下方的推送目标，然后运行 ai-commit push --rebase。

推送目标

ai-commit 会推送到配置的上游：branch.<name>.remote 和 branch.<name>.merge。远程可以是具名远程，也可以是 URL。如果上游分支名称不同，branch.<name>.pushRemote 必须与 branch.<name>.remote 相同。对于允许维护者推送的 PR，gh pr checkout 会写入此配置。

处理现有 PR 时，请在提交或推送前通过 gh pr view 获取其头部仓库和分支。推送到其他分支不会更新该 PR。如果上游与 PR 头部不匹配，请更正分支配置：

git config branch.<branch>.remote '<head-remote-or-url>'
git config branch.<branch>.merge 'refs/heads/<head-branch>'
git config branch.<branch>.pushRemote '<head-remote-or-url>'

然后使用 ai-commit 推送。不要手动推送。不要强制推送。如果 ai-commit 拒绝该目标，请报告其错误。报告完成前，请再次读取 PR，并确认其头部 SHA 与已推送的提交一致。

Squash 模式

仅当用户明确要求 squash 时才进入 squash 模式。切勿根据分支状态、合并请求或长期指令推断需要 squash。存在 --squash 时，按照 references/squash.md 执行计划和重置步骤。然后以 --staged 模式继续执行步骤 2 至 5。即使长期指令允许推送，在 squash 模式下也切勿传入 --push。squash 参考文档还会添加共同作者署名信息、失败时的回滚操作和 squash 报告。

2. 仅准备一次

运行一条准备命令：

ai-commit prepare [--all | --staged] [--natural | --conventional] --diff full \
  [--exclude-baseline '<path>=<oid>']... [-- <session-modified-paths>...]

• 阅读完整的准备输出。切勿通过 tail、head、awk、grep 或类似命令对其进行管道处理。输出包含打印的事务 ID，以及步骤 3 必须分析的 diff；截断输出的管道会连同 ID 一起丢弃证据。

• 仅当完整 diff 过大，无法一次读完时（例如，跨数百个文件的全仓库迁移），并且本次会话已审查过内容，才改用 --diff summary。这种情况下，根据 name-status、shortstat 和该次审查来撰写提交消息。

• 在默认模式准备之前，仅对本次会话修改过的路径运行仓库格式化工具，避免格式化 pre-commit 钩子在内容固定后对其进行修改。

• 根据本次会话中有变更且可归因于本次会话的单个仓库相对文件路径，构建默认模式的路径列表。将目录路径展开为具体文件路径，包括新建和删除的文件。切勿通过解析 git status 或 git status --porcelain 输出构建列表，因为其中可能包含其他 Agent 未跟踪或已修改的文件。默认模式要求包含本次会话编辑过的每个路径。对于重命名，包含旧路径和新路径，包括仅大小写不同的文件或目录重命名。

• 在默认模式准备之前，如果 ai-coord touched 可用，则运行该命令，并将其输出与本次会话的路径列表核对。此交叉检查中，补充遗漏的本次会话编辑过的路径。忽略本次会话未在语义上修改的路径。触及路径仅是尽力收集的证据，并非权威来源。如果命令不可用或无法识别本次会话，则静默跳过此交叉检查。

• --all 不接受显式路径，并会捕获所有已跟踪、未跟踪、已修改、已删除和已暂存的变更。

• --staged 不接受显式路径或基线排除项，并会准确捕获共享暂存区的内容。

• ai-commit prepare 会自动应用本次会话的 ai-coord 旧有脏改动基线。自动应用的排除项会显示在准备证据中，必须原样披露。仍可使用显式的 --exclude-baseline 覆盖选项，而 --no-auto-baseline 则会为确定性自动化停用发现功能。切勿还原无关变更。

  如果协调重新进入流程将本次会话已完成的编辑记录为基线，则将其 blob ID 与保留的会话证据或准备证据进行比较。只有在每个选定文件的全部差异都可归因于获授权任务时，才使用 --no-auto-baseline。对于所有权混杂或归属不确定的内容，保留排除项。

准备过程中列出 unclaimed paths 时，表示本次会话的活跃 ai-coord 认领范围未涵盖这些路径。提交之前，逐个路径作出决定：如果变更属于本次会话获授权的工作，则使用 ai-coord start 获取缺失范围；如果属于其他 Agent 的工作，则丢弃该事务并重新准备，但不包含该路径。切勿提交无法归因的路径。

准备会根据打印的事务 ID 固定确切的树和差异，不会更改共享暂存区。保留该 ID。后续提交会复用该事务，而不是从可变工作树或共享暂存区重新计算预期内容。它会将此不可变差异应用于已锁定的当前分支；如果分支期间的移动导致冲突，则会安全失败。如果准备在发出事务 ID 之前失败，则应修正证据明确指出的参数、归属或输入问题，并在获授权范围内重试准备。

3. 分析并撰写

分析这份已准备好的完整差异。不要仅为了获取不同的证据，就替换有效的准备结果。超出大小限制的 逐文件部分会附带 DIFF_TRUNCATED 说明。其名称状态和简要统计证据仍决定提交消息。

• 使用打印出的消息格式和消息格式规则。规则来源是 ai-commit。不要加载单独的 Conventional 或 Natural 参考。
• 应用位置覆盖规则、检测破坏性变更、从代码推断范围或上下文，并且仅在正文能补充实质性理由时才添加正文。
• 收集 --close 中的议题编号，以及对话记录中本次提交实际解决的议题引用。收集 --finding 和上下文中的发现 ID。将它们作为第 4 步的标志传入。不要在 -m 值中写入 Closes、Finding-ID 或 Agent-Session 行。ai-commit 会附加 Closes 段落和尾注块，其中包括经过验证的准备尾注。不要自行生成或修补缺失的尾注。

撰写一个主题段落，以及一个可选的正文段落。仅当尾注是 ai-commit 不会生成的内容（例如 squash 模式下的 Co-authored-by:）时，才自行传入尾注段落。ai-commit 会将其尾注合并到该段落中。

ai-commit 会原样接收每个 -m 值，并拒绝包含字面量 \\n 的值。在带引号的参数中输入实际换行符，如第 4 步示例所示。

4. 提交事务

运行：

ai-commit commit <transaction-id> -m '<subject>' [-m '<body>'] [--close <N>]... [--finding <id>]... [--push --rebase]

例如，包含两项的正文应作为一个包含实际换行符的 -m 参数传入：

ai-commit commit <transaction-id> -m '<subject>' -m '- first material change
- second material change' --close 42 --finding 873d2a01bb9722f8 [--push --rebase]

获得推送授权且推送目标检查通过时，追加 --push --rebase。此时，只有在没有进行中的 Git 操作，且工作树和索引干净时，ai-commit 才会将落后的分支变基到已获取的上游分支。如果变基中止，它会取消变基。同一命令可处理默认、--all 和 --staged 事务。绝不要使用直接 Git 命令暂存或提交这些更改。

事务具有幂等性。中断、锁竞争或可重试的退出后，使用相同的事务 ID 和消息参数重试。对于这些可重试的失败，不要从更新的可变状态重新准备。重放会恢复或返回留存的回执，而不会创建重复提交。绝不要删除索引锁。

对于已确认发生在创建提交之前的确定性内容失败，修正获得授权的工作，并使用恢复引用替换未提交的准备结果。这包括 snapshot-check hook modified prepared content。不可变重试无法修复固定在失败快照中的内容。现有任务授权涵盖此恢复操作。

在替换失败的准备结果或添加 --no-verify 或 --no-gpg-sign 之前，请阅读 references/failure-recovery.md。绕过标志是针对单次尝试的明确恢复选项，不是首次尝试的默认选项。

提交和推送后，--finding 会通过 ai-coord finding resolve --as fixed 解决每个发现，因此 FINDING_RESOLVED 行之后无需再运行单独的解决命令。若出现 FINDING_UNRESOLVED <id> 且退出码为 3，提交和推送仍然有效。原样重放相同命令一次。如果再次失败，请报告标准错误中的原因，并运行其指定的 ai-coord finding resolve 命令。

5. 完成与回执

保持回执简洁，不加修饰地转发结果行：

• COMMITTED <transaction-id> <commit-oid> 证明提交已创建或通过幂等恢复。未获授权推送时， 即表示完成。

• HOOK_ADDED <path> 指明钩子在已准备的路径集合之外引入的内容。披露每一条此类结果行。

• FINDING_RESOLVED <id> 证明台账中的发现已随提交 OID 解决。FINDING_UNRESOLVED <id> 表示 提交已保留，但台账仍将该发现标记为未解决。遵循第 4 步的重放规则。

• REBASED <branch> <count> 披露 ai-commit 在推送前已将分支变基到 <count> 个上游提交之上。在提交工作流中， 后面会跟着一条 INTEGRATED 结果行。

• PUSHED <branch> 或 PUSHED_NEW <branch> 证明更改已传播，并完成获授权推送或仅推送的工作。

• PUSHED <transaction-id> <commit-oid> 是重放已推送事务时返回的保留凭据。

• INTEGRATED <transaction-id> <head-oid> 披露分支不再包含事务的原始提交，但 HEAD 已包含其内容，例如在变基后或存在相同的上游提交时。后续的 PUSHED 结果行仍表示工作已完成。应将 head OID 作为已推送凭据，而非 COMMITTED OID。

• SUPERSEDED <transaction-id> <commit-oid> 表示安全地未完成：分支既不包含该提交，也不包含其内容，且未推送任何内容。检查分支。如果仍需要此更改，请丢弃该事务并重新准备。

• BEHIND <branch> <count> 表示安全地未完成，绝不表示完成：ai-commit 已获取更改，并拒绝集成或推送。此前的 COMMITTED 仍能证明本地提交已创建。

  如果未使用 --rebase，请使用 --push --rebase 重放相同的事务命令（仅推送的工作则运行 ai-commit push --rebase）。如果使用了 --rebase，stderr 结果行会说明上游为何未被集成。当另一项 Git 操作正在进行，或工作树或索引不干净时，请停止并报告需要协调该分支。如果变基已停止并中止，请报告冲突路径，并在解决冲突前征求用户同意。绝不自动储藏，也绝不手动变基。

不要报告无关的树状态、命令未输出的领先／落后计数、暂存过程说明或成功的钩子活动。仅添加恢复参考中要求的一行绕过披露。