Commit Craft 是一个面向 Git 提交整理的技能，主要解决智能体或开发者留下的大型混合 diff 难以审查、回滚和二分定位的问题。它把一次混杂的改动拆解为一系列逻辑单一的提交，每个提交可独立构建、不包含密钥，并说明改动原因。
用途 当工作区同时包含功能、格式化、依赖升级和意外文件（如 .env）时，直接作为一个提交会失去可审查性。Commit Craft 的目标是规划出可审查的提交序列，并在提交前拦截敏感信息。
主要能力 技能包含三个仅使用标准库的 Python 脚本，它们以只读方式调用 git，不联网，也不会执行暂存、提交或推送。
-
commit_planner.py：比较工作区与 HEAD（包含未跟踪文件），对文件进行分组和排序，输出暂存命令。分组策略包括：清单文件与锁文件、纯移动、仅空白改动、各模块改动与其测试、文档与 CI。它会扣留 .env、密钥和 tfstate（退出码 4），标记混合了格式化与真实改动的文件，并标记调用方导入修改位于其他分组的移动操作，因为那样的提交无法构建。它不会替用户决定 feat 还是 fix，需要根据改动实际作用判断。
-
secret_gate.py：仅扫描已暂存内容的新增行，检测提供商形态的令牌、赋值给 key/secret/token/password 的高熵值、敏感文件和冲突标记。输出会做脱敏处理。误报可通过 .commit-craft-allow 按指纹或路径并附原因豁免。
-
message_linter.py：检查单条提交信息（-m 或 --message-file）或一个提交序列（--range）。它会阻止模糊主题（如 "fix"、"update"）、超过 72 字符的主题、主题后缺少空行，以及改动超过 40 行或 4 个文件却没有正文的情况。仅当仓库已使用 Conventional Commits 时才强制该规范。在推送前检查时，还会阻止 fixup!/squash!/WIP 提交，并对重复提交和 revert 对发出警告。
使用方式 工作流分为四步：
- 规划：运行 python scripts/commit_planner.py，查看分组、顺序和暂存方式。
- 逐组暂存并检查：使用 git add -- <文件> 或 git add -p 暂存某一组，然后运行 python scripts/secret_gate.py 进行门禁检查。
- 编写并检查提交信息：运行 python scripts/message_linter.py -m "<message>" --staged，通过后执行 git commit。
- 推送前检查：运行 python scripts/message_linter.py --range @{upstream}..HEAD 检查整个序列，并用 git rebase -x "<test command>" @{upstream} 验证每个提交都能构建。
三个脚本均支持 --help、--sample 和 --output json。
适用场景 适用于提交混合改动、推送前整理提交历史、需要将工作拆分为多个提交或编写提交信息的场景。也适合在提交和推送环节自动运行门禁检查，assets/hooks/ 中提供了 pre-commit、commit-msg 和 pre-push 钩子。
限制与硬性规则
- 禁止在混合工作区使用 git add -A 或 git add .，必须按名称或按块暂存。
- 门禁被阻止意味着不能提交。应移除敏感值并在运行时加载，禁止使用 --no-verify，禁止豁免真实密钥。
- 已推送的密钥应首先轮换，仅在新提交中删除仍会留在历史中。
- 每个提交都应能构建，测试随改动一起提交，移动操作应包含调用方修改。
- 提交正文说明原因，diff 本身已说明做了什么。
- 只重写未推送的历史，对共享提交进行 rebase 或 amend 由用户决定。
参考资料包括 references/commit_series_design.md、references/message_discipline.md、references/secret_response.md，以及 assets/hooks/、assets/commit-craft-allow.example 和 assets/series_checklist.md。