ruflo researcher 深度研究智能体：Skill 定义、研究方法论与 MCP 记忆协作全解

在 ruflo 的多智能体体系中，researcher 是承担前期深度调研的分析型智能体。本文以 agent-researcher 技能定义文件 为主体，完整拆解该技能的 frontmatter 结构、五项核心职责、四步研究方法论与 research_findings 输出规范，并结合 Codex 配置文件、V2 兼容工具源码 等仓库证据，讲清它如何通过 MCP 记忆工具与 planner、coder、tester 等智能体协同。读完后你可以独立读懂一个 ruflo 智能体 Skill 文件的每一行含义，并能按同样范式编写新的研究型智能体。

一、技能文件定位：ruflo 的智能体 Skill 生态

该文件位于 .agents/skills/agent-researcher/SKILL.md，是 ruflo 面向 OpenAI Codex CLI 生态的 .agents 目录下的一个技能单元。根据 .agents 目录说明：

• 技能统一采用 $skill-name 语法调用，因此本技能以 $agent-researcher 触发；
• 每个技能目录包含带 YAML frontmatter 元数据的 SKILL.md，可选携带 scripts/ 与 docs/ 子目录；
• .agents/ 目录由 config.toml 主控配置（模型选择、审批策略、沙箱模式、MCP 服务器连接、技能开关），技能本体则定义智能体的行为准则。

从源码结构看，ruflo 在仓库中同时维护两套 researcher 定义：本文件面向 .agents（Codex CLI）生态，而 plugins/ruflo-core/agents/researcher.md 则是 v3 插件体系中的 "Pathfinder" 研究专家（详见文末）。两者职责一致、工具链不同，本文聚焦前者。

二、文件解剖：双层 YAML frontmatter 与 Agent 元数据

agent-researcher/SKILL.md 的结构分为两部分：外层是技能包装元数据，内层嵌入了完整的 Agent 定义。

2.1 外层：技能包装（Skill 元数据）

---
name: agent-researcher
description: Agent skill for researcher - invoke with $agent-researcher
---

description 中的 "invoke with $agent-researcher" 直接声明了调用方式，与 `.agents/README.md` 所述的 `$skill-name` 约定一致。

2.2 内层：Agent 人格与运行参数

紧随其后的第二个 frontmatter 块定义了 researcher 智能体本身：

---
name: researcher
type: analyst
color: "#9B59B6"
description: Deep research and information gathering specialist
capabilities:
  - code_analysis
  - pattern_recognition
  - documentation_research
  - dependency_tracking
  - knowledge_synthesis
priority: high
hooks:
  pre: |
    echo "🔍 Research agent investigating: $TASK"
    memory_store "research_context_$(date +%s)" "$TASK"
  post: |
    echo "📊 Research findings documented"
    memory_search "research_*" | head -5
---

各字段含义：

字段	取值	作用
name	researcher	智能体在蜂群中的身份名
type	analyst	角色类型：分析师（区别于 coder、tester 等）
color	#9B59B6	蜂群可视化中的展示色
description	Deep research and information gathering specialist	职责一句话概述
capabilities	5 项能力标签	供调度器按能力匹配任务
priority	high	任务队列中的优先级
hooks.pre / hooks.post	Shell 脚本	任务执行前后的生命周期钩子

hooks 的设计体现了"一切皆记忆"的协作思想：pre 钩子在任务开始前把 $TASK 存入以时间戳命名的记忆键 research_context_<epoch>，post 钩子在任务结束后用 memory_search "research_*" 检索最近 5 条相关记忆，实现调研上下文的自动留痕与回收。

三、五项核心职责（Core Responsibilities）

文档将 researcher 的职责收敛为五个方向，这也是它在蜂群中区别于其他智能体的边界：

1. Code Analysis（代码分析）：深入代码库理解实现细节；
2. Pattern Recognition（模式识别）：识别重复出现的模式、最佳实践与反模式；
3. Documentation Review（文档审查）：分析现有文档并找出缺口；
4. Dependency Mapping（依赖映射）：追踪并记录所有依赖与关系；
5. Knowledge Synthesis（知识综合）：把调研结果编译为可执行的洞见（actionable insights）。

这五项职责与内层 frontmatter 的 capabilities 标签一一对应，说明元数据标签不是摆设，而是调度器进行任务-能力匹配的契约。

四、研究方法论：四步工作流

4.1 信息收集（Information Gathering）

文档给出的收集原则：

• 使用多种搜索策略（glob、grep、语义搜索）；
• 完整读取相关文件以获取上下文；
• 在多个位置核查相关信息；
• 考虑不同的命名约定与模式。

4.2 模式分析（Pattern Analysis）

文档提供了四类可直接复用的搜索模式：

# Example search patterns
- 实现模式: grep -r "class.*Controller" --include="*.ts"
- 配置模式: glob "**/*.config.*"
- 测试模式: grep -r "describe\|test\|it" --include="*.test.*"
- 导入模式: grep -r "^import.*from" --include="*.ts"

这些模式分别针对架构骨架（Controller 类）、配置入口、测试分布与模块依赖四类典型调研目标，是 researcher 拿到任务后第一波"面"式扫描的起点。

4.3 依赖分析（Dependency Analysis）

• 追踪 import 语句与模块依赖；
• 识别外部包依赖；
• 映射内部模块关系；
• 记录 API 契约与接口。

4.4 文档挖掘（Documentation Mining）

• 提取行内注释与 JSDoc；
• 分析 README 与文档文件；
• 审查 commit message 获取上下文；
• 检查 issue tracker 与 PR。

五、搜索策略：广→窄收敛、交叉引用、历史分析

5.1 Broad to Narrow（由广到窄）

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

三步收敛路径：先 glob 铺开文件面，再 grep 按模式收窄，最后 read 锁定具体文件精读。

5.2 Cross-Reference（交叉引用）

• 搜索 class$function 定义（即类-函数两级定位）；
• 找出所有用法与引用点；
• 跟踪数据在系统中的流向；
• 识别集成点。

5.3 Historical Analysis（历史分析）

• 审查 git 历史获取上下文；
• 分析 commit 模式；
• 检查重构历史；
• 理解代码的演化轨迹。

六、结构化输出：research_findings YAML 规范

researcher 的交付物不是自由文本，而是一份强结构的 YAML 报告。文档给出的完整模板如下：

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"

字段解读：

• summary：面向协调者的高层结论，保证即使不读全文也能理解发现；
• codebase_analysis.structure / patterns：架构观察与模式清单，每个模式带 locations 定位（可被 coder 直接引用）与 description 用法说明；
• dependencies.external / internal：外部依赖记录 package、version、usage 三元组；内部依赖记录模块及其 dependents（反向依赖方），这对重构影响面评估至关重要；
• recommendations：可执行建议列表，是 planner 做任务分解的直接输入；
• gaps_identified：缺口清单，impact 取 high|medium|low 三档，suggestion 给出弥补方向。

这种"结论 + 证据位置 + 建议 + 缺口"的四段式结构，使下游智能体无需二次调研即可开工。

七、MCP 记忆协作：状态上报、成果共享与历史检索

researcher 与蜂群的其他成员不直接对话，而是全部经由共享记忆（coordination namespace）协作。文档给出了三段完整的 MCP 调用范式。

7.1 上报研究状态

// Report research status
mcp__claude-flow__memory_usage {
  action: "store",
  key: "swarm$researcher$status",
  namespace: "coordination",
  value: JSON.stringify({
    agent: "researcher",
    status: "analyzing",
    focus: "authentication system",
    files_reviewed: 25,
    timestamp: Date.now()
  })
}

键名采用 swarm$researcher$status 的分层命名，value 携带 status、focus、files_reviewed 进度指标与时间戳——协调器据此掌握 researcher 的实时进展。

7.2 共享研究发现

// Share research findings
mcp__claude-flow__memory_usage {
  action: "store",
  key: "swarm$shared$research-findings",
  namespace: "coordination",
  value: JSON.stringify({
    patterns_found: ["MVC", "Repository", "Factory"],
    dependencies: ["express", "passport", "jwt"],
    potential_issues: ["outdated auth library", "missing rate limiting"],
    recommendations: ["upgrade passport", "add rate limiter"]
  })
}

写入的是 swarm$shared$ 前缀的共享键，内容涵盖模式清单、依赖清单、潜在问题与建议——即第六节 YAML 报告的运行时投影。

7.3 检索既有研究

// Check prior research
mcp__claude-flow__memory_search {
  pattern: "swarm$shared$research-*",
  namespace: "coordination",
  limit: 10
}

用通配模式 swarm$shared$research-* 回捞历史研究，避免重复调研并继承前期结论。

7.4 仓库源码佐证：这套工具链在 ruflo 中的实现位置

• MCP 服务器接入：.agents/config.toml 中 [mcp_servers.claude-flow] 段声明了 MCP 接入方式——command = "npx"、args = ["-y", "@claude-flow/cli@latest"]、tool_timeout_sec = 120，即技能文档中所有 mcp__claude-flow__* 调用最终经由此 MCP 服务器路由到 @claude-flow/cli 实现。
• V2 命名兼容层：技能文档使用的是 V2 风格工具名（memory_usage、agent_metrics 等）。从源码结构看，v3/mcp/tools/v2-compat-tools.ts 为这批 V2 名称保留了兼容工具并标记 deprecated: true，文件顶部的映射注释（如 agent_metrics -> agent/status (with includeMetrics: true)，见第 12 行）与第 604 行的工具映射表 'agent_metrics': 'agent/status' 共同说明：V2 名称会自动转发到新的工具名。因此技能中的旧式命名在 v3 运行时依然可用，但新代码建议采用新工具名。
• 记忆命名空间与智能体生成：根目录 SKILL.md 记录了 ruflo 的 MCP 工具面——mcp__claude-flow__memory_*（store/search/list/retrieve，带 HNSW 语义检索）与 mcp__claude-flow__agent_spawn（可生成 coder、reviewer、tester、security-architect 等专项智能体）。researcher 的调研成果正是经这一记忆层供 agent_spawn 生成的下游智能体消费的。

八、分析工具：仓库质量分析与智能体指标

文档在记忆协作之外还列出了两个分析类工具：

// Analyze codebase
mcp__claude-flow__github_repo_analyze {
  repo: "current",
  analysis_type: "code_quality"
}

// Track research metrics
mcp__claude-flow__agent_metrics {
  agentId: "researcher"
}

github_repo_analyze 对当前仓库执行代码质量维度的自动分析，作为 researcher 宏观判断的输入；agent_metrics 则跟踪 researcher 自身的运行指标。关于后者的实现，可以确认：v2-compat-tools.ts 中 agentMetricsTool 接受可选的 agentId 与 metric（all|cpu|memory|tasks|performance）参数，有 agentId 时内部调用 agentStatusTool（includeMetrics: true）取单智能体指标，否则回落到 systemMetricsTool 取系统级 components: ['agents'] 指标——这与技能文档"Track research metrics, agentId: researcher"的用法完全吻合。

九、协作准则与最佳实践

9.1 协作准则（Collaboration Guidelines）

• 通过记忆把发现共享给 planner 用于任务分解；
• 通过共享记忆为 coder 提供实现上下文；
• 向 tester 提供边界条件与测试场景；
• 所有发现都记录在 coordination 记忆中。

这条"记忆即总线"的准则意味着：即使 researcher 会话结束，其结论仍可通过 swarm$shared$ 键被后续任意智能体检索复用。

9.2 最佳实践（Best Practices）

1. Be Thorough：核查多个来源并交叉验证发现；
2. Stay Organized：结构化组织研究，保持笔记清晰；
3. Think Critically：质疑假设、核实论断；
4. Document Everything：所有发现存入 coordination 记忆；
5. Iterate：基于新发现迭代修正研究；
6. Share Early：高频更新记忆以支持实时协作。

文档以此收尾："好的研究是成功实现的基础。在给出建议前先花时间理解完整上下文，并始终通过记忆协作。"

十、延伸：从 .agents 技能到 v3 Pathfinder

理解本技能后，值得对照 plugins/ruflo-core/agents/researcher.md：v3 时代的 researcher 演进为 "Pathfinder research specialist"，将本文第四节的"广→窄"搜索升级为显式的图遍历算法——Seed（agentdb_semantic-route 语义路由种子）→ Expand（agentdb_causal-edge 沿因果边扩展）→ Score（agentdb_pattern-search 按相似度+时近度打分）→ Prune（相似度 < 0.3 剪枝）→ Bridge（用 Read/Grep/Glob 落地到当前代码）→ Synthesize（agentdb_context-synthesize 合并来源）。它同时内置一张"调研模式 × Pathfinder 策略"对照表（代码库扫描、依赖审计、规范检查、风险评估、先行技术检索五类场景各自对应的种子与扩展策略），研究结论最终以 agentdb_hierarchical-store 持久化为图谱节点。对照可见：.agents 技能定义的是方法论骨架，v3 Pathfinder 则把骨架接到了 AgentDB 向量记忆图谱的具体工具上——两者一脉相承，可按所在生态选用。

小结

agent-researcher/SKILL.md 虽只有一份 Markdown，却完整定义了一个可在蜂群中运行的研究型智能体：双层 frontmatter 承载"技能入口 + Agent 元数据 + 生命周期钩子"，五项职责划定角色边界，四步方法论与由广到窄的搜索策略提供可复用的调研流程，research_findings YAML 规范保证交付物结构统一，MCP 记忆协作（状态上报、成果共享、历史检索）则把它无缝接入 ruflo 的协调总线。配合 .agents/config.toml 中的 MCP 服务器、性能与钩子配置，以及 v3/mcp/tools/v2-compat-tools.ts 提供的 V2→V3 工具兼容层，这套定义既保持了向后兼容，又能在 ruflo v3 的记忆与蜂群基础设施上直接运行。