| name | git-batch-commit |
| homepage | https://github.com/cat-xierluo/legal-skills |
| author | 杨卫薪律师（微信ywxlaw） |
| version | 1.4.2 |
| license | MIT |
| description | 智能 Git 批量提交快捷按钮。触发词："git 提交"、"批量提交"、"拆分提交"、"整理提交"，或用户明确要把已暂存变更拆成多个聚焦 commit 时使用。只负责 commit 拆分和提交信息生成；分支、PR、push、merge、Issue 关闭语义以 git-workflow 为准。提交完成后，若仓库内存在 clawhub-sync 或 subtree-publish 配置，本技能会提示是否将涉及版本更新的技能同步发布到 ClawHub/SkillHub 或推送 subtree 独立仓库——这些发布/推送动作均需用户显式确认。 |
Git 批量提交工具
概述
将混合的修改自动拆分为多个聚焦的、逻辑清晰的提交。而不是创建一个包含"更新各种文件"的大提交，而是创建多个清晰的提交，如"docs: 更新 README"、"chore: 更新依赖"、"license: 更新 license 文件"。
与 git-workflow 的职责边界
git-batch-commit 是提交拆分工具，不是完整 Git 工作流控制器。
| 场景 | 使用哪个 Skill | 说明 |
|---|
| 将已暂存的混合变更拆成多个 commit | git-batch-commit | 本 Skill 的核心职责 |
| 判断是否能 merge / push / close PR | git-workflow | 本 Skill 不做合并门禁 |
PR 合入 main 的 commit 标题是否带 (#N) | git-workflow | 本 Skill 只在生成普通 commit 时保留 Issue/Task 引用 |
直接解决 GitHub Issue 是否应写 Closes #N | git-workflow | 本 Skill 只写 Refs #N，不关闭 Issue |
| 项目本地任务引用 | cross-agent-collab 定任务来源，git-batch-commit 写引用 | 使用 --local-ref "project-task Issue #13" |
当用户只是说“把这些改动提交一下 / 拆分提交”，使用本 Skill；当用户说“合并 PR / 拉 PR 到 main / 推送 / 关闭 issue”，同时遵循 git-workflow。
使用场景
- 用户暂存的文件来自多个类别（文档 + 代码 + 配置）
- 用户希望保持清晰、标准化的提交历史
- 用户提到"批量提交"、"拆分提交"或"整理提交"
- 用户修改了许多文件，希望按逻辑分组
快速开始
方式一：使用交互式脚本
git add file1.py file2.md package.json
python3 skills/git-batch-commit/scripts/interactive_commit.py
python3 skills/git-batch-commit/scripts/interactive_commit.py --yes
python3 skills/git-batch-commit/scripts/interactive_commit.py --dry-run
python3 skills/git-batch-commit/scripts/interactive_commit.py --issue 13
python3 skills/git-batch-commit/scripts/interactive_commit.py --local-ref "project-task Issue #13"
命令行参数：
--yes, -y：跳过交互式确认，自动创建提交--dry-run：仅显示分组建议，不实际创建提交--issue N：关联 GitHub Issue，提交标题追加 (#N)，正文写 Refs #N--local-ref "..."：关联项目本地任务，如 project-task Issue #13，只写 Refs: ...，不会关闭 GitHub Issue
方式二：手动分类
python3 skills/git-batch-commit/scripts/categorize_changes.py
python3 skills/git-batch-commit/scripts/categorize_changes.py --json
提交分类
支持类型：docs, feat, fix, refactor, style, chore, license, config, test
完整定义和检测逻辑详见 references/commit-types.md
技能核心文件的特殊处理
重要规则：SKILL.md 虽然是 Markdown 格式，但它是技能的核心功能文件，不应归类为 docs 类型。
| 文件类型 | 正确分类 | 理由 |
|---|
SKILL.md | feat/style/fix | 技能核心文件，修改它相当于修改功能/代码 |
AGENTS.md | docs | 项目协作规范，属于文档 |
DECISIONS.md | docs | 决策记录，属于文档 |
CHANGELOG.md | docs | 变更日志，属于文档 |
TASKS.md | docs | 任务列表，属于文档 |
判断依据：
- 如果修改的是定义行为/功能的文件（如
SKILL.md、.py、.ts），视为代码变更
- 如果修改的是记录/说明性质的文件（如
README.md、CHANGELOG.md），视为文档变更
同 Skill 内伴随变更合并规则
核心原则：同一 Skill 内的功能变更及其直接关联的配套文件更新，应合并为一条提交，不要按文件类型拆分。
具体规则：
- 当
SKILL.md 有功能变更（feat/fix/style），同 Skill 下的 CHANGELOG.md 更新应合并进同一条提交，不单独拆出 docs 提交
- 同理，版本号变更、配置微调（如删除
.clawhubignore）等配套小改动也一并合并
- 判断标准：这些文件变动是否由同一个功能变更引起？如果是，就是一条提交
- 只有当 CHANGELOG 独立更新（如补录历史版本）且无对应功能变更时，才单独使用
docs 类型
提交信息格式
所有提交遵循格式：
<类型>: <标题>
<正文描述>
重要规则：每个提交必须包含正文（body），不能只有标题。 正文用于补充变更的具体内容和原因，方便后续追溯。
使用英文前缀加中文内容，确保 GitHub 能识别并显示彩色标签。完整示例见 references/conventional-commits.md
Multi-Module/Multi-Skill 仓库规则：
- 描述中应包含模块名称：
docs: course-generator 更新 CHANGELOG
- 如果一次修改涉及多个模块，必须按模块分别提交
- 描述中的模块名称使用原始英文名称，不要翻译
Issue / Task 引用规则：
- 若一组批量提交关联 GitHub Issue，使用
--issue N。每个提交标题会包含 (#N)，正文写 Refs #N。
- 本 Skill 不生成
Closes #N。是否关闭 GitHub Issue 属于 git-workflow 的判断范围。
- 若编号来自项目本地任务源而非 GitHub Issue，使用
--local-ref "project-task Issue #N" 或项目约定的等价引用，不要写 Closes #N。
- PR 合并提交的
(#PR编号) 规则不由本 Skill 决定，遵循 git-workflow。
工作流程
- 暂存文件 - 使用
git add 正常暂存
- 运行交互式脚本 - 查看分类结果
- 审核 - 检查提议的提交分组
- 确认 - 创建提交或取消以调整
- ClawHub 同步检查 - 仅当
skills/clawhub-sync/ 存在时执行，详见 references/clawhub-sync-check.md。不存在则静默跳过
- Subtree 推送检查 - 仅当
skills/subtree-publish/config/subtree-skills.json 存在时执行，详见 references/subtree-push-check.md。不存在则静默跳过
- 完成 - 获得清晰历史的聚焦提交
所需权限与能力边界
本技能核心职责是 Git 提交拆分，但提交完成后可能触发以下可选的后续动作。这些动作均超出"仅提交"的最小职责，且只有在满足触发条件时才会发生，并必须经用户显式确认：
发布到外部平台（ClawHub / SkillHub）
- 仅当仓库内存在
skills/clawhub-sync/，且本次提交涉及 skills/<skill-name>/ 下的版本更新/新增技能、且该技能在 sync-allowlist.yaml 白名单中时，才会提示用户是否同步。
- 每个发布动作前都会向用户确认（
是否将其加入白名单并同步？，选项 y/n/s）；未确认不会执行 clawhub publish / skillhub publish。
- 发布会把技能内容上传到 ClawHub/SkillHub 平台；发布前检查临时目录不含
.env、密钥等敏感文件。
- 用户选择同步后，会修改
skills/clawhub-sync/config/sync-allowlist.yaml 与 sync-records.yaml（仓库状态变更）。
推送 subtree 独立仓库
- 仅当仓库内存在
skills/subtree-publish/config/subtree-skills.json、本次提交涉及已注册的 subtree 子目录、且对应 <name>-standalone remote 已配置时，才会提示是否推送。
- 推送动作需用户确认，不会自动执行。
本地命令执行
- 本技能通过
subprocess 调用 git（暂存/提交/查看 diff）与 clawhub/skillhub（仅用户确认发布后）等外部命令。命令以参数数组拼接，不经过 shell 字符串拼接。
文件访问
- 读取
git diff/git status 输出、skills/*/SKILL.md frontmatter、clawhub-sync/config/sync-allowlist.yaml 与 sync-records.yaml。
- 修改上述 allowlist/records 文件（仅用户确认后）。
若你只希望"纯粹提交、绝不触发任何发布/推送提示"，请先移除或重命名仓库中的 skills/clawhub-sync/ 与 skills/subtree-publish/config/subtree-skills.json，这两个步骤会静默跳过。
资源文件
scripts/
categorize_changes.py - 分析 git diff 并按类别分组文件generate_commit_message.py - 生成约定式提交信息interactive_commit.py - 批量提交的主交互式工具
references/
commit-types.md - 详细的类别定义和检测逻辑conventional-commits.md - 提交信息规范clawhub-sync-check.md - ClawHub 同步检查详细流程（工作流第5步）subtree-push-check.md - Subtree 推送检查详细流程（工作流第6步）
