RuView 多智能体系统中的 Researcher 研究员智能体：从 YAML 定义到自学习协议的全解

本文深入剖析 RuView 仓库中 Claude Flow 多智能体框架的核心角色——Researcher（研究员）智能体的完整定义（.claude/agents/core/researcher.md），包括其 YAML 元数据与 pre/post 钩子脚本、研究方法论与结构化输出契约、V3 自学习协议（ReasoningBank、HNSW 检索、GNN 模式识别、EWC++ 固化）的 TypeScript 实现细节，以及该智能体如何被仓库内的路由脚本和 Claude Code 钩子体系调度。读完本文，你将掌握在 RuView 这类多智能体研发项目中，一个"研究型 Agent"是如何被声明、被路由、被度量并持续自我改进的。

1. 文档定位：Claude Flow 核心四件套中的研究专家

researcher.md 位于 .claude/agents/core/ 目录下，与 planner.md、coder.md、reviewer.md、tester.md 共同构成 Claude Flow 的核心智能体（core agents）集合。该文件的结构是典型的"Claude Code Subagent 定义"：YAML frontmatter（机器可解析的身份、能力与钩子）+ Markdown 主体（给 LLM 阅读的角色指令）。

frontmatter 中的关键身份字段如下（researcher.md L1-L17）：

name: researcher
type: analyst
color: "#9B59B6"
description: Deep research and information gathering specialist with AI-enhanced pattern recognition
capabilities:
  - code_analysis
  - pattern_recognition
  - documentation_research
  - dependency_tracking
  - knowledge_synthesis
  # NEW v3.0.0-alpha.1 capabilities
  - self_learning         # ReasoningBank pattern storage
  - context_enhancement   # GNN-enhanced search (+12.4% accuracy)
  - fast_processing       # Flash Attention
  - smart_coordination    # Multi-head attention synthesis
priority: high

几个值得注意的设计点：

• type: analyst 将其归入分析型智能体，与 planner 的 coordinator 类型区分开；
• 基础能力 5 项（代码分析、模式识别、文档调研、依赖追踪、知识综合），对应正文中的五大职责；
• # NEW v3.0.0-alpha.1 capabilities 注释标记了 V3 版本新增的 4 项能力，其中内联注释直接说明了每项能力背后的技术（ReasoningBank、GNN、Flash Attention、多头注意力），这是把"能力声明"与"实现原理"绑定在一起的写法；
• priority: high 表明在多智能体并发调度中，研究员任务具有较高优先级。

2. pre/post 钩子：把研究任务接入 V3 记忆与学习管线

文档 L18-L73 的 hooks 字段是本智能体最"硬核"的部分——它不是纯描述，而是两段真正会在任务生命周期中执行的 Bash 脚本，全部基于 npx claude-flow@v3alpha CLI。

2.1 pre 钩子：任务启动前的"历史学习"

echo "🔍 Research agent investigating: $TASK"

# V3: Initialize task with hooks system
npx claude-flow@v3alpha hooks pre-task --description "$TASK"

# 1. Learn from past similar research tasks (ReasoningBank + HNSW 150x-12,500x faster)
SIMILAR_RESEARCH=$(npx claude-flow@v3alpha memory search --query "$TASK" --limit 5 --min-score 0.8 --use-hnsw)
if [ -n "$SIMILAR_RESEARCH" ]; then
  echo "📚 Found similar successful research patterns (HNSW-indexed)"
  npx claude-flow@v3alpha hooks intelligence --action pattern-search --query "$TASK" --k 5
fi

# 2. Store research context via memory
npx claude-flow@v3alpha memory store --key "research_context_$(date +%s)" --value "$TASK"

# 3. Store task start via hooks
npx claude-flow@v3alpha hooks intelligence --action trajectory-start \
  --session-id "researcher-$(date +%s)" \
  --task "$TASK"

执行顺序体现了 V3 的核心思想——先检索再干活：

1. hooks pre-task 向钩子系统注册本次任务；
2. memory search --min-score 0.8 --use-hnsw 用 HNSW 索引从 ReasoningBank 中召回与当前任务相似度 ≥ 0.8 的历史研究模式（文档声称 HNSW 可带来 150x-12,500x 的检索加速，这是文档自身对 claude-flow V3 的表述）；
3. 若命中，则进一步调用 hooks intelligence --action pattern-search --k 5 拉取 Top-5 模式；
4. 用 Unix 时间戳生成 research_context_<ts> 键，把任务描述存入短期记忆；
5. trajectory-start 开启一条"轨迹（trajectory）"记录，后续 post 钩子会用它来落盘完整的学习样本。

2.2 post 钩子：任务结束后的"质量度量 + 模式固化"

echo "📊 Research findings documented"
npx claude-flow@v3alpha memory search --query "research" --limit 5

# 1. Calculate research quality metrics
FINDINGS_COUNT=$(npx claude-flow@v3alpha memory search --query "research" --count-only || echo "0")
REWARD=$(echo "scale=2; $FINDINGS_COUNT / 20" | bc)
SUCCESS=$([[ $FINDINGS_COUNT -gt 5 ]] && echo "true" || echo "false")

# 2. Store learning pattern via V3 hooks (with EWC++ consolidation)
npx claude-flow@v3alpha hooks intelligence --action pattern-store \
  --session-id "researcher-$(date +%s)" \
  --task "$TASK" \
  --output "Research completed with $FINDINGS_COUNT findings" \
  --reward "$REWARD" \
  --success "$SUCCESS" \
  --consolidate-ewc true

# 3. Complete task hook
npx claude-flow@v3alpha hooks post-task --task-id "researcher-$(date +%s)" --success "$SUCCESS"

# 4. Train neural patterns on comprehensive research (SONA <0.05ms adaptation)
if [ "$SUCCESS" = "true" ] && [ "$FINDINGS_COUNT" -gt 15 ]; then
  echo "🧠 Training neural pattern from comprehensive research"
  npx claude-flow@v3alpha neural train \
    --pattern-type "coordination" \
    --training-data "research-findings" \
    --epochs 50 \
    --use-sona
fi

# 5. Trigger deepdive worker for extended analysis
npx claude-flow@v3alpha hooks worker dispatch --trigger deepdive

这段脚本把一个"研究任务"转化成了可度量的学习信号，关键参数含义：

变量 / 参数	计算方式 / 取值	作用
FINDINGS_COUNT	memory search --count-only 计数	本次研究产出的发现条数，是整个奖励函数的输入
REWARD	FINDINGS_COUNT / 20（bc 两位小数）	0-1 区间的启发式质量分：20 条发现即满分
SUCCESS	FINDINGS_COUNT > 5 时为 true	成功与否的硬阈值，决定是否触发下游训练
--consolidate-ewc true	pattern-store 开关	以 EWC++（弹性权重固化）方式合并新经验，防止"灾难性遗忘"
neural train --epochs 50 --use-sona	仅当 SUCCESS 且发现数 > 15	对"高产研究"额外做 50 轮 SONA 自优化神经训练
worker dispatch --trigger deepdive	无条件触发	派发 deepdive worker 做延伸分析

值得强调的是分级触发设计：5 条发现是"及格线"（决定 success），15 条以上是"优秀线"（触发神经训练）。这避免了每次任务都做重训练，把昂贵的学习成本集中在高价值样本上。

3. 核心职责与研究方法论

文档 L88-L94 定义了五大核心职责：代码分析（Code Analysis）、模式识别（Pattern Recognition）、文档审查（Documentation Review）、依赖映射（Dependency Mapping）、知识综合（Knowledge Synthesis）。其后的"研究方法论"（L96-L124）给出了四条可操作路径，其中最实用的是模式分析中给出的四类搜索模式：

# Example search patterns
- Implementation patterns: grep -r "class.*Controller" --include="*.ts"
- Configuration patterns: glob "**/*.config.*"
- Test patterns: grep -r "describe\|test\|it" --include="*.test.*"
- Import patterns: grep -r "^import.*from" --include="*.ts"

这四条命令分别覆盖"找实现、找配置、找测试、找依赖"四种典型调研场景，是理解一个陌生代码库时最先应执行的检索动作。其余三条路径：

1. 依赖分析（Dependency Analysis）：跟踪 import 语句与模块依赖、识别外部包依赖、绘制内部模块关系图、记录 API 契约与接口；
2. 文档挖掘（Documentation Mining）：提取内联注释与 JSDoc、分析 README 与文档、回顾 commit 信息获取上下文、检查 issue tracker 与 PR。

3.1 结构化研究输出契约

L125-L157 规定研究员必须以如下 YAML 结构交付成果。这个 schema 是整个多智能体流水线的"接口协议"——planner 消费 recommendations，coder 消费 codebase_analysis.patterns，tester 消费 gaps_identified：

research_findings:
  summary: "High-level overview of findings"

  codebase_analysis:
    structure:
      - "Key architectural patterns observed"
      - "Module organization approach"
    patterns:
      - pattern: "Pattern name"
        locations: ["file1.ts", "file2.ts"]
        description: "How it's used"

  dependencies:
    external:
      - package: "package-name"
        version: "1.0.0"
        usage: "How it's used"
    internal:
      - module: "module-name"
        dependents: ["module1", "module2"]

  recommendations:
    - "Actionable recommendation 1"
    - "Actionable recommendation 2"

  gaps_identified:
    - area: "Missing functionality"
      impact: "high|medium|low"
      suggestion: "How to address"

其中 gaps_identified.impact 的三档枚举（high/medium/low）为下游排优先级提供了显式依据；patterns.locations 要求落到具体文件，保证结论可追溯。

3.2 三种搜索策略

L159-L181 总结了研究员的检索纪律：

# Start broad
glob "**/*.ts"
# Narrow by pattern
grep -r "specific-pattern" --include="*.ts"
# Focus on specific files
read specific-file.ts

1. 由宽到窄（Broad to Narrow）：先全局 glob 摸文件布局，再按模式 grep 收敛，最后精读目标文件——与本文开头"研究优先、写作其次"的工作方式同构；
2. 交叉引用（Cross-Reference）：搜类/函数定义 → 找全部用法与引用 → 沿系统追踪数据流 → 识别集成点；
3. 历史分析（Historical Analysis）：查看 git 历史、分析提交模式、跟踪重构历史，理解代码的演化脉络。

4. V3 自学习协议：五个 TypeScript 实现细节

文档 L183-L315 是全文技术密度最高的章节，把 pre/post 钩子中 claude-flow@v3alpha CLI 的底层行为翻译成了可直接阅读的 TypeScript 伪代码。

4.1 任务前：从 ReasoningBank 召回历史经验

// 1. Search for similar past research (150x-12,500x faster with HNSW)
const similarResearch = await reasoningBank.searchPatterns({
  task: currentTask.description,
  k: 5,
  minReward: 0.8,
  useHNSW: true  // V3: HNSW indexing for fast retrieval
});

if (similarResearch.length > 0) {
  console.log('📚 Learning from past research (HNSW-indexed):');
  similarResearch.forEach(pattern => {
    console.log(`- ${pattern.task}: ${pattern.reward} accuracy score`);
    console.log(`  Key findings: ${pattern.output}`);
  });
}

// 2. Learn from incomplete research (EWC++ protected)
const failures = await reasoningBank.searchPatterns({
  task: currentTask.description,
  onlyFailures: true,
  k: 3,
  ewcProtected: true  // V3: EWC++ ensures we never forget research gaps
});

两个设计细节：成功模式以 minReward: 0.8 过滤低质量经验；失败经验则单独以 onlyFailures + ewcProtected 召回——"从失败中学习"与"成功路径复用"是两条并行的检索通道，且失败记忆受 EWC++ 保护不随时间冲刷。

4.2 任务中：GNN 增强的模式检索

// Use GNN for better pattern recognition (+12.4% accuracy)
const relevantDocs = await agentDB.gnnEnhancedSearch(
  researchQuery,
  {
    k: 20,
    graphContext: buildKnowledgeGraph(),
    gnnLayers: 3,
    useHNSW: true  // V3: Combined GNN + HNSW for optimal retrieval
  }
);

console.log(`Pattern recognition improved by ${relevantDocs.improvementPercent}%`);
console.log(`Found ${relevantDocs.results.length} highly relevant sources`);
console.log(`Search time: ${relevantDocs.searchTimeMs}ms (HNSW: 150x-12,500x faster)`);

// Build knowledge graph for enhanced context
function buildKnowledgeGraph() {
  return {
    nodes: [concept1, concept2, concept3, relatedDocs],
    edges: [[0, 1], [1, 2], [2, 3]], // Concept relationships
    edgeWeights: [0.95, 0.8, 0.7],
    nodeLabels: ['Core Concept', 'Related Pattern', 'Implementation', 'References']
  };
}

检索参数组合值得记住：k: 20（宽召回）+ gnnLayers: 3（3 层图卷积聚合邻居语义）+ useHNSW: true（ANN 索引兜底低延迟），即"图结构语义 + 近似最近邻"的双引擎检索。文档给出的 +12.4% 准确率提升是该项目对 GNN 检索的表述，属于文档声明值。

4.3 多源综合与大规模文档处理

多智能体综合阶段用注意力协调器把多路研究发现按"多头"视角合成：

// Synthesize findings from multiple sources using attention
const coordinator = new AttentionCoordinator(attentionService);

const synthesis = await coordinator.coordinateAgents(
  [source1Findings, source2Findings, source3Findings],
  'multi-head' // Multi-perspective analysis
);

console.log(`Synthesized research: ${synthesis.consensus}`);
console.log(`Source credibility weights: ${synthesis.attentionWeights}`);
console.log(`Most authoritative sources: ${synthesis.topAgents.map(a => a.name)}`);

输出三要素：consensus（共识结论）、attentionWeights（各来源可信度权重）、topAgents（权威来源排序）——相当于给"多源调研"做了一次带权投票。

文档量超过阈值时切换到 Flash Attention 批处理（据文档描述可获得 2.49x-7.47x 加速、约 50% 内存缩减）：

// Process large documentation sets 4-7x faster
if (documentCount > 50) {
  const result = await agentDB.flashAttention(
    queryEmbedding,
    documentEmbeddings,
    documentEmbeddings
  );
  console.log(`Processed ${documentCount} docs in ${result.executionTimeMs}ms`);
  console.log(`Speed improvement: 2.49x-7.47x faster`);
  console.log(`Memory reduction: ~50%`);
}

SONA（自优化神经架构）则负责把适配器实时调适到当前研究上下文（文档声明 <0.05ms 的适配时延）：

// V3: SONA adapts to your research patterns in real-time
const sonaAdapter = await agentDB.getSonaAdapter();
await sonaAdapter.adapt({
  context: currentResearchContext,
  learningRate: 0.001,
  maxLatency: 0.05  // <0.05ms adaptation guarantee
});

console.log(`SONA adapted to research patterns in ${sonaAdapter.lastAdaptationMs}ms`);

4.4 任务后：EWC++ 模式固化与质量评分函数

研究收尾时，样本连同元数据一起写入 ReasoningBank：

// Store research patterns with EWC++ consolidation
await reasoningBank.storePattern({
  sessionId: `researcher-${Date.now()}`,
  task: 'Research API design patterns',
  input: researchQuery,
  output: findings,
  reward: calculateResearchQuality(findings), // 0-1 score
  success: findingsComplete,
  critique: selfCritique(), // "Comprehensive but could include more examples"
  tokensUsed: countTokens(findings),
  latencyMs: measureLatency(),
  // V3: EWC++ prevents catastrophic forgetting
  consolidateWithEWC: true,
  ewcLambda: 0.5  // Importance weight for old knowledge
});

function calculateResearchQuality(findings) {
  let score = 0.5; // Base score
  if (sourcesCount > 10) score += 0.2;
  if (hasCodeExamples) score += 0.15;
  if (crossReferenced) score += 0.1;
  if (comprehensiveAnalysis) score += 0.05;
  return Math.min(score, 1.0);
}

这里与 post 钩子形成两套评分视角：钩子脚本用简单的"发现数 / 20"计数分，而存储层用四因子加权分（来源数 >10 得 +0.2、含代码示例 +0.15、有交叉引用 +0.1、分析全面 +0.05，封顶 1.0）。ewcLambda: 0.5 控制旧知识的重要度权重，critique 字段保存自我批评文本，使失败样本同样携带可学习的改进方向。

5. 多智能体协同、度量与协作规范

5.1 研究任务的专家分发

复杂研究可经协调器路由给多个专家智能体并行处理：

// Distribute research across specialized agents
const coordinator = new AttentionCoordinator(attentionService);

const distributedResearch = await coordinator.routeToExperts(
  researchTask,
  [securityExpert, performanceExpert, architectureExpert],
  3 // All experts
);

console.log(`Selected experts: ${distributedResearch.selectedExperts.map(e => e.name)}`);
console.log(`Research focus areas: ${distributedResearch.routingScores}`);

routeToExperts 的第三参 3 表示让全部专家参与，返回选中专家与路由分数，便于事后审计"哪个维度由谁负责"。

5.2 持续改进度量

研究员的长期表现可通过模式统计持续追踪：

// Get research performance stats
const stats = await reasoningBank.getPatternStats({
  task: 'code-analysis',
  k: 15
});

console.log(`Research accuracy: ${stats.successRate}%`);
console.log(`Average quality: ${stats.avgReward}`);
console.log(`Common gaps: ${stats.commonCritiques}`);

三个指标——成功率、平均奖励、高频批评——正好对应"做得多不多、做得好不好、差在哪"。

文档 L351-L368 最后给出协作规范与最佳实践：把发现共享给 planner 做任务拆解、为 coder 提供 GNN 增强上下文、向 tester 输送边缘用例、用 ReasoningBank 沉淀供未来检索、用多头注意力做跨源验证；最佳实践六条中强调"彻底（多源验证）、有条理、批判性思维（质疑问预设）、记录一切（未来智能体依赖你的发现）、迭代、持续学习"，并总结为一句核心箴言：好的研究是成功实现的基础，建议前先完整理解上下文。

6. 仓库佐证：researcher 如何被路由与调度

以上定义不是孤立的文件，仓库中有多处源码证据说明它在真实运行链路中的位置。

6.1 任务路由表：什么样的任务会命中 researcher

routing 脚本 定义了智能体能力表与任务模式表（L7-L30）：

const AGENT_CAPABILITIES = {
  // ...
  researcher: ['web-search', 'documentation', 'analysis', 'summarization'],
  // ...
};

const TASK_PATTERNS = {
  // ...
  'research|find|search|documentation|explore': 'researcher',
  // ...
};

routeTask()（L32-L53）对任务描述做正则匹配，命中即返回 {agent: 'researcher', confidence: 0.8, reason: 'Matched pattern: ...'}；若无任何模式命中，默认回落到 coder（confidence 0.5）。也就是说，当用户输入含 research / find / search / documentation / explore 等关键词时，该文件定义的 agent 会被优先调度——这解释了为什么其 frontmatter 中 capabilities 列出的 documentation_research、knowledge_synthesis 与路由表中的 documentation、summarization 标签互为镜像。

6.2 Claude Code 钩子生命周期：pre/post 脚本的触发点

settings.json 把生命周期事件挂到 hook-handler.cjs 上：PreToolUse（Bash 命令执行前）、PostToolUse（Write/Edit/MultiEdit 后）、UserPromptSubmit（用户提交提示时路由）、SessionStart / SessionEnd（会话恢复与收尾，L38-L53）。researcher 的 pre/post 钩子就运行在这套生命周期之内：任务启动对应 hooks pre-task + trajectory-start，会话结束对应 SessionEnd 的收尾逻辑。hook-handler.cjs 中还保留了向用户展示"Alternative agent for researcher"的提示文案（L92 附近），说明路由失败时框架会主动提示可改派 researcher。

6.3 学习服务的 Bash 侧：learning-hooks.sh 与 learning-service.mjs

post 钩子中的模式存储/检索，在仓库里有一个可独立运行的 Bash 实现 learning-hooks.sh，它桥接 Node 侧的 learning-service.mjs：

• 数据落盘目录为 .claude-flow/learning（学习数据）与 .claude-flow/metrics（度量 JSON），见 L8-L9；
• session-start（L35-L81）：初始化学习服务，必要时自动 npm install better-sqlite3，写入 current-session-id 与 learning-status.json（含 hnswEnabled: true 标志）；
• session-end（L86-L145）：导出会话模式 → consolidate 去重/剪枝 → 输出最终统计（短期/长期模式数、平均搜索耗时）；
• store（L150-L180）与 search（L185-L214）：分别对应 post 钩子的"存模式"与 pre 钩子的"查模式"，返回 JSON 中的 action（created/updated）与 searchTimeMs 供上层解析；
• benchmark（L235-L258）：跑 HNSW 性能基准，输出平均/P95 搜索耗时与"预估加速比"——这正是 researcher.md 声称"HNSW 加速"的可度量入口。

对照同目录的 planner.md 可以发现同一套骨架：planner 的 post 钩子用 ($TASKS_COUNT + $AGENTS_ALLOCATED) / 30 计算奖励、以"任务数 > 3"为成功阈值、触发 map worker；researcher 用发现数 / 20、阈值 5、触发 deepdive worker。两个智能体共享相同的"度量 → EWC++ 固化 → 条件训练 → worker 派发"五段式生命周期，仅奖励函数与派发目标不同——这说明 V3 钩子协议是仓库级的统一约定，researcher 是其中的"研究域"实例。

7. 适用前提与使用边界

阅读和使用这份定义时需注意几点仓库事实：

1. 运行前提：pre/post 钩子依赖 npx claude-flow@v3alpha CLI（v3.0.0-alpha.1 预发布版本）与 Node 环境（better-sqlite3 由 learning-hooks.sh 按需安装）。没有该 CLI 时，钩子脚本会失败，agent 仅作为纯 Markdown 角色定义生效；
2. 性能数字属于文档声明：文中出现的 "150x-12,500x"（HNSW 检索加速）、"2.49x-7.47x"（Flash Attention）、"+12.4%"（GNN 准确率）、"<0.05ms"（SONA 适配时延）均出自 researcher.md 及其 frontmatter 注释，是对 claude-flow V3 组件的描述性声明；仓库内 learning-hooks.sh 的 benchmark 子命令提供了可自行测量的入口，本文不将其表述为已验证的实测数据；
3. 奖励函数是启发式的：FINDINGS_COUNT / 20 只衡量发现"数量"，存储层的四因子评分才覆盖质量维度；两者阈值（5 / 15）在 post 钩子中硬编码，调整触发策略需要修改 frontmatter 中的脚本；
4. 路径与版本：本文所有行号均基于当前仓库快照（researcher.md 全文 368 行），V3 能力以 v3.0.0-alpha.1 注释为版本锚点。

8. 小结

researcher.md 示范了"声明式智能体定义"的完整写法：YAML frontmatter 负责身份、能力、优先级与可执行钩子，Markdown 主体负责角色指令、方法论与输出契约；V3 自学习协议（历史召回 → GNN 检索 → 注意力综合 → EWC++ 固化 → SONA 适应）让每一次研究任务同时成为一次训练样本；而 router.js、settings.json、learning-hooks.sh 等仓库内源码则证明了这条链路在 Claude Code 钩子生命周期中有真实的调度与落盘位置。对于希望在自己的项目中构建"会自我改进的研究型 Agent"的开发者，这份文件提供了可直接对标的结构模板：能力声明与实现原理绑定、pre/post 钩子承担"先检索后执行、先度量后固化"的闭环、结构化 YAML 输出作为智能体间的接口协议。