# 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 = "" 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": "", "designer": "", "dev": "" } ``` **Token 优先级**: `GITEA_TOKEN` 环境变量 > `--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 node scripts/gitea.js --role pm issue create --title "P-XXX 标题" --body "..." --milestone 2 node scripts/gitea.js --role pm issue close node scripts/gitea.js --role pm issue comment --body "汇报内容" node scripts/gitea.js --role pm issue labels --set node scripts/gitea.js --role pm issue block 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 --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 | 🔄 流水线追踪 | — |