github-do-issue

github-do-issue

目的

用于在任何项目中实施 GitHub issue 的结构化工作流。对于每个 issue：获取 issue、理解需求、规划方案、实施并验证——然后停止，让用户先审核，再进行任何 Git 操作。

issue 队列

开始前，先根据 $ARGUMENTS 确定队列：

输入	队列
42、#42	该 issue
https://github.com/owner/repo/issues/42	该 issue；记下 owner/repo（见步骤 1）
多个数字 / URL	对应的 issue，按给定顺序排列
无输入，或“all” / “the open issues” / “az összes issue”	当前仓库的所有未关闭 issue——参见待办列表模式

单个 issue 就是只有一项的队列。无论哪种情况，下面的规则都适用。

一个 issue、一个提交、一个 PR

每个 issue 从头到尾都是一个独立的工作单元：有自己的实现、审核、提交、分支和拉取请求。一句话中提到的五个 issue，或在待办列表中找到的十五个 issue，都应分别运行五次（或十五次）这个工作流，而不是一次性全部处理。

拉取请求是人们用来审核、讨论、回退并关联回 issue 的工作单元。一个关闭三个 issue 的 PR 无法分开审核或回退，也会迫使只关心其中一个 issue 的审核者阅读全部三个。交错实现更糟：一旦两个 issue 的修改混在工作树中，就只能手动拆解 diff，才能整理成干净的提交。

因此，当队列中有多个 issue 时：

1. 在修改任何代码前，向用户确认队列及其顺序：

I'll do these one at a time, each with its own commit and PR:
1. #12 — <title>
2. #13 — <title>
3. #14 — <title>

Starting with #12. Order OK?

如果某个 issue 依赖另一个 issue，说明这一点并建议相应的顺序。否则，按给定顺序处理（待办列表模式有自己的默认顺序，见下文）。

2. 只对第一个 issue 执行步骤 1–6。
3. 停止，让用户审核并合并它（github-commit-pr --issue <N> 会为该 issue 处理提交 → 分支 → PR；--issue 会确保暂存内容及 Closes #N 仅对应此 issue）。
4. 只有当该 issue 的修改已离开工作树——已提交，或由用户明确暂存到别处——才开始下一个 issue 的步骤 1。

队列只是由数字和标题组成的列表，仅此而已。不要获取每个 issue 的完整正文并一起规划：只关注当前 issue，才能保持其 diff 干净且易于审核。

待办列表模式（未指定 issue）

未指定 issue 时，表示用户希望处理仓库中所有未关闭的 issue。列出它们——只列标题和元数据，不列正文：

gh issue list --state open --limit 200 \
  --json number,title,labels,assignees,createdAt,blockedBy,closedByPullRequestsReferences

（--limit 默认为 30，待办列表较长时会被静默截断。如果恰好返回 200 项，请说明列表可能不完整。）

根据该列表构建队列：

• **顺序：**按 issue 编号升序排列（较早的在前），但如果某个 issue 出现在另一个 issue 的 blockedBy 中，则将它排在后者之前；带有 bug 标签或明确优先级标签的 issue 可以提前——调整顺序时说明原因。
• 暂放，不要静默移除，并单独列出，以便用户可以将其中任何 issue 加回队列：
  • 已关联 PR 的 issue（closedByPullRequestsReferences 非空）——有人正在处理；
  • 已指派给当前用户以外人员的 issue（gh api user --jq .login）；
  • 非实现类 issue——例如带有 question、discussion、duplicate、wontfix、invalid 标签的 issue，或子 issue 已在列表中的 epic / 跟踪 issue。
• 如果没有剩余 issue，请说明并停止。如果队列很长（超过约 10 项），全部列出，但建议用户缩减队列，或选择某个标签 / 里程碑作为处理范围——每项都需要一轮审核。

然后像指定 issue 队列时一样，列出这两份清单并向用户确认：

14 open issues. Queue (one commit + PR each):
1. #3  — <title>   [bug]
2. #5  — <title>
3. #9  — <title>   (blocks #11)
...
Set aside: #7 (open PR #40), #8 (assigned to @alice), #10 (question)

Starting with #3. Order OK?

从这里开始，按普通的逐项循环处理。开始下一个 issue 前，重新列出未关闭 issue——期间可能已有 issue 被关闭或被他人接手。

前置条件

1. 工具和仓库：

command -v gh && gh auth status && git rev-parse --show-toplevel

如果缺少 gh，请引导用户访问 https://cli.github.com；如果尚未通过身份验证，请让用户运行 gh auth login；如果当前目录不在 Git 仓库中，则中止并给出明确提示。

2. 干净的起点：

git status --porcelain

未提交的更改不一定有问题——但如果它们属于上一个问题，在此基础上开始处理下一个问题，就会导致两个问题的更改最终进入同一个提交。如果工作区不干净，请向用户展示现有更改，并询问他们是要先通过 github-commit-pr --issue <N> 提交这些更改（针对这些更改所属的问题）、将其暂存，还是有意继续。

工作流

每次只处理一个问题。

步骤 1：获取问题

从队列中取出第一个问题。如果输入的是 URL，请提取问题编号和 owner/repo；如果该仓库与当前仓库不同，请提醒用户并询问是否继续（实现在当前仓库中进行，问题上下文来自另一个仓库）。

gh issue view "$ISSUE_NUMBER" ${ISSUE_REPO:+--repo "$ISSUE_REPO"} --json number,title,body,labels,assignees,milestone,state,comments

只有当 URL 指向不同的仓库时，才会将 ISSUE_REPO 设为 owner/repo；否则 gh 会默认使用当前仓库。如果命令失败（问题不存在或权限被拒绝），请报告错误；如果是在队列中，请询问是否跳过并处理下一个问题；否则停止。

如果问题已关闭，请提醒用户，并仅在用户确认后继续。

显示摘要，包括评论——评论通常包含说明、决定或变更后的要求：

Issue #42: <title>
State: open | Labels: enhancement
---
<issue body, trimmed to key requirements>
<key points from comments, if any>

步骤 2：了解需求

从问题正文和评论中提取以下内容：

• 需要更改的内容——功能、修复或改进
• 验收标准——复选框或明确要求
• 范围边界——不在范围内的内容（如有提及）
• 相关上下文——关联问题、提及的文件、引用的 PR

如果评论与正文相矛盾，以最新达成一致的评论为准。如果问题表述不清或缺少关键信息，请先询问，再继续。

步骤 3：规划方案

编写任何代码之前：

1. 阅读项目规范——README.md、CLAUDE.md、AGENTS.md、CONTRIBUTING.md 或类似文件、配置文件，以及变更相关的现有代码。
2. 确定需要创建或修改哪些文件。
3. 找出现有的、覆盖受影响代码的测试——变更应扩展测试覆盖范围，而不是破坏现有测试。
4. 提交简要计划：

Implementation plan for #42:
1. <specific change>
2. <specific change>
3. <specific change>

如果计划显示问题的规模超出预期，请说明情况并建议拆分。等待用户批准或调整计划。

步骤 4：实现

• 遵循步骤 3 中找到的规范。
• 按照最新评论讨论串中达成一致的内容实现，而不只是遵循问题的初始描述。
• 只更改问题要求的内容。如果项目使用 i18n，请为新增的用户可见字符串添加翻译键。
• 如果某个子任务变得比计划复杂，请暂停并告知用户，而不是悄悄扩大范围。
• 不要触碰属于队列中其他问题的内容，即使只差一行修复，而且十分钟后就会处理它。那一行应放在另一个问题对应的提交中，让审查者能将其与提出该需求的问题关联起来。记录下来，然后继续。

第 5 步：验证

运行项目自身的检查。优先运行 CI 中的检查（.github/workflows/、.gitlab-ci.yml、Jenkinsfile、.circleci/），以及 package.json 脚本、Makefile 或项目文档中列出的检查——PR 必须通过这些检查。各技术栈的常用命令：

• TypeScript/JavaScript： npx tsc --noEmit、npm test、npm run lint
• Rust： cargo check、cargo test
• Python： python -m pytest、mypy .、ruff check .
• Go： go build ./...、go test ./...
• Android（Kotlin/Java）： ./gradlew build、./gradlew test、./gradlew lint
• Flutter/Dart： flutter analyze、flutter test
• Swift： swift build、swift test
• Ruby： bundle exec rspec、bundle exec rubocop
• .NET（C#/F#）： dotnet build、dotnet test
• Elixir： mix compile --warnings-as-errors、mix test、mix credo

至少运行编译器／类型检查器，以及涉及此次更改的测试，并在报告前修复失败项。长输出只需筛选相关行，不要粘贴完整日志。如果没有可用的验证命令，请说明并建议手动检查。

第 6 步：报告并停止

Done — Issue #<number>: <title>

Files modified:
- <path> (new)
- <path> (modified)

Verification:
- Type check: clean
- Tests: passed

Ready for review.

如果队列中还有其他问题，结束时指出剩余事项以及继续处理前必须完成的操作：

Remaining: #13, #14.
Next step for #12: review, then commit + PR (github-commit-pr --issue 12).
I'll start #13 once #12 is committed.

到此为止。 不要提交、推送、创建分支或创建 PR。后续操作由用户决定。如果用户想要发布，github-commit-pr --issue <N> 会针对该问题执行提交 → 分支 → PR，并附带对应的 Closes #N——指定问题可让该技能在工作树还包含其他内容时，知道应暂存哪些路径。

第 7 步：处理下一个问题

当前问题合并（或用户明确决定暂缓）后，重新检查 git status --porcelain——遗留更改意味着上一个问题实际上尚未完成——然后从队列中处理下一个问题，并返回第 1 步。在积压模式下，先重新列出未关闭的问题，并移除期间已关闭或已有人接手的问题。

如果用户要求在上一个问题尚未提交时开始处理下一个问题，请明确说明代价——两个差异会混在一起，只能手动拆分——并提议先提交当前工作。如果用户仍想继续，由他们决定：继续处理，并提醒一次，最终提交将涉及两个问题。

错误处理

场景	检测方式	操作
未安装 gh／尚未登录	command -v gh／gh auth status 失败	提供 https://cli.github.com 或 gh auth login
不在 Git 仓库中	git rev-parse 失败	中止并清楚说明
找不到问题／无权访问	gh issue view 返回非零状态码、403/404	报告情况；在队列中可提议跳过
问题已关闭	state 为 CLOSED	发出警告，仅在确认后继续
问题来自其他仓库	URL 与当前仓库不符	发出警告，询问是否继续
存在多个问题，或未指定问题	队列长度大于 1	确认队列及顺序，仅处理第一个
没有未关闭的问题	gh issue list 返回 []	说明情况并停止
上一个问题留下未提交的更改	git status --porcelain 非空	显示更改，提议先提交／暂存
范围超出预期	规划／实施过程中发现	暂停，告知用户并建议拆分
找不到验证工具	命令不可用	告知用户并建议手动验证

关键约束

此技能仅负责实现阶段 — Git 工作流由用户掌控：

• 绝不让两个 issue 共用一个 commit 或 pull request；当前 issue 的更改离开工作区之前，不要开始队列中的下一个 issue。
• 不要 commit、push、创建分支或发起 PR — 用户会先进行审查，也可能有自己的分支策略；github-commit-pr 是交付步骤。
• 不要修改 issue 范围之外的文件 — 范围蔓延会增加审查和回滚的难度。
• 需求不明确时要先询问，不要猜测 — 错误猜测造成的代价高于快速提问。