企业官网建设流程全解析

ruflo-federation 插件契约解析（ADR-0001）：3-Gate 对齐、ADR-097 预算熔断、命名空间协调与 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/ruflo

本文以ruflo-federation插件的架构决策记录 ADR-0001 为核心脉络，完整解读跨安装（cross-installation）Agent 联邦通信层如何通过"契约化"工程手段收敛文档漂移、锚定安全门控设计、接入预算熔断并建立可自动验证的发布门禁。读完本文，你将掌握该插件的表面（Surface）构成、5 层信任模型、14 类 PII 检测管线与规范 3-Gate 模式的映射关系、ADR-097 预算电路断路器的参数语义，以及 10 项 smoke 契约检查的具体含义，并能直接基于仓库源码与配置文件复现每一项验证。

1. 契约的由来：ruflo-federation 的插件化演进

ruflo-federation（v0.2.0）是 ruflo 生态中负责跨安装 Agent 联邦通信的插件层：它自身不带 CLI MCP 工具，而是通过npx -y -p @claude-flow/plugin-agent-federation@latest驱动宿主侧的联邦运行时（npm 包驱动模式），对外暴露一套标准的插件表面。根据 README 与 ADR-0001，其表面由四部分组成：

随着会话内多款插件陆续建立各自的 ADR 契约（如ruflo-aidefence、ruflo-agentdb、ruflo-browser），ruflo-federation被审计出五类与既有节奏（cadence）不一致的契约缺口：

1. 缺少插件级 ADR—— 同批次更新的其他插件均已建立；
2. 缺少 smoke 测试—— 无法自动验证插件表面与文档承诺；
3. PII Pipeline 缺少规范锚点—— README 声称的 "PII Pipeline" 功能未交叉引用 ruflo-aidefence ADR-0001 所拥有的规范 3-Gate 模式。联邦的 PII 管线是更丰富的 14 类型检测，但本质上是同一 3-Gate 设计的特化，应服从规范契约；
4. 缺少命名空间协调—— 使用了federation命名空间，却未按 kebab-case 的<plugin-stem>-<intent>规则说明归属（或需论证"插件名即意图"这一特例）；
5. 缺少兼容性钉扎—— Compatibility 部分未包含 v3.6 钉扎。

ADR-0001 正是针对这五项缺口做出的正式决策记录，状态为Accepted，日期 2026-05-04，更新于 2026-05-09。

2. 决策内容：四项契约动作

ADR-0001 的 Decision 包含四条主线，覆盖文档、元数据与自动化验证三个层面：

1. 新增本 ADR（记录缺口与决策）；
2. README 增补四个区块：Compatibility（钉扎 v3.6）、Namespace coordination（认领federation命名空间并交叉引用 ruflo-agentdb ADR-0001 的命名空间约定）、3-Gate alignment 区块（声明联邦 PII 管线是规范 3-Gate 的丰富特化）、Verification 与 Architecture Decisions 区块；
3. 插件元数据保持节奏：ADR 决策时版本停留在0.2.0（已符合节奏），keywords 追加mcp、pii-pipeline、audit-log；仓库当前实际状态为 plugin.json 声明0.2.1并已携带上述三个新增关键词，同时保留了zero-trust、peer-discovery、consensus、circuit-breaker、budget、token-quota等原有标签；
4. 以scripts/smoke.sh作为契约门禁：10 项结构化检查（详见第 6 节），把"文档承诺"变成"可自动验证的不变量"。

3. 3-Gate 对齐：联邦 PII 管线的规范锚点

这是本 ADR 最核心的架构决策。规范 3-Gate 模式由 ruflo-aidefence ADR-0001 拥有，任何处理不可信内容的消费方插件都应按顺序套用三道门：

1. 存储前 PII 门（aidefence_has_pii）—— 在任何 AgentDB /memory_store写入之前执行；
2. 净化门（aidefence_scan）—— 针对 cookie、token、高熵 blob，采用"入保险库而非内嵌"策略；
3. 提示注入门（aidefence_is_safe）—— 针对任何回流给 LLM 的抽取内容。

ruflo-federation的 "PII Pipeline" 是这三道门的丰富特化，README 中的映射关系如下：

联邦在规范门之上扩展了自适应置信度校准（adaptive confidence calibration）与信任级别感知策略，但门序与意图与规范完全一致——新的联邦内容路径应直接按名称引用规范 3-Gate 模式，而不是重新推导。

该对齐决策的直接收益（ADR 原文 Consequences）是：实现者同时阅读两个插件时，不再需要调和两套不同的 "gate" 叙事；且 README 进一步注明，伴随aidefence@2.3.0升级（ADR-118），入站的aidefence_is_safe门（Gate 3）现在能捕获更广的注入面——ignore all previous instructions家族（0..4 修饰词窗口）、角色劫持（you are now …/act as …/pretend to be …）以及越狱标记（DAN mode/developer mode/god mode/root mode），联邦的自适应置信度校准会自动运行在这套更广的检测集之上，无需插件代码改动。

源码级佐证：Rust 侧的单进程联邦对等节点

3-Gate 对齐不仅是文档层面的交叉引用，在仓库的 Rust crate crates/ruflo-federation-peer/src/lib.rs 中有直接的实现映射。该 crate 将 QUIC 传输（midstreamer-quic）与 AIMDS 3-Gate 安全管线（aimds-detection/aimds-analysis/aimds-response）组合进单个 Rust 进程（文档注释注明为 ADR-120 Step 3），把此前 Node-bridge → Node-MCP → Rust-crate 的路径折叠为"一次联邦跳 + 一次飞行中 3-Gate 扫描 + stdio 交接给本地 Agent"。

其核心抽象SafetyVerdict恰好对应三道门的三种裁决：

pub enum SafetyVerdict { Pass, // 通过全部三道门，按原样转发 Block(String), // 门触发危险内容，隔离 + 写审计记录 Redact(FederationMessage), // 门净化了 PII / cookie / token，转发净化后的载荷 }

Peer::run()的入站循环严格遵循transport.recv() → gate.inspect() → dispatcher.dispatch()的管道：Block裁决的消息永远不进入dispatch（直接隔离并记录AIDefence gate blocked inbound message — quarantined日志），Redact则转发净化变体；出站send()同样先过门再发。crate 内测试run_quarantines_messages_that_the_gate_blocks验证了 Block 消息不会到达 dispatcher，aimds_gate_adapter_forwards_pass_and_block_verdicts则通过一个阻塞含secret载荷的模式门（PatternGate）验证AimdsGate适配器真实跑通上游aimds_core::SafetyGatetrait 面。这从实现层面印证了"联邦每一跳都过 3-Gate"的契约承诺。

4. ADR-097 预算熔断集成：从 send 侧强制到成本追踪

ADR-097（联邦预算电路断路器）解决的是联邦场景下的两类典型失控：递归委托环（A → B → A → … 无跳数计数器终止）与成本级联（一次小任务在远端触发子 swarm 调用昂贵前沿模型）。ruflo-federation将其作为插件内不变量接入了契约。

4.1 预算字段与默认值

/federation send接受可选的累计消费上限，使单次委托无法展开无界扇出（README 示例）：

/federation send <node-id> task-assignment '{"task":"…"}' \ --max-hops 4 \ --max-tokens 50000 \ --max-usd 0.25

校验层会前置拒绝NaN、±Infinity、负数以及非整数的跳数。错误以常量字符串形式返回（HOP_LIMIT_EXCEEDED、BUDGET_EXCEEDED、INVALID_BUDGET），且不携带剩余预算回显——这样恶意调用方无法把响应码当作"预言机"来探测配置阈值。该设计细节在 commands/federation.md 与federation-coordinatorAgent 的职责说明中均有明确要求。

4.2 三阶段实施节奏

需要说明的是，宿主侧的 ADR-097 实施状态（更新于 2026-05-09）记录该决策已端到端功能完成：Phase 1 预算信封（domain/value-objects/federation-budget.ts）、Phase 2.a 节点状态值对象（federation-node-state.ts，含 27 项单测）、Phase 2.b 熔断器服务（federation-breaker-service.ts，25 项单测，出站短路返回PEER_SUSPENDED/PEER_EVICTED常量错误）、Phase 3 成本追踪消费端（plugins/ruflo-cost-tracker/scripts/federation.mjs）与上游SpendReporter接口 +federation_report_spendMCP 工具、Phase 4 运维面（federation_breaker_status/federation_evict/federation_reactivate三个 MCP 工具 +ruflo doctor --component federation）。两处文档记录的节奏差异属于仓库内部不同视角的表述，阅读时以各自文档为准：插件 ADR-0001 与 README 从插件消费侧将 Phase 3 标注为 deferred，宿主 ADR-097 从实现侧记录各阶段已合入。

契约化带来的直接收益是：ADR-097 预算集成（即federation_send上限与ruflo-cost-trackerPhase 3 计划之间的交叉引用）从此成为被 smoke 检查的不变量——README 中必须出现maxHops、maxTokens、maxUsd、BUDGET_EXCEEDED、HOP_LIMIT_EXCEEDED这些关键标记，缺一即失败。

5. 命名空间协调：federation作为文档化的例外

AgentDB 命名空间约定（由 ruflo-agentdb ADR-0001 §"Namespace convention" 拥有）的默认规则是 kebab-case 的<plugin-stem>-<intent>。ruflo-federation认领的federation命名空间是这条规则的文档化例外：当插件名本身就是意图时，命名空间可以直接等于插件词干。

契约同时明确三条硬性约束：

• 保留命名空间不可遮蔽：pattern（ReasoningBank 回退写入）、claude-memories（Claude Code 自动记忆桥接目标）、default（memory_store默认）三个命名空间由 AgentDB 插件自身拥有，MUST NOT 被影子化；
• 命名护栏：命名空间不得包含:（与桥接层键内分隔符冲突）、长度必须 ≤200 字符、必须通过validateIdentifier校验；
• 路由语义：命名空间字符串仅作用于memory_*与embeddings_search路径；agentdb_*系列工具按控制器（ReasoningBank、层级记忆、因果图）路由，不消费命名空间参数。

federation命名空间通过memory_*工具（按命名空间路由）访问，用于存储四类联邦状态：对等节点注册表、信任分数历史、审计日志索引、消息信封回执。federation-initskill 的初始化事件写入即使用该命名空间：

mcp__plugin_ruflo-core_ruflo__memory_store({ key: "federation-init", value: "Node initialized", namespace: "federation" })

6. Smoke-as-Contract：10 项结构化检查逐条拆解

ADR 把"契约"落实为可执行的 scripts/smoke.sh。脚本以set -u严格模式运行，10 步检查全部通过时输出10 passed, 0 failed，任一失败则以非零退出码结束。逐条拆解如下：

其中第 10 项对应零信任的最小权限原则：三个 skill 的allowed-tools均为显式枚举——如federation-init授予Bash(npx *) mcp__plugin_ruflo-core_ruflo__memory_store mcp__plugin_ruflo-core_ruflo__hooks_post-task Read Write，federation-status授予Bash(npx *) mcp__plugin_ruflo-core_ruflo__memory_search Read，federation-audit授予Bash(npx *) mcp__plugin_ruflo-core_ruflo__memory_search Read Grep——通配授权会被第 10 步直接判负。

验证方式（README 与 ADR 的 Verification 一节完全一致）：

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

7. 配套设施：命令、技能、Agent 与信任模型

7.1/federation子命令与底层调用链

commands/federation.md 定义了 9 个子命令，每个子命令的底层动作都通过npx -y -p @claude-flow/plugin-agent-federation@latest ruflo-federation <subcommand>委托给宿主联邦运行时：

安装方式（README）：

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

7.2 5 层信任模型与行为评分

federation-coordinatorAgent（agents/federation-coordinator.md）负责持续信任评估，采用加权评分公式：

0.4×success_rate + 0.2×uptime + 0.2×(1-threat_penalty) + 0.2×data_integrity

信任级别从低到高共 5 级，能力随级别递增：

并定义了自动降级规则：1 小时内出现 2+ 次威胁检测、任何 HMAC 验证失败、或检测到会话劫持尝试时，立即将对等节点降级为UNTRUSTED。

7.3 合规审计模式

federation-auditskill（skills/federation-audit/SKILL.md）将合规模式作为一等公民：

8. 结果评估与实施状态

ADR-0001 的 Consequences 评估相当克制：

• 正面：联邦 PII 管线被契约锚定到规范 3-Gate 模式，跨插件实现者不再需要调和两套 gate 叙事；ADR-097 预算集成（federation_send上限与ruflo-cost-trackerPhase 3 计划之间的交叉引用）成为 smoke 检查的不变量。
• 负面：无——插件行为完全不变，本 ADR 是纯文档 + smoke 门禁动作。

实施状态（ADR 原文）：插件 v0.2.0 已发布并列入 marketplace；源码位于plugins/ruflo-federation/；契约要素已落地——ADR-097 预算电路断路器 Phase 1（send 侧强制）与 Phase 2（对等节点状态机）已文档化，Phase 3（ruflo-cost-tracker集成）deferred；通过 ruflo-aidefence ADR-0001 完成 3-Gate 对齐；smoke-as-contract 门禁定义于scripts/smoke.sh。仓库当前 plugin.json 已演进至0.2.1，新增关键词全部就位，与 smoke 第 1 步的期望一致。

9. 相关文档索引

• plugins/ruflo-aidefence/docs/adrs/0001-aidefence-contract.md —— 本插件所特化的规范 3-Gate 模式的归属方
• plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md —— 命名空间约定（含保留命名空间与护栏）
• plugins/ruflo-cost-tracker/docs/adrs/0001-cost-tracker-contract.md —— ADR-097 Phase 3 的集成目标（ADR 的 Related 一节引用）
• v3/docs/adr/ADR-097-federation-budget-circuit-breaker.md —— 宿主侧预算熔断的完整实现记录与接受标准
• v3/docs/adr/ADR-118-aidefence-2.3.0-upgrade.md —— Gate 3 注入面扩展的升级依据
• crates/ruflo-federation-peer/src/lib.rs —— 3-Gate 与联邦跳合一的 Rust 对等节点实现

通读本 ADR 及配套的 README、smoke 脚本与 Rust 实现后，一条清晰的工程主线浮现出来：文档承诺 → 规范交叉引用 → 机器可验证门禁。这正是"smoke-as-contract"这一插件契约范式的价值所在——它让安全模型（3-Gate）、成本治理（ADR-097）与命名空间治理（AgentDB 约定）不再是 README 里的软性表述，而是每次发布前必须通过的硬性检查。

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