首页
/ RuFlo Claude Flow 插件目录结构全解析：.claude-plugin、commands、agents 与 hooks 架构指南

RuFlo Claude Flow 插件目录结构全解析：.claude-plugin、commands、agents 与 hooks 架构指南

2026-09-06 18:16:52作者：盛欣凯Ernestine
ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
项目地址：https://gitcode.com/GitHub_Trending/cl/ruflo

.claude-plugin/docs/STRUCTURE.md 是 RuFlo（Claude Flow）插件包中面向开发者的“结构说明书”，它定义了该插件如何遵循官方 Claude Code 插件规范组织元数据、斜杠命令、可委派 Agent 与事件钩子。本篇以该文档为骨架，结合本仓库中 .claude-plugin/plugin.json、.claude-plugin/marketplace.json、.claude-plugin/hooks/hooks.json 及 plugin/ 目录下的真实实现，逐层拆解这套“150+ 命令 + 74+ Agent + 3 个 MCP 服务器”插件系统的目录设计与加载原理，读完后你将能独立理解、安装、校验甚至二次搭建同类 Claude Code 插件。

一、文档定位：一份面向开发者的插件结构说明

STRUCTURE.md 在文档体系中扮演“地图”角色：它不对某个命令的使用展开教学，而是精确回答三个问题——插件由哪些目录组成、每个目录承载什么格式的内容、Claude Code 如何发现并加载它们。文档自述该插件“遵循官方 Claude Code 插件规范”（Official Claude Code Plugin Specification），并在结尾标注了可复现的版本契约：

  • 版本：2.5.0
  • 许可证：MIT
  • 作者：rUv
  • 兼容性：Claude Code >= 2.0.0
  • 状态：✅ PRODUCTION READY

这些元信息并非孤立声明：在 .claude-plugin/plugin.json 中可逐一核对——version 字段为 "2.5.0"、license 为 "MIT"、engines.claudeCode 为 ">=2.0.0"、engines.node 为 ">=20.0.0"，JSON 清单与结构文档严格互锁，是“文档与配置同源”的典型案例。

二、目录结构总览：四条内容管线

STRUCTURE.md 给出了插件包的标准目录树。对照本仓库根目录（当前工作目录即 RuFlo 仓库根），插件内容被组织为四个相互独立、职责清晰的内容管线，分别对应 .claude-plugin、commands、agents、hooks：

ruflo/                              # 仓库根目录（当前工作目录）
├── .claude-plugin/                 # 插件元数据与官方文档
│   ├── plugin.json                 # 插件清单（manifest）：名称、版本、MCP 服务器、引擎要求
│   ├── marketplace.json            # 市场分发元数据
│   ├── README.md                   # 完整文档（含 150+ 命令 / 74+ Agent 全量说明）
│   ├── STRUCTURE.md                # 本文所依据的结构文档
│   ├── docs/
│   │   ├── INSTALLATION.md         # 安装指南
│   │   ├── PLUGIN_SUMMARY.md       # 生产状态与内容清单
│   │   └── QUICKSTART.md           # 5 分钟快速上手
│   ├── hooks/
│   │   └── hooks.json              # 钩子事件配置（PreToolUse/PostToolUse/Stop…）
│   └── scripts/
│       ├── install.sh              # 安装脚本
│       ├── verify.sh               # 安装校验脚本
│       ├── uninstall.sh            # 卸载脚本
│       ├── ruflo-hook.cjs          # Node 版钩子执行器
│       └── ruflo-hook.sh           # 钩子脚本
│
├── plugin/                         # 插件能力内容（命令 / Agent / 钩子 / 技能）
│   ├── commands/                   # 150+ 斜杠命令（按 19 个类别分子目录）
│   │   ├── coordination/  ├── sparc/  ├── github/  ├── hive-mind/
│   │   ├── swarm/  ├── memory/  ├── monitoring/  ├── optimization/
│   │   ├── analysis/  ├── automation/  ├── hooks/  ├── workflows/
│   │   ├── training/  ├── flow-nexus/  ├── agents/  ├── pair/
│   │   ├── stream-chain/  ├── truth/  └── verify/
│   ├── agents/                     # 74+ 可委派 Agent（Markdown + YAML frontmatter）
│   │   ├── core/  ├── swarm/  ├── consensus/  ├── github/
│   │   ├── specialized/  ├── sparc/  ├── hive-mind/  ├── optimization/
│   │   └── …（20 个类别）
│   ├── hooks/
│   │   └── hooks.json              # 事件处理器配置
│   ├── scripts/
│   │   └── ruflo-hook.sh           # 弹性的钩子调用 shim
│   └── skills/                     # 供 Agent/CLI 调用的技能包

文档中的树形图是面向“打包后的 claude-flow 插件”的规范形态（顶层即 .claude-plugin/、commands/、agents/、hooks/），而本仓库以 RuFlo 单仓形式存放，命令与 Agent 统一收纳在 plugin/commands 与 plugin/agents 下——目录划分逻辑与文档描述的规范完全一致，只是物理挂载点多了一层 plugin/。

三、安装方式与验证闭环

STRUCTURE.md 将安装收敛为两条路径，均可一步完成插件的克隆、命令/Agent 装载、MCP 配置与钩子布设。

方式一：市场源安装（文档推荐）——在 Claude Code 会话内执行：

/plugin add ruvnet/claude-flow
/restart

方式二：本地目录安装——若已在本地克隆仓库（或本仓库内），在 Claude Code 中执行：

/plugin add .
/restart

安装完成后可用 /plugin list 确认 claude-flow 处于 active 状态，再以一条代表性命令验证加载是否生效：

/coordination-swarm-init

配套的 .claude-plugin/scripts/verify.sh 提供了脚本化校验闭环：它会依次检测 claude CLI 是否可用、$HOME/.claude/commands 与 $HOME/.claude/agents 目录是否存在（并统计 *.md 数量）、settings.json 中是否已写入 claude-flow MCP 配置，最后分别探测 claude-flow@alpha、ruv-swarm、flow-nexus@latest 三个 npm 包的可用性，最终输出 error/warning 汇总并给出退出码。该脚本将“结构文档中的目录规范”直接翻译成了可执行的断言。

四、组件详解：metadata、commands、agents、hooks 四大件

4.1 插件元数据（.claude-plugin/）

STRUCTURE.md 将元数据拆为两个文件：

plugin.json——插件清单，官方规定其承载：

  • 插件名称、版本、描述（name / version / description）
  • 作者与仓库信息（author / repository / homepage / bugs）
  • MCP 服务器配置（mcpServers）
  • 引擎要求（engines）

对照 .claude-plugin/plugin.json 的真实字段，还可以观察到两个额外的设计细节：keywords 与 tags 承担了插件市场的检索分类职责（涵盖 swarm、sparc、github、neural-network、enterprise 等），而 category: "development" 声明了插件的功能域。值得注意 engines 同时约束了两层运行时：claudeCode >= 2.0.0（宿主 CLI）与 node >= 20.0.0（命令/钩子运行环境）。

marketplace.json——市场分发元数据，文档列出的职责包括市场 owner 信息、插件清单与特性、需求与依赖。本仓库的 .claude-plugin/marketplace.json 走的是“多插件市场”路线：它不声明单一插件，而是以 plugins 数组挂载 40 余个子插件（从 ruflo-core、ruflo-swarm 到 ruflo-graph-intelligence、ruflo-arena），每个条目以 source 指向本地相对路径。这意味着该仓库本身就是一个可整体分发的插件市场，而 claude-flow 插件则是其中最早发布、以独立包形式存在的经典子集。

4.2 Commands：150+ 斜杠命令，19 个类别

文档对 commands 的三条硬性约定：

  • 载体：Markdown 文件（.md）
  • 发现机制：由 Claude Code 自动发现，无需注册表
  • 命名：kebab-case，且带类别前缀（如 coordination-swarm-init.md）

仓库 plugin/commands/ 的实际目录与文档的“19 个类别”一一吻合：coordination、sparc、github、hive-mind、swarm、memory、monitoring、optimization、analysis、automation、hooks、workflows、training、flow-nexus、agents、pair、stream-chain、truth、verify。各类命令规模如下（STRUCTURE.md 及 .claude-plugin/docs/PLUGIN_SUMMARY.md 中给出的分组口径）：

类别 数量 代表命令
coordination 6 /coordination-swarm-init、/coordination-agent-spawn、/coordination-task-orchestrate
sparc 18 /sparc-tdd、/sparc-architect、/sparc-reviewer、/sparc-optimizer
github 18 /github-pr-manager、/github-code-review-swarm、/github-release-manager
hive-mind 11 /hive-mind-init、/hive-mind-consensus、/hive-mind-memory
swarm 15 /swarm-init、/swarm-monitor、/swarm-background
flow-nexus 9 /flow-nexus-swarm、/flow-nexus-workflow、/flow-nexus-login
hooks / memory / monitoring / optimization / analysis / automation / workflows / training 各 5–7 /hooks-pre-task、/memory-persist、/monitoring-swarm-monitor、/optimization-auto-topology、/analysis-token-usage、/automation-smart-spawn、/workflows-create、/training-neural-train
合计 150+ 19 个类别

类型上除一级命令外，/sparc、/swarm 等入口命令会进一步路由到其子目录中类别化的具体命令，形成“顶层入口 + 分类子命令”的两级命令树。

4.3 Agents：74+ 可委派 Agent，20 个类别

文档对 agents 的约定：

  • 载体：带 YAML frontmatter 的 Markdown 文件
  • 机制：可供主 Agent 委派执行（delegation）
  • 命名：kebab-case（如 backend-dev.md）
  • 规模：74+ 专业 Agent，跨 20 个类别

在 plugin/agents/core/coder.md 等文件的开头可以确认 frontmatter 结构确实存在：每个 Agent 文件以 --- 分隔的 YAML 头声明 name/description 等元数据，正文则是给该 Agent 的角色指令。类别构成按文档分组为：Core Development（coder、planner、researcher、reviewer、tester）、Swarm Coordination（hierarchical/mesh/adaptive 等 5 类协调器）、Consensus & Fault Tolerance（Byzantine、Raft、Gossip、CRDT、Quorum 等 7 个）、GitHub Automation（13 个）、Specialized Development（backend、mobile、ML、CICD、api-docs 等 8 个）、SPARC Methodology（4 个）、Hive Mind、Optimization 等。

4.4 Hooks：事件处理器配置

文档将 hooks 定位为“与 Claude Flow 协调逻辑集成的、围绕任务执行前后与会话管理的钩子”。本仓库存在两份同名配置，作用不同：

以 .claude-plugin/hooks/hooks.json 为例，可以看到官方 hooks.json 的事件契约（每条事件可挂多个 matcher + command）：PreToolUse 监听 Bash 与 Write|Edit|MultiEdit，PostToolUse 通过 cat | jq -r 管道提取事件 JSON 中的命令与文件路径再回调脚本，Stop 事件则触发 session-end 做摘要生成与状态持久化。其 command 统一走 "${CLAUDE_PLUGIN_ROOT}/scripts/ruflo-hook.sh" … || true 的调用约定，并注明“优先调用已本地安装的 ruflo/claude-flow 二进制，回退到 npx --prefer-offline，且始终退出 0”——这是为了让钩子保持 best-effort 语义，任何一次 CLI 安装失败都不得在 Claude Code 中报错或阻塞回合（详见 .claude-plugin/scripts/ruflo-hook.sh 头注释与 plugin/scripts/ruflo-hook.sh 的同类实现）。

五、MCP 集成：三服务器布局与加载命令

STRUCTURE.md 与 plugin.json 一致声明插件将配置 3 个 MCP 服务器，合计 110+ 工具。其中仅 claude-flow 为必需项，其余两个按 optional 标记优雅降级——即便缺失，核心功能仍可用。

5.1 claude-flow（必需，40+ 编排工具）

{
  "mcpServers": {
    "claude-flow": {
      "command": "npx",
      "args": ["claude-flow@alpha", "mcp", "start"],
      "description": "Core Claude Flow MCP server for swarm coordination, agent management, and task orchestration (40+ tools)",
      "optional": false
    }
  }
}

覆盖 swarm 初始化管理、Agent 生成与协调、任务编排、记忆管理、神经训练与性能监控。手动装载方式为 claude mcp add claude-flow npx claude-flow@alpha mcp start。

5.2 ruv-swarm（可选，WASM 加速）

{
  "mcpServers": {
    "ruv-swarm": {
      "command": "npx",
      "args": ["ruv-swarm", "mcp", "start"],
      "description": "Enhanced swarm coordination with WASM acceleration",
      "optional": true
    }
  }
}

提供增强协调、SIMD 优化、高级拓扑管理与拜占庭容错能力。

5.3 flow-nexus（可选，需认证）

{
  "mcpServers": {
    "flow-nexus": {
      "command": "npx",
      "args": ["flow-nexus@latest", "mcp", "start"],
      "description": "Cloud-based orchestration platform with 70+ tools (requires authentication)",
      "optional": true
    }
  }
}

提供 70+ 云端工具（E2B 沙箱、分布式神经训练、事件驱动工作流等），文档明确标注需要认证。

插件安装时 MCP 服务器即被自动写入 Claude Code 配置，因此日常使用无需手工 claude mcp add；手动方式主要用于无插件场景下的补充装载。

六、文档体系与加载后的目录形态

STRUCTURE.md 列出的文档集合在本仓库均可找到实际文件：

文档 仓库相对路径 职责
插件总文档（~20KB） .claude-plugin/README.md 功能总览、命令/Agent 全量清单、示例
市场分发元数据 .claude-plugin/marketplace.json 多插件市场声明
安装指南 .claude-plugin/docs/INSTALLATION.md 三种安装方法与故障排查
生产状态总结 .claude-plugin/docs/PLUGIN_SUMMARY.md 内容统计表、合规清单、技术规格
5 分钟快速上手 .claude-plugin/docs/QUICKSTART.md 首个 swarm + 常用工作流
结构说明 .claude-plugin/docs/STRUCTURE.md 本文所依据的目录规范

值得一提的是，插件安装进 $HOME/.claude/ 后，命令与 Agent 会平铺到 ~/.claude/commands/、~/.claude/agents/ 这类 Claude Code 原生扫描目录——这正是 .claude-plugin/scripts/verify.sh 用它来统计命令/Agent 数量的原因，也解释了“Claude Code 自动发现、目录即注册表”的插件设计哲学。

七、如何用一分钟验证这套结构

结构是否就绪，无需通读全部文件，可按下述顺序快速验收：

  1. 清单一致性：检查 .claude-plugin/plugin.json 的 name/version/engines/mcpServers 是否与文档声明一致；
  2. 命名规范：抽查 plugin/commands/ 与 plugin/agents/ 是否全部 kebab-case、命令带类别前缀、Agent 带 YAML frontmatter；
  3. 钩子可执行：确认 .claude-plugin/hooks/hooks.json 中引用的脚本存在于 .claude-plugin/scripts/；
  4. 脚本化校验：运行 bash .claude-plugin/scripts/verify.sh，一次性核验 CLI、命令目录、Agent 目录与三个 MCP 包；
  5. 运行时冒烟：在 Claude Code 中依次执行 /plugin list → /coordination-swarm-init → /monitoring-status，完成从“结构正确”到“功能可用”的最终确认。

对希望自行打包 Claude Code 插件的开发者而言，本仓库的 .claude-plugin/ + plugin/commands/ + plugin/agents/ + plugin/hooks/ 布局即是一份可复制的参考实现：元数据驱动声明、目录自动发现、命令/Agent 纯 Markdown 承载、钩子走独立脚本 shim——这套约定让插件无需编译即可被宿主动态加载，也正是 STRUCTURE.md 全篇想要传达的结构契约。

ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
项目地址：https://gitcode.com/GitHub_Trending/cl/ruflo
登录后查看全文

相关内容推荐

1 ruflo/Claude Flow 插件安装指南：在 Claude Code 中一键启用 150+ 命令、74+ Agent 与 MCP 集群编排2 RuFlo（Claude Flow）插件 5 分钟快速上手指南：从安装、Swarm 编排到 MCP 接入全流程3 RuFlo / Claude Flow Plugin 企业级 AI Agent 编排插件完全指南：Swarm 群、SPARC 流程、GitHub 自动化与 MCP 集成4 RuFlo（Claude Flow）插件全景解读：150+ 命令、74+ 专精 Agent 与多智能体编排的生产级落地指南5 Ruflo 内置 Agent 类型全览：核心开发、Swarm 协调与专项 Agent 的分层选型实战6 ruflo agent-repo-architect 技能解析：用 Swarm 协调与 GitHub MCP 工具实现仓库结构分析与多仓架构治理7 ruflo 项目 SONA Learning Optimizer 深度解析：基于 LoRA 微调与 EWC++ 的 Agent 自学习优化实战指南8 ruflo 中的 GitHub Repository Architect：基于 ruv-swarm 多智能体群落的仓库结构优化与跨仓库管理实战9 ruflo Hive Mind Advanced 详解：Queen 主导的集群智能、拜占庭共识与蜂群 CLI 实战10 Ruflo Hooks Automation：Claude Code 智能钩子体系的设计、配置与源码解析
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
856
1.35 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
529
592
leetcodeleetcode
🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer（第 2 版）》、《程序员面试金典（第 6 版）》题解
Markdown
77
23
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.13 K
2.73 K
docsdocs
暂无描述
Markdown
897
5.79 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.57 K
1.01 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
1.01 K
513
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
912
1.83 K
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
213
313