ChildHood/docs/technical/Gitea API 指南.md

# 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 | 🔄 流水线追踪 | — |