docs: 添加 UE5.7 项目 Git 配置与开发规范

- 优化 .gitignore 为 UE5.7 专用版本（新增 Rider/VSCode/日志/崩溃/系统文件等） - 添加 .gitattributes 配置二进制资产处理与 Git LFS 追踪 - 添加 docs/GIT-GUIDE.md 分支策略与提交规范文档 - 添加 .claude/settings.json 项目级权限配置 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-05-31 01:56:40 +08:00
parent 97f04bb0fa
commit 710cd45a48
4 changed files with 399 additions and 62 deletions
@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(dir:*)",
+      "Bash(git:*)",
+      "mcp__web-reader__webReader",
+      "mcp__zread__get_repo_structure",
+      "mcp__web-search-prime__webSearchPrime",
+      "WebSearch"
+    ]
+  }
+}
@@ -0,0 +1,69 @@
+# UE5 Git Attributes - ChildHood Project
+
+# ==============================
+# 二进制资产（禁止文本合并，避免损坏）
+# ==============================
+*.uasset binary
+*.umap binary
+
+# ==============================
+# Git LFS 大文件追踪
+# ==============================
+*.uasset filter=lfs diff=lfs merge=lfs -text
+*.umap filter=lfs diff=lfs merge=lfs -text
+
+# ==============================
+# 美术资源
+# ==============================
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.tga filter=lfs diff=lfs merge=lfs -text
+*.bmp filter=lfs diff=lfs merge=lfs -text
+*.psd filter=lfs diff=lfs merge=lfs -text
+*.ai filter=lfs diff=lfs merge=lfs -text
+
+# ==============================
+# 3D 模型
+# ==============================
+*.fbx filter=lfs diff=lfs merge=lfs -text
+*.obj filter=lfs diff=lfs merge=lfs -text
+*.gltf filter=lfs diff=lfs merge=lfs -text
+*.glb filter=lfs diff=lfs merge=lfs -text
+
+# ==============================
+# 音频
+# ==============================
+*.wav filter=lfs diff=lfs merge=lfs -text
+*.mp3 filter=lfs diff=lfs merge=lfs -text
+*.ogg filter=lfs diff=lfs merge=lfs -text
+*.flac filter=lfs diff=lfs merge=lfs -text
+
+# ==============================
+# 视频
+# ==============================
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.avi filter=lfs diff=lfs merge=lfs -text
+*.mov filter=lfs diff=lfs merge=lfs -text
+*.wmv filter=lfs diff=lfs merge=lfs -text
+
+# ==============================
+# 文本 / 代码（正常 diff）
+# ==============================
+*.cpp text
+*.h text
+*.cs text
+*.json text
+*.ini text
+*.cfg text
+*.md text
+*.txt text
+*.uproject text
+*.uplugin text
+*.Build.cs text
+*.Target.cs text
+
+# ==============================
+# 自动换行（Windows 开发环境）
+# ==============================
+* text=auto
@@ -1,40 +1,11 @@
-# ---> UnrealEngine
-# Visual Studio 2015 user specific files
+# ==============================
+# ChildHood - UE5.7 Git Ignore
+# ==============================
+
+# ==============================
+# Visual Studio
+# ==============================
 .vs/
-
-# Compiled Object files
-*.slo
-*.lo
-*.o
-*.obj
-
-# Precompiled Headers
-*.gch
-*.pch
-
-# Compiled Dynamic libraries
-*.so
-*.dylib
-*.dll
-
-# Fortran module files
-*.mod
-
-# Compiled Static libraries
-*.lai
-*.la
-*.a
-*.lib
-
-# Executables
-*.exe
-*.out
-*.app
-*.ipa
-
-# These project files can be generated by the engine
-*.xcodeproj
-*.xcworkspace
 *.sln
 *.suo
 *.opensdf
@@ -42,35 +13,87 @@
 *.VC.db
 *.VC.opendb

-# Precompiled Assets
+# ==============================
+# JetBrains Rider
+# ==============================
+.idea/
+*.csproj
+*.DotSettings.user
+
+# ==============================
+# VS Code
+# ==============================
+.vscode/
+
+# ==============================
+# 编译产物
+# ==============================
+*.o
+*.obj
+*.pch
+*.gch
+*.dll
+*.so
+*.dylib
+*.lib
+*.a
+*.pdb
+*.exe
+*.out
+*.ipa
+
+# ==============================
+# UE5 引擎生成目录
+# ==============================
+Binaries/
+Intermediate/
+DerivedDataCache/
+Saved/
+Build/
+Staging/
+Script/
+
+# 插件内的编译产物
+Plugins/**/Binaries/
+Plugins/**/Intermediate/
+
+# 保留 Build 中的图标和 PakBlacklist
+!Build/**/*.ico
+!Build/*/PakBlacklist*.txt
+
+# ==============================
+# UE5 烘焙数据
+# ==============================
+*_BuiltData.uasset
+
+# ==============================
+# 预编译资源源文件
+# ==============================
 SourceArt/**/*.png
 SourceArt/**/*.tga

-# Binary Files
-Binaries/*
-Plugins/**/Binaries/*
+# ==============================
+# 日志与崩溃报告
+# ==============================
+*.log
+CrashReportClient/

-# Builds
-Build/*
+# ==============================
+# 系统文件
+# ==============================
+.DS_Store
+Thumbs.db
+Desktop.ini
+*.lnk

-# Whitelist PakBlacklist-<BuildConfiguration>.txt files
-!Build/*/
-Build/*/**
-!Build/*/PakBlacklist*.txt
-
-# Don't ignore icon files in Build
-!Build/**/*.ico
-
-# Built data for maps
-*_BuiltData.uasset
-
-# Configuration files generated by the Editor
-Saved/*
-
-# Compiled source files for the engine to use
-Intermediate/*
-Plugins/**/Intermediate/*
-
-# Cache files for the editor to use
-DerivedDataCache/*
+# ==============================
+# Git LFS 临时文件
+# ==============================
+*.lfs

+# ==============================
+# 其他
+# ==============================
+*.swp
+*.swo
+*~
@@ -0,0 +1,233 @@
+# ChildHood - Git 规范
+
+> 本文档规定 ChildHood 项目的 Git 分支策略和提交规范。
+> 适用场景：单人独立开发 + UE5.7.4
+
+---
+
+## 一、分支策略
+
+采用**轻量级 Feature Branch 模型**，避免企业级复杂流程，保持 `main` 分支随时可玩。
+
+### 1.1 分支总览
+
+```
+main ──────────────────────────────────────── 稳定主线
+ │
+ ├── feature/player-movement ───→ 合并后删除
+ ├── feature/inventory-system ──→ 合并后删除
+ ├── fix/camera-clipping ───────→ 合并后删除
+ ├── prototype/procedural-gen ──→ 实验完即删
+ └── release/v0.1 ──────────────→ 永久保留
+```
+
+### 1.2 分支类型
+
+| 分支 | 前缀 | 用途 | 合并目标 | 生命周期 |
+|---|---|---|---|---|
+| 主线 | `main` | 稳定可玩版本，每次提交都能编译运行 | — | 永久 |
+| 功能 | `feature/` | 新系统、新功能开发 | `main` | 完成后删除 |
+| 修复 | `fix/` | Bug 修复 | `main` | 完成后删除 |
+| 原型 | `prototype/` | 技术验证、玩法实验 | 合并或丢弃 | 实验完即删 |
+| 发布 | `release/` | 版本发布标记，只从 `main` 切出 | — | 永久保留 |
+
+### 1.3 命名规范
+
+格式：`<类型>/<简短描述>`，全小写，用连字符分隔单词。
+
+```
+# ✅ 好的命名
+feature/player-movement
+feature/inventory-system
+feature/dialogue-tree
+fix/camera-clipping-through-walls
+fix/enemy-ai-stuck-on-navmesh
+prototype/procedural-dungeon
+release/v0.1
+
+# ❌ 不好的命名
+my-new-feature
+fix-bug
+test
+feature/AddPlayerMovement
+```
+
+### 1.4 工作流程
+
+```
+1. 开始新功能
+   git checkout main
+   git pull
+   git checkout -b feature/xxx
+
+2. 开发过程中（随时提交）
+   git add .
+   git commit -m "wip(xxx): 进度描述"
+
+3. 功能完成，测试通过
+   git checkout main
+   git merge feature/xxx
+   git branch -d feature/xxx        # 删除已合并分支
+
+4. 到达里程碑
+   git checkout main
+   git tag -a v0.1.0 -m "第一个可玩原型"
+   git checkout -b release/v0.1
+   git push origin release/v0.1
+```
+
+### 1.5 核心原则
+
+- **`main` 永远可玩**：坏了就留在 feature 分支继续改，不要合并进 main
+- **功能分支粒度**：一个分支做一件事，不要在一个分支里同时做多个系统
+- **原型不怕乱**：`prototype/` 分支随便写，验证完再决定合并还是丢弃
+- **定期清理**：已合并的 feature/fix 分支及时删除，避免分支堆积
+
+---
+
+## 二、提交规范
+
+### 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`（由引擎自动生成）
+
+---
+
+## 三、版本号规范
+
+采用简化语义化版本：
+
+```
+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
+```