173 lines
5.9 KiB
Markdown
173 lines
5.9 KiB
Markdown
---
|
||
name: issue-drive
|
||
description: 归集证据并把问题拆成 1 到多张 Gitea issue，支持从当前仓库 origin 自动识别仓库或用户显式指定，并通过环境变量配置的 Gitea API 批量创建工单。
|
||
---
|
||
|
||
# Issue Drive - 通用 Gitea 问题拆单与创建
|
||
|
||
> **定位**：不是“查看 issue”，而是把一个真实问题沉淀成可执行的 Gitea issue。适合“线上出 bug 了”“要把一个需求拆成工单”“需要补齐工程治理任务”这类场景。
|
||
>
|
||
> 如果用户只是想查 issue 列表或详情，用 `issue`。如果用户想通过统一入口完成 issue / push / PR 组合操作，用 `gitea`。
|
||
|
||
当用户调用 `/issue-drive`、`$issue-drive`，或自然语言要求“拆 issue”“提 issue”“把问题沉淀成 Gitea 工单”时，执行以下步骤。
|
||
|
||
## 1. 先确定目标仓库
|
||
|
||
目标仓库按以下优先级确定：
|
||
|
||
1. 用户显式给出的完整仓库 URL：`https://git.example.com/owner/repo`
|
||
2. 用户显式给出的仓库简写：`owner/repo`，此时需要 `GITEA_BASE_URL`
|
||
3. 当前项目的 `git remote get-url origin`
|
||
|
||
解析规则：
|
||
|
||
- 支持 `https://host[/prefix]/owner/repo`
|
||
- 支持 `git@host:owner/repo.git`
|
||
- 支持 `git@host:prefix/owner/repo.git`
|
||
- 支持 `ssh://git@host/owner/repo.git`
|
||
- 当前仓库 `origin` 是 SSH 地址时：
|
||
- 优先使用 `GITEA_BASE_URL`
|
||
- 否则退回 `https://host`
|
||
|
||
如果参数和当前仓库都无法确定目标仓库，停止并提示：
|
||
|
||
```bash
|
||
❌ 无法确定目标仓库
|
||
|
||
请显式指定仓库，例如：
|
||
/issue-drive https://git.example.com/owner/repo
|
||
|
||
或配置：
|
||
export GITEA_BASE_URL=https://git.example.com
|
||
```
|
||
|
||
## 2. 检查环境变量
|
||
|
||
先读取环境变量：
|
||
|
||
- `GITEA_TOKEN`：必需，创建 issue 时使用
|
||
- `GITEA_BASE_URL`：可选；仓库简写或 SSH origin 时推荐配置
|
||
|
||
如果缺少 `GITEA_TOKEN`，输出：
|
||
|
||
```bash
|
||
❌ 缺少 GITEA_TOKEN
|
||
|
||
请先在当前 shell 或 .env 中配置：
|
||
export GITEA_TOKEN=your_gitea_token
|
||
```
|
||
|
||
然后停止，不继续创建 issue。
|
||
|
||
## 3. 先读仓库基线和证据
|
||
|
||
不要先写 issue。先确认事实、范围、影响和证据入口。
|
||
|
||
优先读取以下文件；只读存在的那些：
|
||
|
||
1. `docs/ISSUE_WORKFLOW.md`
|
||
2. `.gitea/ISSUE_TEMPLATE/`
|
||
3. `.github/ISSUE_TEMPLATE/`
|
||
4. `README.md`
|
||
5. `doc/`, `docs/` 下与当前问题直接相关的说明、审计、回归、报表文档
|
||
|
||
如果仓库里没有现成 issue 基建，就直接基于用户描述、代码、日志、测试结果和已有文档整理事实，不要因为“模板不完整”而停住。
|
||
|
||
## 4. 判断该用哪种 issue
|
||
|
||
按下面规则分类：
|
||
|
||
- **缺陷 / 异常报告**：已有事实证据，目标是排查、修复、回归
|
||
- **业务需求 / 功能请求**：目标是交付用户价值，需要产品化描述
|
||
- **工程任务 / 重构 / 基建**：目标是稳定性、可观测性、测试、流程、治理
|
||
|
||
标签策略：
|
||
|
||
- 优先复用仓库远端已有标签
|
||
- 如果远端没有对应标签，不要中断；用标题前缀和正文结构表达类型
|
||
- 不要为了建 issue 先去重构整套标签体系
|
||
|
||
## 5. 拆单规则
|
||
|
||
不要默认一张大工单。优先按“可独立修复、可独立验证、可独立关闭”拆。
|
||
|
||
优先拆开的情况：
|
||
|
||
- 现象修复 和 口径 / 文案 / 导出字段修复 是两件事
|
||
- 业务缺陷 和 工程可观测性补齐 是两件事
|
||
- 一个问题需要不同 owner、不同验证方式或不同发布时间
|
||
|
||
## 6. 写 issue 前的最小检查
|
||
|
||
创建 issue 前必须确认：
|
||
|
||
- 标题是否直接表达现象或交付物
|
||
- 正文是否写明：现象、期望、影响范围、证据入口、初步判断、完成标准
|
||
- 事实数字是否已经从本地数据、日志、代码或用户描述中复核
|
||
- 引用的仓库内链接是否已经存在于默认分支
|
||
|
||
如果本次要新建或更新以下文件：
|
||
|
||
- `.gitea/ISSUE_TEMPLATE/*`
|
||
- `.github/ISSUE_TEMPLATE/*`
|
||
- `.gitea/PULL_REQUEST_TEMPLATE.md`
|
||
- `docs/ISSUE_WORKFLOW.md`
|
||
- issue 正文会引用的证据文档
|
||
|
||
先做最小提交并推送到默认分支，再创建 issue。只提交与 issue 基建或证据直接相关的文件，不要顺手带上无关改动。
|
||
|
||
## 7. 用脚本批量创建 issue
|
||
|
||
优先使用本 skill 附带脚本，并按当前平台选择路径：
|
||
|
||
```bash
|
||
# Codex
|
||
python3 .codex/skills/issue-drive/scripts/create_gitea_issues.py /tmp/issues.json --dry-run
|
||
python3 .codex/skills/issue-drive/scripts/create_gitea_issues.py /tmp/issues.json
|
||
|
||
# Claude Code
|
||
python3 .claude/skills/issue-drive/scripts/create_gitea_issues.py /tmp/issues.json --dry-run
|
||
python3 .claude/skills/issue-drive/scripts/create_gitea_issues.py /tmp/issues.json
|
||
```
|
||
|
||
JSON 结构固定为：
|
||
|
||
```json
|
||
{
|
||
"repo_url": "https://git.example.com/owner/repo",
|
||
"issues": [
|
||
{
|
||
"title": "[缺陷][登录] 示例标题",
|
||
"body": "Issue 正文",
|
||
"labels": ["P1", "bug"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
规则：
|
||
|
||
- `repo_url` 可省略；脚本会按 `--repo-url` > `spec.repo_url` > `spec.repo` > 当前仓库 `origin` 的顺序解析
|
||
- `spec.repo` 允许写 `owner/repo`，但需要 `GITEA_BASE_URL`
|
||
- Token 固定读取 `GITEA_TOKEN`
|
||
- `labels` 写标签名，脚本会自动解析成远端 label id
|
||
- 远端不存在的标签会告警并自动跳过，不中断整个批次
|
||
- 先跑 `--dry-run`，确认 payload 和目标仓库无误后再正式创建
|
||
|
||
## 8. 输出结果
|
||
|
||
创建成功后，输出：
|
||
|
||
- 已推送的提交信息（如果本次为了 issue 基建或证据先推了提交）
|
||
- 新建 issue 的编号、标题、URL
|
||
- 哪些标签成功命中，哪些因远端不存在被跳过
|
||
- 如果拆成多张 issue，要说明每张工单分别驱动什么工作
|
||
|
||
## 9. 行为边界
|
||
|
||
- 默认以中文写 issue；用户明确要求英文时再切换
|
||
- 不把一个大问题硬塞进一张工单
|
||
- 不在 issue 里写超长散文，优先写清单、事实和完成标准
|
||
- 不因为缺少完美自动化复现就拒绝提单；现网证据或稳定复现路径成立时，可以先提
|
||
- 创建 issue 后，不自动继续写修复代码，除非用户明确要求
|