自动 Git 提交

概述

为当前任务确定安全的提交范围，结合项目规则与近期历史编写提交信息，然后创建一次 Git commit。

激活边界

仅在用户明确点名 git-auto-commit，或明确选择带有该名称的选项时使用。

普通的“提交一下”、任务内容与本技能匹配、其他文档提到本技能、询问或否定使用本技能，都不构成调用。

一次调用只处理一个仓库中的一个提交单元，并创建至多一个 commit。显式调用本技能已经授权为当前提交单元暂存文件并提交，不必再次确认生成的提交信息。

确定提交范围

先检查：

git status --short
git diff
git diff --cached

提交范围只包括以下来源：

• 当前任务或当前会话产生的修改；
• 用户明确指定要包含的修改。

已有 staged 状态不能证明文件属于本次提交。对比 staged 与 unstaged diff，排除会话开始前已经存在或与当前任务无关的修改。按明确路径暂存最终范围。

如果无法安全区分应提交和不应提交的内容，说明具体歧义并停止，不猜测文件归属。

决定提交信息

分别判断两个维度：

1. 语言：标题与正文使用哪种自然语言；
2. 标题风格：第一行采用 Conventional Commits、普通描述句、带工单号的格式，或项目已有的其他格式。

两个维度各自按照下面的优先级决定，不要因为一个来源只规定了其中一项，就忽略另一项的后续来源：

1. 用户对本次提交的明确要求；
2. 项目对 Git 提交信息的明确规则；
3. 最近相关提交呈现的主导模式；
4. 默认值：英文 + Conventional Commits。

读取项目规则

读取适用于当前仓库和修改文件的 AGENTS.md 及其直接引用文件，并检查明显的贡献指南或提交配置。只有明确针对 commit message 的约定才决定本技能的语言或标题风格；一般性的对话语言或文档语言要求不自动等同于提交规则。

读取近期历史

查看最近若干条提交的完整信息，例如：

git log -n 10 --format=full

从相关、正常的提交中归纳主导语言与第一行的结构。忽略明显的 merge、revert、自动生成或一次性异常信息。历史样本不足以判断的维度继续使用默认值。

如果用户明确给出完整且必须原样使用的提交信息，直接采用它。plan 或文档中的“建议提交信息”只是语义提示；仍应根据实际 diff、项目规则与历史生成最终信息。

编写标题

标题必须让不了解当前任务、没有阅读 diff 的读者，仅看第一行就能识别主要对象和具体变化。写清“哪个组件或对象发生了什么变化或得到了什么结果”；清晰度优先于刻意缩短标题。

不要把变更类别、实施阶段或宽泛模块名当作具体描述。仅由“增加、接入、更新、优化、调整、完善、重构”等抽象动词加宽泛对象组成的标题不合格，例如“增加运行时核心”“接入提供器”“更新相关说明”“优化启动交互”。应继续说明新增了什么能力、改变了什么行为，或解决了什么问题。

确定标题前逐项自检：

• 是否同时包含可定位的对象和可理解的具体变化或结果；
• 是否足以与同一功能的其他相邻提交区分；
• 是否存在只有阅读 diff 或回忆当前任务才能理解的内部口径；
• 是否宽泛到可以套用在多组明显不同的修改上。

任一项不满足时重写标题。不要为了塞进所有细节而罗列文件或实现步骤；标题容纳不下的重要信息放入 Body。

如果最终采用 Conventional Commits，第一行格式为：

<type>(<optional scope>): <description>

常见 type 包括 feat、fix、docs、refactor、test、build、ci、chore 和 perf。scope 应帮助定位受影响的组件；它不能替代清楚的描述。

例如：

fix(session): 深合并 token 元数据，保留已有统计字段
fix(stream): 保存会话时不再将临时流式消息写入元数据
docs(session): 说明每个会话独立保存模型参数的设计
feat(llama-cpp): 托管单个 llama-server 并持久化运行配置
feat(llama-cpp): 允许还原未保存配置并在启动前选择保存方式

避免仅写成：

fix: 深合并会话 token 元数据
docs: 设计会话独立模型参数
feat: 增加 llama.cpp 托管运行时核心
feat: 优化 llama.cpp 配置还原与启动交互

项目采用其他标题风格时遵循该风格，但清晰度要求不变。

Body 和 Footer

标题风格只约束第一行。完整提交信息可以是：

<title>

<body，除非同时满足下述全部省略条件>

<optional footer>

把 Body 视为提交信息的默认组成部分。Body 用于补充标题容纳不下的重要背景，包括修改动机、此前行为与现在行为的差异、关键结果、重要约束，以及同一提交内需要一起理解的次要变化。不要换一种说法重复标题；使用与标题相同的自然语言。

只有同时满足以下全部条件时才省略 Body：

• 提交只包含一个简单、局部且直接的变化；
• 标题已经完整说明对象以及具体变化或结果；
• 没有需要保留的修改动机、行为对比、重要约束、兼容性影响或次要变化；
• 省略后，未来读者不查看 diff 也不会误解这次提交的目的。

修正单个错字、调整一处显而易见的样式值等修改通常可以省略 Body。涉及多个有意义的行为、多个模块、用户交互变化、架构或数据边界、错误修复原因，或标题只能概括主要结果时，必须编写 Body。Body 可以是一段简洁文字或若干要点，不要为了形式填充无信息内容。

近期历史中普遍没有 Body，不构成继续省略 Body 的理由。历史只用于判断自然语言和标题第一行的结构；是否编写 Body 必须根据当前提交的实际内容单独判断。

Footer 默认省略。Issue 编号以及 Closes、Fixes、Refs、签名或共同作者等外部信息，只能来自用户或项目中明确可验证的信息，不得猜测。

明确的公开向后不兼容变化是例外，可以根据任务、diff、文档或测试自行标记：

• Conventional Commits 标题在类型或 scope 后加 !；
• 当兼容性影响或迁移办法需要进一步说明时，添加 BREAKING CHANGE: <description> footer；
• 证据不足时不要把普通内部改动标记为 breaking change。

测试与验证信息

测试和常规检查通过是提交的正常前提，不是需要写入提交信息的变更内容。

• 标题、Body 和 Footer 都不要添加成功验证记录，包括“全部测试通过”“30 项测试通过”、通过数量或通过率，以及构建、lint、格式检查等通过说明；也不要用 Tests:、Validation: 或“验证：”段落重复这些信息。近期历史中存在此类内容，不构成继续沿用的理由。
• 只有存在测试失败且用户明确要求仍然提交时，才在提交信息中说明失败项、已知原因或影响，以及仍然提交的原因；不知道的内容不推测。这条例外不授权自行忽略失败或绕过 hooks。
• 新增、修改或修复测试本身属于实际变更，可以描述覆盖了什么场景或修复了什么问题；不要附带运行通过的统计。
• 这条规则只约束提交信息，不减少实际测试与检查；需要向用户汇报验证结果时，放在会话回复中。

暂存并提交

提交前再次检查最终 diff，确保生成的信息描述实际要提交的内容，并删除提交信息中的成功验证记录。只暂存已经确认属于当前提交范围的路径，然后创建 commit。

创建 commit 前先写出完整提交信息。若准备省略 Body，逐项确认上面的四个省略条件全部成立；任何一项不成立都必须补写 Body。不要先按历史习惯创建单行提交，再事后判断是否需要正文。

尊重项目 hooks。hook 修改了范围内文件时，重新检查 diff 并根据实际状态继续；hook 失败、产生了范围外修改，或结果含义不清时，报告实际状态。除非用户明确要求，否则不绕过项目检查。

如果常规提交过程出现无法安全解决的歧义，停止并保留真实现场，说明原因与当前 Git 状态。

报告结果

成功后报告：

• commit hash；
• 完整提交信息；
• 有意保留为未提交的文件或改动；若没有则说明 worktree 状态。

失败时说明 commit 是否创建、哪些文件仍为 staged 或 unstaged，以及需要用户决定的事项。