--- name: "gitea-collab" description: "Gitea 协作工具 — CLI 命令速查、认证机制、标签体系、Issue/Milestone/Pipeline 操作规范、角色汇报模板" --- # Gitea 协作工具 > 本 skill 封装 ChildHood 项目基于 Gitea 的进度管理全部实现细节。 > Agent 文件只描述项目管理的逻辑(做什么),本文件描述实现细节(怎么做)。 > 未来若更换项目管理后端,只需替换本 skill,Agent 逻辑无需修改。 --- ## 1. CLI 工具 **工具路径**: `node scripts/gitea.js [subcommand] [options]` **API 封装**: `scripts/gitea-api.js`(GiteaAPI 类,HTTP REST 调用) **服务端**: `micecola.top:8418`,仓库 `starmen1265/ChildHood` **`--json` 标志**: 所有命令支持 `--json` 输出纯 JSON,供脚本解析。 --- ## 2. 认证机制 通过 `--role <角色>` 参数自动从 `scripts/.gitea-tokens.json` 读取对应 Token,无需手动传 `GITEA_TOKEN`。 | 角色 | `--role` 值 | 适用 Agent | |------|------------|-----------| | 策划 | `designer` | game-designer | | 程序 | `dev` | game-dev | | 美术 | `artist` | (暂无独立 Agent) | | PM | `pm` | game-pm | --- ## 3. 标签体系 23 个标准标签,通过 `node scripts/gitea.js label init` 初始化。 ### 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` | PM | ### gate(质量门判定) | 标签 | 含义 | |------|------| | `gate:execution-pass` | 执行案质量门通过 | | `gate:execution-fail` | 执行案质量门未通过 | | `gate:tech-pass` | 程序设计质量门通过 | | `gate:tech-fail` | 程序设计质量门未通过 | | `gate:art-pass` | 美术资产验收门通过 | | `gate:art-fail` | 美术资产验收门未通过 | | `gate:impl-pass` | 程序实现验收门通过 | | `gate:impl-fail` | 程序实现验收门未通过 | --- ## 4. 命令速查 ### issue ```bash # 列出 Issue node scripts/gitea.js --role issue list --milestone <标题> [--state open|closed|all] [--labels ] [--json] # 查看 Issue 详情 node scripts/gitea.js --role issue get [--json] # 创建 Issue node scripts/gitea.js --role issue create --title "..." --body "..." --milestone # 更新 Issue node scripts/gitea.js --role issue update --title "..." --body "..." # 关闭 Issue node scripts/gitea.js --role issue close [--body "关闭说明"] # 重新打开 Issue node scripts/gitea.js --role issue reopen # 评论 node scripts/gitea.js --role issue comment --body "评论内容" # 查看评论 node scripts/gitea.js --role issue comments [--json] # 设置标签 node scripts/gitea.js --role issue labels --set # 依赖关系 node scripts/gitea.js --role issue deps # 阻塞关系 node scripts/gitea.js --role issue block node scripts/gitea.js --role issue unblock ``` ### milestone ```bash # 列出里程碑 node scripts/gitea.js --role milestone list [--state open|closed|all] [--json] # 创建里程碑 node scripts/gitea.js --role milestone create --title "..." --description "..." # 更新里程碑 node scripts/gitea.js --role milestone update --title "..." --description "..." --due "YYYY-MM-DD" ``` ### label ```bash # 列出标签 node scripts/gitea.js --role label list [--json] # 创建标签 node scripts/gitea.js --role label create --name "..." --color "#hex" # 初始化标准标签体系 node scripts/gitea.js --role label init ``` ### pipeline ```bash # 初始化 Pipeline Tracker Meta Issue node scripts/gitea.js --role pipeline init # 查看 Pipeline 状态 node scripts/gitea.js --role pipeline status # 更新 Pipeline 步骤状态 node scripts/gitea.js --role pipeline update --step <1-7> --status "状态描述" ``` ### test ```bash # 运行 API 连通性测试(P0 + P1) node scripts/gitea.js test ``` --- ## 5. 数据映射 | 概念 | Gitea 对应 | 说明 | |------|-----------|------| | 任务 (P-002) | Issue | 标题含任务 ID 前缀 | | 版本 (v0.1) | Milestone | 版本号即里程碑标题 | | 任务状态 | Label (`status:*`) | 6 种状态标签 | | 流水线步骤 | Label (`pipeline:*`) | 5 种步骤标签 | | 角色归属 | Label (`role:*`) | 4 种角色标签 | | 质量门结果 | Label (`gate:*`) | 8 种判定标签 | | 角色汇报 | Issue 评论 | 各角色在对应 Issue 下评论 | | 流水线总览 | Pipeline Tracker Meta Issue | 单个 Issue 记录全局流水线状态 | | 审查记录 | Issue 评论(摘要+链接)+ 本地 `docs/plans/reviews/` | 本地保留详细结构化文档 | | 任务归档 | close Issue | 不需要本地 archive 文件 | --- ## 6. 任务 ID 规范 格式:`[角色前缀]-[三位数字]` | 前缀 | 角色 | 示例 | |------|------|------| | `D` | 策划 (Design) | `D-001` | | `P` | 程序 (Programmer) | `P-002` | | `A` | 美术 (Artist) | `A-003` | 每个前缀从 001 独立编号。Issue 标题需包含任务 ID 前缀。 --- ## 7. Pipeline Tracker Pipeline Tracker 是一个 **Meta Issue**,用于记录当前版本的全局流水线状态。 - 初始化:`pipeline init`(阶段开始时执行一次) - 查看状态:`pipeline status` - 更新步骤:`pipeline update --step <1-7> --status "描述"` --- ## 8. 角色汇报模板 各角色完成工作后,在对应 Issue 下评论汇报。 ### 策划汇报 ```bash node scripts/gitea.js --role designer issue comment --body "## 策划汇报 — YYYY-MM-DD **任务ID**: D-XXX **状态**: 进行中 / 已完成 **产出**: path/to/output ### 完成内容 - ... ### 待确认 - ..." ``` ### 程序汇报 ```bash node scripts/gitea.js --role dev issue comment --body "## 程序汇报 — YYYY-MM-DD **任务ID**: P-XXX **状态**: 进行中 / 已完成 **产出**: path/to/output ### 完成内容 - ... ### 偏差/问题 - ..." ``` ### PM 审查后 ```bash # 发布审查摘要评论 node scripts/gitea.js --role pm issue comment --body "审查结论..." # 更新标签反映质量门结果 node scripts/gitea.js --role pm issue labels --set ,,... ``` --- ## 9. PM 会话启动命令序列 PM 在每次会话启动时按序执行: ```bash # 1. 读取当前里程碑 node scripts/gitea.js --role pm milestone list --state open # 2. 读取活跃任务 node scripts/gitea.js --role pm issue list --milestone <当前版本> # 3. 读取流水线状态 node scripts/gitea.js --role pm pipeline status # 4. 读取近期评论(按需) node scripts/gitea.js --role pm issue comments ``` --- ## 10. PM 任务管理命令序列 ### 创建任务 ```bash # 创建 Issue node scripts/gitea.js --role pm issue create \ --title "P-XXX 任务标题" \ --body "## 任务信息\n- **任务ID**: P-XXX\n- **所属版本**: vX.X\n..." \ --milestone # 设置标签 node scripts/gitea.js --role pm issue labels --set # 设置依赖 node scripts/gitea.js --role pm issue block ``` ### 关闭任务 ```bash node scripts/gitea.js --role pm issue close --body "## 任务完成 ✔\n**完成日期**: YYYY-MM-DD\n**产出**: path/to/output" ``` ### 更新流水线 ```bash node scripts/gitea.js --role pm pipeline update --step <1-7> --status "状态描述" ``` --- ## 11. 其他角色读取命令 ### 程序查看任务 ```bash node scripts/gitea.js --role dev pipeline status node scripts/gitea.js --role dev issue list --milestone <当前版本> node scripts/gitea.js --role dev issue get ``` ### 策划查看任务 ```bash node scripts/gitea.js --role designer issue list --labels node scripts/gitea.js --role designer issue get ```