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 Codemc技能体系中的gh-bulk-issuesBulk 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 历史来推荐值得处理的 IssueRUN gh issue list --state open --limit 50 --json number,title,labels,assignees RUN git log --author$(git config user.name) --prettyformat: --name-only --since6 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 的 build2 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/-pparseHeadlessArgs对--timeout 0、--timeout 1.5、--timeout soon均抛错。因此编排时必须给每个 worker 的execute_command配置与--timeout 180030 分钟相匹配的等待上限并以后台进程方式运行、记录每个 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 命令约定 提交、推送并创建 PRConventional commit 标题fix: ...或feat(pkg): ...简洁的 PR 描述并附代码示例引用Closes #NUMBER更新报告文件写入 PR 链接。特别注意技能的最后一条规则Review all mc output before creating PRs — subagent work is untrustedsubagent 的产出不可信。这体现了编排体系的安全底线并行 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 之后包括评论修复后的再次推送都要检查 CIgh pr checks PR_NUMBER若有检查失败在对应 worktree 内 spawn 一个执行/gh-fix-ci的mc实例来诊断并修复。gh-fix-ci 命令 的流程为gh pr statusgh pr checks定位失败 → 深入分析错误信息与失败测试 → 区分 flaky test、真实 bug 与环境问题 → 制定计划实施修复 → 本地跑测试验证 → 提交推送并监控新一轮 CI。超时同样重启并在提示词中带上哪些检查失败、已尝试过什么。一个贯穿始终的硬规则所有与某 Issue 相关的任务调试、PR 评论、CI 修复必须在该 Issue 自己的 worktree 中完成绝不为其另建第二个 worktree。理由很直接worktree 会持续积累上下文commits、diffs、构建产物每次重启的mc实例都能从中受益——这正是把进程隔离与上下文累积统一起来的精妙之处。七、关键规则速查将 SKILL.md 的 Key Rules 整理如下规则原因同时最多 2 个pnpm buildpnpm build是 CPU 密集型限流避免打满开发机所有mc实例可全并行headless 实例是 IO-bound网络、LLM 调用而非 CPU-bound每个 Issue 永远只用一个 worktreeworktree 累积的 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-commentsCI 修复走 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 #nbulk-issues 负责把多个待调查 Issue 一次性并行消化。整套体系的设计哲学是一致的——研究先行、任务隔离、过程可观测、产出必审查。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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 Codemc技能体系中的gh-bulk-issuesBulk 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 历史来推荐值得处理的 IssueRUN gh issue list --state open --limit 50 --json number,title,labels,assignees RUN git log --author$(git config user.name) --prettyformat: --name-only --since6 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 的 build2 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/-pparseHeadlessArgs对--timeout 0、--timeout 1.5、--timeout soon均抛错。因此编排时必须给每个 worker 的execute_command配置与--timeout 180030 分钟相匹配的等待上限并以后台进程方式运行、记录每个 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 命令约定 提交、推送并创建 PRConventional commit 标题fix: ...或feat(pkg): ...简洁的 PR 描述并附代码示例引用Closes #NUMBER更新报告文件写入 PR 链接。特别注意技能的最后一条规则Review all mc output before creating PRs — subagent work is untrustedsubagent 的产出不可信。这体现了编排体系的安全底线并行 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 之后包括评论修复后的再次推送都要检查 CIgh pr checks PR_NUMBER若有检查失败在对应 worktree 内 spawn 一个执行/gh-fix-ci的mc实例来诊断并修复。gh-fix-ci 命令 的流程为gh pr statusgh pr checks定位失败 → 深入分析错误信息与失败测试 → 区分 flaky test、真实 bug 与环境问题 → 制定计划实施修复 → 本地跑测试验证 → 提交推送并监控新一轮 CI。超时同样重启并在提示词中带上哪些检查失败、已尝试过什么。一个贯穿始终的硬规则所有与某 Issue 相关的任务调试、PR 评论、CI 修复必须在该 Issue 自己的 worktree 中完成绝不为其另建第二个 worktree。理由很直接worktree 会持续积累上下文commits、diffs、构建产物每次重启的mc实例都能从中受益——这正是把进程隔离与上下文累积统一起来的精妙之处。七、关键规则速查将 SKILL.md 的 Key Rules 整理如下规则原因同时最多 2 个pnpm buildpnpm build是 CPU 密集型限流避免打满开发机所有mc实例可全并行headless 实例是 IO-bound网络、LLM 调用而非 CPU-bound每个 Issue 永远只用一个 worktreeworktree 累积的 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-commentsCI 修复走 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 #nbulk-issues 负责把多个待调查 Issue 一次性并行消化。整套体系的设计哲学是一致的——研究先行、任务隔离、过程可观测、产出必审查。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考