docs(refs): 新增进度管理迁移方案文档
This commit is contained in:
DESKTOP-2K5TJI4\admin
@@ -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/<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 更新和评论发布正确
|
||||||
@@ -108,3 +108,4 @@ scripts/.gitea-tokens.json
|
|||||||
*.swp
|
*.swp
|
||||||
*.swo
|
*.swo
|
||||||
*~
|
*~
|
||||||
|
temp.txt
|
||||||
|
|||||||
Reference in New Issue
Block a user