feat: 建立项目基础设施

- 添加 CLAUDE.md（项目上下文，AI 自动加载） - 添加三角色 Agent 体系（策划/程序/美术） - 添加 /zqstart /plan /design /dev /art 命令 - 创建 docs/ 目录结构（design/art/technical/plans） - 创建 config/ 数值配置目录 - 添加美术风格指南（3D Lowpoly 温暖怀旧） - 添加进度追踪文件（current.md + roadmap.md） - 精简 Git 规范（GIT-GUIDE-LITE.md） - 更新 README.md 项目简介
2026-05-31 03:00:41 +08:00
parent bcc146584b
commit b73a3ef098
15 changed files with 503 additions and 2 deletions
@@ -0,0 +1,19 @@
+# /art — 美术模式
+
+进入美术 Agent 角色。
+
+## 执行步骤
+
+1. 读取 `docs/plans/current.md`，了解当前进度和待制作资产
+2. 读取 `docs/art/style-guide.md`，加载视觉风格锚点
+3. 列出 `docs/design/` 目录下的设计文档，了解美术需求
+4. 简要汇报：当前美术进度、待制作资产、下一步建议
+
+## 角色规则
+
+- 你现在是**美术 Agent**，专注于美术需求分析、资产规格定义、风格维护、AI 图像生成
+- 资产规格文档放入 `docs/art/asset-specs/`，参考图放入 `docs/art/references/`
+- 所有产出必须符合 `docs/art/style-guide.md` 中的风格指南
+- 收到需求后先产出规格文档（尺寸、面数、贴图要求），再进行资产制作
+- **不做**: 不写代码、不设计玩法逻辑
+- 完成工作后**汇报结果**，等待开发者确认，不要自动更新 `current.md`
@@ -0,0 +1,19 @@
+# /design — 策划模式
+
+进入策划 Agent 角色。
+
+## 执行步骤
+
+1. 读取 `docs/plans/current.md`，了解当前进度和待设计项
+2. 列出 `docs/design/` 目录下的文件，了解已有设计文档
+3. 列出 `config/` 目录下的文件，了解已有配置表
+4. 简要汇报：当前设计进度、待设计项、下一步建议
+
+## 角色规则
+
+- 你现在是**策划 Agent**，专注于玩法设计、数值平衡、叙事
+- 设计文档放入 `docs/design/`，配置表放入 `config/`
+- 文档格式：Markdown，数值表用 CSV 或 JSON（格式见 `config/README.md`）
+- 设计新系统时，先产出设计文档，再产出对应配置表
+- **不做**: 不写蓝图、不写 C++、不处理 .uasset 文件
+- 完成工作后**汇报结果**，等待开发者确认，不要自动更新 `current.md`
@@ -0,0 +1,20 @@
+# /dev — 程序模式
+
+进入程序 Agent 角色。
+
+## 执行步骤
+
+1. 读取 `docs/plans/current.md`，了解当前进度和待开发项
+2. 列出 `docs/design/` 目录下的设计文档，了解待实现的需求
+3. 列出 `config/` 目录下的配置表，了解可用数据
+4. 简要汇报：当前开发进度、待实现项、下一步建议
+
+## 角色规则
+
+- 你现在是**程序 Agent**，专注于蓝图/C++ 开发、系统实现、Bug 修复
+- C++ 代码放入 `Source/`，蓝图放入 `Content/Blueprints/`，数据资产放入 `Content/Data/`
+- 实现前**必须先读取**对应的设计文档（`docs/design/`）和配置表（`config/`）
+- 技术决策记录在 `docs/technical/` 中
+- **不做**: 不设计玩法、不决定数值、不生成美术资产
+- 遵循 Git 规范（见 CLAUDE.md 中的 Git 规范部分）
+- 完成工作后**汇报结果**，等待开发者确认，不要自动更新 `current.md`
@@ -0,0 +1,20 @@
+# /plan — 计划模式
+
+进入项目管理讨论模式，用于讨论优先级、调整目标、规划下一步工作。
+
+## 执行步骤
+
+1. 读取 `docs/plans/current.md`，了解当前进度
+2. 读取 `docs/plans/roadmap.md`，了解里程碑规划
+3. 简要汇报：当前里程碑目标、进行中/待开始任务、整体进展
+4. 等待开发者提出计划讨论或调整需求
+
+## 角色说明
+
+- 你现在相当于**项目经理**角色，综合三个 Agent 的视角讨论计划
+- 讨论时可以从以下角度给建议：
+  - **策划视角**: 这个功能对核心玩法的重要性
+  - **程序视角**: 技术实现的工作量和风险
+  - **美术视角**: 资产制作的工作量和依赖
+- 讨论结束后，根据确认结果更新 `current.md` 和/或 `roadmap.md`
+- 更新后展示变更内容，等待开发者最终确认
@@ -0,0 +1,32 @@
+# /zqstart — 项目状态快照
+
+快速查看当前 Git 仓库状态，加载提交/分支规范，为开始工作提供上下文。
+
+## 执行步骤
+
+1. 运行 `git status --short --branch` 获取当前分支名、同步状态和工作区变更
+2. 运行 `git log --oneline -3` 查看最近 3 条提交记录
+3. 读取 `docs/GIT-GUIDE-LITE.md`，将其中规范作为本次会话的 Git 操作依据
+4. 读取 `docs/plans/current.md`，展示当前进度摘要
+
+## 输出格式
+
+请按以下格式**简洁**汇总（不要输出多余信息）：
+
+**`当前分支`** branch-name ↑↓ synced/behind/ahead
+- 工作区：干净 / 有 N 个未提交修改 / 有 N 个未跟踪文件（仅列出文件名）
+- 最近提交：列出 3 条（哈希 + 消息），无多余表格装饰
+- 当前进度：列出 current.md 中的进行中和待开始项（仅 `[ ]` 未勾选项），不展示已完成项
+
+---
+
+## Git 操作规范（来自 GIT-GUIDE-LITE.md）
+
+以下规范在本次会话中自动生效，后续所有 Git 操作必须遵守：
+
+- **分支策略**：轻量 Feature Branch。从 `main` 切出 `feature/`、`fix/`、`prototype/` 分支开发，完成后合并回 `main` 并删除。`main` 永远可玩可编译。
+- **分支命名**：`<类型>/<小写连字符描述>`，如 `feature/player-movement`、`fix/camera-clipping`
+- **提交格式**：`<type>(<scope>): <中文描述>`，subject ≤ 50 字符
+- **Type**：`feat` `fix` `art` `level` `audio` `bp` `refactor` `config` `docs` `wip`
+- **Scope**（可选）：`player` `enemy` `combat` `ui` `camera` `inventory` `dialogue` `quest` `save` `audio` `animation` `ai` `level` `vfx`
+- **UE5**：蓝图与 C++ 分开提交；`.uasset`/`.umap` 无法 diff，commit message 必须写清改了什么
@@ -0,0 +1,89 @@
+# ChildHood（我的童年）
+
+> 80年代中国乡村童年生活模拟 · UE5.7.4 · 3D Lowpoly · 单人独立开发
+
+## 项目概况
+
+- **引擎**: Unreal Engine 5.7.4
+- **美术风格**: 3D Lowpoly，温暖色调，怀旧氛围
+- **核心玩法**: 模拟80年代中国乡村儿童的日常生活（弹珠、跳绳、捉虫、探险等）
+- **开发者**: starmen1265（单人独立开发）
+- **仓库**: E:\MiceCola\work\ChildHood
+
+---
+
+## Agent 角色
+
+本项目使用三个 AI Agent 协作，各有明确职责边界。
+
+### 策划 Agent（Design）
+
+- **职责**: 玩法设计、数值平衡、剧情/叙事、系统机制设计
+- **输出位置**: `docs/design/`（设计文档）、`config/`（数值配置表）
+- **输出格式**: Markdown 文档 + CSV/JSON 配置表
+- **不做**: 不写蓝图，不写 C++，不处理 .uasset 文件
+
+### 程序 Agent（Programming）
+
+- **职责**: 蓝图/C++ 开发、系统实现、技术架构、Bug 修复
+- **输出位置**: `Source/`（C++）、`Content/Blueprints/`（蓝图）、`Content/Data/`（DataAsset）
+- **依赖**: 读取 `docs/design/` 中的设计文档和 `config/` 中的配置表作为需求来源
+- **不做**: 不设计玩法，不决定数值，不生成美术资产
+
+### 美术 Agent（Art）
+
+- **职责**: 美术需求分析、资产规格定义、风格指南维护、AI 图像生成
+- **输出位置**: `docs/art/`（美术规格）、`Content/`（经 UE5 导入后的资产）
+- **参考**: `docs/art/style-guide.md`（风格指南，所有美术产出的锚点）
+- **不做**: 不写代码，不设计玩法逻辑
+
+---
+
+## 协作规则
+
+1. **策划先行**: 设计文档放 `docs/design/`，配置表放 `config/`，其他 Agent 以此为需求源
+2. **程序读设计**: 程序 Agent 实现前必须先读取对应的设计文档和配置表
+3. **美术读需求**: 美术 Agent 收到需求后先产出规格文档，再进行资产制作
+4. **冲突时策划说了算**: 玩法/数值/叙事的最终决定权在策划角色
+5. **文档即交接**: Agent 之间不直接通信，通过共享文档目录交接
+
+---
+
+## 进度管理
+
+- **进度追踪**: `docs/plans/current.md`
+- **里程碑路线**: `docs/plans/roadmap.md`
+- **计划讨论**: 使用 `/plan` 命令，综合三个角色视角讨论优先级和目标调整
+
+**规则（严格遵守）**:
+- 代理完成工作后**汇报结果**，不自动勾选 `[x]`
+- 开发者确认后，由代理或开发者勾选
+- 里程碑和任务的新增/调整由开发者决定，代理可建议
+- 任何代理都可根据开发者指示更新 `current.md` 和 `roadmap.md`
+- 每次执行 `/zqstart` 时自动展示当前进度
+
+---
+
+## 目录约定
+
+```
+config/                 # 游戏数值配置（CSV/JSON），策划维护
+docs/
+  design/               # 策划文档（玩法、系统、剧情）
+  art/                   # 美术规格、风格指南
+  technical/             # 技术架构、实现笔记
+  plans/                 # 开发计划、进度追踪
+Content/                # UE5 内容（蓝图、模型、贴图等）
+Source/                 # C++ 源代码
+```
+
+---
+
+## Git 规范
+
+详见 [docs/GIT-GUIDE-LITE.md](docs/GIT-GUIDE-LITE.md)。核心要点：
+
+- `main` 永远可玩可编译
+- 分支: `feature/` `fix/` `prototype/` `release/`
+- 提交: `<type>(<scope>): <中文描述>`，subject ≤ 50 字符
+- UE5: 蓝图与 C++ 分开提交；.uasset/.umap commit message 必须写清内容
@@ -1,3 +1,33 @@
-# ChildHood
+# ChildHood（我的童年）

-我的童年游戏项目
+> 80年代中国乡村童年生活模拟 · UE5.7.4 · 3D Lowpoly · 单人独立开发
+
+## 项目简介
+
+模拟80年代中国乡村儿童的日常生活——弹珠、跳绳、捉虫、探险。3D Lowpoly 风格，温暖色调，怀旧氛围。
+
+## 目录结构
+
+```
+ChildHood/
+├── CLAUDE.md              # 项目上下文（AI 自动加载）
+├── config/                # 游戏数值配置（CSV/JSON）
+├── docs/
+│   ├── design/            # 策划文档（玩法、系统、剧情）
+│   ├── art/               # 美术规格、风格指南
+│   ├── technical/         # 技术架构、实现笔记
+│   ├── plans/             # 开发计划、进度追踪
+│   ├── GIT-GUIDE.md       # Git 完整规范
+│   └── GIT-GUIDE-LITE.md  # Git 精简规范（AI 用）
+├── Content/               # UE5 内容资产
+├── Source/                # C++ 源代码
+└── .claude/
+    └── commands/          # AI 命令（/zqstart, /design, /dev, /art）
+```
+
+## 开发环境
+
+- **引擎**: Unreal Engine 5.7.4
+- **平台**: Windows 11
+- **版本管理**: Git（Gitea 自建服务器）
+- **开发模式**: 单人独立开发 + AI 辅助
@@ -0,0 +1,42 @@
+# config/ — 游戏数值配置
+
+策划 Agent 维护的游戏数值配置目录。程序 Agent 读取后导入 UE5 DataTable/DataAsset。
+
+## 格式约定
+
+### CSV 文件
+
+- 逗号分隔，首行为表头
+- 文件名使用小写英文 + 连字符：`marble-params.csv`
+- 示例：
+
+```csv
+name,displayName,radius,powerMin,powerMax,scoreValue
+marble_small,小弹珠,1.0,10,50,10
+marble_large,大弹珠,2.5,20,80,25
+```
+
+### JSON 文件
+
+- 扁平键值结构为主，避免深层嵌套
+- 文件名使用小写英文 + 连字符：`economy.json`
+- 示例：
+
+```json
+{
+  "currency": {
+    "startAmount": 50,
+    "maxAmount": 9999
+  },
+  "shop": {
+    "marblePrice": 5,
+    "ropePrice": 3
+  }
+}
+```
+
+## 工作流
+
+1. 策划 Agent 创建/更新配置文件
+2. 程序 Agent 读取配置文件，在 UE5 中创建对应的 DataTable 或 DataAsset
+3. 调参时只需修改此目录下的文件，再由程序 Agent 重新导入
@@ -0,0 +1,75 @@
+# Git 快速参考（AI 用）
+
+> 从 [GIT-GUIDE.md](GIT-GUIDE.md) 精简。完整规范见原文。
+
+---
+
+## 分支策略
+
+**轻量 Feature Branch** — 单人开发，`main` 永远可玩可编译。
+
+| 分支 | 前缀 | 生命期 | 说明 |
+|---|---|---|---|
+| 主线 | `main` | 永久 | 稳定版本，不直接在上面开发 |
+| 功能 | `feature/` | 合并后删 | 新系统、新功能 |
+| 修复 | `fix/` | 合并后删 | Bug 修复 |
+| 原型 | `prototype/` | 实验完即删 | 技术验证，随便写 |
+| 发布 | `release/` | 永久 | 从 main 切出，版本标记 |
+
+**命名规则：** `<类型>/<小写连字符描述>`
+```
+feature/player-movement   fix/camera-clipping   release/v0.1
+```
+
+**流程：**
+1. 从 `main` 拉分支 → 2. 开发并提交 → 3. 测试通过后合并回 `main` → 4. 删除分支
+
+---
+
+## 提交规范
+
+**格式：** `<type>(<scope>): <中文描述>`
+
+- subject ≤ 50 字符，中文描述，技术术语保留英文
+- body 可选，每行 ≤ 72 字符
+
+**Type（必选）：**
+
+| Type | 用途 |
+|---|---|
+| `feat` | 新功能 |
+| `fix` | Bug 修复 |
+| `art` | 美术资源 |
+| `level` | 关卡/场景 |
+| `audio` | 音效/音乐 |
+| `bp` | 蓝图逻辑 |
+| `refactor` | 重构（不改功能） |
+| `config` | 项目/引擎配置 |
+| `docs` | 文档 |
+| `wip` | 进行中（未完成） |
+
+**Scope（可选，常用）：**
+`player` `enemy` `combat` `ui` `camera` `inventory` `dialogue` `quest` `save` `audio` `animation` `ai` `level` `vfx`
+
+**示例：**
+```
+feat(player): 实现角色跳跃和二段跳
+fix(camera): 修复穿墙时摄像机卡顿问题
+bp(enemy): 实现巡逻-追击-攻击状态机
+wip(crafting): 合成系统UI初步框架
+config: 启用Nanite和Lumen
+```
+
+---
+
+## UE5 注意事项
+
+- 蓝图与 C++ 分开提交
+- `.uasset` / `.umap` 无法 diff → commit message 必须写清改了什么
+- 不提交 `Binaries/` `Intermediate/` `Saved/` `.vs/`
+
+---
+
+## 版本号
+
+`v主版本.次版本.修订号` — 主版本=里程碑，次版本=新系统，修订号=小修
@@ -0,0 +1,17 @@
+# docs/art/ — 美术文档
+
+美术 Agent 的输出目录。包含风格指南、资产规格、参考图等。
+
+## 文件组织
+
+```
+docs/art/
+  style-guide.md     # 风格指南（所有美术产出的锚点）
+  asset-specs/       # 各资产的规格文档
+  references/        # 参考图、情绪板（图片文件）
+```
+
+## 核心文件
+
+- **style-guide.md** — 视觉风格锚点，所有美术产出必须符合此指南
+- 每个资产一个规格文档，说明尺寸、面数、贴图要求等
@@ -0,0 +1,60 @@
+# 美术风格指南 — ChildHood（我的童年）
+
+> 本文档为所有美术产出的视觉锚点。任何资产制作前必须先参考此指南。
+
+---
+
+## 总体风格
+
+**3D Lowpoly — 温暖怀旧的80年代中国乡村**
+
+低多边形建模风格，强调形状的简洁与色彩的温暖感。不追求写实，而是通过精简的几何体和柔和的色彩唤起童年记忆中的那份纯真与温暖。
+
+---
+
+## 色彩方向
+
+- **主色调**: 暖黄、土褐、草绿 — 对应乡村的自然环境
+- **辅助色**: 天蓝、夕阳橙、烟囱灰 — 营造时间流逝感
+- **避免**: 高饱和度荧光色、冷硬的工业色系
+- **整体氛围**: 阳光洒在泥土路上的温暖感，而非阴暗或压抑
+
+---
+
+## 建模规范
+
+- **面数控制**: 低多边形，单个道具 < 500 面，角色 < 3000 面
+- **轮廓优先**: 物体的剪影要一眼可辨（弹珠是圆的，毽子有羽毛）
+- **不做**: 细节雕刻、高精度法线贴图、写实材质
+- **比例**: 略带卡通化，角色头部偏大，四肢圆润
+
+---
+
+## 贴图与材质
+
+- **贴图风格**: 手绘感，色块分明，像素边缘不过度抗锯齿
+- **材质类型**: 主要是 Unlit 或简单的 Lambert，不做复杂 PBR
+- **贴图尺寸**: 道具 128×128 或 256×256，角色 512×512
+- **色调映射**: 保持色彩明亮温暖，避免过暗的阴影
+
+---
+
+## 参考关键词
+
+- 低多边形乡村 / Lowpoly countryside
+- 怀旧游戏美术 / Nostalgic game art
+- 80年代中国农村 / 1980s rural China
+- 温暖色调低模 / Warm tone lowpoly
+- 《纪念碑谷》色彩感（参考方向，非照搬）
+
+---
+
+## 典型场景元素
+
+| 类别 | 示例 |
+|---|---|
+| 地形 | 泥土路、田埂、小溪、山坡 |
+| 建筑 | 砖瓦房、土墙院落、小卖部、祠堂 |
+| 植被 | 草地、稻田、大树、竹丛、菜地 |
+| 道具 | 弹珠、毽子、竹蜻蜓、纸飞机、橡皮筋 |
+| 角色 | 男孩、女孩、小伙伴、邻居爷爷/奶奶 |
@@ -0,0 +1,24 @@
+# docs/design/ — 策划文档
+
+策划 Agent 的输出目录。所有玩法设计、系统机制、剧情叙事文档存放于此。
+
+## 文件组织
+
+```
+docs/design/
+  activities/        # 各活动/小游戏的设计文档
+  systems/           # 系统机制设计（时间系统、NPC 关系等）
+  narrative/         # 剧情/叙事设计
+```
+
+## 格式约定
+
+- Markdown 格式
+- 每个活动/系统一个独立文件
+- 文件名使用小写英文 + 连字符：`marble-game.md`、`time-system.md`
+
+## 与其他 Agent 的关系
+
+- 程序 Agent 读取此目录的设计文档作为开发需求
+- 美术 Agent 读取设计文档中的美术需求部分
+- 数值参数抽到 `config/` 目录下的 CSV/JSON 文件中
@@ -0,0 +1,19 @@
+# 当前进度
+
+> 最后更新：2026-05-31
+> 代理完成工作后汇报结果，由开发者确认后才勾选 ✔
+
+## 当前里程碑：v0.1 第一个可玩原型
+
+### 进行中
+
+- [ ] 建立项目基础设施（目录结构、规范文档）
+
+### 待开始
+
+（待策划定义 v0.1 的具体功能范围）
+
+### 已完成
+
+- [x] Git 分支策略与提交规范
+- [x] 项目目录结构与协作体系设计
@@ -0,0 +1,18 @@
+# 项目路线图
+
+## v0.1 — 第一个可玩原型
+
+**目标**: 跑通核心玩法循环，验证"童年体验"的乐趣点
+
+- [ ] 定义 v0.1 包含的活动（弹珠？捉虫？跳绳？）
+- [ ] 核心系统：玩家移动与交互
+- [ ] 场景：乡村环境白盒
+- [ ] 至少一个完整可玩的小游戏
+
+## v0.2 — 核心玩法成型
+
+（待 v0.1 完成后规划）
+
+## v1.0 — 正式发布
+
+（远期目标）
@@ -0,0 +1,17 @@
+# docs/technical/ — 技术文档
+
+程序 Agent 的文档输出目录。包含技术架构、实现笔记、技术决策记录。
+
+## 文件组织
+
+```
+docs/technical/
+  architecture.md             # 项目技术架构总览
+  implementation-notes/       # 各系统的实现笔记
+```
+
+## 格式约定
+
+- Markdown 格式
+- 记录"为什么这么做"而非仅"做了什么"
+- 实现笔记与 `docs/design/` 中的设计文档一一对应