1. 项目简介

一句话：Ruflo 是一个面向 Claude Code 的多智能体 AI 编排框架，给单一上下文的 AI 助手装上“神经系统”——把 100+ 个专长各异的 Agent 组织成可协作的 Swarm，并为它们提供共享记忆、自我学习、跨机器联邦通信和企业级安全能力。

核心功能

  • 🤖 多 Agent 编排：Hierarchical / Mesh / Hybrid / Adaptive 等多种拓扑下的 Swarm 协调，支持 Hive-Mind（女王协调者）和 Byzantine / Raft / Gossip 等共识算法。
  • 🧠 自学习记忆：基于 AgentDB + HNSW 向量索引的长期记忆，集成 ReasoningBank 与 SONA 神经模式学习，实现“成功一次→沉淀模式→未来复用”。
  • 🔌 MCP-First：以 Model Context Protocol 为对外 API，向 Claude Code、Codex CLI、Web UI 暴露 ~300 个工具（agent_/swarm_/memory_/hooks_/github_/browser_ 等）。
  • 🌐 Agent Federation：跨安装/跨机器的零信任协作通道，自动剥离 PII、mTLS+ed25519 鉴权、可审计。
  • 🔁 Hooks 自动化：pre-task / post-task / route / session-* 钩子在 Claude Code 操作流程中自动注入路由、记忆检索、模式训练等行为。
  • 🧩 插件市场：32 个原生 Claude Code 插件（已 ls plugins/ \| grep ^ruflo \| wc -l = 32 核实，含 ruflo-core / -swarm / -autopilot / -federation / -ruvector / …）+ README 声明的 21 个 npm 插件。
  • 🛡️ AIDefence：提示注入检测、PII 检测、CVE 修复、路径穿越防护等安全能力。
  • 💬 配套 Web UI：ruvocal（多模型聊天 + 并行 MCP 工具调用）和 goal_ui（GOAP A* 自主规划器）。

技术栈总览

层技术
运行时Node.js >= 20，ESM ("type": "module")；可选 Bun
语言TypeScript 5.x（v3 主线）、JavaScript（v2 与 bin 入口）
包管理npm（顶层）+ pnpm 8.x workspace（v3/）
测试Vitest 1.x / 4.x（v3）、Jest（v2 历史遗留）
协议MCP（stdio / http / websocket / in-process）
校验zod ^3
内存/向量agentdb ^3、@ruvector/*（HNSW、attention、router、sona）
LLM 接入agentic-flow ^2、Anthropic / OpenAI / Gemini / OpenRouter / Ollama
Web UIruflo/src/ruvocal/（多阶段 Dockerfile + MongoDB），v3/goal_ui/（Vite + Supabase）
部署Docker Compose、Cloud Run（cloudbuild.yaml）、scripts/install.sh

2. 目录结构说明

ruflo/                                  # 仓库根（npm 包名 "claude-flow"，CLI 名 claude-flow）
├── bin/                                # 顶层 CLI 入口（极薄壳）
│   ├── cli.js                          # 入口：proxy 到 v3/@claude-flow/cli/bin/cli.js
│   ├── npx-repair.js                   # npx 缓存修复
│   └── npx-safe-launch.js              # npx 安全启动
├── package.json                        # name=claude-flow, bin: claude-flow → bin/cli.js
├── tsconfig.json                       # TS 配置（include: v3/**/*.ts，paths: @v3/* → ./v3/*）
│
├── ruflo/                              # 独立 npm 包 "ruflo"（品牌封装 + 周边产品）
│   ├── bin/ruflo.js                    # ruflo CLI（自动探测 MCP 模式 vs CLI 模式）
│   ├── package.json                    # 依赖 @claude-flow/cli
│   ├── docker-compose.yml              # 一键起 mcp-bridge + chat-ui + mongo + nginx
│   └── src/
│       ├── mcp-bridge/                 # ★ MCP 网关（Express + stdio MCP 客户端聚合）
│       ├── ruvocal/                    # ★ Web UI（Svelte/SvelteKit 多模型聊天 + MCP）
│       ├── chat-ui/                    # 备用聊天前端
│       ├── nginx/                      # 反向代理配置
│       ├── config/                     # 默认配置 / .env 模板
│       └── scripts/                    # generate-config / deploy / package-rvf
│
├── v3/                                 # ★ 新一代主线（pnpm workspace）
│   ├── package.json                    # workspaces: @claude-flow/* + claude-flow
│   ├── pnpm-workspace.yaml
│   ├── tsconfig.base.json
│   ├── index.ts                        # 聚合入口：re-export 所有 @claude-flow/* 模块
│   ├── swarm.config.ts                 # Swarm 默认拓扑/agent 数配置
│   │
│   ├── @claude-flow/                   # ★★ 核心 monorepo（每个目录一个 npm 包）
│   │   ├── cli/                        # ruflo / claude-flow CLI 主体（含 src/commands/*）
│   │   ├── cli-core/                   # 极简核心（仅 memory + hooks，<5s 冷启）
│   │   ├── shared/                     # 公共类型 / 事件 / 工具
│   │   ├── mcp/                        # MCP server / 连接池 / 工具注册（<400ms 启动）
│   │   ├── memory/                     # AgentDB + HNSW + 混合后端 (ADR-009)
│   │   ├── swarm/                      # 100+ agent 协调、4 种拓扑、共识
│   │   ├── hooks/                      # 事件驱动钩子 + ReasoningBank 集成
│   │   ├── neural/                     # SONA 神经模式 / 神经训练
│   │   ├── security/                   # CVE 修复、输入校验、路径安全
│   │   ├── aidefence/                  # AIMDS：提示注入 / PII / 向量检索安全
│   │   ├── providers/                  # 多 LLM 提供方
│   │   ├── embeddings/                 # OpenAI / Transformers.js / ONNX 嵌入
│   │   ├── plugins/                    # Worker / Hook / Provider 插件 SDK
│   │   ├── plugin-agent-federation/    # 跨安装零信任联邦
│   │   ├── plugin-iot-cognitum/        # IoT Seed 设备桥接
│   │   ├── claims/                     # 任务认领与协调（src/ tests/ vitest.config.ts）
│   │   ├── codex/                      # OpenAI Codex CLI 适配（含 agents/ AGENTS.md src/）
│   │   ├── deployment/                 # 发版 / CI-CD / 版本管理（含 examples/ QUICK_START.md）
│   │   ├── guidance/                   # Guidance Control Plane（含 wasm-kernel/ wasm-pkg/ scripts/）
│   │   ├── integration/                # agentic-flow@alpha 深度集成（ADR-001）
│   │   ├── performance/                # 基准 / Flash Attention 验证（含 benchmarks/ docs/）
│   │   ├── testing/                    # TDD London 测试框架与 fixtures
│   │   ├── browser/                    # 浏览器自动化（含 docker/ skills/ agents/）
│   │   └── agents/                     # 仅 5 个 yaml（与顶层 agents/、v3/agents/ 完全相同）
│   │
│   ├── src/                            # 另一套精简 DDD 实现（教学/参考用，与 @claude-flow 并存）
│   │   ├── shared/types/               # 共享 TypeScript 接口
│   │   ├── agent-lifecycle/domain/     # Agent 实体（Agent.ts）
│   │   ├── task-execution/             # Task 实体 + WorkflowEngine（domain + application）
│   │   ├── memory/                     # MemoryEntity + Hybrid/SQLite/AgentDB 后端
│   │   ├── coordination/application/   # SwarmCoordinator（EventEmitter 驱动）
│   │   └── infrastructure/{mcp,plugins}# MCPServer + PluginManager
│   │
│   ├── mcp/                            # 独立 MCP server 实现（与 @claude-flow/mcp 并存）
│   ├── agents/                         # 5 个 yaml 角色（与顶层 agents/、@claude-flow/agents/ 完全相同）
│   ├── helpers/                        # 跨平台启动脚本 (claude-flow-v3.sh / .ps1) + templates/ + docs/
│   ├── implementation/                 # ADR / 架构 / 迁移 / hooks / init / plugins / PLUGIN_INTEGRATION.md
│   ├── docs/                           # ADR / DDD / examples / benchmarks / assets
│   ├── goal_ui/                        # goal.ruv.io 的 GOAP A* 前端（Vite + Supabase）
│   └── __tests__/                      # 集成 + 安全测试（vitest）
│
├── v2/                                 # 历史版本（仍在维护，src/ 极其庞大）
│   ├── src/{cli,hive-mind,mcp,swarm,neural,reasoningbank,enterprise,…}
│   └── …                               # 与 v3 概念对应，但实现独立
│
├── plugins/                            # ★ Claude Code 插件市场（32 个独立插件目录）
│   ├── ruflo-core/   ruflo-swarm/   ruflo-autopilot/   ruflo-federation/
│   ├── ruflo-agentdb/   ruflo-rag-memory/   ruflo-ruvector/   ruflo-rvf/
│   ├── ruflo-intelligence/   ruflo-daa/   ruflo-sparc/   ruflo-ddd/
│   ├── ruflo-security-audit/   ruflo-aidefence/   ruflo-cost-tracker/  …
│
├── plugin/                             # 单个示例插件骨架（agents/ commands/ skills/ 三个子目录 + 一个 hooks.json 文件）
├── agents/                             # 顶层 5 个角色 yaml（与 v3/agents/ 完全相同）
│
├── .claude/                            # 安装到工作区后的 Claude Code 配置（即 ruflo init 的产物）
│   ├── agents/  commands/  skills/  hooks/  helpers/  config/  checkpoints/
│   ├── settings.json    mcp.json       # MCP 注册 + 通用设置（settings.json.bak 为备份）
│   └── statusline.mjs / statusline.sh / statusline-command.sh
├── .claude-plugin/                     # 把本仓库本身打包成一个 Claude Code 插件 + 市场清单
│   ├── plugin.json                     # 已确认：name=claude-flow, version=2.5.0,
│   │                                   #          含 150+ commands / 74+ agents 的元数据
│   ├── marketplace.json                # 市场清单
│   └── docs/  hooks/  scripts/  README.md
├── .agents/                            # Codex CLI 用的同类配置（config.toml + skills/）
├── AGENTS.md                           # ★ Codex CLI 行为指南（核心：Codex 执行 / Ruflo 编排）
├── CLAUDE.md                           # ★ Claude Code 行为指南（路由、并发、防漂移规则）
├── CLAUDE.local.md                     # 本地覆盖配置（.local 后缀，未提交）
│
├── docs/                               # GitHub Pages 文档站点
│   ├── index.md  USERGUIDE.md (~7600 行)  STATUS.md  _config.yml
├── scripts/                            # install.sh / cleanup-v3.sh / inventory-capabilities.mjs
│                                       # / regenerate-witness.mjs / sign-witness-from-inventory.mjs / verify-appliance.sh
├── tests/                              # 顶层冒烟/集成测试（rvf-* 系列 + context-persistence-hook + docker-regression/）
├── .githooks/   .github/               # Git hooks 与 GitHub workflows
├── verification.md  verification-inventory.json  verification.md.json
│                                       # 已签名能力清单（“密码学见证”机制，由 ruflo verify 校验）
└── README.md / SECURITY.md / CHANGELOG.md / LICENSE

提示：v3 是当前主线，v2 是历史版本仍可访问；新增功能优先去 v3/@claude-flow/<module>/。

3. 架构设计

3.1 整体架构模式

Ruflo 采用 Hexagonal + DDD + Plugin Microkernel 的混合模式，10 个核心 ADR（v3/index.ts 顶部有完整列表）奠定了基调，最关键的几条：

  • ADR-001：把 agentic-flow 作为底层基石，Ruflo 是其“专门化扩展”，避免重复造轮子；
  • ADR-002：按领域 (agent-lifecycle / task-execution / memory / coordination / infrastructure) 拆分包；
  • ADR-003：单一 SwarmCoordinator 引擎，避免 v2 时代多套并存；
  • ADR-004：Plugin-based 微内核，所有非核心能力通过 @claude-flow/plugins SDK 接入；
  • ADR-005：MCP-First API 设计，CLI / Hooks / Web UI 共享同一层工具；
  • ADR-006 + ADR-009：统一记忆服务，默认混合后端 (SQLite + AgentDB)；
  • ADR-007：状态变化用事件溯源（Event Sourcing）；
  • ADR-010：抛弃 Deno，仅支持 Node.js 20+。

3.2 核心模块与职责

模块（v3/@claude-flow/*）职责
cli用户主入口；命令注册、解析、懒加载；既可作为交互式 CLI，也可作为 stdio MCP server
cli-core极简核心，只包含 memory + hooks，确保插件冷启 <5s
shared公共类型、事件总线、错误模型
mcpMCP 协议实现：连接池、工具注册、stdio/http/websocket 传输
memoryAgentDB 统一封装 + HNSW 向量索引 + 混合后端
swarm100+ agent 协调、4 种拓扑、Hive-Mind、共识算法
hooks事件驱动生命周期钩子 + ReasoningBank 学习闭环
neuralSONA 神经模式、Q-Learning 路由、轨迹学习
security / aidefenceCVE 修复、输入校验、路径穿越；提示注入 / PII 检测
providers多 LLM 提供方抽象（Anthropic/OpenAI/Gemini/Cohere/Ollama）
embeddings嵌入服务（OpenAI / Transformers.js / ONNX / Mock）
pluginsWorker / Hook / Provider 插件统一 SDK
plugin-agent-federation跨安装零信任联邦：mTLS、ed25519、PII 网关、审计日志
guidance把 ADR/规则编译为 Claude 会话可消费的 Guidance Plane
claims / deployment / integration / testing / performance / browser / codex各自独立的功能包

ruflo/src/mcp-bridge/index.js 是“MCP 工具聚合网关”：它把 ruflo / agentic-flow / ruvector / claude / gemini / codex 等多个上游 MCP server 的工具按 Tool Group（intelligence / agents / memory / devtools / security / browser / neural / …）统一聚合再暴露给 Web UI，每个 Group 都可由环境变量 MCP_GROUP_* 单独开关。

3.3 模块间调用关系与数据流

        ┌────────────────────────── 用户层 ──────────────────────────┐
        │ Claude Code / Codex CLI / Web UI (ruvocal) / 终端 ruflo …  │
        └───────────────┬────────────────────────┬──────────────────┘
                        │ JSON-RPC (MCP)         │ CLI args
                        ▼                        ▼
                ┌───────────────┐        ┌──────────────────┐
                │ MCP Bridge    │        │ @claude-flow/cli │
                │ (聚合多上游)  │◀──spawn│ (命令路由 + 懒加载) │
                └───────┬───────┘        └────────┬─────────┘
                        │                         │
                        ▼                         ▼
                ┌───────────────────────────────────────────┐
                │   AIDefence  →  Hooks (pre-task / route)  │
                │           ↓                                │
                │   SwarmCoordinator + Hive-Mind             │
                │           ↓                                │
                │ Agents (coder/tester/reviewer/architect/…) │
                │           ↓                                │
                │   Memory (AgentDB + HNSW + SQLite hybrid)  │
                │           ↓                                │
                │   Providers (Anthropic / OpenAI / Gemini)  │
                └───────────────────────────────────────────┘
                        ▲                         │
                        │                         ▼
                ┌──────────────────────────────────────────┐
                │ Hooks (post-task) → ReasoningBank/SONA   │
                │  → memory_store(namespace="patterns")    │  ← 学习闭环
                └──────────────────────────────────────────┘

关键约定（AGENTS.md）：“Codex/Claude 执行任务，Ruflo/claude-flow 只编排和记忆”——swarm_init / agent_spawn 等命令是“即时返回的协调记录”，不会真正去写代码。

4. 核心流程解析

4.1 应用启动流程

CLI 启动是一个两层薄壳 → 真正业务的过程：

  1. 顶层入口：bin/cli.js（仅 11 行）

    // bin/cli.js
const cliPath = join(__dirname, '..', 'v3', '@claude-flow', 'cli', 'bin', 'cli.js');
await import(pathToFileURL(cliPath).href);

    它直接转发到 v3 包内 CLI，避免顶层 package.json 与 v3 子包重复维护逻辑。

  2. 品牌薄壳 ruflo/bin/ruflo.js：自动探测“是否处于 MCP stdio 模式”：

    const isExplicitMCP = cliArgs[0] === 'mcp' && (cliArgs.length === 1 || cliArgs[1] === 'start');
const isMCPMode = !process.stdin.isTTY && (process.argv.length === 2 || isExplicitMCP);
if (isMCPMode) { await import(...'cli.js'); }                 // JSON-RPC 模式
else           { const { CLI } = await import(...'index.js'); // 交互式模式
                 new CLI({ name: 'ruflo' }).run().then(() => process.exit(0)); }

  3. 真正入口 v3/@claude-flow/cli/bin/cli.js：

    • 先 import log-filters.js（必须最先执行，过滤 agentdb 兼容性噪音）；
    • 再次执行同样的 MCP 模式探测，若是 stdio MCP 则启用 10MB 缓冲上限的 JSON-RPC 解析循环并加载 mcp-client.js；
    • 否则进入 CLI 类（src/index.ts）：注册命令、解析参数、检查更新、分派到对应 commands/<name>.ts。

  4. 命令懒加载：src/commands/index.ts 用 commandLoaders 表保存 () => import('./xxx.js')，只有用户真正用到某条命令才会加载它的代码——这是冷启时间能压到 < 500ms 的关键。

4.2 ruflo init —— 项目初始化

入口 v3/@claude-flow/cli/src/commands/init.ts，真正的实现拆分在 v3/@claude-flow/cli/src/init/ 下八个文件：

src/init/
├── index.ts                  # 桶式 re-export
├── types.ts                  # InitOptions / InitComponents / *Config 类型 + DEFAULT/MINIMAL/FULL_INIT_OPTIONS + detectPlatform
├── executor.ts               # 主执行器：executeInit / executeUpgrade / executeUpgradeWithMissing
├── settings-generator.ts     # generateSettings / generateSettingsJson  → .claude/settings.json
├── claudemd-generator.ts     # generateClaudeMd / generateMinimalClaudeMd + CLAUDE_MD_TEMPLATES
├── mcp-generator.ts          # generateMCPConfig / generateMCPJson / generateMCPCommands → .claude/mcp.json
├── statusline-generator.ts   # generateStatuslineScript / generateStatuslineHook
└── helpers-generator.ts      # generatePreCommitHook / PostCommitHook / SessionManager / AgentRouter
                              #  / MemoryHelper / WindowsDaemonManager / WindowsBatchWrapper
                              #  / CrossPlatformSessionManager

执行流程：

  1. commands/init.ts 读取 CLI flag（--minimal / --full / --codex / --dual / --force），结合 select / confirm / multiSelect 交互 prompt，组合出一个 InitOptions；
  2. 调用 executeInit(options)，依次触发上述各 generate* 把生成的文本写到工作区：
    • CLAUDE.md（路由 / Hook / 行为约定）
    • .claude/{agents,commands,skills,hooks,helpers,config}/
    • .claude/settings.json、.claude/mcp.json
    • .claude/statusline.*（多种 statusline 脚本）
    • 跨平台 helper 脚本（特别地，Windows 走 WindowsDaemonManager / WindowsBatchWrapper）
  3. 启用 Codex 双模式时，会额外调用 @claude-flow/codex 的初始化器写出 .agents/、AGENTS.md 等。

已读源码确认：.claude-flow/（运行时配置 + 记忆 DB）由后续命令运行时按需创建，不一定在 init 阶段写入。

4.3 Swarm 协调流程（“一句话需求 → 多 agent 落地”）

以 Recipe 1b（来自 AGENTS.md）为例：

npx claude-flow swarm init --topology hierarchical --max-agents 5
for i in 1 2 3 4 5; do
  npx claude-flow agent spawn --type coder --name "worker-$i"
done
# 真正干活的是“调用方”，例如 Codex / Claude / 用户：
for i in 1 2 3 4 5; do (echo "Worker $i: Hello!" && sleep 0.$i) & done
wait

调用链（基于 v3/src/coordination/application/SwarmCoordinator.ts 的真实实现）：

swarm init / agent spawn
   → @claude-flow/cli 的 swarm.ts / agent.ts
   → SwarmCoordinator (基于 agentic-flow 的 AttentionCoordinator 模式)
       ├─ 持有 Map<id, Agent> agents、Map<id, AgentMetrics> agentMetrics、MeshConnection[] connections
       ├─ 内部通过 EventEmitter 广播事件，例如 spawnAgent() 末尾会 emit:
       │     this.eventBus.emit('agent:spawned', { agentId, type })
       ├─ 若构造时传入 memoryBackend，则把每次 spawn 写入记忆：
       │     this.memoryBackend.store({
       │       id: `agent-spawn-${agent.id}`,
       │       agentId: 'system',
       │       type: 'event',
       │       timestamp: Date.now(),
       │       metadata: { eventType: 'agent-spawn', agentId, agentType }
       │     })
       └─ 根据 topology 通过 updateConnections() 维护 agent 间连边
   → 真实代码生成 / shell 命令由调用方（Claude / Codex / 用户）完成
   → post-task hook 回收结果 → ReasoningBank 评分 → 由调用方主动 memory_store 到 "patterns" namespace

关键代码片段（v3/src/index.ts）：

export { SwarmCoordinator, type SwarmCoordinatorOptions } from './coordination/application/SwarmCoordinator';
export { WorkflowEngine, type WorkflowEngineOptions } from './task-execution/application/WorkflowEngine';
export { Agent } from './agent-lifecycle/domain/Agent';
export { Task } from './task-execution/domain/Task';

注意：swarm-state 这个 namespace 名并未在 SwarmCoordinator 中硬编码出现；状态以 MemoryEntry（type: 'event'）形式逐条 append（事件溯源），由上层应用聚合得到 swarm 当前状态。

4.4 MCP server 启动与工具暴露

启动方式：ruflo mcp start 或被 Claude Code 通过 claude mcp add ruflo -- npx ruflo@latest mcp start 拉起。

client (Claude Code)  ── stdio JSON-RPC ─▶  ruflo/bin/ruflo.js (isMCPMode)
                                          └─▶ v3/@claude-flow/cli/bin/cli.js
                                               └─ mcp-client.js: listMCPTools / callMCPTool
                                                  └─ @claude-flow/mcp 内核：
                                                     • SessionManager
                                                     • ConnectionPool（≤10）
                                                     • ToolRegistry
                                                     • Transports: stdio / http / websocket

工具来源（已 ls 确认）：所有 CLI 暴露的 MCP 工具集中在 v3/@claude-flow/cli/src/mcp-tools/ 下，命名规约是 <group>-tools.ts —— 例如 agent-tools.ts / swarm-tools.ts / memory-tools.ts / hooks-tools.ts / hive-mind-tools.ts / coordination-tools.ts / agentdb-tools.ts / embeddings-tools.ts / neural-tools.ts / security-tools.ts / browser-tools.ts / github-tools.ts / performance-tools.ts / analyze-tools.ts / config-tools.ts / system-tools.ts / terminal-tools.ts / progress-tools.ts / session-tools.ts / task-tools.ts / claims-tools.ts / autopilot-tools.ts / daa-tools.ts / guidance-tools.ts / ruvllm-tools.ts / browser-session-tools.ts / agent-execute-core.ts / auto-install.ts / request-tracker.ts，由同目录 index.ts 聚合。注册中心 ToolRegistry（v3/mcp/tool-registry.ts:59）继承 EventEmitter，工具注册/执行的事件可直接被 hooks 监听。Web UI 路径下的工具则由 ruflo/src/mcp-bridge 通过 StdioMcpClient 从多个上游 MCP server 子进程动态拉取后再聚合。

4.5 Memory 写入与语义检索（学习闭环）

v3/src/memory/ 给出了一个清晰可读的 DDD 实现：

// v3/src/index.ts
export { HybridBackend } from './memory/infrastructure/HybridBackend';
export { SQLiteBackend } from './memory/infrastructure/SQLiteBackend';
export { AgentDBBackend } from './memory/infrastructure/AgentDBBackend';
  • 写：MCP 工具 memory_store(...) 最终落到 HybridBackend.store(MemoryEntry)：
    • 元数据 + 内容写 SQLite（事务、agentId / type 索引）；
    • 当 entry.embedding 非空时，写 AgentDB 的 HNSW 索引。
    • HNSW 真实默认参数已确认（v3/src/memory/infrastructure/AgentDBBackend.ts:28-29）： this.hnswM = options.hnswM || 16; this.efConstruction = options.efConstruction || 200;； v3/@claude-flow/memory/src/hnsw-index.ts:537 同样把 efConstruction 默认值定为 200。
  • 读：memory_search({query, ...})：
    • 先用 @claude-flow/embeddings（OpenAI / Transformers.js / ONNX / Mock 任选）把 query 文本转成向量；
    • 在 AgentDB 中做 HNSW 近邻搜索（注释声明比暴力检索快 150× – 12,500×，见 AgentDBBackend.ts:6 与 HybridBackend.ts:103）；
    • 用 score 阈值筛选（AGENTS.md 给出的经验值：>0.7 强匹配 / 0.5–0.7 弱匹配），再联合 SQLite 元数据返回。

4.6 Web UI + MCP Bridge（ruvocal）

ruflo/src/mcp-bridge/index.js：用 Express + 自实现 StdioMcpClient 同时管理多个上游 MCP server 子进程，通过 Tool Groups（core / intelligence / agents / memory / devtools / security / browser / neural / agentic-flow / claude-code / gemini / codex）将所有上游工具按前缀打平后暴露给 Web UI；前端在一次模型回合内即可并行触发 4–6+ 个工具调用。

Web UI 本体在 ruflo/src/ruvocal/，技术栈已核实（ruflo/src/ruvocal/package.json）：SvelteKit (@sveltejs/kit ^2.52) + Vite + svelte-check + vitest，name: "chat-ui"，源码骨架为 src/{lib,routes,styles} + app.html / hooks.server.ts，多阶段 Dockerfile 可选 INCLUDE_DB=true 内嵌 MongoDB。

5. 关键设计与实现

5.1 设计模式

  • Microkernel + Plugin：@claude-flow/plugins 提供 Worker / Hook / Provider 三类扩展点；32 个 plugins/ruflo-* 是其“市场实例”。
  • Domain-Driven Design (DDD)：v3/src/{agent-lifecycle,task-execution,memory,coordination} 是教学级实现，每个领域含 domain/ 实体 + application/ 用例。
  • Hexagonal：infrastructure/{mcp,plugins} 把外部协议适配与领域逻辑彻底分离。
  • Event Sourcing（ADR-007）：状态变化通过事件流持久化，便于审计与回放。
  • Strategy：memory 多后端（SQLite / AgentDB / Hybrid）、providers 多 LLM、embeddings 多嵌入算法均为策略模式。
  • Lazy Loading：commandLoaders[name] = () => import('./xxx.js')，按需加载命令；@claude-flow/cli-core 只装核心子集。
  • Decorator-style Filtering：CLI 入口用闭包覆写 console.warn/log 精确屏蔽 agentdb 噪音，且仅匹配特定文本，避免遮蔽真问题。

5.2 数据模型（已对照源码核对）

仓库里同时存在两套互不冲突的内存模型，对应两套实现层：

A. DDD 教学层 v3/src/

  • MemoryEntity（v3/src/memory/domain/Memory.ts）： 
    { id, agentId, content, type: MemoryType, timestamp,
  embedding?: number[], metadata?: Record<string, unknown> }
    注意这里没有 namespace / key 字段——它围绕 agentId + type 组织。
  • Agent（v3/src/agent-lifecycle/domain/Agent.ts）： 
    { id, type: AgentType, status: AgentStatus, capabilities: string[],
  role?: AgentRole, parent?: string, metadata?, createdAt, lastActive }
    无 name / tokenBudget / memoryNamespace，这些是 CLI 层 / metadata 里的概念。
  • Task（v3/src/task-execution/domain/Task.ts）： 
    { id, type: TaskType, description, priority: TaskPriority,
  status: TaskStatus, assignedTo?: string, dependencies: string[],
  metadata?, workflow?: WorkflowDefinition,
  onExecute?: () => void|Promise<void>, onRollback?: () => void|Promise<void> }
// 私有：startedAt? / completedAt?
    字段叫 assignedTo（不是 assignedAgentId），并用 areDependenciesResolved(completed) 检查依赖。

B. 生产实现层 v3/@claude-flow/memory/

  • MemoryEntry（v3/@claude-flow/memory/src/types.ts）：含 namespace / key / value / embedding? 等字段，是 MCP 工具 memory_store / memory_search 真正传递的结构（这套被 agentdb-backend.ts / agentdb-adapter.ts 与 HNSWIndex 直接消费）。

两套并存的原因：A 用于讲清 DDD 边界，B 用于跑生产；新代码请按需选择，不要混用字段名。

  • Patterns Namespace 约定：AGENTS.md 中明确的“学习池”用法是 memory_store(namespace="patterns", ...)；该名称是社区/钩子层的约定，不是数据库层的硬约束。

5.3 状态管理 / 数据流

  • 跨进程：通过 MCP（JSON-RPC over stdio/http/ws）+ 共享 MemoryBackend 实现跨 agent 状态。
  • 跨会话：持久化数据写到 .claude-flow/；package.json.files 通过 !.claude/**/*.db 显式排除 .claude/ 下的数据库文件，避免被 npm 包带出去。
  • 跨机器：plugin-agent-federation 通过 mTLS + ed25519 构建零信任通道，PII 在出站前被剥离。

5.4 错误处理与日志

  • 统一 OutputFormatter：v3/@claude-flow/cli/src/output.ts 提供 quiet/verbose/debug 三级输出；CLI 主类在 catch 里 console.error('Fatal error:', error.message); process.exit(1)。
  • DoS 防御：MCP stdio 模式对未换行的输入设置 MCP_MAX_BUFFER_BYTES = 10 MB 上限并主动回 -32700 错误。
  • 窄域噪音过滤：log-filters.js + 入口处 _isCosmeticAgentdbPatchNoise 严格匹配 [AgentDB Patch] ... Controller index not found，避免“宽过滤遮蔽真问题”被安全审计标红。
  • 可验证发布：verification.md + verification-inventory.json 提供 “signed witness” 机制，ruflo verify 可以核对实际安装位是否与签名清单一致。

5.5 安全机制

  • AIDefence（@claude-flow/aidefence）：提示注入分类、PII 检测、越权工具调用拦截。
  • 零信任联邦：身份 = ed25519 公钥；通信 = mTLS；声誉随历史行为升降级。
  • Path Security：@claude-flow/security 内含路径穿越校验、CVE-1/2/3 修复。
  • 凭据隔离：所有密钥经环境变量传入；docker-compose.yml 的 OPENAI_API_KEY / GOOGLE_API_KEY / OPENROUTER_API_KEY 不允许提交到仓库。

6. 环境搭建与运行

6.1 前置条件

  • Node.js >= 20（engines 限制）
  • pnpm >= 8（构建 v3 monorepo 需要；v3/package.json.packageManager = "pnpm@8.15.0"）
  • 可选：Bun（v3/bunfig.toml，可通过 npm run bun:* 等脚本使用）
  • 可选：Docker / docker compose（运行 ruflo/ 下的 Web UI + MongoDB）
  • 至少一个 LLM 凭据：ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY / OPENROUTER_API_KEY

6.2 三种安装/运行方式

A) 体验官方 npm 包（最常用）

# 一行安装脚本（同 README）
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash

# 或直接用 npx（推荐先 wizard 引导）
npx ruflo@latest init --wizard

# 把 Ruflo 作为 MCP server 注册到 Claude Code
claude mcp add ruflo -- npx ruflo@latest mcp start

B) 本仓库源码运行

# 1. 安装顶层依赖
npm install

# 2. 构建 v3 monorepo（CLI 主体；v3/@claude-flow/agents 没有 build，其余 24 个子包都有）
cd v3 && pnpm install && pnpm -r build && cd ..

# 3. 直接跑顶层 CLI（顶层 bin/cli.js 仅 11 行，转发到 v3/@claude-flow/cli/bin/cli.js）
node bin/cli.js --help          # = claude-flow --help
node ruflo/bin/ruflo.js --help  # = ruflo --help（品牌薄壳）

# 4. 单独以 dev 模式跑 v3 CLI 入口（已编译产物 + 命令路由）
node v3/@claude-flow/cli/bin/cli.js --help

注意：不能用 npx tsx v3/@claude-flow/cli/src/index.ts 启动 CLI—— 该文件只 export class CLI {...}，不会自动执行 new CLI().run()；真正的引导在 v3/@claude-flow/cli/bin/cli.js（构造 CLI 实例并调用 .run()）和 ruflo/bin/ruflo.js。

package.json 顶层脚本一览（已与文件实际内容核对）：

脚本作用
npm run dev字面定义为 tsx watch src/index.ts。⚠️ 顶层并不存在 src/，直接执行会 ENOENT；该脚本是从 v3 子包模板复制过来的遗留项，实际开发时请进入 v3/ 或 v3/@claude-flow/cli/ 再跑各自的 dev 脚本。
npm run build顶层 tsc（按根 tsconfig.json 编译 v3/**/*.ts 到 dist/）
npm run build:tscd v3/@claude-flow/cli && npm run build（带 || true 兜底，失败也不会中断顶层流程）
npm test直接跑顶层 vitest。顶层无 vitest.config.*，会以默认配置在仓库内自动发现 *.test.ts*；如需 v3 完整集成套件，请改用 cd v3 && pnpm test
npm run test:securityvitest run v3/__tests__/security/
npm run security:audit / security:fix调用 npm audit / npm audit fix
npm run v3:swarm / v3:security / v3:domains转发到对应聚合脚本（start:swarm / security:audit + security:test / build:domains），其中 start:swarm、build:domains 需在 v3 子包中存在才能跑通

C) Web UI（聊天 + MCP 工具盘）

cd ruflo
cp .env.example .env               # 已确认：模板在 ruflo/.env.example；至少填一个 API Key
# 另有 ruflo/src/config/config.example.json 作为应用层配置示例（非环境变量）
npm install
npm run docker:build
npm run docker:up                  # 启动 mongodb + mcp-bridge + chat-ui + nginx
npm run docker:logs                # 跟踪日志

随后访问 http://localhost（nginx）即可使用本地版 flo.ruv.io。

6.3 关键环境变量

变量作用
ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY / OPENROUTER_API_KEYLLM 提供方密钥
MCP_GROUP_INTELLIGENCE / AGENTS / MEMORY / DEVTOOLS / SECURITY / BROWSER / NEURAL / AGENTIC_FLOW / CLAUDE_CODE / GEMINI / CODEX控制 mcp-bridge 暴露的工具组开关
PORTmcp-bridge 端口（默认 3001）
CLAUDE_FLOW_CONFIG自定义配置文件路径（默认 ./claude-flow.config.json，源码引用见 v3/@claude-flow/cli/CLAUDE.md:571、v3/@claude-flow/cli/src/init/claudemd-generator.ts:288）
CLAUDE_FLOW_LOG_LEVEL日志等级（info / debug / ...，多个 Dockerfile 默认 info）
CLAUDE_FLOW_MEMORY_BACKENDsqlite / agentdb / hybrid（v3/@claude-flow/cli/docker/Dockerfile.full:55 与 Dockerfile.full:54 默认 hybrid，对应 ADR-009）

7. 推荐学习路线

阶段 1 · 入门（半天～一天）

  1. 顺序阅读：
    • README.md（项目定位、Quick Start、能力清单）
    • docs/STATUS.md（当前真正可用的能力一览）
    • AGENTS.md（理解最重要的心智模型：Ruflo 编排，调用方执行）
    • CLAUDE.md 前 200 行（路由、并发、防漂移）
  2. 按 6.2A 跑通 npx ruflo@latest init --wizard，观察生成的 CLAUDE.md / .claude/ / .claude-flow/。
  3. 在 Claude Code 里试一条命令：/plugin install ruflo-core@ruflo，理解“插件 ≠ MCP server，CLI 安装才是完整体”。

阶段 2 · 进阶（2–3 天）

按 “由外到内” 阅读源码：

  1. 入口链路：bin/cli.js → ruflo/bin/ruflo.js → v3/@claude-flow/cli/bin/cli.js → v3/@claude-flow/cli/src/index.ts → src/commands/index.ts。
  2. 核心命令实现（任选 2–3 个）：commands/init.ts、commands/swarm.ts、commands/memory.ts、commands/mcp.ts、commands/hooks.ts。
  3. 领域实现（教学级、好读）：v3/src/index.ts → agent-lifecycle/domain/Agent.ts → task-execution/{domain,application} → coordination/application/SwarmCoordinator.ts → memory/infrastructure/HybridBackend.ts。
  4. 协议层：v3/mcp/{server,session-manager,tool-registry,connection-pool}.ts 与 v3/@claude-flow/mcp/。
  5. 学习闭环：v3/@claude-flow/hooks/ + v3/@claude-flow/neural/，配合 .claude/skills/reasoningbank-* 阅读。

阶段 3 · 实践（1 周内可做的小任务）

由小到大，按需取一两个练手即可。

  1. 加一个 CLI 子命令：在 v3/@claude-flow/cli/src/commands/ 新建 hello.ts，在 commands/index.ts 注册到 commandLoaders，确保 ruflo hello --name Aone 能跑通。
  2. 写一个最简插件：以 plugin/ 为骨架（含 agents/ commands/ skills/ 三个子目录与一个 hooks.json 文件）复制到 plugins/ruflo-myplugin/，再补一个 package.json / plugin.json 让 Claude Code 插件市场识别（参考 plugins/ruflo-core/ 的真实结构），最后用 /plugin install ruflo-myplugin@ruflo 验证。
  3. 接一个新的 MCP 工具：按 mcp-tools/ 目录的命名约定新增 echo-tools.ts（参考最简单的 system-tools.ts），在同目录 index.ts 里聚合导出，工具最终通过 ToolRegistry（v3/mcp/tool-registry.ts）注册到 server；ruflo mcp start 后用 echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node v3/@claude-flow/cli/bin/cli.js 验证返回列表里含新工具。
  4. 跑一遍学习闭环：执行一段 swarm 任务后，用 ruflo memory search --query "..." 检查 patterns namespace 是否被写入；尝试改进 post-task 钩子的写入策略。
  5. 复现“密码学见证”：阅读 scripts/inventory-capabilities.mjs / sign-witness-from-inventory.mjs，跑 ruflo verify，再故意改一个文件验证它能否检测出来。

8. 常见问题与注意事项

8.1 容易踩的坑

  • 包名混乱：仓库根目录 package.json.name = "claude-flow"，但 ruflo/package.json.name = "ruflo"，且 homepage / repository.url 仍写老名 ruvnet/claude-flow；实际 git remote 为 ruvnet/ruflo。这是有意为之（项目改名 + 兼容老用户），不要试图“统一”。
  • v2 与 v3 并存：v2/ 整套源码仍在仓库里，新代码请只动 v3。tsconfig.json 已显式 include: ["v3/**/*.ts"]。
  • MCP 模式自动判定：bin 入口都是 “stdin 是 pipe 且无 args ⇒ MCP 模式”，意味着 echo '...' | ruflo 就会被当成 MCP，而不是普通命令——调试时记得带 --help 或显式 mcp start。
  • 退出码：ruflo/bin/ruflo.js 在命令完成后强制 process.exit(0)，这是为了规避 HNSW VectorDb / sql.js / ONNX worker 把事件循环吊住的问题（issue #1641 / #1653），不要随意改。
  • plugin 与 CLI install 不是一回事：README 表格已点明，仅装 plugin 不会注册 MCP server，因此 memory_store / swarm_init 等工具调用不会生效，必须走 npx ruflo init。
  • Codex / Claude 的“执行 vs 编排”心智：AGENTS.md 反复强调，调用 swarm_init / agent_spawn 之后 必须立刻自己接着干活，否则永远不会有事情发生。
  • 冷启动时间：插件 skill 与 MCP server 启动有 30s 超时；这就是 @claude-flow/cli-core 存在的原因——别把重依赖塞进 cli-core。
  • AgentDB 噪音过滤：见到 [AgentDB Patch] Controller index not found 是 v3 兼容老 v1 patch 的提示，已经被精确过滤；其他 [AgentDB Patch] 警告不会被吞掉。

8.2 代码中的特殊约定

  • All-ESM：顶层 "type": "module"，导入扩展名必须显式 .js (import './log-filters.js')，编译后亦然。
  • 副作用导入顺序：CLI 入口的第一行必须是 import './log-filters.js';，因为 ESM 会按依赖图先评估它，从而抢在 agentdb 加载之前安装 console 过滤器。
  • 每个命令一个文件 + 集中懒加载：新增命令请同时在 commands/index.ts 的 commandLoaders 注册，并在 getLazyCommandNames() 中暴露名字（避免 daemon start 被误路由到 start，详见 issue #1596）。
  • DDD 包不能反向依赖 infrastructure：v3/src/agent-lifecycle/domain/ 不允许 import infrastructure/*。
  • 测试文件不进编译：根 tsconfig.json 显式 exclude: ["**/*.test.ts","**/*.bench.ts","v3/__tests__/**/*.ts"]，新增测试请放到 v3/__tests__/ 或 tests/。
  • 签名清单要重新生成：动到 bin/、v3/@claude-flow/*/dist/ 后必须执行 npm run security:test 与重生成 witness（scripts/regenerate-witness.mjs），否则 ruflo verify 会失败。

8.3 值得注意的 TODO / 技术债务

  • README & package.json 的旧名：根 package.json.name = "claude-flow"，homepage / repository.url / bugs.url 都仍指向 https://github.com/ruvnet/claude-flow，但实际 git remote 与 README 链接都是 ruvnet/ruflo。两个仓库目前的归属关系（是否仍是同一个 GitHub repo 的别名 / 是否分别承载 issue）需要去 GitHub 上确认；做 PR / 提 issue 前请先核对当前 alpha 版本的官方说明。
  • v2 长期保留的代价：v2/src/ 体量与 v3 相当，文档（v2/README.md 453 行、v2/CLAUDE.md）也仍在维护，存在“文档/能力错位”风险。
  • docs/USERGUIDE.md ~7600 行：单文件过大，已在 docs/index.md 切分为子页面，但权威入口仍是 USERGUIDE.md，搜索效率不高；阅读建议直接 grep 关键词。
  • 跨子项目依赖：ruflo/ 依赖 @claude-flow/cli，但顶层与 v3 又是 workspace，这意味着 本地开发要么用 npm link，要么先 pnpm publish:dry 否则 ruflo/bin/ruflo.js 中的 findCliPath() 找不到目标。
  • WASM 可选依赖：@ruvector/* 在 optionalDependencies 里，平台不匹配时静默跳过，可能导致部分高级功能（attention / router）无声地降级，调试时可加 --verbose 观察。
  • 大量 “待生产化” 插件：plugins/ 中部分目录处于 alpha（ruflo-iot-cognitum / ruflo-neural-trader / ruflo-market-data 等），生产环境引入前请逐个 review 其 package.json 与 README。

本指南基于 commit 时刻的仓库快照编写。docs/USERGUIDE.md、docs/STATUS.md、v3/implementation/adrs/ 是后续深入学习的最佳长篇资料。