Git 批量提交工具

概述

将混合的修改自动拆分为多个聚焦的、逻辑清晰的提交。而不是创建一个包含"更新各种文件"的大提交，而是创建多个清晰的提交，如"docs: 更新 README"、"chore: 更新依赖"、"license: 更新 license 文件"。

使用场景

• - 用户暂存的文件来自多个类别（文档 + 代码 + 配置）
• 用户希望保持清晰、标准化的提交历史
• 用户提到"批量提交"、"拆分提交"或"整理提交"
• 用户修改了许多文件，希望按逻辑分组

快速开始

方式一：使用交互式脚本

CODEBLOCK0

脚本将：

1. 1. 分析已暂存的文件
2. 按类别分组
3. 显示提议的提交和提交信息
4. 请求确认（使用 --yes 可跳过）
5. 创建提交

命令行参数：

• - --yes, -y：跳过交互式确认，自动创建提交（适用于 CI/CD 或 AI 助手等非交互式环境）
• INLINECODE3：仅显示分组建议，不实际创建提交

方式二：手动分类

CODEBLOCK1

提交分类

⚠️ 技能核心文件的特殊处理

重要规则：SKILL.md 虽然是 Markdown 格式，但它是技能的核心功能文件，不应归类为 docs 类型。

判断依据：

• - 如果修改的是定义行为/功能的文件（如 SKILL.md、.py、.ts），视为代码变更
• 如果修改的是记录/说明性质的文件（如 README.md、CHANGELOG.md），视为文档变更

提交信息格式

所有提交遵循格式：<类型>: <描述>

使用英文前缀加中文内容，确保 GitHub 能识别并显示彩色标签。

单一项目仓库

对于只包含一个项目的仓库：

CODEBLOCK2

Multi-Module/Multi-Skill 仓库

对于包含多个独立模块或技能的仓库（如 skills 仓库），描述中应包含模块名称以确保聚焦：

CODEBLOCK3

重要规则：

• - 如果一次修改涉及多个模块，必须按模块分别提交
• 每个提交只包含一个模块的变更
• 描述中的模块名称使用原始英文名称，不要翻译

工作流程

1. 1. 暂存文件 - 使用 git add 正常暂存
2. 运行交互式脚本 - 查看分类结果
3. 审核 - 检查提议的提交分组
4. 确认 - 创建提交或取消以调整
5. ClawHub 同步检查 - 检查本次提交是否需要同步到 ClawHub（详见下方「提交后检查：ClawHub 同步」章节）

1. 6. 完成 - 获得清晰历史的聚焦提交

实现说明

分类使用两遍扫描方法：

1. 1. 文件模式匹配 - 文件按路径和扩展名模式分类
2. Diff 内容分析 - 对于源代码，分析实际的 git diff 以区分功能、修复、重构和风格变更

检测规则：

• - Fix: diff 中包含 "fix"、"bug"、"error" 等关键字
• Feat: diff 中包含 "add"、"new"、"implement" 等关键字且添加多于删除
• Refactor: 删除多于添加
• Style: 添加和删除平衡（源文件默认）

资源文件

scripts/

• - categorize_changes.py - 分析 git diff 并按类别分组文件
• generate_commit_message.py - 生成约定式提交信息
• interactive_commit.py - 批量提交的主交互式工具

references/

• - commit-types.md - 详细的类别定义和检测逻辑
• conventional-commits.md - 提交信息规范

使用示例

CODEBLOCK4

工作流第5步参考：ClawHub 同步检查

本节是工作流第5步的详细参考。核心规则：仅当项目目录下存在 skills/clawhub-sync/ 时才执行——不存在则静默跳过，不输出任何提示。

完成 Git 提交后，执行以下检查。

触发条件

完成提交后，依次执行以下三类检测。任一命中即提示用户是否同步。

检测 A：已有技能版本升级

全部满足时触发：

1. 1. 本地存在 clawhub-sync 技能

1. 2. 提交涉及 skills 目录

1. 3. 版本号有更新

1. 4. 在白名单中

检测 B：新增 MIT 技能首次同步

当提交新增了 skills/<skill-name>/ 目录时触发：

1. 1. 识别新增技能：检查提交中是否有 skills/<skill-name>/SKILL.md 为新文件（untracked → committed）

1. 2. 许可证为 MIT：读取新技能 SKILL.md frontmatter 中的 license 字段，判断是否为 MIT

1. 3. 未在白名单中：sync-allowlist.yaml 中无此 skill 的条目（无论是否被注释）

1. 4. 未在同步记录中：sync-records.yaml 中无此 skill 的条目

满足全部条件时，向用户提示：
CODEBLOCK5

用户选择 y 时：

• - 在 sync-allowlist.yaml 中添加该 skill（添加到对应分类区域）
• 执行 prepare-publish → publish → 更新 sync-records 流程
• 注意：发布前检查临时目录，确保不含 .env、密钥等敏感文件

用户选择 s 时：

• - 仅在 sync-allowlist.yaml 中添加该 skill（被注释），下次版本更新时再同步

检测 C：白名单新增但未同步

当白名单中有未被注释的 skill，但 sync-records.yaml 中没有对应记录时：

1. 1. 遍历 sync-allowlist.yaml 中未被注释的 skill
2. 检查 sync-records.yaml 中是否有该 skill 的记录
3. 如果白名单有但记录中没有，且 SKILL.md 存在，提示用户执行首次同步

执行步骤

对于每个需要同步的 skill，按照 clawhub-sync 的"单个 Skill 同步工作流"执行：

步骤 1：准备发布目录
CODEBLOCK6

步骤 2：执行发布（使用 publish 命令）
CODEBLOCK7

⚠️ 必须指定 --slug 和 --name

• - 临时目录名可能包含前缀，使用 --slug 确保正确的 skill 标识符
• 使用 --name 确保 ClawHub 上显示正确的名称

为什么用 publish 而不是 sync？

• - clawhub sync 会扫描所有目录的 skills，可能遇到 slug 冲突
• INLINECODE76 只发布指定路径的单个 skill，更精确

步骤 3：更新同步记录

更新 skills/clawhub-sync/config/sync-records.yaml：

• - 更新 version 为新版本号
• 更新 last_sync 为当前时间
• 更新 git_hash 为当前 commit hash
• 更新 status 为 INLINECODE82
• 添加 url 和 publish_id（从命令输出获取）

失败处理

• - 同步失败时仅显示警告信息
• 不影响 Git 提交结果
• 继续处理其他 skills

版本比较逻辑

CODEBLOCK8

版本号按语义化版本规则比较（major.minor.patch）。

示例场景