RuView 中的 Code Review Swarm：一个带自学习能力的 Claude Code 多智能体代码评审代理规范

本文以仓库内的代理定义文件 code-review-swarm.md 为核心，完整解析这份 Claude Code 子代理规范的元数据、生命周期钩子、自学习评审协议（ReasoningBank + GNN + Attention 共识）以及基于 gh CLI 的 GitHub 评审操作流程，并结合仓库中的配套命令、技能与邻近代理文件说明其定位、调用关系与运行前提。读完本文后，你可以理解该仓库多智能体体系中“智能代码评审”这一环节是如何被定义与编排的，并能按照文档给出的命令模板在满足依赖前提的项目中组织一次多智能体评审。

文档定位：一个子代理定义文件，而非可执行代码

code-review-swarm.md 位于 .claude/agents/github/ 目录，与 swarm-pr.md、workflow-automation.md 等代理定义并列，属于 Claude Code 自定义子代理（subagent）的声明文件。文件由两部分组成：

1. YAML frontmatter：声明代理名称、能力、可用工具与生命周期钩子，供 Claude Code 在调度时读取；
2. Markdown 正文：描述该代理的行为协议（自学习流程、多智能体协作方式）和面向 GitHub 评审场景的具体命令模板。

理解这一点很重要：该文件本身不包含可执行逻辑，它是交给 Claude Code 运行时遵循的“行为规范”。真正驱动流程的三要素是 frontmatter 中的 tools（工具白名单）、hooks（pre/post 钩子脚本）以及正文中的命令模板。

仓库中还有两个与本文档同主题、但粒度和命令名不同的配套文件，可以对照阅读：

• commands/github/code-review-swarm.md：面向用户触发的命令版说明，命令前缀使用 npx ruv-swarm；
• skills/github-code-review/SKILL.md：技能包形式，frontmatter 中声明了 requires: [github-cli, ruv-swarm, claude-flow]，把评审能力封装为可复用的 skill。

可以推断，agents/ 下的定义负责“代理如何行为”，commands/ 负责“用户如何触发”，skills/ 负责“能力如何打包”，三者共享同一套评审命令模板，只是 CLI 包名存在 claude-flow@v3alpha 与 ruv-swarm 两种写法，这属于仓库内不同文档阶段的命名变体，实际使用时应以具体依赖包为准。

元数据解剖：frontmatter 声明了哪些能力与工具

文件开头的 frontmatter（第 1–83 行）定义了代理的身份与资源边界，关键字段如下：

name: code-review-swarm
description: Deploy specialized AI agents to perform comprehensive, intelligent
  code reviews that go beyond traditional static analysis
type: development
color: blue
capabilities:
  - self_learning         # ReasoningBank pattern storage
  - context_enhancement   # GNN-enhanced search
  - fast_processing       # Flash Attention
  - smart_coordination    # Attention-based consensus
  - automated_multi_agent_code_review
  - security_vulnerability_analysis
  - performance_bottleneck_detection
  - architecture_pattern_validation
  - style_and_convention_enforcement
tools:
  - mcp__claude-flow__swarm_init
  - mcp__claude-flow__agent_spawn
  - mcp__claude-flow__task_orchestrate
  - mcp__agentic-flow__agentdb_pattern_store
  - mcp__agentic-flow__agentdb_pattern_search
  - mcp__agentic-flow__agentdb_pattern_stats
  - Bash
  - Read
  - Write
  - TodoWrite
priority: high

从源码结构看，这份工具白名单揭示了整个评审体系的两条底层通道：

• mcp__claude-flow__* 三个工具（swarm_init、agent_spawn、task_orchestrate）：负责 swarm 的初始化、按职责 spawn 出 security / performance / style / architecture 等专职评审代理、以及任务编排。这与 swarm-pr.md 中展示的 mcp__claude-flow__swarm_init { topology: "mesh", maxAgents: 8 } + 多个 agent_spawn 的用法一致，说明 code-review-swarm 只是 swarm 体系的一个应用实例。
• mcp__agentic-flow__agentdb_pattern_* 三个工具（pattern_store / pattern_search / pattern_stats）：对应 frontmatter 中 self_learning 能力，是“从历史评审中学习”的数据存取层。钩子脚本里调用的 npx agentdb-cli pattern search/store/stats 命令，从命名对应关系看就是这三个 MCP 工具的 CLI 形态。
• Bash / Read / Write / TodoWrite：通用工具，用于执行 gh CLI、读写评审产物与记录待办。

capabilities 字段中的四条注释把四个自学习/加速机制与具体技术一一对应：self_learning 对应 ReasoningBank 模式存储、context_enhancement 对应 GNN 增强检索、fast_processing 对应 Flash Attention、smart_coordination 对应基于 Attention 的共识——这四项也正是正文四节技术内容的主题，后文逐一展开。

生命周期钩子：评审前“先检索经验”，评审后“再沉淀经验”

frontmatter 的 hooks 是整个自学习闭环的执行入口，分为 pre 与 post 两段 shell 脚本。

pre 钩子：检索相似评审经验并登记任务

# 1. 从历史中学习（ReasoningBank）
SIMILAR_REVIEWS=$(npx agentdb-cli pattern search "Code review for $FILE_CONTEXT" \
  --k=5 --min-reward=0.8)
if [ -n "$SIMILAR_REVIEWS" ]; then
  echo "Found ${SIMILAR_REVIEWS} similar successful review patterns"
  npx agentdb-cli pattern stats "code review" --k=5
fi

# 2. GitHub 认证检查
gh auth status || (echo "GitHub CLI not authenticated" && exit 1)

# 3. 登记任务开始
npx agentdb-cli pattern store \
  --session-id "code-review-$AGENT_ID-$(date +%s)" \
  --task "$TASK" \
  --input "$FILE_CONTEXT" \
  --status "started"

三个关键点：

• --k=5 --min-reward=0.8 是检索参数：只取相似度最高的 5 条、且质量分（reward）不低于 0.8 的历史评审模式。这与正文 TypeScript 示例中 reasoningBank.searchPatterns({ k: 5, minReward: 0.8 }) 完全对应，说明钩子脚本与正文伪代码描述的是同一逻辑的两种形态。
• gh auth status 作为硬性门禁：未认证则 exit 1，保证后续所有 gh pr view/diff/comment/review 操作不会静默失败。
• --status "started" 的 store 调用为本次评审创建了一个带时间戳的会话记录（session-id 形如 code-review-$AGENT_ID-<epoch>），post 钩子会向同一个逻辑会话补全结果。

post 钩子：计算质量指标、沉淀模式、条件触发训练

REWARD=$(calculate_review_quality "$REVIEW_OUTPUT")
SUCCESS=$(validate_review_completeness "$REVIEW_OUTPUT")
TOKENS=$(count_tokens "$REVIEW_OUTPUT")
LATENCY=$(measure_latency)

npx agentdb-cli pattern store \
  --session-id "code-review-$AGENT_ID-$(date +%s)" \
  --task "$TASK" \
  --input "$FILE_CONTEXT" \
  --output "$REVIEW_OUTPUT" \
  --reward "$REWARD" \
  --success "$SUCCESS" \
  --critique "$REVIEW_CRITIQUE" \
  --tokens-used "$TOKENS" \
  --latency-ms "$LATENCY"

# 高质量且成功的评审会进一步训练“协调模式”
if [ "$SUCCESS" = "true" ] && [ "$REWARD" -gt "0.9" ]; then
  npx claude-flow neural train \
    --pattern-type "coordination" \
    --training-data "$REVIEW_OUTPUT" \
    --epochs 50
fi

从文件内容看，calculate_review_quality、validate_review_completeness、count_tokens、measure_latency 四个函数在该文档中只有调用、没有定义，可以推断它们是由运行时环境（如 Claude Code 的 hook 执行上下文或配套 helper 脚本）在钩子执行时注入的占位实现，文档本身聚焦于“存什么、何时存”的协议层。沉淀的模式包含 reward（质量分）、success（完整性校验结果）、critique（自评/批评文本）、tokens-used 与 latency-ms 四类元数据——这正是下一次 pre 钩子做 --min-reward=0.8 过滤时依赖的字段。

最后一段 neural train --pattern-type "coordination" --epochs 50 设定了双重门槛（SUCCESS=true 且 REWARD>0.9）才会把一次成功评审作为“协调模式”的训练样本，这对应 smart_coordination 能力：不仅记住“发现了什么问题”，还学习“多智能体是如何协作得出共识的”。

自学习评审协议：评审前后的 ReasoningBank 检索与存储

正文“Self-Learning Protocol (v3.0.0-alpha.1)”一章用 TypeScript 伪代码给出了比钩子脚本更完整的检索/存储语义。

评审前：从成功与失败两路检索

// 检索相似的历史评审（成功路径）
const similarReviews = await reasoningBank.searchPatterns({
  task: `Review ${currentFile.path}`,
  k: 5,
  minReward: 0.8
});

if (similarReviews.length > 0) {
  // 打印每个历史模式的 reward、issuesFound、falsePositives、critique
  // 提炼高质策略：reward > 0.9 且 falsePositives < 0.1
  const bestPractices = similarReviews
    .filter(p => p.reward > 0.9 && p.output.falsePositives < 0.1)
    .map(p => p.output.reviewStrategy);
}

// 同时检索失败的历史评审（降低误报）
const failedReviews = await reasoningBank.searchPatterns({
  task: 'code review',
  onlyFailures: true,
  k: 3
});

这段逻辑的核心是双通道学习：一路从 minReward: 0.8 的成功模式中提炼 reviewStrategy（且用 reward > 0.9 && falsePositives < 0.1 二次筛选出“高质且低误报”的策略）；另一路用 onlyFailures: true 取出 3 条失败模式，打印其 critique 与 falsePositiveRate，提醒本次评审避开曾经踩过的坑。误报率（false positive）被当作与召回同等重要的一级指标贯穿始终。

评审中：GNN 增强的代码依赖图检索

// 构建代码依赖图：节点=文件，边=依赖关系，权重=耦合度
const buildCodeGraph = (files) => ({
  nodes: files.map(f => ({ id: f.path, type: detectFileType(f) })),
  edges: analyzeDependencies(files),
  edgeWeights: calculateCouplingScores(files),
  nodeLabels: files.map(f => f.path)
});

// GNN 增强检索相关代码（文档声明的准确率提升目标：+12.4%）
const relatedCode = await agentDB.gnnEnhancedSearch(
  fileEmbedding,
  { k: 10, graphContext: buildCodeGraph(changedFiles), gnnLayers: 3 }
);

// 用 GNN 检索相似的历史缺陷模式
const bugPatterns = await agentDB.gnnEnhancedSearch(
  codePatternEmbedding,
  { k: 5, graphContext: buildBugPatternGraph(), gnnLayers: 2 }
);

buildCodeGraph 把一个 PR 的变更文件抽象成图：节点带文件类型标签，边由 analyzeDependencies 生成并辅以 calculateCouplingScores 计算耦合权重。随后 gnnEnhancedSearch 在“纯向量检索”之上叠加图上下文（graphContext），用 3 层 GNN 聚合邻域信息来找相关代码、用 2 层找缺陷模式。文档在注释中声明了“+12.4% better accuracy”这一目标值——注意这属于文档声明的性能目标而非实测数据，后文性能目标表中有同一数字。

多智能体共识：AttentionCoordinator 汇总四类评审结论

const coordinator = new AttentionCoordinator(attentionService);

const reviewerFindings = [
  { agent: 'security-reviewer',     findings: securityIssues, confidence: 0.95 },
  { agent: 'performance-reviewer',  findings: perfIssues,     confidence: 0.88 },
  { agent: 'style-reviewer',       findings: styleIssues,     confidence: 0.92 },
  { agent: 'architecture-reviewer', findings: archIssues,      confidence: 0.85 }
];

const consensus = await coordinator.coordinateAgents(reviewerFindings, 'multi-head');

// consensus.consensus / aggregatedFindings.critical / attentionWeights
const prioritizedIssues = consensus.aggregatedFindings.sort(
  (a, b) => b.attentionScore - a.attentionScore
);

协议是：security / performance / style / architecture 四个专职代理各自输出 findings 与置信度，AttentionCoordinator 以 multi-head（多视角）模式做加权汇总，产出共识结论、按严重度聚合的 critical 问题列表、各代理的影响力权重 attentionWeights，最后所有 issue 按 attentionScore 降序排优先级。从源码结构看，这里的“注意力权重”即各代理在最终结论中的话语权，置信度高的代理（如示例中 0.95 的 security-reviewer）会获得更高的聚合权重。

评审后：storePattern 的质量判据

await reasoningBank.storePattern({
  sessionId: `code-review-${prId}-${Date.now()}`,
  task: `Review PR: ${pr.title}`,
  input: JSON.stringify({ files: files.map(f => f.path), context: pr.description }),
  output: JSON.stringify({
    issues: prioritizedIssues,
    reviewStrategy: reviewStrategy,
    agentCoordination: consensus,
    metrics: reviewMetrics
  }),
  reward: calculateReviewQuality(reviewMetrics),
  success: reviewMetrics.falsePositives / reviewMetrics.issuesFound < 0.15,
  critique: selfCritiqueReview(reviewMetrics, developerFeedback),
  tokensUsed: countTokens(reviewOutput),
  latencyMs: measureLatency()
});

这里给出了 success 的量化判据：误报数 / 问题总数 < 0.15 才算成功——与性能目标表中“False Positive Reduction < 15%”互相印证。reviewMetrics 本身包含 filesReviewed、issuesFound、criticalIssues、falsePositives、reviewTime、agentConsensus（取共识置信度）与 developerFeedback，说明开发者反馈也被纳入模式评估的输入。

GitHub 场景专项优化：历史缺陷模式、相似问题代码与风险排序

“GitHub-Specific Review Optimizations”一节给出三个针对评审场景的增强。

1. 基于历史缺陷模式的 issue 检测

const bugHistory = await reasoningBank.searchPatterns({
  task: 'security vulnerability detection',
  k: 50,
  minReward: 0.9
});
const learnedPatterns = extractBugPatterns(bugHistory);
const detectedIssues = learnedPatterns
  .map(pattern => pattern.detect(currentCode))
  .filter(issue => issue !== null);

与评审前检索的 k=5 相比，这里一次性取 50 条、门槛提高到 minReward: 0.9，把历史中最高质量的安全漏洞检测经验编译成一组可执行的 detect 谓词，再逐条作用于当前代码。

2. GNN 检索“曾出过问题的相似代码”

const similarCodeWithIssues = await agentDB.gnnEnhancedSearch(
  currentCodeEmbedding,
  {
    k: 10,
    graphContext: buildHistoricalIssueGraph(),
    gnnLayers: 3,
    filter: 'has_issues'   // 只匹配历史上带 issue 的代码
  }
);

filter: 'has_issues' 是关键差异点：检索目标不是“相似的代码”，而是“相似的且历史上出过 issue 的代码”，命中后逐条打印历史问题类型与描述，用于主动预警（proactively flag）。

3. Flash Attention 风险排序

// 用文件嵌入与风险因子嵌入做注意力计算，得到每个文件的评审优先级
const reviewPriorities = await agentDB.flashAttention(
  fileEmbeddings, riskFactorEmbeddings, riskFactorEmbeddings
);
const prioritizedFiles = files.sort(
  (a, b) => reviewPriorities[b.id] - reviewPriorities[a.id]
);

这段把“文件嵌入 × 风险因子嵌入”的注意力分数作为评审投入的排序依据，让有限的评审预算优先流向高风险文件，对应 frontmatter 的 fast_processing（Flash Attention）能力。

核心评审流程：gh CLI 获取 PR 上下文 + swarm 初始化

“Core Features”一节把上述能力落成可直接复制的 bash 流程。

多智能体评审初始化

# 获取 PR 元数据与 diff
PR_DATA=$(gh pr view 123 --json files,additions,deletions,title,body)
PR_DIFF=$(gh pr diff 123)

# 以 PR 上下文初始化评审 swarm
npx claude-flow@v3alpha github review-init \
  --pr 123 \
  --pr-data "$PR_DATA" \
  --diff "$PR_DIFF" \
  --agents "security,performance,style,architecture,accessibility" \
  --depth comprehensive

# 在 PR 上发布评审启动状态
gh pr comment 123 --body "🔍 Multi-agent code review initiated"

参数含义：--agents 决定 spawn 哪五类专职代理，--depth comprehensive 指定评审深度（命令版文档中还出现 --depth "maximum" 用于安全关键 PR）。配套文档 commands/github/code-review-swarm.md 中给出了同流程的 ruv-swarm 写法，并补充了 review-performance（--profile "cpu,memory,io" --benchmark-against main）与 review-architecture（--check "patterns,coupling,cohesion,solid"）两个子命令，以及按 PR 规模自动选择 swarm 拓扑的规则（见后文“邻近代理”一节）。

安全评审代理：发现 critical 即请求修改

CHANGED_FILES=$(gh pr view 123 --json files --jq '.files[].path')

SECURITY_RESULTS=$(npx claude-flow@v3alpha github review-security \
  --pr 123 \
  --files "$CHANGED_FILES" \
  --check "owasp,cve,secrets,permissions" \
  --suggest-fixes)

# 按严重度分流：critical → request changes + 打标签；否则 → 普通评论
if echo "$SECURITY_RESULTS" | grep -q "critical"; then
  gh pr review 123 --request-changes --body "$SECURITY_RESULTS"
  gh pr edit 123 --add-label "security-review-required"
else
  gh pr comment 123 --body "$SECURITY_RESULTS"
fi

--check "owasp,cve,secrets,permissions" 声明了四个检测面；分流逻辑（critical 触发 gh pr review --request-changes 并加 security-review-required 标签，非 critical 仅评论）是该代理最重要的行为约定，保证了安全结论能以 GitHub 原生机制（review decision + label）介入合并流程。技能包 SKILL.md 中还给出了更完整的检查项清单（SQL 注入、XSS、认证绕过、授权缺陷、加密弱点、依赖漏洞、密钥泄露、CORS 配置错误）与安全 issue 的评论模板（含严重度、影响、建议修复代码、参考链接四段结构），可作为本文命令的输出格式规范。

实现示例：带学习的安全评审

文档最后用一段完整 TypeScript 串联了学习闭环：

// 1. 评审前：取回 reward > 0.9 的历史安全评审
const pastSecurityReviews = await reasoningBank.searchPatterns({
  task: 'security vulnerability review',
  k: 10,
  minReward: 0.9
});
const knownVulnerabilities = extractVulnerabilityPatterns(pastSecurityReviews);

// 2. 评审中：携带已知漏洞模式 + GNN 上下文做安全检测
const securityIssues = await reviewSecurityWithGNN(code, knownVulnerabilities);

// 3. 评审后：有发现即沉淀新安全模式
if (securityIssues.length > 0) {
  await reasoningBank.storePattern({
    task: 'security vulnerability detected',
    output: JSON.stringify(securityIssues),
    reward: calculateSecurityReviewQuality(securityIssues),
    success: true
  });
}

“检索 → 增强检测 → 沉淀”三步与前文 pre/post 钩子形成互证：钩子脚本是这条链路的最小 shell 形态，本文示例则是其在安全子域上的完整语义。

性能目标表：文档声明的目标值

文档内置了如下指标表，均标注了实现机制。需要说明：这些是文档声明的设计目标，仓库中未提供对应的实测基准：

指标	目标值	实现机制
评审准确率（Review Accuracy）	较基线 +12.4%	GNN 检索
误报率（False Positive）	< 15%	ReasoningBank 学习
评审速度（Review Speed）	2.49x–7.47x	Flash Attention
问题检出率（Issue Detection Rate）	> 95%	组合能力
开发者满意度（Developer Satisfaction）	> 90%	Attention 共识

其中“+12.4%”与“<15%”分别在上文 GNN 检索注释和 storePattern 的 success 判据中出现过，三处数字自洽，说明该表是正文协议参数的汇总而非独立来源。

仓库内佐证：这套协议在整个代理体系中的位置

围绕这份规范，仓库提供了多层佐证材料，可以从三个维度交叉验证其设计。

1. 自学习底座：ReasoningBank 四阶段管线

v3/reasoningbank-learner.md 定义了完整的智能管线 RETRIEVE → JUDGE → DISTILL → CONSOLIDATE（HNSW 检索、成败裁决、LoRA 蒸馏、EWC++ 防遗忘巩固），并给出轨迹跟踪命令（trajectory-start/step/end）与模式 schema（含 reward: 0.0–1.0、embedding: number[] 字段）。code-review-swarm 中的 searchPatterns / storePattern / reward / critique 字段与该 schema 一一对应，可以确认评审代理的模式存储并非自定义结构，而是复用了整个 V3 智能层的统一模式库。该文档同时声明了检索延迟目标（HNSW 检索 <5ms），这是钩子脚本能在每次评审前同步完成模式检索的前提。

2. PR 级编排：swarm-pr 的拓扑选择规则

swarm-pr.md 中给出了评审 swarm 的拓扑选择规则：

# Small PR (< 100 lines): ring topology
# Medium PR (100-500 lines): mesh topology
# Large PR (> 500 lines): hierarchical topology

这解释了 code-review-swarm 为什么把 swarm 初始化交给 mcp__claude-flow__swarm_init 而非硬编码拓扑——评审规模由 PR diff 大小动态决定。该文档还定义了按 PR 标签映射代理（bug → [debugger, tester]、security → [security, authentication, audit]）、/swarm ... 评论命令与合并前状态检查（swarm/review-approved 等 required status checks），与本文的 --agents 参数、gh pr edit --add-label 行为构成同一套 PR 生命周期约定。

3. 协调层：三类 swarm coordinator

.claude/agents/swarm/ 下存在 adaptive-coordinator.md、hierarchical-coordinator.md、mesh-coordinator.md 三个协调器定义，与 swarm-pr 中的三种拓扑命名一一对应。正文中 AttentionCoordinator（multi-head 模式）可以推断为这些协调器在评审场景下的注意力变体：拓扑负责“谁和谁通信”，Attention 共识负责“各代理的结论如何加权”。

运行前提与限制

按仓库现状整理该规范的可运行条件与边界：

1. 依赖外部 CLI 包：npx claude-flow@v3alpha ...（命令版文档中为 npx ruv-swarm ...）、npx agentdb-cli ... 均为通过 npx 拉取的外部包，仓库本身不包含这些包源码，只有调用约定；SKILL.md 的 requires 字段明确列出 github-cli、ruv-swarm、claude-flow 三项依赖。
2. GitHub 认证是硬门槛：pre 钩子以 gh auth status 作为门禁，CI 场景需先执行 echo "${GITHUB_TOKEN}" | gh auth login --with-token（命令版文档的 workflow 模板给出了完整示例）。
3. MCP 服务器需可用：mcp__claude-flow__* 与 mcp__agentic-flow__* 工具要求对应 MCP 服务器已接入 Claude Code，否则工具白名单声明的能力无法落地。
4. 钩子中的度量函数由运行时提供：calculate_review_quality 等四个函数未在文档内定义，实际部署时需由 hook 执行环境提供等价实现。
5. 性能数字为声明目标：+12.4%、2.49x–7.47x 等均为文档目标值，引用时应注明“文档声明”，不要当作实测结果。
6. 适用对象：该规范面向“以 Claude Code 为宿主、以 GitHub PR 为协作单元”的研发流程；它定义的是评审代理的行为协议与命令模板，而非一个独立的评审服务。

小结

code-review-swarm.md 在 RuView 仓库多智能体体系中承担“GitHub 代码评审”这一职能，其设计要点可归纳为三层：

• 协议层（frontmatter + hooks）：以 agentdb 模式库为学习底座，评审前检索 min-reward ≥ 0.8 的历史经验，评审后以“误报占比 < 15% 即 success”的判据沉淀新模式，并对 reward > 0.9 的成功评审追加协调模式训练；
• 分析层（正文 TypeScript 示例）：GNN 依赖图检索提供上下文增强，Flash Attention 提供风险排序，AttentionCoordinator 的 multi-head 共识把四个专职代理的输出加权为按注意力分数排序的统一 issue 列表；
• 执行层（bash 命令模板）：gh pr view/diff 采集 PR 上下文 → review-init 按 --agents/--depth 参数化启动 swarm → 安全代理按 critical 与否分流到 request-changes 或普通评论。

结合 reasoningbank-learner.md、swarm-pr.md 与 SKILL.md 三处配套材料，可以看到该评审规范并不是孤立文件：它复用 V3 智能层的统一模式库、服从 swarm 拓扑的动态选择规则，并以 skill 形式对外打包，构成仓库“自学习 + 多智能体 + GitHub 原生流程”三位一体的评审方案。