Cost Federation 是 ruflo 生态中成本追踪（cost-tracker）的消费端接线脚本，围绕 ADR-097 第三阶段设计的 federation_spend 事件总线工作。
用途 ADR-097 第三阶段定义了一个 federation_spend 事件总线：每当一次 federation_send 完成时，发布一个事件，格式为 {peerId, taskId, tokensUsed, usdSpent, ts}。Cost-tracker 是声明的事件消费者，负责按对等节点（peer）聚合滚动窗口（1h / 24h / 7d），联邦断路器（federation breaker）则查询该聚合结果，对超过配置阈值的对等节点执行挂起。
主要能力
- 消费 federation_spend 事件，按对等节点累计滚动窗口内的调用次数与花费美元金额。
- 输出每个对等节点的 1h / 24h / 7d 窗口统计。
- 提供“Suspension threshold check”区块，标记超过断路器阈值的对等节点。
- 当上游尚未发布事件时，干净地报告“no events found”。
使用方式 运行脚本： node plugins/ruflo-cost-tracker/scripts/federation.mjs
可选环境变量：
- FED_FORMAT=json — 输出 JSON 而非 markdown。
- FED_NAMESPACE=federation-spend — 覆盖目标命名空间。
- FED_SUSPEND_THRESHOLD_USD=5.0 — 断路器阈值（ADR-097 默认值）。
运行后检查每个对等节点的 1h / 24h / 7d 调用次数与美元花费窗口，以及标记超出断路器阈值的“Suspension threshold check”区块。
存储契约（消费端） 当第三阶段落地后，事件应持久化到命名空间 federation-spend，键前缀为 fed-spend-，JSON 值需匹配： { "peerId": "<peer-uuid>", "taskId": "<task-uuid>", "tokensUsed": 12345, "usdSpent": 0.0287, "ts": "2026-05-05T..." } 脚本会读取任何匹配该前缀的记录，无论上游如何产生它们。同一对等节点的多个事件会干净地累加进滚动窗口合计。
适用场景
- 在向新对等节点开放联邦流量之前，建立基线。
- 定期运行（例如 /loop 5m）以监控各对等节点跨窗口的支出。
- 在 ADR-097 第二阶段/第三阶段落地后，验证断路器挂起判断。
限制 ADR-097 第三阶段尚未在上游落地。此技能只是消费端接线，直到上游向 federation-spend 命名空间发布事件时才会激活；在此之前它会干净地报告“no events found”。
交叉引用
- ADR-097: Federation budget circuit breaker — 完整规范。
- cost-report — 相同数据、不同视角（cost-report 关注本地代理花费；本技能关注按对等节点的联邦花费）。
- ruflo-federation 插件 — 生产端（当第三阶段落地时）。