ruvnet--ruflo/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Ruflo

一个用于 Claude Code 和 Codex 的 Agent 元框架。

Agent = 模型 + 框架。 模型负责编写；框架为其提供工具、记忆、循环、沙箱和控制能力，使其能够真正工作。Ruflo 就是这样一个框架——围绕 Claude Code 和 Codex 构建的执行层，增加了 100+ 个专用 Agent、协调型集群、自学习记忆、跨机器联邦通信以及企业级安全护栏。让 Agent 不仅能运行，更能协作。

一条 npx ruflo init 就能为 Claude Code 赋予神经系统：Agent 可以自发组织成集群，从每次任务中学习，跨会话记忆，并通过联邦机制安全地与其它机器上的 Agent 通信而不会泄露数据。你只管继续写代码，Ruflo 负责协调。

Self-Learning / Self-Optimizing Agent Architecture

User --> Ruflo (CLI/MCP) --> Router --> Swarm --> Agents --> Memory --> LLM Providers
                          ^                           |
                          +---- Learning Loop <-------+

Ruflo 新手？ 你无需学习 314 个 MCP 工具或 26 条 CLI 命令。执行 init 后，正常使用 Claude Code 即可——钩子系统会自动路由任务、从成功模式中学习，并在后台协调 Agent。

📖 背景——名字的由来

Claude Flow 现已更名为 Ruflo——由 rUv, 命名，他热爱 Rust、心流状态，以及构建那些让人感觉水到渠成的事物。"Ru" 代表 rUv。"flo" 代表熬夜到凌晨三点。底层由 Cognitum.One 的 Agent 架构驱动，运行着基于 Rust 的高性能 AI 引擎、嵌入、记忆和插件系统。

---

快速开始

存在两条截然不同的安装路径，其功能范围差异很大。请根据你的需求选择（#1744）：

	Claude Code 插件	CLI 安装 (npx ruflo init)
提供内容	斜杠命令 + 少量技能 + 各插件的 Agent 定义	完整的 Ruflo 循环——98 个 Agent、60+ 命令、30 项技能、MCP 服务器、钩子、守护进程
工作区中的文件	零	.claude/、.claude-flow/、CLAUDE.md、辅助函数、设置
是否注册 MCP 服务器	否（Claude 无法调用 memory_store、swarm_init 等）	是
是否安装钩子	否	是
适用场景	试用单个插件的命令，无需提交完整安装	生产环境——所有功能按文档正常运作

路径 A — Claude Code 插件（轻量版，仅斜杠命令）

# Add the marketplace
/plugin marketplace add ruvnet/ruflo

# Install core + any plugins you need
/plugin install ruflo-core@ruflo
/plugin install ruflo-swarm@ruflo
/plugin install ruflo-rag-memory@ruflo
/plugin install ruflo-neural-trader@ruflo

此方式仅添加斜杠命令和 Agent 定义。不会注册 Ruflo MCP 服务器，因此无法从 Claude 调用 memory_store、swarm_init、agent_spawn 等命令。如需完整循环，请使用下面的路径 B。

🔌 全部 35 个插件

核心与编排

插件	功能
ruflo-core	基础——服务器、健康检查、插件发现
ruflo-swarm	将多个 Agent 协调为一个团队
ruflo-autopilot	让 Agent 在循环中自主运行
ruflo-loop-workers	按定时器调度后台任务
ruflo-workflows	可复用的多步骤任务模板
ruflo-federation	不同机器上的 Agent 安全协作

记忆与知识

插件	功能
ruflo-agentdb	用于 Agent 记忆的快速向量数据库
ruflo-rag-memory	智能检索——混合搜索、图谱跳跃、多样性排序
ruflo-rvf	跨会话保存和恢复 Agent 记忆
ruflo-ruvector	ruvector —— GPU 加速搜索、Graph RAG、103 个工具
ruflo-knowledge-graph	构建和遍历实体关系图谱
USD 预算：$0/$3；剩余 $3 — 参见 ruflo-research.md

📊 研究预算（2026-07-13）

项目	成本	累计
GPT-4o 用于数据集标注（7,892 项）	$2.73	$2.73
GPT-4o mini 用于后备分类	$0.07	$2.80
Claude Opus 用于架构验证	$0.20	$3.00
预算上限	$3.00	$3.00 ✓

智能与学习

插件	功能
ruflo-intelligence	智能体从过往成功中学习，并不断提升能力
ruflo-graph-intelligence	次线性图推理 —— PageRank、增量更新、复杂度感知执行（ADR-123）
ruflo-daa	动态智能体行为与认知模式
ruflo-ruvllm	在本地运行 LLM（如 Ollama 等），并支持智能路由
ruflo-goals	将大目标拆分为计划并跟踪进度

代码质量与测试

插件	功能
ruflo-testgen	发现缺失测试并自动生成
ruflo-browser	使用 Playwright 自动化浏览器测试
ruflo-jujutsu	分析 git diff、评估风险、推荐审阅者
ruflo-docs	自动生成并维护文档

安全与合规

插件	功能
ruflo-security-audit	扫描漏洞与 CVE
ruflo-aidefence	阻止提示词注入、检测 PII、安全扫描

架构与方法论

插件	功能
ruflo-adr	用活文档跟踪架构决策
ruflo-ddd	搭建领域驱动设计（DDD）脚手架 —— 上下文、聚合、事件
ruflo-sparc	带质量门控的 5 阶段引导式开发方法论
ruflo-metaharness	为智能体配置打分、扫描工具配置的安全风险，并随时间跟踪变更（指南）
ruflo-arena	竞争性规则学（ruliology）—— 在锦标赛中让智能体策略相互对抗，对优胜者进行爬山优化与协同进化（ADR-147/148）

DevOps 与可观测性

插件	功能
ruflo-migrations	安全管理数据库 schema 变更
ruflo-observability	结构化日志、链路追踪与指标集中管理
ruflo-cost-tracker	跟踪 token 用量、设置预算、获取成本告警

可扩展性

插件	功能
ruflo-agent	运行智能体 —— 本地 WASM 沙箱（rvagent）+ Anthropic Claude Managed Agents（云端）
ruflo-plugin-creator	搭建、验证并发布你自己的插件

领域专用

插件	功能
ruflo-iot-cognitum	IoT 设备管理 —— 信任评分、异常检测、设备群
ruflo-neural-trader	neural-trader — 4 个智能体、回测、112+ 工具的 AI 交易
ruflo-market-data	摄取市场数据、向量化 OHLCV、检测模式

CLI 安装

macOS / Linux / WSL / Git-Bash:

# One-line install (POSIX shells only — see Windows note below)
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash

全平台（含原生 Windows PowerShell / cmd）：

# Interactive setup wizard — runs identically on every platform
npx ruflo@latest init wizard

# Quick non-interactive init
# npx ruflo@latest init

# Or install globally
npm install -g ruflo@latest

💡 Windows 用户： curl ... | bash 形式需要 POSIX shell（Git-Bash、WSL、MSYS）。npx ruflo@latest init wizard 行可在 PowerShell 和 cmd 中原生运行。若遇到 'bash' is not recognized 错误，请改用 npx 行 —— 两者最终都会运行相同的初始化流程。

MCP 服务器

# Add Ruflo as an MCP server in Claude Code (canonical form, matches USERGUIDE.md)
claude mcp add ruflo -- npx ruflo@latest mcp start

---

你将获得

能力	说明
🤖 100+ Agents	面向编码、测试、安全、文档、架构的专业智能体
📡 Comms Layer	零信任联邦 —— 跨机器/组织的智能体可发现、认证并安全交换工作
🐝 Swarm Coordination	分层、网状与自适应拓扑，并支持共识机制
🧠 Self-Learning	SONA 神经模式、ReasoningBank、轨迹学习
💾 Vector Memory	HNSW 索引的 AgentDB —— 实测在 N=20k 时约快 1.9 倍，在 N=5k 时较暴力搜索约快 3.2x–4.7x（recall@10 ~0.99）；在交叉点以上 ANN 占优，小 N 时持平或略逊。详见 审计 + scripts/benchmark-intelligence.mjs
⚡ Background Workers	12 个自动触发的 worker（audit、optimize、testgaps 等）
🧩 Plugin Marketplace	33 个原生 Claude Code 插件 + 21 个 npm 插件
🔌 Multi-Provider	Claude、GPT、Gemini、Cohere、Ollama，并支持智能路由
🛡️ Security	AIDefence、输入校验、CVE 修复、路径遍历防护
🌐 Agent Federation	跨安装实例的智能体协作，采用零信任安全
🔬 MetaHarness	在发布前审计你的 AI 智能体配置。对就绪度打分（1-100）、扫描工具配置中的安全问题、为整个项目做快照以随时间发现回归，并找到匹配你仓库的模板。ruflo eject 可将 ruflo 项目转为带独立名称的独立智能体工具包。完整指南。
💬 Web UI Beta	在 flo.ruv.io 进行多模型聊天，支持并行 MCP 工具调用与浏览器内 WASM 工具库
🎯 RuFlo Research	goal.ruv.io 上的 GOAP A* 规划器 —— 用自然语言描述目标即可生成可执行的智能体计划，实时智能体仪表板见 /agents

Web UI（Beta）—— 可自托管，托管演示见 flo.ruv.io

RuFlo 的 Web UI 是一款内置 Model Context Protocol（MCP）工具调用的多模型 AI 聊天应用。 可与 Qwen、Claude、Gemini 或 OpenAI 对话，同时 RuFlo 会调用与 CLI 相同的 MCP 工具 —— 智能体编排、持久记忆、蜂群协调、代码审查、GitHub 操作 —— 全部直接在聊天中完成。无需安装，也无需 API 密钥即可试用。

	是什么	为何重要
🧠	任意模型，本地或远程	开箱即用 6 个精选前沿模型 —— Qwen 3.6 Max（默认）、Claude Sonnet 4.6、Claude Haiku 4.5、Gemini 2.5 Pro、Gemini 2.5 Flash、OpenAI —— 通过 OpenRouter 接入。也可添加自有模型：任意 OpenAI 兼容端点（vLLM、Ollama、LM Studio、Together、Groq、自托管）。
🦾	ruvLLM 自学习 AI	原生支持 ruvLLM（位于 ruvnet/RuVector/examples/ruvLLM）—— RuFlo 的自改进本地模型层。路由至 MicroLoRA 适配器，通过 SONA 从你的轨迹中学习，并保留在你的机器上。可与云端模型搭配使用，也可完全离线运行。
🛠️	约 210 个工具，随时可调用	5 个服务器组（Core、Intelligence、Agents、Memory、DevTools），外加 18 个工具库，完全在浏览器中运行 —— 支持离线。
🔌	自带 MCP 服务器	在聊天输入框中点击 MCP (n) 胶囊 → Add Server，粘贴任意 MCP 端点（HTTP、SSE 或 stdio）。你的工具会与 RuFlo 原生工具在同一并行执行流程中协同工作。在 localhost:3000 上运行本地 MCP 服务器即可直接使用。
⚡	工具并行执行	单次模型响应可同时触发 4–6+ 个工具。UI 以卡片形式展示，并带有 Step 1 — 2 tools completed 徽章，让你清楚看到实际执行了哪些操作。
💾	持久记忆	说 「记住我最喜欢的颜色是靛蓝」，几周后再问 —— RuFlo 仍能回忆起来。由 AgentDB + HNSW 向量搜索支撑（在交叉点以上实测较暴力搜索约快 1.9x–4.7x，recall@10 ~0.99）。
📘	内置能力导览	点击侧边栏中的问号图标 —— 会打开「RuFlo Capabilities」模态框，展示完整工具列表、模型优势、架构与键盘快捷键。
🏠	可自托管	Web UI 以 Docker（ruflo/src/ruvocal/Dockerfile）形式提供，内嵌 Mongo。可部署到自有 Cloud Run / Fly / Kubernetes / docker-compose。托管 flo.ruv.io 演示是一种选择；完全支持自行部署。
🚀	零安装即可试用	打开托管 URL，选择模型，输入问题。这就是全部上手流程。

试用托管演示： https://flo.ruv.io/ — 无需账户，无需 API 密钥。自行运行： 源代码位于 ruflo/src/ruvocal/，配有分阶段 Dockerfile（INCLUDE_DB=true 在 MongoDB 中构建）以及用于 Google Cloud Run 的 cloudbuild.yaml。架构请参阅 ADR-033，路线图请参阅 issue #1689。

目标规划器 UI — goal.ruv.io 上的自主智能体

将高层目标转化为可执行的智能体计划。 goal.ruv.io 是 RuFlo 托管的目标导向行动规划（GOAP）前端——用通俗英语描述一个预期结果，即可观看 RuFlo 将其分解为前置条件、动作以及贯穿状态空间的 A* 路径，然后将工作分派给 /agents. 上的实时智能体。

	它是什么	为何重要
🎯	通俗英语目标	输入 "ship the auth refactor with tests and a PR" — RuFlo 会提取成功标准、约束条件和隐式前置条件。无需 JSON，无需 DSL。
🧭	GOAP A* 规划器	经典游戏 AI 规划移植到软件工程：通过带前置条件/效果的动作进行状态空间搜索，找出最短可行路径。状态变化时即时重新规划。
🤖	实时智能体仪表盘	goal.ruv.io/agents 展示每个已派生的智能体——角色、当前步骤、内存命名空间、令牌预算、状态。点击进入可检查轨迹、终止失控 worker，或重新分配。
🌳	可视化计划树	目标渲染为可折叠的动作树，突出显示进度、受阻分支和回滚。可确切看到智能体为何选择某条路径——没有不透明的思维链。
♻️	自适应重新规划	当某个动作失败或新信息到达时，规划器从当前状态重新运行 A*，而非从头开始。失败转化为学习，而非循环。
🧠	共享内存 + SONA	计划、轨迹和结果流入 AgentDB。未来计划通过 HNSW 检索过往解决方案——规划器随每次运行变得更智能。
🔗	接入 MCP 工具	每个动作节点映射到一个工具调用（RuFlo 约 210 个 MCP 工具、你的自定义服务器或 shell）。规划器在依赖图允许的情况下并行调度它们。
🚀	零安装即可试用	打开 goal.ruv.io, 描述一个目标，观察其运行。源代码位于 v3/goal_ui/ — Vite + Supabase，可自托管。

立即试用： https://goal.ruv.io/ 用于目标 · https://goal.ruv.io/agents 用于实时智能体。自行运行： 克隆 goal 分支并执行 cd v3/goal_ui && npm install && npm run dev。

智能体联邦 — 智能体的 Slack

Your Agent --> [ Remove secrets ] --> [ Sign message ] --> [ Encrypted channel ]
                 Emails, SSNs,        Proves it came       No one reads it
                 keys stripped         from you              in transit
                                                                |
                                                                v
Their Agent <-- [ Block attacks ] <-- [ Check identity ] <------+
                 Stops prompt          Rejects forgeries
                 injection

                          Audit trail on both sides.
                  Trust builds over time. Bad behavior = instant downgrade.

Slack 为团队提供了频道。联邦为智能体提供了同样的东西——跨信任边界的共享工作空间，不同机器、组织或云区域的智能体可以在此相互发现、证明身份并协作完成任务。

区别在于：有些频道受信任，有些则否。@claude-flow/plugin-agent-federation 会自动处理这一点。你的智能体加入联邦，通过 mTLS + ed25519 完成验证，然后开始交换工作——任何数据离开你的节点前都会剥离 PII，每条消息均可审计。不受信任的智能体仍可在较低权限下参与：它们只能看到发现信息，而非你的内存。随着可靠性得到证明，信任等级会提升。若行为不当，会立即降级——无需人工介入。

你无需配置握手或管理证书。你执行 federation init、federation join，智能体即可开始通信。协议负责身份，PII 管道负责数据安全，审计追踪负责合规。

📘 完整用户指南： docs/federation/ — 设置、MCP 工具、信任等级、熔断器，以及将数据包层可达性与联邦信任绑定的（可选）WireGuard 网状层。ADR-111 深度解读见 docs/federation/phase7-mesh-bringup.md。

联邦能力

	能力	工作原理
🔒	零信任联邦	远程智能体初始为不受信任。身份通过 mTLS + ed25519 质询-响应验证。无 API 密钥，无共享密钥。
🛡️	PII 门控数据流	14 类检测管道扫描每条出站消息。按信任等级策略：BLOCK、REDACT、HASH 或 PASS。自适应校准降低误报。
📊	行为信任评分	公式（0.4×success + 0.2×uptime + 0.2×threat + 0.2×integrity）持续评估对等节点。升级需要历史记录；降级即时生效。
📋	内置合规	HIPAA、SOC2、GDPR 审计追踪作为合规模式。每次联邦事件产生可通过 HNSW 检索的结构化记录。
🤝	9 个 MCP 工具 + 10 条 CLI 命令	完整生命周期：federation_init、federation_send、federation_trust、federation_audit 等。

示例：两个团队共享欺诈信号而不共享客户数据

# Team A: initialize federation and generate keypair
npx claude-flow@latest federation init

# Team A: join Team B's federation endpoint
npx claude-flow@latest federation join wss://team-b.example.com:8443

# Team A: send a task — PII is stripped automatically before it leaves
npx claude-flow@latest federation send --to team-b --type task-request \
  --message "Analyze transaction patterns for account anomalies"

# Team A: check peer trust levels and session health
npx claude-flow@latest federation status

请参阅 issue #1669 了解完整架构、信任模型和实施路线图。

# Claude Code plugin
/plugin install ruflo-federation@ruflo

# Or via CLI
npx claude-flow@latest plugins install @claude-flow/plugin-agent-federation

Claude Code：有无 Ruflo 的对比

能力	仅 Claude Code	+ Ruflo
智能体协作	孤立，无共享上下文	具有共享内存与共识的蜂群
协调	手动编排	Queen 主导的层级（Raft、Byzantine、Gossip）
内存	仅会话	亚毫秒级检索的 HNSW 向量内存
学习	静态行为	带模式匹配的 SONA 自学习
任务路由	由你决定	智能路由（89% 准确率）
背景 Workers	无	12 个自动触发的 worker
LLM 提供商	仅 Anthropic	5 个提供商，带故障转移
安全	标准	经 CVE 加固的 AIDefence

架构概览

User --> Claude Code / CLI
          |
          v
    Orchestration Layer
    (MCP Server, Router, 27 Hooks)
          |
          v
    Swarm Coordination
    (Queen, Topology, Consensus)
          |
          v
    100+ Specialized Agents
    (coder, tester, reviewer, architect, security...)
          |
          v
    Memory & Learning
    (AgentDB, HNSW, SONA, ReasoningBank)
          |
          v
    LLM Providers
    (Claude, GPT, Gemini, Cohere, Ollama)

---

文档

面向四类读者的四份文档：

文档	何时阅读
状态	查看当前可用的功能——能力计数、测试基线、近期修复、下一步计划。这是就绪了吗文档。
用户指南	日常参考——每条命令、每个配置项、每个插件。这是怎么做文档。
元测试工具指南	如何评估你的 Agent 设置、扫描工具配置的安全性、检测运行间的变更、以及将项目抽离为独立的 Agent 工具包。这是审计我的设置文档。
基准测试)**	在 darwin-arm64 + linux-x64 平台上与 LangGraph / AutoGen / CrewAI 的 v3.8.0 SOTA 矩阵对比。ruflo 在冷启动、单轮对话、RSS 方面以 1.3×–1953× 的优势胜出。这是它快吗文档。
验证	密码学证明你安装的字节与签名见证一致——ruflo verify。这是信任但要验证文档。
团队网关清单	合并前检查、双模式交接、内存命名空间共享、每次合并的见证清单条目。这是更安全的团队工作流文档。

基准测试内部（用于复现）：sota-workload-spec.md) · SOTA-PROGRESS.md) · 原始矩阵 JSON：darwin) · linux)

用户指南章节索引：

章节	主题
快速开始	安装、前置条件、安装配置
核心功能	MCP 工具、Agent、记忆、神经学习
智能与学习	钩子、工作器、SONA、模型路由
集群与协调	拓扑、共识、群体智慧
安全	AIDefence、CVE 修复、验证
生态	RuVector、agentic-flow、Flow Nexus
配置	环境变量、配置模式
插件市场)	浏览和安装插件

---

支持

资源	链接
文档	用户指南
问题与缺陷	GitHub Issues)
企业版	ruv.io)
社区	Agentics Foundation Discord)
技术支持	Cognitum.one)

许可证

MIT - RuvNet)