ruflo-plugin-creator用契约化脚手架批量生成合规 Claude Code 插件的工程实践【免费下载链接】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-plugin-creator是 ruflo 生态中的元插件meta-plugin它负责脚手架化scaffold、校验validate与发布publish新的 Claude Code 插件并且让每个新生成的插件从诞生第一天起就继承整个插件家族的统一契约——ADR 决策记录、smoke 冒烟测试、Compatibility 兼容性锁定、Namespace 命名空间协调以及 MCP 工具接线防漂移警告。读完本文你将掌握如何安装与调用该插件、它生成的规范目录结构长什么样、plugin.json与SKILL.md的正确写法、必须规避的四类 MCP 工具引用漂移以及如何通过scripts/smoke.sh把插件质量做成可执行的硬性门槛。什么是 ruflo-plugin-creatorruflo 家族有数十个插件ruflo-agentdb、ruflo-browser、ruflo-cost-tracker、ruflo-market-data、ruflo-knowledge-graph、ruflo-observability等每个插件都由.claude-plugin/plugin.json、skills/、commands/、agents/、docs/adrs/、scripts/组成。历史上这些插件是逐个手工搭建的导致三类反复出现的问题结构不统一有的插件缺scripts/有的缺docs/版本锁定方式五花八门MCP 工具引用漂移embeddings_embed这个不存在的工具名、错误的namespace参数被反复写进allowed-tools过期数字被抄来抄去例如19 个 AgentDB 控制器这个陈旧计数在多个插件文档中反复出现。ruflo-plugin-creator的定位正是一个工厂它把上述教训固化成脚手架模板与校验脚本让新插件生而合规而不是事后修补。正如其 ADR-0001 中所说这个插件位置特殊——每个由它生成的插件都会继承它所产出的契约因此 ADR-0001 必须同时做两件事自身遵守家族契约pinning、namespace 协调、smoke 即契约并更新脚手架输出让新插件一出生就带着契约。安装在 Claude Code 中通过 ruflo marketplace 安装/plugin marketplace add ruvnet/ruflo /plugin install ruflo-plugin-creatorruflo安装后插件提供 1 个命令、2 个技能与 1 个 agent对应仓库内的实体为命令commands/create-plugin.md技能skills/create-plugin/SKILL.md 与 skills/validate-plugin/SKILL.mdAgentagents/plugin-developer.md插件的元数据名称、版本、关键词定义在 .claude-plugin/plugin.json当前版本0.2.1关键词含mcp、scaffolding、contract-bootstrap——这三个关键词也是 smoke 检查的固定断言项。核心能力1. 脚手架化插件在几秒内生成完整的插件目录结构包含规范契约四件套ADR-0001、scripts/smoke.sh、README 契约段落Compatibility / Namespace coordination / Verification / Architecture Decisions。2. 校验格式检查plugin.json、SKILL.mdfrontmatter 与文件引用是否正确在发布前拦截结构性问题。3. MCP 工具接线自动发现并接线 ruflo MCP 工具到技能的allowed-tools并对已知的损坏工具引用给出漂移警告embeddings_embed、传给agentdb_hierarchical-*/agentdb_pattern-*的namespace参数等。4. Marketplace 集成将新插件登记到marketplace.json以便分发。命令与技能命令/create-plugin交互式脚手架新插件。执行流程见 commands/create-plugin.md询问用户插件名、描述、期望的 skills / commands / agents调用create-plugin技能生成完整目录结构调用validate-plugin技能校验正确性向用户展示产出并用claude --plugin-dir ./plugins/name进行本地测试。技能create-plugin生成插件的技能frontmatter 中显式声明了allowed-toolstransfer_plugin-info、transfer_plugin-search、store-search加Bash Read Write Edit不使用通配符。它的执行步骤见 SKILL.md非常完整获取插件名与描述冲突检查——调用transfer_plugin-search确保插件名未被占用按规范契约创建目录结构生成plugin.json不要包含skills、commands、agents数组——Claude Code 会从目录结构自动发现写了反而触发校验错误生成带合法 frontmatter 的SKILL.md生成命令文件name description frontmatter生成 agent 文件name description model: sonnet生成 README并写入四个契约段落Compatibility、Namespace coordination、Verification、Architecture Decisions生成docs/adrs/0001-name-contract.md状态Proposed生成scripts/smoke.sh至少 8 项结构检查如需加入 ruflo marketplace 则更新marketplace.json。技能validate-plugin发布前的校验关卡执行 10 项检查详见 validate-plugin/SKILL.md.claude-plugin/plugin.json存在于插件根目录plugin.json必填字段齐全name、description、versionskills/name/SKILL.md均为合法技能自动发现plugin.json不得列出skills数组commands/name.md均为合法命令自动发现agents/name.md均为合法 agent自动发现plugin.json中不允许存在skills/commands/agents数组会导致 Claude Code 拒绝加载每个技能 frontmatter 含name、description、allowed-tools不允许通配符每个 agent frontmatter 含name、description、model文件不落在错误位置skills/commands/agents 不得放进.claude-plugin/allowed-tools中的工具引用均为合法的mcp__plugin_ruflo-core_ruflo__*标识符。规范插件契约脚手架产出的标准形状每个由本插件生成的插件都继承统一的目录形状源自 create-plugin/SKILL.md 与 README.mdplugins/name/ ├── .claude-plugin/plugin.json # version、keywords、mcp 关键词 ├── skills/skill/SKILL.md # name description allowed-tools无通配符 ├── commands/command.md # name description 分发逻辑 ├── agents/agent.md # name description model ├── docs/adrs/0001-name-contract.md # ADRProposed——pinning、namespace、smoke 范围 ├── scripts/smoke.sh # 结构契约≥8 项检查 └── README.md # Compatibility Namespace coordination Verification ADRplugin.json 的字段契约create-plugin/SKILL.md 明确了字段分级必填namekebab-case 插件标识、description插件做什么、versionsemver推荐author{ name: ..., url: ... }、homepage、license、keywords可选graph_adapterADR-130 图智能契约默认以注释形式输出——当autoRegister: true时插件产生的边会自动进入核心图层的graph_edges写入因此要声明edgeRelations本插件产生的关联类型。// graph_adapter: { // edgeRelations: [my-relation-type], // nodeTypes: [entity], // autoRegister: true // }绝对禁止在plugin.json中包含skills、commands、agents数组。这些内容由 Claude Code 从目录结构自动发现手动列出会导致校验失败。README 的四个契约段落脚手架会在 README 中强制生成四段Compatibility——锁定claude-flow/cliv3.6 大版本次版本Namespace coordination——声明一个 kebab-case 的plugin-stem-intent命名空间并 defer 到 ruflo-agentdb ADR-0001 的Namespace conventionVerification——bash plugins/name/scripts/smoke.shArchitecture Decisions——链接到本插件 ADR-0001。MCP 工具漂移必须规避的四类经典 Bug这是脚手架内嵌的前车之鉴清单源自整个插件家族在历次 ADR 修复中发现的真实 Bug。脚手架会把这张表写进每个新插件的 README 与技能模板Bug正确用法embeddings_embed被当作工具引用用embeddings_generate——_embed名称不存在给agentdb_hierarchical-*传namespace参数用tierworking/episodic/semantic命名空间的读写请用memory_*给agentdb_pattern-*传namespace参数不要传——它走 ReasoningBank 路由回退写入保留的pattern命名空间混淆pattern与patterns它们是不同的保留命名空间ReasoningBank 回退写入pattern单数hooks_pretrain写入patterns复数硬编码19 个 AgentDB 控制器以运行时agentdb_controllers为准——真实数量会变约 15 个 MCP 工具、29 个控制器名源码佐证embeddings_generate是唯一真实工具名我们在 v3/claude-flow/cli/src/mcp-tools/embeddings-tools.ts 中可以确认name: embeddings_generate是真实的工具定义见该文件第 274 行而embeddings_embed在工具清单中并不存在。这与 ruflo-agentdb ADR-0001 中统计的 10 个embeddings_*工具一一对应embeddings_init, embeddings_generate, embeddings_compare, embeddings_search, embeddings_neural, embeddings_hyperbolic, embeddings_status, embeddings_rabitq_build, embeddings_rabitq_search, embeddings_rabitq_status。接线时可用的工具族来自 create-plugin 技能脚手架技能还内置了一份可用工具族速查memory_*——存储、搜索、检索agentdb_*——15 个控制器桥接工具不要传namespace参数它们按 tier 或 ReasoningBank 路由运行时调用agentdb_controllers获取权威清单neural_*——神经训练与预测hooks_*——生命周期钩子与智能browser_*——浏览器自动化workflow_*——工作流管理aidefence_*——安全扫描embeddings_*——10 个向量嵌入工具用embeddings_generate不是不存在的embeddings_embed。用 smoke 把契约变成硬门槛本插件的冒烟契约仓库内的 scripts/smoke.sh 定义了 10 项结构检查运行方式bash plugins/ruflo-plugin-creator/scripts/smoke.sh # Expected: 10 passed, 0 failed10 项检查逐条列出即 ADR-0001 中smoke as contract的落地实现plugin.json声明0.2.1且包含mcp、scaffolding、contract-bootstrap三个关键词两个技能 agent command 齐全且 frontmatter 合法name:、description:、allowed-tools:齐备create-plugin技能脚手架内容包含 ADR、smoke、Compatibility、Namespace coordinationcreate-plugin技能包含 MCP 漂移警告embeddings_embed、agentdb_hierarchical×namespace、agentdb_pattern×namespace/ReasoningBank、单复数pattern警告create-plugin技能不再声称19 个 AgentDB 控制器回归检查README 锁定claude-flow/cliv3.6README 含 Architecture Decisions 段落ADR-0001 存在且状态为Acceptedvalidate-plugin技能存在任何技能都不得授予通配符工具权限allowed-tools: *即失败。注意第 8 项ADR-0001 文件 docs/adrs/0001-plugin-creator-contract.md 的 frontmatter 状态为Acceptedsmoke 脚本实际断言的是Accepted而脚手架输出给新插件的 ADR 模板状态则是Proposed——已采纳的元契约与新生插件的待批准契约是有意区分的。每个新插件都被要求生成自己的 smoke脚手架要求每个新插件生成scripts/smoke.sh至少 8 项结构检查版本与关键词skills/agents/commands 存在且 frontmatter 合法README 中的 v3.6 pinREADME 中的 namespace coordination 段落ADR 存在且状态为Proposed技能中无通配符工具。家族级先例smoke-as-contract 的普适模式把 smoke 当作契约并非本插件独创而是整个 ruflo 家族的共识。以 ruflo-agentdb 的 ADR-0001 为例它的 smoke 契约同样以10 passed, 0 failed为验收线并特意做了三条设计决策断言下界而非精确值agentdb_controllers.total 15、active 10——验证注册表初始化成功而不是把 29 个控制器名硬编码进测试如果未来 ADR 关闭默认激活的控制器只需上调下限回归守卫agentdb_hierarchical-store拒绝非{working, episodic, semantic}的 tier 值对应agentdb-tools.ts:426的校验、agentdb_batch拒绝 501 元素的数组对应MAX_BATCH_SIZE 500、memory_store拒绝含:或超长200 字符的命名空间明确非目标不精确测试控制器数量、不依赖agentdb的具体 minor 版本、不触发禁用的graphAdapter控制器。这条先例直接启发了本插件 smoke.sh 中的第 5 条回归检查不再声称19 个控制器与第 10 条无通配符检查。ADR-0001 的来龙去脉本插件的架构决策记录见 docs/adrs/0001-plugin-creator-contract.md其核心上下文是每个由本插件脚手架出来的新插件都会继承脚手架所产出的任何契约因此 ADR-0001 必须做两件事① 采纳与其他插件相同的家族契约② 更新脚手架输出让新插件生而携带契约而非事后修补。已修复的漂移ADR 记录了一个具体案例create-plugin技能曾声称19 个 AgentDB 控制器而 ruflo-agentdb ADR-0001 已宣布该数字是神话——真实的 MCP 工具面是 15 个agentdb_*工具、29 个ControllerName条目。该次修正被固化为 smoke.sh 的第 5 项回归检查。决策与后果决策本插件自身采纳契约README 增加 Compatibility / Namespace coordination / Verification / Architecture Decisions 段落版本0.1.0 → 0.2.0关键词增加mcp、scaffolding、contract-bootstrap同时更新脚手架输出ADR smoke README 契约段落 四类 MCP 漂移警告。积极后果未来的脚手架自动继承规范契约家族正在做的逐插件事后修补对新插件不再必要四类反复发现的 MCP 漂移 Bug 成为脚手架内嵌警告插件进入统一节奏。消极后果既有插件不受此 ADR 自动更新仍需通过逐插件通道修补该工作当时已基本完成。实现状态v0.2.0 已发布并登记 marketplace契约要素全部落地脚手架模板默认包含契约 ADR、smoke 测试、Compatibility 段与 namespace 协调块MCP 漂移警告加入技能模板scripts/smoke.sh定义了 smoke-as-contract 门槛。关联插件与生态位ruflo-agentdb——namespace 约定所有者agentdb_controllers运行时是权威控制器清单本插件对其保持 defer不硬编码数量ruflo-cost-tracker、ruflo-market-data、ruflo-migrations、ruflo-observability——各自修复过 namespace 路由类 Bug这些 Bug 现在成为脚手架的警告ruflo-knowledge-graph、ruflo-market-data——各自修复过embeddings_embed引用同样成为脚手架的警告。最佳实践小结一切以契约为准plugin.json不写 skills/commands/agents 数组技能 frontmatter 必须含allowed-tools且禁止通配符agent 必须声明model: sonnet别硬编码会变的数字工具数量、控制器数量一律 defer 到运行时工具agentdb_controllers或源码统计smoke 断言用下界而非精确值接线前核对工具真实名称embeddings_generate是真实工具、embeddings_embed不是agentdb_*按 tier / ReasoningBank 路由而非 namespace把冒烟测试当作发布门槛bash plugins/name/scripts/smoke.sh输出 10 passed, 0 failed 才允许发布新插件继承契约用create-plugin脚手架而非手写让 ADR smoke 契约段落从第一天就位。如需深入可继续阅读本插件的 README、ADR-0001 与 smoke.sh以及家族契约的源头 ruflo-agentdb ADR-0001。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考