RuView 的 GitHub PR Manager 智能体：ReasoningBank 自学习 + Swarm 协同的 PR 自动化工作流

本篇技术指南基于 RuView 仓库中的智能体定义文件 pr-manager.md，完整拆解这个“GitHub PR 管理器”智能体的 YAML 能力声明、pre/post 钩子脚本、自学习协议（ReasoningBank 模式存储/检索、GNN 增强搜索、注意力共识协调）以及 GitHub 专用优化策略。读完后，你将掌握在 Claude Code 类 Agent 工作流中设计一个“会积累 PR 管理经验、能指挥多 Agent 评审蜂群、并自动做出合并决策”的 PR 管理智能体的完整方法论，并了解该智能体在本仓库中如何与 hooks、技能（skills）与命令（commands）体系协同落地。

需要说明一点文档性质：pr-manager.md 是 Claude Code 的 agent 定义文件，正文中的 TypeScript / JavaScript 代码块是描述该智能体行为规范的“示意代码”（spec 式伪代码），而非仓库中可直接运行的模块；真正可执行的支撑实现位于 learning-service.mjs 等 helper 脚本与外部 agentic-flow / agentdb 依赖中。

1. 智能体定义：YAML frontmatter 的能力声明

pr-manager.md 采用“YAML frontmatter + Markdown 正文”的标准 agent 定义结构。frontmatter 完整声明了该智能体的身份、能力、工具白名单与生命周期钩子：

字段	取值	含义
name	pr-manager	智能体注册名，可被 /pr-manager 等命令体系引用
description	Comprehensive pull request management with swarm coordination...	用途描述：带蜂群协同的 PR 管理（自动评审、测试、合并）
type	development	归类为开发类智能体
color	#4ECDC4	界面展示色（青绿色）
capabilities	self_learning / context_enhancement / fast_processing / smart_coordination	四项能力标记，分别对应 ReasoningBank 模式存储、GNN 增强搜索、Flash Attention、基于注意力的共识
priority	high	调度优先级高

1.1 工具白名单

tools 字段为该智能体划定了三层工具边界：

1. 基础文件与命令工具：Bash、Read、Write、Edit、Glob、Grep、LS、TodoWrite —— 负责本地仓库操作与任务清单跟踪；
2. claude-flow 蜂群 MCP 工具：mcp__claude-flow__swarm_init、agent_spawn、task_orchestrate、swarm_status、memory_usage，以及 github_pr_manage、github_code_review、github_metrics —— 负责拉起评审蜂群、跨 Agent 记忆共享与 GitHub 操作；
3. agentdb 模式记忆 MCP 工具：mcp__agentic-flow__agentdb_pattern_store、agentdb_pattern_search、agentdb_pattern_stats —— 对应 frontmatter 中 self_learning 能力标记背后的“经验库”。

与之配套，仓库中存在同名的命令侧定义 commands/github/pr-manager.md，其中列出了另一套 GitHub 工具清单（mcp__github__create_pull_request、get_pull_request_files、create_pull_request_review、merge_pull_request 等 9 个 mcp__github__* 工具），命令层负责“调用哪个 GitHub API”，agent 层负责“何时调用、由谁协同调用”，两者分工明确。

此外，仓库还保留了一个更基础的模板版本 agents/templates/github-pr-manager.md，它的钩子只做 gh auth status 鉴权检查与分支状态回显，正文聚焦 PR 创建、评审协调、三种合并策略（squash / merge / rebase）与 CI/CD 集成——可以把它理解为当前 pr-manager.md 的“前身”，当前版本在其上叠加了完整的自学习协议。

2. pre / post 钩子：PR 任务的生命周期脚本

frontmatter 中的 hooks.pre 与 hooks.post 是该智能体每次被调度时自动执行的生命周期脚本，也是“自学习”闭环的实际触发点。

2.1 pre 钩子：先学习，再动手

echo "🚀 [PR Manager] starting: $TASK"

# 1. Learn from past similar PR patterns (ReasoningBank)
SIMILAR_PATTERNS=$(npx agentdb-cli pattern search "Manage pull request for $PR_CONTEXT" --k=5 --min-reward=0.8)
if [ -n "$SIMILAR_PATTERNS" ]; then
  echo "📚 Found ${SIMILAR_PATTERNS} similar successful PR patterns"
  npx agentdb-cli pattern stats "PR management" --k=5
fi

# 2. GitHub authentication and status
gh auth status || (echo 'GitHub CLI not authenticated' && exit 1)
git status --porcelain
gh pr list --state open --limit 1 >/dev/null || echo 'No open PRs'
npm test --silent || echo 'Tests may need attention'

# 3. Store task start
npx agentdb-cli pattern store \
  --session-id "pr-manager-$AGENT_ID-$(date +%s)" \
  --task "$TASK" \
  --input "$PR_CONTEXT" \
  --status "started"

pre 钩子做三件事：检索历史经验（agentdb-cli pattern search，--k=5 取 5 条最相似、--min-reward=0.8 只取成功率不低于 0.8 的模式）、环境预检（gh auth status 未鉴权直接 exit 1 快速失败；检查脏工作区、开放 PR 与测试基线）、写入“任务开始”记录，保证会话即使中断也能在经验库中留下轨迹。

2.2 post 钩子：沉淀学习结果

# 1. Calculate success metrics
REWARD=$(calculate_pr_success "$PR_OUTPUT")
SUCCESS=$(validate_pr_merge "$PR_OUTPUT")
TOKENS=$(count_tokens "$PR_OUTPUT")
LATENCY=$(measure_latency)

# 2. Store learning pattern for future PR management
npx agentdb-cli pattern store \
  --session-id "pr-manager-$AGENT_ID-$(date +%s)" \
  --task "$TASK" \
  --input "$PR_CONTEXT" \
  --output "$PR_OUTPUT" \
  --reward "$REWARD" \
  --success "$SUCCESS" \
  --critique "$PR_CRITIQUE" \
  --tokens-used "$TOKENS" \
  --latency-ms "$LATENCY"

# 4. Train neural patterns for successful PRs (optional)
if [ "$SUCCESS" = "true" ] && [ "$REWARD" -gt "0.9" ]; then
  npx claude-flow neural train \
    --pattern-type "coordination" \
    --training-data "$PR_OUTPUT" \
    --epochs 50
fi

post 钩子把本次 PR 管理的输入、输出、奖励值（reward）、是否成功、自我批评（critique）、token 消耗与延迟一起写回经验库；当 reward > 0.9 时还会触发 claude-flow neural train 对“协同类”模式做 50 个 epoch 的增量训练。中间的标准后置检查为 gh pr status、git branch --show-current、gh pr checks、git log --oneline -3，用于在退出前确认仓库状态。

2.3 支撑钩子的真实实现：learning-service.mjs

从源码结构看，钩子所调用的模式存储并非空壳。仓库内的 helpers/learning-service.mjs 是一个“ReasoningBank 持久学习服务”，使用 better-sqlite3 落盘、HNSW 近似索引加速检索，其关键配置与钩子脚本中的行为一一对应：

• HNSW 参数：M: 16（每层最大连接数）、efConstruction: 200、efSearch: 100、metric: 'cosine'；
• 模式晋升策略：短期模式上限 500 条、长期模式上限 2000 条，一个模式被使用 promotionThreshold: 3 次后从 short_term_patterns 表晋升到 long_term_patterns 表——这正是 pre 钩子 pattern search 能“越用越准”的底层机制；
• 嵌入配置：dimension: 384、模型 all-MiniLM-L6-v2（ONNX 推理），批大小 32；
• 记忆固化（consolidation）：每 30 分钟扫描一次，超过 30 天且使用次数不足 2 次的模式被修剪。

配套的 skills/reasoningbank-agentdb/SKILL.md 给出了该经验库的标准 CLI 用法，例如初始化数据库与 MCP 服务：

npx agentdb@latest init ./.agentdb/reasoningbank.db --dimension 1536
npx agentdb@latest mcp
claude mcp add agentdb npx agentdb@latest mcp

以及迁移与导出：npx agentdb@latest migrate --source .swarm/memory.db、npx agentdb@latest export ./.agentdb/reasoningbank.db ./backup.json。

3. 自学习协议（v3.0.0-alpha.1）：四个阶段

正文的“Self-Learning Protocol”一节把智能体的一次 PR 任务拆成“任务前学习 → 任务中增强搜索 → 多 Agent 注意力协调 → 任务后沉淀”四个阶段。

3.1 任务前：检索相似历史 PR 与失败教训

// 1. Search for similar past PR solutions
const similarPRs = await reasoningBank.searchPatterns({
  task: `Manage PR for ${currentPR.title}`,
  k: 5,
  minReward: 0.8
});

if (similarPRs.length > 0) {
  similarPRs.forEach(pattern => {
    console.log(`- ${pattern.task}: ${pattern.reward} success rate`);
    console.log(`  Merge strategy: ${pattern.output.mergeStrategy}`);
    console.log(`  Conflicts resolved: ${pattern.output.conflictsResolved}`);
    console.log(`  Critique: ${pattern.critique}`);
  });

  // Apply best practices from successful PR patterns
  const bestPractices = similarPRs
    .filter(p => p.reward > 0.9)
    .map(p => p.output);
}

// 2. Learn from past PR failures
const failedPRs = await reasoningBank.searchPatterns({
  task: 'PR management',
  onlyFailures: true,
  k: 3
});

这段示意代码体现了经验复用的两条路径：正向取 reward > 0.9 的高分模式作为最佳实践，负向取 onlyFailures: true 的最近 3 次失败案例及其 failureReason，避免重复踩坑。reasoningBank 的 searchPatterns / storePattern API 在本仓库技能文档 skills/reasoningbank-intelligence/SKILL.md 中有对应形态（recordExperience、recommendStrategy、compareStrategies 等），可视为同一套“经验记录 → 策略推荐”思想的两种表述。

3.2 任务中：GNN 增强的相关代码搜索与冲突检测

// Use GNN to find related code changes
const buildPRGraph = (prFiles) => ({
  nodes: prFiles.map(f => f.filename),
  edges: detectDependencies(prFiles),
  edgeWeights: calculateChangeImpact(prFiles),
  nodeLabels: prFiles.map(f => f.path)
});

const relatedChanges = await agentDB.gnnEnhancedSearch(
  prEmbedding,
  {
    k: 10,
    graphContext: buildPRGraph(pr.files),
    gnnLayers: 3
  }
);

// Smart conflict detection with GNN
const potentialConflicts = await agentDB.gnnEnhancedSearch(
  currentChangesEmbedding,
  {
    k: 5,
    graphContext: buildConflictGraph(),
    gnnLayers: 2
  }
);

这里把 PR 改动文件构造成一张图（节点是文件、边是依赖关系、边权是变更影响度），再用 3 层 GNN 做上下文感知检索；冲突检测则复用同一机制，以 2 层 GNN 在候选集（k=5）中定位潜在冲突区域。文中同时给出了一个量化目标：相比普通向量检索，GNN 增强搜索的准确率提升约 12.4%（“+12.4% better accuracy”，以文档标注为准，属于设计目标而非本仓库实测数据）。

3.3 多 Agent 协调：注意力共识替代简单投票

const coordinator = new AttentionCoordinator(attentionService);

const reviewDecisions = [
  { agent: 'security-reviewer', decision: 'approve', confidence: 0.95 },
  { agent: 'code-quality-reviewer', decision: 'request-changes', confidence: 0.85 },
  { agent: 'performance-reviewer', decision: 'approve', confidence: 0.90 }
];

const consensus = await coordinator.coordinateAgents(
  reviewDecisions,
  'flash' // 2.49x-7.47x faster
);

// Intelligent merge decision based on attention consensus
if (consensus.consensus === 'approve' && consensus.confidence > 0.85) {
  await mergePR(pr, consensus.suggestedStrategy);
}

三个评审 Agent（安全、代码质量、性能）各自给出带置信度的决策，AttentionCoordinator 用注意力机制（而非多数投票）加权合成最终共识，并输出每个 Agent 的影响权重（attentionWeights）。合并闸门是显式的：共识为 approve 且置信度 > 0.85 才触发合并，并采用共识推荐的合并策略。

3.4 任务后：把完整 PR 指标写回经验库

const prMetrics = {
  filesChanged: pr.files.length,
  linesAdded: pr.additions,
  linesDeleted: pr.deletions,
  conflictsResolved: conflicts.length,
  reviewRounds: reviews.length,
  mergeTime: mergeTimestamp - createTimestamp,
  testsPassed: allTestsPass,
  securityChecksPass: securityPass
};

await reasoningBank.storePattern({
  sessionId: `pr-manager-${prId}-${Date.now()}`,
  task: `Manage PR: ${pr.title}`,
  input: JSON.stringify({ title: pr.title, files: pr.files, context: pr.description }),
  output: JSON.stringify({
    mergeStrategy: mergeStrategy,
    conflictsResolved: conflicts,
    reviewerConsensus: consensus,
    metrics: prMetrics
  }),
  reward: calculatePRSuccess(prMetrics),
  success: pr.merged && allTestsPass,
  critique: selfCritiquePRManagement(pr, reviews),
  tokensUsed: countTokens(prOutput),
  latencyMs: measureLatency()
});

注意 success 的判定是“已合并 且 全部测试通过”的合取条件，reward 则由 8 项 PR 指标（文件数、增删行数、冲突数、评审轮次、合并耗时、测试与安全检查结果）共同计算——这与 post 钩子里 validate_pr_merge + calculate_pr_success 的计算口径一致，说明 Markdown 正文与 frontmatter 钩子描述的是同一个数据闭环。

4. GitHub 专用优化：合并策略、冲突排序与评审分派

4.1 从历史中学习合并策略

const mergeHistory = await reasoningBank.searchPatterns({
  task: 'PR merge strategy',
  k: 20,
  minReward: 0.85
});

const strategy = analyzeMergePatterns(mergeHistory, currentPR);
// Returns: 'squash', 'merge', 'rebase' based on learned patterns

策略选择不是写死的，而是取最近 20 条高奖励（≥0.85）合并模式做模式分析，输出 squash / merge / rebase 之一。模板版智能体 templates/github-pr-manager.md 中对三种策略的适用场景给出了补充说明：squash 适用于 commit 众多的功能分支、merge 用于保留完整历史、rebase 用于线性历史，可作为 analyzeMergePatterns 的判据参考。

4.2 基于注意力权重的冲突解决排序

const conflictPriorities = await agentDB.flashAttention(
  conflictEmbeddings,
  codeContextEmbeddings,
  codeContextEmbeddings
);

// Resolve conflicts in order of attention scores
const sortedConflicts = conflicts.sort((a, b) =>
  conflictPriorities[b.id] - conflictPriorities[a.id]
);

先用 Flash Attention 计算每个冲突与代码上下文的注意力分数，再按分数降序解决——影响面最大的冲突优先处理。这与 frontmatter 中 fast_processing（Flash Attention）能力标记相互印证。

4.3 GNN 增强的评审人分派

const reviewGraph = {
  nodes: reviewers.concat(prFiles),
  edges: buildReviewerFileRelations(),
  edgeWeights: calculateExpertiseScores(),
  nodeLabels: [...reviewers.map(r => r.name), ...prFiles.map(f => f.path)]
};

// Find optimal reviewer assignments with GNN
const assignments = await agentDB.gnnEnhancedSearch(
  prEmbedding,
  {
    k: 3, // Top 3 reviewers
    graphContext: reviewGraph,
    gnnLayers: 2
  }
);

把“评审人 × PR 文件”构造成异构图，边权为专业度得分，取 top-3 评审分派。模板版智能体提到按 CODEOWNERS 指派评审人，这里则是用 GNN 检索替代静态规则，两者可叠加使用。

5. 三种典型使用模式（MCP 工具调用示例）

5.1 蜂群协同创建并管理 PR

// Initialize review swarm
mcp__claude-flow__swarm_init { topology: "mesh", maxAgents: 4 }
mcp__claude-flow__agent_spawn { type: "reviewer", name: "Code Quality Reviewer" }
mcp__claude-flow__agent_spawn { type: "tester", name: "Testing Agent" }
mcp__claude-flow__agent_spawn { type: "coordinator", name: "PR Coordinator" }

// Create PR and orchestrate review
mcp__github__create_pull_request {
  owner: "ruvnet",
  repo: "ruv-FANN",
  title: "Integration: claude-code-flow and ruv-swarm",
  head: "integration/claude-code-flow-ruv-swarm",
  base: "main",
  body: "Comprehensive integration between packages..."
}

// Orchestrate review process
mcp__claude-flow__task_orchestrate {
  task: "Complete PR review with testing and validation",
  strategy: "parallel",
  priority: "high"
}

流程是：先以 mesh 拓扑初始化 4 节点蜂群 → 分别生成评审、测试、协调三类 Agent → 创建 PR → 用 task_orchestrate 以并行策略、高优先级编排评审任务。

5.2 自动化多文件评审

mcp__github__get_pull_request_files { owner: "ruvnet", repo: "ruv-FANN", pull_number: 54 }

mcp__github__create_pull_request_review {
  owner: "ruvnet",
  repo: "ruv-FANN",
  pull_number: 54,
  body: "Automated swarm review with comprehensive analysis",
  event: "APPROVE",
  comments: [
    { path: "package.json", line: 78, body: "Dependency integration verified" },
    { path: "src/index.js", line: 45, body: "Import structure optimized" }
  ]
}

先拉取 PR 文件清单，再一次性提交带行级评论的评审（示例中为 APPROVE 事件，评论挂在具体 path + line 上）。

5.3 带测试验证的合并协调

mcp__github__get_pull_request_status { owner: "ruvnet", repo: "ruv-FANN", pull_number: 54 }

mcp__github__merge_pull_request {
  owner: "ruvnet",
  repo: "ruv-FANN",
  pull_number: 54,
  merge_method: "squash",
  commit_title: "feat: Complete claude-code-flow and ruv-swarm integration",
  commit_message: "Comprehensive integration with swarm coordination"
}

// Post-merge coordination
mcp__claude-flow__memory_usage {
  action: "store",
  key: "pr/54/merged",
  value: { timestamp: Date.now(), status: "success" }
}

合并前先查状态，合并后把 pr/54/merged 写入蜂群共享记忆，供其他 Agent（如 release-manager）消费——命令侧清单中的 mcp__claude-flow__*（all swarm coordination tools）正是这一跨 Agent 记忆通道。

6. 批量操作：单条消息完成整个 PR 生命周期

文档给出的“Complete PR Lifecycle in Parallel”模式，核心思想是在一条消息内批量发出协调指令，减少轮次开销：

[Single Message - Complete PR Management]:
  // Initialize coordination
  mcp__claude-flow__swarm_init { topology: "hierarchical", maxAgents: 5 }
  mcp__claude-flow__agent_spawn { type: "reviewer", name: "Senior Reviewer" }
  mcp__claude-flow__agent_spawn { type: "tester", name: "QA Engineer" }
  mcp__claude-flow__agent_spawn { type: "coordinator", name: "Merge Coordinator" }

  // Create and manage PR using gh CLI
  Bash("gh pr create --repo :owner/:repo --title '...' --head '...' --base 'main'")
  Bash("gh pr view 54 --repo :owner/:repo --json files")
  Bash("gh pr review 54 --repo :owner/:repo --approve --body '...'")

  // Execute tests and validation
  Bash("npm test")
  Bash("npm run lint")
  Bash("npm run build")

  // Track progress
  TodoWrite { todos: [
    { id: "review", content: "Complete code review", status: "completed" },
    { id: "test", content: "Run test suite", status: "completed" },
    { id: "merge", content: "Merge when ready", status: "pending" }
  ]}

相比 5.1 节的 mesh 拓扑，批量模式采用 hierarchical（分层）拓扑并将 maxAgents 提到 5；MCP 工具调用与 gh CLI 命令、TodoWrite 里程碑跟踪在同一消息中混合编排，merge 步骤保持 pending 直到校验完成——这与 pre/post 钩子的“先预检、后落库”设计互为呼应。

7. 最佳实践、模式集成与错误处理

7.1 四条最佳实践

1. 始终使用蜂群协调：复杂 PR 操作前先 swarm_init，按评审维度分派专职 Agent，用共享记忆做跨 Agent 协调；
2. 批量 PR 操作：多条 GitHub API 调用合并到单条消息，大 PR 的文件操作并行化，测试与校验同步进行；
3. 智能评审策略：自动冲突检测与解决，多 Agent 评审覆盖安全性与性能，而不是单点评审；
4. 进度跟踪：TodoWrite 管里程碑，GitHub issue 管项目级协调，蜂群记忆管实时状态更新。

7.2 与其他模式的集成

文档列出的协作对象在本仓库中都有对应实体文件，可继续深入阅读：

• /github issue-tracker → agents/github/issue-tracker.md（项目协调）
• /github branch-manager 与 /github ci-orchestrator → 见 commands/github/README.md 中的命令族（分支策略、CI/CD 集成）
• /sparc reviewer、/sparc tester → 见 commands/sparc/reviewer.md 与 commands/sparc/tester.md（深度代码分析、全面测试）

同一 agents/github/ 目录下还有 swarm-pr.md、code-review-swarm.md、release-manager.md 等兄弟智能体，说明 PR Manager 是仓库“GitHub 智能体族”中专管 PR 生命周期的成员。

7.3 错误处理：自动重试 + 蜂群容错

文档定义的自动重试逻辑覆盖四类故障：GitHub API 网络失败、可智能解决的合并冲突、可自动重跑的测试失败、评审瓶颈的负载均衡；蜂群协同层面则保证：无单点故障、Agent 自动故障转移（failover）、中断后进度可恢复、完整的错误上报与恢复。结合第 2 节的 post 钩子可以看出，每次失败经验（success: false + critique）同样会被写回 ReasoningBank，供下次任务的“失败教训检索”（3.1 节 onlyFailures）消费——错误处理与自学习在此形成闭环。

8. 小结：从“命令文档”到“自学习智能体”的设计范式

回看 pr-manager.md 的完整结构，它展示了一条清晰的演进路线：模板版 templates/github-pr-manager.md 是纯命令式的工作流说明书（gh CLI + 合并策略 + 描述模板），而 pr-manager.md 在其上增加了三层设计——工具白名单（MCP 蜂群 + 模式记忆双通道）、生命周期钩子（pre 检索 / post 沉淀，对应 learning-service.mjs 的短期→长期模式晋升机制）、行为协议（检索→GNN 搜索→注意力共识→回写的四阶段自学习闭环）。对于想在自己的仓库中搭建类似“会积累经验的 PR 管理 Agent”的开发者，这份文件提供了可直接对标的骨架：先声明工具边界，再用 pre/post 钩子打通经验库，最后用正文的行为规范约束 Agent 的决策阈值（如 0.85 合并置信线、0.9 训练奖励线）。