ruflo-federation 插件契约解析ADR-00013-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-installationAgent 联邦通信层如何通过契约化工程手段收敛文档漂移、锚定安全门控设计、接入预算熔断并建立可自动验证的发布门禁。读完本文你将掌握该插件的表面Surface构成、5 层信任模型、14 类 PII 检测管线与规范 3-Gate 模式的映射关系、ADR-097 预算电路断路器的参数语义以及 10 项 smoke 契约检查的具体含义并能直接基于仓库源码与配置文件复现每一项验证。1. 契约的由来ruflo-federation 的插件化演进ruflo-federationv0.2.0是 ruflo 生态中负责跨安装 Agent 联邦通信的插件层它自身不带 CLI MCP 工具而是通过npx -y -p claude-flow/plugin-agent-federationlatest驱动宿主侧的联邦运行时npm 包驱动模式对外暴露一套标准的插件表面。根据 README 与 ADR-0001其表面由四部分组成表面元素名称说明Agentfederation-coordinator编排发现、握手、信任评估与安全消息路由Skillfederation-init/federation-status/federation-audit节点初始化、健康检查、合规审计日志查询Command/federation子命令分发器init/join/leave/peers/send/status/audit/trust/config文档README完整记录 ADR-097 预算电路断路器与各功能区块随着会话内多款插件陆续建立各自的 ADR 契约如ruflo-aidefence、ruflo-agentdb、ruflo-browserruflo-federation被审计出五类与既有节奏cadence不一致的契约缺口缺少插件级 ADR—— 同批次更新的其他插件均已建立缺少 smoke 测试—— 无法自动验证插件表面与文档承诺PII Pipeline 缺少规范锚点—— README 声称的 PII Pipeline 功能未交叉引用 ruflo-aidefence ADR-0001 所拥有的规范 3-Gate 模式。联邦的 PII 管线是更丰富的 14 类型检测但本质上是同一 3-Gate 设计的特化应服从规范契约缺少命名空间协调—— 使用了federation命名空间却未按 kebab-case 的plugin-stem-intent规则说明归属或需论证插件名即意图这一特例缺少兼容性钉扎—— Compatibility 部分未包含 v3.6 钉扎。ADR-0001 正是针对这五项缺口做出的正式决策记录状态为Accepted日期 2026-05-04更新于 2026-05-09。2. 决策内容四项契约动作ADR-0001 的 Decision 包含四条主线覆盖文档、元数据与自动化验证三个层面新增本 ADR记录缺口与决策README 增补四个区块Compatibility钉扎 v3.6、Namespace coordination认领federation命名空间并交叉引用 ruflo-agentdb ADR-0001 的命名空间约定、3-Gate alignment 区块声明联邦 PII 管线是规范 3-Gate 的丰富特化、Verification 与 Architecture Decisions 区块插件元数据保持节奏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等原有标签以scripts/smoke.sh作为契约门禁10 项结构化检查详见第 6 节把文档承诺变成可自动验证的不变量。3. 3-Gate 对齐联邦 PII 管线的规范锚点这是本 ADR 最核心的架构决策。规范 3-Gate 模式由 ruflo-aidefence ADR-0001 拥有任何处理不可信内容的消费方插件都应按顺序套用三道门存储前 PII 门aidefence_has_pii—— 在任何 AgentDB /memory_store写入之前执行净化门aidefence_scan—— 针对 cookie、token、高熵 blob采用入保险库而非内嵌策略提示注入门aidefence_is_safe—— 针对任何回流给 LLM 的抽取内容。ruflo-federation的 PII Pipeline 是这三道门的丰富特化README 中的映射关系如下规范门联邦特化存储前 PIIaidefence_has_pii14 类型 PII 检测 按信任级别执行BLOCK/REDACT/HASH/PASS策略净化aidefence_scan出站 HMAC 签名信封 双重 AI Defence 门提示注入aidefence_is_safe入站消息在投递给本地 Agent 前进行验证联邦在规范门之上扩展了自适应置信度校准adaptive confidence calibration与信任级别感知策略但门序与意图与规范完全一致——新的联邦内容路径应直接按名称引用规范 3-Gate 模式而不是重新推导。该对齐决策的直接收益ADR 原文 Consequences是实现者同时阅读两个插件时不再需要调和两套不同的 gate 叙事且 README 进一步注明伴随aidefence2.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 消息不会到达 dispatcheraimds_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字段缺省值说明maxHops80完全禁止远端委托硬上限 64maxTokens无界整个跳链的 Σ tokens硬上限 10 亿maxUsd无界各跳 Σ USD硬上限 100 万美元hopCount0被转发的消息的透传起点spent.{tokens,usd}0上一跳调用方上报的用量负数钳制为 0校验层会前置拒绝NaN、±Infinity、负数以及非整数的跳数。错误以常量字符串形式返回HOP_LIMIT_EXCEEDED、BUDGET_EXCEEDED、INVALID_BUDGET且不携带剩余预算回显——这样恶意调用方无法把响应码当作预言机来探测配置阈值。该设计细节在 commands/federation.md 与federation-coordinatorAgent 的职责说明中均有明确要求。4.2 三阶段实施节奏阶段内容状态插件视角Phase 1send 侧强制执行预算信封 跳数计数器已落地Phase 2对等节点状态机ACTIVE/SUSPENDED/EVICTED已文档化Phase 3ruflo-cost-tracker集成统一消费上报插件 README 标注为后续发布需要说明的是宿主侧的 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.ts25 项单测出站短路返回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命名空间是这条规则的文档化例外当插件名本身就是意图时命名空间可以直接等于插件词干。契约同时明确三条硬性约束保留命名空间不可遮蔽patternReasoningBank 回退写入、claude-memoriesClaude Code 自动记忆桥接目标、defaultmemory_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-Contract10 项结构化检查逐条拆解ADR 把契约落实为可执行的 scripts/smoke.sh。脚本以set -u严格模式运行10 步检查全部通过时输出10 passed, 0 failed任一失败则以非零退出码结束。逐条拆解如下#检查项实质内容1插件版本与关键词plugin.json声明0.2.1且必须包含mcp、pii-pipeline、audit-log三个关键词2表面完整性3 个 skillfederation-init/federation-status/federation-audit的SKILL.md均含name:/description:/allowed-tools:前置元数据federation-coordinator.md与federation.md存在3ADR-097 预算区块README 必须包含maxHops、maxTokens、maxUsd、BUDGET_EXCEEDED、HOP_LIMIT_EXCEEDED45 层信任模型README 必须逐级出现UNTRUSTED→VERIFIED→ATTESTED→TRUSTED→PRIVILEGED5合规模式README 必须文档化HIPAA、SOC2、GDPR6CLI 钉扎README 必须将claude-flow/cli钉扎到 v3.6majorminor7命名空间约定README 必须引用ruflo-agentdb及其 Namespace convention 章节83-Gate 对齐README 必须出现 3-gate 类表述并交叉引用ruflo-aidefence9ADR 状态docs/adrs/0001-federation-contract.md存在且 status 为Accepted10最小权限任何 skill 的allowed-tools不得是通配符*其中第 10 项对应零信任的最小权限原则三个 skill 的allowed-tools均为显式枚举——如federation-init授予Bash(npx *) mcp__plugin_ruflo-core_ruflo__memory_store mcp__plugin_ruflo-core_ruflo__hooks_post-task Read Writefederation-status授予Bash(npx *) mcp__plugin_ruflo-core_ruflo__memory_search Readfederation-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 failed7. 配套设施命令、技能、Agent 与信任模型7.1/federation子命令与底层调用链commands/federation.md 定义了 9 个子命令每个子命令的底层动作都通过npx -y -p claude-flow/plugin-agent-federationlatest ruflo-federation subcommand委托给宿主联邦运行时子命令用途底层调用init生成密钥对并初始化联邦ruflo-federation initjoin endpoint连接联邦对等节点ruflo-federation join ENDPOINTleave优雅退出联邦ruflo-federation leavepeers列出已知节点及信任级别ruflo-federation peerssend node-id msg-type payload发送消息可携带预算控制ruflo-federation send NODE_ID MSG_TYPE PAYLOAD [--max-hops N] [--max-tokens N] [--max-usd N] [--hop-count N] [--spent-tokens N] [--spent-usd N]status展示联邦健康、会话与指标ruflo-federation statusaudit按合规模式 / 日期查询审计日志ruflo-federation audit --compliance MODE --since DATEtrust node-id查看信任分数明细ruflo-federation trust NODE_ID --reviewconfig配置 PII 策略与合规模式ruflo-federation config --pii-policy PATH安装方式README/plugin marketplace add ruvnet/ruflo /plugin install ruflo-federationruflo7.2 5 层信任模型与行为评分federation-coordinatorAgentagents/federation-coordinator.md负责持续信任评估采用加权评分公式0.4×success_rate 0.2×uptime 0.2×(1-threat_penalty) 0.2×data_integrity信任级别从低到高共 5 级能力随级别递增级别名称能力0UNTRUSTED仅发现1VERIFIED状态、ping2ATTESTED收发任务、查询记忆脱敏3TRUSTED共享上下文、协作执行4PRIVILEGED完整记忆、远端 Agent 派生并定义了自动降级规则1 小时内出现 2 次威胁检测、任何 HMAC 验证失败、或检测到会话劫持尝试时立即将对等节点降级为UNTRUSTED。7.3 合规审计模式federation-auditskillskills/federation-audit/SKILL.md将合规模式作为一等公民模式记录内容HIPAA完整审计轨迹、日志中不落 PII、PHI 检测、6 年留存SOC2访问控制事件、变更管理、可用性监控GDPR数据处理记录、同意追踪、被遗忘权、数据驻留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 1send 侧强制与 Phase 2对等节点状态机已文档化Phase 3ruflo-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考