ruvnet / ruflo

57,2916,532+366 todayTypeScript

🌊 The leading agent meta-harness for Claude. Deploy intelligent multi-agent swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning swarm intelligence, RAG integration, and native Claude Code / Codex Integration

💡 Use Cases

最适合需要大规模、跨信任边界的多AI代理协作场景，特别是企业级开发团队希望让Claude Code代理安全协同、记忆学习并自动编排复杂工作流

多智能体集群协作

Problem: 单个Claude Code代理能力有限，复杂任务需要多个专业代理协同完成，但手动管理调度成本高

Solution: Ruflo自动编排100+专业AI代理形成集群，代理自组织为群体，自动分配任务并协调工作流

Example: 开发一个电商平台时，一个代理负责前端代码生成，另一个处理后端API，第三个优化数据库查询，Ruflo自动协调它们的工作顺序和数据传递

跨团队安全数据共享

Problem: 不同团队或组织之间需要共享AI代理的分析结果，但担心敏感数据泄露

Solution: 零信任联邦通信机制自动脱敏PII数据，通过mTLS和加密通道安全交换信息，同时保留审计追踪

Example: 两个银行的反欺诈团队各自运行Ruflo代理集群，安全共享欺诈模式信号而不暴露具体客户数据

持久化记忆与学习

Problem: Claude Code每次会话都是独立的，无法记住之前的任务上下文和学习经验

Solution: Ruflo为代理提供自学习记忆系统，跨会话保持上下文，从每次任务中积累知识并优化后续行为

Example: 在持续数月的代码重构项目中，代理记住之前已重构的模块和采用的模式，避免重复工作并保持一致性

📊 Project Info

Language: TypeScript
Stars: ⭐ 57,291
Forks: 6,532
Today: +366
Ranking: #9
Collection: Language
Trending Date: June 1, 2026
Last Push: 6/1/2026

🏷️ Topics

agentic-aiagentic-frameworkagentic-ragagentic-workflowagentsai-agentsai-assistantai-codingai-skillsautonomous-agentsclaude-codecodexmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript

📸 Screenshots

Ruflo 5分钟快速开始

Ruflo 为 Claude Code 添加多智能体编排、自学习记忆和联邦通信能力。本指南帮助您在5分钟内完成安装并运行第一个智能体集群。

🖥️ OS

macOSLinux

⚙️ Runtime

Node.js>=18

npm>=8

🔧 Tools

Claude Code CLI— 运行智能体

📝 Steps

安装 Ruflo

使用一键安装脚本或 npx 安装 Ruflo。

一键安装（推荐）

$ curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash

或使用 npx 交互式安装

$ npx ruflo@latest init --wizard

✓Expected: 安装成功，显示 'Ruflo installed successfully' 或类似信息。

💡如果 curl 方式失败，请使用 npx 方式。

将 Ruflo 添加为 Claude Code 的 MCP 服务器

在 Claude Code 中注册 Ruflo 作为 MCP 服务器。

添加 Ruflo MCP 服务器

$ claude mcp add ruflo -- npx -y @claude-flow/cli@latest

✓Expected: MCP 服务器 'ruflo' 添加成功。

💡确保已安装 Claude Code CLI 并登录。

初始化 Ruflo 项目

在您的项目目录中初始化 Ruflo。

初始化 Ruflo 配置

$ cd your-project && ruflo init

✓Expected: 生成 ruflo.config.json 和默认智能体配置文件。

💡如果 ruflo 命令未找到，请确保安装路径在 PATH 中。

启动第一个智能体集群

运行一个示例智能体集群，验证 Ruflo 正常工作。

启动演示集群

$ ruflo swarm start --demo

✓Expected: 控制台显示智能体集群启动信息，包括智能体数量、状态等。

💡演示模式会启动 3 个模拟智能体。

✅ 验证成功

打开 Claude Code，输入 /ruflo status 查看集群状态。

✓显示 'Ruflo cluster is running'
✓智能体列表显示在线状态

⚡ Quick Tips

插件使用 /plugin install ruflo-swarm@ruflo 安装集群插件以获得更多功能。

配置查看 ruflo.config.json 调整智能体数量和行为。

联邦运行 ruflo federation init 设置联邦通信。

🔍 Troubleshooting

❓ 安装脚本执行失败

→ 尝试 npx ruflo@latest init --wizard 或 npm install -g ruflo@latest

❓ claude mcp add 命令失败

→ 确保 Claude Code CLI 已安装且版本最新，或手动添加 MCP 服务器配置

❓ ruflo 命令未找到

→ 检查是否全局安装成功，或使用 npx ruflo 代替

🎯 Next Steps

阅读完整文档

访问 https://flo.ruv.io/ 获取用户指南

探索插件市场

运行 /plugin marketplace 浏览可用插件

配置联邦通信

运行 ruflo federation init 开始跨机器协作

Difficulty

中级

Est. Time

3-5天

Target Audience

有一定TypeScript和AI代理基础知识的开发者，希望快速上手多智能体编排平台

🎯 What You'll Learn

学会安装、配置Ruflo，创建并协调超过100个AI代理，实现自主工作流和跨会话记忆，并掌握联邦通信和安全配置。

📋 Prerequisites

TypeScript基础熟悉

Ruflo使用TypeScript编写，需要理解基本语法、类型和模块系统。

Node.js环境了解

需要Node.js 18+来运行Ruflo和相关CLI工具。

AI代理概念了解(optional)

理解什么是AI代理、智能体协作和Claude Code的基本概念有助于快速上手。

Git基础了解

用于克隆项目和安装插件。

📚 Resources

必看

Ruflo用户指南

包含完整安装、配置、API参考和高级主题。

🗺️ Learning Phases

环境准备与安装

⏱ 1小时

检查系统要求

确保安装Node.js 18+和npm，并验证Git可用。

💡使用`node --version`和`npm --version`检查版本。

安装Ruflo核心

使用npx或npm全局安装：`npx ruflo@latest init --wizard` 或 `npm install -g ruflo@latest`。

💡推荐使用npx方式以避免全局污染。

安装必备插件

通过CLI安装核心插件：`/plugin install ruflo-core@ruflo`、`/plugin install ruflo-swarm@ruflo`等。

💡先安装ruflo-core，其他按需安装。

配置MCP服务器

运行`claude mcp add ruflo -- npx -y @claude-flow/cli@latest`将Ruflo添加为Claude Code的MCP服务器。

💡确保Claude Code已安装并登录。

快速入门：创建第一个代理集群

⏱ 2小时

运行初始化向导

执行`npx ruflo@latest init --wizard`，根据提示选择配置模板。

💡选择默认模板即可快速开始。

创建并注册代理

使用Ruflo的API或CLI创建一个简单代理，并添加到集群中。

💡参考官方文档中的`Quick Start`部分。

测试代理协作

编写一个简单任务，让两个代理协同完成（如一个负责数据收集，一个负责分析）。

💡使用`ruflo task run`命令触发任务。

查看记忆系统

运行任务后，检查代理的记忆存储，验证跨会话学习能力。

💡使用`ruflo memory list`查看记忆内容。

核心功能实战

⏱ 3小时

配置自学习记忆系统

学习如何调整HNSW向量记忆参数，并测试子毫秒检索。

💡参考`Intelligence & Learning`章节。

实现联邦通信

在两台机器上分别安装Ruflo，配置mTLS和ed25519身份验证，发送加密消息。

💡注意PII检测和信任评分机制，避免数据泄露。

设置安全策略

配置AIDefence和CVE修复，启用HIPAA或GDPR合规模式。

💡使用`ruflo security configure`命令。

部署多代理工作流

使用Ruflo的队列和共识机制（Raft/Byzantine/Gossip）构建一个复杂工作流。

💡从简单链式任务开始，逐步增加并行代理。

深入进阶：自定义与优化

⏱ 4小时

开发自定义插件

学习Ruflo插件架构，编写一个简单的MCP工具插件。

💡参考`Plugin Marketplace`和`Plugin Development`文档。

优化模型路由

配置多LLM提供商（如Anthropic、OpenAI等）和故障转移策略。

💡使用`ruflo model route`命令查看当前路由。

性能调优

监控代理集群的延迟和吞吐量，调整SONA学习参数。

💡使用内置监控工具或集成第三方APM。

集成RAG

将Ruflo与HuggingFace或自定义向量数据库集成，实现检索增强生成。

💡参考`agentic-rag`相关文档。

⚠️ Common Mistakes

❌ 忽略MCP服务器配置，导致Claude Code无法与Ruflo通信。

✅ 确保已正确运行`claude mcp add ruflo`命令，并检查Claude Code的MCP设置。

❌ 在联邦通信中未正确配置mTLS证书，导致身份验证失败。

✅ 按照文档生成ed25519密钥对，并正确部署到两台机器上。测试前使用`ruflo federation trust`验证连接。

❌ 一次性创建过多代理，导致资源耗尽或性能下降。

✅ 从少量代理开始，逐步增加，并使用监控工具观察系统负载。合理设置队列和共识参数。

❌ 忽视PII检测配置，导致敏感数据泄露。

✅ 在联邦通信前，使用`ruflo security pii-scan`扫描消息，并根据业务需求调整策略（BLOCK/REDACT等）。

🚀 Next Steps

学完基础后，可以探索Ruflo的生态系统，如RuVector、agentic-flow、Flow Nexus，并尝试构建企业级多智能体应用，集成更多LLM提供商，或贡献自定义插件到社区。