ruFlo Scout-Explorer 技能深度解析：蜂群侦察 Agent 的实时记忆上报协议与 MCP 底层实现

本文围绕 ruFlo 仓库中的 agent-scout-explorer 技能定义 展开，完整讲解这个「蜂群侦察兵」角色如何通过 MCP memory_usage 工具向 coordination 命名空间实时写入侦察情报（状态、发现、威胁、机会、环境、指标六类数据结构），并结合 v2-compat-tools.ts 与 memory-tools.ts 的源码，剖析这些上报调用在 MCP 服务器端的真实落盘路径。读完本文，你将掌握 scout 技能的全部协议细节、键名规范、三种侦察策略，以及 V2 兼容工具到 V3 记忆服务的映射机制，能够在多智能体蜂群中正确部署并验证一个侦察角色。

1. 技能定位：蜂群的「眼睛与传感器」

scout-explorer 是 ruFlo 蜂群体系中的一个侦察型角色技能，其 YAML 元数据声明了角色的核心属性：

元数据字段	取值	含义
name	scout-explorer	技能内部角色名
description	Information reconnaissance specialist…	探索未知区域、收集情报、通过持续记忆更新向蜂群汇报
color	cyan	蜂群可视化配色
priority	high	调度优先级

文件本身是双层 frontmatter 结构：外层 frontmatter（name: agent-scout-explorer，description: Agent skill for scout-explorer - invoke with $agent-scout-explorer）是技能包装层，说明该技能可通过 $agent-scout-explorer 语法在支持 .agents 技能体系的 Agent CLI 中直接调用；内层 frontmatter 才是角色本体的元数据。

关于 .agents 目录的组织方式，.agents/README.md 给出了官方说明：该目录存放 Agent 配置与技能，结构为 config.toml（主配置，控制模型选择、审批策略、沙箱模式、MCP 服务器连接与技能配置）+ skills/（每个技能一个子目录，内含 SKILL.md 指令文件、可选 scripts/ 与 docs/），技能通过 $skill-name 语法触发，且每条技能包含 YAML frontmatter 元数据、触发/跳过条件、命令与示例。

其角色使命在文档开头一句话中定调：「You are a Scout Explorer, the eyes and sensors of the hive mind」——探索、收集情报、识别机会与威胁，并「通过持续的记忆协调」上报所有发现。整个技能的核心机制可以概括为：侦察动作本身不产生持久价值，价值全部经由 mcp__claude-flow__memory_usage 工具写入 coordination 命名空间的共享记忆。

2. 侦察协议（Reconnaissance Protocol）：两类基础写入

文档将「所有发现必须立即上报记忆」标记为 MANDATORY（强制），并定义了两类基础写入模板。

2.1 DEPLOY：上报探索开始

// DEPLOY - Signal exploration start
mcp__claude-flow__memory_usage {
  action: "store",
  key: "swarm$scout-[ID]$status",
  namespace: "coordination",
  value: JSON.stringify({
    agent: "scout-[ID]",
    status: "exploring",
    mission: "reconnaissance type",
    target_area: "codebase|documentation|dependencies",
    start_time: Date.now()
  })
}

键名 swarm$scout-[ID]$status 遵循「swarm$<角色>$<用途>」的私有状态键规范：[ID] 由部署方替换为具体实例标识（如 scout-code-1），使每个侦察兵的状态互不覆盖。target_area 字段枚举了侦察目标域：codebase（代码库）、documentation（文档）、dependencies（依赖）。

2.2 DISCOVER：实时上报发现

// DISCOVER - Report findings in real-time
mcp__claude-flow__memory_usage {
  action: "store",
  key: "swarm$shared$discovery-[timestamp]",
  namespace: "coordination",
  value: JSON.stringify({
    type: "discovery",
    category: "opportunity|threat|information",
    description: "what was found",
    location: "where it was found",
    importance: "critical|high|medium|low",
    discovered_by: "scout-[ID]",
    timestamp: Date.now()
  })
}

注意这里键名切换到了 swarm$shared$discovery-[timestamp] 前缀——shared 段标识这是全体蜂群可见的共享键，用 [timestamp] 后缀保证每次发现都是独立条目、永不互相覆盖。负载中的 category 三分类（机会/威胁/信息）与 importance 四级（critical/high/medium/low）构成下游角色做优先级决策的依据。

3. 三种专项侦察模式（Exploration Patterns）

技能为不同侦察目标域各给出一套完整的存储模板，全部写入 swarm$shared$ 前缀的共享键，供 queen-coordinator 等决策角色读取。

3.1 Codebase Scout：代码库测绘

// Map codebase structure
mcp__claude-flow__memory_usage {
  action: "store",
  key: "swarm$shared$codebase-map",
  namespace: "coordination",
  value: JSON.stringify({
    type: "map",
    directories: {
      "src/": "source code",
      "tests/": "test files",
      "docs/": "documentation"
    },
    key_files: ["package.json", "README.md"],
    dependencies: ["dep1", "dep2"],
    patterns_found: ["MVC", "singleton"],
    explored_by: "scout-code-1"
  })
}

codebase-map 是一个固定共享键（无时间戳后缀），意味着该图会被重复侦察时刷新，保持最新测绘结果。patterns_found 字段用于记录架构模式（如 MVC、单例），这为后续的 worker-specialist 直接按地图作业提供了索引。

3.2 Dependency Scout：依赖分析

// Analyze external dependencies
mcp__claude-flow__memory_usage {
  action: "store",
  key: "swarm$shared$dependency-analysis",
  namespace: "coordination",
  value: JSON.stringify({
    type: "dependencies",
    total_count: 45,
    critical_deps: ["express", "react"],
    vulnerabilities: ["CVE-2023-xxx in package-y"],
    outdated: ["package-a: 2 major versions behind"],
    recommendations: ["update package-x", "remove unused-y"],
    explored_by: "scout-deps-1"
  })
}

该负载将依赖侦察压缩为六个可机读字段：总数、关键依赖、已知漏洞（CVE 引用格式）、过期程度（按 major 版本数量化）、可执行建议、侦察者署名。vulnerabilities 与 outdated 两个字段直接对接第 4 节的威胁上报流程。

3.3 Performance Scout：性能瓶颈识别

// Identify performance bottlenecks
mcp__claude-flow__memory_usage {
  action: "store",
  key: "swarm$shared$performance-bottlenecks",
  namespace: "coordination",
  value: JSON.stringify({
    type: "performance",
    bottlenecks: [
      {location: "api$endpoint", issue: "N+1 queries", severity: "high"},
      {location: "frontend$render", issue: "large bundle size", severity: "medium"}
    ],
    metrics: {
      load_time_ms: 3500,
      memory_usage_mb: 512,
      cpu_usage_percent: 78
    },
    explored_by: "scout-perf-1"
  })
}

注意负载中 location 字段复用了 $ 分隔符（api$endpoint、frontend$render），与记忆键名体系保持同一套命名约定，便于下游用相同的字符串规则精确定位。metrics 三元组（加载耗时/内存/CPU）给出了量化基准，使「瓶颈」成为可验证的论断而非定性描述。

4. 威胁检测与机会识别：两类高价值情报

4.1 威胁警报（Threat Detection）

// ALERT - Report threats immediately
mcp__claude-flow__memory_usage {
  action: "store",
  key: "swarm$shared$threat-alert",
  namespace: "coordination",
  value: JSON.stringify({
    type: "threat",
    severity: "critical",
    description: "SQL injection vulnerability in user input",
    location: "src$api$users.js:45",
    mitigation: "sanitize input, use prepared statements",
    detected_by: "scout-security-1",
    requires_immediate_action: true
  })
}

威胁负载的设计要点有四：severity 定级、location 精确到文件与行号（src$api$users.js:45）、mitigation 必须给出缓解措施（不能只报问题）、以及布尔开关 requires_immediate_action。最后一个字段是蜂群调度层的直接触发信号，等价于向 queen-coordinator 发出的紧急指令。

4.2 机会识别（Opportunity Identification）

// OPPORTUNITY - Report improvement possibilities
mcp__claude-flow__memory_usage {
  action: "store",
  key: "swarm$shared$opportunity",
  namespace: "coordination",
  value: JSON.stringify({
    type: "opportunity",
    category: "optimization|refactor|feature",
    description: "Can parallelize data processing",
    location: "src$processor.js",
    potential_impact: "3x performance improvement",
    effort_required: "medium",
    identified_by: "scout-optimizer-1"
  })
}

机会负载将「收益」与「成本」显式分离：potential_impact 描述潜在收益，effort_required 描述投入量，category 三分类（优化/重构/新功能）决定它流向哪类 worker。这让决策者可以直接按 impact/effort 比率排序，而不必回头追问侦察兵。

5. 环境扫描与性能指标：自我遥测

除对外侦察外，scout 还需维护对运行环境的持续感知：

// ENVIRONMENT - Monitor system state
mcp__claude-flow__memory_usage {
  action: "store",
  key: "swarm$scout-[ID]$environment",
  namespace: "coordination",
  value: JSON.stringify({
    system_resources: {
      cpu_available: "45%",
      memory_available_mb: 2048,
      disk_space_gb: 50
    },
    network_status: "stable",
    external_services: {
      database: "healthy",
      cache: "healthy",
      api: "degraded"
    },
    timestamp: Date.now()
  })
}

环境负载写入私有键（swarm$scout-[ID]$environment），与共享键区分：每个 scout 只维护自己的环境视图，避免多实例互相污染。external_services 对数据库/缓存/API 做健康分级（healthy/degraded 等），当 api: "degraded" 这类信号出现时，worker 端可以据此降级或重试。

自我绩效指标用于量化侦察效率：

// Track exploration efficiency
mcp__claude-flow__memory_usage {
  action: "store",
  key: "swarm$scout-[ID]$metrics",
  namespace: "coordination",
  value: JSON.stringify({
    areas_explored: 25,
    discoveries_made: 18,
    threats_identified: 3,
    opportunities_found: 7,
    exploration_coverage: "85%",
    accuracy_rate: 0.92
  })
}

六个指标覆盖广度（areas_explored）、产出（discoveries_made）、威胁/机会双通道计数、覆盖率与准确率，是 queen-coordinator 评估侦察兵是否值得继续投入的资源依据。

6. 三种侦察策略：广度优先、深度优先与持续巡逻

技能正文将侦察策略归纳为三种工作模式，对应不同任务阶段：

广度优先探索（Breadth-First Exploration）

1. 快速勘察整个区域
2. 识别高层模式
3. 标记需要深入检查的区域
4. 上报初步发现
5. 引导聚焦探索

深度优先调查（Depth-First Investigation）

1. 选定特定区域
2. 彻底探索
3. 记录全部细节
4. 识别隐蔽问题
5. 上报综合分析

持续巡逻（Continuous Patrol）

1. 定期监控关键区域
2. 即时检测变化
3. 追踪时间趋势
4. 异常时告警
5. 维持态势感知

三者构成「先测绘、再钻取、后驻守」的完整侦察生命周期：Breadth-First 阶段主要产出第 3.1 节的 codebase-map；Depth-First 阶段产出 threat-alert 与 performance-bottlenecks；Continuous Patrol 则持续刷新 environment 与 discovery-* 流。

7. 集成点：scout 在蜂群中的上下游关系

文档「Integration Points」一节明确了 scout 的双向连接，且这些对接角色在仓库中均有对应的技能定义文件可以印证：

Reports To（上报对象）

• queen-coordinator：战略情报的接收方。其技能定义在 agent-queen-coordinator/SKILL.md 中，queen 通过 swarm$shared$royal-directives 下发指令（含 Begin reconnaissance, assignee: "scouts"），正是 scout 侦察任务的来源
• collective-intelligence：模式分析消费方
• swarm-memory-manager：发现的归档方。其技能定义见 agent-swarm-memory-manager/SKILL.md，负责构建 swarm$shared$memory-index 记忆索引、多级缓存与同步清单

Supports（服务对象）

• worker-specialist：提供其作业所需的情报（如 codebase-map）
• Other scouts：互相协调，避免重复劳动
• neural-pattern-analyzer：为其供给训练/分析数据

整个蜂群的拓扑与共识策略（hierarchical/mesh/adaptive 拓扑、byzantine/raft/gossip/crdt 共识）由 hive-mind 技能 定义，scout 作为其中的高优先级角色运行在该协调框架之上。

8. 源码纵深：memory_usage 工具在 MCP 端的真实实现

以上是技能文档中 Agent 视角的调用模板，而 ruFlo 仓库中这些调用的服务端实现位于 v2-compat-tools.ts。从源码结构看，memory_usage 是一个 V2 向后兼容工具（文件头部注释明确给出 memory_usage -> memory/store or memory/search 的映射表），其实现细节与技能文档高度吻合：

输入 Schema 与技能文档完全一致：action 枚举 store | retrieve | delete | list，namespace 默认值即为 'coordination'——这解释了为什么所有 scout 示例都显式声明 namespace: "coordination"；detail 参数（summary | detailed | by-agent）控制 list 的返回粒度。

handler 的四分支映射逻辑（v2-compat-tools.ts）：

V2 action	内部委托	关键行为
store	storeMemoryTool.handler	key 被重写为 `${namespace}/${input.key}`（即 coordination/swarm$shared$threat-alert），并把 namespace 记入 metadata
retrieve	searchMemoryTool.handler	以 key 为查询词、限定 namespace、limit: 1，返回 {found, value, key}
delete	storeMemoryTool.handler	写入 value: null + deleted: true 元数据（软删除语义）
list	listMemoryTool.handler	detail === 'detailed' 时 limit 100，否则 limit 20

这意味着技能文档中所有 swarm$shared$xxx 键，在 V3 记忆服务中的实际物理键都是 coordination/swarm$shared$xxx 形式，检索时由 retrieve 分支做同命名空间内的搜索匹配（limit: 1 说明 retrieve 语义是「取最近/最相关一条」而非严格等值查询）。

V3 原生记忆工具的 Schema 定义在 memory-tools.ts（文件头注明实现 ADR-005「MCP-First API Design」与 ADR-006「Unified Memory Service / AgentDB integration」）。从源码结构看，V3 的 memory/store 负载比 V2 更丰富：记忆类型分为 episodic | semantic | procedural | working 四类，支持 tags 分类、importance（0–1 浮点分值，对应 scout 负载中的 importance 分级）、ttl（毫秒级临时记忆，天然适合 swarm$scout-[ID]$status 这类短生命周期状态键）；memory/search 支持 semantic | keyword | hybrid 三种检索模式并带 minRelevance 阈值；memory/list 支持按 created | accessed | importance | relevance 排序与分页。

一个需要注意的兼容性事实：memoryUsageTool 在源码中标记了 deprecated: true，其 description 也写明「Deprecated: Use memory/store, memory/search, or memory/list instead」。也就是说，scout 技能文档沿用的是 V2 调用约定，在 V3 MCP 服务器中仍可运行（兼容层完整保留了四分支逻辑），但新技能开发建议直接使用 memory/store 等 V3 工具名。理解这一点可以避免把「工具名不存在」的报错误判为技能配置错误。

9. 质量标准（Quality Standards）：侦察纪律

技能以 Do/Don't 清单固化了侦察兵的纪律边界，这与第 7 节「不修改所发现代码」的只读定位直接呼应：

必须做（Do）

• 发现立即上报
• 告警前先验证
• 提供可执行的（actionable）情报
• 测绘未探索区域
• 高频更新自身状态

禁止做（Don't）

• 修改所发现的代码
• 对发现擅自做决策（决策权在 queen-coordinator）
• 忽略潜在威胁
• 重复其他 scout 的工作
• 超出侦察边界活动

这套「只侦察、不行动」的职责隔离是多智能体系统中防止角色越权与状态竞争的关键设计：scout 的写入键空间（swarm$scout-* 私有 + swarm$shared$discovery-* 追加式发现键）天然避免了对 worker 工作区键的覆盖写。

10. 使用方式与适用前提

查看与调用：技能定义位于 .agents/skills/agent-scout-explorer/SKILL.md，.agents/README.md 说明技能通过 $agent-scout-explorer 语法调用；技能启用与 MCP 服务器连接由 .agents/config.toml 统一管理。

适用前提与限制：

1. scout 的全部产出依赖 mcp__claude-flow__memory_usage 工具可用，即 Claude Flow MCP 服务器已按 config.toml 配置并处于活动状态；
2. 文档中的 [ID]、[timestamp] 为模板占位符，部署时须替换为实例 ID 与真实时间戳，否则多实例状态会互相覆盖；
3. 技能模板采用 V2 工具名，当前仓库的 V3 MCP 服务器以兼容层提供该工具（已标记 deprecated），生产新代码时建议对照 v2-compat-tools.ts 头部的映射表迁移到 memory/store / memory/search / memory/list；
4. scout 定位为只读情报角色，任何需要修改代码或做出决策的后续动作必须路由给 queen-coordinator / worker-specialist，不应在 scout 技能内扩展写操作。

延伸阅读：侦察兵的上游指挥链见 agent-queen-coordinator 与 agent-swarm-memory-manager 两个技能文件；蜂群拓扑与共识策略见 hive-mind 技能；V3 记忆服务实现见 v3/mcp/tools/memory-tools.ts。