ruflo Neural Pattern Training 实战：在 Claude Code 中通过 mcp__claude-flow 神经网络工具训练协作与优化模式

2026-09-07 12:26:59作者：郜逊炳

🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

项目地址：https://gitcode.com/GitHub_Trending/cl/ruflo

本文围绕项目根目录命令定义文档 .claude/commands/memory/neural.md 展开，系统讲解 ruflo（Claude Code Agent Meta-Harness）中「Neural Pattern Training（神经模式训练）」这一命令的能力边界、调用约定与实战用法：它借助 mcp__claude-flow__neural_train 等 MCP 工具，为 Claude Code 沉淀"任务拆解、协调模式选择、资源分配"等高阶协作模式，而不越界编写代码、访问文件或执行命令。读者在阅读后将能准确区分"协调工具"与"执行工具"的职责，并掌握训练、状态查询、模式分析到源码落地的完整闭环。

一、命令是什么：定位为"协调器"而非"代码编写器"

打开 .claude/commands/memory/neural.md，文档开门见山用一行加粗文字给出本命令不可动摇的原则：

This tool coordinates Claude Code's actions. It does NOT write code or create content. （该工具负责协调 Claude Code 的动作，它不写代码、不生成内容。）

这是一条"职责分界线"：在 Agent Meta-Harness 的多智能体场景里，神经工具负责提供协调与结构（coordination and structure），而 Claude Code 本身负责一切实际实现（all actual implementation）。文档后续的 Important Reminders 用正反两面对这条边界做了完整列举：

角色	该工具负责	该工具不负责
可以 / 必须	提供协调与结构	—
可以 / 必须	由 Claude Code 完成全部实际实现	—
禁止	—	不写代码（does NOT write code）
禁止	—	不直接访问文件（does NOT access files directly）
禁止	—	不执行命令（does NOT execute commands）

从目录结构看，该文件位于 .claude/commands/memory/ 目录下，属于 Claude Code 的 memory 命令类别（同类命令的入口索引见 .claude/commands/memory/README.md，该索引列出了 memory-usage、memory-persist、memory-search 等同族命令）。同时仓库里存在一份逐字一致的副本，随 CLI 一起发布在 v3/@claude-flow/cli/.claude/commands/memory/neural.md（经 diff 校验二者内容完全相同）。这说明该命令文档既服务本项目自身的运行，也作为命令模板随 CLI 分发。

这条边界之所以重要，是因为"训练"这个动作在文档中被定义为纯数据层面的事后沉淀：Claude Code 先靠自己的能力完成任务，神经工具再把"怎样做任务才高效"这类成功模式记录下来供后续复用——它是一个学习回路（learning loop）的记录端，而不是任务的执行端。

二、调用约定：MCP Tool Usage in Claude Code

文档明确了在 Claude Code 中通过 MCP 前缀调用神经网络训练工具：

**Tool:** `mcp__claude-flow__neural_train`

这里 mcp__<server>__<tool> 是 Claude Code 调用 MCP 工具的命名规范：claude-flow 是对应 MCP server 名，neural_train 是工具名。仓库源码在 v3/@claude-flow/cli/src/mcp-client.ts 中通过 registerTools 注册了 ...neuralTools（约第 152 行），将所有神经工具放入 TOOL_REGISTRY 供 MCP 层调度，随后 Claude Code 侧即可按上述命名规则访问。

文档给出的调用参数样例为：

{
  "pattern_type": "coordination",
  "training_data": "task decomposition patterns",
  "epochs": 50
}

三个参数的语义如下：

参数	含义	文档示例取值
`pattern_type`	要训练的模式类别（如协调类、优化类）	`coordination`
`training_data`	用于训练的语料/经验来源	`task decomposition patterns`（任务拆解模式）
`epochs`	训练轮次	`50`

需要说明的是：这份命令文档中的 pattern_type、training_data 属于面向 Agent 的语义化参数，描述的是"要沉淀哪一类经验"；而仓库当前源码 v3/@claude-flow/cli/src/mcp-tools/neural-tools.ts（第 411 行起导出 neuralTools）中 neural_train 实际的输入 JSON Schema 字段为：

{
  "modelId": "string, 可选，默认自动生成 model-<timestamp>-<rand>",
  "modelType": "string, 必填，枚举 moe | transformer | classifier | embedding",
  "epochs": "number, 可选，默认 10（文档示例常用 50）",
  "learningRate": "number, 可选，默认 0.001",
  "data": "object | array, 训练数据，可为字符串文本或含 text/content/label 等字段的对象"
}

即文档描述"训练什么类型/用什么素材"，Schema 定义"底层工具真正接收什么结构"——二者是不同抽象层级对同一能力的描述，接入不同版本或不同命名空间的 MCP 服务（仓库中还能看到 mcp__plugin_ruflo-core_ruflo__neural_train、mcp__flow-nexus__neural_train 等变体）时字段名会相应变化。

三、文档定义的 Description 与四个改善维度

文档对 neural_train 的功能描述为：

Description: Improve coordination patterns through neural network training （通过神经网络训练改善协调模式）

并明确训练可以改进以下四个方面（Details 小节）：

任务拆解有效性（Task breakdown effectiveness）——面对复杂目标时能否被切分成更合理、可并行的子任务；
协调模式选择（Coordination pattern selection）——在多智能体协作中能否挑选更合适的协作拓扑/协调策略；
资源分配策略（Resource allocation strategies）——Agent、token、工具调用等资源在任务链路上的分配是否更优；
整体协调效率（Overall coordination efficiency）——上述三项综合作用后整个工作流吞吐与质量的提升。

在 ruflo 的多智能体编排场景中，这套"经验-沉淀-复用"的闭环同样体现在 Agent 定义文档里。例如 .claude/agents/swarm/adaptive-coordinator.md 中出现了把 swarm 性能历史作为训练素材的调用写法（mcp__claude-flow__neural_train coordination --training_data="swarm_performance_history" --epochs=50），说明协调器类 Agent 正是这类"协调模式训练"的目标用户。

四、Example Usage：一次完整的训练-查询闭环

文档的 Example Usage 给出四步标准操作，前两步针对不同的 pattern_type 做专项训练：

第 1 步：训练协调模式（coordination patterns）

调用 mcp__claude-flow__neural_train，参数为 {"pattern_type": "coordination", "training_data": "successful task patterns", "epochs": 50}——把"成功的任务执行路径"沉淀为协调模式，50 轮。

第 2 步：训练优化模式（optimization patterns）

调用 mcp__claude-flow__neural_train，参数为 {"pattern_type": "optimization", "training_data": "performance metrics", "epochs": 30}——把性能指标作为训练素材，训练优化类模式。

第 3 步：检查训练状态

调用 mcp__claude-flow__neural_status，不带参数即可查看当前神经系统的整体状态。

第 4 步：分析已沉淀的模式

调用 mcp__claude-flow__neural_patterns，参数为 {"action": "analyze"}。

对照仓库源码，neural_status 与 neural_patterns 返回的真实信息远比文档示例丰富。neural_status 的实现（neural-tools.ts 第 1042 行起）会返回：

models：模型总数、ready 数、training 数、平均 accuracy；
patterns：模式总数、按类型（byType）的分布、embedding 维度（默认 384）；
features：HNSW、量化、flash-attention（探测 @claude-flow/neural 的真实加载结果而非硬编码）、ReasoningBank 等能力开关；
embeddingProvider：当前实际生效的向量服务（@claude-flow/embeddings (ruvector@0.2.27 ...) 或 hash-based (deterministic)）。

而 neural_patterns 在 neural-tools.ts 第 631 行起的 action 枚举为 list / get / store / search / delete。其中与文档中 analyze 意图最接近的是 search：它支持 query、limit（默认 10、上限 100）、mode（hybrid 默认 / cosine 兼容模式）等参数，返回带 similarity、cosineScore、bm25Score、mmrScore（可选 crossEncoderScore）的打分结果，供上层做模式诊断与复用决策。因此在实际接入当前源码的 MCP 服务时，可将文档中的"analyze"理解为"对模式库执行语义检索与分析"。

五、训练的底层语义：源码级拆解

文档是一份面向用户的命令指南，而其背后的真实实现集中在 v3/@claude-flow/cli/src/mcp-tools/neural-tools.ts。该文件自述为 HYBRID Implementation（V2 兼容层），核心语义可归纳如下：

1. 存储位置与数据模型

模式库默认落盘于项目根目录下的 .claude-flow/neural/models.json（MODELS_FILE 常量，见 neural-tools.ts 第 212-214 行及 loadNeuralStore/saveNeuralStore）。数据结构包含：

{
  "models":  { "<modelId>": { "id", "name", "type", "status", "accuracy", "trainedAt", "epochs", "config" } },
  "patterns": { "<patternId>": { "id", "name", "type", "embedding", "content", "metadata", "createdAt", "usageCount" } },
  "version": "3.0.0"
}

值得注意：文件头注释明确 .claude-flow/neural/patterns.json 是 ReasoningBank（见内存模块 v3/@claude-flow/cli/src/memory/intelligence.ts）独立持有的另一份数据，本工具只读写 models.json，二者互不覆盖。

2. "训练"的真实语义：经验文本 → 可检索向量模式

neural_train 的 handler（第 413-528 行）流程是：创建一个 status 为 training 的模型记录 → 对训练数据中每条文本生成 embedding → 以语义化标签（优先取 label/category/class/tag/intent/name/title 等字段，其次取 text/input/task/description/content，避免把原始 JSON 当名字——这是 ADR-093 F11 的修复）写入模式库 → 将模型状态置为 ready，并诚实上报 accuracy = patternsStored > 0 ? 1.0 : 0（注释明言 "accuracy = data stored, not simulated"，即不模拟虚假的精度指标）。

3. Embedding 提供链：真模型优先，绝不静默造假

generateEmbedding（第 358-395 行）采用懒加载的多级嵌入提供链（ensureEmbeddings，第 96-207 行）：可选 WASM embedder（环境变量 RUFLO_EMBED_WASM_PKG 开启、fail-closed）→ ruvector@0.2.27 内置 ONNX 版 all-MiniLM-L6-v2 → agentic-flow ReasoningBank → @claude-flow/embeddings 的 agentic-flow / ONNX provider → 最后的兜底是确定性 hash 向量（注释明确说明其无语义含义，只用于一致性去重，不适合相似度检索）。一旦落入 hash 兜底，返回结果会附带 platformNote 提醒用户安装真实嵌入依赖以启用语义检索——这是"工具诚实性"在实现层面的体现，相关设计背景可参考 v3/implementation/adrs/ADR-073-stub-tool-honesty-real-predictions.md。

4. 配套工具：预测、检索、压缩、优化

同一个 neuralTools 数组内还注册了 neural_predict、neural_compress、neural_optimize：

neural_predict（第 530 行起）：对输入做 embedding，与存量模式做 k-NN + cosine，再经温度 tau=0.1 的 softmax 输出和为 1 的置信度分布（真实分类头，而非把裸 cosine 当置信度）；
neural_compress（第 927 行起）：支持 quantize（Int8 量化，约 3.92x）、prune（按 usageCount 低于阈值剪枝）、distill（cosine > 0.95 的模式做 embedding 平均合并）；
neural_optimize（第 1112 行起）：按目标 speed / memory / accuracy / balanced 组合执行去重、量化和零信号模式清理。

neural_patterns search 则默认走 ADR-078 以来的 hybrid 检索（cosine + 多字段 BM25 + MMR 多样化，默认 alpha=0.5、mmrLambda=0.7、subject/body 权重 2.0/1.0），可选 rerank 启用 cross-encoder 二次排序，且支持从 .claude-flow/harness-active-policy.json（ADR-176/177 champion 机制）读取已证明有效的默认配置。

六、边界提示与最佳实践（Important Reminders 的工程化解读）

文档的 Important Reminders 在实践中应落实为三条工程纪律：

让执行归于执行者：让 Claude Code 完成代码编写、文件访问与命令执行，神经工具只在其完成任务后负责模式训练与状态上报，避免工具职责混乱；
信任但要核验：训练/预测/状态类工具应当像 neural_status 那样如实暴露 embeddingProvider 与能力探测结果；上层 Agent 拿到 _realEmbedding: false 或 hash-fallback 提示时，应认识到当前只有一致性去重能力而无语义检索能力；
失败要诚实：neural_predict 在没有任何模式时不会空手返回成功，而是明确提示 "No patterns stored. Train with neural_train(modelType, trainingData) before predicting."，杜绝了"空库还报预测成功"的误导。

同主题的另一份命令文档 .claude/commands/training/neural-patterns.md 还给出了补充的 CLI 调用形式（如 npx claude-flow neural train --type coordination --epochs 50、npx claude-flow neural status、npx claude-flow neural patterns --analyze）以及认知模式分类（convergent / divergent / lateral / systems / critical / abstract），可作为命令文档族的上游参考；仓库根 CLAUDE.md 的命令总表（约第 395 行）也将 neural 列为拥有 5 个子命令（train、status、patterns、predict、optimize）的高级命令组。

七、进阶：从命令层到生产级神经算法（@claude-flow/neural）

如果只需要"沉淀并复用协作模式"，neural_train 系列 V2 兼容工具已足够；若要完整的轨迹学习与自适应，CLAUDE.md 的包清单（约第 1403 行）指向 @claude-flow/neural（版本 3.0.0-alpha，描述为 "Neural pattern training (SONA, MoE, EWC++)"）。其模块文档 v3/@claude-flow/neural/README.md 显示这是 Self-Optimizing Neural Architecture（SONA） 学习模块：记录 Agent 执行轨迹（trajectory）→ 蒸馏为可复用模式 → 新任务到来时检索复用 → 通过 SONA + LoRA + EWC++ 持续自适应。高层入口是 createNeuralLearningSystem(mode)，内部组合了 SONAManager、ReasoningBank、PatternLearner；底层还暴露 getMoERouter()（跨 8 个专家路由）与学习模式选择（real-time / balanced / research / edge / batch）。模块注释的职责划分是："package 拥有算法，CLI 拥有编排（the package owns the algorithms, the CLI owns the orchestration）"——这与本文主角（位于 .claude/commands/memory/ 的命令指南）恰好形成"编排层用法"与"算法层实现"的上下对应。plugin 侧还有一份带 frontmatter 的命令变体 plugins/ruflo-intelligence/commands/neural.md，按 train / status / patterns / predict / optimize / compress 六个子命令分发，并在 train 后要求上报 loss 曲线摘要，可视为本命令在生产插件形态下的演进。