ChildHood/docs/common/GIT-GUIDE.md

ChildHood - Git 规范

本文档规定 ChildHood 项目的 Git 分支策略和提交规范。 适用场景：单人独立开发 + UE5.7.4

---

一、分支策略

采用 develop 长期开发分支模型，适合单人开发 + 多 AI Agent 协作场景。所有 agent 在 develop 上工作，迭代结束时通过 PR 合并回 main。

1.1 分支总览

main ──────────── 永远可玩可编译，受保护，禁止直接推送
  │
  │   PR (Gitea)     ← 里程碑/迭代结束时，PM 发起
  │
  └── develop ──── 长期分支，所有 agent 的日常工作分支
       │
       ├── 程序1 提交代码
       ├── 策划 提交文档
       ├── 程序2 提交代码
       └── 迭代就绪 → PR develop→main

1.2 分支类型

分支	用途	生命周期
main	稳定可玩版本，受保护	永久
develop	日常开发，所有 agent 共用	永久
prototype/	技术验证、玩法实验	实验完即删
release/	版本发布标记，只从 main 切出	永久保留

1.3 工作流程

1. 开始工作（agent 自动执行）
   bash .claude/scripts/git-workflow.sh ready

2. 开发并提交
   bash .claude/scripts/git-workflow.sh commit <type> <scope> "描述"

3. 推送到远程
   bash .claude/scripts/git-workflow.sh push

4. 迭代完成，PM 创建 PR
   bash .claude/scripts/git-workflow.sh release "迭代名称"

5. 用户在 Gitea 合并后同步
   bash .claude/scripts/git-workflow.sh post-release

1.4 核心原则

• main 永远可玩：通过 develop → main PR 合并，不直接推送
• develop 是工作台：所有 agent 在 develop 上并行工作
• 不同文件不冲突：各 agent 修改不同文件，可真正并行
• 同一文件需协调：两个 agent 修改同一文件时需顺序执行

---

二、提交规范

2.1 提交消息格式

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

<body>（可选，多行说明）

• subject：不超过 50 个字符，简明扼要
• body：每行不超过 72 个字符，解释"做了什么"和"为什么"
• 使用中文描述，技术术语保留英文

2.2 Type 类型标签

Type	含义	使用场景
feat	新功能	新增系统、机制、玩法
fix	Bug 修复	修复已知问题
art	美术资源	模型、贴图、材质、动画导入
level	关卡/场景	关卡搭建、场景编辑
audio	音效/音乐	BGM、SFX、语音导入
bp	蓝图逻辑	蓝图节点修改、逻辑调整
refactor	重构	不改变功能的结构优化
config	项目配置	引擎设置、插件配置、项目参数
docs	文档	README、设计文档、注释
wip	进行中	未完成的工作进度保存

2.3 Scope 范围标签（可选）

按游戏系统或模块划分：

player      玩家角色
enemy       敌人/AI
combat      战斗系统
ui          UI 界面
camera      摄像机
inventory   背包/物品
dialogue    对话系统
quest       任务系统
save        存档系统
audio       音频系统
animation   动画系统
ai          AI 行为树/状态机
level       关卡
vfx         视觉特效

2.4 提交示例

# 新功能
git commit -m "feat(player): 实现角色跳跃和二段跳"

# 带 body 的详细提交
git commit -m "feat(combat): 实现基础连击系统

- 添加三段连击动画蒙太奇
- 实现动画通知触发伤害判定
- 连击窗口时间可配置"

# Bug 修复
git commit -m "fix(camera): 修复穿墙时摄像机卡顿问题"

# 美术资源
git commit -m "art(environment): 添加草地和树木模型"

# 蓝图修改
git commit -m "bp(enemy): 实现巡逻-追击-攻击状态机"

# 关卡搭建
git commit -m "level(chapter1): 第一章关卡白盒搭建完成"

# 进行中
git commit -m "wip(crafting): 合成系统UI初步框架"

# 项目配置
git commit -m "config: 启用Nanite和Lumen，设置画质预设"

# 重构
git commit -m "refactor(inventory): 拆分背包数据层与UI层"

2.5 提交粒度建议

操作	粒度
蓝图逻辑	按功能点提交，不要一次提交多个系统
关卡编辑	按区域/房间提交
美术资源导入	按类型/角色分批提交
C++ 代码	按逻辑单元提交
材质/贴图	按材质组提交

2.6 UE5 特别注意

• 蓝图与 C++ 分开提交：避免同一提交中混合两者，方便出问题时 revert
• 二进制文件提交：.uasset、.umap 无法 diff，commit message 要写清楚改了什么
• 不要提交以下目录（已被 .gitignore 排除）：
  • Binaries/、Intermediate/、Saved/、DerivedDataCache/
  • .vs/、*.sln（由引擎自动生成）

2.7 临时代码与调查脚本（验证完即删）

排查问题时往往需要写临时验证代码、测试脚本、一次性工具。约定如下（详见 problem-solving skill）：

• 默认不进仓库：临时代码只在本地 / 临时分支跑，验证完删除。
• 若必须 commit（如要在 UE5 里跑）：用 wip 类型，message 标注 [TEMP-INVESTIGATE: issue#XX]，验证后 git revert 或删除该 commit。
• 文件标记：文件名前缀 tmp_ / dev_，文件头注释 // [TEMP-INVESTIGATE: issue#XX] 验证后删除。
• 清理检查：关闭 issue 前执行 grep -r "TEMP-INVESTIGATE" Source/ tools/，确认无残留。
• 保留什么：结论 + 关键代码片段以代码块形式写入 issue 评论，不保留可运行文件。

原则：删除的是 artifact，保留的是 insight。

2.8 fix 提交引用 issue

Bug 修复 / 问题排查类提交，在 body 里引用对应 Gitea issue 号，便于溯源：

git commit -m "fix(camera): 修复穿墙时摄像机卡顿问题

issue #42"

---

三、版本号规范

采用简化语义化版本：

v主版本.次版本.修订号

v0.1.0  ← 第一个可玩原型
v0.2.0  ← 核心玩法成型
v0.3.0  ← 内容填充阶段
...
v1.0.0  ← 正式发布

• 主版本：重大里程碑（原型、Alpha、正式版）
• 次版本：新系统/大功能完成
• 修订号：Bug 修复、小调整

---

四、常用命令速查

# 查看当前状态
git status
git log --oneline --graph --all

# 开始新功能
git checkout -b feature/xxx

# 暂存当前工作（需要临时切分支时）
git stash
git stash pop

# 撤销上次提交（保留修改）
git reset --soft HEAD~1

# 强制同步远程（仅限个人项目）
git fetch origin
git reset --hard origin/main

---

五、远程仓库配置

5.1 服务器信息

项目	值
平台	Gitea（自建）
HTTP 地址	http://192.168.1.22:8418/starmen1265/ChildHood.git
SSH 地址	ssh://sc-gitea@192.168.1.22:2223/starmen1265/ChildHood.git
SSH 端口	2223（非默认 22）
SSH 用户名	sc-gitea（非默认 git）

5.2 SSH 配置

生成密钥（ED25519，推荐）

ssh-keygen -t ed25519 -C "starmen1265@163.com" -f ~/.ssh/id_ed25519 -N ""

⚠️ 优先使用 ED25519 而非 RSA。部分 Git 服务器对 RSA 密钥兼容性较差。

添加公钥到 Gitea

1. 查看公钥：cat ~/.ssh/id_ed25519.pub
2. 复制完整输出
3. 登录 Gitea Web UI → 设置 → SSH/GPG 密钥 → 添加密钥
4. 粘贴公钥内容，保存

设置远程地址

# 查看当前远程地址
git remote get-url origin

# 切换到 SSH（注意用户名是 sc-gitea，端口是 2223）
git remote set-url origin ssh://sc-gitea@192.168.1.22:2223/starmen1265/ChildHood.git

5.3 常见问题排查

❌ Host key verification failed

首次连接服务器需要信任主机密钥：

ssh-keyscan -p 2223 192.168.1.22 >> ~/.ssh/known_hosts

❌ Permission denied (publickey)

排查步骤：

# 1. 测试 SSH 连接，查看详细日志
ssh -vvv -p 2223 sc-gitea@192.168.1.22 "exit"

# 2. 检查密钥是否被 offer
#    在日志中找 "Offering public key" 行
#    确认使用了 id_ed25519 而不是 id_rsa

# 3. 对比本地和服务器的密钥指纹
ssh-keygen -lf ~/.ssh/id_ed25519.pub
#    然后到 Gitea Web UI → 设置 → SSH/GPG 密钥 查看指纹是否一致

常见原因：

原因	解决方法
远程地址用了 git@ 而非 sc-gitea@	改用正确的用户名（见 5.1）
SSH 端口用了默认 22 而非 2223	URL 中指定端口 ssh://sc-gitea@host:2223/...
RSA 密钥被服务器拒绝	重新生成 ED25519 密钥
公钥未添加到 Gitea	Web UI → 设置 → SSH/GPG 密钥 → 添加
公钥格式不完整	确保从 ssh-ed25519 复制到字符串末尾，无截断

❌ Authentication failed（HTTP 方式）

HTTP 方式需要用户名密码认证，建议切换到 SSH：

git remote set-url origin ssh://sc-gitea@192.168.1.22:2223/starmen1265/ChildHood.git

🔧 SSH 使用了错误的密钥

如果服务器同时有 RSA 和 ED25519 密钥，SSH 可能优先尝试 RSA。可以指定密钥：

# 单次指定
git -c core.sshCommand="ssh -i ~/.ssh/id_ed25519 -p 2223" push origin main

# 或全局配置（推荐）
# 编辑 ~/.ssh/config，添加：
Host 192.168.1.22
    Port 2223
    User sc-gitea
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes