starmen1265/ChildHood
1
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects 2 Releases Wiki Activity

chore(refs): 清理过期refs文档与agent-memory残留

Browse Source
This commit is contained in:
starmen1265
2026-06-16 19:02:40 +08:00
parent f59a5e0700
commit e38c6efec1
5 changed files with 0 additions and 565 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/agent-memory/game-reviewer/MEMORY.md
-4
View File
@@ -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 交互系统程序实现二次审查未通过记录
.claude/agent-memory/game-reviewer/gitea-token-permission.md
-12
View File
@@ -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)"署名。
.claude/agent-memory/game-reviewer/p012-review-note.md
-16
View File
@@ -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 个代码位置的修复状态，并验证修改汇报与实际代码变更一致。
.claude/refs/development-workflow.md
-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 负责质量把关
.claude/refs/进度管理流程修改方案.md
-248
View File
@@ -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 更新和评论发布正确