Ruflo 智能体编排目录结构：新文件放哪、插件系统怎么分工的完整答案-育师

Ruflo 智能体编排目录结构：新文件放哪、插件系统怎么分工的完整答案

【免费下载链接】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

新人拿到 Ruflo 仓库最容易懵的一件事：要给一个智能体补一段定义，不知道文件该落在哪个目录。Ruflo 是一个智能体元框架（meta-harness），核心能力是多智能体蜂群编排、自学习记忆、RAG 集成，以及对 Claude Code / Codex 的原生支持。它的目录结构把「智能体定义、插件包、运行时实现」分得相当干净，摸清之后定位任何文件都不超过三次点击。

目录全景：一次看清仓库布局

ruflo/ ├── v3/ # 当前主版本：智能体运行时与 CLI（pnpm workspace） │ ├── @claude-flow/ # 核心包：cli / mcp / memory / swarm / security / shared │ ├── agents/ # 五个基础智能体的 YAML 定义（architect/coder/reviewer 等） │ ├── mcp/ # MCP 服务器、工具注册、传输层 │ ├── plugins/ # 运行时插件实现（TS 包，16 个） │ ├── docs/ # 177 篇 ADR + 规格文档 │ └── goal_ui/ # 前端：目标规划与对话界面（Svelte） ├── v3/crates/ # Rust crate：watermark / federation-peer / agntcy ├── plugin/ # Claude Code 插件资产：agents / commands / skills / hooks ├── plugins/ # 35 个可独立安装的插件包（ruflo-core、ruflo-swarm…） ├── ruflo/ # 产品应用：ruvocal 聊天 UI、Docker 编排、发布产物 ├── scripts/ # 约 110 个维护脚本：审计、基准测试、冒烟检查 ├── tests/ # 顶层集成测试（rvf 后端、hook 持久化等） ├── verification/ # linux / macos / windows 三平台验证基线 ├── data/ # 克隆与证明账本 └── docs/ # 仓库级文档：基准、安全基线、用户指南

这是一张典型的「三层」结构：v3/是引擎，plugins/是面向用户的安装包，plugin/是注入给 Claude Code 的声明式资产。理解这个分层，下面的问题就都能回答了。

导读：开发者最常问的 3 个问题

新智能体定义放哪？

结论：角色定义进v3/agents/，能力扩展进plugin/或plugins/，别放混。v3/agents/ 下放着五个基础智能体：architect.yaml、coder.yaml、reviewer.yaml、security-architect.yaml、tester.yaml，这是 YAML 层面的「角色卡」。而 plugin/agents/ 是一个按领域分层的智能体文档库（github、consensus、hive-mind、sparc 等 20+ 个主题目录），plugins/下则是一个智能体连同命令、脚本、技能打包成可安装单元。三者分工：定义、说明、可交付包。

plugin/ 与 plugins/ 和 v3/plugins/ 如何分工？

这是全仓库最容易绕晕的一组名字。

plugins/：35 个面向用户的安装包（ruflo-core、ruflo-swarm、ruflo-rag-memory等），每个包自带agents/、commands/、skills/、scripts/和 README，通过 Claude Code 的 plugin marketplace 单独安装。
plugin/：CLI 全量安装时注入工作区的声明式资产，按 agents / commands / skills / hooks 分类，不打包、不分发。
v3/plugins/：真正的运行时 TS 插件实现（cognitive-kernel、neural-coordination、perf-optimizer 等 16 个），被主程序加载执行。

一句话记法：plugins/装给用户，plugin/装给工作区，v3/plugins/装在代码里。

跨智能体共享的资源放哪？

共享代码进 v3/@claude-flow/。这里的包名带@前缀是刻意的：workspace 只把@claude-flow/*纳入构建（见 v3/pnpm-workspace.yaml），所以memory、swarm、shared、guidance这些包就是所有智能体共同依赖的「公共库」。共享的智能体间通信协议看 v3/plugin-agent-federation/，底层高性能组件则沉到 Rust 层 crates/ruflo-federation-peer/。跨平台的行为基线不靠口头约定，而是锁在 verification/ 的三平台 JSON 基线里。

实践清单：五条可勾选的自检项

命名用 kebab-case，扩展名即职责。反例：SwarmManager_v2.ts；正例：仓库里到处是smoke-wasm-plugin-bridge.mjs、ruflo-rag-memory这种「小写 + 连字符 + 后缀表类型」的写法。
一个目录只做一件事。反例：把测试脚本塞进plugins/ruflo-core/skills/；正例：scripts/ 里 110 个脚本按前缀自分类——audit-*是审计、smoke-*是冒烟、benchmark-*是基准，一眼可辨。
文档跟着代码走，ADR 跟着决策走。反例：设计说明写在 README 末尾一段话；正例：v3/docs/adr/ 用 177 篇编号 ADR（如ADR-094-xenova-to-huggingface-transformers-migration.md）逐一记录架构决策，每个插件包还自带docs/和 README。
产物不进源码树。反例：把编译出的 JS 和.map文件提交到源码目录；正例：根 package.json 的files字段明确用!排除dist/**/*.map，构建产物按白名单发布。
测试按层级落位，别散。反例：单测、集成测、容器测混放一个目录；正例：单测在v3/__tests__/与各包内，顶层 tests/ 放 rvf 集成测试，容器回归独立在 tests/docker-regression/（自带 Dockerfile + Makefile）。

上手三步：clone 之后怎么快速摸透

第一步，clone 仓库：

git clone https://gitcode.com/GitHub_Trending/cl/ruflo

然后按顺序扫三个入口文件，十分钟能画出全图：根 README.md 讲两条安装路径（Claude Code 插件 vsnpx ruflo init全量装）；plugins/README.md 列 35 个插件包的清单；v3/pnpm-workspace.yaml 告诉你@claude-flow/*哪些才是核心构建单元。

第二步，找同类再动手。想加一个智能体角色，先去v3/agents/里读coder.yaml的字段结构；想加一个插件包，去plugins/ruflo-sparc/看它的agents/ commands/ skills/ scripts/四件套怎么摆。照着现有同类文件的骨架写，比看任何文档都快。

第三步，防腐化。仓库把「检查结构健康」做成了自动化：scripts/下的audit-*和check-*脚本会在每次维护时扫描插件清单、工具描述、版本联动是否漂移；verification/的三平台基线则会捕获跨操作系统行为差异。你只需要在合并前跑一遍相关审计脚本，结构腐化会在变成「历史债」之前被拦下来。