docs: 完善 split-commit 命令使用说明

.cursor/commands/split-commit.md

@@ -2,8 +2,15 @@
 
 将当前未提交改动拆分为多个原子提交。**不调用脚本**，严格按本文件执行，并与 `COMMIT_CONVENTION.md` 一致。
 
-## 0. 先读规范（硬门槛）
+## 0. 前置检查
 
+### 0.1 清理临时文件
+若存在上次残留的 `msg.txt`，先删除：
+```bash
+rm -f msg.txt
+```
+
+### 0.2 读取规范（硬门槛）
 执行前先读取并遵守 `COMMIT_CONVENTION.md`。若下列任一条件不满足，**不得提交**：
 
 - 提交头必须是 `<type>(<scope>): <subject>` 或 `<type>: <subject>`
@@ -12,38 +19,41 @@
 - `subject` 必须中文、动词开头、不超过 50 字、不加句号
 - 一次提交只做一件事（One commit, one purpose）
 
-## 1. 保护分支（仅当项目有规定时）
+## 1. 保护分支检查
 
-仅在项目规则明确指定保护分支时才检测。检查 `AGENTS.md`、`.cursor/rules/` 等是否有「保护分支」「禁止在 X 分支提交」规则。
+检测当前是否在保护分支。保护分支列表按以下优先级获取：
+1. 检查 `AGENTS.md`、`.cursor/rules/` 中是否有「保护分支」规则
+2. 检查 `.git/config` 中 `branch.protected` 配置
+3. 默认保护分支：`master`, `main`, `develop`
 
-- 若未找到规则：直接进入第 2 节
-- 若找到规则且当前在保护分支，给出选项：
-  - [A] 创建 feature 分支后继续拆分（推荐）
-  - [B] 转移到新分支后压成单提交，不拆分
-  - [C] 取消
+- 若当前不在保护分支：直接进入第 2 节
+- 若在保护分支，给出选项：
+  - **[A]** 创建 feature 分支后继续拆分（推荐）
+  - **[B]** 转移到新分支后压成单提交，不拆分
+  - **[C]** 取消
 
 执行细则：
 
-- A：`git stash push --include-untracked` -> `git checkout -b <branch>` -> `git stash pop`
-- B：同上切新分支后，仅一次 `git add` + 一次提交（`msg.txt`）
-- C：停止
+- **A**：`git stash push --include-untracked` -> `git checkout -b <branch>` -> `git stash pop`
+- **B**：同上切新分支后，仅一次 `git add -A` + 一次提交（使用 `msg.txt`）
+- **C**：停止，恢复原始状态
 
 ## 2. 盘点变更
 
 在仓库根执行：
 
-1. `git status`
-2. `git diff --stat`
-3. `git diff`
-4. `git diff --cached`
+1. `git status` - 确认整体状态
+2. `git diff --stat` - 查看改动文件统计
+3. `git diff` - 查看详细改动内容
+4. `git diff --cached` - 查看已暂存的改动
 
 目的：确认全部改动、识别 staged/unstaged、识别同文件多逻辑。
 
 ## 3. 规则化分组（先分组，后提交）
 
-按“意图一致”分组，不按文件数量分组。
+按"意图一致"分组，不按文件数量分组。
 
-### 必须拆分触发条件
+### 3.1 必须拆分触发条件
 
 满足任一即必须拆：
 
@@ -52,15 +62,21 @@
 - 涉及多个核心 scope 且可独立提交
 - 资源替换与代码逻辑混在同一组
 
-### 分组优先级
+### 3.2 分组优先级
 
 1. 先按变更目的区分：功能/修复/重构/测试/文档/资源
 2. 再按模块 scope 细分：`blockpuzzle`、`dialog`、`scene-mgmt` 等
 3. 同文件多逻辑必须标注 `git add -p`
 
+### 3.3 最小拆分原则
+
+避免过度拆分导致提交历史碎片化。以下情况**可以合并**：
+- 同一功能的多文件改动（如新增脚本 + 对应 Prefab）
+- 同一模块的多个 Bug 修复（如修复同一脚本的 3 个边界问题）
+
 ## 4. type/scope 决策规则
 
-### type 选择顺序
+### 4.1 type 选择顺序
 
 1. 修复已有缺陷 -> `fix`
 2. 新增或增强行为 -> `feat`
@@ -70,7 +86,7 @@
 6. 纯 Yarn 文本/分支脚本 -> `yarn`
 7. 其余按规范：`perf|refactor|style|docs|build|chore|test`
 
-### scope 规则
+### 4.2 scope 规则
 
 - 单模块改动：使用对应 scope（如 `blockpuzzle`、`fix-system`、`timeline-kit`）
 - 跨模块或全局改动：省略 scope（如 `chore: ...`）
@@ -130,6 +146,14 @@
 3. 使用 `msg.txt` 提交（见第 10 节）
 4. 提交后检查工作区状态：`git status`
 
+### 失败处理机制
+
+- **若 `git add -p` 中用户跳过关键 hunk**：暂停执行，提示剩余改动如何处理
+- **若提交失败（如 pre-commit hook 拒绝）**：
+  - 显示失败原因
+  - 询问：[R] 重试 / [S] 跳过本组 / [A] 中止全部
+  - 若选择中止，确保工作区恢复到执行前状态
+
 ## 9. 全部完成后的结果校验与回放
 
 全部提交结束后必须输出：
@@ -139,16 +163,63 @@
    - type 是否合法
    - scope 是否合理
    - subject 是否满足中文动词开头规则
-3. 若发现不合规，明确说明并询问是否修正
+3. 若发现不合规，明确说明并询问是否修正（`git commit --amend` 或 `git rebase -i`）
 
 ## 10. 中文提交消息写入方式（固定）
 
 PowerShell 5.1 下 `git commit -m "中文"` 可能乱码。统一使用：
 
-1. 在仓库根写 UTF-8 编码 `msg.txt`
-2. `git commit -F msg.txt`
-3. 删除 `msg.txt`
+```bash
+# 1. 在仓库根写 UTF-8 编码 msg.txt
+echo "feat(blockpuzzle): 添加方块旋转功能" > msg.txt
 
-## 11. 工作目录
+# 2. 使用文件提交
+git commit -F msg.txt
 
-所有命令必须在仓库根执行。
+# 3. 删除临时文件
+rm -f msg.txt
+```
+
+## 11. 关于 Pre-commit Hooks
+
+若项目配置了 pre-commit hook（如 husky、lint-staged）：
+
+- 每次提交都会触发 hook 检查
+- 若 hook 执行较慢（如运行全量测试），拆分提交会变慢
+- 如需跳过 hook（**不推荐，仅在紧急修复时**）：`git commit -F msg.txt --no-verify`
+- **警告**：跳过 hook 可能引入未检查的问题，后续 CI 可能失败
+
+## 12. 工作目录
+
+所有命令必须在仓库根执行。
+
+## 13. 快速参考：常见场景处理
+
+### 场景 A：同文件包含功能和重构
+```bash
+# 先提交功能改动
+git add -p <file>  # 只选择功能相关的 hunk
+git commit -F msg.txt  # feat: ...
+
+# 再提交重构
+git add -p <file>  # 选择重构相关的 hunk
+git commit -F msg.txt  # refactor: ...
+```
+
+### 场景 B：误操作后的恢复
+```bash
+# 若某次提交后发现错误，撤销最后一次提交但保留改动
+git reset --soft HEAD~1
+# 然后重新分组提交
+
+# 若需要完全放弃本次拆分的所有提交（谨慎使用）
+git reset --hard ORIG_HEAD
+```
+
+### 场景 C：中途取消
+```bash
+# 若在第 8 步中途需要取消
+git reset HEAD  # 取消暂存
+git checkout -- .  # 恢复工作区（会丢失未提交改动，谨慎）
+rm -f msg.txt  # 清理临时文件
+```