github-issues

github-issues

用途

在任何项目中统一 GitHub 问题的创建和管理。确保每个问题都有清晰的结构、恰当的标签和可执行的内容。引导用户创建规范的问题，并一致地应用 GitHub 的默认标签分类。

前置条件

执行任何操作前，请检查环境：

1. 检查是否已安装并通过身份验证的 gh — gh auth status。如果未通过身份验证，请停止并提示用户运行 gh auth login；否则后续步骤都会失败。

2. 检测仓库上下文：

gh repo view --json nameWithOwner --jq .nameWithOwner

将结果保存为 REPO="owner/repo"。gh 会自行解析远程仓库（SSH 或 HTTPS，以及 fork 中配置的基础仓库）。如果解析失败（当前目录不是 Git 仓库，或没有 GitHub 远程仓库），请询问用户 owner/repo。

请在执行任何 gh issue 或 gh label 命令之前完成此操作，并为每个命令传入 -R "$REPO"，确保无论当前目录是什么，都能针对正确的仓库执行操作。

适用场景

• 创建新的 GitHub 问题（先检查是否存在重复问题；如果已有问题涵盖该请求，则更新现有问题）
• 根据审计或评审报告文件批量创建问题
• 查看问题详情
• 附带说明关闭问题
• 在现有问题中发表评论
• 对现有问题进行分类或添加标签
• 列出带有标签的未解决问题

详细参考

按需加载以下内容，不要预先阅读：

• references/issue-templates.md — 标题规则、增强功能和错误的问题正文模板、正文段落规则，以及根据标题或上下文判断类型的方法。编写或重写问题正文前请阅读。
• references/labels.md — 类型和状态标签分类、应用标签前如何验证标签是否存在，以及 --add-label 与 --label 的使用规则。应用或更改标签前请阅读。
• references/audit-import.md — 将审计或评审报告转换为问题：解析发现项、类别到标签的映射、逐项检查重复问题、批量评审表，以及关于是否删除报告的结束提问。执行 from-audit 时请阅读。

操作

根据 $ARGUMENTS 执行以下操作之一。如果用户要求根据报告文件创建问题（例如“为审计发现项创建问题”“csinálj issue-kat az audit alapján”，或在代码分析器审计后选择选项 2），则使用 from-audit，即使用户说的是“create”。

create <title>

1. 根据标题和上下文判断问题类型 — 参见 references/issue-templates.md 中的问题类型判定指标。
2. 创建任何内容之前，先检查是否已有描述相同问题的 issue。 为已有问题再次提交 issue 会分散讨论并浪费分类处理精力，因此务必先搜索。从标题中提取最具辨识度的关键词（去掉“add”“fix”等通用动词和停用词），并搜索所有开放和已关闭的 issue：

gh issue list -R "$REPO" --search "<keywords>" --state all --json number,title,state,url,updatedAt --limit 20

阅读候选项，判断是否有任何一项描述了相同的根本需求或 Bug — 而不只是关键词重合。两个 issue 涉及同一个文件，但诉求不同，并不算重复；两个 issue 的措辞不同，但可通过同一项更改解决，则算重复。如果无法确定，将最接近的候选项视为可能匹配项，让用户决定，而不要自行猜测。

• **没有真正匹配的 issue：**继续执行第 3 步并创建新 issue。
• **存在匹配的开放 issue：**不要创建重复项。打开该 issue（gh issue view <number> -R "$REPO"），并将其正文与新信息进行比较。如果新请求带来了真正的新信息（额外的复现步骤、issue 中遗漏的受影响文件、更清晰的解决方案建议、新上下文），则更新现有 issue — 参见第 6b 步。如果现有 issue 已涵盖所有内容，告知用户该问题已有人提交（附上链接）并停止，不做任何更改。
• **存在匹配的已关闭 issue：**向用户展示该 issue 的链接和状态。询问用户是要重新打开（如果问题再次出现）、将新上下文作为评论添加，还是提交新 issue（例如，旧 issue 的根本原因不同）。不要擅自重新打开。

3. 检查目标仓库中有哪些可用标签，并处理缺少的类型标签 — 按照 references/labels.md 中的说明操作。
4. 从 references/issue-templates.md 中选择匹配的正文模板（enhancement 或 bug），并根据上下文预填“Summary”部分。如果用户提供了足够的详细信息，则填写所有适用部分。否则，询问缺少的必填部分 — 尤其是包含具体文件路径和实现方案的“Proposed Solution”。
5. 根据类型判定结果和第 3 步发现的可用标签，建议合适的标签。
6. **创建前，向用户展示完整的 issue（标题、正文、标签）以供审核。**等待用户确认或提出修改。
7. 创建 issue：

gh issue create -R "$REPO" --title "<title>" --label "<label1>,<label2>" --body "$(cat <<'EOF'
<body content>
EOF
)"

8. 输出 issue URL。

第 6b 步：更新现有 issue，而不是创建新 issue

仅当第 2 步发现匹配的开放 issue 缺少新请求提供的信息时，才执行此步骤。目标是在不覆盖现有内容的前提下补充现有 issue — 其正文可能包含编辑内容、讨论引用或用户手动添加的详细信息。

1. 判断真正需要更改的内容。对于小幅补充（额外的复现步骤、链接、新发现的原因），评论最不具破坏性，也能保留审计记录：

gh issue comment <number> -R "$REPO" --body "$(cat <<'EOF'
<the new information, e.g. additional repro steps or an affected file>
EOF
)"

2. 如果 issue 的结构化正文明显不完整（缺少“Proposed Solution”、“Summary”错误或为空），且重写能让 issue 更清晰，则编辑正文 — 但先向用户展示拟议的新正文，并与现有内容合并，而不是将其整体替换：

gh issue edit <number> -R "$REPO" --body "$(cat <<'EOF'
<merged body — existing content plus the new details>
EOF
)"

3. 如果新上下文改变了分类（例如，问题最终被确认是 Bug，而不只是 enhancement），则使用 --add-label 添加相应标签（切勿使用 --label，它会清除现有标签）。
4. 输出 issue URL，并用一句话说明所做的更改。

from-audit [<file>] [<ids or severities>]

根据审计或评审报告中的发现批量创建议题——请完整遵循 references/audit-import.md。简而言之：

1. 定位报告（指定的路径；否则使用仓库根目录中最新的 CODE_AUDIT_*.md——若有多个，请先确认），并解析每条发现。
2. 确定范围——使用用户指定的 ID 或严重性；如果用户未指定，则建议选择 Critical + High 并询问用户。
3. 对每条发现分别执行 create 第 2 步的重复项检查，并查询一次可用标签。
4. 根据模板起草每个议题，确保每个正文内容完整独立（报告之后可能会被删除）。
5. 为整个批次展示一张审核表——包含发现 ID、建议标题、标签和操作（create / update #N / skip）——并等待确认。
6. 创建或更新已确认的议题，并展示发现 → 议题 URL 对照表。
7. 询问是否删除审计文件。 切勿自行删除——用户回答前应告知的内容请参阅参考文档。

view <number>

1. 显示议题详情：

gh issue view <number> -R "$REPO"

2. 如果用户想查看讨论内容，则显示评论：

gh issue view <number> -R "$REPO" --comments

close <number> [reason]

1. 获取议题以验证状态：

gh issue view <number> -R "$REPO" --json title,labels,state

2. 如果议题已关闭，告知用户并停止。
3. 如果要以重复项为由关闭，必须要求用户指定原始议题编号。验证原始议题存在，然后使用 GitHub 原生的重复项关闭原因关闭议题——此操作会在议题时间线中记录链接：

gh issue view <original> -R "$REPO" --json number,title,state
gh issue close <number> -R "$REPO" --duplicate-of <original> --comment "Closing as duplicate of #<original>."

如果仓库有 duplicate 标签，也请添加（gh issue edit <number> -R "$REPO" --add-label "duplicate"）；如果没有，则跳过——关闭原因已表达了相同含义。如果旧版 gh 不支持 --duplicate-of（执行时出现 "unknown flag"），则改用 --reason "not planned" 并附上评论。

4. 对于其他关闭操作，添加说明原因的评论，并选择关闭原因——completed（已完成／已修复）或 not planned（不予修复、无效或已过时）：

gh issue close <number> -R "$REPO" --reason "<completed|not planned>" --comment "<reason>"

5. 如果用户在参数中提供了原因，则使用该原因。否则，在关闭前询问原因——切勿不作说明就关闭议题。

comment <number> <text>

1. 验证议题存在：

gh issue view <number> -R "$REPO" --json number,title,state

2. 添加评论：

gh issue comment <number> -R "$REPO" --body "<text>"

3. 确认评论已发布，并提供链接。

assign <number> <user> [--remove]

1. 验证议题存在：

gh issue view <number> -R "$REPO" --json number,title,state,assignees

2. 如果未提供 --remove，则将议题分配给该用户：

gh issue edit <number> -R "$REPO" --add-assignee "<user>"

如果提供了 --remove，则取消分配：

gh issue edit <number> -R "$REPO" --remove-assignee "<user>"

3. 如果 <user> 是 @me 或 me，则解析为已通过身份验证的用户：

gh api user --jq '.login'

4. 确认分配已更改。

label <number> <label> [--remove]

1. 获取可用标签，以验证请求的标签是否存在：

gh label list -R "$REPO" --json name --jq '.[].name'

2. 使用 --add-label / --remove-label 添加或移除标签——确切命令以及为何在 gh issue edit 中绝不能使用 --label，请参阅 references/labels.md。
3. 如果标签不存在，警告用户并列出可用标签。如果可能，建议最接近的标签。

triage

1. 列出所有带标签的未关闭议题：

gh issue list -R "$REPO" --state open --json number,title,body,labels,createdAt --limit 100

2. 筛选出 labels 为空的议题。
3. 如果没有找到未添加标签的议题，告知用户（“所有未关闭议题均已添加标签”）并停止。
4. 根据 references/issue-templates.md 中的类型检测指标和 references/labels.md 中的分类体系，分析每个未添加标签议题的标题和正文，建议相应标签。
5. 展示包含建议标签的汇总表：

#   Title                                    Suggested Label
37  Add database corruption recovery         enhancement
33  Fix error state on successful ops        bug
30  Update API documentation                 documentation

6. 在应用之前，询问用户是否确认、修改或跳过每项建议。
7. 应用已确认的标签：

gh issue edit <number> -R "$REPO" --add-label "<label>"

list（无参数时默认）

1. 列出未关闭的问题：

gh issue list -R "$REPO" --state open --json number,title,labels,assignees --limit 50

如果参数中指定了 --label <label>，则添加 --label "<label>" 进行筛选。

2. 以易读的表格形式显示：

#   Title                                    Labels              Assignee
12  Add dark mode toggle                     enhancement         @user
11  App crashes on startup with empty DB     bug, good first     —
10  Update README with build instructions    documentation       @user

3. 显示摘要：总数和标签分布。
4. 如果问题数量超过显示上限，告知用户，并建议使用 --label 进行筛选或提高上限。

错误处理

场景	检测方式	操作
未安装 gh	command -v gh 失败	指引用户访问 https://cli.github.com
gh 未通过身份验证	gh auth status 失败	请用户运行 gh auth login
当前目录不在 git 仓库中	git rev-parse --show-toplevel 失败	请用户手动提供 owner/repo
未配置远程仓库	git remote get-url origin 失败	请用户手动提供 owner/repo
未找到问题	gh issue view 退出状态非零	核实问题编号和仓库
未找到标签	标签不在 gh label list 输出中	显示可用标签，并建议最接近的匹配项
权限被拒绝	gh 返回 403/404	检查仓库访问权限和身份验证范围
达到速率限制	gh 返回 429，或返回提及 "secondary rate limit" 的 403（连续创建多个问题时很常见）	暂停后重试一次；批量操作时，报告尚未创建的项目

约束

遵循这些规则可确保问题质量，并防止意外损坏现有标签和问题：

• 创建新问题前先搜索现有问题；如果找到，则更新该问题，而不要重复提交——重复问题会分散讨论，并增加双倍的分类处理负担
• 每个问题都至少需要一个类型标签——标签是主要的分类机制，可用于筛选和分类处理
• 创建前向用户展示完整的问题内容（标题、正文、标签）以供审核——最终内容由用户决定
• 关闭任何问题前，先添加评论说明原因——方便未来的读者了解作出此决定的原因
• 将原问题关联为重复项后再关闭——这样可以在 GitHub 界面中保留关联关系
• 编辑问题时使用 --add-label（而非 --label）——--label 会替换所有现有标签，可能在不提示的情况下移除重要分类
• 未经用户确认，不要创建新标签——标签由整个仓库共享，会影响所有人的工作流
• 如果上下文中有具体文件路径和代码引用，请在问题正文中附上——带有明确指引的问题更容易得到解决
• 未经用户明确同意，绝不要删除源报告（审计文件）——其中可能包含尚未提交的问题