ruflo 插件脚手架完全指南：用 ruflo-plugin-creator 打造符合规范契约的 Claude Code 插件

ruflo 插件脚手架完全指南：用 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 仓库中的create-plugin技能（plugins/ruflo-plugin-creator/skills/create-plugin/SKILL.md）为骨架，完整讲解如何在 ruflo 生态中从零脚手架（scaffold）一个生产级 Claude Code 插件：目录结构、plugin.json 契约、SKILL.md 前后置元数据、MCP 工具接线、四类经典工具引用漂移（drift）陷阱，以及把 smoke 测试当作结构契约的验证方式。读完你既能手工照抄每一步产出，也能理解底层 ADR 契约（ADR-0001）与验证脚本（smoke.sh）为何这样设计。

一、背景：为什么需要一个"会生成契约"的脚手架插件

ruflo 是一个 agent meta-harness 项目，其生态由大量相互协作的 Claude Code 插件构成（ruflo-agentdb、ruflo-browser、ruflo-rag-memory、ruflo-intelligence 等）。这些插件共享同一套"规范插件契约"（canonical plugin contract）：版本钉扎（pinning）、命名空间协调（namespace coordination）、MCP 工具接线、ADR 记录、以及"smoke 即契约"的结构验证。

ruflo-plugin-creator是其中唯一的"元插件"（meta-plugin）：它自身就是 v0.2.x 的正式插件（1 个 agent + 2 个 skill + 1 个 command），但它的产出物——每一个被脚手架出来的新插件——会自动继承整套契约。这正是其 ADR-0001 的核心论断：

每个由它脚手架出的新插件，都会继承脚手架产出的一切。ADR-0001 必须做两件事：① 采用本会话中其他插件采纳的同一套契约；② 更新脚手架产出，让新插件天生携带契约，而不是事后返工（retrofit）。

因此本文的实操对象就是 create-plugin 技能，它负责生成正确的目录结构并把 MCP 工具接好线。

二、何时使用 create-plugin

根据 SKILL.md 的 "When to use" 与命令入口 commands/create-plugin.md：

• 当你需要创建一个扩展 Claude Code 的新插件（提供 skills、commands、agents）时使用；
• 交互入口为/create-plugin，它会先向用户收集：插件名、描述、期望的 skills、commands、agents；
• 然后调用create-pluginskill 完成整套目录脚手架；
• 接着调用validate-pluginskill 验证正确性；
• 最后展示产出，并用claude --plugin-dir ./plugins/<name>进行本地测试。

三、第一步：名称冲突检查（plugin-search）

脚手架的第一步不是创建目录，而是检查冲突。技能要求先调用：

mcp__plugin_ruflo-core_ruflo__transfer_plugin-search

确认目标插件名尚未被占用。这一步在 ruflo 的多插件生态中至关重要——每个插件都要在 .claude-plugin/marketplace.json 的市场注册表中占位，重名会直接破坏市场集成。从源码结构看，ruflo 仓库的plugins/目录下 40+ 个插件全部以ruflo-前缀命名并各自维护独立目录，任何新名字都必须先在全局市场中校验可用性。

四、第二步：生成规范目录结构

技能要求脚手架产出以下目录树（这也是 ruflo 家族所有插件经各自 ADR-0001 采纳的同一形状，见 ruflo-plugin-creator README 的 "Canonical plugin contract" 一节）：

plugins/<name>/ ├── .claude-plugin/ │ └── plugin.json ├── skills/ │ └── <skill-name>/ │ └── SKILL.md ├── commands/ │ └── <command-name>.md ├── agents/ │ └── <agent-name>.md ├── docs/ │ └── adrs/ │ └── 0001-<name>-contract.md # Plugin-level ADR (Proposed) ├── scripts/ │ └── smoke.sh # Structural contract (≥8 checks) └── README.md # Compatibility + Namespace coordination + Verification + ADR sections

逐项说明每个产物的职责：

硬性红线：不得把 skills/commands/agents 放进.claude-plugin/

validate-plugin技能（plugins/ruflo-plugin-creator/skills/validate-plugin/SKILL.md）第 9 项检查明确：任何 skill/command/agent 文件出现在.claude-plugin/目录内都属于结构错误。这与 plugin-developer agent 的规则一致："Never put skills/commands/agents inside.claude-plugin/"。

五、生成 plugin.json：字段契约与自动发现

技能规定 plugin.json 的生成规则：不要包含skills、commands、agents数组——Claude Code 会根据目录结构自动发现这些内容，一旦出现这些数组反而会触发校验错误导致插件被拒。

字段分层如下：

必需字段

推荐字段

• author：{ "name": "...", "url": "..." }
• homepage、license、keywords

可选字段：graph_adapter（ADR-130 图智能契约）

脚手架默认以注释形式输出，按需取消注释：

// "graph_adapter": { // "edgeRelations": ["my-relation-type"], // "nodeTypes": ["entity"], // "autoRegister": true // }

当autoRegister: true时，插件产生的边会被核心图层的graph_edges写入自动收录，因此必须声明edgeRelations——即本插件会产出的关系类型。

验证兜底：validate-plugin技能第 3、4、5、6 项会逐一断言：skills 自动发现、commands 自动发现、agents 自动发现，以及不存在遗留数组。凡是 plugin.json 里出现了skills/commands/agents数组，一律判为校验错误。

六、生成 SKILL.md、命令与 agent 文件

6.1 SKILL.md 前后置元数据

脚手架生成的每个技能文件都必须带正确的 frontmatter：

--- name: skill-name description: What this skill does allowed-tools: mcp__plugin_ruflo-core_ruflo__tool1 mcp__plugin_ruflo-core_ruflo__tool2 Bash ---

三个字段缺一不可（validate-plugin第 7 项检查），且allowed-tools不允许使用通配符*——smoke.sh第 10 项与 ADR 契约都明确禁止 wildcard 工具授权。以本插件自身的 create-plugin SKILL.md 为例，其allowed-tools精确列出 4 个 MCP 工具与 Bash/Read/Write/Edit，而非*。

6.2 命令文件

命令文件同样需要name+descriptionfrontmatter，正文写分派逻辑。参见本插件的 create-plugin.md 命令：收集需求 → 调 skill 脚手架 → 调 validate-plugin 验证 → 给出测试指引。

6.3 Agent 文件

Agent 需要name、description，且必须声明model: sonnet。本插件的 plugin-developer.md 是现成范例，它还展示了如何在 agent 内接入记忆与神经学习：

# 记忆沉淀：把成功插件模式存入 plugin-patterns 命名空间 npx @claude-flow/cli@latest memory store --namespace plugin-patterns --key "plugin-TYPE" --value "STRUCTURE_AND_CONFIG" npx @claude-flow/cli@latest memory search --query "plugin scaffold for TYPE" --namespace plugin-patterns # 任务后神经训练 npx @claude-flow/cli@latest hooks post-task --task-id "TASK_ID" --success true --train-neural true npx @claude-flow/cli@latest memory search --query "TASK_TYPE patterns" --namespace patterns

注意其中patterns是复数命名空间——这正是下文"漂移陷阱"第 4 条涉及的命名空间区分，实际使用时务必分清。

七、README 的四个契约段落

技能要求生成的 README 除了安装说明、特性、命令、技能清单外，还必须包含四个规范契约段落：

1. Compatibility（兼容性）——钉扎到@claude-flow/cliv3.6 的 major+minor。本插件 README 原文："CLI: pinned to@claude-flow/cliv3.6 major+minor"，smoke.sh第 6 项会 grep 校验这一钉扎声明。
2. Namespace coordination（命名空间协调）——声明 kebab-case 的<plugin-stem>-<intent>命名空间，遵循 ruflo-agentdb ADR-0001 §"Namespace convention"。纯脚手架类插件（如本插件）可以声明"无 AgentDB 写入"，但仍必须保留该段落。
3. Verification（验证）——bash plugins/<name>/scripts/smoke.sh即契约。
4. Architecture Decisions（架构决策）——链接到docs/adrs/0001-<name>-contract.md。

八、生成 ADR-0001（Proposed）

脚手架在docs/adrs/0001-<name>-contract.md生成插件级 ADR，记录四件事：

• 版本钉扎（pinning）；
• 命名空间协调（namespace coordination）；
• MCP 工具面数量（如适用，surface count）；
• smoke 契约范围（smoke contract scope）。

状态初始为Proposed。本插件自身的 ADR-0001 状态为Accepted（由Proposed演进而来），其 "Implementation status" 记录：脚手架模板已默认生成契约 ADR、smoke 测试、Compatibility 段与命名空间协调块，并把 MCP-drift 警告加入被脚手架出的技能模板。

九、生成 scripts/smoke.sh：至少 8 项结构检查

技能要求新插件的 smoke.sh 至少包含 8 项结构性检查：

1. 版本号与关键词（version + keywords）；
2. skills/agents/commands 存在且 frontmatter 合法；
3. README 中存在 v3.6 钉扎；
4. README 中存在命名空间协调块；
5. ADR 存在且状态为Proposed；
6. 技能中无通配符工具。

本插件自身的 smoke.sh 是 10 项检查的完整范例（bash+grep即可运行，无外部依赖），核心片段：

#!/usr/bin/env bash set -u ROOT="$(cd "$(dirname "$0")/.." && pwd)" PASS=0; FAIL=0 # 检查 1：plugin.json 声明版本与 mcp/scaffolding/contract-bootstrap 关键词 step "1. plugin.json declares 0.2.1 with new keywords" v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1) ... # 检查 4：create-plugin 包含 MCP 工具漂移警告 step "4. create-plugin includes MCP-tool drift warnings" grep -q "embeddings_embed" "$F" || miss="$miss embed-warning" ... printf "\n%s passed, %s failed\n" "$PASS" "$FAIL" [[ $FAIL -eq 0 ]] || exit 1

10 项检查清单（来自 ADR-0001 §3 Smoke contract）：

1. plugin.json 声明 0.2.x 且含新关键词；
2. 两个 skill + agent + command 均存在且 frontmatter 合法；
3. create-plugin skill 会脚手架出 ADR、smoke、README 契约段；
4. create-plugin skill 包含 MCP 工具漂移警告；
5. create-plugin skill 不再声称"19 AgentDB controllers"（回归检查）；
6. README 钉扎@claude-flow/cliv3.6；
7. README 有 Architecture Decisions 段；
8. ADR-0001 存在且状态合法；
9. validate-plugin skill 存在；
10. 无技能授予通配符工具权限。

运行方式：bash plugins/<name>/scripts/smoke.sh，期望输出如10 passed, 0 failed。

十、必读：四类 MCP 工具漂移陷阱（sibling-ADR 血泪教训）

这是整个技能中最具实战价值的部分。多个已发布插件曾携带微妙的 MCP bug，循环（loop）在家族内逐一修复后，脚手架技能把这些教训固化成了警告。新插件作者必须规避：

陷阱 1：embeddings_embed不存在

真实的工具是embeddings_generate。任何allowed-tools行里出现embeddings_embed都属于无效引用（该名称在 ruflo-knowledge-graph ADR-0001 中有 rename 记录）。embeddings_*共 10 个向量嵌入工具，一律使用embeddings_generate。

陷阱 2：agentdb_hierarchical-*不按命名空间路由

该类工具按tier（层级）路由：working | episodic | semantic。传namespace参数会被静默忽略。需要按命名空间读写时，改用memory_*工具。

陷阱 3：agentdb_pattern-*不按命名空间路由

该类工具经由ReasoningBank路由，同样不要传namespace参数；其回退写入落在保留命名空间pattern（memory-store-fallback）。

陷阱 4：pattern（单数）与patterns（复数）是两个不同的命名空间

ReasoningBank 回退写入pattern；hooks_pretrain写入patterns。两者不可混用。

这四条警告已被smoke.sh第 4 项以 grep 断言固化，ruflo-plugin-creator README 的 "MCP-tool drift to avoid" 表格也做了摘要。深层契约在 ruflo-agentdb ADR-0001 与 ruflo-agentdb README §Namespace convention：

• 命名规范为 kebab-case<plugin-stem>-<intent>，如browser-sessions、browser-selectors；
• 三个保留命名空间不得遮蔽：pattern（ReasoningBank 回退写入）、claude-memories（Claude Code 自动记忆桥）、default（memory_store默认值）；
• 命名空间字符串只对memory_*与embeddings_search生效；
• 命名空间不得含:（与桥接层内部键分隔符冲突）、长度 ≤200 字符、必须通过validateIdentifier校验。

十一、可接线的 MCP 工具分类总览

脚手架阶段需要把 MCP 工具写进allowed-tools。技能给出的分类指引（可用mcp__plugin_ruflo-core_ruflo__transfer_plugin-info浏览全部可用工具）：

关于agentdb_*的"15 个工具"数字：ADR-0001 明确记录了一个漂移修复——旧文档声称"19 个 AgentDB controllers"，实际为 15 个agentdb_*MCP 工具（另约 29 个ControllerName条目）。不要在文档里硬编码控制器数量，运行期以agentdb_controllers的返回为准，这正是 smoke.sh 第 5 项回归检查的用意。

十二、市场集成与最终验证

脚手架最后一步：如果要把插件加入 ruflo 市场，更新 .claude-plugin/marketplace.json（本插件自身 v0.2.x 已按 ADR 记录列入市场）。ruflo 家族插件的 README 安装范式为：

/plugin marketplace add ruvnet/ruflo /plugin install ruflo-plugin-creator@ruflo

新插件安装后，用claude --plugin-dir ./plugins/<name>本地加载测试（见 plugin-developer agent）。发布前的完整检查链为：

# 1. 结构契约（smoke 即契约） bash plugins/<name>/scripts/smoke.sh # 期望输出：N passed, 0 failed # 2. 语义验证（validate-plugin skill 逐项断言） # 目录结构 / plugin.json schema / 自动发现 / 无遗留数组 / frontmatter / MCP 引用合法性 # 3. 本地加载冒烟 claude --plugin-dir ./plugins/<name>

十三、一张图看懂整个脚手架闭环

用本插件的自举案例收尾：ruflo-plugin-creator用 create-plugin 技能 产出新插件 → 新插件继承契约（ADR + smoke + README 四段）→ validate-plugin 技能 在发布前拦截结构问题 → smoke.sh 把契约固化为可执行断言 → MCP 漂移警告让新作者绕开四类历史 bug。整个流程保证了"新插件天生携带契约，无需事后返工"——这是该元插件区别于普通模板生成器的根本价值所在。

延伸阅读

• create-plugin 技能原文
• ruflo-plugin-creator README
• ADR-0001：脚手架即契约的设计决策
• smoke.sh：10 项结构检查脚本
• validate-plugin 技能
• agentdb 命名空间契约 与 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