ruflo 中的 backend-dev 技能：构建带自学习能力的后端 API 开发 Agent

ruflo 的 .agents/skills/ 目录下存放着大量可直接被 Codex / Claude Code 类 CLI 调用的 Agent 技能文件，其中 agent-dev-backend-api 技能 定义了名为 backend-dev 的后端 API 开发专用 Agent：它不仅声明了触发条件、工具白名单、路径沙箱和行为约束，还把"自学习"落到了可执行的 hook 脚本与 ReasoningBank 模式存取 API 上。读完本篇，你可以完整看懂这个技能的 YAML 配置骨架、复现它的"先检索历史模式、再实现、最后回存奖励"的闭环，并了解 ruflo 仓库中支撑该闭环的 ReasoningBank 向量存储实现。

技能文件的位置与调用方式

按照 .agents 目录说明，ruflo 的技能体系遵循如下约定：

• 每个技能是一个目录，内含 SKILL.md（技能指令主体）以及可选的 scripts/、docs/ 子目录；
• 技能通过 $skill-name 语法调用，config.toml 负责模型选择、审批策略、沙箱模式等全局控制；
• 项目根目录的 AGENTS.md 提供主指令，.codex/AGENTS.override.md 提供本地覆盖。

agent-dev-backend-api 技能文件的写法比较特殊：它包含两层 YAML frontmatter。外层是 Codex 技能包装层（name: agent-dev-backend-api，描述为 "Agent skill for dev-backend-api - invoke with $agent-dev-backend-api"），内层才是真正定义的 Agent 规格：

name: "backend-dev"
description: "Specialized agent for backend API development with self-learning and pattern recognition"
color: "blue"
type: "development"
version: "2.0.0-alpha"
created: "2025-07-25"
updated: "2025-07-25"
author: "Claude Code"
metadata:
  specialization: "API design, implementation, optimization, and continuous improvement"
  complexity: "moderate"
  autonomous: true
  v2_capabilities:
    - "self_learning"
    - "context_enhancement"
    - "fast_processing"
    - "smart_coordination"

v2_capabilities 中声明的 self_learning 等四项能力，正是后文自学习协议的能力声明：版本标记为 2.0.0-alpha，说明它是在 v1 静态 Agent 基础上叠加学习能力的新版本。

触发机制：关键词、文件模式与任务模式三重匹配

技能通过 triggers 字段声明何时应被路由到该 Agent：

triggers:
  keywords:
    - "api"
    - "endpoint"
    - "rest"
    - "graphql"
    - "backend"
    - "server"
  file_patterns:
    - "**$api/**/*.js"
    - "**$routes/**/*.js"
    - "**$controllers/**/*.js"
    - "*.resolver.js"
  task_patterns:
    - "create * endpoint"
    - "implement * api"
    - "add * route"
  domains:
    - "backend"
    - "api"

从结构上看，它把匹配拆成三个维度：关键词（任务描述中出现 api/endpoint 等词）、文件模式（正在编辑的 routes/、controllers/、*.resolver.js 文件）、任务模式（"create * endpoint" 之类的动词 + 名词组合），并归入 backend、api 两个领域。这种声明式设计让编排器（ruflo 的 swarm 路由逻辑）无需理解任务语义，仅靠规则即可把后端 API 任务分派给 backend-dev。

能力与沙箱：工具白名单、路径围栏与文件限制

capabilities 和 constraints 两组字段共同构成该 Agent 的执行边界：

capabilities:
  allowed_tools:
    - Read
    - Write
    - Edit
    - MultiEdit
    - Bash
    - Grep
    - Glob
    - Task
  restricted_tools:
    - WebSearch  # Focus on code, not web searches
  max_file_operations: 100
  max_execution_time: 600
  memory_access: "both"
constraints:
  allowed_paths:
    - "src/**"
    - "api/**"
    - "routes/**"
    - "controllers/**"
    - "models/**"
    - "middleware/**"
    - "tests/**"
  forbidden_paths:
    - "node_modules/**"
    - ".git/**"
    - "dist/**"
    - "build/**"
  max_file_size: 2097152  # 2MB
  allowed_file_types:
    - ".js"
    - ".ts"
    - ".json"
    - ".yaml"
    - ".yml"

要点解读：

• 工具白名单只保留文件读写、编辑、Bash 与检索类工具，显式限制 WebSearch（注释说明"聚焦代码而非网络搜索"），并给出两个硬上限：最多 100 次文件操作、最长 600 秒执行时间；
• 路径围栏用 allowed_paths + forbidden_paths 双重声明：只能动 src/、api/、routes/、controllers/、models/、middleware/、tests/，禁止触碰 node_modules/、.git/、dist/、build/；
• 文件类型白名单限定为 JS/TS/JSON/YAML，单文件上限 2MB（2097152 字节），防止大文件拖垮上下文；
• memory_access: "both" 表示同时可读可写 AgentDB 记忆库——这是自学习闭环能工作的前提。

行为约束与多 Agent 协作声明

behavior 段定义了出错与变更策略：

behavior:
  error_handling: "strict"
  confirmation_required:
    - "database migrations"
    - "breaking API changes"
    - "authentication changes"
  auto_rollback: true
  logging_level: "debug"

即：严格错误处理、对数据库迁移/破坏性 API 变更/认证变更三类操作强制人工确认、失败自动回滚、debug 级日志。communication 段则约定输出风格为技术向、批量更新、附带代码片段、禁用 emoji。

integration 段声明了它与同 swarm 中其他 Agent 的协作拓扑：

integration:
  can_spawn:
    - "test-unit"
    - "test-integration"
    - "docs-api"
  can_delegate_to:
    - "arch-database"
    - "analyze-security"
  requires_approval_from:
    - "architecture"
  shares_context_with:
    - "dev-backend-db"
    - "test-integration"

从源码结构看，这是一个典型的"开发 Agent"协作契约：backend-dev 可以自己派生测试与文档子任务（can_spawn），把数据库设计与安全分析委托出去（can_delegate_to），重大决策需 architecture Agent 批准，并与数据库后端 Agent、集成测试 Agent 共享上下文。optimization 段进一步给出 parallel_operations: true、batch_size: 20、cache_results: true、memory_limit: "512MB" 等并行与资源参数。

自学习协议：实现前先检索历史模式

技能正文（"Backend API Developer v2.0.0-alpha"）将自学习拆成四个阶段，第一个阶段是实现前从历史中学习：

// 1. 检索相似的历史 API 实现
const similarAPIs = await reasoningBank.searchPatterns({
  task: 'API implementation: ' + currentTask.description,
  k: 5,
  minReward: 0.85
});

if (similarAPIs.length > 0) {
  similarAPIs.forEach(pattern => {
    console.log(`- ${pattern.task}: ${pattern.reward} success rate`);
    console.log(`  Best practices: ${pattern.output}`);
    console.log(`  Critique: ${pattern.critique}`);
  });

  // 只从高奖励（>0.9）的实现中抽取最佳实践
  const bestPractices = similarAPIs
    .filter(p => p.reward > 0.9)
    .map(p => extractPatterns(p.output));
}

// 2. 主动检索过去的失败案例
const failures = await reasoningBank.searchPatterns({
  task: 'API implementation',
  onlyFailures: true,
  k: 3
});

这个协议的关键在于双向检索：minReward: 0.85 过滤出高成功率的可复用模式，onlyFailures: true 则单独捞出失败案例用于避坑。两次检索分别对应"学怎么做"和"学怎么不踩坑"。

检索增强：GNN 依赖图搜索与 Flash Attention

文档给出了两种针对 API 开发场景的检索加速手段。其一是 GNN 增强的上下文搜索——把当前任务的相关模块（Controller、Service、Database、Middleware）建模成带权依赖图，再交由向量库做图感知检索：

const graphContext = {
  nodes: [authController, userService, database, middleware],
  edges: [[0, 1], [1, 2], [0, 3]], // 依赖关系图
  edgeWeights: [0.9, 0.8, 0.7],
  nodeLabels: ['AuthController', 'UserService', 'Database', 'Middleware']
};

const relevantEndpoints = await agentDB.gnnEnhancedSearch(
  taskEmbedding,
  {
    k: 10,
    graphContext,
    gnnLayers: 3
  }
);

文档声称该方式可提升上下文准确性（文中给出 +12.4% 的说法，属于文档自身的声明，仓库中未提供对应的基准复现）。其二是大 Schema 的 Flash Attention 处理：当 API Schema 元素超过 1024 个时，切换到 flash attention 路径，文档称可获得 4-7 倍加速、约 50% 内存节省：

if (schemaSize > 1024) {
  const result = await agentDB.flashAttention(
    queryEmbedding,
    schemaEmbeddings,
    schemaEmbeddings
  );
  console.log(`Processed ${schemaSize} schema elements in ${result.executionTimeMs}ms`);
}

学习闭环：完成后回存模式并训练

实现完成后，Agent 需要把结果连同质量指标回存，形成下一轮可用的经验：

const codeQuality = calculateCodeQuality(generatedCode);
const testsPassed = await runTests();

await reasoningBank.storePattern({
  sessionId: `backend-dev-${Date.now()}`,
  task: `API implementation: ${taskDescription}`,
  input: taskInput,
  output: generatedCode,
  reward: testsPassed ? codeQuality : 0.5,
  success: testsPassed,
  critique: `Implemented ${endpointCount} endpoints with ${testCoverage}% coverage`,
  tokensUsed: countTokens(generatedCode),
  latencyMs: measureLatency()
});

注意 reward 的取值逻辑：测试通过时取代码质量分，失败时只给 0.5 的保底分并标记 success: false，critique 字段写入端点数量与测试覆盖率，供未来检索时快速判断价值。

在 ruflo 仓库中，这套 storePattern / searchPatterns 语义有真实的实现对应：ReasoningBank 模块 将模式以向量形式存入 AgentDB（memory.db），核心配置包括：

• 384 维 MiniLM-L6 嵌入（dimensions: 384）；
• 真实 HNSW 索引：hnswM: 16、hnswEfConstruction: 200、hnswEfSearch: 100；
• 短期记忆上限 1000 条、长期记忆上限 5000 条；
• 模式晋升机制：promotionThreshold: 3（被使用 3 次）、qualityThreshold: 0.6 时从短期晋升到长期记忆，dedupThreshold: 0.95 做去重。

也就是说，技能文档里"reward/success 回存"的每条模式，最终都会成为 HNSW 图上一个可检索的向量节点，并被使用频次与质量阈值驱动的晋升机制管理生命周期。

Hook 脚本：把学习闭环落到可执行的 CLI 调用

YAML 的 hooks 段把上述协议翻译成了 pre/post execution 的 shell 脚本，通过 claude-flow@alpha CLI 与记忆库交互。pre_execution 的核心逻辑：

# v2.0.0-alpha: 从过去的 API 实现中学习
echo "🧠 Learning from past API patterns..."
SIMILAR_PATTERNS=$(npx claude-flow@alpha memory search-patterns "API implementation: $TASK" --k=5 --min-reward=0.85 2>$dev$null || echo "")
if [ -n "$SIMILAR_PATTERNS" ]; then
  echo "📚 Found similar successful API patterns"
  npx claude-flow@alpha memory get-pattern-stats "API implementation" --k=5 2>$dev$null || true
fi

# 记录任务开始，供后续学习对照
npx claude-flow@alpha memory store-pattern \
  --session-id "backend-dev-$(date +%s)" \
  --task "API: $TASK" \
  --input "$TASK_CONTEXT" \
  --status "started" 2>$dev$null || true

post_execution 则完成了"评估 + 回存 + 条件训练"三步：

REWARD=$(if npm run test:api 2>$dev$null; then echo "0.95"; else echo "0.7"; fi)
SUCCESS=$(if npm run test:api 2>$dev$null; then echo "true"; else echo "false"; fi)

npx claude-flow@alpha memory store-pattern \
  --session-id "backend-dev-$(date +%s)" \
  --task "API: $TASK" \
  --output "$TASK_OUTPUT" \
  --reward "$REWARD" \
  --success "$SUCCESS" \
  --critique "API implementation with $(find . -name '*.route.js' -o -name '*.controller.js' | wc -l) endpoints" 2>$dev$null || true

# 成功时用产出训练神经模式
if [ "$SUCCESS" = "true" ]; then
  npx claude-flow@alpha neural train \
    --pattern-type "coordination" \
    --training-data "$TASK_OUTPUT" \
    --epochs 50 2>$dev$null || true
fi

设计上有两个值得注意的工程决策：

1. 奖励分级：测试通过记 0.95、失败记 0.7（而不是 0），配合 on_error 钩子中显式的 --reward "0.0"，形成 0.0 / 0.7 / 0.95 三档信号——错误中断、测试未跑、测试通过，语义各不相同；
2. 尽力而为（best-effort）容错：所有学习类 CLI 调用都带 || true 或 || echo ""，记忆系统故障不会阻塞 API 开发主流程，这与 behavior.auto_rollback 关注的是代码正确性、学习链路关注的是经验积累的职责分离一致。

on_error 钩子则把失败本身也变成训练数据：

echo "❌ Error in API development: {{error_message}}"
npx claude-flow@alpha memory store-pattern \
  --session-id "backend-dev-$(date +%s)" \
  --task "API: $TASK" \
  --output "Failed: {{error_message}}" \
  --reward "0.0" \
  --success "false" \
  --critique "Error: {{error_message}}" 2>$dev$null || true

{{error_message}} 是模板占位符，由 hook 运行时注入，失败模式随后即可被"实现前检索"阶段的 onlyFailures 查询命中——闭环至此完整。

领域优化：CRUD 模式沉淀与端点成功率跟踪

文档最后给出了两个"按领域蒸馏经验"的具体样例。其一，把一次成功的 CRUD 实现结构化入库：

await reasoningBank.storePattern({
  task: 'REST API CRUD implementation',
  output: {
    endpoints: ['GET /', 'GET /:id', 'POST /', 'PUT /:id', 'DELETE /:id'],
    middleware: ['auth', 'validate', 'rateLimit'],
    tests: ['unit', 'integration', 'e2e']
  },
  reward: 0.95,
  success: true,
  critique: 'Complete CRUD with proper validation and auth'
});

// 之后遇到类似任务，按高奖励阈值检索
const crudPatterns = await reasoningBank.searchPatterns({
  task: 'REST API CRUD',
  k: 3,
  minReward: 0.9
});

其二，按端点类型统计历史成功率与延迟，用历史表现指导方案选择：

const endpointStats = {
  'authentication': { successRate: 0.92, avgLatency: 145 },
  'crud': { successRate: 0.95, avgLatency: 89 },
  'graphql': { successRate: 0.88, avgLatency: 203 },
  'websocket': { successRate: 0.85, avgLatency: 67 }
};

const bestApproach = Object.entries(endpointStats)
  .sort((a, b) => b[1].successRate - a[1].successRate)[0];

这两段展示的是学习系统的"数据面"：模式（结构化方案）与统计（聚合指标）并存，检索时既能拿到具体可复用的实现，也能拿到按类别的成功率先验。

职责、最佳实践与示例交互

技能正文还固化了该 Agent 的行为契约。七项核心职责覆盖 REST/GraphQL 设计、认证授权、数据库查询与数据模型、API 文档、错误处理与日志，其中第 6、7 项是 v2 新增的"从历史 API 实现中学习"和"存储成功模式供未来复用"。最佳实践清单在传统条目（输入校验、HTTP 状态码、限流缓存、REST/GraphQL 约定、全端点测试、变更文档化）之外追加了三条学习类实践：编码前检索相似历史实现、用 GNN 搜索定位相关端点、带成功指标存储 API 模式。

架构模式层面，它要求遵循 Controller-Service-Repository 分层、中间件处理横切关注点、DTO 做数据校验、规范的错误响应格式，以及 v2 新增的 ReasoningBank 模式存取与 GNN 依赖图检索。

文档末尾给出两个示例交互，说明触发后的响应形态：

触发任务	Agent 响应
create user authentication endpoints	创建登录、登出、注册、token 刷新的完整认证端点
implement CRUD API for products	实现带校验、错误处理与文档的完整产品 CRUD API

在仓库中进一步阅读

围绕这一技能，ruflo 仓库内有几处值得对照的材料：

• .agents/skills/agent-dev-backend-api/SKILL.md：本文主体技能文件；
• .agents/README.md：.agents 目录结构与 $skill-name 调用约定；
• v3/@claude-flow/hooks/src/reasoningbank/index.ts：ReasoningBank 的向量存储实现（HNSW 参数、模式晋升、去重阈值）；
• v3/implementation/integration/HOOKS-LEARNING-INTEGRATION.md：Claude Code hook 事件与 agentic-flow 学习工具（intelligence_pattern_store / intelligence_pattern_search 等）的映射关系，是理解该技能 hook 段背后机制的延伸阅读。

小结

agent-dev-backend-api 技能是 ruflo "自学习 Agent"路线的一个完整样本：YAML 层用 triggers/capabilities/constraints/behavior/integration 声明路由与执行边界，正文层给出"检索—实现—回存—训练"四阶段学习协议的 TypeScript 参照实现，hook 层则用 claude-flow@alpha memory store-pattern / search-patterns 与 neural train 把它落成可执行的 shell 脚本。其核心价值不在某个单点算法，而在于把"经验的结构化存取（reward、success、critique）+ 图感知检索 + 失败案例回捞"组装进了后端 API 开发的每个生命周期节点，且整条学习链路以尽力而为的方式运行，故障不影响主任务。