Compare commits

...

4 Commits

Author SHA1 Message Date
starmen1265 11895bddfc art(research): 重整美术参考资料库
- 清理104张旧参考图(杂乱游戏截图与随机命名图)
- 新增东井村/十字街/十里长沟/迈皋桥广场等城郊实地实拍
- 新增各地点历史背景、家具物件清单、待补充素材清单
- 深夏时光参考截图改为正式命名
2026-06-16 19:06:55 +08:00
starmen1265 e38c6efec1 chore(refs): 清理过期refs文档与agent-memory残留 2026-06-16 19:02:40 +08:00
starmen1265 f59a5e0700 docs(common): Git规范文档迁移至docs/common 2026-06-16 19:01:55 +08:00
starmen1265 d7960b264e docs: 更新CLAUDE说明(灵感来源与技能精简) 2026-06-16 19:01:08 +08:00
176 changed files with 367 additions and 976 deletions
@@ -1,4 +0,0 @@
# game-reviewer 记忆索引
- [Gitea Token Permission](gitea-token-permission.md) — reviewer token 为空,所有操作使用 PM role
- [P-012 Review](p012-review-note.md) — Issue #32 交互系统程序实现二次审查未通过记录
@@ -1,12 +0,0 @@
---
name: gitea-token-permission
description: reviewer token 权限限制——仅可评论,标签操作需用 PM token
metadata:
type: feedback
---
reviewer token 为空字符串,无法执行任何 API 操作(评论、标签均不可)。PM token 可执行全部操作。
**Why:** gitea-config.json 中 reviewer 角色未配置 token(token 字段为空字符串)。
**How to apply:** 所有 Gitea API 操作(评论、标签更新)均使用 PM 角色执行:`node .claude/skills/gitea-collab/gitea.js --role pm issue comment/labels <number>`。评论内容仍以"审查 Agent (ai-reviewer)"署名。
@@ -1,16 +0,0 @@
---
name: p012-review-note
description: Issue #32 交互系统程序实现审查——二次审查未通过记录
metadata:
type: project
---
Issue #32 (P-012 交互系统程序实现) 二次审查未通过。首次审查发现 2 个重大问题 + 5 个中等问题。程序提交修改汇报后,二次审查发现修改汇报声称的修复并未在代码中体现,4 个问题实际未修复:
1. SetInteracting(true) 双调用(InteractionManager 反射 + Character 直接调用)——运行时 Bug
2. DoorActor::OnInteractStarted_Implementation 仍调用 ToggleDoor ——代码残留
3. ExecuteCameraReturn 未清空 CachedPushCamera ——冗余回位
4. AddToBackpack 缺 TODO 注释
**Why:** 程序修改汇报与实际代码变更不一致,可能修改未提交或修改了错误文件。
**How to apply:** 后续审查此 Issue 时,重点关注以上 4 个代码位置的修复状态,并验证修改汇报与实际代码变更一致。
-139
View File
@@ -1,139 +0,0 @@
# Git 快速参考(AI 用)
> 从 [GIT-GUIDE.md](GIT-GUIDE.md) 精简。完整规范见原文。
---
## 分支策略
**develop 长期开发分支模型** — 单人开发 + 多 Agent 协作。
```
main ─────────── 永远可玩可编译,受保护,禁止直接推送
│
│ PR (Gitea) ← 里程碑/迭代结束时,PM 发起
│
└── develop ──── 长期分支,所有 agent 在此工作
```
| 分支 | 生命期 | 说明 |
|---|---|---|
| `main` | 永久 | 稳定版本,受保护 |
| `develop` | 永久 | 日常开发分支,所有 agent 共用 |
**辅助分支(可选,用于实验):**
| 分支 | 前缀 | 生命期 | 说明 |
|---|---|---|---|
| 原型 | `prototype/` | 实验完即删 | 技术验证,随便写 |
| 发布 | `release/` | 永久 | 从 main 切出,版本标记 |
**流程:**
1. 所有开发在 `develop` 上进行 → 2. 迭代完成时创建 PR → 3. 审查通过后合并回 `main`
---
## 提交规范
**格式:** `<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主版本.次版本.修订号` — 主版本=里程碑,次版本=新系统,修订号=小修
---
## 远程仓库
**SSH 地址**:`ssh://sc-gitea@micecola.top:2223/starmen1265/ChildHood.git`
> ⚠️ 用户名是 `sc-gitea`(非默认 `git`),端口是 `2223`(非默认 22)
**切换远程地址**:
```bash
git remote set-url origin ssh://sc-gitea@micecola.top:2223/starmen1265/ChildHood.git
```
**SSH config**(`~/.ssh/config`):
```
Host gitea micecola.top
HostName micecola.top
Port 2223
User sc-gitea
IdentityFile ~/.ssh/id_ed25519_gitea
IdentitiesOnly yes
```
**内网地址**(家里用):`ssh://sc-gitea@192.168.1.22:2223/starmen1265/ChildHood.git`
完整规范见 → [GIT-GUIDE.md](GIT-GUIDE.md)
---
## 自动化工作流
`git-workflow.sh` 脚本封装了常用 git 操作:
```bash
# 开始工作:确保在 develop 上且最新
bash .claude/scripts/git-workflow.sh ready
# 提交修改
bash .claude/scripts/git-workflow.sh commit <type> <scope> "中文描述"
# 推送到远程
bash .claude/scripts/git-workflow.sh push
# 查看状态
bash .claude/scripts/git-workflow.sh status
```
### PM 发布流程
```bash
# 创建 develop → main PR
bash .claude/scripts/git-workflow.sh release "迭代名称"
# 用户在 Gitea 合并后同步
bash .claude/scripts/git-workflow.sh post-release
```
-285
View File
@@ -1,285 +0,0 @@
# 游戏开发工作流
> 本文档定义游戏项目的开发阶段、任务管理、角色职责、产出标准和质量检查规则。
> 项目采用 3 阶段开发模型:草图 → 总路线 → 迭代。每个阶段有独立的技能文件管理任务序列。
>
> 项目管理工具当前使用 Gitea。PM 操作详见 `gitea-pm` 技能,通用协作详见 `gitea-collab` 技能。
> 阶段技能文件:
> - `.claude/skills/project-initializer.md` — 项目初始化
> - `.claude/skills/stage-sketch.md` — 草图阶段
> - `.claude/skills/stage-roadmap.md` — 总路线阶段
> - `.claude/skills/stage-iteration.md` — 迭代阶段
---
## 角色定义
| 角色 | 职责 | 产出位置 | PM 如何判断其进度 |
|------|------|----------|-------------------|
| **策划** (Design) | 玩法设计、数值平衡、叙事、系统机制 | `docs/design/`、`GameConfig/` | 扫描 `docs/design/` 和 `GameConfig/` 目录中的文件 |
| **程序** (Dev) | 系统实现、技术架构、Bug 修复 | `Source/`、`Content/`、`docs/technical/` | 扫描对应目录中的文件 |
| **美术** (Art) | 美术需求分析、资产规格、风格指南 | `docs/art/`、`Content/` | 扫描对应目录中的文件 |
| **PM** | 进度管理(3阶段状态机)、任务分配与追踪、开发决策咨询 | **Gitea Issues + Milestones** | 通过 Gitea 读取任务和里程碑 |
| **审查** (Reviewer) | 审查交付物质量、更新 Issue 标签和评论 | Issue 评论 | 通过 `review:pass/fail` 标签 |
### 协作规则
- **策划先行**:设计文档是其他角色的需求源
- **程序读设计**:实现前必须先读取对应设计文档和配置表
- **文档即交接**:Agent 之间不直接通信,通过共享文档目录 + 任务 Issue 评论交接(参见 `gitea-collab` 技能)
- **冲突时用户说了算**:玩法/数值/叙事的最终决定权在用户
- **PM 是进度调度器**:PM 管理进度和任务分配,不做审查
- **审查是子代理**:角色完成工作后启动 game-reviewer 子代理审查,审查结果返回给角色,角色向用户汇报
- **会话启动先调 PM**:每次工作会话开始时,用户先调 PM 执行进度检查,确认当前状态后再进入具体工作
- **用户驱动角色切换**:角色间的工作切换由用户手动触发,PM 不自动指派任务
- **角色任务汇报**:各角色通过项目管理工具在任务 Issue 下评论汇报进度,PM 据此追踪
### 进度汇报规则
- 进度管理唯一真实来源是 **项目管理工具**(当前为 Gitea Issues + Milestones)。具体操作参见 `gitea-pm` / `gitea-collab` 技能
- 各角色完成工作后在对应 Issue 下评论汇报,不更新本地 report 文件
- PM 通过项目管理工具读取任务和评论,给出行动建议
- 角色完成工作后自行启动 game-reviewer 子代理审查,审查通过后 PM 请示用户关闭 Issue
- 任务追踪使用唯一任务 ID(格式:`[角色前缀]-[三位数字]`),对应 Issue 标题前缀
- 审查结果通过 Issue 评论发布
---
## 开发阶段
项目开发分为三个阶段,每个阶段有独立的技能文件管理任务序列。
```
草图阶段 ─── "这个游戏是什么?能不能做?" ─── 概念设计 + 技术可行性
↓
总路线阶段 ─── "全面设计蓝图" ─── 9 份设计文档 + 版本路径图
↓
迭代阶段 ─── "按版本迭代开发" ─── 插件准备 → 执行案 → 开发 → 整合 → 修复
↑ ↓
└──── 迭代完成,有下一个迭代 ←── 迭代完成 ───────┘
```
**阶段转换由 PM 建议但需用户确认**。阶段技能文件定义了每个阶段的任务序列和转换条件。
---
### 草图阶段
**目的**:确定游戏是什么——玩法方向、美术风格、技术可行性。
**关注问题**:这个游戏是什么?为什么要做?做不做得了?
#### 任务序列(2 个任务)
1. **概念设计** (D-XXX) — 策划产出概念草案
2. **技术可行性评估** (P-XXX) — 程序评估技术可行性(依赖概念设计完成)
#### 完成标志
两个任务都关闭 + 草图阶段里程碑下无 open issues → 进入总路线阶段。
#### 详细任务定义
参见 `.claude/skills/stage-sketch.md`。
---
### 总路线阶段
**目的**:建立完整的游戏设计蓝图,规划版本迭代路径。
**关注问题**:游戏长什么样?有哪些系统?分几个版本做?
#### 任务序列(9 个任务)
1. **设计总索引** (D-XXX) — 必须完整
2. **世界观设计** (D-XXX) — 允许占位
3. **剧情设计** (D-XXX) — 允许占位
4. **角色设计** (D-XXX) — 允许占位
5. **系统设计** (D-XXX) — ⚠️ 必须完整
6. **关卡设计** (D-XXX) — ⚠️ 必须完整
7. **UI 设计** (D-XXX) — 允许占位
8. **音频设计** (D-XXX) — 允许占位
9. **版本路径图** (D-XXX) — 必须完整(依赖 2-8)
**占位规则**:除系统设计和关卡设计外,其他文档允许空文件占位(标题+章节+「待填充」),后续迭代完善。
#### 完成标志
所有任务关闭 + 里程碑下无 open issues → 进入迭代阶段。
#### 详细任务定义
参见 `.claude/skills/stage-roadmap.md`。
---
### 迭代阶段
**目的**:按版本迭代推进开发,每个迭代完成一个可玩版本。
**关注问题**:这个版本做什么?做到什么程度?Bug 修了没?
#### 任务序列(每迭代 6-9 个任务)
| 任务 | 角色 | 说明 |
|------|------|------|
| 插件资产检查与准备 | 程序 | 仅首次迭代 |
| 设计案迭代补充 | 策划 | 可选 |
| 策划执行案 | 策划 | 必选 |
| 程序需求分析 | 程序 | 必选 |
| 关卡搭建 | 程序 | 有场景时 |
| 系统开发 | 程序 | 必选 |
| 优化意见 | 程序 | 必选 |
| 资产接入整合 | 程序 | 必选 |
| Bug 修复 | 程序 | 必选 |
**关键规则**:PM 每次激活时只创建下一个可创建的任务,不要一次全部创建。
#### 迭代完成
Bug 修复关闭 → 询问用户是否有下一个迭代:
- **有** → 关闭当前里程碑 → 创建下一个迭代里程碑 → 继续
- **没有** → 返回总路线阶段
#### 详细任务定义
参见 `.claude/skills/stage-iteration.md`。
---
## 设计文档层级关系
草案、设计案、执行案三者的关系:
| 层级 | 定位 | 比喻 | 特点 |
|------|------|------|------|
| **草案** (概念草案.md) | 给游戏**定调** | 灵魂 | 回答"这个游戏是什么",简略但方向明确 |
| **设计案** | 给游戏**定骨架** | 骨架 | 基于草案的原则展开系统设计,定义有哪些系统、系统关系、核心行为 |
| **执行案** | 给游戏**填血肉** | 血肉 | 细化到程序可直接实现的交互规则和行为细节 |
设计案初始基于草案的原则进行设计。在后续迭代中遇到具体问题时,可以灵活调整或替换草案中的元素——草案是方向指引,不是硬性约束。
---
## 执行案规范
### 执行案格式
每个执行案文件顶部必须包含**迭代记录表头**:
```markdown
# <系统名>执行案
## 迭代记录
| 迭代版本 | 修改日期 | 状态 | 说明 |
|----------|----------|------|------|
| v0.1 | 2026-06-10 | 📝 设计中 | 初始版本 |
> 状态标记:📝 设计中 | 🔄 开发中 | ✅ 已同步
---
## 系统概述
(描述该系统做什么、服务于什么体验目标)
## 行为规则
(当前最新状态的所有行为规则)
```
### 执行案必须包含
1. **系统概述**:这个系统做什么、服务于什么体验目标
2. **完整的行为规则清单**:每个操作的触发条件、触发后表现、结束条件
3. **状态和状态转换**:系统有哪些状态、什么条件触发状态变化
4. **边界情况处理**:异常/极端情况下的系统行为
5. **与其他系统的交互**:本系统与其他系统的关联和影响
### 执行案不应包含
- 用什么引擎组件实现
- 代码/脚本架构怎么组织
- 数据用什么格式存储
- 具体的参数精确值(调优参数标注"建议值,可调")
### 关卡执行案
- 当版本开发涉及场景搭建时,策划额外产出一份关卡执行案
- 关卡执行案将场景设计案的氛围描述转化为空间精度搭建指南(坐标、尺寸、BSP 资产映射)
- 使用混合坐标体系:区域用场景绝对坐标,区域内物件用相对偏移坐标
- 交互物和收集品的位置标注必须与交互系统/收集系统执行案交叉引用
- 完整规范参见 `.claude/refs/level-execution-template.md`
---
## 审查流程
> 审查由 **game-reviewer 子代理**执行,不再由 PM 执行。
> 角色完成工作后自行启动 reviewer 子代理。
### 审查触发
角色完成工作 → 在 Issue 下评论汇报 → 改标签为 `status:in-review` → 启动 game-reviewer 子代理
### 审查标准
审查标准定义在 `.claude/skills/quality-gate-review.md`,包含 4 道质量门:
1. 执行案质量门 — 完整性、清晰性、边界情况、系统关联、技术越界
2. 程序设计质量门 — 执行案覆盖度、美术需求、架构、数据流、风险、工作量
3. 美术资产验收门 — 需求覆盖、资产到位、规格、缺失处理
4. 程序实现验收门 — 设计一致性、覆盖度、资产使用、偏差处理
### 审查结果
- **通过** → reviewer 更新标签为 `review:pass` → 角色向用户汇报 → 用户决定是否关闭
- **未通过** → reviewer 更新标签为 `review:fail` + `status:blocked` → 角色向用户汇报 → 修改后重新提交
---
## 审查质量标准
> 以下标准供 game-reviewer 子代理使用。详细标准定义在 `.claude/skills/quality-gate-review.md`。
### 执行案质量标准
- [ ] 是否覆盖了该系统所有玩家可感知的行为?
- [ ] 每个操作是否明确了触发条件、触发后表现、结束条件?
- [ ] 边界情况是否都处理了?
- [ ] 与其他系统的关联是否说明?
- [ ] 是否有模糊地带?行为描述是否无歧义?
- [ ] 是否误入了技术细节?参数值是否标注为"建议值,可调"?
- [ ] 迭代记录表头是否存在且填写完整?
### 程序设计质量标准
- [ ] 是否完整回应了执行案中的每条行为规则?(逐条对照)
- [ ] 美术资源需求是否列得具体(尺寸、数量、触发时机)?
- [ ] 类与组件架构是否清晰?
- [ ] 数据流是否明确?
- [ ] 技术风险是否识别?
- [ ] 工作量估算是否给出?实现拆分建议是否合理且可操作?
### 美术资产验收标准
- [ ] 资源需求清单中的每一项是否都有对应的美术产出?(逐项对照)
- [ ] 资产文件是否已放置在对应目录?
- [ ] 资产规格是否符合需求?
- [ ] 未到位资产是否有明确的处理方案?
### 程序实现验收标准
- [ ] 实现是否与程序设计方案一致?(逐条对照)
- [ ] 最终实现是否完整覆盖了执行案中的所有行为规则?
- [ ] 美术资产是否已正确集成并使用?
- [ ] 偏差清单是否已梳理清楚?重大偏差是否有处理方案?
---
## 单人独立开发的特殊考量
- **无法并行**——同一时间只能做一件事,选择更关键
- **精力有限**——避免一次性拆分太多并行任务
- **心流重要**——建议按「完整做完一个小系统」而非「同时推进多个系统」的方式工作
- **早期验证**——越早能跑起来看到东西,越不容易失去动力
- **文档交接**——Agent 之间通过文档交接,PM 是进度调度器,reviewer 负责质量把关
@@ -1,248 +0,0 @@
ChildHood 项目当前使用本地 Markdown 文件(docs/plans/current.md、reports/、reviews/、archive/)进行进度管理。用户已在 Gitea 上搭建了 Issue/Milestone/看板基础设施(3 个 Issue、1 个 Milestone、1
个看板),并希望将进度管理完全迁移到 Gitea,不再保留本地降级模式。
核心目标:Gitea 成为唯一的进度管理真实来源,获得可视化看板、Web 面板随时查看、更结构化的任务管理体验。
---
一、结论:可行,但有前提条件
迁移可行,Gitea API 能覆盖当前进度管理 80%+ 的需求。但有两个前提条件必须先解决:
1. UTF-8 编码问题:现有 3 个 Issue 的中文全部乱码,说明之前通过 API 创建时编码处理有误。这是阻塞性问题,必须在迁移前解决。
2. API Token 写权限验证:ai-pm 账号的 Token 需要验证对 Issue/Milestone/Label/Comment 的写操作权限。
---
二、本地概念 → Gitea 映射设计
任务 (P-002) → Issue(标题含任务ID前缀,如 "P-002 v0.1 执行案")
版本 (v0.1) → Milestone(如 "v0.1-基础交互")
任务完成 [x] → Issue 关闭 (state=closed)
任务状态 → Label(status:backlog / in-progress / blocked / in-review / done)
流水线步骤 → Label(pipeline:3-execution / 4-tech-design / ...)
角色归属 → Label(role:design / dev / art / pm)+ assignee
质量门判定 → Label(gate:execution-pass/fail / tech-pass/fail / ...)
角色汇报 → Issue 评论
审查记录 → Issue 评论(摘要+链接)+ 本地文件(详细内容保留)
任务依赖 → Issue Dependencies API
流水线总览 → Meta Issue(body 中维护流水线进度表)
需要创建的 Label 体系(共约 20 个)
┌──────────────┬─────────────────────────────────────────────────────────────────────────────────────────────┬────────────────────┐
│ 类别 │ Labels │ 用途 │
├──────────────┼─────────────────────────────────────────────────────────────────────────────────────────────┼────────────────────┤
│ status (6) │ status:backlog status:ready status:in-progress status:blocked status:in-review status:done │ 任务生命周期状态 │
├──────────────┼─────────────────────────────────────────────────────────────────────────────────────────────┼────────────────────┤
│ pipeline (5) │ pipeline:3-execution pipeline:4-tech-design pipeline:5-art pipeline:6-impl pipeline:7-retro │ 当前在流水线哪一步 │
├──────────────┼─────────────────────────────────────────────────────────────────────────────────────────────┼────────────────────┤
│ role (4) │ role:design role:dev role:art role:pm │ 归属角色 │
├──────────────┼─────────────────────────────────────────────────────────────────────────────────────────────┼────────────────────┤
│ gate (8) │ gate:execution-pass/fail gate:tech-pass/fail gate:art-pass/fail gate:impl-pass/fail │ 质量门审查结果 │
└──────────────┴─────────────────────────────────────────────────────────────────────────────────────────────┴────────────────────┘
本地文件处理策略
┌──────────────────────┬────────────────────┬─────────────────────────────────────────────────────────────────────┐
│ 文件 │ 策略 │ 原因 │
├──────────────────────┼────────────────────┼─────────────────────────────────────────────────────────────────────┤
│ current.md │ 废弃 │ 流水线进度迁移到 Pipeline Tracker Meta Issue;任务列表迁移到 Issues │
├──────────────────────┼────────────────────┼─────────────────────────────────────────────────────────────────────┤
│ reports/*.md │ 废弃 │ 角色汇报迁移到 Issue 评论 │
├──────────────────────┼────────────────────┼─────────────────────────────────────────────────────────────────────┤
│ reviews/*.md │ 保留本地 │ 审查记录是结构化文档,内容复杂;Issue 评论中放结论摘要+文件链接 │
├──────────────────────┼────────────────────┼─────────────────────────────────────────────────────────────────────┤
│ archive/ │ 冻结现有,不再新增 │ closed Issues = 归档,通过 Milestone 过滤查看历史 │
├──────────────────────┼────────────────────┼─────────────────────────────────────────────────────────────────────┤
│ prototype-roadmap.md │ 保留本地 │ 信息量太大(4版本×多维度),不适合放 Milestone description │
├──────────────────────┼────────────────────┼─────────────────────────────────────────────────────────────────────┤
│ roadmap.md │ 保留本地 │ 全局路线图,不迁移 │
├──────────────────────┼────────────────────┼─────────────────────────────────────────────────────────────────────┤
│ work-log.md │ 保留本地 │ 粒度不匹配 Gitea time tracker │
└──────────────────────┴────────────────────┴─────────────────────────────────────────────────────────────────────┘
---
三、需验证的 API 接口(按优先级)
P0 — 阻塞性验证(迁移前必须通过)
┌─────┬───────────────────────────────────┬────────────────────────────────────────────┬─────────────────────────┬────────────────────┐
│ # │ 操作 │ 端点 │ 验证内容 │ 管理场景 │
├─────┼───────────────────────────────────┼────────────────────────────────────────────┼─────────────────────────┼────────────────────┤
│ 1 │ 创建含中文的 Issue │ POST /repos/{owner}/{repo}/issues │ UTF-8 编码正确显示 │ 创建任何任务 │
├─────┼───────────────────────────────────┼────────────────────────────────────────────┼─────────────────────────┼────────────────────┤
│ 2 │ 创建含中文的评论 │ POST /repos/{index}/comments │ UTF-8 编码正确显示 │ 角色汇报、审查结论 │
├─────┼───────────────────────────────────┼────────────────────────────────────────────┼─────────────────────────┼────────────────────┤
│ 3 │ 创建 Label │ POST /repos/{owner}/{repo}/labels │ 含中文名的 Label 能创建 │ 初始化标签体系 │
├─────┼───────────────────────────────────┼────────────────────────────────────────────┼─────────────────────────┼────────────────────┤
│ 4 │ 给 Issue 添加/移除 Label │ POST/DELETE /issues/{index}/labels │ Label 正确关联 │ 状态变更 │
├─────┼───────────────────────────────────┼────────────────────────────────────────────┼─────────────────────────┼────────────────────┤
│ 5 │ 更新 Issue(状态/标题/body/指派) │ PATCH /repos/{owner}/{repo}/issues/{index} │ 所有字段正确更新 │ 任务状态推进 │
├─────┼───────────────────────────────────┼────────────────────────────────────────────┼─────────────────────────┼────────────────────┤
│ 6 │ 关闭/重开 Issue │ PATCH ... state=closed/open │ 状态切换正确 │ 任务完成/回退 │
└─────┴───────────────────────────────────┴────────────────────────────────────────────┴─────────────────────────┴────────────────────┘
P1 — 核心功能验证
┌─────┬──────────────────────────────────┬────────────────────────────────────────────┬──────────────────┬──────────────────┐
│ # │ 操作 │ 端点 │ 验证内容 │ 管理场景 │
├─────┼──────────────────────────────────┼────────────────────────────────────────────┼──────────────────┼──────────────────┤
│ 7 │ 读取 Issue 列表(含过滤) │ GET /issues?state=open&labels=&milestones= │ 过滤参数生效 │ PM 会话启动 │
├─────┼──────────────────────────────────┼────────────────────────────────────────────┼──────────────────┼──────────────────┤
│ 8 │ 读取 Issue 评论列表 │ GET /issues/{index}/comments │ 返回完整评论历史 │ PM 读取角色汇报 │
├─────┼──────────────────────────────────┼────────────────────────────────────────────┼──────────────────┼──────────────────┤
│ 9 │ Issue 依赖关系(添加/读取/删除) │ POST/GET/DELETE /issues/{index}/blocks │ 依赖链正确建立 │ P-003 依赖 P-002 │
├─────┼──────────────────────────────────┼────────────────────────────────────────────┼──────────────────┼──────────────────┤
│ 10 │ 创建/更新 Milestone │ POST/PATCH /milestones │ 新版本创建 │ 版本管理 │
└─────┴──────────────────────────────────┴────────────────────────────────────────────┴──────────────────┴──────────────────┘
P2 — 可选验证
┌─────┬────────────┬──────────────────────────────────────┬────────────────────────────┐
│ # │ 操作 │ 端点 │ 说明 │
├─────┼────────────┼──────────────────────────────────────┼────────────────────────────┤
│ 11 │ 时间追踪 │ POST /issues/{index}/stopwatch/start │ 替代 work-log.md,优先级低 │
├─────┼────────────┼──────────────────────────────────────┼────────────────────────────┤
│ 12 │ Issue 搜索 │ GET /repos/issues/search │ 跨仓库搜索,可能用不到 │
└─────┴────────────┴──────────────────────────────────────┴────────────────────────────┘
---
四、新流程设计
4.1 PM 会话启动追踪(核心变化)
旧:读 current.md → 读 reports/*.md → 汇报
新:
1. GET /milestones → 确认当前版本 Milestone
2. GET /issues?state=open&milestones={当前版本ID} → 获取当前版本所有活跃任务
3. 读取 Pipeline Tracker Meta Issue body → 了解流水线位置
4. 读取各 Issue 的 Labels → 理解每个任务状态/角色/质量门
5. 读取相关 Issue 评论 → 了解角色最新汇报
6. 读本地 reviews/ 最新审查记录(如有)
7. 向用户汇报 + 建议
4.2 角色汇报进度
旧:更新 docs/plans/reports/<role>-report.md
新:在对应 Issue 下评论
## 策划汇报 — 2026-06-06
**任务ID**: P-002a
**状态**: 已完成
**产出**: `docs/design/prototype/interaction-system-execution.md`
### 完成内容
- 创建独立执行案文件
- 移除技术越界内容
- 补充 4 个边界情况
### 待确认
- 交互取消行为链是否满足需求
4.3 质量门审查
旧:审查 → 写 reviews/<ID>-review.md → 更新 current.md
新:
1. PM 执行审查(仍读本地文件内容逐条检查)
2. 写本地 reviews/<ID>-review.md(详细记录保留本地)
3. 在对应 Issue 下发审查结论评论(摘要 + 文件链接)
4. 通过 API 更新 Issue Labels:移除 status:in-review,添加 status:blocked + gate:execution-fail(不通过时)
5. 更新 Pipeline Tracker Meta Issue body 中的进度表
4.4 任务归档
旧:current.md 中 [x] → 移到 archive/ 文件
新:用户确认完成 → PATCH /issues/{index} state=closed → 发完成评论(日期+产出链接)→ 不再需要 archive/ 文件
4.5 新任务创建
旧:在 current.md 中添加 - [ ] P-XXX ...
新:
1. POST /issues 创建 Issue(标题含任务ID、body 含模板信息、关联 Milestone、打上初始 Labels)
2. 如有依赖 → POST /issues/{index}/blocks 设置依赖关系
3. PM 更新 Pipeline Tracker Meta Issue body
---
五、实施步骤
步骤 1:API 验证脚本
编写 scripts/gitea-api.py 封装所有 API 操作,解决 UTF-8 编码问题。Agent 通过 python scripts/gitea-api.py <command> <args> 调用,而非裸 curl/python 内联。
验证所有 P0 + P1 接口。同时修复现有 3 个乱码 Issue(重建或更新内容)。
步骤 2:Label 体系初始化
通过脚本创建全部约 20 个 Labels。为现有 3 个 Issue 打上正确 Labels。
步骤 3:创建 Pipeline Tracker Meta Issue
将 current.md 中的流水线进度表迁移到一个 Meta Issue 的 body 中。
步骤 4:修改 PM Agent 的 system prompt
修改 .claude/agents/game-pm.md:
- 会话启动:从 Gitea API 读取进度(替代读 current.md + reports/)
- 质量门审查:审查后更新 Issue Labels + 评论
- 任务创建/归档:通过 API 创建/关闭 Issue
- 不再维护 current.md
步骤 5:修改策划/程序 Agent 的 system prompt
修改 .claude/agents/game-designer.md 和 .claude/agents/game-dev.md:
- 完成工作后在对应 Issue 下评论汇报(替代更新 reports/ 文件)
步骤 6:验证与稳定
用 PM Agent 按新流程完成一次完整工作会话,确认 API 调用链路稳定、数据准确。
---
六、风险与缓解
┌────────────────────────────┬──────┬──────────────────────────────────────────────────┐
│ 风险 │ 等级 │ 缓解措施 │
├────────────────────────────┼──────┼──────────────────────────────────────────────────┤
│ 网络不可用导致 PM 无法工作 │ 中 │ 接受此风险——Gitea 是自建服务,可用性由用户掌控 │
├────────────────────────────┼──────┼──────────────────────────────────────────────────┤
│ UTF-8 编码问题重现 │ 高 │ 封装 Python 脚本统一处理编码,ensure_ascii=False │
├────────────────────────────┼──────┼──────────────────────────────────────────────────┤
│ 看板列位置不可 API 操作 │ 低 │ 用 Labels 替代看板列概念;用户手动拖拽(频率低) │
├────────────────────────────┼──────┼──────────────────────────────────────────────────┤
│ Agent 调用 API 出错 │ 中 │ 封装脚本统一错误处理和重试;API 调用前本地记录 │
└────────────────────────────┴──────┴──────────────────────────────────────────────────┘
---
七、关键修改文件清单
┌──────────────────────────────────────┬───────────────────────────────────────────────────────────┐
│ 文件 │ 修改内容 │
├──────────────────────────────────────┼───────────────────────────────────────────────────────────┤
│ scripts/gitea-api.py │ 新建 — API 封装脚本,解决编码和错误处理 │
├──────────────────────────────────────┼───────────────────────────────────────────────────────────┤
│ .claude/agents/game-pm.md │ 大幅修改 — PM 的进度读取/质量门/任务管理全部改为 API 调用 │
├──────────────────────────────────────┼───────────────────────────────────────────────────────────┤
│ .claude/agents/game-designer.md │ 中等修改 — 汇报方式从写文件改为 Issue 评论 │
├──────────────────────────────────────┼───────────────────────────────────────────────────────────┤
│ .claude/agents/game-dev.md │ 中等修改 — 同上 │
├──────────────────────────────────────┼───────────────────────────────────────────────────────────┤
│ .claude/refs/development-workflow.md │ 小改 — 协作规则中更新进度汇报方式描述 │
├──────────────────────────────────────┼───────────────────────────────────────────────────────────┤
│ docs/plans/current.md │ 废弃 — 不再维护 │
├──────────────────────────────────────┼───────────────────────────────────────────────────────────┤
│ docs/plans/reports/*.md │ 废弃 — 不再维护 │
├──────────────────────────────────────┼───────────────────────────────────────────────────────────┤
│ docs/technical/gitea-api-guide.md │ 更新 — 补充新验证的 API 端点和脚本用法 │
└──────────────────────────────────────┴───────────────────────────────────────────────────────────┘
---
八、验证方式
1. API 验证:用 ai-pm Token 依次执行 P0 全部 6 项操作,确认中文显示正确、写权限可用
2. Label 创建:创建全部 Labels 并在 Web 面板确认显示正确
3. 端到端测试:PM Agent 用新流程完成一次完整的工作会话启动追踪,确认 API 调用链路正确
4. 质量门测试:PM 对一个 Issue 执行质量门审查,确认 Labels 更新和评论发布正确
+3 -5
View File
@@ -7,7 +7,7 @@
- **引擎**: Unreal Engine 5.7.4
- **美术风格**: 3D Lowpoly,温暖色调,怀旧氛围
- **核心玩法**: 模拟千禧年前后城郊结合区儿童的日常生活(探索、小游戏互动、收集、剧情叙事)
- **灵感来源**: NDS《放学后少年》自由探索 + PS《我的暑假》日常叙事节奏
- **灵感来源**: NDS《放学后少年》自由探索 + PS《我的暑假》日常叙事节奏 +《深夏时光》玩法
- **时代背景**: 2000年前后,城市边缘的城郊结合区(如南京迈皋桥),兼顾乡村情节
- **开发者**: starmen1265(单人独立开发)
@@ -16,8 +16,6 @@
## 项目管理
- **工具**: Gitea(Issues + Milestones)
- **PM 技能**: `gitea-pm`(任务创建/关闭、里程碑管理、Pipeline Tracker)
- **通用技能**: `gitea-collab`(任务查询、进度汇报、审查操作)
- **进度查询**: Pipeline Tracker(Meta Issue,仅记录当前阶段和阶段历史)
- **配置文件**: `.claude/skills/gitea-pm/gitea-config.json`(含连接信息、Token、角色映射、标签定义)
@@ -25,9 +23,9 @@
## Git 规范
详见 [.claude/refs/GIT-GUIDE-LITE.md](.claude/refs/GIT-GUIDE-LITE.md)。核心要点:
详见 [docs/common/GIT-GUIDE.md](docs/common/GIT-GUIDE.md)。核心要点:
- `main` 永远可玩可编译
- 分支: `feature/` `fix/` `prototype/` `release/`
- 分支: `develop/`
- 提交: `<type>(<scope>): <中文描述>`,subject ≤ 50 字符
- UE5: 蓝图与 C++ 分开提交;.uasset/.umap commit message 必须写清内容
Binary file not shown.

Before

Width:  |  Height:  |  Size: 33 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 33 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 33 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 33 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 387 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 313 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 184 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 124 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 272 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 259 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 523 KiB

Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.

Some files were not shown because too many files have changed in this diff Show More