starmen1265
6ba07318be
- 简化 game-pm：删除质量门审查和风险检测，改为进度检查+任务分配调度器 - 重写 game-reviewer：改为子代理模式，角色完成工作后自行启动，使用 ai-reviewer 账号 - 新增 project-initializer 技能：项目冷启动初始化 - 新增 stage-sketch/roadmap/iteration 技能：3 阶段任务序列管理 - 修改 game-designer/game-dev：添加审查交接流程 - 更新 gitea-collab/quality-gate-review/development-workflow - gitea.js：添加 reviewer 角色 + 5 个新标签（review:pass/fail, stage:sketch/roadmap/iteration）
399 lines
11 KiB
Markdown
399 lines
11 KiB
Markdown
---
|
||
name: "gitea-collab"
|
||
description: "Gitea 协作工具 — CLI 命令速查、认证机制、Assignee 映射、标签体系、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 |
|
||
| 审查 | `reviewer` | game-reviewer |
|
||
|
||
---
|
||
|
||
## 3. Assignee 映射
|
||
|
||
创建任务时通过 `--assignees` 指派给对应角色的 Gitea 用户。
|
||
|
||
| 角色 | `--assignees` 值 | 任务 ID 前缀 |
|
||
|------|-----------------|-------------|
|
||
| 策划 | `ai-designer` | `D-XXX` |
|
||
| 程序 | `ai-programmer` | `P-XXX` |
|
||
| 美术 | `ai-artist` | `A-XXX` |
|
||
| PM | `ai-pm` | （管理任务） |
|
||
| 审查 | `ai-reviewer` | （审查操作，不拥有任务） |
|
||
|
||
---
|
||
|
||
## 4. 标签体系
|
||
|
||
19 个标准标签，通过 `node scripts/gitea.js label init` 初始化。
|
||
|
||
### status（任务状态）
|
||
| 标签 | 含义 |
|
||
|------|------|
|
||
| `status:backlog` | 待处理 |
|
||
| `status:ready` | 已就绪，可开始 |
|
||
| `status:in-progress` | 进行中 |
|
||
| `status:blocked` | 被阻塞 |
|
||
| `status:in-review` | 待审查（角色完成工作后设置） |
|
||
| `status:done` | 已完成 |
|
||
|
||
### gate（质量门判定 — 旧标签，保留用于历史 Issue）
|
||
| 标签 | 含义 |
|
||
|------|------|
|
||
| `gate:execution-pass/fail` | 执行案质量门 |
|
||
| `gate:tech-pass/fail` | 程序设计质量门 |
|
||
| `gate:art-pass/fail` | 美术资产验收门 |
|
||
| `gate:impl-pass/fail` | 程序实现验收门 |
|
||
|
||
> 新工作流使用 `review:*` 标签替代 `gate:*`。旧 Issue 上的 gate 标签保留不动。
|
||
|
||
### review（审查结果 — 新标签）
|
||
| 标签 | 含义 |
|
||
|------|------|
|
||
| `review:pass` | 审查已通过 ✅ |
|
||
| `review:fail` | 审查未通过 ❌ |
|
||
|
||
### stage（开发阶段 — 新标签）
|
||
| 标签 | 含义 |
|
||
|------|------|
|
||
| `stage:sketch` | 草图阶段任务 |
|
||
| `stage:roadmap` | 总路线阶段任务 |
|
||
| `stage:iteration` | 迭代阶段任务 |
|
||
|
||
> **注**：`pipeline:*` 和 `role:*` 标签已废弃并从 Gitea 上删除。如旧 Issue 上仍残留这些标签，忽略即可。
|
||
|
||
---
|
||
|
||
## 5. 命令速查
|
||
|
||
### issue
|
||
|
||
```bash
|
||
# 列出 Issue（支持按 assignee 过滤）
|
||
node scripts/gitea.js --role <role> issue list --milestone <标题> [--state open|closed|all] [--labels <id,...>] [--assigned <用户名>] [--json]
|
||
|
||
# 查看 Issue 详情
|
||
node scripts/gitea.js --role <role> issue get <number> [--json]
|
||
|
||
# 创建 Issue（必须指定 assignees）
|
||
node scripts/gitea.js --role <role> issue create --title "..." --body "..." --milestone <id> --assignees <用户名,...>
|
||
|
||
# 更新 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
|
||
|
||
```bash
|
||
# 列出里程碑
|
||
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
|
||
|
||
```bash
|
||
# 列出标签
|
||
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
|
||
|
||
```bash
|
||
# 初始化 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
|
||
|
||
```bash
|
||
# 运行 API 连通性测试（P0 + P1）
|
||
node scripts/gitea.js test
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 数据映射
|
||
|
||
| 概念 | Gitea 对应 | 说明 |
|
||
|------|-----------|------|
|
||
| 任务 (P-002) | Issue | 标题含任务 ID 前缀 |
|
||
| 阶段/版本 | Milestone | 阶段名或版本号作为里程碑标题 |
|
||
| 任务状态 | Label (`status:*`) | 6 种状态标签 |
|
||
| 审查结果 | Label (`review:*`) | 通过/未通过 |
|
||
| 开发阶段 | Label (`stage:*`) | 草图/总路线/迭代 |
|
||
| 质量门结果 | Label (`gate:*`) | 旧标签，保留用于历史 Issue |
|
||
| 角色归属 | Assignee | 通过 `--assignees` 指派 |
|
||
| 当前进度 | Pipeline Tracker | Meta Issue 记录当前阶段和进度 |
|
||
| 角色汇报 | Issue 评论 | 各角色在对应 Issue 下评论 |
|
||
| 审查记录 | Issue 评论（摘要+链接）+ 本地 `docs/plans/reviews/` | 本地文件名格式 `<任务ID>-审查记录.md` |
|
||
| 任务归档 | close Issue | 用户确认后由 PM 关闭 |
|
||
|
||
---
|
||
|
||
## 7. 任务 ID 规范
|
||
|
||
格式：`[角色前缀]-[三位数字]`
|
||
|
||
| 前缀 | 角色 | 示例 |
|
||
|------|------|------|
|
||
| `D` | 策划 (Design) | `D-001` |
|
||
| `P` | 程序 (Programmer) | `P-002` |
|
||
| `A` | 美术 (Artist) | `A-003` |
|
||
|
||
每个前缀从 001 独立编号。Issue 标题需包含任务 ID 前缀。
|
||
|
||
---
|
||
|
||
## 8. Pipeline Tracker
|
||
|
||
Pipeline Tracker 是一个 **Meta Issue**，用于记录项目当前阶段和进度。
|
||
|
||
### Tracker 正文格式
|
||
|
||
```markdown
|
||
# 流水线进度追踪
|
||
|
||
## 当前阶段
|
||
草图阶段 / 总路线阶段 / 迭代阶段
|
||
|
||
## 当前里程碑
|
||
- 名称: <milestone title>
|
||
- 状态: open/closed
|
||
- Open Issues: X
|
||
- Closed Issues: Y
|
||
|
||
## 阶段历史
|
||
| 阶段 | 里程碑 | 进入日期 | 完成日期 |
|
||
|------|--------|----------|----------|
|
||
| 草图阶段 | 草图阶段 | YYYY-MM-DD | — |
|
||
```
|
||
|
||
### 相关命令
|
||
|
||
- 初始化：`pipeline init`
|
||
- 查看状态：`pipeline status`
|
||
- 更新步骤：`pipeline update <number> --step <1-7> --status "描述"`
|
||
- 阶段转换时直接编辑 Issue 正文更新「当前阶段」和「阶段历史」
|
||
|
||
---
|
||
|
||
## 9. 角色汇报模板
|
||
|
||
各角色完成工作后，在对应 Issue 下评论汇报。
|
||
|
||
### 策划汇报
|
||
|
||
```bash
|
||
node scripts/gitea.js --role designer issue comment <number> --body "## 策划汇报 — YYYY-MM-DD
|
||
|
||
**任务ID**: D-XXX
|
||
**状态**: 进行中 / 已完成
|
||
**产出**: path/to/output
|
||
|
||
### 完成内容
|
||
- ...
|
||
|
||
### 待确认
|
||
- ..."
|
||
```
|
||
|
||
### 程序汇报
|
||
|
||
```bash
|
||
node scripts/gitea.js --role dev issue comment <number> --body "## 程序汇报 — YYYY-MM-DD
|
||
|
||
**任务ID**: P-XXX
|
||
**状态**: 进行中 / 已完成
|
||
**产出**: path/to/output
|
||
|
||
### 完成内容
|
||
- ...
|
||
|
||
### 偏差/问题
|
||
- ..."
|
||
```
|
||
|
||
### 审查修改后汇报（审查退回修改后使用）
|
||
|
||
```bash
|
||
node scripts/gitea.js --role <role> issue comment <number> --body "## 修改汇报 — YYYY-MM-DD
|
||
|
||
**任务ID**: <ID>
|
||
**修改原因**: 质量门审查退回
|
||
|
||
### 修改内容
|
||
- [对应审查意见第X条]：[具体修改内容]
|
||
|
||
### 修改后产出
|
||
- path/to/output"
|
||
```
|
||
|
||
### PM 确认关闭任务（审查通过后）
|
||
|
||
```bash
|
||
# 用户确认后关闭 Issue
|
||
node scripts/gitea.js --role pm issue close <number> --body "## 任务完成 ✔
|
||
|
||
**完成日期**：YYYY-MM-DD
|
||
**产出**：path/to/output
|
||
**审查记录**：docs/plans/reviews/<task-ID>-审查记录.md"
|
||
```
|
||
|
||
---
|
||
|
||
## 10. PM 会话启动命令序列
|
||
|
||
PM 在每次会话启动时按序执行：
|
||
|
||
```bash
|
||
# 1. 读取 Pipeline Tracker（确定当前阶段）
|
||
node scripts/gitea.js --role pm pipeline status
|
||
|
||
# 2. 读取当前里程碑
|
||
node scripts/gitea.js --role pm milestone list --state open
|
||
|
||
# 3. 读取活跃任务
|
||
node scripts/gitea.js --role pm issue list --state open
|
||
|
||
# 4. 根据阶段调用对应技能：
|
||
# 无进度 → project-initializer
|
||
# 草图阶段 → stage-sketch
|
||
# 总路线阶段 → stage-roadmap
|
||
# 迭代阶段 → stage-iteration
|
||
|
||
# 5. 检查 review:pass 标签的 Issue → 请示用户是否关闭
|
||
```
|
||
|
||
---
|
||
|
||
## 11. PM 任务管理命令序列
|
||
|
||
### 创建任务
|
||
|
||
```bash
|
||
# 创建 Issue（必须指定 assignees 和 stage 标签）
|
||
node scripts/gitea.js --role pm issue create \
|
||
--title "D-001 概念设计" \
|
||
--body "## 任务信息\n- **任务ID**: D-001\n- **所属阶段**: 草图阶段\n- **角色**: 策划\n- **预期产出**: docs/design/概念草案.md\n..." \
|
||
--milestone <id> \
|
||
--assignees ai-designer
|
||
|
||
# 设置标签（status + stage + role）
|
||
node scripts/gitea.js --role pm issue labels <number> --set <status-label-id>,<stage-label-id>,<role-label-id>
|
||
|
||
# 设置依赖
|
||
node scripts/gitea.js --role pm issue block <blocker_number> <new_number>
|
||
```
|
||
|
||
### 关闭任务（用户确认后）
|
||
|
||
```bash
|
||
# 审查通过 + 用户确认关闭后
|
||
node scripts/gitea.js --role pm issue close <number> --body "## 任务完成 ✔\n**完成日期**: YYYY-MM-DD\n**产出**: path/to/output\n**审查记录**: docs/plans/reviews/<task-ID>-审查记录.md"
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 其他角色读取命令
|
||
|
||
### 程序查看任务
|
||
|
||
```bash
|
||
# 查看分配给自己的任务
|
||
node scripts/gitea.js --role dev issue list --assigned ai-programmer --milestone <当前版本>
|
||
|
||
# 查看流水线状态
|
||
node scripts/gitea.js --role dev pipeline status
|
||
|
||
# 查看 Issue 详情
|
||
node scripts/gitea.js --role dev issue get <number>
|
||
```
|
||
|
||
### 策划查看任务
|
||
|
||
```bash
|
||
# 查看分配给自己的任务
|
||
node scripts/gitea.js --role designer issue list --assigned ai-designer --milestone <当前版本>
|
||
|
||
# 查看 Issue 详情
|
||
node scripts/gitea.js --role designer issue get <number>
|
||
```
|
||
|
||
### 美术查看任务
|
||
|
||
```bash
|
||
# 查看分配给自己的任务
|
||
node scripts/gitea.js --role artist issue list --assigned ai-artist --milestone <当前版本>
|
||
|
||
# 查看 Issue 详情
|
||
node scripts/gitea.js --role artist issue get <number>
|
||
```
|