在 Claude-Flow / ruflo 中使用 `/github` 命令：GitHub 九大集成模式的完整实战指南

关联文档：.claude/commands/github/github-modes.md（本仓库根级命令集）与 v3 命令副本

ruflo（即本仓库内以 Claude-Flow / ruv-swarm 体系为核心的 Agent 元控制台）在 .claude/commands/github/ 下内置了一整套 GitHub 集成命令。本指南以 github-modes.md 为主干，系统讲解九种按工作场景划分的集成模式（工作流协调、仓库管理、集成协同三大类），逐一给出其能力属性、可用工具、调用语法与适用场景；同时结合同目录配套命令文档与 swarm 底层源码，说明如何通过批处理、MCP 工具与 ruv-swarm 协调让这些模式跑出"多智能体并行作业"的效果。读完你将掌握：为 PR 评审、Issue 管理、发布流程、CI/CD 与安全审计选择正确的 /github 子命令，并用 MCP 工具调用完成可落地的 GitHub 自动化工作流。

一、文档定位与命令集全貌

github-modes.md 是一份"模式选型索引"，它没有把九种能力拆成碎片，而是按使用场景归为三类，方便你在接到具体任务时快速对号入座：

分类	模式	一句话定位
GitHub Workflow Modes	gh-coordinator	复杂工作流与多仓库编排
GitHub Workflow Modes	pr-manager	PR 管理与评审协调
GitHub Workflow Modes	issue-tracker	Issue 管理与项目协调
GitHub Workflow Modes	release-manager	发布与部署协调
Repository Management Modes	repo-architect	仓库结构与多仓库组织
Repository Management Modes	code-reviewer	自动化代码评审与质量保障
Repository Management Modes	branch-manager	GitFlow 分支与合并策略
Integration Commands	sync-coordinator	多包同步与版本对齐
Integration Commands	ci-orchestrator	CI/CD 流水线协调
Integration Commands	security-guardian	安全与合规管理

在 .claude/commands/github/ 目录中，这九种模式既有各自独立的命令文档（如 pr-manager.md、issue-tracker.md、release-manager.md、repo-architect.md、sync-coordinator.md），也有配套的 swarm 聚合命令 github-swarm.md 与多仓库场景命令（multi-repo-swarm.md、swarm-pr.md、swarm-issue.md、release-swarm.md、code-review-swarm.md）。同一份模式索引还以 agent 定义形式存在于 .claude/agents/github/github-modes.md，说明这些模式既可以作为"一次性命令"由你显式唤起，也可以作为具备持久上下文的"Agent"常驻协作。

说明：本仓库存在多处 .claude 命令/Agent 镜像（根级 .claude 与 v3/@claude-flow/cli/.claude、v3/@claude-flow/mcp/.claude），其 github-modes.md 内容一致，本文以根级文档为对象讲解，示例同样适用于镜像副本。

二、GitHub Workflow Modes：四种工作流协调模式

这一组的共同特征是以 gh CLI + 任务跟踪（TodoWrite/TodoRead）+ 协调（Task）为核心，适合处理端到端的 GitHub 业务流。

2.1 gh-coordinator —— 工作流编排中枢

当任务涉及"多个仓库、多步骤、跨模块协同"时，gh-coordinator 是首选入口。

• 协调模式：Hierarchical（分层协调）
• 最大并行数：10
• 批处理优化：是
• 可用工具：gh CLI 命令、TodoWrite、TodoRead、Task、Memory、Bash
• 调用语法：/github gh-coordinator <GitHub workflow description>
• 最佳场景：复杂 GitHub 工作流、多仓库协调

所谓 Hierarchical 协调，是让一个"协调者"拆解任务并分派给多级子 Agent；这与 swarm MCP 工具中 swarm_init { topology: "hierarchical" } 的拓扑语义一一对应（详见第六节源码分析）。同时该模式的"Memory"工具暗示其具备跨步骤记忆保持能力，可在多轮工作流中共享仓库上下文。

2.2 pr-manager —— PR 全生命周期管理

• 评审模式：Automated（自动评审）
• 多评审人：支持
• 冲突解决：Intelligent（智能冲突解决）
• 可用工具：gh pr create、gh pr view、gh pr review、gh pr merge、TodoWrite、Task
• 调用语法：/github pr-manager <PR management task>
• 最佳场景：PR 评审、合并协调、冲突解决

配套文档 pr-manager.md 给出了更细的工具面：除了 gh 命令，它还能经由 mcp__github__create_pull_request、get_pull_request、list_pull_requests、create_pull_request_review、merge_pull_request、get_pull_request_files、get_pull_request_status、update_pull_request_branch 等 MCP 工具与 GitHub 对话，并挂接 swarm 记忆与自动重试（网络失败重试、合并冲突智能处理、评审瓶颈负载均衡）。典型完整生命周期见该文档的批处理示例：初始化评审 swarm → gh pr create → gh pr review 54 --approve → npm test && npm run lint && npm run build → TodoWrite 跟踪三项状态。

2.3 issue-tracker —— Issue 与项目进度协调

• Issue 工作流：Automated
• 标签管理：Smart（智能打标）
• 进度跟踪：Real-time（实时）
• 可用工具：gh issue create、gh issue edit、gh issue comment、gh issue list、TodoWrite
• 调用语法：/github issue-tracker <issue management task>
• 最佳场景：项目管理、Issue 协调、进度跟踪

配套文档 issue-tracker.md 内置了两套可直接复用的模板：集成任务模板（含 Dependencies / Functionality / Testing 三组验收清单）与 Bug 报告模板（含问题描述、期望/实际行为、复现步骤、环境、排查计划、swarm 分工）。它还演示了"多 Issue 项目协调"：用 search_issues 检索同标签/同状态的关联 Issue 后批量更新 labels、milestone，并把进度写入 swarm 记忆键 issue/<n>/progress，实现跨 Agent 的实时状态同步。

2.4 release-manager —— 发布协调与部署

• 发布流水线：Automated
• 版本化：Semantic（语义化版本）
• 部署：Multi-stage（多阶段）
• 可用工具：gh pr create、gh pr merge、gh release create、Bash、TodoWrite
• 调用语法：/github release-manager <release task>
• 最佳场景：发布管理、版本协调、部署流水线

该模式与仓库中的发布实践相互印证：本仓库根目录与各插件都维护 CHANGELOG.md（如 CHANGELOG.md、v3/@claude-flow/cli/CHANGELOG.md），并存在 prepare-root-publish.mjs、prepare-publish.mjs 等发布脚本——release-manager 正是把"打标签、改版本、创建 release"这类语义化发布动作交给 Agent 统一协调的入口。

三、Repository Management Modes：三种仓库管理模式

这一组偏重"仓库本身"的结构、质量与分支治理，工具面更多落在 gh repo、git 与文件读写上。

3.1 repo-architect —— 仓库结构与多仓库组织

• 结构优化：支持
• 多仓库：支持
• 模板管理：Advanced
• 可用工具：gh repo create、gh repo clone、git 命令、Write、Read、Bash
• 调用语法：/github repo-architect <repository management task>
• 最佳场景：仓库初始化、结构优化、多仓库管理

提示：仓库根级 AGENTS.md 与本仓库大量 monorepo 实践（crates/、plugins/、v3/ 多包共存）都印证了"结构即约定"的组织思路；使用 repo-architect 做新仓库初始化时，可结合 CONTRIBUTING.md 与各插件 README 来生成一致的目录骨架。

3.2 code-reviewer —— 自动化评审与质量保障

• 评审深度：Deep
• 安全分析：支持
• 性能检查：Automated
• 可用工具：gh pr view --json files、gh pr review、gh pr comment、Read、Write
• 调用语法：/github code-reviewer <review task>
• 最佳场景：代码质量、安全评审、性能分析

gh pr view --json files 用于先取出 PR 改动文件清单，再交给评审 Agent 逐文件 Read/Write。这与仓库中的评审驱动实践一致：根级存在 .claude/agents/reviewer.yaml 等角色定义，并有独立子命令 code-review.md 与 code-review-swarm.md。仓库还专门编写了 audit-*.mjs、smoke-*.mjs 系列脚本（如 audit-tool-descriptions.mjs、smoke-github-actions-pins.mjs），可作为评审 Agent 在本地补强"安全/合规"维度的检测抓手。

3.3 branch-manager —— 分支与合并策略治理

• 分支策略：GitFlow
• 合并策略：Intelligent
• 冲突预防：Proactive（主动预防）
• 可用工具：gh api（用于分支操作）、git 命令、Bash
• 调用语法：/github branch-manager <branch management task>
• 最佳场景：分支协调、合并策略、工作流管理

注意该模式以 gh api 而非 gh branch 之类的命令驱动分支操作——GitHub 本身没有 gh branch 子命令，因此文档刻意用 gh api 直接调 REST/GraphQL 端点完成"基于上游更新分支""校验保护分支规则"等操作。

四、Integration Commands：三种集成协同模式

这一组是面向"开发流程中需要横向打通"的场景：多包版本、CI/CD 状态、安全基线。

4.1 sync-coordinator —— 多包同步与版本对齐

• 包同步：Intelligent
• 版本对齐：Automatic
• 依赖解析：Advanced
• 可用工具：git 命令、gh pr create、Read、Write、Bash
• 调用语法：/github sync-coordinator <sync task>
• 最佳场景：包同步、版本管理、依赖更新

原文档的示例即"同步 claude-code-flow 与 ruv-swarm 两包、对齐版本并更新交叉依赖"——这种场景正是 monorepo 日常。本仓库有真实参照：package.json 使用 package-lock.json 与 pnpm-lock.yaml 双锁文件、pnpm-workspace.yaml 声明工作区，多个 crates 子包共享根级 Cargo.toml（workspace），v3/@claude-flow/* 又是独立 TS 包群；跨包版本对齐与依赖升级正是 sync-coordinator 的用武之地。

4.2 ci-orchestrator —— CI/CD 流水线协调

• 流水线管理：Advanced
• 测试协调：Parallel（并行）
• 部署：Automated
• 可用工具：gh pr checks、gh workflow list、gh run list、Bash、TodoWrite、Task
• 调用语法：/github ci-orchestrator <CI/CD task>
• 最佳场景：CI/CD 协调、测试管理、部署自动化

它通过 gh pr checks 读取 PR 状态检查、gh workflow list/gh run list 枚举与回放 workflow 运行，把"等待测试 → 定位失败 → 重跑"从人工轮询变成 Agent 主动编排。仓库自身的测试基建（如根级 vitest、tests/ 下的 docker-regression 与各类 smoke-*.mjs）可作为并行测试任务的真实清单来源。

4.3 security-guardian —— 安全与合规管理

• 安全扫描：Automated
• 合规检查：Continuous
• 漏洞管理：Proactive
• 可用工具：gh search code、gh issue create、gh secret list、Read、Write
• 调用语法：/github security-guardian <security task>
• 最佳场景：安全审计、合规检查、漏洞管理

该模式用 gh search code 全局检索疑似泄露的密钥/模式、用 gh secret list 校验仓库 Secrets 配置、对发现项以 gh issue create 建档跟踪。本仓库在 SECURITY.md 与 .claude/settings.json 之外还沉淀了大量安全审计脚本（audit-supply-chain.mjs、audit-hook-handler-prompt.mjs、smoke-github-safe-injection.mjs 等），可作为 security-guardian 本地预检的后端命令。

五、命令实战示例与批处理

5.1 三条开箱即用的调用

原文档给出了三个高频用法，均以 /github <mode> "<自然语言任务描述>" 形式唤起（在 Claude Code / claude-flow 会话中直接输入）：

# 1) 带自动化测试与多评审人协调的 PR 全流程
/github pr-manager "Review and merge feature/new-integration branch with automated testing and multi-reviewer coordination"

# 2) 跨包同步与版本对齐
/github sync-coordinator "Synchronize claude-code-flow and ruv-swarm packages, align versions, and update cross-dependencies"

# 3) 带自动化进度跟踪与 swarm 协调的 Issue 管理
/github issue-tracker "Create and manage integration issues with automated progress tracking and swarm coordination"

5.2 批处理：单条消息并行多条 GitHub 操作

"Batch Optimized"是九种模式的共性能力。由于模式本身由 Agent 执行，它可以在一条消息内并发发起多个工具调用，从而把往返延迟摊平。原文档的示意（JavaScript 伪代码）如下：

[Single Message with BatchTool]:
  Bash("gh issue create --title 'Feature A' --body '...'")
  Bash("gh issue create --title 'Feature B' --body '...'")
  Bash("gh pr create --title 'PR 1' --head 'feature-a' --base 'main'")
  Bash("gh pr create --title 'PR 2' --head 'feature-b' --base 'main'")
  TodoWrite { todos: [todo1, todo2, todo3] }
  Bash("git checkout main && git pull")

要点：

• 同类操作（如两个 gh issue create、两个 gh pr create）并行发出，提升批量创建/批量更新吞吐；
• 用 TodoWrite 在并行操作之前先把 todo 清单登记好，便于随后逐项核对结果；
• 先 git checkout main && git pull 保证本地基线最新，避免批量操作基于过期快照执行。
• 在 pr-manager.md 的完整生命周期示例中，并行段还扩展了 npm test / npm run lint / npm run build 三个验证命令与「review/test/merge」三段式 Todo，可作为更真实的模板。

六、与 ruv-swarm 的深度集成

6.1 让 GitHub 任务拥有多智能体协调能力

原文档明确指出：所有 GitHub 模式都可以叠加 ruv-swarm 协调来增强。示意如下：

// 初始化 GitHub 工作流 swarm
mcp__claude-flow__swarm_init { topology: "hierarchical", maxAgents: 5 }
mcp__claude-flow__agent_spawn { type: "coordinator", name: "GitHub Coordinator" }
mcp__claude-flow__agent_spawn { type: "reviewer", name: "Code Reviewer" }
mcp__claude-flow__agent_spawn { type: "tester", name: "QA Agent" }

// 以并行策略编排 GitHub 工作流
mcp__claude-flow__task_orchestrate { task: "GitHub workflow", strategy: "parallel" }

分工含义：

• swarm_init：先声明拓扑与规模。topology: "hierarchical"（分层）适合"coordinator 拆任务 → reviewer/tester 分工"；pr-manager.md 与 issue-tracker.md 分别示范了 topology: "mesh"（评审 Agent 平级互审）与 topology: "star"（以 Issue Manager 为中心）的用法；
• agent_spawn：按角色孵化子 Agent。coordinator（编排）、reviewer（评审）、tester（测试）是三个基础角色；issue-tracker 还用到 researcher（需求分析）、analyst（进度跟踪）等角色，对应命令文档中"按 Issue 类型指派专职 Agent"的最佳实践；
• task_orchestrate：把"GitHub workflow"作为一个整体任务下发，strategy: "parallel" 表示并行执行，priority 可配 high/medium 等优先级。

6.2 底层机制：swarm MCP 工具的源码印证

这些 mcp__claude-flow__swarm_* 工具并非占位示例，在本仓库中有真实实现。从源码 swarm-tools.ts 可以看出：

• swarm 状态以文件方式持久化到项目目录下的 .claude-flow/swarm/swarm-state.json（带 .lock 锁文件与 10s 过期机制，见第 33~36 行常量定义），并区分 initializing / running / paused / shutting_down / terminated 五种生命周期状态（第 42 行）；
• SwarmState 结构体中的 topology、maxAgents、agents[]、tasks[] 字段，正是上文 swarm_init / agent_spawn / task_orchestrate 三类调用所写入的内容，两者语义完全对齐；
• 文件操作使用 O_CREAT + 临时文件 renameSync 原子替换 + statSync 等方式管理并发（第 8~18 行引入 node:fs 相关 API），说明同一时刻多个 GitHub 子 Agent 写进度是有并发保护的。

结合这些源码证据，你可以推断：/github pr-manager 这类命令在会话内的执行，实质上会通过同一套 MCP 工具建立 swarm 状态，评审进度与合并结论可写入 .claude-flow/swarm 状态目录，从而实现跨 Agent、跨消息的上下文延续。

运行前提提示：要复现上述 MCP 调用，需要你的 Claude Code / claude-flow 环境已加载 claude-flow 的 MCP 服务器与对应工具（工具命名前缀 mcp__claude-flow__ 即 MCP 命名空间约定）。.claude/mcp.json 展示了此类 MCP 服务器的标准声明方式（name、command、args、env 结构），可参照配置你自己的服务器条目。

七、模式选型建议与配套资料

7.1 一张图选型

• 任务跨多仓库 / 流程长 → gh-coordinator；
• 核心是"评审并合入一个 PR" → pr-manager；
• 核心是"跟踪并推进一堆 Issue/里程碑" → issue-tracker；
• 核心是"走一遍发版流水线" → release-manager；
• 核心是"搭/理仓库结构" → repo-architect；
• 核心是"给代码改动挑毛病" → code-reviewer；
• 核心是"理分支/定合并策略" → branch-manager；
• 核心是"对齐 monorepo 多包版本" → sync-coordinator；
• 核心是"盯 CI 运行与失败重跑" → ci-orchestrator；
• 核心是"扫密钥/查合规/管 Secrets" → security-guardian。

复杂场景无需单选——pr-manager.md 与 issue-tracker.md 都列出了"模式互操作"清单，例如 pr-manager 可搭配 issue-tracker（Issue 关联 PR）、branch-manager（分支策略）、ci-orchestrator（CI 集成）；.claude/agents/github/ 下的独立 Agent（multi-repo-swarm、project-board-sync、release-swarm 等）则覆盖更垂直的专项。

7.2 需要 gh CLI 的命令

文档中多数模式的工具面直接以 gh 子命令书写（gh pr *、gh issue *、gh release *、gh search *、gh workflow *、gh run *、gh secret list、gh api）。运行这些模式前请确保本机已安装并认证 GitHub CLI（gh auth status 可验证）。部分操作也可被等价的 mcp__github__* MCP 工具替代（见 pr-manager.md 工具清单），两类通道可以混用。

7.3 进一步阅读

• 命令聚合入口：.claude/commands/github/README.md 与 github-swarm.md（npx claude-flow github swarm 一键拉起含 Issue Triager / PR Reviewer / Documentation / Test / Security 五类 Agent 的仓库管理 swarm）；
• 仓库结构说明：AGENTS.md、SKILL.md、README.md；
• swarm 状态实现：swarm-tools.ts；
• 评审/测试与安全脚本样例：scripts/ 下的 audit-*.mjs、smoke-github-*.mjs 系列。