zfc c27b85193f Add unified Gitea skill workflows

2026-03-12 17:23:08 +08:00

5.9 KiB

Raw Blame History

name	description
issue-drive	归集证据并把问题拆成 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. 先确定目标仓库

目标仓库按以下优先级确定：

用户显式给出的完整仓库 URL：https://git.example.com/owner/repo
用户显式给出的仓库简写：owner/repo，此时需要 GITEA_BASE_URL
当前项目的 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

如果参数和当前仓库都无法确定目标仓库，停止并提示：

❌ 无法确定目标仓库

请显式指定仓库，例如：
/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，输出：

❌ 缺少 GITEA_TOKEN

请先在当前 shell 或 .env 中配置：
export GITEA_TOKEN=your_gitea_token

然后停止，不继续创建 issue。

3. 先读仓库基线和证据

不要先写 issue。先确认事实、范围、影响和证据入口。

优先读取以下文件；只读存在的那些：

docs/ISSUE_WORKFLOW.md
.gitea/ISSUE_TEMPLATE/
.github/ISSUE_TEMPLATE/
README.md
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 附带脚本，并按当前平台选择路径：

# 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 结构固定为：

{
  "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 后，不自动继续写修复代码，除非用户明确要求

5.9 KiB Raw Blame History Unescape Escape