dispatch-issues

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dispatch Issues

问题分派

Find actionable GitHub Issues with

gh

, let the user choose what to pursue, then act as a commander to dispatch independent issue work to subagents in parallel.

使用

gh

找到可处理的GitHub Issues，让用户选择要处理的内容，然后作为指挥官将独立的问题处理任务并行分派给子代理。

Required Sub-Skill

必备子技能

REQUIRED: Use
```
commander
```
once issue work is selected. The commander never performs hands-on implementation, tests, commits, pushes, or issue edits.

必填： 一旦选定要处理的问题，需使用
```
commander
```
。指挥官从不执行实际的实现、测试、提交、推送或问题编辑操作。

Steps

步骤

1. Parse the Request

1. 解析请求

Read

args

. If empty, ask what repository, labels, keywords, or issue type to search. Extract:

Repository scope; default to the current GitHub repo only if unambiguous.
Search filters: labels, milestone, assignee, state, keywords, limit.
Selection mode: user-selected by default; automatic only if explicitly asked.
Dispatch intent: triage only, implementation, review, documentation, or another user-specified outcome.

读取

args

。若为空，则询问要搜索的仓库、标签、关键词或问题类型。提取以下信息：

仓库范围；仅在明确无歧义时默认使用当前GitHub仓库。
搜索筛选条件：标签、里程碑、经办人、状态、关键词、数量限制。
选择模式：默认由用户选择；仅当明确要求时才自动选择。
分派意图：仅分类、实现、评审、文档编写，或用户指定的其他结果。

2. Preflight

2. 预检

bash

gh auth status
gh repo view --json nameWithOwner,defaultBranchRef -q '.nameWithOwner + " " + .defaultBranchRef.name'

If auth fails, stop and ask the user to authenticate. Use read-only

gh issue

commands during discovery. Do not edit issues, labels, assignments, projects, or comments unless the user explicitly asks for that state change — the one standing exception is a dispatched agent reporting a dead end on its own issue (step 5).

bash

gh auth status
gh repo view --json nameWithOwner,defaultBranchRef -q '.nameWithOwner + " " + .defaultBranchRef.name'

若认证失败，停止操作并要求用户进行认证。在发现阶段使用只读的

gh issue

命令。除非用户明确要求更改状态，否则不得编辑问题、标签、经办人、项目或评论——唯一例外是分派的代理报告其负责的问题陷入僵局时（步骤5）。

2b. Verify the baseline (do not skip)

2b. 验证基线（不可跳过）

Issues are written against a tree. The checkout you are sitting in may not be that tree. Dispatching parallel agents onto the wrong baseline wastes every one of them, so establish the baseline before step 5.

bash

git status -sb
git log --oneline -1
git fetch origin --quiet
git log --oneline -1 origin/main
git merge-base --is-ancestor HEAD origin/main && echo "on main" || echo "DIVERGED"

Then spot-check the issue bodies against the tree. Issues cite file paths and line numbers; resolve two or three of them:

bash

wc -l <files the issues cite>
grep -n '<exact snippet quoted in the issue>' <file>

Stop and ask the user when any of these hold:

Detached HEAD, or HEAD diverged from
```
origin/main
```
.
A cited file is missing, or its length is far from what the issue implies.
A cited symbol/snippet does not exist (the feature lives on an unmerged branch).
Issue line numbers are off by more than a couple of lines.

Line numbers that are merely shifted are fine — but tell each subagent the corrected line ("the issue says 583; on this branch it is 582"), or it will edit the wrong place.

问题是基于特定代码树编写的。当前的检出版本可能并非该代码树。将并行代理分派到错误的基线会完全浪费资源，因此需在步骤5之前确定基线。

bash

git status -sb
git log --oneline -1
git fetch origin --quiet
git log --oneline -1 origin/main
git merge-base --is-ancestor HEAD origin/main && echo "on main" || echo "DIVERGED"

然后对照代码树抽查问题内容。问题会引用文件路径和行号，需验证其中两到三个：

bash

wc -l <files the issues cite>
grep -n '<exact snippet quoted in the issue>' <file>

出现以下任一情况时，停止操作并询问用户：

分离HEAD，或HEAD与
```
origin/main
```
分支偏离。
引用的文件缺失，或其长度与问题描述相差甚远。
引用的符号/代码片段不存在（功能位于未合并的分支上）。
问题中的行号偏差超过几行。

行号轻微偏移是可以接受的——但需告知每个子代理修正后的行号（“问题中写的是583；在当前分支上是582”），否则代理会编辑错误的位置。

2c. Preserve unreferenced commits before switching

2c. 切换分支前保留未引用的提交

If HEAD is detached with commits that no branch contains, switching away leaves them reachable only via reflog, where

gc

will eventually take them. Give them a name before creating the work branch:

bash

git branch --contains <sha>          # empty output = nothing points at it
git branch wip/detached-<short-sha> <sha>
git checkout -b <work-branch> origin/main

Report the rescue branch to the user. Never

reset

rebase

, or delete it.

若HEAD处于分离状态且包含无分支指向的提交，切换分支后这些提交只能通过reflog访问，最终会被

gc

清理。因此在创建工作分支前，需为这些提交命名：

bash

git branch --contains <sha>          # 输出为空表示无分支指向该提交
git branch wip/detached-<short-sha> <sha>
git checkout -b <work-branch> origin/main

向用户报告拯救分支的名称。切勿执行

reset

、

rebase

或删除该分支。

3. Discover Candidate Issues

3. 发现候选问题

Start broad, then inspect promising issues:

bash

gh issue list --state open --limit 30
gh issue list --state open --search 'is:issue is:open no:assignee' --limit 30
gh issue list --state open --label 'help wanted' --limit 30
gh issue view <number> --comments --json number,title,body,labels,assignees,comments,url,state

Adapt filters to the repository vocabulary (

bug

enhancement

good first issue

priority

needs-triage

). Inspect comments before classifying; labels alone are not enough.

先进行大范围搜索，再检查有潜力的问题：

bash

gh issue list --state open --limit 30
gh issue list --state open --search 'is:issue is:open no:assignee' --limit 30
gh issue list --state open --label 'help wanted' --limit 30
gh issue view <number> --comments --json number,title,body,labels,assignees,comments,url,state

根据仓库的常用词汇调整筛选条件（如

bug

、

enhancement

、

good first issue

、

priority

、

needs-triage

）。分类前需查看评论；仅靠标签是不够的。

4. Classify Actionability

4. 分类可处理性

Verdict	Criteria
`actionable`	Concrete desired outcome, bounded scope, enough context, open, not blocked, likely verifiable.
`needs clarification`	Goal is plausible but product intent, reproduction, or acceptance criteria are missing.
`blocked`	Marked blocked, assigned to someone else where assignment appears to mean ownership, depends on external access, or needs maintainer decision.
`not parallel-safe`	Reserved for true sequencing: the issue needs another selected issue's outcome before it can start. Touching the same files is not enough to land here — overlapping work is dispatched in parallel and reconciled at merge time.

Report candidates with issue number, URL, title, rationale, likely touched area, verification signal, and risks. Ask the user which issues to dispatch unless the request explicitly authorized automatic selection.

结论	判断标准
`actionable` （可处理）	有明确的预期结果、范围可控、上下文充分、状态为开放、无阻塞、可验证。
`needs clarification` （需澄清）	目标合理，但产品意图、复现步骤或验收标准缺失。
`blocked` （已阻塞）	标记为阻塞状态、已分配给他人（且分配意味着所有权）、依赖外部权限，或需要维护者决策。
`not parallel-safe` （不可并行）	仅适用于必须按顺序执行的情况：该问题需等待其他选中问题完成后才能开始。仅涉及相同文件并不属于此类——重叠工作可并行分派，在合并时解决冲突。

向用户报告候选问题，包括问题编号、URL、标题、分类理由、可能涉及的区域、验证信号和风险。除非请求明确授权自动选择，否则需询问用户要分派哪些问题。

5. Dispatch Through Commander

5. 通过Commander分派任务

After issue selection, switch into commander behavior:

Decompose selected issues into independent units.
Keep an explicit unit table: issue/unit → assignee → status (
```
not-started
```
/
```
in-progress
```
/
```
committed
```
/
```
PR-opened
```
).
Choose an isolation mode (see below) before writing any prompt.
Dispatch independent units in parallel in one message.
Put issue context, relevant comments, scope, constraints, and report format in each prompt.
Verify subagent reports read-only before claiming completion.

选定问题后，切换为指挥官模式：

将选中的问题分解为独立单元。
维护明确的单元表：问题/单元 → 经办人 → 状态（
```
not-started
```
/
```
in-progress
```
/
```
committed
```
/
```
PR-opened
```
）。
在编写任何提示前选择隔离模式（见下文）。
在一条消息中并行分派独立单元。
在每个提示中包含问题上下文、相关评论、范围、约束和报告格式。
在宣布完成前以只读方式验证子代理的报告。

Choose the isolation mode first

先选择隔离模式

Units	Mode	Why
1–2, clearly disjoint files	Shared tree, file partitioning	No merge step, no per-unit dependency install.
3+, or any file overlap	Worktree isolation ( `isolation: "worktree"` )	Agents work unconstrained; conflicts are resolved once, at the end.

Default to worktree isolation as soon as there are three or more units. File partitioning looks cheaper but it taxes every agent:

You must forbid
```
fmt
```
/
```
lint --fix
```
/
```
check
```
/
```
build
```
repo-wide, because they rewrite files other agents are mid-edit.
Units that share a file get pushed to a later wave instead of running now.
One agent needing a file outside its lane stalls and has to report back.

Worktree isolation costs a dependency install per worktree and a merge at the end. That is usually the better trade — and the user often expects it, so say which mode you picked rather than letting them assume.

单元数量	模式	原因
1–2个，文件明确无重叠	共享代码树，按文件划分	无需合并步骤，无需为每个单元安装依赖。
3个及以上，或存在文件重叠	工作树隔离（ `isolation: "worktree"` ）	代理可不受限制地工作；冲突仅在最后统一解决。

一旦单元数量达到3个及以上，默认使用工作树隔离。按文件划分看似成本更低，但会给所有代理带来负担：

必须禁止全仓库范围的
```
fmt
```
/
```
lint --fix
```
/
```
check
```
/
```
build
```
命令，因为这些命令会改写其他代理正在编辑的文件。
涉及相同文件的单元需推迟到后续批次执行，无法立即运行。
若某个代理需要访问其负责范围外的文件，会陷入停滞并需反馈。

工作树隔离的成本是每个工作树需安装一次依赖，以及最后进行一次合并。这通常是更优的选择——且用户通常也期望如此，因此需告知用户选择的模式，而非让他们自行猜测。

Commit policy depends on the mode

提交策略取决于所选模式

Shared tree: forbid commits. Changes land in one tree; the user reviews the combined diff.
Worktree isolation: local commits on the agent's own worktree branch are required — uncommitted work in a worktree cannot be integrated. Forbid the implementing agent from
```
push
```
and PR creation, and forbid switching to or modifying
```
main
```
/ the work branch / any rescue branch.

For independent units that map 1:1 to issues, the default handoff is one PR per unit, after independent verification. Local-commit-only is for users who explicitly want one combined diff. Settle the policy before dispatch, or at least state plainly which one you picked.

Deliver a PR in two stages: the implementing agent commits locally, then a separate verification agent re-runs the tests and type checks, pushes, and opens the PR. The implementer's own "tests pass" is not evidence enough to open a PR on.

Either way,

gh issue

labels, assignments, and closures stay forbidden unless the user asked for that state change.

gh issue comment

has one standing exception. When a unit ends without a PR-ready result — blocked, root cause not found, tests not green, a product decision needed — the agent must not finish silently. It posts its findings to the issue with

gh issue comment <n>

, in the language the issue is written in, covering:

what it established,
what it tried,
the evidence behind both (numbers, failing output, screenshots),
why the work did not reach a PR,
the options it recommends next.

When the work does reach a PR, no comment is needed —

Closes #N

in the PR body covers it. A transcript is not a report: an investigation that never lands on the issue is lost the moment the agent exits.

共享代码树： 禁止提交。所有更改都在同一代码树中；用户会查看合并后的差异。
工作树隔离： 要求代理在自己的工作树分支上进行本地提交——工作树中的未提交工作无法被整合。禁止实现代理执行
```
push
```
和创建PR操作，禁止切换到或修改
```
main
```
/ 工作分支 / 任何拯救分支。

对于与问题一一对应的独立单元，默认交付方式是每个单元对应一个PR，经过独立验证后提交。仅本地提交适用于明确要求合并为单个差异的用户。需在分派前确定策略，或至少明确说明所选的策略。

PR的交付分为两个阶段：实现代理在本地提交，然后由单独的验证代理重新运行测试和类型检查，推送代码并创建PR。仅靠实现代理自己说“测试通过”并不足以作为创建PR的依据。

无论哪种模式，除非用户要求更改状态，否则禁止修改

gh issue

的标签、经办人或关闭问题。

gh issue comment

有一个例外情况。当某个单元未能产生可提交PR的结果时——如阻塞、未找到根本原因、测试未通过、需要产品决策——代理不得静默结束任务。 需使用

gh issue comment <n>

在该问题下发布调查结果，使用问题的语言，内容包括：

已确定的信息，
已尝试的操作，
支撑上述内容的证据（数字、失败输出、截图），
工作未能生成PR的原因，
推荐的下一步操作。

若工作成功生成PR，则无需评论——PR正文中的

Closes #N

已足够说明。对话记录不能替代报告：未发布到问题上的调查结果会在代理退出后丢失。

Other constraints worth putting in every prompt

每个提示中都应包含的其他约束

Dev server ports are machine-global. Assign each agent its own port (5181, 5182, …) and tell it to shut the server down. Otherwise the second agent to start silently binds elsewhere or fails.
The baseline numbers. Give the pre-change test count and type-check status from step 2b, so the agent can tell its own regressions from pre-existing ones.
The corrected line numbers when they drifted from the issue body.
Overlap is expected, not forbidden. Tell each agent that other agents may be editing the same files right now. That is never a reason to stall, ask permission, or narrow the fix — the conflict is resolved when the branches merge.
Minimal diffs, precisely because of that overlap: no drive-by reformatting, no unrelated cleanups, the smallest change that closes the issue. Sprawl is what makes the merge unreadable, not the overlap itself.
The fallback report. If the unit will not reach a PR, the agent comments its findings on the issue, in the issue's language, rather than ending on a shrug.
No
git clean
, with any options. Worktrees often live inside the repository as untracked directories, so a
```
git clean -fd
```
sweep deletes the other agents' checkouts.

Use this dispatch prompt shape:

text

Objective: <what done looks like for issue #N>
Issue context: <number, URL, title, labels, body summary, relevant comments>
Baseline: <branch, HEAD sha, test count, type-check status, corrected line refs>
Environment: <worktree-isolated or shared tree; install step; allowed commands;
assigned dev-server port>
Scope: <files/areas allowed, files/areas not allowed, state-changing limits>
Shared files: <other units running now and the files they may also touch; overlap
is expected — keep the diff minimal, do not stall on it>
Constraints: <commit policy for this mode; no `git clean`; no pushes, PRs,
labels, assignments, or closures; if the unit does not reach a PR-ready result,
comment the findings on issue #N with `gh issue comment`, in the issue's
language>
Report format: files changed, commands run with results, risks, blockers,
open questions, and verification evidence.

开发服务器端口是全局的。 为每个代理分配独立的端口（5181、5182……）并告知其关闭服务器。否则第二个启动的代理会静默绑定到其他端口或启动失败。
基线数据。 提供步骤2b中获取的变更前测试数量和类型检查状态，以便代理区分自身引入的回归和预先存在的问题。
修正后的行号。 若行号与问题描述有偏差，需告知修正后的行号。
允许重叠。 告知每个代理其他代理可能正在同时编辑相同的文件。这绝不是停滞、请求许可或缩小修复范围的理由——冲突会在分支合并时解决。
最小化差异，正是因为存在重叠：禁止顺带格式化代码、禁止无关的清理操作，仅提交能解决问题的最小变更。导致合并难以阅读的是变更范围过大，而非文件重叠本身。
** fallback报告。** 若单元无法生成PR，代理需在问题下评论调查结果，使用问题的语言，而非不了了之。
禁止使用
git clean
及任何参数。工作树通常作为未跟踪目录存在于仓库中，
```
git clean -fd
```
会删除其他代理的检出版本。

使用以下分派提示模板：

text

Objective: <问题#N的完成标准>
Issue context: <编号、URL、标题、标签、内容摘要、相关评论>
Baseline: <分支、HEAD哈希、测试数量、类型检查状态、修正后的行号引用>
Environment: <工作树隔离或共享代码树；安装步骤；允许的命令；分配的开发服务器端口>
Scope: <允许修改的文件/区域、禁止修改的文件/区域、状态变更限制>
Shared files: <当前正在运行的其他单元及其可能修改的文件；允许重叠——尽量缩小差异，不要因重叠停滞>
Constraints: <当前模式下的提交策略；禁止`git clean`；禁止推送、创建PR、修改标签、经办人或关闭问题；若单元无法生成可提交PR的结果，需使用`gh issue comment`在问题#N下发布调查结果，使用问题的语言>
Report format: 修改的文件、执行的命令及结果、风险、阻塞点、未解决的问题、验证证据。

Quick Reference

快速参考

Need	Action
Find issues	`gh issue list` with repo-specific labels/search.
Confirm context	`gh issue view <n> --comments --json ...` .
Check the baseline	`git status -sb` , `git log --oneline -1 origin/main` , resolve cited lines.
Decide actionability	Use concrete outcome, bounded scope, context, verification, and blockers.
Dispatch work	Use `commander` ; delegate hands-on work, keep verification read-only.
Handle file overlap	Dispatch anyway under worktree isolation; resolve the conflict at merge time.
Close out a dead end	`gh issue comment <n>` in the issue's language: findings, attempts, evidence, why no PR, next options.
Recover from an agent failure	Reconcile selected units against assigned units; inspect the worktrees before redispatching.

需求	操作
查找问题	使用带仓库特定标签/搜索条件的 `gh issue list` 命令。
确认上下文	使用 `gh issue view <n> --comments --json ...` 命令。
检查基线	执行 `git status -sb` 、 `git log --oneline -1 origin/main` ，验证引用的行号。
判断可处理性	依据明确的结果、可控的范围、上下文、可验证性和阻塞状态。
分派工作	使用 `commander` ；委托实际操作，保持验证为只读。
处理文件重叠	在工作树隔离模式下照常分派；合并时解决冲突。
处理僵局	使用问题的语言执行 `gh issue comment <n>` ：调查结果、尝试的操作、证据、无法生成PR的原因、下一步建议。
从代理故障中恢复	对照已分配的单元核对选定的单元；重新分派前检查工作树。

Red Flags

警示信号

You selected issues automatically without explicit authorization.
You ignored issue comments that may contain maintainer decisions or duplicates.
You have not checked that the cited files and lines exist in this checkout.
HEAD is detached, or diverged from
```
origin/main
```
, and you dispatched anyway.
Three or more units are going into one shared tree.
You serialized a unit, dropped it, or asked the user to pick one, because two agents might edit the same files.
An agent ended with neither a PR nor a comment on its issue.
The selected unit set and the assigned unit set differ after an agent failure.
Worktree isolation is in play with no stated PR-per-unit vs combined-diff policy.
A dispatch prompt permits
```
git clean
```
.
You are doing implementation work yourself while claiming commander mode.
A subagent prompt lacks issue context, scope, constraints, or report format.

未经明确授权自动选择问题。
忽略可能包含维护者决策或重复信息的问题评论。
未验证当前检出版本中是否存在问题引用的文件和行号。
HEAD处于分离状态或与
```
origin/main
```
分支偏离，但仍进行了分派。
三个及以上单元被分派到同一个共享代码树。
因两个代理可能编辑相同文件而将某个单元串行执行、丢弃或让用户二选一。
代理结束任务时既未生成PR也未在问题下评论。
代理故障后选定的单元集与已分配的单元集不一致。
使用工作树隔离模式但未说明“每个单元一个PR”还是“合并为单个差异”的策略。
分派提示允许使用
```
git clean
```
。
声称处于指挥官模式但自己执行实现工作。
子代理提示缺少问题上下文、范围、约束或报告格式。

Common Mistakes

常见错误

Treating labels as truth: comments can supersede labels. Inspect promising issues with
```
gh issue view --comments
```
.
Trusting the checkout: the tree an issue was written against and the tree you are in are different claims. A feature described in an issue can live on an unmerged branch, in which case its "actionable" issues have nothing to edit. Verify in step 2b, before selection — a candidate list built on the wrong tree is wrong in ways the user cannot see.
Treating file overlap as a blocker: two issues touching one file is a merge to perform, not a reason to serialize the units, drop one, or make the user choose. Dispatch both, isolate them in worktrees, reconcile at the end.
Letting a dead end die in the transcript: a unit that produced no PR still produced knowledge. If it is not on the issue, the next agent starts from zero.
Reaching for file partitioning by reflex: it is the right call for two units and a tax on every unit beyond that. Pick the mode deliberately and tell the user which one you picked.
Forbidding commits under worktree isolation: the work then has no way back. Require local commits on the agent's own branch; forbid pushes and PRs instead.
Hiding finished work: a local commit is invisible from outside the machine. For independent issue units, stream verified PRs as each unit finishes, unless the user chose one combined diff.
Dispatching too early: show candidates and get selection unless automatic selection was explicitly authorized.
Under-specifying prompts: subagents start cold. Include issue context, constraints, other selected issues, and exact report fields.
Redispatching blindly after a failure: run
```
git worktree list
```
and
```
git status --porcelain
```
in each worktree first. Hand the salvageable partial work to the successor instead of restarting it from zero.
Reassigning units already started: once a unit is in progress, that agent owns it. Reassign only units that never started. If duplicate implementations collide, adopt one diff and repurpose the other agent as its reviewer.

将标签视为事实： 评论可以推翻标签。需使用
```
gh issue view --comments
```
检查有潜力的问题。
信任当前检出版本： 问题编写时基于的代码树与当前的检出版本可能不同。问题中描述的功能可能位于未合并的分支上，此时“可处理”的问题并无对应的代码可编辑。需在选择前的步骤2b中进行验证——基于错误代码树生成的候选列表存在用户无法察觉的错误。
将文件重叠视为阻塞： 两个问题涉及同一个文件只需在合并时处理，而非串行执行单元、丢弃其中一个或让用户选择。应同时分派两个单元，使用工作树隔离，最后统一解决冲突。
让僵局结果仅存在于对话记录中： 未能生成PR的单元仍产生了有用信息。若未发布到问题上，下一个代理将从零开始。
习惯性选择按文件划分： 这种模式仅适用于两个单元，超过两个单元后会给所有代理带来负担。需谨慎选择模式并告知用户。
在工作树隔离模式下禁止提交： 这样工作成果无法被整合。需要求代理在自己的分支上进行本地提交；改为禁止推送和创建PR。
隐藏已完成的工作： 本地提交在机器外部不可见。对于独立的问题单元，应在每个单元完成后推送经过验证的PR，除非用户选择合并为单个差异。
过早分派： 需先展示候选问题并获取用户选择，除非明确授权自动选择。
提示信息不完整： 子代理从零开始工作。需包含问题上下文、约束、其他选中的问题和明确的报告字段。
代理故障后盲目重新分派： 需先执行
```
git worktree list
```
和每个工作树中的
```
git status --porcelain
```
。将可挽救的部分工作交给后续代理，而非从零开始。
重新分配已启动的单元： 单元一旦启动，就由对应的代理负责。仅重新分配从未启动的单元。若出现重复实现冲突，采用其中一个差异，将另一个代理改为评审者。