# https://github.com/ruvnet/ruflo 项目说明书
生成时间：2026-06-23 11:25:34 UTC
## 目录
- [Overview and System Architecture](#page-1)
- [Installation, Setup, Uninstallation, and Known Failure Modes](#page-2)
- [Core Features: Agents, Swarms, Memory, and Self-Learning](#page-3)
- [Plugin Marketplace, MCP Tools, and Extensibility](#page-4)
## Overview and System Architecture
### 相关页面
相关主题：[Installation, Setup, Uninstallation, and Known Failure Modes](#page-2), [Core Features: Agents, Swarms, Memory, and Self-Learning](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [v3/implementation/adrs/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/adrs/README.md)
- [v3/implementation/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/README.md)
- [v3/@claude-flow/cli/package.json](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/cli/package.json)
- [v3/@claude-flow/codex/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/codex/README.md)
- [v3/@claude-flow/plugins/package.json](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/plugins/package.json)
- [v3/@claude-flow/guidance/package.json](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/guidance/package.json)
- [v3/@claude-flow/deployment/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/deployment/README.md)
- [v3/plugins/code-intelligence/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/code-intelligence/README.md)
- [v3/plugins/hyperbolic-reasoning/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/hyperbolic-reasoning/README.md)
- [v3/plugins/prime-radiant/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/prime-radiant/README.md)
- [plugins/ruflo-sparc/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-sparc/README.md)
- [plugins/ruflo-knowledge-graph/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-knowledge-graph/README.md)
- [plugins/ruflo-metaharness/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-metaharness/README.md)
- [plugins/ruflo-cost-tracker/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-cost-tracker/README.md)
- [plugins/ruflo-docs/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-docs/README.md)
# 概述与系统架构
## 项目定位与核心能力
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 工具 → 微内核 → 插件生态）：
```mermaid
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
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`），用于在自动生成测试后驱动代码修复。
## See Also
- 架构决策记录索引：[v3/implementation/adrs/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/adrs/README.md)
- V3 实施文档目录：[v3/implementation/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/README.md)
- Codex 集成说明：[v3/@claude-flow/codex/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/codex/README.md)
- CLI 包元数据：[v3/@claude-flow/cli/package.json](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/cli/package.json)
- 代码智能插件：[v3/plugins/code-intelligence/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/code-intelligence/README.md)
- SPARC 方法论插件：[plugins/ruflo-sparc/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-sparc/README.md)
- 知识图谱插件：[plugins/ruflo-knowledge-graph/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-knowledge-graph/README.md)
- 部署与发布包：[v3/@claude-flow/deployment/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/deployment/README.md)
- 成本跟踪插件：[plugins/ruflo-cost-tracker/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-cost-tracker/README.md)
---
## Installation, Setup, Uninstallation, and Known Failure Modes
### 相关页面
相关主题：[Overview and System Architecture](#page-1), [Plugin Marketplace, MCP Tools, and Extensibility](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [v3/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/README.md)
- [v3/@claude-flow/codex/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/codex/README.md)
- [v3/@claude-flow/deployment/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/deployment/README.md)
- [v3/@claude-flow/aidefence/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/aidefence/README.md)
- [v3/implementation/adrs/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/adrs/README.md)
- [v3/plugins/code-intelligence/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/code-intelligence/README.md)
- [plugins/ruflo-docs/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-docs/README.md)
- [plugins/ruflo-metaharness/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-metaharness/README.md)
# 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 平台双模支持，`@claude-flow/deployment` 负责发布与版本管理，`@claude-flow/aidefence` 提供安全防护，`@claude-flow/guidance`（WASM 内核）承担确定性策略执行。资料来源：[v3/README.md:1-80]()
由于项目仍处于 alpha 阶段（社区讨论 #659 中明确说明 `@alpha` 标签代表"持续在公开场合构建"），安装与卸载流程既包含标准 npm 路径，也存在多项已知陷阱与社区请求的改进点（#670、#710、#694 均请求官方卸载命令）。
---
## 安装与初始化
### 通过 npx 直接调用
最简安装方式无需全局注册，直接通过 `npx` 拉取并执行：
```bash
npx -y @claude-flow/cli@alpha --version
```
但需注意：**冷启动时 CLI 会无条件初始化 ONNX embedder**，导致 `--version` 等轻量子命令也可能挂起超过 60 秒（社区问题 #2286）。建议在受限网络或 CI 环境下预先下载 ONNX 模型缓存，或在初始化前禁用向量后端。
### Codex 双模式初始化
`@claude-flow/codex` 包支持 Claude Code 与 OpenAI Codex 双平台初始化，安装时 MCP 服务器会自动注册。资料来源：[v3/@claude-flow/codex/README.md:1-60]()
```bash
# 基础初始化
npx @claude-flow/codex init --template full --force
# 双模式（Claude Code + Codex）
npx @claude-flow/codex init --dual
```
初始化结果会返回 `CodexInitResult` 对象，包含 `filesCreated`、`skillsGenerated`、`mcpRegistered` 字段，可用于程序化校验安装完整性。
### 项目级配置
完整配置示例：
```yaml
# claude-flow.config.yaml
plugins:
prime-radiant:
enabled: true
config:
coherence:
warnThreshold: 0.3
rejectThreshold: 0.7
```
资料来源：[v3/plugins/prime-radiant/README.md:80-110]()
---
## 安装架构与生命周期
```mermaid
flowchart TD
A[npx @claude-flow/cli@alpha] --> B[ONNX 模型初始化]
B --> C{冷启动缓存?}
C -->|缺失| D[下载 ONNX 模型
耗时 >60s]
C -->|命中| E[快速启动]
D --> F[CLI 主进程]
E --> F
F --> G[init 子命令]
G --> H[daemon start
PID 锁文件竞争]
H --> I[生成 MCP 配置]
I --> J[写入 .claude.json]
J --> K[项目就绪]
H -->|race condition| L[僵尸守护进程
v3.12.2 已修复]
```
---
## 配置诊断与跨平台辅助
### `doctor` 诊断命令
CLI 内置 `doctor` 子命令用于系统健康检查，覆盖 Node 版本、配置、守护进程、内存、API 密钥、MCP 配置、磁盘空间七项。资料来源：[v3/implementation/adrs/README.md:40-90]()
```bash
claude-flow doctor
# 典型输出:
# ✓ Node.js Version: v22.21.1 (>= 20 required)
# ⚠ Daemon Status: Not running
# ⚠ Memory Database: Not initialized
```
### 跨平台辅助脚本
主仓库提供 `claude-flow-v3.sh`（Linux/macOS）与 `claude-flow-v3.ps1`（Windows）两个主辅助脚本，存放在 `v3/helpers/` 目录下，确保三类平台（macOS、Linux、Windows）的安装一致性——这与见证清单（witness manifests）所追踪的 95–99 项构建产物缺失问题直接相关（社区问题 #2391、#2047）。
### WASM 内核与插件架构
`@claude-flow/guidance/wasm-pkg` 提供 Rust 编写的确定性策略内核 `guidance-kernel`（v0.1.0），作为可选依赖嵌入。资料来源：[v3/@claude-flow/guidance/wasm-pkg/package.json:1-15]() 多数插件（如 `healthcare-clinical`）将其列为 `optionalDependencies`，缺失时仍可降级运行。
---
## 卸载与清理
### 官方卸载命令的缺失
截至 v3.14.0，**官方 CLI 未提供 `uninstall` 子命令**。社区问题 #670（19 条评论）、#710、#694 反复请求此功能，目前唯一可用的清理方式仍是手动操作。`npm uninstall -g claude-flow` 仅移除全局包，不会清理：
- `.claude.json` 中的 MCP 注册条目
- 项目级 `.claude-flow/` 目录
- ONNX 模型缓存（通常位于 `~/.cache/claude-flow/`）
- 守护进程 PID 文件（`/tmp/claude-flow-*.pid`）
- 见证清单与签名材料
### 建议的清理流程
```bash
# 1. 终止守护进程
pkill -f 'claude-flow/cli/bin/cli.js daemon'
# 2. 移除 npm 包
npm uninstall -g @claude-flow/cli
# 3. 手动清理配置与缓存
rm -rf ~/.claude-flow ~/.cache/claude-flow
# 编辑 ~/.claude.json，删除 claude-flow 相关条目
# 4. 清理项目级工件
rm -rf .claude-flow/ AGENTS.md CLAUDE.md
```
---
## 已知故障模式
下表汇总社区与 CI 中观测到的高频故障，按严重程度排序：
| 故障编号 | 现象 | 根本原因 | 修复版本 |
|---------|------|---------|---------|
| #2286 | `cli@alpha --version` 冷启动挂起 >60s | ONNX embedder 无条件初始化 | 待修复 |
| #2407 | macOS 累积 39 个僵尸守护进程 → 内核恐慌 | `init.ts:424` 使用 shell `&` 后台启动 | **v3.12.2** |
| #2395 | MCP `memory_store` 输出 128-dim mock 嵌入 | AgentDB `vectorBackend` 控制器未启用 | **v3.12.3** |
| #2403 | `security cve` 子命令返回空数据 | 子命令为桩，未接入 CVE 数据库 | 待修复 |
| #2391 / #2047 | 见证清单报告 95–99 项缺失产物 | `dist/` 编译产物未随源树发布 | 待修复 |
| #2412 | v3-ci.yml 主分支供应链审计失败 | 审计作业（`Run supply-chain audit`）结论为 `failure` | 待修复 |
### 守护进程激增问题（#2407）
该问题在真实 macOS 26.1（Mac mini M4 Pro）环境中复现：单次会话累积 **39 个僵尸 `node … daemon start` 进程**。修复方案为在 `daemon.ts` 中引入 `O_EXCL` 原子锁文件，并在 `init.ts` 中去掉 shell 后台化 `&` 操作符；竞态测试显示 5 个并发 `daemon start` 仅剩 1 个存活守护进程。资料来源：v3.12.2 发布说明
### 嵌入维度回归（#2395）
独立 CLI 路径使用 384-dim 真实 ONNX 嵌入，但 MCP 会话内路径持续回退到 128-dim 哈希占位嵌入，悄悄污染相似度检索结果。v3.12.3 修复后 MCP 路径恢复 384-dim 输出。资料来源：v3.12.3 发布说明
---
## See Also
- [ADR 与架构决策目录](https://github.com/ruvnet/ruflo/tree/main/v3/implementation/adrs)
- [@claude-flow/cli 命令参考](https://github.com/ruvnet/ruflo/tree/main/v3/@claude-flow/cli)
- [AIDefence 安全防护](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/aidefence/README.md)
- [发布与版本管理](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/deployment/README.md)
- [Metaharness 子进程集成架构](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-metaharness/README.md)
---
## Core Features: Agents, Swarms, Memory, and Self-Learning
### 相关页面
相关主题：[Overview and System Architecture](#page-1), [Plugin Marketplace, MCP Tools, and Extensibility](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [v3/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/README.md)
- [v3/@claude-flow/cli/package.json](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/cli/package.json)
- [v3/@claude-flow/codex/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/codex/README.md)
- [v3/@claude-flow/aidefence/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/aidefence/README.md)
- [v3/implementation/adrs/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/adrs/README.md)
- [v3/implementation/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/README.md)
- [v3/plugins/hyperbolic-reasoning/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/hyperbolic-reasoning/README.md)
- [v3/plugins/code-intelligence/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/code-intelligence/README.md)
- [v3/plugins/teammate-plugin/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/teammate-plugin/README.md)
- [plugins/ruflo-knowledge-graph/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-knowledge-graph/README.md)
- [plugins/ruflo-sparc/README.md](https://github.com/ruvlo/blob/main/plugins/ruflo-sparc/README.md)
- [plugins/ruflo-ruvector/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-ruvector/README.md)
- [plugins/ruflo-graph-intelligence/package.json](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-graph-intelligence/package.json)
- [ruflo/package.json](https://github.com/ruvnet/ruflo/blob/main/ruflo/package.json)
# Core Features: Agents, Swarms, Memory, and Self-Learning
## 概览
Ruflo 是基于 Claude Flow V3 演化而来的多智能体编排框架，围绕四大支柱构建：智能体（Agents）、群体（Swarms）、记忆（Memory）与自学习（Self-Learning）。系统采用 **领域驱动设计 + 微内核插件架构**，通过 Model Context Protocol（MCP）对外暴露统一接口，并使用事件溯源维护完整状态审计 资料来源：[v3/README.md:1-50](https://github.com/ruvnet/ruflo/blob/main/v3/README.md)。包入口与导出口已在 `package.json` 中显式声明，包含 `./mcp-tools`、`./memory`、`./intelligence` 等子路径 资料来源：[v3/@claude-flow/cli/package.json:1-60](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/cli/package.json)。
## 智能体与群体协调
Ruflo 的核心采用 **15-Agent Hierarchical Mesh** 分层网格结构，由 Queen 协调器统一指挥，下辖多个领域专家 Worker 智能体；通过事件总线实现任务分发、状态同步与故障恢复 资料来源：[v3/README.md:1-50](https://github.com/ruvnet/ruflo/blob/main/v3/README.md)。CLI 暴露 `agent`、`swarm`、`memory`、`deploy` 等命令族对运行时进行管理 资料来源：[v3/implementation/adrs/README.md:1-30](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/adrs/README.md)。
在团队协作维度，**teammate-plugin** 通过 21 个 MCP 工具支持团队管理、teammate 生成、消息传递、计划审批、远程同步与 BMSSP 优化 资料来源：[v3/plugins/teammate-plugin/README.md:1-50](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/teammate-plugin/README.md)。
群体执行遵循 **SPARC 方法论**，分为五个阶段：Specification → Pseudocode → Architecture → Refinement → Completion，每阶段都有 Gate 校验与对应 spawn 的智能体（researcher / planner / system-architect / coder+tester / reviewer） 资料来源：[plugins/ruflo-sparc/README.md:1-40](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-sparc/README.md)。状态机如下：
```mermaid
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](https://github.com/ruvnet/ruflo/blob/main/v3/README.md)。向量化默认采用 384 维嵌入（如 `all-MiniLM-L6-v2`），配合 HNSW 索引完成语义模式匹配 资料来源：[v3/@claude-flow/codex/README.md:1-30](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/codex/README.md)。
需要注意的是，社区曾报告 `memory_store` 持续返回 128 维 mock 嵌入的问题——根因是 AgentDB `vectorBackend` 控制器初始化为 `enabled: false` 且从不切换，3.12.3 版本通过强制启用 ONNX 路径予以修复 资料来源：[release v3.12.3](https://github.com/ruvnet/ruflo/releases/tag/v3.12.3)。
Ruflo 同时提供两类结构化记忆扩展：
- **知识图谱**：`kg-extract` 抽取实体与关系，`kg-traverse` 基于 pathfinder 算法按边权与语义相似度评分路径 资料来源：[plugins/ruflo-knowledge-graph/README.md:1-30](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-knowledge-graph/README.md)。
- **双曲推理**：利用负曲率嵌入建模深层层级（如 taxonomy），并由 SONA 自适应曲率 资料来源：[v3/plugins/hyperbolic-reasoning/README.md:1-30](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/hyperbolic-reasoning/README.md)。
## 自学习
自学习通过 **SONA**（Self-Optimizing Neural Architecture）与 **ReasoningBank** 两条互补路径实现：
- **SONA**：在任务执行后训练模式（pattern），并与双曲推理自适应集成，使 137+ 技能在调用时能够即时调优 资料来源：[v3/@claude-flow/codex/README.md:1-30](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/codex/README.md)。
- **ReasoningBank**：沉淀成功经验并支持向量检索，让 AIDefence 等模块可在 <0.1ms 延迟内复用新捕获的攻击模式，从而防御零日变体 资料来源：[v3/@claude-flow/aidefence/README.md:1-30](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/aidefence/README.md)。
Ruvector 插件将上述能力以命令族方式对外暴露：`/vector sona`（train、export、stats）、`/vector brain`（drift、partition、sync）以及 `/vector llm`（embed、benchmark） 资料来源：[plugins/ruflo-ruvector/README.md:1-60](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-ruvector/README.md)。`ruflo-graph-intelligence` 则基于 PageRank 与 sublinear 复杂度实现个性化图排序，为自学习提供图级别的反馈信号 资料来源：[plugins/ruflo-graph-intelligence/package.json:1-20](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-graph-intelligence/package.json)。
## See Also
- [v3/docs/adr/](./v3/docs/adr/) — 架构决策记录（ADR-001 至 ADR-175+，含 ADR-153 Darwin Mode）
- [v3/plugins/code-intelligence](./v3/plugins/code-intelligence/) — 代码语义搜索、克隆检测与控制流分析
- [v3/implementation/README.md](./v3/implementation/README.md) — V3 路线图与状态评估
- [release v3.12.2](https://github.com/ruvnet/ruflo/releases/tag/v3.12.2) — daemon 锁文件与 CVE 子命令修复
- [release v3.14.0](https://github.com/ruvnet/ruflo/releases/tag/v3.14.0) — testgen Test-Driven Repair
---
## Plugin Marketplace, MCP Tools, and Extensibility
### 相关页面
相关主题：[Overview and System Architecture](#page-1), [Core Features: Agents, Swarms, Memory, and Self-Learning](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [v3/implementation/plugins/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/plugins/README.md)
- [v3/@claude-flow/mcp/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/mcp/README.md)
- [v3/@claude-flow/codex/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/codex/README.md)
- [v3/@claude-flow/cli/package.json](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/cli/package.json)
- [v3/@claude-flow/plugins/package.json](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/plugins/package.json)
- [plugins/ruflo-sparc/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-sparc/README.md)
- [v3/plugins/code-intelligence/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/code-intelligence/README.md)
- [plugins/ruflo-docs/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-docs/README.md)
- [plugins/ruflo-metaharness/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-metaharness/README.md)
- [plugins/ruflo-cost-tracker/README.md](https://github.com/ruvnet/ruflo/blob/main/plugins/ruflo-cost-tracker/README.md)
- [v3/plugins/prime-radiant/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/plugins/prime-radiant/README.md)
- [v3/implementation/adrs/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/implementation/adrs/README.md)
- [v3/@claude-flow/deployment/README.md](https://github.com/ruvnet/ruflo/blob/main/v3/@claude-flow/deployment/README.md)
# 插件市场、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 插件系统由三层组成：
```mermaid
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：
```bash
# 验证 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 @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 锁文件修复。
## See Also
- [Agent 类型与 SPARC 流程]()
- [MCP 服务器与自学习记忆]()
- [Daemon 生命周期与 PID 锁文件]()
- [Witness Manifest 与供应链审计]()
---
---
## Doramagic 踩坑日志
项目：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