RuView 的 GitHub 集成模式体系：基于 Claude-Flow 与 ruv-swarm 的 Agent 模式设计与 gh CLI 编排实践

本文基于仓库中 github-modes.md 展开，系统讲解 RuView 项目中 Claude-Flow 框架下全部 10 种 GitHub 集成模式的定义结构、工具映射与适用场景，并结合 pr-manager、sync-coordinator 等配套 Agent 定义与 github-setup.sh 脚本，说明这些模式如何通过 pre/post 钩子、批处理操作与 swarm 编排真正驱动 GitHub 工作流。

模式体系的定位与文档布局

该文档的 Overview 明确：它描述 Claude-Flow 中所有可用的 GitHub 集成模式，配合 ruv-swarm 协同，每个模式都针对特定 GitHub 工作流做了优化，并内建批处理工具集成以最大化效率（"Each mode is optimized for specific GitHub workflows and includes batch tool integration for maximum efficiency"）。

从源码结构看，这套体系在仓库中有两处镜像布局：

• .claude/agents/github/github-modes.md：Agent 定义版本，带 YAML frontmatter（下文详述），属于 Agent 规格说明；
• .claude/commands/github/github-modes.md：命令版本，正文与 Agent 版几乎一致，供 Claude Code 的 slash 命令体系调用；
• .claude/agents/github/ 目录下还有 12 个同族 Agent 定义（如 pr-manager.md、issue-tracker.md、release-manager.md、repo-architect.md、sync-coordinator.md、workflow-automation.md 等），各自携带更完整的工具清单、钩子脚本与学习协议，可视为本文各模式的"展开版"；
• .claude/commands/github/ 下另有一组命令文档（issue-triage、code-review、pr-enhance、multi-repo-swarm 等），入口说明见 commands/github/README.md。

也就是说，github-modes.md 是这套 GitHub 自动化能力的总目录，而具体模式的实现细节分散在同目录的兄弟 Agent 定义中。

Agent 定义结构：frontmatter 中的钩子与能力声明

与命令版本不同，Agent 版本的 frontmatter 完整声明了模式的运行契约，这是理解整个体系的入口：

---
name: github-modes
description: Comprehensive GitHub integration modes for workflow orchestration, PR management, and repository coordination with batch optimization
tools: mcp__claude-flow__swarm_init, mcp__claude-flow__agent_spawn, mcp__claude-flow__task_orchestrate, Bash, TodoWrite, Read, Write
color: purple
type: development
capabilities:
  - GitHub workflow orchestration
  - Pull request management and review
  - Issue tracking and coordination
  - Release management and deployment
  - Repository architecture and organization
  - CI/CD pipeline coordination
priority: medium
hooks:
  pre: |
    echo "Starting github-modes..."
    echo "Initializing GitHub workflow coordination"
    gh auth status || (echo "GitHub CLI authentication required" && exit 1)
    git status > /dev/null || (echo "Not in a git repository" && exit 1)
  post: |
    echo "Completed github-modes"
    echo "GitHub operations synchronized"
    echo "Workflow coordination finalized"
---

几个要点值得注意：

• 工具集：声明了 mcp__claude-flow__swarm_init、mcp__claude-flow__agent_spawn、mcp__claude-flow__task_orchestrate 三个 MCP 协同工具，加上 Bash、TodoWrite、Read、Write 四个本地工具。也就是说模式的"手"是 gh CLI（经 Bash 执行），"脑"是 swarm 编排三件套。
• pre 钩子是硬前置校验：先执行 gh auth status，失败即提示"GitHub CLI authentication required"并 exit 1；再执行 git status，不在 git 仓库内同样终止。这决定了使用任何模式的前提是本地已安装并认证 gh CLI，且当前目录处于一个 git 仓库中。仓库中的 github-setup.sh 做了同样的检查——command -v gh 探测安装、gh auth status 探测认证，未通过时给出 gh auth login 提示——两套逻辑互为印证。
• post 钩子只做收尾状态播报（"GitHub operations synchronized / Workflow coordination finalized"），不承担清理职责。

全部 10 种模式：完整清单与适用边界

原文档将模式分为三类共 10 种。以下完整保留各模式的参数、工具与用法说明。

一、GitHub 工作流模式（4 种）

gh-coordinator —— 工作流编排与协调

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

pr-manager —— 拉取请求管理与评审协调

• 评审模式：Automated；多评审者：支持
• 冲突处理：Intelligent
• 工具：gh pr create、gh pr view、gh pr review、gh pr merge、TodoWrite、Task
• 用法：/github pr-manager <PR management task>
• 适用：PR 评审、合并协调、冲突解决

issue-tracker —— 问题管理与项目协调

• 问题工作流：Automated；标签管理：Smart
• 进度跟踪：Real-time
• 工具：gh issue create、gh issue edit、gh issue comment、gh issue list、TodoWrite
• 用法：/github issue-tracker <issue management task>
• 适用：项目管理、issue 协调、进度跟踪

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

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

二、仓库管理模式（3 种）

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

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

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

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

branch-manager —— 分支管理与工作流协调

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

三、集成命令（3 种）

sync-coordinator —— 多包同步

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

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 协调、测试管理、部署自动化

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

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

深入两个代表性模式：模式清单背后的真实实现

模式清单给出的是"路由表"，而每个模式对应的 Agent 定义文件展示了实际执行时的行为深度。

pr-manager：从 gh CLI 到自学习评审

pr-manager.md 是该模式最完整的展开。其 frontmatter 将工具从清单中的 6 个扩展到 20 个左右，新增了 mcp__claude-flow__github_pr_manage、mcp__claude-flow__github_code_review、mcp__claude-flow__github_metrics 以及 mcp__agentic-flow__agentdb_pattern_store/search/stats 等模式库工具；priority 从总目录的 medium 提升到 high。

它的 pre 钩子比总目录版多了三步实质动作：

1. 通过 npx agentdb-cli pattern search "Manage pull request for $PR_CONTEXT" --k=5 --min-reward=0.8 检索历史相似 PR 的处理模式；
2. 执行 gh auth status、git status --porcelain、gh pr list --state open --limit 1 完成环境与状态体检；
3. 用 agentdb-cli pattern store 以 pr-manager-$AGENT_ID-$(date +%s) 为 session 标记记录任务开始。

post 钩子则计算 REWARD/SUCCESS/TOKENS/LATENCY 四类指标并回存模式库，最后执行 gh pr status、git branch --show-current、gh pr checks、git log --oneline -3 四组收尾校验；当 SUCCESS=true 且 REWARD>0.9 时触发 npx claude-flow neural train --pattern-type "coordination" --epochs 50 的神经模式训练。文档正文进一步给出了三类可执行模式：swarm 评审（swarm_init { topology: "mesh", maxAgents: 4 } 后并行 spawn 质量评审、测试、协调三类 Agent）、多文件并行评审（gh pr view 54 --json files 驱动逐文件评论）、带测试验证的合并协调（状态校验通过后以 merge_method: "squash" 合并，并用 memory_usage 存储 pr/54/merged 状态）。

sync-coordinator：多包版本对齐的完整工作流

sync-coordinator.md 展示了"集成命令"类模式的实现深度：它声明了 mcp__github__push_files、mcp__github__create_or_update_file、mcp__github__get_file_contents 等 GitHub MCP 工具，以及 coordination_sync、load_balance 等协同工具。其用法示例包含一条真实的分支创建命令——

gh api repos/:owner/:repo/git/refs \
  -f ref='refs/heads/sync/package-alignment' \
  -f sha=$(gh api repos/:owner/:repo/git/refs/heads/main --jq '.object.sha')

即通过 gh api 基于 main 分支的 SHA 创建同步分支，再用 gh api .../contents/... --method PUT（带 base64 编码内容与 sha 防冲突）推送版本对齐后的 package.json；随后以 task_orchestrate { strategy: "parallel", priority: "high" } 编排验证。文档还给出了版本对齐策略对象（engines.strategy: "highest_common"，取各包最高公共要求）、文档同步模式（指定 source of truth 与目标文件清单）以及跨包测试矩阵，构成"分析—对齐—验证—报告"的闭环。

issue-tracker.md 的 frontmatter 也值得注意：它把能力细化到 9 项（智能模板建 issue、跨仓库 issue 同步、智能标签组织、里程碑协调等），验证了总目录中"Smart 标签管理、Real-time 进度跟踪"两个参数的具体含义。

用法示例：直接可复制的调用方式

原文档给出三个典型的 slash 命令用法，任务描述以自然语言传入，由模式内部映射到 gh CLI 与 swarm 操作：

# 协调式 PR 工作流
/github pr-manager "Review and merge feature/new-integration branch with automated testing and multi-reviewer coordination"

# 仓库/包同步
/github sync-coordinator "Synchronize claude-code-flow and ruv-swarm packages, align versions, and update cross-dependencies"

# 自动化 issue 跟踪
/github issue-tracker "Create and manage integration issues with automated progress tracking and swarm coordination"

批处理操作：单消息内的并行 GitHub 操作

原文档强调"所有 GitHub 模式都支持批处理操作"，并给出一个单消息（BatchTool）示例，说明一次交互内可并行发起多条独立的 gh 命令与状态跟踪：

[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")

设计意图是：相互独立的 GitHub API 调用（建 issue、开 PR）合并到同一轮消息以减少往返，TodoWrite 承担跨操作进度跟踪，最后以 git checkout main && git pull 收尾本地状态。pr-manager 的"Complete PR Lifecycle in Parallel"示例展示了同一思想在 PR 全生命周期的应用：swarm 初始化、建 PR、拉取 PR 文件、提交评审、跑测试（npm test / lint / build）、TodoWrite 里程碑跟踪（review/test/merge 三态）全部并列在同一消息中。

与 ruv-swarm 的集成：拓扑、Agent 角色与任务编排

所有模式都可叠加 ruv-swarm 协同。原文档给出的标准集成序列是：

// Initialize swarm for GitHub workflow
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" }

// Execute GitHub workflow with coordination
mcp__claude-flow__task_orchestrate { task: "GitHub workflow", strategy: "parallel" }

对照各 Agent 定义可以归纳出实际使用的拓扑与角色搭配：PR 评审场景常用 mesh 拓扑 + 4 个 Agent（reviewer/tester/coordinator）；同步场景用 hierarchical + 5~6 个 Agent（coordinator/analyst/coder/tester/reviewer）；恢复场景则用 star 拓扑 + 3 个 Agent（monitor/analyst/coder）。task_orchestrate 的 strategy 取值在文档中观察到 parallel、sequential、adaptive 三种，分别对应并行执行、依赖顺序执行与按条件动态路由。

适用前提与边界

• 运行环境：依赖 gh CLI 且已完成 gh auth login（pre 钩子与 github-setup.sh 双重校验）；必须处于 git 仓库内；
• 依赖的外部能力：mcp__claude-flow__* 与 mcp__agentic-flow__* 系列 MCP 工具、agentdb-cli（模式库检索/存储）、claude-flow CLI（神经模式训练），这些组件来自 Claude-Flow/Agentic-Flow 生态，不属于 RuView 的 WiFi 感知核心，使用时需确认已在当前环境可用；
• 文档定位：.claude/ 目录是项目的 AI 辅助开发配置区，本文所述模式服务于该仓库自身的多包、多仓库协作（claude-code-flow、ruv-swarm 等配套包）场景，与 docs/adr 所记录的 WiFi 感知功能模块相互独立；
• 继续深入的路径：模式清单见 agents/github/github-modes.md，命令侧对照 commands/github/github-modes.md，各模式实现细节以同目录兄弟文件（pr-manager、issue-tracker、sync-coordinator、workflow-automation 等）为准。

综合来看，这份 GitHub 集成模式文档的价值在于它定义了一套"模式路由 + 工具映射 + 钩子契约 + swarm 编排"的四层结构：路由层用 10 个模式覆盖 PR、Issue、发布、仓库、CI、安全六大工作流；工具层把每个模式固定到一组最小化的 gh CLI 子命令；钩子层用 pre 校验（gh 认证 + git 仓库）保证执行前提；编排层则通过 batch 操作与 swarm_init/agent_spawn/task_orchestrate 三件套把单点操作升级为多 Agent 并行流水线。理解这四层，就能在 Claude-Flow 环境中按需选取模式并推演其完整执行路径。