From e38c6efec12eac4a9d9373b668e9cb1651aa15d2 Mon Sep 17 00:00:00 2001 From: starmen1265 Date: Tue, 16 Jun 2026 19:02:40 +0800 Subject: [PATCH] =?UTF-8?q?chore(refs):=20=E6=B8=85=E7=90=86=E8=BF=87?= =?UTF-8?q?=E6=9C=9Frefs=E6=96=87=E6=A1=A3=E4=B8=8Eagent-memory=E6=AE=8B?= =?UTF-8?q?=E7=95=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/agent-memory/game-reviewer/MEMORY.md | 4 - .../game-reviewer/gitea-token-permission.md | 12 - .../game-reviewer/p012-review-note.md | 16 - .claude/refs/development-workflow.md | 285 ------------------ .claude/refs/进度管理流程修改方案.md | 248 --------------- 5 files changed, 565 deletions(-) delete mode 100644 .claude/agent-memory/game-reviewer/MEMORY.md delete mode 100644 .claude/agent-memory/game-reviewer/gitea-token-permission.md delete mode 100644 .claude/agent-memory/game-reviewer/p012-review-note.md delete mode 100644 .claude/refs/development-workflow.md delete mode 100644 .claude/refs/进度管理流程修改方案.md diff --git a/.claude/agent-memory/game-reviewer/MEMORY.md b/.claude/agent-memory/game-reviewer/MEMORY.md deleted file mode 100644 index 7d3691d..0000000 --- a/.claude/agent-memory/game-reviewer/MEMORY.md +++ /dev/null @@ -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 交互系统程序实现二次审查未通过记录 diff --git a/.claude/agent-memory/game-reviewer/gitea-token-permission.md b/.claude/agent-memory/game-reviewer/gitea-token-permission.md deleted file mode 100644 index 965cf4f..0000000 --- a/.claude/agent-memory/game-reviewer/gitea-token-permission.md +++ /dev/null @@ -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 `。评论内容仍以"审查 Agent (ai-reviewer)"署名。 diff --git a/.claude/agent-memory/game-reviewer/p012-review-note.md b/.claude/agent-memory/game-reviewer/p012-review-note.md deleted file mode 100644 index ed07bde..0000000 --- a/.claude/agent-memory/game-reviewer/p012-review-note.md +++ /dev/null @@ -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 个代码位置的修复状态，并验证修改汇报与实际代码变更一致。 diff --git a/.claude/refs/development-workflow.md b/.claude/refs/development-workflow.md deleted file mode 100644 index befe91b..0000000 --- a/.claude/refs/development-workflow.md +++ /dev/null @@ -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 负责质量把关 diff --git a/.claude/refs/进度管理流程修改方案.md b/.claude/refs/进度管理流程修改方案.md deleted file mode 100644 index d82ec25..0000000 --- a/.claude/refs/进度管理流程修改方案.md +++ /dev/null @@ -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/-report.md - - 新：在对应 Issue 下评论 - - ## 策划汇报 — 2026-06-06 - - **任务ID**: P-002a - **状态**: 已完成 - **产出**: `docs/design/prototype/interaction-system-execution.md` - - ### 完成内容 - - 创建独立执行案文件 - - 移除技术越界内容 - - 补充 4 个边界情况 - - ### 待确认 - - 交互取消行为链是否满足需求 - - 4.3 质量门审查 - - 旧：审查 → 写 reviews/-review.md → 更新 current.md - - 新： - 1. PM 执行审查（仍读本地文件内容逐条检查） - 2. 写本地 reviews/-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 调用，而非裸 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 更新和评论发布正确 \ No newline at end of file