ruflo-plugin-creator 插件契约解析：ADR-0001、脚手架规范与 Smoke-as-Contract 落地实践

ruflo-plugin-creator 插件契约解析ADR-0001、脚手架规范与 Smoke-as-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/rufloruflo-plugin-creator 是 ruflo 插件家族中唯一的元插件meta-plugin它本身只有 1 个 agent、2 个 skills、1 个 command却负责为整个家族批量生成新插件——因此它产出的脚手架是什么形状未来每一个新插件就会继承什么形状。本文围绕仓库中的 ADR-0001 展开讲解把规范契约pinning、namespace 协调、MCP-drift 告警、smoke 即契约内置进脚手架的完整决策链并落到scripts/smoke.sh的 10 项可执行检查。读完你既能复现create-plugin的脚手架产物也能掌握这套ADR smoke Compatibility插件治理模式如何在 ruflo 家族中自举扩散。一、为什么需要一个插件契约ADRruflo 家族中每个插件都通过各自的 ADR-0001 采用了一套统一的插件契约包括pinning版本钉死在 README 的 Compatibility 段落声明所依赖的claude-flow/cli版本majorminornamespace coordination命名空间协调声明插件占用的命名空间且不遮蔽保留命名空间smoke as contract以冒烟测试作为契约scripts/smoke.sh是格式与结构的可执行验收标准sibling-ADR 交叉引用兄弟插件之间互相链接形成可追溯的证据链。ruflo-plugin-creator的独特之处在于每个由它脚手架生成的新插件都会继承脚手架产出的契约。因此 ADR-0001 必须同时做两件事让本插件自己也采用同一套契约否则样板工自己不合格更新脚手架输出让新插件生来就带契约而不是日后返工retrofit。这条 ADR 还顺手修复了一处漂移create-pluginskill 中曾写着19 AgentDB controllers这是 ruflo-agentdb ADR-0001 判定的过时神话——真实数字是 15 个agentdb_*MCP 工具、29 个ControllerName注册项。修复后的原则是任何数量都不应硬编码以运行时agentdb_controllers为准。二、被脚手架继承的规范契约scaffold-the-canonical-contractcreate-pluginskillskills/create-plugin/SKILL.md生成的标准目录结构如下plugins/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 ADR每个新插件生来必须具备四块契约内容Compatibility钉到claude-flow/cliv3.6 的 majorminorNamespace coordination声明一个 kebab-case 的plugin-stem-intent命名空间并遵循 ruflo-agentdb ADR-0001 的命名空间约定保留命名空间pattern、claude-memories、default不得遮蔽Verification给出bash plugins/name/scripts/smoke.sh作为验收命令Architecture Decisions链接到本插件的 ADR-0001。同时生成docs/adrs/0001-name-contract.md状态Proposed内容覆盖 pinning、namespace coordination、MCP 工具面数量如适用与 smoke 契约范围。plugin.json 生成要点create-plugin对plugin.json的生成有一条反直觉但关键的规则不要写入skills、commands、agents数组。Claude Code 会从目录结构自动发现这些组件显式声明反而会导致校验失败。必填字段只有namekebab-case、description、versionsemver推荐author、homepage、license、keywords可选字段graph_adapterADR-130 图智能契约默认注释掉在autoRegister: true时会让插件产生的边自动纳入graph_edges写入需声明edgeRelations。本插件自身的 plugin.json 即按此生成版本0.2.1keywords 含mcp、scaffolding、contract-bootstrap。三、MCP-tool drift脚手架内置的四类已知陷阱ADR-0001 的第 2 项决策是把整个循环loop在家族插件中反复修复的四类真实 MCP 集成 bug 变成脚手架里的显式告警区MCP-tool drift to avoid。create-plugin生成的每个新 skill 模板都会带上这些警示陷阱正确做法embeddings_embed不存在使用embeddings_generate_embed命名不存在见 embeddings-tools.ts 的embeddings_generate定义给agentdb_hierarchical-*传namespace参数它按tierworking\|episodic\|semantic路由不按 namespace 路由传tier带命名空间的读写请改用memory_*给agentdb_pattern-*传namespace参数它经 ReasoningBank 路由传了也会被忽略兜底写入保留命名空间patternmemory-store-fallback混淆pattern单数与patterns复数它们是不同的保留命名空间ReasoningBank 兜底写patternhooks_pretrain写patterns同类 bug 的实证可以对照兄弟 ADRruflo-cost-tracker ADR-0001 就记录了其cost-report/cost-optimize两个 skill 曾把namespace参数传给agentdb_hierarchical-recall与agentdb_pattern-store而被静默忽略的真实事故修复方式是改用 namespace 路由的memory_search/memory_store。ruflo-knowledge-graph、ruflo-market-data则分别修复过embeddings_embed引用。脚手架把这些教训固化下来新插件就不会再把同样的雷。与之配套的还有一条回归检查脚手架输出不得再出现19 AgentDB controllers 之类的硬编码数量统一改为调用运行时agentdb_controllers获取权威列表。四、Smoke-as-Contract10 项结构检查逐条拆解ADR-0001 的核心主张是以冒烟测试作为契约可执行脚本比散文更不容狡辩。本插件自带的 scripts/smoke.sh 定义了 10 项检查ADR 决策部分的 3 条对应关系如下plugin.json 声明0.2.1且含新关键字——校验mcp、scaffolding、contract-bootstrap三个 keyword注意ADR 决策时写0.2.0实施后实际 bump 到0.2.1以脚本为准两个 skill agent command 齐备且 frontmatter 合法——create-plugin、validate-plugin的 SKILL.md 必须含name:、description:、allowed-tools:同时存在agents/plugin-developer.md与commands/create-plugin.mdcreate-plugin会脚手架出规范契约——SKILL.md 中必须出现docs/adrs/0001-、scripts/smoke.sh、Compatibility、Namespace coordination四处create-plugin含 MCP-drift 告警——校验embeddings_embed、agentdb_hierarchical.*namespace、agentdb_pattern.*namespace/ReasoningBank routes、单复数pattern(s)告警文案都在19 controllers 回归检查——SKILL.md 中不得再出现 19 AgentDB controllers 或 19 controllersREADME 钉住claude-flow/cliv3.6README 含## Architecture Decisions章节ADR-0001 存在且状态为AcceptedADR 从Proposed升级为Accepted脚本用grep -E ^status:[[:space:]]*Accepted判定validate-pluginskill 存在任何 skill 都不允许通配符工具授权——allowed-tools:行不得以*开头。脚本运行方式与期望输出与 ADR 的 Verification 段落一致bash plugins/ruflo-plugin-creator/scripts/smoke.sh # Expected: 10 passed, 0 failed脚本本身只用了grep、set -u与简单的计数逻辑无外部依赖任何 CI 环境都能直接跑任一检查失败都会exit 1。这正是smoke 即契约的用意把插件结构的验收标准变成一条命令。五、脚手架工作流从 create 到 validate 到发布把 ADR 与 skill 拼起来一条完整的新插件生产线是交互收集——/create-plugin命令commands/create-plugin.md向用户收集插件名、描述、所需 skills/commands/agents查重——create-pluginskill 先调用mcp__plugin_ruflo-core_ruflo__transfer_plugin-search确认名字未被占用脚手架——按上文目录结构生成全部文件含契约四件套与 drift 告警校验——validate-pluginskillskills/validate-plugin/SKILL.md做 10 项检查plugin.json存在与 schema、skills/commands/agents 自动发现、不得存在 legacy 数组、frontmatter 完整性、文件位置正确性、allowed-tools中的工具必须是合法的mcp__plugin_ruflo-core_ruflo__*标识符本地试跑——claude --plugin-dir ./plugins/name验证插件可加载见 agents/plugin-developer.md更新 marketplace.json——若加入 ruflo marketplace 则登记发布。plugin-developeragent 还自带记忆沉淀流程成功模式可写入--namespace plugin-patterns供后续模板持续改进——这与 ruflo 家族的 memory/neural 基础设施天然打通。六、契约扩散与后续影响ADR-0001 的 Consequences 很克制地指出了两面性正面未来新插件生来继承规范契约循环正在做的批量返工对新插件不再必要四类 MCP-drift bug 从反复发现变成脚手架即告警插件加入家族节奏cadence负面已存在的旧脚手架不会自动更新仍需循环按插件逐一 retrofitt该工作在 ADR 记录时已基本完成。从实施状态看插件 v0.2.1 已发布并列入 marketplace.json契约要素均已落地脚手架模板默认包含契约 ADR、smoke 测试、Compatibility 段、namespace coordination 块drift 告警已写入脚手架 skill 模板scripts/smoke.sh定义了 smoke-as-contract 门禁。这套模式的深层逻辑值得单独提炼ruflo 把规范从文档劝诫升级为生成器默认输出 可执行检查两层约束。文档层由 README 的 Compatibility / Namespace coordination / Verification / Architecture Decisions 四段构成执行层由 ≥8 项本插件 10 项的smoke.sh把关二者再通过 ADR 交叉引用形成证据网。兄弟插件的契约如 ruflo-agentdb 的命名空间约定、ruflo-cost-tracker 的 namespace-routing bug 类互为支撑——plugin-creator 正是这条契约链上的自举点它把整个家族验证过的规则一次性写入每一代新插件。【免费下载链接】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），仅供参考