aibis-dream/.cursor/commands/split-commit.md

split-commit

将当前未提交改动拆分为多个原子提交。不调用脚本，严格按本文件执行，并与 COMMIT_CONVENTION.md 一致。

0. 先读规范（硬门槛）

执行前先读取并遵守 COMMIT_CONVENTION.md。若下列任一条件不满足，不得提交：

• 提交头必须是 <type>(<scope>): <subject> 或 <type>: <subject>
• type 必须在允许集合：feat|fix|art|audio|scene|yarn|perf|refactor|style|docs|build|chore|test
• scope 仅在单一模块改动时填写；多模块/全局改动可省略
• subject 必须中文、动词开头、不超过 50 字、不加句号
• 一次提交只做一件事（One commit, one purpose）

1. 保护分支（仅当项目有规定时）

仅在项目规则明确指定保护分支时才检测。检查 AGENTS.md、.cursor/rules/ 等是否有「保护分支」「禁止在 X 分支提交」规则。

• 若未找到规则：直接进入第 2 节
• 若找到规则且当前在保护分支，给出选项：
  • [A] 创建 feature 分支后继续拆分（推荐）
  • [B] 转移到新分支后压成单提交，不拆分
  • [C] 取消

执行细则：

• A：git stash push --include-untracked -> git checkout -b <branch> -> git stash pop
• B：同上切新分支后，仅一次 git add + 一次提交（msg.txt）
• C：停止

2. 盘点变更

在仓库根执行：

1. git status
2. git diff --stat
3. git diff
4. git diff --cached

目的：确认全部改动、识别 staged/unstaged、识别同文件多逻辑。

3. 规则化分组（先分组，后提交）

按“意图一致”分组，不按文件数量分组。

必须拆分触发条件

满足任一即必须拆：

• 同一组改动可归属多个 type
• 同一文件中包含多个独立目的（例如功能 + 重构）
• 涉及多个核心 scope 且可独立提交
• 资源替换与代码逻辑混在同一组

分组优先级

1. 先按变更目的区分：功能/修复/重构/测试/文档/资源
2. 再按模块 scope 细分：blockpuzzle、dialog、scene-mgmt 等
3. 同文件多逻辑必须标注 git add -p

4. type/scope 决策规则

type 选择顺序

1. 修复已有缺陷 -> fix
2. 新增或增强行为 -> feat
3. 纯美术资源替换 -> art
4. 纯音频资源替换 -> audio
5. 纯场景/Prefab 布局与参数调整 -> scene
6. 纯 Yarn 文本/分支脚本 -> yarn
7. 其余按规范：perf|refactor|style|docs|build|chore|test

scope 规则

• 单模块改动：使用对应 scope（如 blockpuzzle、fix-system、timeline-kit）
• 跨模块或全局改动：省略 scope（如 chore: ...）

5. Unity 常见改动速查（type/scope 建议）

改动类型	推荐 type	scope 选择
Assets/Scripts/MiniGame/BlockPuzzle/ 逻辑修复	fix	blockpuzzle
Assets/Scripts/MiniGame/BlockPuzzle/ 新交互/新规则	feat	blockpuzzle
动画、贴图、模型、Spine 资源替换	art	对应系统 scope 或省略
音效、BGM、FMOD 资源调整	audio	audio-kit 或省略
.unity 灯光/后处理/镜头参数调整	scene	对应玩法 scope 或省略
Yarn 文本与分支改动	yarn	dialog
仅测试代码改动	test	对应模块 scope

6. 生成拆分方案并展示（必须含依据）

先产出表格，再等待用户确认。每一行必须包含：

• 顺序
• 文件集合
• 变更目的
• type/scope/subject
• 选择依据（为什么是这个 type/scope）
• 暂存方式（git add 或 git add -p）

示例：

顺序	文件	变更目的	提交头	依据	方式
1	Assets/Scripts/MiniGame/BlockPuzzle/Class/ShapeDragger.cs	修复拖拽边界判定	fix(blockpuzzle): 修复方块拖拽越界判定错误	已有行为修复，单模块	git add -p
2	Assets/Prefabs/BlockPuzzle/*.prefab	调整拼图视觉资源	art(blockpuzzle): 更新方块拼图组件预制体表现	纯资源替换	git add

7. 提交消息校验（执行前最后守卫）

每组提交前逐条校验：

1. 格式：<type>(<scope>): <subject> 或 <type>: <subject>
2. type 在允许集合
3. scope 合法或省略合理
4. subject 中文、动词开头、<=50 字、无句号
5. body/footer 仅在需要时添加：
   • 需要解释原因/影响时加 body
   • 关联 issue 或破坏性变更时加 footer

任一不通过：先改消息，不执行 commit。

8. 用户确认后执行

先询问：是否按该拆分执行？[Y 执行 / n 取消 / 提出调整]

用户确认后逐组执行：

1. 按方案 git add 或 git add -p
2. 复查本组暂存：git diff --cached --stat + git diff --cached
3. 使用 msg.txt 提交（见第 10 节）
4. 提交后检查工作区状态：git status

9. 全部完成后的结果校验与回放

全部提交结束后必须输出：

1. git log --oneline -<N>（N=本次新增提交数）
2. 回放清单（每条提交是否符合规范）：
   • type 是否合法
   • scope 是否合理
   • subject 是否满足中文动词开头规则
3. 若发现不合规，明确说明并询问是否修正

10. 中文提交消息写入方式（固定）

PowerShell 5.1 下 git commit -m "中文" 可能乱码。统一使用：

1. 在仓库根写 UTF-8 编码 msg.txt
2. git commit -F msg.txt
3. 删除 msg.txt

11. 工作目录

所有命令必须在仓库根执行。