gh-create-issue

GitHub 创建 Issue

当用户请求创建 issue 时，使用此技能。必须遵循仓库的 issue 模板格式。

工作流

第 1 步：确定模板类型

分析用户的请求以确定 issue 类型：

• 如果用户描述了一个问题、错误、崩溃或某些无法正常工作的内容 -> Bug Report
• 如果用户请求新功能、增强功能或额外支持 -> Feature Request
• 如果用户是在提问或需要某方面的帮助 -> Questions & Discussion
• 如果用户描述的是没有面向用户行为变更的工程工作（从 pull request 中延后的后续事项、技术债、重构、工具或 CI 工作）-> Engineering Task
• 否则 -> Others

Engineering Task 不是 GitHub issue 表单，也不会提供给普通用户。仅当请求明确描述内部工程工作时才选择它。

如果不确定，询问用户要使用哪个模板。不要自行默认选择 "Others"。

资格检查（仅限 Engineering Task）

Engineering Task 面向拥有写权限的维护者和协作者。这是一个请求， 而不是访问控制——没有任何机制阻止任何人直接调用 gh issue create，本 技能也不会尝试这么做。下面的检查是为了让没有写权限的贡献者尽早得知这一点，并被引导到更有用的地方。

在收集任何信息之前，读取已认证用户的权限级别：

repo="$(gh repo view --json nameWithOwner --jq .nameWithOwner)"
user="$(gh api user --jq .login)"
permission="$(gh api "repos/$repo/collaborators/$user/permission" --jq .permission 2>/dev/null)"
case "$permission" in
  admin | write) echo "eligible" ;;
  *) echo "not eligible" ;;
esac

只有 admin 和 write 符合资格（maintain 会报告为 write）。始终比较返回的 值：在公开仓库上，此端点对任何用户都会返回 read，包括根本不是 协作者的用户，因此调用成功本身并不能证明什么。不要在此处使用 repos/{owner}/{repo}/collaborators/{user}——它对仅有 read 和 triage 权限的 协作者会返回 204，而他们并不是此模板的目标受众。

如果结果是其他任何值，则不要使用此模板。说明它面向拥有写权限的维护者， 礼貌地请贡献者改用某个公开模板，并 主动提出帮助他们在那里提交——他们的报告是受欢迎的，只是不应使用此模板。不要 在保留 Engineering Task 标签或 issue 类型的情况下悄悄切换模板。

第 2 步：读取所选模板

1. 从 .github/ISSUE_TEMPLATE/ 目录读取对应的模板文件。
2. 识别必填字段（validations.required: true）、标题前缀（title）、标签（labels，如果存在）以及 issue 类型（type，如果存在）。

对于 Engineering Task，请改为读取 references/engineering-task.md——它有意放在 .github/ISSUE_TEMPLATE/ 之外，并带有自己的标题前缀、标签、issue 类型和正文结构。

第 3 步：收集信息

根据所选模板，仅向用户询问必填信息。遵循模板的必填字段和选项约束（例如 Platform 和 Priority 选项）。

第 4 步：构建并预览 Issue 内容

创建一个临时文件并写入 issue 内容：

• 使用 issue_body_file="$(mktemp /tmp/gh-issue-body-XXXXXX).md"
• 使用所选模板中的确切标题前缀。
• 按照模板正文结构和章节顺序填写内容。
• 严格按照模板定义应用标签。
• 当存在多个标签时，保留所有标签。
• 如果模板没有标签，则不要添加自定义标签。
• 严格按照模板的 type 字段定义应用 issue 类型。

预览临时文件内容。显示文件路径（例如 /tmp/gh-issue-body-XXXXXX.md）并在创建前请求确认。如果用户明确表示不需要预览/确认（例如自动化工作流），则跳过此步骤。

第 5 步：创建 Issue

使用 gh issue create 命令创建 Issue。

为正文使用一个唯一的临时文件：

issue_body_file="$(mktemp /tmp/gh-issue-body-XXXXXX).md"
cat > "$issue_body_file" <<'EOF'
...issue body built from selected template...
EOF

使用所选模板中的值创建 Issue：

gh issue create --title "<title_with_template_prefix>" --body-file "$issue_body_file"

如果所选模板包含标签，则为每个标签追加一个 --label：

gh issue create --title "<title_with_template_prefix>" --body-file "$issue_body_file" --label "<label_1_from_template>" --label "<label_2_from_template>"

如果所选模板没有标签，则不要传入 --label。

如果所选模板声明了 type，也要一并传入。--body-file 本身不会携带 Issue 类型，因此省略它会使该 Issue 没有类型：

gh issue create --title "<title_with_template_prefix>" --body-file "$issue_body_file" --type "<type_from_template>"

--template 和 --web 会基于默认分支上的 .github/ISSUE_TEMPLATE/ 进行解析，因此两者都不适用于 Engineering Task。请为它在本地构建正文。

对于其他模板，你可以将 --template 作为起点（使用仓库中的确切模板名称）：

gh issue create --template "<template_name>"

当需要复杂格式时，使用 --web 标志在浏览器中打开创建页面：

gh issue create --web

创建后清理临时文件：

rm -f "$issue_body_file"

注意事项

• 必须读取 .github/ISSUE_TEMPLATE/ 下的模板文件（Engineering Task 则读取 references/），以确保遵循正确的格式。
• 将模板文件视为唯一的真相来源。不要在此技能中硬编码标题前缀、标签或 Issue 类型。
• 标题必须清晰简洁，避免使用 "a suggestion" 或 "stuck" 之类的模糊措辞。
• 提供尽可能多的细节，以帮助开发者理解和解决问题。
• 如果用户未指定模板类型，请先让他们选择一个。