starmen1265
b2820ec024
- 新增 problem-solving skill：固化「问题分析→工作记录→知识沉淀」9步流程与3模板 - 新建 docs/knowledge/ 经验知识库（README/INDEX/临时方案登记/坑-UE5引擎含2条迁移示例） - GIT-GUIDE 补 §2.7 临时代码 [TEMP-INVESTIGATE] 约定、§2.8 fix 提交引用 issue - CLAUDE.md 项目管理段加问题管理引用 - 配套 Gitea 标签 type:bug / type:investigation（后台已建）
335 lines
9.3 KiB
Markdown
335 lines
9.3 KiB
Markdown
# 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 提交示例
|
||
|
||
```bash
|
||
# 新功能
|
||
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 号，便于溯源：
|
||
|
||
```bash
|
||
git commit -m "fix(camera): 修复穿墙时摄像机卡顿问题
|
||
|
||
issue #42"
|
||
```
|
||
|
||
---
|
||
|
||
## 三、版本号规范
|
||
|
||
采用简化语义化版本：
|
||
|
||
```
|
||
v主版本.次版本.修订号
|
||
|
||
v0.1.0 ← 第一个可玩原型
|
||
v0.2.0 ← 核心玩法成型
|
||
v0.3.0 ← 内容填充阶段
|
||
...
|
||
v1.0.0 ← 正式发布
|
||
```
|
||
|
||
- **主版本**：重大里程碑（原型、Alpha、正式版）
|
||
- **次版本**：新系统/大功能完成
|
||
- **修订号**：Bug 修复、小调整
|
||
|
||
---
|
||
|
||
## 四、常用命令速查
|
||
|
||
```bash
|
||
# 查看当前状态
|
||
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，推荐）
|
||
|
||
```bash
|
||
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. 粘贴公钥内容，保存
|
||
|
||
#### 设置远程地址
|
||
|
||
```bash
|
||
# 查看当前远程地址
|
||
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`
|
||
|
||
首次连接服务器需要信任主机密钥：
|
||
|
||
```bash
|
||
ssh-keyscan -p 2223 192.168.1.22 >> ~/.ssh/known_hosts
|
||
```
|
||
|
||
#### ❌ `Permission denied (publickey)`
|
||
|
||
排查步骤：
|
||
|
||
```bash
|
||
# 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：
|
||
|
||
```bash
|
||
git remote set-url origin ssh://sc-gitea@192.168.1.22:2223/starmen1265/ChildHood.git
|
||
```
|
||
|
||
#### 🔧 SSH 使用了错误的密钥
|
||
|
||
如果服务器同时有 RSA 和 ED25519 密钥，SSH 可能优先尝试 RSA。可以指定密钥：
|
||
|
||
```bash
|
||
# 单次指定
|
||
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
|
||
```
|