Ruflo 詳細教學

本教學對應 repo commit 6d50dd8（2026-05-20，v3.7.0-alpha.72），最後驗證日 2026-05-21。 涵蓋專案定位、安裝（雙路設計）、核心架構、CLI 詳細用法、應用場景、資安、FAQ、進階技巧、整合 9 個章節，重點放在「33 個 plugin 工程模式 + lite/full 雙路安裝設計」。

1. 專案定位

1.1 是什麼

Ruflo（前名 claude-flow，npm 套件名仍是 claude-flow）是 ruvnet 主導的 Claude Code multi-agent orchestration 旗艦平台：

• 53k stars / 6k forks / 22.2M+ npm 累計下載 / 兩週 115k git clones
• 2026-05-20 仍每天 commit + 每天發 alpha release
• 一行 npx ruflo@latest init 給 Claude Code 加上：
  • 100+ 專業 agent（coder / architect / reviewer / security-architect / tester / …）
  • 33 個 native plugin（marketplace 形式）
  • Rust 引擎 + WASM 加速
  • 向量記憶（AgentDB + HNSW，比 brute force 快 150-12500×）
  • 聯邦通訊（zero-trust agent federation）
  • SONA 自學習 / ReasoningBank / trajectory learning
  • GOAP A* 規劃器

1.2 為什麼重要

1.3 與相關工具的關係

1.4 一句話總結

用 100+ agent + 33 plugin + Rust/WASM 引擎，把 Claude Code 從「單一 CLI」升級成「多 agent 協調平台」 — 重點是 33 個 plugin 是自製 Claude plugin 最豐富的參考庫。

2. 安裝指南（雙路設計）

2.1 雙路差異對照

2.2 Path A — Plugin lite（最快試）

1# 在 Claude Code 內
2/plugin marketplace add ruvnet/ruflo
3
4# 裝 core + 你要的 plugins
5/plugin install ruflo-core@ruflo
6/plugin install ruflo-swarm@ruflo
7/plugin install ruflo-rag-memory@ruflo
8/plugin install ruflo-neural-trader@ruflo

只裝 slash commands + agent 定義，Ruflo MCP server 不註冊。

2.3 Path B — CLI full

 1# macOS / Linux / WSL / Git-Bash（POSIX shell）
 2curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash
 3
 4# 全平台（含 Windows PowerShell / cmd）
 5npx ruflo@latest init wizard          # 互動式
 6npx ruflo@latest init                  # 非互動式
 7npm install -g ruflo@latest            # 全域安裝
 8
 9# 把 Ruflo 加成 MCP server
10claude mcp add ruflo -- npx ruflo@latest mcp start

install.sh 旗標：

• --global 全域安裝
• --minimal 跳過可選依賴
• --full 完整：global + MCP + doctor + init
• --version=X.X.X 指定版本

2.4 安裝流程圖

flowchart TD
    A[使用者] --> B{要 lite 還 full?}
    B -->|試單一功能
零工作區檔案| C[Path A: Plugin lite]
    B -->|完整 loop
MCP + hooks + daemon| D[Path B: CLI install]
    C --> C1[/plugin marketplace add ruvnet/ruflo/]
    C1 --> C2[/plugin install ruflo-core@ruflo/]
    C2 --> C3[+ 任選 plugin]
    C3 --> E[用 slash commands]
    D --> D1{平台}
    D1 -->|macOS/Linux/WSL| D2[curl install.sh / bash]
    D1 -->|Windows / 全平台| D3[npx ruflo@latest init wizard]
    D2 --> D4[.claude/ + .claude-flow/ + CLAUDE.md 生成]
    D3 --> D4
    D4 --> D5[claude mcp add ruflo
註冊 MCP]
    D5 --> F[完整 314 MCP 工具 + hooks + 60 commands]
    E --> G[正常用 Claude Code]
    F --> G

2.5 系統需求

2.6 常見安裝問題

3. 核心架構解析

3.1 整體架構

flowchart TB
    subgraph User["使用者層"]
        U1[Claude Code CLI]
        U2[Web UI flo.ruv.io]
        U3[Goal Planner goal.ruv.io]
    end

    subgraph Ruflo["Ruflo Platform"]
        R1[CLI ruflo init
v3/@claude-flow/cli]
        R2[MCP Server
314 tools]
        R3[Router]
        R4[Swarm Coordinator
hierarchical/mesh/adaptive]
        R5[Self-Learning Loop
SONA + ReasoningBank]
    end

    subgraph Plugins["33 Native Plugins"]
        P1[Core: core/swarm/autopilot/federation/loop-workers/workflows]
        P2[Memory: agentdb/rag-memory/rvf/ruvector/knowledge-graph]
        P3[Intelligence: intelligence/graph-intelligence/daa/ruvllm/goals]
        P4[Quality: testgen/browser/jujutsu/docs]
        P5[Security: security-audit/aidefence]
        P6[Method: adr/ddd/sparc]
        P7[Ops: migrations/observability/cost-tracker]
        P8[Ext: agent/plugin-creator]
        P9[Domain: iot-cognitum/neural-trader/market-data]
    end

    subgraph Agents["100+ Agents"]
        A1[coder/architect/reviewer/tester]
        A2[security-architect]
        A3[domain agents]
    end

    subgraph Memory["持久層"]
        M1[(AgentDB
HNSW vector)]
        M2[(Knowledge Graph)]
        M3[(rvf snapshots)]
    end

    subgraph LLM["LLM Providers"]
        L1[Claude / GPT / Gemini / Cohere / Ollama]
    end

    User --> Ruflo
    Ruflo --> Plugins
    Ruflo --> Agents
    Agents --> Memory
    Agents --> LLM
    Memory -.feed.-> R5
    R5 -.tune.-> Agents
    Ruflo -.federation.-> RemoteRuflo[其他機器的 Ruflo
zero-trust]

3.2 33 Native Plugins 分類

3.3 v3 Monorepo 結構

 1v3/
 2├── @claude-flow/                # 3 個 workspace 套件
 3│   ├── cli/                     # 主 CLI（bin: claude-flow）
 4│   ├── shared/                  # 共用 utils
 5│   └── guidance/                # 指引模組
 6├── agents/                      # YAML agent 定義（architect / coder / reviewer / security-architect / tester）
 7├── crates/                      # Rust crates（加速核心）
 8├── plugins/                     # 16 個內部 plugin
 9├── goal_ui/                     # Vite + Supabase GOAP UI（goal.ruv.io 來源）
10├── mcp/                         # MCP server 實作
11├── docs/adr/                    # ADR-001 ~ ADR-126+ 重大決策文件
12├── src/                         # TS source
13└── pnpm-workspace.yaml          # workspace 配置

3.4 Self-Learning 迴圈

sequenceDiagram
    participant U as User
    participant CC as Claude Code
    participant R as Ruflo Router
    participant S as Swarm Coordinator
    participant A as Agent
    participant M as AgentDB + HNSW
    participant L as LLM Provider
    participant SO as SONA Learning

    U->>CC: 寫 code / 提需求
    CC->>R: hook 自動觸發
    R->>M: 查 HNSW vector memory
找類似任務歷史
    M-->>R: 過去 trajectories
    R->>S: 路由到適合 swarm topology
    S->>A: 派多個 agent（並行）
    A->>L: 呼叫 LLM
    L-->>A: response
    A->>M: 寫入新 trajectory
    A->>CC: 回交結果
    A->>SO: 餵 ReasoningBank
    SO-->>R: 更新 routing 偏好
    Note over SO,R: 下次類似任務
更快、更準

3.5 為什麼 ruflo 比 raw Claude Code 強

4. CLI 詳細用法

4.1 init 與基礎指令

 1# 初始化（互動式 wizard）
 2npx ruflo@latest init wizard
 3
 4# 非互動式
 5npx ruflo@latest init
 6
 7# 啟動 MCP server（給 Claude 連）
 8npx ruflo@latest mcp start
 9
10# 整合到 Claude Code
11claude mcp add ruflo -- npx ruflo@latest mcp start

4.2 swarm 指令

1# 啟動 swarm（多 agent 並行）
2ruflo swarm init --topology hierarchical
3ruflo agent spawn --role coder
4ruflo agent spawn --role reviewer
5
6# 看 swarm 狀態
7ruflo swarm status

4.3 memory 指令

1# 寫入 vector memory
2ruflo memory store --key "decision-1" --value "use HNSW for speed"
3
4# 查詢
5ruflo memory search "vector index choice"
6
7# 匯出 / 還原
8ruflo memory export > backup.json
9ruflo memory retrieve --value-only key

4.4 goal 指令（GOAP 規劃）

1# 從 plain English 拆解成 plan
2ruflo goal plan "ship auth refactor with tests and a PR"
3# → 自動規劃 A* path + 派 agent 執行
4
5# 看 plan tree
6ruflo goal show <goal-id>

4.5 cost-tracker（觀察用量）

1ruflo cost summary               # 累計
2ruflo cost set-budget --usd 100  # 設預算
3ruflo cost alert --threshold 80  # 80% 警示

4.6 plugin 管理

1# 列已裝
2ruflo plugin list
3
4# 從 marketplace 裝
5ruflo plugin install ruflo-rag-memory
6
7# 自製 plugin（scaffold）
8ruflo plugin create my-plugin --type swarm

4.7 federation（跨機器 agent）

1# 在機器 A
2ruflo federation start --bind 0.0.0.0:7777
3
4# 在機器 B
5ruflo federation join --peer <machine-A-pubkey>@<host>:7777
6
7# 派 agent 給 peer
8ruflo federation dispatch --to <peer> --task "review code"

5. 應用場景

6. 資安掃描報告

掃描日期：2026-05-21 / 範圍：scripts/ + bin/ + v3/@claude-flow/cli/src/ + .claude-plugin/

6.1 紅黃綠燈總結

6.2 詳細發現

✅ 完整 SECURITY.md：

• 漏洞通報窗口：security@cognitum.one
• 48h ack / 7 day assessment / 30 day fix SLA
• Safe Harbor 條款
• 明列安全實踐：「Zod schemas 驗證所有 public API 輸入」+「parameterized SQL queries」+「PathValidator 模組防 path traversal」

✅ execSync / execFileSync / spawnSync 全內部用：

• 內部呼叫 git rev-parse / npm audit / npx mcp start / gh api / claude CLI
• 無使用者輸入直接拼接命令
• statusline-generator.ts 註解明確「strict 2s timeout」+「single combined call」— 有意識避免漏洞

✅ 內建安全 plugins：

• ruflo-aidefence：block prompt injection、PII detection、safety scanning
• ruflo-security-audit：CVE 掃描 + 漏洞補丁
• scripts/audit-supply-chain.mjs：跑 npm audit + 查 npm maintainers 改變（供應鏈防禦）

✅ Ed25519 backtest signing（#2071）：

• neural-trader 用密碼學簽章驗證 backtest 結果，防偽造

🟡 觀察 1：curl ... \| bash 安裝模式

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

• 業界普遍但風險：執行第三方 shell script，需信任 ruvnet + jsdelivr CDN
• 緩解：(1) 53k stars 社群監督；(2) 可選 npx ruflo init wizard 不走 curl-bash
• 建議：謹慎場域用 npx 路徑

🟡 觀察 2：alpha 版本快速迭代

• v3.7.0-alpha.72 (今天) 是 alpha 階段
• 每天 1+ release，breaking change 可能
• 生產用建議：鎖具體版本（ruflo@3.7.0-alpha.72），不要用 latest

🟡 觀察 3：#2078 案例（已修但是教訓）

• 之前 init 預設加 Co-Authored-By: ruvnet@... 到所有 user repos commits
• 引社群反彈，alpha.72 改為 opt-in（#2079）
• 教訓：自己做 Claude plugin 時，任何會改使用者 git config / commit metadata 都應預設 opt-in

6.3 結論

🟢 整體低風險 + 多重最佳實踐。 53k stars 專案有充足社群監督；ruvnet 主動寫 SECURITY.md + 內建 aidefence/security-audit/supply-chain audit + Ed25519 簽章。

使用者責任：(1) 鎖版本；(2) install.sh 內容可先讀過再執行；(3) opt-out 不需要的功能（Co-Authored-By / 自動 hook）；(4) federation 用前確認 zero-trust 設定正確。

7. FAQ

Q1: 為什麼 npm 套件名是 claude-flow，repo 名是 ruflo？ A: ruvnet 把 claude-flow rebrand 成 Ruflo（「Ru」= rUv 自己的名字、「flo」= flow state）。npm 包名為避免 breaking 沒改，repo 名先改了。

Q2: 我能只用 Claude Code 不裝這個嗎？ A: 當然可以。Ruflo 是「進階加強」，raw Claude Code 已可用。但若你經常做「多任務並行 + 跨 session 記憶」，Ruflo 顯著加速。

Q3: Lite vs Full 該選哪個？ A: 第一次試或只想要某個 plugin → Lite（不污染工作區）。要完整 loop / MCP / hooks / 跨 session memory → Full。

Q4: 33 個 plugin 都要裝嗎？ A: 不用。ruflo-core 為必須，其他依需求。常見組合：

• 基礎：core + swarm + rag-memory + intelligence
• 安全：+ aidefence + security-audit
• 觀察：+ cost-tracker + observability
• 寫 code：+ testgen + browser + jujutsu + docs

Q5: Web UI flo.ruv.io 安全嗎？ A: hosted demo 是「無 API key 試用」場景，不要送機密 prompt。要長期用建議自託管（ruflo/src/ruvocal/ 有 Dockerfile）。

Q6: GOAP 規劃器是什麼？ A: Goal-Oriented Action Planning，源自遊戲 AI。把「ship auth refactor」這種高層目標用 A* 在 state space 內搜出最短 action path。Ruflo 把它應用到軟體工作流。

Q7: 53k stars 的 alpha 版可信嗎？ A: alpha 是 ruvnet 的快速迭代策略，每天 release 但測試很完整（看 tests/ 736KB + 5 個 smoke script）。生產用記得鎖版本。

Q8: federation 真的 zero-trust 嗎？ A: 設計上是。每個 agent 用密碼學身份；agent 間通訊預設加密；workspace 隔離。但實際安全性看設定，預設可能寬鬆，請看 ruflo-federation 文件。

8. 進階技巧

8.1 自製 Claude plugin 三步走

1# 1. 用 ruflo-plugin-creator scaffold
2ruflo plugin create my-plugin --type swarm
3
4# 2. 參考 33 個 plugin 中最近的（看 plugins/ruflo-core/ 結構）
5cp -r plugins/ruflo-core /tmp/template
6# 注意 .claude-plugin/plugin.json 結構
7
8# 3. 發 plugin
9ruflo plugin publish my-plugin

8.2 把 Ruflo 接 Ollama（本地模型完全離線）

1ruflo plugin install ruflo-ruvllm
2# 設定 Ollama endpoint
3ruflo config set ruvllm.provider ollama
4ruflo config set ruvllm.endpoint http://localhost:11434
5ruflo config set ruvllm.model qwen3:8b

8.3 用 Ruflo 做生醫實驗自動化（移植到非寫程式場景）

1. 用 ruflo-plugin-creator 建 bio-experiment plugin
2. 把 agents 改成 data-puller / analyzer / reviewer
3. 用 ruflo-rag-memory 存實驗 protocol / 過往結果
4. 用 ruflo-cost-tracker 控 LLM 用量
5. 用 ruflo-aidefence 防 PHI 洩漏

8.4 學 ADR 系列文件化

1ls v3/docs/adr/      # ADR-001 ~ ADR-126+
2# 每個 ADR：context / decision / consequences
3# 套到本知識庫：每個重大決策（例如 quarkdown 選擇）都寫 ADR

8.5 學 install.sh 跨平台處理

scripts/install.sh 是「跨平台 + 多模式（global / minimal / full）+ env var override」的好範例，可參考用於本知識庫的 setup 腳本。

8.6 鎖 alpha 版本作生產

1# package.json
2"ruflo": "3.7.0-alpha.72"   # 鎖具體版本
3# 不要用
4"ruflo": "alpha"            # 滾動 alpha 危險
5"ruflo": "latest"           # 滾動 latest 危險

9. 整合進其他工作流

9.1 與本知識庫其他 Layer 配合

9.2 衍生 / 後續題目

• 本知識庫 v2 ruflo 化：把 15 個 layer 重組為 ruflo plugin marketplace

• 生醫 swarm：用 ruflo swarm 並行跑「資料分析 + 統計檢驗 + 論文校對」三 agent

• 跨團隊 federation：用 ruflo-federation 在 Apotek 內部不同團隊共享 agent

• 直接相關度低（agent orchestration vs 生醫 pipeline）

• 可借鑑：(1) plugin 切法；(2) ADR 文件化；(3) cost-tracker；(4) self-learning 迴圈設計

10. 重點摘要 Checklist

• 53k stars / 6k forks / 22.2M+ npm 下載：Claude Code 生態最大專案
• 雙路安裝：Plugin lite（slash commands only）/ CLI full（完整 MCP + hooks + daemon）
• 33 個 native plugins — 自製 Claude plugin 最完整參考
• 100+ agents + 314 MCP tools
• 多介面：CLI / MCP / Web UI / GOAP UI（每個都自託管 + hosted demo）
• 資安：🟢 低 + 多最佳實踐：SECURITY.md / Zod / PathValidator / AIDefence / supply-chain audit
• License：MIT
• 狀態：v3.7.0-alpha.72（活躍 alpha，每天 release）
• 生產用注意：鎖具體版本 / opt-out 不需要的 hook / 用 federation 前審設定

11. 進一步閱讀

本教學由 gh-tutorial-qd skill 自動生成 / 2026-05-21 / commit 6d50dd8 / v3.7.0-alpha.72。 對「自製 Claude plugin」感興趣的讀者請特別細讀 §3.2（33 plugin 分類）、§8.1（plugin scaffold）、§6.2（資安最佳實踐）。