aibis-dream/COMMIT_CONVENTION.md

Git 提交规范

本文档定义 AIBIS Dream 项目的 Git 提交消息格式、分支命名规范与最佳实践。

---

提交消息格式

采用 Conventional Commits 规范，结构如下：

<type>(<scope>): <subject>

[body]

[footer]

各部分说明

部分	是否必填	说明
type	必填	提交类型，英文小写关键词
scope	可选	影响的模块/系统，用括号包裹
subject	必填	简要描述，中文，不超过 50 字，不加句号
body	可选	详细说明变更原因、背景和影响
footer	可选	关联 issue 编号或标注 BREAKING CHANGE

格式要求

• type 与 scope 之间无空格
• : 后面加一个空格再写 subject
• subject 使用中文，动词开头（添加、修复、优化、重构、更新……）
• body 与 subject 之间空一行
• 每行不超过 72 个字符

---

Type 类型定义

针对游戏开发场景扩展了标准 Conventional Commits 类型：

type	说明	示例
feat	新功能或功能增强	添加线索收藏功能
fix	Bug 修复	修复对话跳过时崩溃的问题
art	美术资源变更（贴图、模型、动画、Spine 等）	替换火山头部模型和贴图
audio	音频资源变更（音效、音乐、FMOD bank 等）	添加酒吧环境音效
scene	场景配置变更（灯光、Timeline、Prefab 布局、Cinemachine 等）	调整 D1S 酒吧场景灯光参数
yarn	Yarn 对话剧本变更	更新佩佩 Day2 对话分支
perf	性能优化	减少语言粒子系统 DrawCall
refactor	代码重构（不改变外部行为）	将状态机逻辑从 Update 迁移到协程
style	代码格式调整（空格、缩进、命名等，不影响逻辑）	统一 MiniGame 目录下命名风格
docs	文档变更	补充 TimelineKit 使用说明
build	构建/打包/CI 相关	更新 WebGL 构建配置
chore	杂项（依赖更新、配置调整、.gitignore 等）	升级 DOTween 到 1.2.7
test	测试相关	添加对象池单元测试

选择 type 的原则

• 一次提交只做一件事，选最能体现主要变更的 type
• 如果同时涉及代码和美术，按主要变更选择（如功能开发附带占位美术 → feat）
• fix 仅用于修复已有 Bug，功能调整用 feat
• 纯资源替换/更新用 art / audio，伴随代码改动的用 feat 或 fix

---

Scope 作用域定义

Scope 标注本次提交影响的模块，帮助团队快速定位变更范围。

核心系统

scope	对应目录	说明
dialog	Scripts/Dialog System/	对话系统（Yarn Spinner 集成）
clue	Scripts/Clue/	线索/证据收集系统
ui	Scripts/UI/	用户界面（Panel、DialogUI、Form）
scene-mgmt	Scripts/SceneManagement/	场景管理与切换
fix-system	Scripts/FixSystem/	修复/拼图交互系统

小游戏

scope	对应目录	说明
huoshan	Scripts/MiniGame/HuoShan/	火山系统（语言粒子、波形、情绪迷宫、分析模式）
blockpuzzle	Scripts/MiniGame/BlockPuzzle/	方块拼图
peipei	Scripts/MiniGame/Peipei/	佩佩角色相关小游戏
gear	Scripts/MiniGame/Gear/	齿轮系统

框架

scope	对应目录	说明
action-kit	Scripts/Framework/ActionKit/	动作序列/命令模式
audio-kit	Scripts/Framework/AudioKit/	音频管理
pool-kit	Scripts/Framework/PoolKit/	对象池
event-kit	Scripts/Framework/EventSystemKit/	事件系统
timeline-kit	Scripts/Framework/TimelineKit/	Timeline 管理
state-machine	Scripts/Framework/StateMachineKit/	状态机
resource-kit	Scripts/Framework/ResourceKit/	资源加载
singleton-kit	Scripts/Framework/SingletonKit/	单例基类

其他

scope	说明
prototype	Web 原型（prototype/、web-prototype/）
config	游戏配置、ProjectSettings
localization	本地化/多语言
save	存档系统

注意：如果变更涉及多个模块或全局性改动，可以省略 scope。

---

分支命名规范

<type>/<简短英文描述>

分支类型

前缀	用途	示例
feature/	新功能开发	feature/block-puzzle-rotation
bugfix/	Bug 修复	bugfix/dialog-skip-crash
art/	美术资源批量更新	art/huoshan-head-replace
hotfix/	紧急线上修复	hotfix/save-data-corruption
release/	版本发布	release/v0.3.0
build/	打包/构建专用	build/webgl-optimization
experiment/	实验性探索	experiment/new-particle-system

分支命名要求

• 使用英文小写 + 短横线（kebab-case）
• 简洁明确，2-5 个单词
• 避免使用中文（防止编码问题和跨平台兼容性问题）
• 避免使用日期作为分支名（如 火山制作8.7）

长期分支

分支	用途
master	稳定发布版本
develop	开发主线，所有 feature 分支的合入目标
playtest	测试/试玩版本

---

完整示例

基本提交

feat(blockpuzzle): 添加方块旋转功能

带 body 的提交

fix(huoshan): 修复语言粒子碰撞后不消失的问题

粒子在碰撞检测回调中未正确归还对象池，
导致粒子数量持续增长引发帧率下降。

带 footer 的提交

feat(dialog): 支持对话中插入表情动画

在 Yarn 指令中新增 <<expression>> 命令，
可在对话气泡旁播放角色表情动画。

Closes #42

美术资源提交

art(huoshan): 替换火山头部高清模型和贴图

场景配置提交

scene(huoshan): 调整 HuoShanFixScene 灯光和后处理参数

多模块/全局变更（省略 scope）

chore: 升级 Unity 到 2022.3.20f1

WIP 提交（临时保存，合并前需 squash）

chore: WIP 火山情绪模块原型开发中

---

对照改进表

以下是项目历史提交的改写示例，便于理解规范的实际效果：

原始提交	规范写法
提交	feat(huoshan): 添加石头维修交互逻辑
bugfix	fix(dialog): 修复对话跳过时崩溃的问题
美术资源替换	art(huoshan): 替换火山头部模型和贴图
细碎的完善	fix(ui): 修复设置面板滑块响应区域偏移
临时提交一下	chore: WIP 火山情绪模块原型
更新	feat(clue): 添加线索收藏功能
石头手感调整	feat(huoshan): 优化石头拖拽手感和物理反馈
问题修复	fix(scene-mgmt): 修复场景切换时音频未停止的问题
短按改长按	feat(ui): 将确认按钮交互从短按改为长按
text adj	yarn(dialog): 调整 D1S 对话文本措辞

---

常见问题

Q: subject 用中文还是英文？

用中文。本项目团队以中文为主要工作语言，中文 subject 可以更准确、更快地传达变更内容。type 和 scope 保持英文以兼容工具链。

Q: 提交粒度怎么把握？

• 一次提交只做一件事（One commit, one purpose）
• 避免在一个提交中混合功能开发、Bug 修复和资源替换
• 如果改动过大，考虑拆分为多个提交

Q: 什么时候可以用 WIP 提交？

• 仅在需要临时保存进度时使用
• 合并到 develop 之前，必须用 git rebase -i 将 WIP 提交 squash 为有意义的提交

Q: Merge Commit 消息怎么写？

使用默认的 merge commit 消息即可（如 Merge branch 'feature/xxx' into 'develop'），无需修改。

Q: Unity 场景文件（.unity）和 Prefab 变更归哪个 type？

• 纯场景配置调整（灯光、摄像机、布局） → scene
• 添加新 Prefab / 新功能对象到场景 → feat
• 替换场景中的美术资源 → art