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

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

# 列出所有 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（里程碑）

# 列出所有里程碑
milestones = gitea_api('GET', '/milestones')

# 创建里程碑
gitea_api('POST', '/milestones', {
    'title': 'v0.2-小游戏',
    'description': '验证小游戏核心循环',
    'state': 'open'
})

# 修改里程碑
gitea_api('PATCH', '/milestones/2', {
    'title': '新标题',
    'state': 'closed'
})

Labels（标签）

# 列出标签
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
• 升级 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），每台机器配置一次。

{
  "pm": "<ai-pm 的 API Token>",
  "designer": "<ai-designer 的 API Token>",
  "dev": "<ai-dev 的 API Token>"
}

Token 优先级: GITEA_TOKEN 环境变量 > --role <role> 文件读取 > 报错

两台机器使用同一套 Token，只需将此文件拷贝到对应机器的 scripts/ 目录下。

用法

# 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 类。可供自定义脚本引用：

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