企业官网建设流程全解析

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

导读

plugin-developer是 ruflo 仓库中 ruflo-plugin-creator 插件内置的插件开发专家 Agent，其职责是面向 Claude Code 生态，完成插件的脚手架（Scaffold）、格式验证（Validate）与市场发布（Publish）。本文以该 Agent 的职责说明文档为主体，结合仓库内 create-plugin 技能、validate-plugin 技能、ADR-0001 契约 与 smoke.sh 验证脚本 的源码级实现，完整还原一套可复制、可运行的 Claude Code 插件开发工作流。读完本文，你将掌握插件目录结构的正确形态、SKILL.md 的 frontmatter 规范、MCP 工具的接线规则、发布前的 10 项冒烟校验，以及如何借助 ruflo 的记忆与神经学习能力沉淀插件开发模式。

一、插件开发专家的角色定位

plugin-developer.md 通过 frontmatter 声明了该 Agent 的身份：name: plugin-developer，description: Plugin development specialist for scaffolding, validating, and publishing Claude Code plugins，并指定model: sonnet——这与 ruflo 插件体系中所有 Agent 文件的规范一致（见下方“关键规则”）。

该 Agent 的五大核心职责是：

1. Scaffold plugins—— 以正确的目录结构（plugin.json、skills/、commands/、agents/）生成新插件；
2. Write SKILL.md files—— 编写带规范 frontmatter（name、description、allowed-tools）的技能文件；
3. Wire MCP tools—— 将 ruflo MCP server 的工具接入 skill 的allowed-tools声明；
4. Validate plugins—— 对照官方 Claude Code 插件格式做校验；
5. Update marketplace—— 将新插件登记进marketplace.json实现分发。

从仓库结构看，这五个职责在 ruflo-plugin-creator 中被拆解为1 个 Agent + 2 个 Skill + 1 个 Command的轻量组合：create-plugin技能负责职责 1–3、validate-plugin技能负责职责 4，而/create-plugin命令（见 create-plugin.md）负责把整个过程串成交互式流程。

二、插件的关键规则与目录结构规范

2.1 六大关键规则

Agent 文档明确列出开发 Claude Code 插件时必须遵守的规则，任何一条违规都会导致校验失败：

需要注意一个关键演进：create-plugin 技能 第 4 步明确指出，生成的plugin.json只包含name、description、version、author，不要写入skills、commands、agents数组——因为 Claude Code 会从目录结构自动发现（auto-discover）这些内容，手动写入反而会触发验证错误。这一点与 validate-plugin 技能 的第 6 项检查（plugin.json中出现这三个数组即为校验错误）互为印证。因此，表格中“plugin.json 必须含数组”这一规则应理解为 Agent 文档早期版本的表述，当前仓库的实际契约以“自动发现、禁止显式数组”为准。

2.2 规范化插件目录结构（canonical contract）

ruflo-plugin-creator README 的 “Canonical plugin contract” 一节展示了每个被脚手架生成的插件都会继承的统一形态（该契约源自 ruflo 家族各插件各自的 ADR-0001，详见 ADR-0001-plugin-creator-contract）：

plugins/<name>/ ├── .claude-plugin/plugin.json # version、keywords、mcp keyword ├── 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 # ADR（Proposed）—— pinning、namespace、smoke 范围 ├── scripts/smoke.sh # 结构契约，≥8 项检查 └── README.md # Compatibility + Namespace coordination + Verification + ADR

也就是说，脚手架产出的不仅是“能跑”的插件，而是一个自带契约文档、冒烟测试与兼容性说明的完整工程单元。ADR-0001 对这套结构的定位是“scaffold-the-canonical-contract”：让新插件出生即带契约，而不是事后修补。

三、SKILL.md 的规范写法与 MCP 工具接线

3.1 frontmatter 三要素

Agent 文档要求每个 SKILL.md 具备name、description、allowed-tools三个 frontmatter 字段。create-plugin 技能 第 5 步给出了生成模板：

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

仓库中真实的例子是create-plugin技能自身的 frontmatter：

--- name: create-plugin description: Scaffold a new Claude Code plugin with proper directory structure, plugin.json, skills, commands, and agents argument-hint: "<plugin-name>" allowed-tools: mcp__plugin_ruflo-core_ruflo__transfer_plugin-info mcp__plugin_ruflo-core_ruflo__transfer_plugin-search mcp__plugin_ruflo-core_ruflo__transfer_store-search Bash Read Write Edit ---

可以看到它额外声明了argument-hint提示参数用法。其中mcp__plugin_ruflo-core_ruflo__transfer_plugin-info与mcp__plugin_ruflo-core_ruflo__transfer_plugin-search用于在生成前检查插件名是否已被占用（create-plugin 技能第 2 步），transfer_store-search用于冲突检测与检索。

3.2 allowed-tools 的接线原则：精确声明，禁止通配符

两条硬性要求：

• 每条 allowed-tools 必须列出实际使用的 MCP 工具，不能省略；
• 禁止使用通配符（如allowed-tools: *）。

validate-plugin技能与smoke.sh第 10 项检查（grep -q '^allowed-tools:[[:space:]]*\*'，见 smoke.sh）都会对这一点做校验。

3.3 可接线的 MCP 工具分类

create-plugin 技能 的 “Available MCP tools to wire” 一节列出了 ruflo MCP server 常见的工具族，供插件作者在allowed-tools中声明：

四、MCP 工具漂移陷阱：四类高频 Bug 及其规避

这是 create-plugin 技能 与 README 共同强调的重点章节——ruflo 家族多个插件曾上线后被自动化巡检发现上述接线错误，因此脚手架会为每个新插件内置“MCP-tool drift to avoid”警告段落。四类必须规避的漂移：

1. embeddings_embed不存在。真实工具是embeddings_generate。任何allowed-tools行里引用embeddings_embed都会失效（ruflo-knowledge-graph、ruflo-market-data曾修复此类引用，现已成为脚手架的警告项）。
2. agentdb_hierarchical-*不按 namespace 路由，它按 tier（working|episodic|semantic）路由。必须传tier而不是namespace；需要按 namespace 读写时改用memory_*。
3. agentdb_pattern-*不按 namespace 路由，它经由 ReasoningBank 路由。不要传namespace参数——回退写入会落到保留的patternnamespace（经memory-store-fallback）。
4. pattern（单数）与patterns（复数）是两个不同的保留 namespace。ReasoningBank 回退写入pattern，hooks_pretrain写入patterns，切勿混为一谈。

此外还有一条“19 个 AgentDB controllers”的陈旧说法：ADR-0001 记录，create-plugin技能早期文案声称存在 19 个控制器，而 ruflo-agentdb ADR-0001 证实真实数量为15 个agentdb_*MCP 工具、29 个ControllerName条目（详见 ruflo-agentdb README 的控制器注册表）。脚手架现在要求以agentdb_controllers运行时输出为准，并在 smoke.sh 第 5 项检查 中做回归检测，防止陈旧数字回潮。

关于 namespace 路由语义的底层佐证，可参考 ruflo-agentdb README 的 “Where namespace strings actually apply” 一节：memory_*与embeddings_search按 namespace 路由；agentdb_hierarchical-*、agentdb_pattern-*、agentdb_causal-edge均忽略 namespace 参数。向agentdb_pattern-store传namespace: 'browser-cookies'期望做过滤是无效的，参数会被静默丢弃。

五、插件验证：validate-plugin 的十项检查

Agent 文档职责 4 是“Validate plugins against the official Claude Code plugin format”，validate-plugin 技能 将其落实为 10 项具体检查：

执行步骤（validate-plugin 技能 “Steps” 一节）：先读plugin.json断言无三大数组；再 Globskills/*/SKILL.md、commands/*.md、agents/*.md逐个校验 frontmatter；随后逐技能检查必填字段与通配符；最后逐 Agent 检查 frontmatter，并输出每项检查的 pass/fail 与可操作的修复建议。

5.1 plugin.json schema 详解

create-plugin 技能 的 “Plugin.json schema” 一节给出了字段分级：

• 必填：name（kebab-case 插件标识）、description（功能描述）、version（semver 版本号）；
• 推荐：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——本插件会产生的关系类型。

仓库中 ruflo-plugin-creator 自身的 plugin.json 是上述 schema 的完整范例：name: ruflo-plugin-creator、version: 0.2.1、author指向 ruvnet、license: MIT，以及keywords数组（含mcp、scaffolding、contract-bootstrap）——这三个关键词正是 smoke.sh 第 1 项检查 要求存在的。

六、测试与验证：claude --plugin-dir与 smoke 契约

6.1 本地加载测试

Agent 文档给出的测试命令是：

claude --plugin-dir ./plugins/<name>

通过--plugin-dir指向插件根目录，即可在 Claude Code 中本地加载未发布的插件进行验证。/create-plugin命令（create-plugin.md）的第 4 步也提示用户“如何用claude --plugin-dir ./plugins/<name>测试”。

6.2 smoke.sh：契约即测试

ruflo 插件家族的验证哲学是“smoke as contract”——冒烟脚本就是插件契约的权威定义。ADR-0001（0001-plugin-creator-contract.md）为 ruflo-plugin-creator 自身定义了 10 项检查，smoke.sh 将其逐条实现：

运行方式与预期输出：

bash plugins/ruflo-plugin-creator/scripts/smoke.sh # Expected: "10 passed, 0 failed"

脚本通过grep断言版本号、关键词、文件存在性与 frontmatter 字段，并以PASS/FAIL计数，FAIL非零时以退出码 1 结束——任何一项检查失败都意味着插件契约被破坏，不得发布。对新脚手架出的插件，契约要求 smoke.sh 至少包含8 项结构检查（版本与关键词、skills/agents/commands 的存在性与 frontmatter、README 中的 v3.6 锁定、namespace 协调块、ADR 存在且状态为Proposed、技能无通配符工具）。

七、发布与市场登记

Agent 文档职责 5 是“Update marketplace by adding new plugins to marketplace.json”。完整发布链路为（create-plugin 技能 第 11 步与 README）：

1. 本地加载验证：claude --plugin-dir ./plugins/<name>；
2. 运行bash plugins/<name>/scripts/smoke.sh通过契约检查；
3. 若加入 ruflo 市场，将插件登记到marketplace.json；
4. 用户侧安装方式（ruflo-plugin-creator README）：

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

同时，新插件的 README 必须包含四个契约段落（由脚手架默认生成）：

• Compatibility—— 锁定@claude-flow/cliv3.6 major+minor，v3.6 内的 patch 升级视为 no-op；
• Namespace coordination—— 认领一个 kebab-case 的<plugin-stem>-<intent>namespace，并遵循 ruflo-agentdb 的 namespace 约定；
• Verification—— 提供bash plugins/<name>/scripts/smoke.sh验证命令；
• Architecture Decisions—— 链接到本插件的 ADR-0001。

八、记忆学习与神经学习：沉淀插件开发模式

Agent 文档的收尾部分给出了两条“学习回路”，把插件开发经验转化为可检索的知识资产。

8.1 Memory Learning（记忆学习）

在完成任务后，把成功的插件结构模式存入 ruflo 记忆，供模板迭代复用：

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

第一条命令把“某类型插件的结构与配置”写入plugin-patternsnamespace；第二条通过语义检索在同类任务中召回历史模式。从 ruflo-agentdb README 的命名约定看，plugin-patterns遵循<plugin-stem>-<intent>的 kebab-case 规范，且memory_*家族工具按 namespace 路由——这里传入--namespace plugin-patterns是正确用法。

8.2 Neural Learning（神经学习）

任务完成后将成功模式送入神经训练管线，并回查历史规律：

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

hooks post-task --train-neural会触发agentdb_pattern-store（ReasoningBank）写入——按照 ruflo-agentdb 的钩子集成约定（见 ruflo-agentdb README 的 Hook integration convention），该写入落到保留的patternnamespace，若 controller 注册表不可用则经memory-store-fallback回退到memory_store（响应中的controller: 'memory-store-fallback'表示数据已持久化而非错误）。第二条memory search --namespace patterns检索的是patterns（复数）——这正是前述“单复数陷阱”的现场：训练写入走pattern，检索语料走patterns，二者并存且不同。

8.3 底层支撑：可用的记忆与智能基础设施

这两条学习回路并非空壳：ruflo 家族提供了完整的底层支撑。memory store/memory search由memory_*MCP 工具族实现（默认 namespace 为default，另有claude-memories等保留 namespace，由 Claude Code 自动记忆桥在SessionStart/SessionEnd时自动填充）；神经训练路径涉及 SONA 模式蒸馏与hooks_*钩子系统。对于想要深入底层路由语义的插件作者，可以：

# 查看控制器实时注册表（真实的 controller 列表） mcp tool call agentdb_controllers --json # 查看当前桥接状态 mcp tool call memory_bridge_status --json

九、从零到一的完整流程串讲

把本文各章节串起来，一个插件从无到有的完整生命周期是：

1. 对话收集需求：/create-plugin命令询问插件名、描述、期望的 skills/commands/agents（create-plugin.md）；
2. 冲突检查：调用transfer_plugin-search确认插件名未被占用；
3. 脚手架生成：create-plugin技能按 canonical contract 生成完整目录——.claude-plugin/plugin.json、skills/、commands/、agents/、docs/adrs/0001-<name>-contract.md（Proposed）、scripts/smoke.sh（≥8 项检查）、README 四段落；
4. MCP 接线：按工具族清单填写各 SKILL.md 的allowed-tools，内置四类漂移警告防止踩坑；
5. 本地测试：claude --plugin-dir ./plugins/<name>加载验证；
6. 契约验证：validate-plugin技能跑 10 项结构检查，bash plugins/<name>/scripts/smoke.sh跑冒烟契约；
7. 发布登记：写入marketplace.json，用户经/plugin marketplace add+/plugin install安装；
8. 经验沉淀：memory store保存结构模式，hooks post-task --train-neural训练神经模式。

这套流程的价值在于：每个新插件出生即带完整契约（ADR + smoke + 兼容性说明 + namespace 协调），而非事后修补——这正是 ADR-0001 所定义的“scaffold-the-canonical-contract”原则的直接体现。

十、快速参考：核心文件索引

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