Ruflo: вводный курс — многоагентный оркестратор, который умеет самосовершенствоваться

Обзор проекта

Ruflo — это уровень оркестрации мультиагентов, ориентированный на Claude Code. Если одной фразой, что он делает, то это: превратить Claude Code из «чат-помощника» в «ИИ-команду», которая умеет сотрудничать, хранить память и самоэволюционировать.

Изначально проект назывался Claude Flow — его разработала RuvNet (у основателей есть бекграунд в Rust; название — сочетание образа Ruv + flow). Базовый WASM-ядерный модуль на Rust реализует движок стратегий, векторные эмбеддинги и систему доказательств, обеспечивая высокую производительность. Новая стабильная версия [email protected] — это уже полноценный продукт уровня enterprise:

• 300+ MCP-инструментов напрямую встраиваются в Claude Code
• 60+ типов профессиональных Agent-ролевей (coder, tester, architect, security-architect……)
• Самообучающаяся память: AgentDB + HNSW-векторный индекс — поиск в 150–12,500 раз быстрее, чем грубый перебор
• Федеративное сотрудничество между машинами: Agent Federation — связь с нулевым доверием на базе mTLS + ed25519
• Способность к самоэволюции: нейромодуль SONA — извлекает паттерны из исторических траекторий и постоянно оптимизирует
• 32 плагина для безопасности, контроля затрат, автоматизации браузера, интеграции с GitHub и многого другого

У него очень любопытная философия проектирования — установив, вам не нужно учить 300 MCP-инструментов: слой маршрутизации Hooks сам отправляет задачу нужному Agent. Вы продолжаете писать код, а Ruflo в фоне координирует всё.

Сложность/время/результат

• Сложность: ★★☆☆☆ (можно запустить за 5 минут)
• Время: примерно 20 минут
• Результат: освоение топологии swarm и управления жизненным циклом, понимание принципов HNSW-векторной памяти, умение выстраивать взаимодействие Agent’ов через SendMessage

Целевая аудитория

• Разработчики с опытом 1–5 лет
• Те, кто хочет превратить ИИ из «чатового инструмента» в «команду для выполнения работ»
• Личные разработчики или небольшие команды, которые уже используют или планируют использовать Claude Code для разработки

Ключевые зависимости и окружение

Полное дерево структуры проекта

ruflo/
├── bin/
│   ├── cli.js              # Точка входа CLI (команда ruflo)
│   └── mcp-server.js       # MCP-сервер
│
├── v3/@claude-flow/        # Пакет ядра
│   ├── cli/                # 26 команд верхнего уровня (140+ подкоманд)
│   ├── memory/             # AgentDB + HNSW-поиск по векторам
│   ├── swarm/              # Унифицированный координатор (15-agent hierarchical mesh)
│   ├── security/           # Исправление CVE, валидация входных данных, безопасность путей
│   ├── neural/             # SONA-модуль самообучения
│   ├── hooks/              # 17 Hook + 12 фоновых Worker
│   ├── guidance/           # Управляющая плоскость (compile/enforce/prove/evolve)
│   └── shared/             # Типы, события, ключевые интерфейсы
│
├── plugins/                # 32 официальных плагина
│   ├── ruflo-core/         # База (сервер, health-check, обнаружение плагинов)
│   ├── ruflo-swarm/        # Оркестрация команды из множества Agent’ов
│   ├── ruflo-federation/   # Безопасное взаимодействие между машинами
│   ├── ruflo-agentdb/      # Память векторной базы
│   ├── ruflo-intelligence/ # Нейросамообучение паттернов
│   └── ...                 # Остальные 27 плагинов
│
├── .claude/                # Настройка Claude Code (MCP-сервер, settings.json)
├── .agents/                # Определения навыков Agent’а (синтаксис $skill-name)
└── mcp/                    # Определения MCP-инструментов (agent-tools.ts, memory-tools.ts и т. п.)

Пошаговая практика

Шаг 1: установка в один клик

Одна команда для инициализации — с подсказками мастера настройки:

npx ruflo@latest init --wizard

Эта команда последовательно сделает:

1. Сгенерирует в текущей директории CLAUDE.md и запишет правила маршрутизации Hooks
2. Зарегистрирует MCP-сервер в конфигурации Claude Code
3. В папке .claude-flow/ запишет настройки по умолчанию и файл seed-памяти

Если вы устанавливаете впервые, выберите вариант «full» — установится конфигурационный файл со всеми доступными опциональными модулями.

---

Шаг 2: регистрация MCP-сервиса

Если предыдущий шаг не зарегистрировал MCP автоматически, добавьте вручную:

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

Проверьте, что регистрация прошла успешно:

claude mcp list
# Ожидаемый вывод примерно такой:
# Name    Command                          Args  Status
# ruflo   npx -y @claude-flow/cli@latest  mcp  enabled

---

Шаг 3: инициализация первого Swarm (hierarchical + 5 Agent’ов)

npx ruflo swarm init --topology hierarchical --max-agents 8
npx ruflo agent spawn --type architect --name arch-1
npx ruflo agent spawn --type coder --name coder-1
npx ruflo agent spawn --type coder --name coder-2
npx ruflo agent spawn --type tester --name tester-1
npx ruflo agent spawn --type reviewer --name reviewer-1

---

Шаг 4: настройка связи между Agent’ами через SendMessage

Это ключевая идея Ruflo — именованные Agent’ы общаются в реальном времени через SendMessage, без опроса или общего пула памяти:

// В Task tool в Claude Code:
Task({
  prompt: "Спроектируйте решение для REST API. После завершения отправьте SendMessage агенту 'coder-1' с описанием решения.",
  subagent_type: "system-architect",
  name: "arch-1",
  run_in_background: true
})

Task({
  prompt: "Дождитесь дизайн от arch-1. После реализации отправьте SendMessage агенту 'tester-1' с путем к коду.",
  subagent_type: "coder",
  name: "coder-1",
  run_in_background: true
})

Task({
  prompt: "Дождитесь код от coder-1. Напишите интеграционные тесты. По завершении отправьте SendMessage агенту 'reviewer-1' с результатом.",
  subagent_type: "tester",
  name: "tester-1",
  run_in_background: true
})

// Запуск пайплайна — отправляем сообщение первому Agent’у
SendMessage({
  to: "arch-1",
  summary: "Начинаем проектирование API",
  message: "Спроектируйте набор CRUD REST API для управления пользователями (создание/удаление/изменение/получение). После подготовки отправьте план coder-1."
})

Направление потока: arch-1 → coder-1 → tester-1 → reviewer-1 — каждый Agent знает, кому передать следующий шаг.

---

Шаг 5: сохранить первую запись памяти (AgentDB + HNSW)

npx ruflo memory store \
  --key "pattern-auth-service" \
  --value "JWT-аутентификация: Bearer Token, express-jwt как middleware, refresh token хранится в Redis, срок действия 6 часов" \
  --namespace patterns

Сохраненный текст автоматически получит векторные эмбеддинги; запись попадает в AgentDB для последующего семантического поиска.

---

Шаг 6: проверка памяти через семантический поиск

npx ruflo memory search --query "authentication patterns" --namespace patterns

Вывод покажет совпавшие записи и балл сходства (0–1, чем выше — тем релевантнее). Если score > 0.7, совпадение очень сильное — можно использовать напрямую.

---

Шаг 7: старт фонового Daemon + запуск диагностики здоровья

# Старт фонового демона (12 автоматических Worker начинают работу)
npx ruflo daemon start

# Одним кликом диагностика (Node version, API Key, подключение MCP, свободное место на диске)
npx ruflo doctor --fix

doctor --fix автоматически исправит то, что ему под силу (например, отсутствующие зависимости) и выведет в терминал полный отчет о здоровье.

---

Шаг 8: установка плагинов (по необходимости)

Плагины ставятся очень удобно — выбирайте нужный функционал:

# Добавить маркетплейс плагинов
/plugin marketplace add ruvnet/ruflo

# Установить плагин федеративного сотрудничества (коммуникация Agent’ов между машинами)
/plugin install ruflo-federation@ruflo

# Установить самообучающийся плагин (SONA нейросценарии)
/plugin install ruflo-intelligence@ruflo

# Установить плагин для безопасностного аудита
/plugin install ruflo-security-audit@ruflo

# Установить плагин для отслеживания затрат
/plugin install ruflo-cost-tracker@ruflo

Или через CLI:

npx ruflo plugins install ruflo-federation
npx ruflo plugins list  # Посмотреть все доступные плагины

---

Шаг 9: продвинутый уровень — вызов self-evolve способностей (SONA)

# Пусть SONA извлечет паттерны из последних успешных кейсов и обучится
npx ruflo hooks post-task --task-id "abc-123" --success true --train-neural true

# Посмотреть текущие выученные паттерны
npx ruflo neural patterns

# Пусть слой маршрутизации использует умный роутинг (89% точности)
npx ruflo hooks route --task "написать middleware для API"

SONA будет работать в фоне по 4 этапам пайплайна: RETRIEVE (HNSW) → JUDGE (вердикт успех/провал) → DISTILL (LoRA-дистилляция) → CONSOLIDATE (EWC++ для предотвращения катастрофического забывания).

---

Частые проблемы и их устранение

1. Ошибка подключения MCP: в claude mcp list ruflo отображается как disabled

Чаще всего причина — проблема с версией Node или порт занят:

# Проверка версии Node
node -v  # должна быть ≥20.0.0

# Ручной перезапуск MCP-сервиса
claude mcp remove ruflo
claude mcp add ruflo -- npx -y @claude-flow/cli@latest mcp start

# Проверка занятости порта
lsof -i :3000  # macOS
netstat -tlnp | grep 3000  # Linux

---

2. API Key не настроен, ошибка ANTHROPIC_API_KEY is not set

Ruflo требует как минимум один API Key от LLM-провайдера:

# Временная настройка (действует только в рамках текущей сессии)
export ANTHROPIC_API_KEY=sk-ant-xxxx

# Постоянно записать в ~/.bashrc или ~/.zshrc
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxx' >> ~/.zshrc

# Или через конфигурационный файл (init --wizard подскажет, как записать .env)
# Поддерживаются несколько провайдеров: Claude / GPT / Gemini / Ollama
npx ruflo providers add anthropic --key sk-ant-xxxx
npx ruflo providers test anthropic  # Тест подключения

---

3. Версия Node не соответствует требованиям: ruflo: requires Node.js >=20.0.0

# Способ 1: обновление через nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 20
nvm use 20

# Способ 2: nvm-windows в Windows
# Ссылка на релиз: https://github.com/coreybutler/nvm-windows/releases
nvm install 20
nvm use 20

# Проверка
node -v  # должно быть v20.x.x

---

4. memory search не находит результатов

Возможно, вы ошиблись в namespace или память еще не сохранена:

# Посмотреть все текущие namespace
npx ruflo memory list --namespace

# Показать все ключи в patterns
npx ruflo memory list --namespace patterns

# Достать известный ключ напрямую
npx ruflo memory retrieve --key "pattern-auth-service"

# Если база пустая — сначала попробуйте сохранить одну запись
npx ruflo memory store --key "test-entry" --value "hello world" --namespace patterns
npx ruflo memory search --query "test" --namespace patterns

---

5. После старта swarm все Agent’ы в состоянии idle

Это означает, что задачи еще не отправлены. Проверьте следующее:

# Посмотреть состояния всех Agent’ов
npx ruflo agent list

# Проверить, инициализирован ли swarm
npx ruflo swarm status

# Если вы запускали через Task tool в Claude Code — убедитесь, что отправили стартовое сообщение:
# SendMessage({ to: "arch-1", message: "Начинаем работу" })
# Если нет SendMessage — первый Agent не запустится автоматически

---

6. ruflo doctor сообщает MongoDB not running

При запуске через Docker Compose (ruflo/src/ruvocal/) требуется MongoDB:

# Способ 1: запустить полный набор зависимостей через Docker
cd ruflo/src/ruvocal
docker compose up -d

# Способ 2: использовать встроенный standalone-режим (без MongoDB)
npx ruflo start --mode standalone
# В standalone используется sql.js (WASM) вместо MongoDB — полностью офлайн

---

Дополнительное чтение / направления продвинутого уровня

1. Agent Federation — сотрудничество с нулевым доверием между машинами

Одна из самых крутых функций. Делает так, чтобы Agent’ы на разных машинах могли работать вместе, при этом PII будет автоматически отфильтровано до отправки:

npx ruflo federation init
npx ruflo federation join wss://other-team.example.com:8443
npx ruflo federation send --to team-b --type task-request --message "проанализировать паттерны транзакций"

Детали архитектуры: каждый исходящий месседж проходит через 14 типов проверки PII → политика из четырех уровней BLOCK / REDACT / HASH / PASS → верификация подписи и личности адресата через mTLS + ed25519. Злоумышленное поведение автоматически понижает уровень доверия — без ручного вмешательства.

2. Принцип работы векторного поиска RuVector HNSW

Это не просто совпадение ключевых слов: текст кодируется в 384-мерный вектор, а затем в векторном пространстве с помощью алгоритма HNSW (Hierarchical Navigable Small World) находятся ближайшие соседи. Каждый memory store автоматически генерирует эмбеддинги, а каждый memory search сортирует результаты по косинусному сходству.

3. Быстрая шпаргалка по экосистеме из 32 плагинов

4. Онлайн-опыт (без установки)

• UI для чата с несколькими моделями: https://flo.ruv.io/ — поддерживает Qwen 3.6 Max / Claude Sonnet / Gemini 2.5 Pro и параллельные вызовы MCP-инструментов
• UI для планирования целей: https://goal.ruv.io/ — превращает вашу фразу «запустить рефакторинг Auth и написать тесты» в маршрут GOAP A*
• Live-дашборд Agent’ов: https://goal.ruv.io/agents — в реальном времени видеть состояние каждого Agent, пространства имён памяти и токен-бюджеты

5. Индекс официальной документации

6. Discord-сообщество

Столкнулись с проблемами или хотите поделиться тем, что вы сделали как Skills? RuvNet поддерживает активное комьюнити в Discord Agentics Foundation:

https://discord.com/invite/dfxmpwkG2D

Там много навыков, созданных пользователями, в формате $skill-name — их можно просто взять и использовать.