Mastra Code gh-bulk-issues 实战指南：编排并行 headless 实例批量调试与修复 GitHub Issue-编程实验室

Mastra Code gh-bulk-issues 实战指南：编排并行 headless 实例批量调试与修复 GitHub Issue

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

本篇指南深入讲解 Mastra Code（mc）技能体系中的gh-bulk-issues（Bulk Issue Solver）：它如何以"监督者（supervisor）"身份同时编排多个 headless 实例，在互不干扰的 git worktree 中并行调试、修复多个 GitHub Issue，并在最终为每个修复创建 PR。读完本文，你将掌握该技能从输入约定、环境搭建、过程监控到 PR 与 CI 收尾的完整执行链路，并理解其背后的 headless CLI 实现原理（headless CLI 实现、标志解析），能够直接在自己的 Mastra Code 工作流中复刻这套"多 worker 并行修 Issue"的编排方案。

一、技能定位：一个"监督者"编排多个"工人"

gh-bulk-issues 的定义在 .mastracode/skills/gh-bulk-issues/SKILL.md 中，其 frontmatter 明确声明：

name: gh-bulk-issues description: Orchestrate parallel Mastra Code headless instances to debug and fix multiple GitHub issues simultaneously metadata: goal: true

核心思想是一句话：你（当前 Agent）是监督者（supervisor），负责 spawn worker、监控进度、审查产出、创建 PR；真正的"调试与修复"由每个 worker 对应的mcheadless 实例独立完成。这与"一个 Agent 串行处理 N 个 Issue"的模式本质不同——后者受限于单线程上下文切换，前者则把每个 Issue 隔离进独立的进程与工作区，实现真正意义上的并行。

在命令体系中，它由 .mastracode/commands/gh-bulk-issues.md 激活，该包装命令的逻辑极其精简——只是把用户参数透传给技能：

Activate skill: gh-bulk-issues Arguments: $ARGUMENTS

也就是说：技能负责完整编排流程，命令只负责"叫醒"技能。从仓库的技能目录（.mastracode/skills）可以看到，它与understand-issue、triage-issue、understand-pr、label-core-bugs、pr-snapshot-release等共同构成一套完整的 GitHub 维护者自动化技能栈，gh-bulk-issues 是其中最强调"并行调度"的一个。

二、输入约定与自动选题

2.1 显式传入 Issue 编号

$ARGUMENTS应为空格分隔的 GitHub Issue 编号列表，例如：

1234 5678 9012

每个编号会贯穿整个流程：创建对应 worktree、生成对应报告文件、最终在对应分支上创建 PR 并引用Closes #<NUMBER>。

2.2 无参时自动推荐候选 Issue

如果没有提供参数，技能会用 GitHub CLI 与本地 git 历史来"推荐"值得处理的 Issue：

RUN gh issue list --state open --limit 50 --json number,title,labels,assignees RUN git log --author="$(git config user.name)" --pretty=format:'' --name-only --since="6 months ago" | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20

第一条命令拉取仓库当前最多 50 个 open issue 的编号、标题、标签与指派人；
第二条命令统计过去 6 个月贡献者自己改动最频繁的目录（git config user.name对应的作者），从而推断出"你最熟悉的技术区域"。

技能随后会把"贡献领域"与"open issue"做匹配，先向用户确认要做哪些 Issue，再开始。这一步的价值在于：让 worker 处理与自己历史经验高度相关的模块，可以显著提高首次调试成功率，也符合 understand-issue 技能中"从 git 历史理解代码为什么存在"的研究理念。

三、Setup：为每个 Issue 建立隔离工作区并启动 worker

技能对列表中的每个Issue 编号依次执行三步，本节逐条展开并给出源码层面的解释。

3.1 创建独立 git worktree 与分支

git worktree add ../$(basename $PWD)-issue-<NUMBER> -b fix/issue-<NUMBER>

在当前仓库目录之外创建一份新工作树，命名形如<仓库名>-issue-1234；
分支名固定为fix/issue-<NUMBER>，让"哪个分支对应哪个 Issue"一目了然；
分支名约定与understand-issue的提取逻辑互相呼应（understand-issue 技能中会从fix/1234、issue-567这类分支名反向提取 Issue 编号）。

3.2 安装依赖并构建

cd ../$(basename $PWD)-issue-<NUMBER> && pnpm i && pnpm build

注意技能特别标注：同时只跑 2 个 worktree 的 build（2 builds at a time to manage CPU）。构建是 CPU 密集型操作，限制并发数是为了避免把开发机打满；这也是整个流程中唯一需要限流的环节。

3.3 在每个 worktree 中启动 headless 实例

cd ../$(basename $PWD)-issue-<NUMBER> && pnpx tsx <path-to-mastracode>/src/main.ts --timeout 1800 --prompt "Activate the understand-issue skill for issue <NUMBER>"

这一行是整个编排的核心。<path-to-mastracode>/src/main.ts对应仓库中的 mastracode/tui/src/main.ts（实际路径随 checkout 布局而定），它是 Mastra Code TUI 的进程入口；当进程参数带有 headless 标志时，会走hasHeadlessFlag/runMCCli分支进入无交互模式（见 main.ts 入口）。

关键参数在 headless CLI 实现与标志解析中可查到准确语义：

参数	语义（源码定义）
`--prompt <text>`/`-p`	必填，指定本次 headless 运行的指令；也可从 stdin 管道输入（`echo ... \\| mastracode --prompt -`）
`--timeout <seconds>`	正整秒数，超时后以退出码 2 结束；由`validate.positiveInt('--timeout')`校验，0、小数、非数字均会被拒绝
`--continue`/`-c`	续跑最近的线程；`--thread <id>`指定具体线程，`--clone-thread`在副本上继续
`--settings <path>`	指定自定义 settings 文件（如`settings-ci.json`），模型、pack、subagent 等配置在启动时解析
`--max-turns <n>`	达到 N 个 agentic 回合后中止（退出码 1）
`--permission-mode <mode>`	权限模式，如`deny`
`--output json/jsonl`	结构化输出

Headless 退出码契约（cli.ts 用法说明）：

0 Agent completed successfully 1 Error, aborted, or max turns reached 2 Timeout

这套语义被 cli.test.ts 测试覆盖验证：hasHeadlessFlag能识别--prompt/-p，parseHeadlessArgs对--timeout 0、--timeout 1.5、--timeout soon均抛错。因此编排时必须给每个 worker 的execute_command配置与--timeout 1800（30 分钟）相匹配的等待上限，并以后台进程方式运行、记录每个 PID——这正是 SKILL.md 明确要求的做法。

3.4 初始 prompt 为什么是 understand-issue

每个 worker 的第一条指令是Activate the understand-issue skill for issue <NUMBER>，而不是直接让它"修"。这是因为 understand-issue 技能是整个修复流程的"研究前置阶段"，它通过 8 个阶段（识别 Issue、检索相关 Issue/PR、代码路径溯源、协同诊断、深度探索、理解质量闸门、产出 UNDERSTANDING 文件、可选发布到 GitHub）确保 worker先真正理解问题根因，再动手。仓库中 gh-debug-issue 命令的弃用说明也印证了这一设计取向：旧命令把"理解、复现规划、写测试、修复"混在一条长流程里，而新体系让understand-issue独占"理解与诊断"环节，为后续修复积累高质量上下文。

四、监控：报告文件 + 3 分钟巡检

4.1 reports/ 报告体系

技能要求在主项目根目录创建reports/，并为每个 Issue 维护reports/issue-<NUMBER>.md，包含：

Issue 编号、标题与链接
当前状态（Analyzing / Implementing / Tests passing / PR open / Done）
方案与变更摘要
创建后的 PR 链接
任何阻塞项或备注

这套报告文件的作用是"用户随时有一份书面记录"——即便所有 worker 都还在后台运行，用户打开仓库就能看到每个 Issue 的进度。

4.2 每 3 分钟巡检一次

对于每个检查周期：

读取每个运行中 PID 的尾部输出（tail）；
更新对应报告文件；
向用户输出一个简短的状态表。

关键纪律：绝不让进程处于无人监控状态（Never leave a process unmonitored）。headless 实例可能因超时、权限、模型异常等原因挂起，定时巡检是及时发现并干预的前提。

五、worker 结束或超时后的处置流程

5.1 先看变更再决定

无论实例是正常完成还是超时退出，先做两件事：

git diff --stat # 在对应 worktree 中查看改动了什么

同时检查是否产生了changeset与ISSUE_SUMMARY 文件（后者是understand-issue类技能产出的调查摘要，前者是 monorepo 变更集记录）。

5.2 超时但有进展 → 续跑

如果实例超时但 diff 显示已取得进展，则用续跑提示词重启：

Continue working on issue #<NUMBER>.

提示词必须基于 diff 与上次输出来概括"停在哪里、还差什么"。这与 headless CLI 的--continue/--thread能力（flags.ts）天然配套：worker 可以在同一线程上下文里继续推进，避免丢失之前的调查结论。

5.3 正常完成 → 人工把关后提 PR

若实例完成了"代码 + 测试 + changeset"，监督者需要：

审查 diff——这个修复是否合理；
把变更汇报给用户评审；
获得批准后，按 gh-new-pr 命令约定提交、推送并创建 PR：
- Conventional commit 标题：fix: ...或feat(pkg): ...
- 简洁的 PR 描述并附代码示例
- 引用Closes #<NUMBER>
更新报告文件，写入 PR 链接。

特别注意技能的最后一条规则：Review all mc output before creating PRs — subagent work is untrusted（subagent 的产出不可信）。这体现了编排体系的安全底线：并行 worker 只负责干活，最终对外发布的 PR 必须经过监督者（乃至用户）的人工审查，防止模型幻觉或错误修改直接流入主干。

六、PR 评论与 CI 的闭环处理

6.1 处理 CodeRabbit 与评审者评论

PR 创建后，监督者 spawn 新的mc实例并调用/gh-pr-comments <PR_NUMBER>处理 CodeRabbit 及评审者反馈。配套的 gh-pr-comments 命令规定了详细行为：用gh pr view --comments拉全所有评论；对 CodeRabbit 的合理建议予以实现，不同意见则回复并@coderabbitai以便机器人跟进；每条回复以 "AI says: " 开头并署名；为每条评论单独提交（commit message 中尽量带上 PR 评论链接）。若该实例超时，同样以"还剩哪些评论待处理"为上下文重启。

6.2 巡检 CI 并在失败时自动修复

每次推送 PR 之后（包括评论修复后的再次推送），都要检查 CI：

gh pr checks <PR_NUMBER>

若有检查失败，在对应 worktree 内 spawn 一个执行/gh-fix-ci的mc实例来诊断并修复。gh-fix-ci 命令的流程为：gh pr status+gh pr checks定位失败 → 深入分析错误信息与失败测试 → 区分 flaky test、真实 bug 与环境问题 → 制定计划实施修复 → 本地跑测试验证 → 提交推送并监控新一轮 CI。超时同样重启，并在提示词中带上"哪些检查失败、已尝试过什么"。

一个贯穿始终的硬规则：所有与某 Issue 相关的任务（调试、PR 评论、CI 修复）必须在该 Issue 自己的 worktree 中完成，绝不为其另建第二个 worktree。理由很直接：worktree 会持续积累上下文（commits、diffs、构建产物），每次重启的mc实例都能从中受益——这正是把"进程隔离"与"上下文累积"统一起来的精妙之处。

七、关键规则速查

将 SKILL.md 的 Key Rules 整理如下：

规则	原因
同时最多 2 个`pnpm build`	`pnpm build`是 CPU 密集型，限流避免打满开发机
所有`mc`实例可全并行	headless 实例是 IO-bound（网络、LLM 调用），而非 CPU-bound
每个 Issue 永远只用一个 worktree	worktree 累积的 commits/diffs/构建产物是后续实例的上下文资产
超时进程必须用带上下文的续跑提示词重启	避免丢失调查进展，从断点继续而非重来
每 3 分钟检查一次，进程不允许无人监控	及时发现超时、挂起与异常
持续更新报告文件	用户始终有书面进度记录
PR 创建前必须人工审查所有 mc 输出	subagent 产出不可信，杜绝坏修改流入主干

八、与整个 Mastra Code 技能体系的关系

gh-bulk-issues 不是孤立的脚本，而是 Mastra Code 仓库内"GitHub 维护者自动化"技能栈的调度中枢：

上游：每个 worker 的第一站是 understand-issue，负责把 Issue 研究透彻并产出 UNDERSTANDING 文件；其"研究优先、协同诊断、用户驱动"的阶段化设计，保证进入修复阶段时已有扎实上下文。
下游：PR 创建走 gh-new-pr 约定，评论反馈走 gh-pr-comments，CI 修复走 gh-fix-ci。
并行的前提：所有 worker 依赖 headless CLI 的--prompt/--timeout/--continue等参数（flags.ts），其退出码（0 成功 / 1 错误 / 2 超时）与参数校验（cli.test.ts）为监督者提供了可靠的进程契约。

如果你同时在使用 gh-triage 做维护者生命周期管理，可以把 gh-bulk-issues 视为"批量执行阶段"：triage 负责分类与路由（Investigate issue #n），bulk-issues 负责把多个待调查 Issue 一次性并行消化。整套体系的设计哲学是一致的——研究先行、任务隔离、过程可观测、产出必审查。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考