From 768d927d262689d5f319a56aac769cd8f5af41e9 Mon Sep 17 00:00:00 2001 From: "DESKTOP-2K5TJI4\\admin" Date: Fri, 5 Jun 2026 19:09:46 +0800 Subject: [PATCH] =?UTF-8?q?docs(refs):=20=E6=96=B0=E5=A2=9E=E8=BF=9B?= =?UTF-8?q?=E5=BA=A6=E7=AE=A1=E7=90=86=E8=BF=81=E7=A7=BB=E6=96=B9=E6=A1=88?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/refs/进度管理流程修改方案.md | 248 +++++++++++++++++++++++++++ .gitignore | 1 + 2 files changed, 249 insertions(+) create mode 100644 .claude/refs/进度管理流程修改方案.md diff --git a/.claude/refs/进度管理流程修改方案.md b/.claude/refs/进度管理流程修改方案.md new file mode 100644 index 0000000..d82ec25 --- /dev/null +++ b/.claude/refs/进度管理流程修改方案.md @@ -0,0 +1,248 @@ +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 diff --git a/.gitignore b/.gitignore index 9bcaa56..effc92f 100644 --- a/.gitignore +++ b/.gitignore @@ -108,3 +108,4 @@ scripts/.gitea-tokens.json *.swp *.swo *~ +temp.txt