ruflo 项目说明书 - Doramagic.ai

Doramagic 项目包 · 项目说明书

ruflo 项目

面向 Claude 的领先 Agent 元编排框架，可部署多智能体集群、编排自主工作流并构建对话式 AI 系统，具备自适应记忆、群体智能自学习、RAG 集成以及原生 Claude Code / Codex 集成能力。

Overview and System Architecture

ruflo（亦称 Claude Flow）是一个面向 AI 编码工作流的多智能体编排框架与开发工具集，旨在为 Claude Code 与 Codex 等代理运行时提供可自我学习的工程化底座。主入口 v3/@claude-flow/cli/package.json 通过统一的 exports 字段将 ruvector、mcp-tools、memory、intelligence...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述与系统架构

项目定位与核心能力

ruflo（亦称 Claude Flow）是一个面向 AI 编码工作流的多智能体编排框架与开发工具集，旨在为 Claude Code 与 Codex 等代理运行时提供可自我学习的工程化底座。主入口 v3/@claude-flow/cli/package.json 通过统一的 exports 字段将 ruvector、mcp-tools、memory、intelligence 等子能力作为独立入口发布资料来源：v3/@claude-flow/cli/package.json:1-80。在 v3 实现层面，状态汇总显示"Overall V3 Implementation: 100% Complete"，并列出 8 项 Beta 就绪检查（真实 ONNX 嵌入、真实性能指标、Claims MCP 工具、生产加固等）资料来源：v3/implementation/adrs/README.md:1-50。

框架的核心能力体现在三个层面：

双平台支持：v3/@claude-flow/codex/README.md 描述 init --codex 会自动将 MCP 服务注册到 Codex，并通过 $skill-name 语法调用 137+ 技能，同时保留对 Claude Code 的兼容。
高维向量记忆：HNSW 索引可实现 150x–12,500x 模式匹配加速，使用 384 维嵌入资料来源：v3/@claude-flow/codex/README.md:1-30。
智能诊断与补全：claude-flow doctor 检查 Node 版本、守护进程、内存数据库、API 密钥与 MCP 状态；命令解析器集成基于 Levenshtein 距离的拼写纠错资料来源：v3/implementation/adrs/README.md:1-80。

关键架构决策

V3 架构以"微内核 + 插件 + 领域驱动设计"为基础。v3/implementation/adrs/README.md 维护了一份"核心决策 + 技术决策"清单，是理解整体架构的第一手资料：

ADR-001：基于 agentic-flow@alpha 复用，避免重复实现约 10,000 行代码。
ADR-002：领域驱动设计（DDD），按有界上下文划分模块以保证边界清晰。
ADR-003：以 UnifiedSwarmCoordinator 作为唯一的群智协调引擎。
ADR-004：微内核 + 插件模式，将 HiveMind、Neural 等可选能力以插件形式挂载资料来源：v3/implementation/adrs/README.md:1-90。
ADR-005：MCP 工具作为主要 API，CLI 仅作薄包装层。
ADR-006/ADR-009：单一 MemoryService，默认采用 SQLite + AgentDB 混合后端资料来源：v3/implementation/adrs/README.md:90-150。

v3/@claude-flow/cli/package.json 的导出结构进一步印证了"薄 CLI + 子模块导出"的设计取向，子目录 @claude-flow/plugins、@claude-flow/guidance 则按职责独立打包发布资料来源：v3/@claude-flow/plugins/package.json:1-30、v3/@claude-flow/guidance/package.json:1-30。

插件生态与系统分层

ruflo 提供了一个由 20+ 插件组成的生态，覆盖从推理、文档到成本跟踪的完整工程链路：ruflo-sparc 给出五阶段方法论（规格/伪码/架构/精化/完成）并带门控标准资料来源：plugins/ruflo-sparc/README.md:1-30；ruflo-knowledge-graph 负责实体/关系抽取与路径寻优资料来源：plugins/ruflo-knowledge-graph/README.md:1-25；hyperbolic-reasoning 利用双曲嵌入建模层次结构与本体导航资料来源：v3/plugins/hyperbolic-reasoning/README.md:1-30；code-intelligence 集成 micro-hnsw-wasm、ruvector-gnn-wasm、ruvector-mincut-wasm 等 WASM 模块，提供语义搜索、克隆检测与模块切分资料来源：v3/plugins/code-intelligence/README.md:1-50；prime-radiant 在相干性、谱分析、因果推理、量子拓扑、HoTT 证明等数学基础上提供自动钩子资料来源：v3/plugins/prime-radiant/README.md:1-50；ruflo-metaharness 通过 _harness.mjs 子进程包装 metaharness CLI，统一 60s 超时与优雅降级资料来源：plugins/ruflo-metaharness/README.md:1-40；ruflo-cost-tracker 与 ruflo-docs 分别承担用量跟踪和文档生成/漂移检测职责资料来源：plugins/ruflo-cost-tracker/README.md:1-30、plugins/ruflo-docs/README.md:1-30。

下图为系统总体分层（CLI → MCP 工具 → 微内核 → 插件生态）：

graph TB
  U[开发者 / CI] --> CLI[npx claude-flow]
  CLI --> MCP[MCP 工具集]
  CLI --> SUB[子命令: swarm/memory/neural/security/deployment]
  MCP --> K{微内核}
  SUB --> K
  K --> MEM[MemoryService<br/>SQLite + AgentDB]
  K --> COORD[UnifiedSwarmCoordinator]
  K --> EMB[ONNX 384-dim 嵌入]
  K --> HK[Hooks / Event Sourcing]
  K --> PG[可插拔插件]
  PG --> SP[ruflo-sparc]
  PG --> KG[ruflo-knowledge-graph]
  PG --> CI[code-intelligence]
  PG --> MH[ruflo-metaharness]
  PG --> CT[ruflo-cost-tracker]
  PG --> DOC[ruflo-docs]

发布侧由 v3/@claude-flow/deployment/README.md 中的 ReleaseManager 与 prepareRelease 提供版本号 bump、变更日志生成、Git 标签与 NPM 发布能力资料来源：v3/@claude-flow/deployment/README.md:1-50；v3/implementation/README.md 的目录则同时维护架构评估、迁移指南、性能优化路线图与学习优化规划资料来源：v3/implementation/README.md:1-30。

已知问题与社区关注

在追踪近期发布与社区反馈时，应注意以下已被记录的风险与体验问题：

冷启动延迟：npx -y @claude-flow/cli@alpha --version 因 ONNX 模型下载无条件初始化而超过 60 秒（issues/2286）。
守护进程增殖：init.ts:424 的 daemon start & 与 PID 文件去重竞态曾在 macOS 上产生 39 个僵尸进程并触发内核恐慌，v3.12.2 通过 O_EXCL 原子锁文件修复（issues/2407）。
数据质量回归：MCP memory_store 曾持续输出 128 维 hash-fallback mock 嵌入（应为 384 维 ONNX），v3.12.3 修复（issues/2395）。
CVE 子命令占位：security cve 始终返回 "No CVE database configured"（issues/2403）。
构建产物缺失：Witness 清单显示 dist/ 缺失 95–99 项（issues/2391 / #2047）。
供应链审计：v3-ci.yml 的 "Run supply-chain audit" 任务失败（issues/2412）。
卸载体验：社区多次反馈（issues/670、#710、#694）缺乏官方卸载命令，需手动清理 .claude.json。
Alpha 期望管理：#659 指出 @alpha 标签代表"活跃开发中的代码"，而非"坏掉的代码"，用户应据此调整预期。

发布节奏上，v3.12.2/v3.12.3 集中修复了上述关键回归；v3.14.0 引入 testgen Test-Driven Repair 闭环（通过 headless claude -p），用于在自动生成测试后驱动代码修复。

Installation, Setup, Uninstallation, and Known Failure Modes

ruflo（仓库代号 claude-flow）是一个基于 @alpha 标签分发的多智能体协同框架，目前活跃版本为 v3 系列，安装入口由 npx @claude-flow/cli@alpha 提供。其安装、初始化、卸载与故障处理路径分布于多个子包中：@claude-flow/cli 负责核心 CLI，@claude-flow/codex 提供 Codex 平台双模支持，@...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述与项目范围

ruflo（仓库代号 claude-flow）是一个基于 @alpha 标签分发的多智能体协同框架，目前活跃版本为 v3 系列，安装入口由 npx @claude-flow/cli@alpha 提供。其安装、初始化、卸载与故障处理路径分布于多个子包中：@claude-flow/cli 负责核心 CLI，@claude-flow/codex 提供 Codex 平台双模支持，@claude-flow/deployment 负责发布与版本管理，@claude-flow/aidefence 提供安全防护，@claude-flow/guidance（WASM 内核）承担确定性策略执行。资料来源：v3/README.md:1-80

由于项目仍处于 alpha 阶段（社区讨论 #659 中明确说明 @alpha 标签代表"持续在公开场合构建"），安装与卸载流程既包含标准 npm 路径，也存在多项已知陷阱与社区请求的改进点（#670、#710、#694 均请求官方卸载命令）。

来源：https://github.com/ruvnet/ruflo / 项目说明书

Core Features: Agents, Swarms, Memory, and Self-Learning

Ruflo 是基于 Claude Flow V3 演化而来的多智能体编排框架，围绕四大支柱构建：智能体（Agents）、群体（Swarms）、记忆（Memory）与自学习（Self-Learning）。系统采用领域驱动设计 + 微内核插件架构，通过 Model Context Protocol（MCP）对外暴露统一接口，并使用事件溯源维护完整状态审计资料来源：v3/RE...

章节 相关页面

继续阅读本节完整说明和来源证据。

概览

Ruflo 是基于 Claude Flow V3 演化而来的多智能体编排框架，围绕四大支柱构建：智能体（Agents）、群体（Swarms）、记忆（Memory）与自学习（Self-Learning）。系统采用 领域驱动设计 + 微内核插件架构，通过 Model Context Protocol（MCP）对外暴露统一接口，并使用事件溯源维护完整状态审计资料来源：v3/README.md:1-50。包入口与导出口已在 package.json 中显式声明，包含 ./mcp-tools、./memory、./intelligence 等子路径资料来源：v3/@claude-flow/cli/package.json:1-60。

智能体与群体协调

Ruflo 的核心采用 15-Agent Hierarchical Mesh 分层网格结构，由 Queen 协调器统一指挥，下辖多个领域专家 Worker 智能体；通过事件总线实现任务分发、状态同步与故障恢复资料来源：v3/README.md:1-50。CLI 暴露 agent、swarm、memory、deploy 等命令族对运行时进行管理资料来源：v3/implementation/adrs/README.md:1-30。

在团队协作维度，teammate-plugin 通过 21 个 MCP 工具支持团队管理、teammate 生成、消息传递、计划审批、远程同步与 BMSSP 优化资料来源：v3/plugins/teammate-plugin/README.md:1-50。

群体执行遵循 SPARC 方法论，分为五个阶段：Specification → Pseudocode → Architecture → Refinement → Completion，每阶段都有 Gate 校验与对应 spawn 的智能体（researcher / planner / system-architect / coder+tester / reviewer）资料来源：plugins/ruflo-sparc/README.md:1-40。状态机如下：

stateDiagram-v2
    [*] --> Specification
    Specification --> Pseudocode: 验收标准 ≥ 3
    Pseudocode --> Architecture: 错误路径显式
    Architecture --> Refinement: 无循环依赖
    Refinement --> Completion: 覆盖率 ≥ 80%
    Completion --> [*]
    Specification --> [*]: Gate 失败
    Pseudocode --> [*]: Gate 失败
    Architecture --> [*]: Gate 失败
    Refinement --> [*]: Gate 失败

记忆系统

Ruflo 记忆层采用 混合后端（Hybrid Backend）：SQLite 负责结构化存储，AgentDB 提供 HNSW 向量索引，二者协同实现 150x–12,500x 的检索加速资料来源：v3/README.md:20-40。向量化默认采用 384 维嵌入（如 all-MiniLM-L6-v2），配合 HNSW 索引完成语义模式匹配资料来源：v3/@claude-flow/codex/README.md:1-30。

需要注意的是，社区曾报告 memory_store 持续返回 128 维 mock 嵌入的问题——根因是 AgentDB vectorBackend 控制器初始化为 enabled: false 且从不切换，3.12.3 版本通过强制启用 ONNX 路径予以修复资料来源：release v3.12.3。

Ruflo 同时提供两类结构化记忆扩展：

知识图谱：kg-extract 抽取实体与关系，kg-traverse 基于 pathfinder 算法按边权与语义相似度评分路径资料来源：plugins/ruflo-knowledge-graph/README.md:1-30。
双曲推理：利用负曲率嵌入建模深层层级（如 taxonomy），并由 SONA 自适应曲率资料来源：v3/plugins/hyperbolic-reasoning/README.md:1-30。

自学习

自学习通过 SONA（Self-Optimizing Neural Architecture）与 ReasoningBank 两条互补路径实现：

SONA：在任务执行后训练模式（pattern），并与双曲推理自适应集成，使 137+ 技能在调用时能够即时调优资料来源：v3/@claude-flow/codex/README.md:1-30。
ReasoningBank：沉淀成功经验并支持向量检索，让 AIDefence 等模块可在 <0.1ms 延迟内复用新捕获的攻击模式，从而防御零日变体资料来源：v3/@claude-flow/aidefence/README.md:1-30。

Ruvector 插件将上述能力以命令族方式对外暴露：/vector sona（train、export、stats）、/vector brain（drift、partition、sync）以及 /vector llm（embed、benchmark）资料来源：plugins/ruflo-ruvector/README.md:1-60。ruflo-graph-intelligence 则基于 PageRank 与 sublinear 复杂度实现个性化图排序，为自学习提供图级别的反馈信号资料来源：plugins/ruflo-graph-intelligence/package.json:1-20。

Plugin Marketplace, MCP Tools, and Extensibility

ruflo（即 claude-flow）项目在 v3 中采用微内核（microkernel）+ 领域驱动设计（DDD）的插件架构，将系统拆分为一个轻量级核心与一组可按需装载的领域插件。插件既是 CLI 子命令的承载者，也是 MCP（Model Context Protocol）工具与 Skills 的注册点，使用户能够针对代码智能、医疗临床、SPARC 方法论、文档生成...

章节 相关页面

继续阅读本节完整说明和来源证据。

插件市场、MCP 工具与可扩展性

概述

ruflo（即 claude-flow）项目在 v3 中采用 微内核（microkernel）+ 领域驱动设计（DDD） 的插件架构，将系统拆分为一个轻量级核心与一组可按需装载的领域插件。插件既是 CLI 子命令的承载者，也是 MCP（Model Context Protocol）工具与 Skills 的注册点，使用户能够针对代码智能、医疗临床、SPARC 方法论、文档生成、成本追踪等垂直场景进行组合扩展。

资料来源：v3/implementation/plugins/README.md:1-20

插件通过 ClaudeFlowPlugin 接口接入，并由 Plugin Loader / Plugin Registry 管理生命周期、依赖解析、健康检查与扩展点注册。CLI 主包 @claude-flow/cli 通过 exports 字段向插件暴露 ruvector、mcp-tools、memory、intelligence 等子模块作为扩展依赖。

资料来源：v3/@claude-flow/cli/package.json:30-58

插件系统架构

v3 插件系统由三层组成：

graph TD
  A[Plugin Loader] --> B[Plugin Registry]
  B --> C[Agent Types]
  B --> D[Task Types]
  B --> E[MCP Tools]
  B --> F[CLI Commands]
  B --> G[Memory Backends]
  A -->|依赖解析| H[Lifecycle Manager]
  A -->|健康检查| I[Health Check]

Plugin Loader：负责依赖解析、生命周期管理、健康检查。
Plugin Registry：跟踪已注册插件、记录扩展点、收集状态与指标。
Plugin Extensions：在 Agent / Task / MCP Tool / CLI Command / Memory Backend 五个维度上注册新能力。

资料来源：v3/implementation/plugins/README.md:13-49

插件实现需实现 initialize(context) 与 shutdown() 两个生命周期钩子，并可通过 PluginContext.logger 进行结构化日志输出。该 SDK 自身发布为独立的 npm 包 @claude-flow/plugins。

资料来源：v3/@claude-flow/plugins/package.json

MCP 工具与 Skills

@claude-flow/mcp 包为插件提供 MCP 2025-11-25 规范的 tools、resources、prompts 三大能力。资源可通过 createTextResource 或 resourceRegistry.registerResource 注册自定义 URI 与处理函数，并通过 subscribe 监听更新。

资料来源：v3/@claude-flow/mcp/README.md

在 Codex 集成路径下，init --codex 会自动将 MCP 服务器注册到 Codex：

# 验证 MCP 注册
codex mcp list
# 预期输出：claude-flow  npx  claude-flow mcp start  enabled

资料来源：v3/@claude-flow/codex/README.md

插件可通过 MCP 暴露语义搜索类工具，例如 memory_search（任务开始前调用）以访问 384 维向量嵌入与 HNSW 索引。

资料来源：v3/@claude-flow/codex/README.md、v3/@claude-flow/cli/package.json:30-58

插件市场与典型扩展

/plugin marketplace add ruvnet/ruflo + /plugin install <name>@ruflo 是当前推荐的安装方式。社区中已落地的典型插件包括：

插件	核心能力	依赖 / 配套
`ruflo-sparc`	5 阶段 SPARC 流程（spec → pseudo → arch → refine → complete）	依赖 `ruflo-core`，CLI 钉到 `@claude-flow/cli` v3.6+
`plugin-code-intelligence`	语义代码搜索、克隆检测、依赖图分析、增量编译	`micro-hnsw-wasm`、`ruvector-gnn-wasm`、`sona`
`ruflo-docs`	自动生成 API 文档、漂移检测、文档后台 worker	依赖 `ruflo-core` 提供 MCP
`ruflo-metaharness`	群体式 harness 自评估，通过 `_harness.mjs` 子进程包装	子进程 60s 硬超时 + `--json` 强制结构化
`ruflo-cost-tracker`	20 条 cost 子命令、预算/趋势/对账、ADR-097 联邦消费	读取 `cost-tracking` 持久化层
`plugin-prime-radiant`	谱分析、因果推理、量子拓扑、HoTT 证明	WASM 后端 + `claude-flow.config.yaml` 阈值
`plugin-gastown-bridge`	多代理 TOML 桥接	依赖 `@claude-flow/memory`（可选）
`plugin-healthcare-clinical`	临床场景领域插件	可选 `micro-hnsw-wasm` 等 WASM 推理
`ruflo-arena`	锦标赛与协同演化实验	与 `vitest` 集成

资料来源：plugins/ruflo-sparc/README.md、v3/plugins/code-intelligence/README.md、plugins/ruflo-docs/README.md、plugins/ruflo-metaharness/README.md、plugins/ruflo-cost-tracker/README.md、v3/plugins/prime-radiant/README.md、v3/plugins/gastown-bridge/package.json、v3/plugins/healthcare-clinical/package.json、plugins/ruflo-arena/package.json

ruflo-sparc 5 个阶段使用不同的 agent 角色与门禁标准，例如阶段 1（Specification）需 ≥3 条验收准则、约束与边界用例，由 researcher 代理承担。

资料来源：plugins/ruflo-sparc/README.md

配置、发行与已知限制

插件配置通常落在 claude-flow.config.yaml 中，例如 prime-radiant 可设置相干性阈值、谱稳定性阈值、最大矩阵尺寸等。

资料来源：v3/plugins/prime-radiant/README.md

发布流水线由 @claude-flow/deployment 提供：包括版本号 bump、变更日志生成、Git 标签、预发布校验（lint/test/build/依赖检查）以及 dry-run 模式。

资料来源：v3/@claude-flow/deployment/README.md

社区已经记录到若干与扩展性相关的真实故障模式（v3.12.2 / v3.12.3 已修复部分）：

CLI 冷启动挂起（#2286）：冷安装下 npx -y @claude-flow/cli@alpha --version 因无条件初始化 ONNX embedder 超过 60 秒。
MCP 128 维 mock 嵌入（#2395 → v3.12.3）：MCP memory_store 持久输出 128 维哈希回退嵌入，因 vectorBackend 控制器始终未启用。v3.12.3 已修复，确保 MCP 路径输出真实的 384 维 ONNX 嵌入。
Daemon 扩散 / 内核恐慌（#2407 → v3.12.2）：init.ts:424 的 daemon start & 与 PID 文件去重竞争，在 macOS 上产生 39 个僵尸进程。v3.12.2 引入原子 O_EXCL 锁文件并去除 & 后台调用，5 路并发仅剩 1 个守护进程。
缺失构建产物（#2047 / #2391）：见证清单报告 macOS / Linux / Windows 三平台 missing=95 且 dist/ 不存在，签名本身有效但编译产物未就绪。
v3-ci 供应链审计失败（#2412）：主分支的 Run supply-chain audit 任务失败。

资料来源：v3/implementation/adrs/README.md 及上述 v3.12.2 / v3.12.3 发布说明。

对于计划接入或升级的开发者，建议：（1）使用 ruflo doctor 做环境体检；（2）在 CI 中启用 witness manifest 校验；（3）升级至 v3.12.3+ 以获得 MCP 嵌入修复与 daemon 锁文件修复。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 失败模式：security_permissions: ADR-153 — Integrate @metaharness/darwin (Darwin Mode) into ruflo

Developers may expose sensitive permissions or credentials: ADR-153 — Integrate @metaharness/darwin (Darwin Mode) into ruflo

high 失败模式：security_permissions: security cve subcommand is a stub — never returns CVE data (scan already does, via npm audit)

Developers may expose sensitive permissions or credentials: security cve subcommand is a stub — never returns CVE data (scan already does, via npm audit)

high 来源证据：[verification] HIGH: @claude-flow/cli@alpha --version hangs >60s on cold install (ONNX model download on every startup)

可能影响授权、密钥配置或安全边界。

high 来源证据：[verification] HIGH: v3-ci.yml on main is FAILURE — supply-chain audit job failing

可能增加新用户试用和生产接入成本。

Pitfall Log / 踩坑日志

项目：ruvnet/ruflo

摘要：发现 39 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: ADR-153 — Integrate @metaharness/darwin (Darwin Mode) into ruflo。

1. 安全/权限坑 · 失败模式：security_permissions: ADR-153 — Integrate @metaharness/darwin (Darwin Mode) into ruflo

严重度：high
证据强度：source_linked
发现：Developers should check this security_permissions risk before relying on the project: ADR-153 — Integrate @metaharness/darwin (Darwin Mode) into ruflo
对用户的影响：Developers may expose sensitive permissions or credentials: ADR-153 — Integrate @metaharness/darwin (Darwin Mode) into ruflo
证据：failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2409 | ADR-153 — Integrate @metaharness/darwin (Darwin Mode) into ruflo

2. 安全/权限坑 · 失败模式：security_permissions: security cve subcommand is a stub — never returns CVE data (scan already does, via npm audit)

严重度：high
证据强度：source_linked
发现：Developers should check this security_permissions risk before relying on the project: security cve subcommand is a stub — never returns CVE data (scan already does, via npm audit)
对用户的影响：Developers may expose sensitive permissions or credentials: security cve subcommand is a stub — never returns CVE data (scan already does, via npm audit)
证据：failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2403 | security cve subcommand is a stub — never returns CVE data (scan already does, via npm audit)

3. 安全/权限坑 · 来源证据：[verification] HIGH: @claude-flow/cli@alpha --version hangs >60s on cold install (ONNX model download on every startup)

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[verification] HIGH: @claude-flow/cli@alpha --version hangs >60s on cold install (ONNX model download on every startup)
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/ruvnet/ruflo/issues/2286 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 安全/权限坑 · 来源证据：[verification] HIGH: v3-ci.yml on main is FAILURE — supply-chain audit job failing

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[verification] HIGH: v3-ci.yml on main is FAILURE — supply-chain audit job failing
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/ruvnet/ruflo/issues/2412 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

5. 安全/权限坑 · 来源证据：[verification] HIGH: witness manifests report missing=95 drift=2 on all three platforms

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[verification] HIGH: witness manifests report missing=95 drift=2 on all three platforms
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/ruvnet/ruflo/issues/2047 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

6. 安全/权限坑 · 来源证据：[verification] MEDIUM: witness verify blocked — @noble/ed25519 not installed in source-only checkout

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[verification] MEDIUM: witness verify blocked — @noble/ed25519 not installed in source-only checkout
对用户的影响：可能阻塞安装或首次运行。
证据：community_evidence:github | https://github.com/ruvnet/ruflo/issues/2313 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

7. 安装坑 · 失败模式：installation: [verification] HIGH: @claude-flow/cli@alpha --version hangs >60s on cold install (ONNX model...

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: [verification] HIGH: @claude-flow/cli@alpha --version hangs >60s on cold install (ONNX model download on every startup)
对用户的影响：Developers may fail before the first successful local run: [verification] HIGH: @claude-flow/cli@alpha --version hangs >60s on cold install (ONNX model download on every startup)
证据：failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2286 | [verification] HIGH: @claude-flow/cli@alpha --version hangs >60s on cold install (ONNX model download on every startup)

8. 安装坑 · 失败模式：installation: [verification] HIGH: Witness manifests report 95–99 missing build artifacts (dist/ absent)

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: [verification] HIGH: Witness manifests report 95–99 missing build artifacts (dist/ absent)
对用户的影响：Developers may fail before the first successful local run: [verification] HIGH: Witness manifests report 95–99 missing build artifacts (dist/ absent)
证据：failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2391 | [verification] HIGH: Witness manifests report 95–99 missing build artifacts (dist/ absent)

9. 安装坑 · 失败模式：installation: [verification] HIGH: witness manifests report missing=95 drift=2 on all three platforms

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: [verification] HIGH: witness manifests report missing=95 drift=2 on all three platforms
对用户的影响：Developers may fail before the first successful local run: [verification] HIGH: witness manifests report missing=95 drift=2 on all three platforms
证据：failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2047 | [verification] HIGH: witness manifests report missing=95 drift=2 on all three platforms

10. 安装坑 · 失败模式：installation: memory_store emits 128-dim mock embeddings — AgentDB vectorBackend controller never enables

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: memory_store emits 128-dim mock embeddings — AgentDB vectorBackend controller never enables
对用户的影响：Developers may fail before the first successful local run: memory_store emits 128-dim mock embeddings — AgentDB vectorBackend controller never enables
证据：failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2395 | memory_store emits 128-dim mock embeddings — AgentDB vectorBackend controller never enables

11. 安装坑 · 失败模式：installation: v3.10.43 — Fable 5 / Opus 4.x temperature fix, daemon TTL, federation cap

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v3.10.43 — Fable 5 / Opus 4.x temperature fix, daemon TTL, federation cap
对用户的影响：Upgrade or migration may change expected behavior: v3.10.43 — Fable 5 / Opus 4.x temperature fix, daemon TTL, federation cap
证据：failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.10.43 | v3.10.43 — Fable 5 / Opus 4.x temperature fix, daemon TTL, federation cap

12. 安装坑 · 失败模式：installation: v3.10.44 — CI OOM fix, Windows plugin install

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v3.10.44 — CI OOM fix, Windows plugin install
对用户的影响：Upgrade or migration may change expected behavior: v3.10.44 — CI OOM fix, Windows plugin install
证据：failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.10.44 | v3.10.44 — CI OOM fix, Windows plugin install

13. 安装坑 · 失败模式：installation: v3.10.45 — hive-mind --dangerously-skip-permissions deny clause

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v3.10.45 — hive-mind --dangerously-skip-permissions deny clause
对用户的影响：Upgrade or migration may change expected behavior: v3.10.45 — hive-mind --dangerously-skip-permissions deny clause
证据：failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.10.45 | v3.10.45 — hive-mind --dangerously-skip-permissions deny clause

14. 安装坑 · 失败模式：installation: v3.10.46 — stale claude-flow@v3alpha references swept (@dskarasev community batch)

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v3.10.46 — stale claude-flow@v3alpha references swept (@dskarasev community batch)
对用户的影响：Upgrade or migration may change expected behavior: v3.10.46 — stale claude-flow@v3alpha references swept (@dskarasev community batch)
证据：failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.10.46 | v3.10.46 — stale claude-flow@v3alpha references swept (@dskarasev community batch)

15. 安装坑 · 失败模式：installation: v3.11.0 — router ADR-148/149 + cost-tracker observability + fleet audits

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v3.11.0 — router ADR-148/149 + cost-tracker observability + fleet audits
对用户的影响：Upgrade or migration may change expected behavior: v3.11.0 — router ADR-148/149 + cost-tracker observability + fleet audits
证据：failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.11.0 | v3.11.0 — router ADR-148/149 + cost-tracker observability + fleet audits

16. 安装坑 · 失败模式：installation: v3.12.0 — ADR-150 metaharness deep integration

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v3.12.0 — ADR-150 metaharness deep integration
对用户的影响：Upgrade or migration may change expected behavior: v3.12.0 — ADR-150 metaharness deep integration
证据：failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.12.0 | v3.12.0 — ADR-150 metaharness deep integration

17. 安装坑 · 失败模式：installation: v3.12.1 — bundle metaharness plugin scripts

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v3.12.1 — bundle metaharness plugin scripts
对用户的影响：Upgrade or migration may change expected behavior: v3.12.1 — bundle metaharness plugin scripts
证据：failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.12.1 | v3.12.1 — bundle metaharness plugin scripts

18. 安装坑 · 失败模式：installation: v3.12.2 — kernel-panic fix + cve subcommand fix + hooks hardening

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v3.12.2 — kernel-panic fix + cve subcommand fix + hooks hardening
对用户的影响：Upgrade or migration may change expected behavior: v3.12.2 — kernel-panic fix + cve subcommand fix + hooks hardening
证据：failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.12.2 | v3.12.2 — kernel-panic fix + cve subcommand fix + hooks hardening

19. 安装坑 · 失败模式：installation: v3.12.3 — #2395 fix: MCP no longer emits 128-dim mock embeddings

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v3.12.3 — #2395 fix: MCP no longer emits 128-dim mock embeddings
对用户的影响：Upgrade or migration may change expected behavior: v3.12.3 — #2395 fix: MCP no longer emits 128-dim mock embeddings
证据：failure_mode_cluster:github_release | https://github.com/ruvnet/ruflo/releases/tag/v3.12.3 | v3.12.3 — #2395 fix: MCP no longer emits 128-dim mock embeddings

20. 安装坑 · 来源证据：ADR-153 — Integrate @metaharness/darwin (Darwin Mode) into ruflo

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ADR-153 — Integrate @metaharness/darwin (Darwin Mode) into ruflo
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/ruvnet/ruflo/issues/2409 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

21. 安装坑 · 来源证据：Default statusline/hooks use `npx @claude-flow/cli@latest` on high-frequency events → runaway Node processes, jetsam ki…

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Default statusline/hooks use npx @claude-flow/cli@latest on high-frequency events → runaway Node processes, jetsam kills, kernel panic
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/ruvnet/ruflo/issues/2448 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

22. 安装坑 · 来源证据：MCP stdio tools/list response exceeds macOS 64KB pipe buffer, causing tool registration failure

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MCP stdio tools/list response exceeds macOS 64KB pipe buffer, causing tool registration failure
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/ruvnet/ruflo/issues/2426 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

23. 安装坑 · 来源证据：Regression (ADR-130): graph-edge-writer.js sql.js writer corrupts memory.db on agentdb_causal-edge — reintroduces the d…

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Regression (ADR-130): graph-edge-writer.js sql.js writer corrupts memory.db on agentdb_causal-edge — reintroduces the dual-write ADR-068 removed (#1257)
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/ruvnet/ruflo/issues/2431 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

24. 安装坑 · 来源证据：Unbounded native memory leak: orphaned sql.js MEMFS `dbfile_*` files (~11 MB each) accumulate per database open

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Unbounded native memory leak: orphaned sql.js MEMFS dbfile_* files (~11 MB each) accumulate per database open
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/ruvnet/ruflo/issues/2432 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

25. 安装坑 · 来源证据：[verification] HIGH: Witness manifests report 95–99 missing build artifacts (dist/ absent)

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[verification] HIGH: Witness manifests report 95–99 missing build artifacts (dist/ absent)
对用户的影响：可能阻塞安装或首次运行。
证据：community_evidence:github | https://github.com/ruvnet/ruflo/issues/2391 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

26. 安装坑 · 来源证据：[verification] HIGH: v3-ci.yml on main is FAILURE — supply-chain audit job failing

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[verification] HIGH: v3-ci.yml on main is FAILURE — supply-chain audit job failing
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/ruvnet/ruflo/issues/2412 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

27. 安装坑 · 来源证据：[verification] MEDIUM: doctor reports MetaHarness ADR-150 integration failure — plugins/ruflo-metaharness/ not found

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[verification] MEDIUM: doctor reports MetaHarness ADR-150 integration failure — plugins/ruflo-metaharness/ not found
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/ruvnet/ruflo/issues/2437 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

28. 安装坑 · 来源证据：memory_store emits 128-dim mock embeddings — AgentDB vectorBackend controller never enables

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：memory_store emits 128-dim mock embeddings — AgentDB vectorBackend controller never enables
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/ruvnet/ruflo/issues/2395 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

29. 配置坑 · 可能修改宿主 AI 配置

严重度：medium
证据强度：source_linked
发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
证据：capability.host_targets | https://github.com/ruvnet/ruflo | host_targets=claude_code, claude

30. 配置坑 · 失败模式：configuration: [BUG] daemon proliferation: `init.ts:424` spawns `daemon start &` racing the PID-file dedup →...

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: [BUG] daemon proliferation: init.ts:424 spawns daemon start & racing the PID-file dedup → kernel panic on macOS
对用户的影响：Developers may misconfigure credentials, environment, or host setup: [BUG] daemon proliferation: init.ts:424 spawns daemon start & racing the PID-file dedup → kernel panic on macOS
证据：failure_mode_cluster:github_issue | https://github.com/ruvnet/ruflo/issues/2407 | [BUG] daemon proliferation: init.ts:424 spawns daemon start & racing the PID-file dedup → kernel panic on macOS

31. 配置坑 · 来源证据：statusLine: hooks statusline loads ONNX model on every call (~1s), causes Claude Code to timeout and hide the status bar

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：statusLine: hooks statusline loads ONNX model on every call (~1s), causes Claude Code to timeout and hide the status bar
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/ruvnet/ruflo/issues/2450 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

32. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
证据：capability.assumptions | https://github.com/ruvnet/ruflo | README/documentation is current enough for a first validation pass.

33. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | https://github.com/ruvnet/ruflo | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | https://github.com/ruvnet/ruflo | no_demo; severity=medium

35. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | https://github.com/ruvnet/ruflo | no_demo; severity=medium

36. 安全/权限坑 · 来源证据：[Dream Cycle 2026-06-18] memory: bi-temporal HNSW gap +10.4pp LongMemEval_S (Engram) + OPD-Evolver beats ReasoningBank…

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Dream Cycle 2026-06-18] memory: bi-temporal HNSW gap +10.4pp LongMemEval_S (Engram) + OPD-Evolver beats ReasoningBank 11.5%; ADR-161 + plugins,automation scan
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/ruvnet/ruflo/issues/2410 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

37. 安全/权限坑 · 来源证据：[Dream Cycle 2026-06-23] memory: semantic drift from repeated summarization cycles — AgentDB has no governance layer +…

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Dream Cycle 2026-06-23] memory: semantic drift from repeated summarization cycles — AgentDB has no governance layer + plugins,automation scan
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/ruvnet/ruflo/issues/2452 | 来源类型 github_issue 暴露的待验证使用条件。

38. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | https://github.com/ruvnet/ruflo | issue_or_pr_quality=unknown

39. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | https://github.com/ruvnet/ruflo | release_recency=unknown

来源：Doramagic 发现、验证与编译记录

ruflo 项目

Overview and System Architecture

概述与系统架构

项目定位与核心能力

关键架构决策

插件生态与系统分层

已知问题与社区关注

See Also

Installation, Setup, Uninstallation, and Known Failure Modes

概述与项目范围

Core Features: Agents, Swarms, Memory, and Self-Learning

概览

智能体与群体协调

记忆系统

自学习

See Also

Plugin Marketplace, MCP Tools, and Extensibility

插件市场、MCP 工具与可扩展性

概述

插件系统架构

MCP 工具与 Skills

插件市场与典型扩展

配置、发行与已知限制

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

1. 安全/权限坑 · 失败模式：security_permissions: ADR-153 — Integrate @metaharness/darwin (Darwin Mode) into ruflo

2. 安全/权限坑 · 失败模式：security_permissions: security cve subcommand is a stub — never returns CVE data (scan already does, via npm audit)

3. 安全/权限坑 · 来源证据：[verification] HIGH: @claude-flow/cli@alpha --version hangs >60s on cold install (ONNX model download on every startup)

4. 安全/权限坑 · 来源证据：[verification] HIGH: v3-ci.yml on main is FAILURE — supply-chain audit job failing

5. 安全/权限坑 · 来源证据：[verification] HIGH: witness manifests report missing=95 drift=2 on all three platforms

6. 安全/权限坑 · 来源证据：[verification] MEDIUM: witness verify blocked — @noble/ed25519 not installed in source-only checkout

7. 安装坑 · 失败模式：installation: [verification] HIGH: @claude-flow/cli@alpha --version hangs >60s on cold install (ONNX model...

8. 安装坑 · 失败模式：installation: [verification] HIGH: Witness manifests report 95–99 missing build artifacts (dist/ absent)

9. 安装坑 · 失败模式：installation: [verification] HIGH: witness manifests report missing=95 drift=2 on all three platforms

10. 安装坑 · 失败模式：installation: memory_store emits 128-dim mock embeddings — AgentDB vectorBackend controller never enables

11. 安装坑 · 失败模式：installation: v3.10.43 — Fable 5 / Opus 4.x temperature fix, daemon TTL, federation cap

12. 安装坑 · 失败模式：installation: v3.10.44 — CI OOM fix, Windows plugin install

13. 安装坑 · 失败模式：installation: v3.10.45 — hive-mind --dangerously-skip-permissions deny clause

14. 安装坑 · 失败模式：installation: v3.10.46 — stale claude-flow@v3alpha references swept (@dskarasev community batch)

15. 安装坑 · 失败模式：installation: v3.11.0 — router ADR-148/149 + cost-tracker observability + fleet audits

16. 安装坑 · 失败模式：installation: v3.12.0 — ADR-150 metaharness deep integration

17. 安装坑 · 失败模式：installation: v3.12.1 — bundle metaharness plugin scripts

18. 安装坑 · 失败模式：installation: v3.12.2 — kernel-panic fix + cve subcommand fix + hooks hardening

19. 安装坑 · 失败模式：installation: v3.12.3 — #2395 fix: MCP no longer emits 128-dim mock embeddings

20. 安装坑 · 来源证据：ADR-153 — Integrate @metaharness/darwin (Darwin Mode) into ruflo

21. 安装坑 · 来源证据：Default statusline/hooks use `npx @claude-flow/cli@latest` on high-frequency events → runaway Node processes, jetsam ki…

22. 安装坑 · 来源证据：MCP stdio tools/list response exceeds macOS 64KB pipe buffer, causing tool registration failure

23. 安装坑 · 来源证据：Regression (ADR-130): graph-edge-writer.js sql.js writer corrupts memory.db on agentdb_causal-edge — reintroduces the d…

24. 安装坑 · 来源证据：Unbounded native memory leak: orphaned sql.js MEMFS `dbfile_*` files (~11 MB each) accumulate per database open

25. 安装坑 · 来源证据：[verification] HIGH: Witness manifests report 95–99 missing build artifacts (dist/ absent)

26. 安装坑 · 来源证据：[verification] HIGH: v3-ci.yml on main is FAILURE — supply-chain audit job failing

27. 安装坑 · 来源证据：[verification] MEDIUM: doctor reports MetaHarness ADR-150 integration failure — plugins/ruflo-metaharness/ not found

28. 安装坑 · 来源证据：memory_store emits 128-dim mock embeddings — AgentDB vectorBackend controller never enables

29. 配置坑 · 可能修改宿主 AI 配置

30. 配置坑 · 失败模式：configuration: [BUG] daemon proliferation: `init.ts:424` spawns `daemon start &` racing the PID-file dedup →...

31. 配置坑 · 来源证据：statusLine: hooks statusline loads ONNX model on every call (~1s), causes Claude Code to timeout and hide the status bar

32. 能力坑 · 能力判断依赖假设

33. 维护坑 · 维护活跃度未知

35. 安全/权限坑 · 存在评分风险

36. 安全/权限坑 · 来源证据：[Dream Cycle 2026-06-18] memory: bi-temporal HNSW gap +10.4pp LongMemEval_S (Engram) + OPD-Evolver beats ReasoningBank…

37. 安全/权限坑 · 来源证据：[Dream Cycle 2026-06-23] memory: semantic drift from repeated summarization cycles — AgentDB has no governance layer +…

38. 维护坑 · issue/PR 响应质量未知

39. 维护坑 · 发布节奏不明确