ruflo 项目 SONA Learning Optimizer 深度解析：基于 LoRA 微调与 EWC++ 的 Agent 自学习优化实战指南

SONA（Self-Optimizing Neural Architecture，自优化神经架构）是 ruflo 生态中驱动 Agent 持续学习的核心机制，而 .claude/agents/sona/sona-learning-optimizer.md 正是定义了「SONA Learning Optimizer」这一自优化 Agent 角色的权威说明文档。本指南以该文档为骨架，结合仓库内 hooks 脚本、ruvector 插件与 Agent 定义等源码实现，讲清 SONA Learning Optimizer 的能力边界、性能特征、任务前后端 hooks 接入方式与底层支撑模块，帮助读者在自己的 Claude Code / ruflo 工程中部署可长期自进化的 Agent 学习回路。

一、先理解文档性质：一份 Agent 定义即技术规格

在 ruflo 仓库中，sona-learning-optimizer.md 是一份 Claude Agent 定义文件，存放于 .claude/agents/sona/sona-learning-optimizer.md。它的 YAML frontmatter 给出了该角色的元信息：

---
name: sona-learning-optimizer
description: SONA-powered self-optimizing agent with LoRA fine-tuning and EWC++ memory preservation
---

• name：sona-learning-optimizer，即该 Agent 在工程中的可引用标识；
• description：概括职责——「由 SONA 驱动、具备 LoRA 微调与 EWC++ 记忆保持能力的自优化 Agent」。description 同时是路由依据，当某个任务涉及"自优化 / 持续学习 / 模式优化"时，该 Agent 会被优先选中。

值得注意的是，该文件并非仅存在于根目录：在 v3/@claude-flow/cli/.claude/agents/sona/sona-learning-optimizer.md 与 v3/@claude-flow/mcp/.claude/agents/sona/sona-learning-optimizer.md 中还有两份同步副本，说明它随 v3 运行时（CLI 与 MCP 两个入口）一并分发部署。

因此，读懂这份文档，实际上就是读懂 ruflo 中「Agent 如何把每一次任务执行转化为自身能力提升」这一整套设计的对外契约。

二、SONA Learning Optimizer 概览与四大核心能力

文档将本 Agent 定义为自优化智能体：它从每一次任务执行中持续学习，综合运用 LoRA 微调、EWC++ 持续学习与基于模式（pattern）的优化，实现质量随使用次数提升。其核心能力分为四块：

1. 自适应学习（Adaptive Learning）

• 从每次任务执行中学习；
• 随时间推移提升输出质量（文档声明最高可提升 +55%）；
• 借助 EWC++（弹性权重巩固的增强变体）避免灾难性遗忘（catastrophic forgetting）——即学习新知识时不会破坏已学会的旧策略。

2. 模式发现（Pattern Discovery）

• 检索 k=3 个相似历史模式（文档声明吞吐约 761 decisions/sec）；
• 将已学会的策略迁移应用于新任务；
• 在运行中持续积累模式库，使可用经验单调增长。

3. LoRA 微调（LoRA Fine-Tuning）

• 相对全参数微调实现 99% 参数缩减；
• 训练速度提升 10~100 倍；
• 内存占用极小，因此可以做到亚毫秒级的学习开销。

4. LLM 路由（LLM Routing）

• 自动选择模型，文档声明可带来约 60% 成本节省；
• 质量感知（quality-aware）路由：根据任务难度与历史成功率动态分配模型，避免为简单任务调用昂贵模型。

在仓库的源码与配置层面，这四项能力并非孤立的宣传口号，而是落在 plugins/ruflo-ruvector/README.md 描述的 ruvector@0.2.25 SONA 命令面与 .claude/helpers/learning-optimizer.sh 的实际调度逻辑上，后文第 4、5 节会逐一展开对应实现。

三、性能特征与质量提升数据（含数据来源说明）

文档给出了 SONA Learning Optimizer 的量化基准，并声明这些数据来源于 vibecast test-ruvector-sona 测试集。

吞吐与延迟

指标	数值	语义
吞吐量（目标）	2211 ops/sec	SONA 学习/路由目标吞吐
单向量延迟（Micro-LoRA）	0.447 ms	每个向量执行 Micro-LoRA 适配的开销
总开销（40 层）	18.07 ms	跨 40 层网络累计的微调开销

各领域质量提升幅度

领域	质量提升
Code（代码）	+5.0%
Creative（创意）	+4.3%
Reasoning（推理）	+3.6%
Chat（对话）	+2.1%
Math（数学）	+1.2%

需要说明的是，以上数字为 Agent 定义文档中自报的基准结论；当前仓库快照内并未包含 vibecase 基准脚本或可复现的原始数据，因此在引用时应将其视为项目声明的目标特征，而非仓库内可独立验证的测量结果。与之互为参照、可在仓库内直接运行的，是 docs/benchmarks/runs/self-learning-*.json 等真实训练/自学习运行记录（例如 docs/benchmarks/runs/self-learning-latest.json），可作为该学习回路在真实工程任务上的补充观测证据。

四、任务前后端 hooks：把 SONA 学习闭环接入日常任务

SONA Learning Optimizer 的学习入口被设计为 pre-task / post-task 两个 hook：任务开始前初始化轨迹（trajectory），任务结束后记录结果并触发学习。文档给出的原始命令为：

# Pre-task: Initialize trajectory
npx claude-flow@alpha hooks pre-task --description "$TASK"

# Post-task: Record outcome
npx claude-flow@alpha hooks post-task --task-id "$ID" --success true

在仓库的命令文档中，这两个 hook 有更完整的面（注意当前仓库命令文档中的形态为 hook 单数子命令）：

pre-task：任务前准备

参考 .claude/commands/hooks/pre-task.md，它负责任务前的上下文装载，常用参数包括：

参数	说明
--description, -d <text>	任务描述，用于建立本次轨迹上下文
--auto-spawn-agents	是否按需自动生成 Agent（默认 true）
--load-memory	加载过往会话的相关记忆
--optimize-topology	选择最优 swarm 拓扑
--estimate-complexity	预估任务复杂度（从而决定学习资源分配）

典型组合用法：

npx claude-flow hook pre-task -d "Refactor codebase" --optimize-topology --estimate-complexity
npx claude-flow hook pre-task -d "Continue API development" --load-memory
npx claude-flow hook pre-task -d "Debug issue #123" --auto-spawn-agents false

该 hook 会返回 JSON，其中 topology、agentsSpawned、complexity 等字段会一并进入轨迹，作为本次任务"如何被路由与编排"的学习样本。

post-task：任务后结果回收

参考 .claude/commands/hooks/post-task.md，它负责任务收尾与学习信号写回：

参数	说明
--task-id, -t <id>	任务唯一标识（文档示例中的 --task-id "$ID"）
--analyze-performance	是否生成性能指标（默认 true）
--store-decisions	将任务决策写入记忆
--export-learnings	导出神经模式学习成果
--generate-report	生成任务完成报告

组合用法：

npx claude-flow hook post-task -t "api-refactor" --analyze-performance --generate-report
npx claude-flow hook post-task -t "bug-fix-123" --store-decisions --export-learnings
npx claude-flow hook post-task -t "minor-update" --analyze-performance false

从学习回路的角度，post-task 会度量执行时长、追踪 token 用量、识别瓶颈，并将"成功模式"导出回写，使 SONA 能在下一次 pre-task 检索 k=3 相似模式时命中本次经验。ruvector 的 Agent 侧文档 plugins/ruflo-ruvector/agents/vector-engineer.md 中还给出了带显式神经训练开关的等价形态：

npx @claude-flow/cli@latest hooks post-task --task-id "TASK_ID" --success true --train-neural true

五、Learning Optimizer Worker：SONA 微调落地的调度脚本

sona-learning-optimizer.md 描述的是"能力契约"，而真正周期性执行 SONA micro-LoRA 优化的是一个 bash worker：.claude/helpers/learning-optimizer.sh（文件头注释即写明 "RuFlo V3 - Learning Optimizer Worker / Runs SONA micro-LoRA optimization on patterns"）。它把 SONA 的概念映射为工程实体：

数据与目录布局

脚本假设存在以下工程内状态目录：

• patterns.db：位于 .claude-flow/learning/，SQLite 库，核心表为 short_term_patterns 与 long_term_patterns，每行记录一个策略模式及其 domain 与 quality；
• learning.json：位于 .claude-flow/metrics/，优化后写出的结构化指标；
• LAST_RUN_FILE：节流标记，避免过度频繁运行。

支持的命令

bash .claude/helpers/learning-optimizer.sh check     # 节流检查后按需优化（默认）
bash .claude/helpers/learning-optimizer.sh run       # 立即执行模式优化
bash .claude/helpers/learning-optimizer.sh force     # 清空节流标记后强制优化
bash .claude/helpers/learning-optimizer.sh sona      # 触发 SONA 深度训练（委托 agentic-flow）
bash .claude/helpers/learning-optimizer.sh status    # 查看当前学习指标

优化逻辑与 SONA 语义的对应

脚本中的 optimize_patterns() 具体实现了三类操作：

1. 质量助推：对 quality > 0.5 的短期模式执行 quality = MIN(1.0, quality * 1.05)，即成功经验的置信度缓步上调（对应 SONA 的"随执行次数提升质量"）；
2. 跨域杂交：将 quality > 0.8 的模式以 0.8 系数降权复制为 domain='general' 的 cross-pollinated 条目（对应"把策略迁移到新任务"）；
3. 指标汇总：统计短/长期模式数量、平均质量、路由准确率，并合成 0–100 的智能分数（intelligence score），按 <25 learning / <50 developing / <75 proficient / 其余 expert 划分等级。

优化结束后写入 learning.json，其中直接包含 sona 字段：

"sona": {
  "adaptationTime": "0.05ms",
  "microLoraEnabled": true
}

worker 默认以 30 分钟为节流窗口（见脚本中 [ $((now - last_run)) -ge 1800 ]），并通过 npx agentic-flow@alpha hooks intelligence 触发 SONA 深度训练（对应 sona 子命令）。status 子命令可用 jq 一行输出当前状态：

jq -r '"Intel: \(.intelligence.score)% (\(.intelligence.level)) | Patterns: \(.patterns.shortTerm)/\(.patterns.longTerm) | Routing: \(.routing.accuracy)%"' .claude-flow/metrics/learning.json

六、ruvector / SONA 命令行：模式检索、训练与诊断

sona-learning-optimizer.md 的 References 指向包 @ruvector/sona@0.1.1。在仓库当前实际锁定的版本中，SONA 能力由 ruvector@0.2.25 提供（Rust 后端 + JS 层），且 sona 子命令依赖可选加装包 @ruvector/ruvllm——这是阅读文档时需要特别留意的版本前提（详见 plugins/ruflo-ruvector/README.md 的 Known Caveats）。

基础安装与健康检查

npm install ruvector@0.2.25                    # 必备
npm install ruvector-onnx-embeddings-wasm      # embed text 所需
npm install @ruvector/pi-brain                 # brain 子命令所需
npm install @ruvector/ruvllm                   # sona 子命令所需（JS 回退）
npx -y ruvector@0.2.25 doctor

SONA 三件套

npx -y ruvector@0.2.25 sona status             # SONA 当前学习状态
npx -y ruvector@0.2.25 sona patterns "auth refactor"   # 检索相似模式（对应当前文档 k=3 检索）
npx -y ruvector@0.2.25 sona stats              # 学习统计

在 /vector 插件命令面下，等价工具更丰富（见 plugins/ruflo-ruvector/README.md 的 Quick reference）：vector sona status|info|stats|patterns|train|export。而 SONA 需要喂入的"轨迹/模式"数据，由同插件的 self-learning hooks 生产：

# 9 阶段预训练 + Agent 生成（AST 分析、diff 嵌入、覆盖率路由、神经训练、图分析、
# 安全扫描、协同编辑模式学习、Agent 构建、RAG 上下文索引）
npx -y ruvector@0.2.25 hooks init --pretrain --build-agents quality

# 轨迹生命周期：begin / step / end（与 pre-task/post-task 语义对齐）
npx -y ruvector@0.2.25 hooks trajectory-begin
npx -y ruvector@0.2.25 hooks trajectory-step
npx -y ruvector@0.2.25 hooks trajectory-end

# 记忆与建议
npx -y ruvector@0.2.25 hooks remember|recall <query>
npx -y ruvector@0.2.25 hooks error-record|error-suggest

通过 MCP 注册后（claude mcp add ruvector -- npx -y ruvector@0.2.25 mcp start），上述能力以 sona_status、sona_patterns、sona_stats 等工具形态暴露，可与 plugins/ruflo-ruvector/agents/vector-engineer.md 中登记的 91 个 MCP 工具协同，把"模式训练 → 语义检索 → 新任务应用"串成一个完整的自学习回路。

七、记忆保持与持续学习：EWC++ 与 AgentDB 持久化

SONA 文档将"无灾难性遗忘（EWC++）"列为自适应学习的核心承诺。仓库中与之一致的设计是「短期模式表 + 长期模式表」双层记忆结构：learning-optimizer.sh 同时统计 short_term_patterns 与 long_term_patterns，短期表承载正在验证的新经验，长期表承载已固化的稳定策略——这正是"弹性权重巩固"思想的表级映射：新知识先落在短期层，只有质量达标才晋升长期层，从而在吸收新模式时保护既有高价值策略。

跨会话/跨项目的经验持久化则由 AgentDB 承担。在 plugins/ruflo-ruvector/agents/vector-engineer.md 的 Memory Persistence 一节给出了向量配置与搜索模式入库的标准写法：

npx @claude-flow/cli@latest memory store --namespace vector-patterns \
  --key "hnsw-config-DOMAIN" --value "M=16,efC=200,efS=50"
npx @claude-flow/cli@latest memory search --query "HNSW configuration" --namespace vector-patterns

由此，SONA 的经验不仅在单次任务后通过 hooks 写回，还能跨项目通过 namespace 检索复用——这是"持续学习"在 ruflo 工程中真正落地的一环。

八、在工程中接入 SONA Learning Optimizer：操作路径汇总

方式一：作为 Agent 定义随工程分发

sona-learning-optimizer.md 位于标准 .claude/agents/ 目录（以及 v3 CLI/MCP 的两份副本），Claude Code 会在会话启动时自动装载同名 Agent。适合把它用作描述文件，让上层协调 Agent（如 swarm/hive-mind 中的 Queen）在遇到需要自优化的子任务时分派给 sona-learning-optimizer。

方式二：通过 ruvector 插件提供运行时能力

以插件方式挂载：

claude --plugin-dir plugins/ruflo-ruvector

随后由 plugins/ruflo-ruvector/agents/vector-engineer.md（model: sonnet）负责实际执行 SONA 相关子命令，实现"Agent 定义负责意图，vector-engineer 负责执行"的分工。

方式三：以 worker 方式常驻自学习

将 .claude/helpers/learning-optimizer.sh 接入工程的定时/钩子体系（例如会话结束或 CI 任务完成时执行 check），以 30 分钟节流频率自动完成模式助推、跨域杂交与智能分数量化，实现文档所述"从每次任务执行中学习"的自动化版本。

九、阅读与使用本文档的注意事项

1. 数据口径：+55% 质量提升、761 decisions/sec、99% 参数缩减、60% 成本节省 等均为 Agent 定义文档自报特征，仓库内缺少可独立复现的基准脚本；引用时应注明出处与口径。
2. 版本约束：文档 References 中的 @ruvector/sona@0.1.1 早于仓库当前锁定的 ruvector@0.2.25，后者明确提示「0.1.x 缺少 brain/route/sona 等多个命令」，使用时务必以当前 pin 的版本为准（参见 plugins/ruflo-ruvector/README.md 的版本说明）。
3. 可选依赖：sona、brain、embed text 分属不同可选加装包（@ruvector/ruvllm、@ruvector/pi-brain、ruvector-onnx-embeddings-wasm），未安装时对应子命令不可用；执行 npx -y ruvector@0.2.25 doctor 可快速诊断。
4. 命令形态差异：部分早前文档记载的 hooks route --task X、embed --file F 等形态在当前版本为位置参数式 hooks route "X"、embed text，迁移时以 .claude/commands/hooks/pre-task.md、.claude/commands/hooks/post-task.md 及 vector-engineer 的替换对照表为准。

十、延伸阅读

• Agent 原始定义：sona-learning-optimizer.md
• 学习调度实现：learning-optimizer.sh
• 任务生命周期 hooks 文档：pre-task.md、post-task.md、hooks 总览
• ruvector 插件与 SONA 命令面：ruflo-ruvector/README.md、vector-engineer.md
• 自学习运行观测记录：docs/benchmarks/runs/self-learning-latest.json（及同目录 self-learning-*.json 系列）
• SONA 模式学习的相邻集成插件：ruflo-intelligence/README.md、ruflo-ruvllm/README.md

需要特别提示：SONA Learning Optimizer 的价值不在于某一项指标的绝对值，而在于它把「每次任务 → 轨迹记录 → 模式检索 → 质量回写 → 跨域迁移」的闭环真正产品化。把 .claude/agents/sona/sona-learning-optimizer.md 视作能力契约、把 learning-optimizer.sh 与 ruvector 插件视作运行时实现来配套阅读，是理解并复用这套自学习机制最直接的方式。