ruflo AgentDB Learning 技能实战：用 9 种强化学习算法构建自学习智能体插件

本文围绕 ruflo 仓库中的 Agent 技能文档 .agents/skills/agentdb-learning/SKILL.md 展开，讲解如何通过 AgentDB 插件系统创建、训练并部署强化学习插件。读完本文，你可以独立完成从 CLI 创建学习插件、以 insertPattern 写入经验轨迹、到调用 adapter.train 训练模型的完整闭环，并理解 ruflo v3 神经网络层中各 RL 算法的真实源码实现（Decision Transformer、Q-Learning、SARSA、PPO、DQN、A2C、Curiosity 等），为构建"越用越聪明"的自主智能体打下基础。

一、技能定位：AgentDB 学习插件是什么

该技能面向自学习智能体场景：通过 AgentDB 的插件系统提供 9 种强化学习（Reinforcement Learning）算法，覆盖三大技术路线：

• 离线强化学习：Decision Transformer（序列建模，从历史数据直接学习策略，无需在线交互）；
• 基于价值函数学习：Q-Learning、SARSA（表格型，适合离散动作空间）；
• 策略梯度类：Actor-Critic（带价值基线，适合连续动作与降方差场景）。

此外还包含探索式（curiosity-driven）、主动学习、对抗训练、课程学习、联邦学习、多任务学习等进阶路线。技能文档给出的性能声明是：借助 WASM 加速的神经推理，模型训练可快 10–100 倍（此为文档声明，具体提速取决于运行环境与后端运行时）。

前置条件（来自原文档）：

依赖	版本要求	说明
Node.js	18+	运行时基线
AgentDB	v1.0.7+	通过 agentic-flow 提供
RL 基础知识	建议具备	理解状态-动作-奖励三元组、折扣因子等概念

技能元数据（SKILL.md 的 frontmatter）将其归类为 Machine Learning / Reinforcement Learning，难度定位为 Intermediate to Advanced，预计上手时间 30–60 分钟。

二、CLI 快速上手：创建与管理学习插件

2.1 创建插件

# 交互式向导
npx agentdb@latest create-plugin

# 使用指定模板
npx agentdb@latest create-plugin -t decision-transformer -n my-agent

# 只预览、不落盘
npx agentdb@latest create-plugin -t q-learning --dry-run

# 自定义输出目录
npx agentdb@latest create-plugin -t actor-critic -o ./plugins

参数说明：-t 指定算法模板，-n 指定插件名，--dry-run 仅预览生成内容，-o 指定输出目录（原文档写作 .$plugins，即当前目录下的 plugins 目录）。

2.2 查看可用模板

npx agentdb@latest list-templates

文档列出的 5 个可用模板及其定位：

模板名	类型	定位
decision-transformer	序列建模 RL（推荐）	离线学习，从日志经验中学习
q-learning	基于价值函数	离散动作空间，样本高效
sarsa	同策略 TD 学习	安全探索、风险敏感任务
actor-critic	带基线的策略梯度	连续动作、多智能体
curiosity-driven	基于探索	用内在奖励驱动探索

2.3 插件管理

# 列出已安装插件
npx agentdb@latest list-plugins

# 查看插件详情：算法、配置、训练状态
npx agentdb@latest plugin-info my-agent

三、API 快速上手：从写入经验到触发训练

技能文档给出的核心编程入口是从 agentic-flow/reasoningbank 导入 createAgentDBAdapter。完整流程如下：

import { createAgentDBAdapter } from 'agentic-flow/reasoningbank';

// 初始化时开启学习能力
const adapter = await createAgentDBAdapter({
  dbPath: '.agentdb$learning.db',
  enableLearning: true,       // 启用学习插件
  enableReasoning: true,      // 同时启用推理检索
  cacheSize: 1000,
});

// 1) 写入一条训练经验
await adapter.insertPattern({
  id: '',
  type: 'experience',
  domain: 'game-playing',
  pattern_data: JSON.stringify({
    embedding: await computeEmbedding('state-action-reward'),
    pattern: {
      state: [0.1, 0.2, 0.3],
      action: 2,
      reward: 1.0,
      next_state: [0.15, 0.25, 0.35],
      done: false
    }
  }),
  confidence: 0.9,
  usage_count: 1,
  success_count: 1,
  created_at: Date.now(),
  last_used: Date.now(),
});

// 2) 训练学习模型
const metrics = await adapter.train({
  epochs: 50,
  batchSize: 32,
});

console.log('Training Loss:', metrics.loss);
console.log('Duration:', metrics.duration, 'ms');

关键字段解读：

• pattern_data 是 JSON 字符串，内部结构为 { embedding, pattern: { state, action, reward, next_state, done } }——这就是标准 RL 转移元组（s, a, r, s'）加终止标志；
• confidence 同时承担"经验优先级"的语义（后文优先经验回放会复用该字段）；
• domain 是检索分区键，训练与推理阶段必须保持一致；
• 训练返回指标至少包含 loss、valLoss、duration（毫秒）、epochs 四个字段（见后文训练工作流的示例注释）。

仓库中对 createAgentDBAdapter 的实际集成记录可参考 AGENTIC-FLOW-INTEGRATION-ANALYSIS.md——该文档的"Skills Analysis"一节明确列出 ruflo 中 7 个 AgentDB 系技能（含 agentdb-learning）都以 createAgentDBAdapter 为核心 API 构建，并规划了向 EnhancedAgentDBWrapper / AgentDBFast 的迁移路径。

四、9 种学习算法详解与配置参数

原文档共列出 9 种算法。前 4 种给出了完整的创建命令与 JSON 配置模板，后 5 种给出了类型与适用场景。

4.1 Decision Transformer（推荐）

• 类型：离线强化学习（Offline RL）
• 适用：从已记录的日志经验中学习、模仿学习
• 优势：无需在线交互，训练稳定
• 典型用例：学习历史数据、从专家示范模仿、无环境交互的安全学习、序列建模任务

npx agentdb@latest create-plugin -t decision-transformer -n dt-agent

{
  "algorithm": "decision-transformer",
  "model_size": "base",
  "context_length": 20,
  "embed_dim": 128,
  "n_heads": 8,
  "n_layers": 6
}

参数含义：context_length 为回溯的轨迹步数窗口，embed_dim / n_heads / n_layers 对应 Transformer 的嵌入维度、注意力头数与层数，model_size 为预设规模档位。

4.2 Q-Learning

• 类型：基于价值函数（Value-Based，Off-Policy）
• 适用：离散动作空间、样本效率敏感场景
• 优势：成熟、简单，中小规模问题效果好
• 典型用例：网格世界、棋盘游戏、导航任务、资源分配、离散决策

npx agentdb@latest create-plugin -t q-learning -n q-agent

{
  "algorithm": "q-learning",
  "learning_rate": 0.001,
  "gamma": 0.99,
  "epsilon": 0.1,
  "epsilon_decay": 0.995
}

参数含义：gamma（折扣因子）控制远期奖励的折现程度，epsilon 是 ε-greedy 探索概率，epsilon_decay 为每步衰减系数（0.995 表示探索率缓慢退火）。

4.3 SARSA

• 类型：基于价值函数（On-Policy）
• 适用：安全探索、风险敏感任务
• 优势：比 Q-Learning 更保守（更新使用实际执行的下一动作），更适合安全性要求高的场景
• 典型用例：安全关键应用、风险敏感决策、带探索的在线学习

npx agentdb@latest create-plugin -t sarsa -n sarsa-agent

{
  "algorithm": "sarsa",
  "learning_rate": 0.001,
  "gamma": 0.99,
  "epsilon": 0.1
}

4.4 Actor-Critic

• 类型：带价值基线的策略梯度（Policy Gradient with Value Baseline）
• 适用：连续动作空间、需要方差缩减
• 优势：训练稳定，连续/离散动作均可
• 典型用例：连续控制（机器人、仿真）、复杂动作空间、多智能体协同

npx agentdb@latest create-plugin -t actor-critic -n ac-agent

{
  "algorithm": "actor-critic",
  "actor_lr": 0.001,
  "critic_lr": 0.002,
  "gamma": 0.99,
  "entropy_coef": 0.01
}

参数含义：策略网络（actor）与价值网络（critic）可分别设置学习率，entropy_coef 是策略熵的正则项，鼓励探索、防止策略过早坍缩。

4.5 其余 5 种算法

算法	类型	最佳场景	核心优势
Active Learning（主动学习）	基于查询的学习	标注高效、人在环	最小化标注成本，聚焦不确定样本
Adversarial Training（对抗训练）	鲁棒性增强	安全、抗扰动	提升模型对对抗扰动的防御能力
Curriculum Learning（课程学习）	渐进难度训练	复杂任务、更快收敛	在难任务上稳定且收敛更快
Federated Learning（联邦学习）	分布式学习	隐私、数据分散	隐私保护、可扩展
Multi-Task Learning（多任务学习）	迁移学习	相关任务族、知识共享	新任务学得更快、泛化更好

对应典型用例分别覆盖：人类反馈整合 / 标注成本控制、安全测试与对抗防御、多阶段复杂任务 / 技能组合 / 迁移学习、多智能体系统 / 隐私敏感数据 / 协同训练、任务族 / 域适应 / 元学习等（均见 SKILL.md 原文）。

五、源码纵深：RL 算法工厂与配置类型

技能文档中的模板名并非凭空而来。ruflo v3 的神经网络包 @claude-flow/neural 中实现了真实的算法工厂：createAlgorithm 按名称分发到 7 个具体实现：

export function createAlgorithm(algorithm: RLAlgorithm, config?: Partial<RLConfig>): unknown {
  switch (algorithm) {
    case 'ppo':                  return createPPO(...);
    case 'dqn':                  return createDQN(...);
    case 'a2c':                  return createA2C(...);
    case 'decision-transformer': return createDecisionTransformer(...);
    case 'q-learning':           return createQLearning(...);
    case 'sarsa':                return createSARSA(...);
    case 'curiosity':            return createCuriosity(...);
    default: throw new Error(`Unknown algorithm: ${algorithm}`);
  }
}

也就是说，从源码结构看，AgentDB 学习插件的"9 算法"叙事落在两套互补的实现上：CLI 插件模板覆盖文档列出的 9 种路线（含 5 种可直接建插件的模板），而 v3 neural 包则把其中的 PPO、DQN、A2C（即 Actor-Critic）、Decision Transformer、Q-Learning、SARSA、Curiosity 7 种落成了可单测的 TypeScript 类（见 v3/@claude-flow/neural/src/algorithms/，含 ppo.ts、dqn.ts、a2c.ts、decision-transformer.ts、q-learning.ts、sarsa.ts、curiosity.ts）。

技能文档中的配置字段与源码类型定义可以一一对应。types.ts 中定义了统一的 RLConfig 基类与算法专属配置：

export type RLAlgorithm =
  | 'ppo' | 'dqn' | 'a2c'
  | 'decision-transformer' | 'q-learning' | 'sarsa' | 'curiosity';

export interface RLConfig {
  algorithm: RLAlgorithm;
  learningRate: number;    // 学习率
  gamma: number;           // 折扣因子
  entropyCoef: number;     // 熵系数
  valueLossCoef: number;   // 价值损失系数
  maxGradNorm: number;     // 梯度裁剪
  epochs: number;
  miniBatchSize: number;
}

// Decision Transformer 专属字段
export interface DecisionTransformerConfig extends RLConfig {
  contextLength: number;   // 对应文档 context_length
  numHeads: number;        // 对应文档 n_heads
  numLayers: number;       // 对应文档 n_layers
  hiddenDim: number;
  embeddingDim: number;    // 对应文档 embed_dim
  dropout: number;
}

可以看到文档 JSON 配置里的 context_length / embed_dim / n_heads / n_layers 正是 DecisionTransformerConfig 的 CLI 命名风格映射。各算法还带有专属参数，例如 PPOConfig 的 clipRange / targetKL / gaeLambda，DQNConfig 的 bufferSize / targetUpdateFreq / doubleDQN，CuriosityConfig 的 intrinsicCoef / useRND（随机网络蒸馏）等。

行为正确性由测试用例守护：algorithms.test.ts 对全部 7 个算法工厂逐一验证"创建即可用"。此外仓库中还存在面向路由决策的 Q-Learning 应用示例 q-learning-router.ts，说明这些算法不仅用于智能体训练，也被复用于模型路由等内部决策场景。

六、训练工作流：经验收集 → 训练 → 评估

6.1 第一步：收集经验

在智能体执行过程中，把每一步转移元组写入 AgentDB：

// 存储智能体执行期间的经验
for (let i = 0; i < numEpisodes; i++) {
  const episode = runEpisode();

  for (const step of episode.steps) {
    await adapter.insertPattern({
      id: '',
      type: 'experience',
      domain: 'task-domain',
      pattern_data: JSON.stringify({
        embedding: await computeEmbedding(JSON.stringify(step)),
        pattern: {
          state: step.state,
          action: step.action,
          reward: step.reward,
          next_state: step.next_state,
          done: step.done
        }
      }),
      confidence: step.reward > 0 ? 0.9 : 0.5,   // 正奖励经验更高置信度
      usage_count: 1,
      success_count: step.reward > 0 ? 1 : 0,
      created_at: Date.now(),
      last_used: Date.now(),
    });
  }
}

6.2 第二步：训练模型

const trainingMetrics = await adapter.train({
  epochs: 100,
  batchSize: 64,
  learningRate: 0.001,
  validationSplit: 0.2,   // 20% 验证集
});

console.log('Training Metrics:', trainingMetrics);
// {
//   loss: 0.023,
//   valLoss: 0.028,
//   duration: 1523,
//   epochs: 100
// }

6.3 第三步：评估表现

训练完成后，用 retrieveWithReasoning 做"状态查询 → 相似经验召回 → 动作建议"的评估回路：

const testQuery = await computeEmbedding(JSON.stringify(testState));
const result = await adapter.retrieveWithReasoning(testQuery, {
  domain: 'task-domain',
  k: 10,
  synthesizeContext: true,   // 合成上下文
});

// 评估动作质量：取最相似经验中的动作与相似度作为置信度
const suggestedAction = result.memories[0].pattern.action;
const confidence = result.memories[0].similarity;

console.log('Suggested Action:', suggestedAction);
console.log('Confidence:', confidence);

这个"检索相似成功经验作为动作建议"的模式，正是 AgentDB 将记忆库（ReasoningBank）与 RL 训练打通的关键：经验既是训练数据，也是推理时的参考依据。

七、进阶训练技巧

7.1 经验回放（Experience Replay）

// 经验存入缓冲池
const replayBuffer = [];

// 随机采样一个训练 batch
const batch = sampleRandomBatch(replayBuffer, { batchSize: 32 });

// 用 batch 做一步训练
await adapter.train({
  data: batch,
  epochs: 1,
  batchSize: 32,
});

7.2 优先经验回放（Prioritized Experience Replay）

利用 confidence 字段承载 TD 误差，实现"误差大的经验优先训练"：

// 写入时以 TD 误差作为优先级
await adapter.insertPattern({
  // ... 标准字段
  confidence: tdError,   // 用 TD 误差作为 confidence/priority
  // ...
});

// 检索高优先级经验
const highPriority = await adapter.retrieveWithReasoning(queryEmbedding, {
  domain: 'task-domain',
  k: 32,
  minConfidence: 0.7,   // 只取高 TD 误差的经验
});

7.3 多智能体训练

按智能体分域存储经验，再训练一个共享模型：

// 收集多个智能体的经验
for (const agent of agents) {
  const experience = await agent.step();

  await adapter.insertPattern({
    // ... 存储经验，携带智能体 ID
    domain: `multi-agent/${agent.id}`,
  });
}

// 训练共享模型
await adapter.train({
  epochs: 50,
  batchSize: 64,
});

八、性能优化

8.1 批量训练

// 收集一批经验（批量插入比逐条快约 500 倍）
const experiences = collectBatch(1000);

for (const exp of experiences) {
  await adapter.insertPattern({ /* ... */ });
}

// 更大的 batch 提升训练效率
await adapter.train({
  epochs: 10,
  batchSize: 128,
});

8.2 增量学习

新经验累积到阈值后触发小步训练，避免长周期阻塞：

setInterval(async () => {
  const newExperiences = getNewExperiences();

  if (newExperiences.length > 100) {
    await adapter.train({
      epochs: 5,
      batchSize: 32,
    });
  }
}, 60000);  // 每分钟检查一次

九、与推理智能体集成

学习与推理结合的推荐做法：训练产出策略，推理时用 MMR 保证召回经验的多样性、用 optimizeMemory 做模式合并：

// 先训练学习模型
await adapter.train({ epochs: 50, batchSize: 32 });

// 再用推理智能体做决策
const result = await adapter.retrieveWithReasoning(queryEmbedding, {
  domain: 'decision-making',
  k: 10,
  useMMR: true,           // 多样化经验
  synthesizeContext: true, // 富上下文合成
  optimizeMemory: true,    // 模式合并
});

// 基于"学到的经验 + 推理"做决策
const decision = result.context.suggestedAction;
const confidence = result.memories[0].similarity;

在 ruflo 的整体架构中，这条"经验 → 轨迹 → 模式"链路正是 SONA 学习体系的核心：Trajectory / Pattern 类型定义 中 TrajectoryStep 同样要求 stateBefore / stateAfter / reward 字段，与 AgentDB 经验的 { state, action, reward, next_state } 结构同构；而 NeuralStats 中的 config.algorithm 直接引用 RLAlgorithm 类型，说明学习模式与 RL 算法选择在同一配置面内可切换。

十、CLI 操作速查与故障排查

10.1 CLI 速查

# 创建插件
npx agentdb@latest create-plugin -t decision-transformer -n my-plugin

# 列出插件
npx agentdb@latest list-plugins

# 插件信息
npx agentdb@latest plugin-info my-plugin

# 列出模板
npx agentdb@latest list-templates

另外技能文档提到可用 npx agentdb@latest mcp 启动 MCP 集成，把 AgentDB 能力暴露给 MCP 客户端。

10.2 常见问题

训练不收敛：降低学习率。

await adapter.train({
  epochs: 100,
  batchSize: 32,
  learningRate: 0.0001,  // 更小的学习率
});

过拟合：使用验证集切分，并开启记忆优化（模式合并可减少过拟合）。

await adapter.train({
  epochs: 50,
  batchSize: 64,
  validationSplit: 0.2,  // 20% 验证
});

await adapter.retrieveWithReasoning(queryEmbedding, {
  optimizeMemory: true,  // 合并模式、降低过拟合
});

训练/推理慢：启用量化。文档建议用二值量化（binary quantization）将推理速度提升约 32 倍。

十一、延伸阅读与仓库导航

资源	路径	说明
技能文档（本文主体）	.agents/skills/agentdb-learning/SKILL.md	9 算法 + CLI/API 全流程
同系列技能	.agents/skills/agentdb-advanced/SKILL.md、.agents/skills/agentdb-memory-patterns/SKILL.md、.agents/skills/agentdb-optimization/SKILL.md、.agents/skills/agentdb-vector-search/SKILL.md	进阶、记忆模式、优化、向量检索
RL 算法工厂	v3/@claude-flow/neural/src/algorithms/index.ts	createAlgorithm / getDefaultConfig
算法类型与默认配置	v3/@claude-flow/neural/src/types.ts	RLConfig、各算法专属配置
算法行为测试	v3/@claude-flow/neural/tests/algorithms.test.ts	7 算法工厂回归验证
集成分析	v3/implementation/architecture/AGENTIC-FLOW-INTEGRATION-ANALYSIS.md	createAgentDBAdapter 在 ruflo 中的集成点与 v2 迁移规划

适用前提与限制：本文的 CLI 命令面向 AgentDB 官方 CLI（npx agentdb@latest），需 Node.js 18+ 与 AgentDB v1.0.7+ 环境；API 示例依赖 agentic-flow 包的 reasoningbank 导出，具体可用方法以你所安装版本的运行时导出为准。文中"10–100x 训练加速""批量插入 500x""二值量化 32x"等数字均为技能文档中的声明值，实际收益随硬件、后端运行时（NAPI/WASM/JS）与数据规模而异，建议以本地基准测试为准。