feat(tools): 新增 Gitea CLI 工具并迁移进度管理到 Issue/Milestone

- 新增 scripts/gitea.js CLI（20+ 子命令，--role Token 管理） - 新增 scripts/gitea-api.js API 客户端模块 - 新增 scripts/.gitea-tokens.json（gitignored，按角色存 Token） - 更新 .gitignore 排除 Token 文件 - 更新 gitea-api-guide.md 新增 CLI 用法和标签体系文档 - Gitea 上初始化 23 个 Labels + 8 个 Issues + 依赖链 - 16/16 API 接口验证全部通过（含 UTF-8 中文编码）
2026-06-05 19:07:37 +08:00
parent 0dfc90cfdf
commit eee3a4925c
6 changed files with 1370 additions and 3 deletions
@@ -0,0 +1,291 @@
+# Gitea API 访问指南
+
+> 最后更新：2026-06-05
+> 适用项目：ChildHood (starmen1265/ChildHood)
+
+---
+
+## 基本信息
+
+| 项目 | 值 |
+|------|-----|
+| Gitea 版本 | 1.23.4 |
+| Web 面板 | `http://micecola.top:8418` |
+| SSH 端口 | 2223 |
+| SSH 用户 | `sc-gitea` |
+| API 基地址 | `http://micecola.top:8418/api/v1` |
+| 仓库 API 路径 | `/repos/starmen1265/ChildHood` |
+
+## Agent 账号
+
+| 账号 | 用途 | 认证方式 |
+|------|------|----------|
+| `starmen1265` | 主开发者（用户） | 密码 + SSH |
+| `ai-pm` | PM Agent | SSH Key + API Token |
+| `ai-designer` | 策划 Agent | 待配置 |
+| `ai-artist` | 美术 Agent | 待配置 |
+
+---
+
+## SSH 配置
+
+PM Agent 的 SSH 密钥已配置在 `~/.ssh/id_ed25519_childhood_pm`。
+
+现有 SSH Config（`~/.ssh/config`）：
+
+```
+Host gitea micecola.top
+    HostName micecola.top
+    Port 2223
+    User sc-gitea
+    IdentityFile ~/.ssh/id_ed25519_gitea
+    IdentitiesOnly yes
+```
+
+> **注意**：当前 SSH Config 指向 `sc-gitea` 用户的密钥。如需用 `ai-pm` 身份操作，Git 命令需指定密钥：
+> ```
+> GIT_SSH_COMMAND="ssh -i ~/.ssh/id_ed25519_childhood_pm -p 2223" git push
+> ```
+
+---
+
+## API 访问方式
+
+### ⚠️ 重要：不要用 curl 发送中文
+
+Windows 环境下 curl 发送中文 JSON 会出现编码错误（GBK/UTF-8 冲突），导致内容乱码。
+
+**正确做法：使用 Python urllib**
+
+```python
+import urllib.request
+import json
+
+API_BASE = "http://micecola.top:8418/api/v1"
+REPO_PATH = "/repos/starmen1265/ChildHood"
+TOKEN = "<your-api-token>"
+
+def gitea_api(method, path, data=None):
+    """发送 Gitea API 请求
+
+    Args:
+        method: GET / POST / PATCH / DELETE
+        path: API 路径（如 /issues/1）
+        data: 请求体（dict），None 则无 body
+    Returns:
+        API 响应（dict）
+    """
+    url = f"{API_BASE}{REPO_PATH}{path}"
+    body = json.dumps(data).encode('utf-8') if data else None
+    req = urllib.request.Request(url, data=body, headers={
+        'Authorization': f'token {TOKEN}',
+        'Content-Type': 'application/json; charset=utf-8'
+    }, method=method)
+    resp = urllib.request.urlopen(req, timeout=10)
+    return json.loads(resp.read().decode('utf-8'))
+```
+
+### API Token
+
+各 Agent 账号的 Token 存储位置：
+
+| Agent | Token 获取位置 |
+|-------|---------------|
+| `ai-pm` | Gitea → ai-pm 设置 → 应用 → Access Token |
+
+> **安全提醒**：Token 不应硬编码在代码中。当前会话中由用户提供，每次新会话需重新获取或从安全存储读取。
+
+---
+
+## 常用 API 操作
+
+### Issues
+
+```python
+# 列出所有 Issue（含已关闭）
+issues = gitea_api('GET', '/issues?state=all')
+
+# 列出某个里程碑下的 Issue
+issues = gitea_api('GET', '/issues?milestones=2')
+
+# 创建 Issue（关联里程碑）
+gitea_api('POST', '/issues', {
+    'title': '任务标题',
+    'body': '任务描述（支持 Markdown）',
+    'milestone': 2,       # 里程碑 ID
+    'assignees': ['ai-pm'] # 指派人（可选）
+})
+
+# 修改 Issue
+gitea_api('PATCH', '/issues/1', {
+    'title': '新标题',
+    'body': '新内容',
+    'state': 'closed'     # 关闭 Issue
+})
+
+# Issue 添加评论
+gitea_api('POST', '/issues/1/comments', {
+    'body': '评论内容'
+})
+```
+
+### Milestones（里程碑）
+
+```python
+# 列出所有里程碑
+milestones = gitea_api('GET', '/milestones')
+
+# 创建里程碑
+gitea_api('POST', '/milestones', {
+    'title': 'v0.2-小游戏',
+    'description': '验证小游戏核心循环',
+    'state': 'open'
+})
+
+# 修改里程碑
+gitea_api('PATCH', '/milestones/2', {
+    'title': '新标题',
+    'state': 'closed'
+})
+```
+
+### Labels（标签）
+
+```python
+# 列出标签
+labels = gitea_api('GET', '/labels')
+
+# 创建标签
+gitea_api('POST', '/labels', {
+    'name': '执行案',
+    'color': '#0052cc'    # 十六进制颜色（不带 # 也行）
+})
+
+# 给 Issue 添加标签
+gitea_api('POST', '/issues/1/labels', {
+    'labels': [1, 2]      # 标签 ID 列表
+})
+```
+
+---
+
+## 已知限制
+
+### Projects（项目看板）无 REST API
+
+Gitea 1.23.4 **不支持** 项目看板的 REST API，端点返回 404。
+
+- 功能请求追踪：[go-gitea/gitea#36824](https://github.com/go-gitea/gitea/issues/36824)
+- 升级 Gitea 版本**不会**解决此问题（截至 2026-06，该功能尚未实现）
+- 看板列的操作（如将 Issue 拖入 Backlog/To Do/In Progress/Done 列）只能通过 Web 页面手动完成
+
+**替代方案**：使用 Issue 的 **状态**（open/closed）+ **标签** 追踪进度，看板仅作为可视化展示。
+
+### 当前看板
+
+- 看板地址：`http://micecola.top:8418/starmen1265/ChildHood/projects/2`
+- 看板名称：**原型制作**
+- 列结构：`Backlog → To Do → In Progress → Done`
+
+---
+
+## CLI 工具（推荐）
+
+> 自 2026-06-05 起，所有 Agent 统一使用 CLI 工具操作 Gitea，不再直接使用 curl。
+
+### 工具位置
+
+`scripts/gitea.js` — Node.js CLI，封装所有 API 操作，自动处理 UTF-8 编码。
+
+### Token 管理
+
+Token 存储在 `scripts/.gitea-tokens.json`（已加入 `.gitignore`），每台机器配置一次。
+
+```json
+{
+  "pm": "<ai-pm 的 API Token>",
+  "designer": "<ai-designer 的 API Token>",
+  "dev": "<ai-dev 的 API Token>"
+}
+```
+
+**Token 优先级**: `GITEA_TOKEN` 环境变量 > `--role <role>` 文件读取 > 报错
+
+两台机器使用同一套 Token，只需将此文件拷贝到对应机器的 `scripts/` 目录下。
+
+### 用法
+
+```bash
+# Agent 调用（通过 --role 自动选 Token，无需手动传 Token）
+node scripts/gitea.js --role pm issue list --milestone v0.1-基础交互
+node scripts/gitea.js --role designer issue comment 2 --body "汇报内容"
+node scripts/gitea.js --role dev pipeline status
+
+# 查看所有命令
+node scripts/gitea.js --help
+
+# 常用操作（以 --role pm 为例）
+node scripts/gitea.js --role pm issue list --milestone v0.1-基础交互
+node scripts/gitea.js --role pm issue get <number>
+node scripts/gitea.js --role pm issue create --title "P-XXX 标题" --body "..." --milestone 2
+node scripts/gitea.js --role pm issue close <number>
+node scripts/gitea.js --role pm issue comment <number> --body "汇报内容"
+node scripts/gitea.js --role pm issue labels <number> --set <id,...>
+node scripts/gitea.js --role pm issue block <blocker> <blocked>
+
+node scripts/gitea.js --role pm milestone list
+node scripts/gitea.js --role pm label list
+node scripts/gitea.js label init     # 初始化标准标签体系
+
+node scripts/gitea.js pipeline status
+node scripts/gitea.js pipeline update <tracker-number> --step <1-7> --status "描述"
+
+node scripts/gitea.js test           # 验证所有 API 接口
+
+# --json 标志输出纯 JSON（供脚本解析）
+node scripts/gitea.js issue list --json
+```
+
+### 标准标签体系（23 个）
+
+| 类别 | 标签 | 用途 |
+|------|------|------|
+| status | `status:backlog` `status:ready` `status:in-progress` `status:blocked` `status:in-review` `status:done` | 任务生命周期 |
+| pipeline | `pipeline:3-execution` `pipeline:4-tech-design` `pipeline:5-art` `pipeline:6-impl` `pipeline:7-retro` | 流水线步骤 |
+| role | `role:design` `role:dev` `role:art` `role:pm` | 角色归属 |
+| gate | `gate:execution-pass/fail` `gate:tech-pass/fail` `gate:art-pass/fail` `gate:impl-pass/fail` | 质量门判定 |
+
+### API 客户端模块
+
+`scripts/gitea-api.js` — Node.js 模块，提供 `GiteaAPI` 类。可供自定义脚本引用：
+
+```javascript
+const { GiteaAPI } = require('./gitea-api');
+const api = new GiteaAPI('your-token');
+const issues = await api.listIssues({ state: 'open' });
+```
+
+---
+
+## 当前里程碑与 Issue 状态
+
+> 最后更新：2026-06-05
+
+### 里程碑
+
+| ID | 标题 | 状态 |
+|----|------|------|
+| 2 | v0.1-基础交互 | open |
+
+### Issues（v0.1-基础交互）
+
+| # | 标题 | 标签 | 状态 | 依赖 |
+|---|------|------|------|------|
+| 9 | P-001 原型阶段启动准备 | role:pm, status:done | ✅ 已完成 | — |
+| 2 | P-002a 交互系统执行案 | status:blocked, pipeline:3, role:design, gate:execution-fail | 🔴 质量门未通过 | — |
+| 1 | P-002b 收集系统执行案 | status:blocked, pipeline:3, role:design, gate:execution-fail | 🔴 质量门未通过 | — |
+| 3 | P-002c 角色控制执行案 | status:blocked, pipeline:3, role:design, gate:execution-fail | 🔴 质量门未通过 | — |
+| 10 | P-003 v0.1 ④程序设计 | status:backlog, pipeline:4, role:dev | ⬜ Backlog | #1, #2, #3 |
+| 11 | P-004 v0.1 ⑤美术 + ⑥程序实现 | status:backlog, role:dev, role:art | ⬜ Backlog | #10 |
+| 12 | P-005 v0.1 ⑦版本复盘 | status:backlog, pipeline:7, role:pm | ⬜ Backlog | #11 |
+| 8 | Pipeline Tracker — v0.1 | role:pm, status:in-progress | 🔄 流水线追踪 | — |