ChildHood/.claude/skills/gitea-collab.md

name, description

name	description
gitea-collab	Gitea 协作工具 — CLI 命令速查、认证机制、标签体系、Issue/Milestone/Pipeline 操作规范、角色汇报模板

Gitea 协作工具

本 skill 封装 ChildHood 项目基于 Gitea 的进度管理全部实现细节。 Agent 文件只描述项目管理的逻辑（做什么），本文件描述实现细节（怎么做）。 未来若更换项目管理后端，只需替换本 skill，Agent 逻辑无需修改。

---

1. CLI 工具

工具路径: node scripts/gitea.js <command> [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

# 列出 Issue
node scripts/gitea.js --role <role> issue list --milestone <标题> [--state open|closed|all] [--labels <id,...>] [--json]

# 查看 Issue 详情
node scripts/gitea.js --role <role> issue get <number> [--json]

# 创建 Issue
node scripts/gitea.js --role <role> issue create --title "..." --body "..." --milestone <id>

# 更新 Issue
node scripts/gitea.js --role <role> issue update <number> --title "..." --body "..."

# 关闭 Issue
node scripts/gitea.js --role <role> issue close <number> [--body "关闭说明"]

# 重新打开 Issue
node scripts/gitea.js --role <role> issue reopen <number>

# 评论
node scripts/gitea.js --role <role> issue comment <number> --body "评论内容"

# 查看评论
node scripts/gitea.js --role <role> issue comments <number> [--json]

# 设置标签
node scripts/gitea.js --role <role> issue labels <number> --set <id,id,...>

# 依赖关系
node scripts/gitea.js --role <role> issue deps <number>

# 阻塞关系
node scripts/gitea.js --role <role> issue block <blocker_number> <blocked_number>
node scripts/gitea.js --role <role> issue unblock <blocker_number> <blocked_number>

milestone

# 列出里程碑
node scripts/gitea.js --role <role> milestone list [--state open|closed|all] [--json]

# 创建里程碑
node scripts/gitea.js --role <role> milestone create --title "..." --description "..."

# 更新里程碑
node scripts/gitea.js --role <role> milestone update <id> --title "..." --description "..." --due "YYYY-MM-DD"

label

# 列出标签
node scripts/gitea.js --role <role> label list [--json]

# 创建标签
node scripts/gitea.js --role <role> label create --name "..." --color "#hex"

# 初始化标准标签体系
node scripts/gitea.js --role <role> label init

pipeline

# 初始化 Pipeline Tracker Meta Issue
node scripts/gitea.js --role <role> pipeline init

# 查看 Pipeline 状态
node scripts/gitea.js --role <role> pipeline status

# 更新 Pipeline 步骤状态
node scripts/gitea.js --role <role> pipeline update <tracker_number> --step <1-7> --status "状态描述"

test

# 运行 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 <number> --step <1-7> --status "描述"

---

8. 角色汇报模板

各角色完成工作后，在对应 Issue 下评论汇报。

策划汇报

node scripts/gitea.js --role designer issue comment <number> --body "## 策划汇报 — YYYY-MM-DD

**任务ID**: D-XXX
**状态**: 进行中 / 已完成
**产出**: path/to/output

### 完成内容
- ...

### 待确认
- ..."

程序汇报

node scripts/gitea.js --role dev issue comment <number> --body "## 程序汇报 — YYYY-MM-DD

**任务ID**: P-XXX
**状态**: 进行中 / 已完成
**产出**: path/to/output

### 完成内容
- ...

### 偏差/问题
- ..."

PM 审查后

# 发布审查摘要评论
node scripts/gitea.js --role pm issue comment <number> --body "审查结论..."

# 更新标签反映质量门结果
node scripts/gitea.js --role pm issue labels <number> --set <gate-pass|gate-fail>,<status-*>,...

---

9. PM 会话启动命令序列

PM 在每次会话启动时按序执行：

# 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 <number>

---

10. PM 任务管理命令序列

创建任务

# 创建 Issue
node scripts/gitea.js --role pm issue create \
  --title "P-XXX 任务标题" \
  --body "## 任务信息\n- **任务ID**: P-XXX\n- **所属版本**: vX.X\n..." \
  --milestone <id>

# 设置标签
node scripts/gitea.js --role pm issue labels <number> --set <label_ids>

# 设置依赖
node scripts/gitea.js --role pm issue block <blocker_number> <new_number>

关闭任务

node scripts/gitea.js --role pm issue close <number> --body "## 任务完成 ✔\n**完成日期**: YYYY-MM-DD\n**产出**: path/to/output"

更新流水线

node scripts/gitea.js --role pm pipeline update <tracker_number> --step <1-7> --status "状态描述"

---

11. 其他角色读取命令

程序查看任务

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 <number>

策划查看任务

node scripts/gitea.js --role designer issue list --labels <role-label-id>
node scripts/gitea.js --role designer issue get <number>