---
name: issue-drive
description: 归集证据并把问题拆成 1 到多张 Gitea issue，支持从当前仓库 origin 自动识别仓库或用户显式指定，并通过环境变量配置的 Gitea API 批量创建工单。
---

# Issue Drive - 通用 Gitea 问题拆单与创建

> **定位**：不是“查看 issue”，而是把一个真实问题沉淀成可执行的 Gitea issue。适合“线上出 bug 了”“要把一个需求拆成工单”“需要补齐工程治理任务”这类场景。
>
> 如果用户只是想查 issue 列表或详情，用 `issue`。

当用户调用 `/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_ISSUE`：创建 issue 时优先使用
- `GITEA_TOKEN`：`GITEA_ISSUE` 缺失时回退使用
- `GITEA_BASE_URL`：可选；仓库简写或 SSH origin 时推荐配置

如果 `GITEA_ISSUE` 和 `GITEA_TOKEN` 都缺失，输出：

```bash
❌ 缺少 GITEA_ISSUE / GITEA_TOKEN

请先在当前 shell 或 .env 中配置：
export GITEA_ISSUE=your_gitea_write_token
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_ISSUE`，兼容回退 `GITEA_TOKEN`
- `labels` 写标签名，脚本会自动解析成远端 label id
- 远端不存在的标签会告警并自动跳过，不中断整个批次
- 先跑 `--dry-run`，确认 payload 和目标仓库无误后再正式创建

## 8. 输出结果

创建成功后，输出：

- 已推送的提交信息（如果本次为了 issue 基建或证据先推了提交）
- 新建 issue 的编号、标题、URL
- 哪些标签成功命中，哪些因远端不存在被跳过
- 如果拆成多张 issue，要说明每张工单分别驱动什么工作

## 9. 行为边界

- 默认以中文写 issue；用户明确要求英文时再切换
- 不把一个大问题硬塞进一张工单
- 不在 issue 里写超长散文，优先写清单、事实和完成标准
- 不因为缺少完美自动化复现就拒绝提单；现网证据或稳定复现路径成立时，可以先提
- 创建 issue 后，不自动继续写修复代码，除非用户明确要求