ruflo-cost-tracker 实现演进全解析从 v0.4 到 v0.15 补齐生产者缺口的十一项落地自动采集 · 预算熔断 · 模型结果反馈 · 可观测性 · 联邦消费【免费下载链接】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-cost-tracker 是 ruflo 生态中负责 token 用量追踪、按模型/Agent 归因成本、预算告警与优化建议的插件。本文以 ADR-0003 — Implementation arc v0.5 → v0.15 为主体完整还原该插件从只会读命名空间、从不写入数据到拥有真实生产者与四重视角消费端的演进全过程十一项按优先级实施的插件本地提交、每项背后的动机、实测基准、源码级落地机制以及作者刻意保留的风险假设与延期项。读完你不仅能理解cost track、cost budget check、cost outcome、cost export、cost federation、cost summary等一系列命令的设计意图还能掌握以 smoke 契约驱动插件演进这一可复用的工程方法。一、背景一个只消费而不生产的成本追踪插件在 ADR-0003 之前的演进线上插件已经解决了两个基础问题ADR-0001v0.2.2修复命名空间路由。此前cost-report/cost-optimize两个技能误用agentdb_hierarchical-recall/agentdb_pattern-store并附带namespace参数而这两个工具族分别按tier与ReasoningBank路由命名空间参数会被静默忽略。ADR-0001 将加载路径切换到memory_*工具族memory_search/memory_list/memory_retrieve/memory_store详见 0001-cost-tracker-contract.md。ADR-0002v0.3.0–v0.4.0接入 Agent Booster 与 agentic-flow 能力面新增cost-booster-route、cost-compact-context技能并规划了hooks_model-outcome反馈回路与 tier 感知报告详见 0002-agentic-flow-and-agent-booster-integration.md。但 ADR-0003 开篇就点出一个最尴尬的缺口该插件当时几乎完全是一个cost-trackingAgentDB 命名空间的消费者——插件内没有任何东西真正向这个命名空间写入数据每个技能都在空数据上工作。插件文档承诺的按 Agent/模型归因 USD 成本从未真实发生cost-report从空命名空间读不到任何会话记录cost-optimize拿不到任何可分析的模式。这就是 ADR-0003 要解决的生产者缺位问题也是整个 v0.4.0 → v0.15.0 实现弧的起点。插件的数据模型同样值得先交代清楚见 README 的Namespace coordination命名空间用途消费方cost-tracking会话用量记录按会话一个 keycost-report、cost-budget-check、cost-summary等cost-patterns优化建议模式cost-optimize二者遵循 ruflo-agentdb ADR-0001 定义的 kebab-caseplugin-stem-intent命名约定且都经由按命名空间路由的memory_*工具族访问参见 ruflo-agentdb ADR-0001。保留命名空间pattern、claude-memories、default严禁被遮蔽。二、决策十一项优先级 实测基线ADR-0003 的决策是将十一项待办按优先级拆成独立的插件本地提交每项都伴随版本号递增与 smoke 契约扩展而不是一次性大改。同时ADR 记录了一份新鲜实测基准2026-05-05corpus v3 25 个用例、4 个端点用于为后续每项改动提供可对照的基线端点Tier 1 胜率对抗用例正确率平均延迟成本/编辑相对 Booster 加速Agent BoosterWASM18/18升级escalate7/70.36 ms$0—Gemini 2.0 Flash18/183/7807.56 ms$0.0000282243×Claude Sonnet 4.618/182/71270.64 ms$0.0009333530×Claude Opus 4.718/185/71563.72 ms$0.0059434344×这份表格的解读要点在于四个端点都能在 18 个 Tier 1 用例上全胜但面对 7 个对抗用例expectedTier1: false只有 Agent Booster 能正确地拒绝——全部升级escalate给上层模型而 Sonnet 4.6 只答对 2/7、Opus 4.7 只答对 5/7。也就是说Booster 的质胜正确拒绝不仅是速度优势这也是后续cost-trend把escalationRate升级率纳入漂移监控的原因。实施顺序与动机完整清单P1 —cost-trackv0.5.0最尴尬缺口的直接修补。读取~/.claude/projects/encoded-cwd/session.jsonl按模型累加每条消息的usage持久化到cost-tracking命名空间。没有它其余所有技能都只能操作空数据。P2 —cost-budget-checkv0.6.0README 早就文档化了 50/75/90/100% 告警阶梯但没有任何代码强制执行。该版本把生产者cost track与消费者budget check真正接通并落地HARD_STOP时的fail-closed exit-1路径。P3 — 自动发射hooks_model-outcomev0.7.0cost-optimize的第 8 步原本只是散文描述。用包装脚本outcome.mjs与cost outcome子命令替代让已应用的建议真正训练路由器。P4 —compact.mjsv0.8.0从cost-compact-context中移除内联的node --input-typemodule -e ...块改为独立脚本真正注册 MCP 工具修改claude-flow/cli源码被刻意推迟。P5 —cost-trendv0.9.0二元制的 smoke 门槛抓不到曲线。cost-trend横跨所有runs/*.json展示漂移——门槛抓不到的回归它能抓。P7 — corpus v2 → v3v0.10.0新增expectedTier1字段与 7 个对抗用例。胜率从此有意义v1 语料上所有端点 100% 胜率是重言式。P8 — GitHub Actionsv0.11.0每个 PR 跑 smoke 仅 Booster 的基准LLM/Anthropic 基线被刻意排除在 CI 之外成本护栏。P11 —cost-conversationv0.12.0按会话视角与cost-report的按 Agent / 按模型是不同聚合轴。P10 —cost-exportv0.13.0Prometheus textfile collector webhook POST接通外部可观测性。P6 —cost-federationv0.14.0接通 ADR-097 Phase 3 消费者上游一发事件即激活。P9 —cost-summaryv0.15.0提供稳定的程序化 JSON 契约供跨插件消费。三、源码级拆解每项落地的机制与依据下面结合 plugins/ruflo-cost-tracker/scripts 下的真实实现逐项看关键机制。P1 ·track.mjs从会话 JSONL 到命名空间的生产者cost-track的实现位于 scripts/track.mjs核心链路分三步定位项目目录encodeProjectPath第 25–32 行把工作目录编码为~/.claude/projects/下的子目录名。编码规则是把路径分隔符和 Windows 盘符冒号都替换为-POSIX 的/home/user/proj→-home-user-projWindows 的D:\project\Subcloudy→D--project-Subcloudy:与\均转-。这是对 issue #1927 的修复——旧代码只替换/对 Windows 路径是空操作。选取会话文件findActiveSession第 39–45 行扫描该目录下所有.jsonl按 mtime 取最近修改者可用TRACK_SESSION环境变量钉死某个会话。汇总与持久化summarizeSession第 47–93 行逐行解析 JSONL只统计type assistant且带message.usage的消息按模型聚合 input/output/cache-write/cache-read token 并调用costForUsage折算 USD同时按 tierhaiku/sonnet/opus/unknown汇总随后persistToMemory第 95–117 行以session-sessionId为 key、cost-tracking为命名空间执行memory store。关键环境变量均可用于日常调试变量作用TRACK_CWD覆盖要扫描的项目目录默认当前工作目录TRACK_SESSION钉住特定会话 jsonlTRACK_OUT额外把 JSON 摘要写到指定路径TRACK_DRY_RUN1跳过memory_store调用TRACK_QUIET1抑制 Markdown 摘要输出TRACK_NAMESPACE覆盖命名空间默认cost-trackingCLI_CORE1走 cli-core 轻量路径冷缓存耗时从约 25s 降到约 2s值得注意的实现细节track.mjs用spawnNpxSync显式传参执行memory store避免 JSON 值经 shell 拼接时的转义陷阱而CLI_CORE1路径ADR-100/#1748换用 JSON 后端语义检索退化为子串匹配——对从不调用 search、只用 store/list/retrieve 的 cost-track 完全够用。P2 ·budget.mjs四级告警阶梯与 fail-closed 语义scripts/budget.mjs 提供set/get/check三个子命令其中alertLevel第 101–107 行实现 README 承诺的告警阶梯级别利用率阈值动作OK 50%预算内无动作INFO≥ 50%记录日志通知WARNING≥ 75%展示警告建议运行/cost-optimizeCRITICAL≥ 90%紧急告警建议模型降级HARD_STOP≥ 100%停止非必要 agent 派发exit 1机制上有两个易被忽略但极其关键的点fail-closed 语义cmdCheck末尾第 201 行在alert.level HARD_STOP时process.exit(1)且该逻辑位于BUDGET_QUIET1两个分支之后第 183–198 行的注释明确这是 iter 75 的回归修复——此前return console.log(JSON.stringify(out))在 alert 计算后提前返回会吞掉 HARD_STOP导致cost-health复合门失效。这让budget check spawn …成为机械化的防护模式昂贵操作前先检查预算超限即失败关闭。UNIQUE 约束 workaroundclaude-flow/cli的 memory 层存在store拒绝retrieve看不到的 key的不一致上游 bug。budget.mjs的解决方式是每次写入带时间戳的 keybudget-config-ms第 38–49 行读取时列出所有budget-config-\dkey 取字典序最大者第 66–90 行作为当前指针。这是 ADR 明确标注可用但反映上游 bug、应另立 ADR 修复的工作区。BUDGET_PERIODtoday|week|month|all可过滤会话汇总的时间窗口BUDGET_QUIET1输出纯 JSON 供机器消费。P3 ·outcome.mjs让优化建议真正训练路由器scripts/outcome.mjs 是hooks model-outcome的薄包装node scripts/outcome.mjs task-description model outcome其中outcome严格限定为success | escalated | failure第 20 行ALLOWED集合 第 29–32 行校验。它通过spawnSync显式传参调用claude-flow/cli hooks model-outcome -t task -m model -o outcome从而保留任务描述中的引号/换行——这是为什么需要包装的注释第 14–16 行给出的动机hooks model-outcome本身用-t -m -o短参走 shell 管道时引用极易出错。这一闭环的意义在于cost-optimize推荐把 reviewer 降级到 haiku后应用结果的成败success / escalated / failure正是hooks_model-outcome要记录的路由信号。没有它路由器的推荐不会随时间收敛——ADR-0002 把它定位为成本优化的复合杠杆不直接省 token但会持续提升cost-booster-route的 Tier 1 分流率。P4 ·compact.mjs去掉内联 Node 一行命令ADR-0002 曾把getTokenOptimizer().getCompactContext()的调用写进技能的Bash一行命令node --input-typemodule -e ...。P4 将其提取为 scripts/compact.mjs用createRequire在工作目录上下文解析claude-flow/integration对检索压缩查询做安全封装agentic-flow 未安装时优雅降级bridge 返回tokensSaved: 0。smoke 第 37 步专门断言技能里不再残留node --input-typemodule -e内联块。真正的 MCP 工具注册如token_optimize_compact被 ADR-0002 明确列为风险最大假设并推迟——原因是要改v3/claude-flow/cli/src/mcp-tools/超出插件本地范围。P5 ·trend.mjs二元门槛之外的漂移曲线scripts/trend.mjs 读取docs/benchmarks/runs/*.json跳过latest.json按 mtime 排序后输出胜率、平均延迟、p99 延迟、升级率、相对 Gemini 加速比的首 vs 末漂移摘要以及逐 run 序列。关键设计按基准系列隔离BENCH_NAME环境变量指定要跟踪的系列未指定时只显示 legacy booster runsbenchmark booster或未打标签避免codemod-tier1等其他基准污染 Booster 漂移曲线。回归标记规则第 130–138 行末次胜率低于首次即报回归平均延迟超过首次 1.5× 即报警。这就是 ADR 说的门槛抓不到曲线——smoke 是二元的过/不过趋势是连续的量变。输出支持TREND_FORMATjson机器可读格式与TREND_LIMITN最近 N 次限制。P7 · 语料 v3让胜率不再是重言式corpus v325 个用例见 bench/booster-corpus.json给每个用例增加expectedTier1字段18 个应走 Tier 1expectedTier1 ! false、7 个对抗用例expectedTier1 false。在 v1 语料上所有端点 100% 胜率是因为语料本身没有区分度加入对抗用例后正确拒绝成为与正确执行并列的质量维度。smoke 第 24 步在 CI 层面对语料形状做了硬断言≥18 个 Tier 1、≥6 个对抗、总数 ≥25。P8 · GitHub ActionsCI 的成本护栏每个触碰本插件的 PR 都会在 GitHub Actions 上运行 smoke 仅 Booster 的基准 回归门Tier 1 winRate ≥ 0.80见 smoke 第 23 步对latest.json的断言。LLM 与 Anthropic 基线明确不跑——每次调用都花真金白银属于手动/定时工作流范畴用BENCH_LLM_BASELINE1 BENCH_ANTHROPIC1显式开启。smoke 第 40 步还反向校验了工作流文件本身必须调用smoke.sh与bench.mjs、包含 winRate 回归门、且不得含BENCH_ANTHROPIC/BENCH_LLM_BASELINE防止 CI 偷偷引入高成本基线。P11 ·conversation.mjs另一根聚合轴scripts/conversation.mjs 提供按会话/对话视角的成本视图——与cost-report的按 Agent / 按模型是正交的聚合维度。它复用_sessions.mjs的memoryListSessionKeys与按 tier 聚合逻辑回答某次对话花了多少钱这类问题。P10 ·export.mjs外部可观测性出口scripts/export.mjs 支持三种出口--prometheus path写 Prometheus textfile collector 格式文件--webhook urlPOST JSON 载荷支持EXPORT_WEBHOOK_HEADER传递鉴权头逗号分隔可重复无参数JSON 打到 stdout。Prometheus 指标族第 59–104 行覆盖 6 种以上类型cost_tracker_total_usd # 总成本 gauge cost_tracker_tier_total_usd{tier} # 按 tier 成本 cost_tracker_session_total_usd{session} # 按会话成本 cost_tracker_session_messages{session} # 按会话消息数 counter cost_tracker_tokens_total{tier,type} # 按 tier×token 类型input/output/cache_write/cache_read cost_tracker_budget_usd / cost_tracker_budget_utilization # 预算与利用率其中cost_tracker_tokens_total的typecache_write维度是刻意加上的源码注释 iter 83 明确其动机此前看板只能看到haiku 花了 $X无法切出opus 上的 cache_write 增长——而569 个输出 token 却花 $16这类异常消息本质就是 cache-write 成本只有按 token 类聚合才能暴露。P6 ·federation.mjsADR-097 Phase 3 消费者scripts/federation.mjs 实现 ADR-097 Phase 3 的消费端契约从federation-spend命名空间读取fed-spend-peerId-ts键事件形状{peerId, taskId, tokensUsed, usdSpent, ts}按 peer 聚合1h / 24h / 7d滚动窗口并对照默认 $5/24h 的挂起阈值FED_SUSPEND_THRESHOLD_USD可调标记超限 peer。输出phase3Active: events.length 0让脚本自述当前是否已激活——因为 Phase 3 上游尚未发射事件时命名空间为空脚本优雅报告等待上游而不是报错。P9 ·summary.mjs稳定的程序化 JSON 契约scripts/summary.mjs 提供--format json|markdown的一次性全量导出其 JSON 形状是稳定契约文件头注释明确列出字段{ exportedAt, git, // git: {sha, shaShort, branch, isDirty} — 快照可追溯 total_cost_usd, sessionCount, conversationCount, byTier, byModel, byTokenClass, // byTokenClass: {input, output, cache_write, cache_read} topSession, budget, federation // budget: {budget_usd, spent_usd, utilization, level} }两个亮点captureGitContext第 37–56 行best-effort 抓取 git sha/分支/脏工作区状态让cost-diff做快照对比时能直接展示baseline 在 sha X、当前在 sha YbyTokenClass把 cache_write 作为独立成本驱动暴露在汇总层iter 84避免在聚合层掩盖 iter-82 那类 bug。这份契约正是 ADR-0002 中考虑但明确推迟的 MCP 工具cost_summary的插件本地等价物——其他插件只需node summary.mjs --format json再解析即可。四、数据与契约的底层支撑定价单一事实源_prices.mjsscripts/_prices.mjs 把散落在 5 个脚本里的定价表收敛为一处iter 31并导出PRICING、modelTier、costForUsage、costAtTier。其定价USD / 1M tokens与 REFERENCE.md 保持同步模型InputOutputCache WriteCache ReadHaiku$0.25$1.25$0.30$0.03Sonnet$3.00$15.00$3.75$0.30Opus$15.00$75.00$18.75$1.50costForUsage第 36–43 行把 usage 记录的四类 token 分别折算并求和modelTier第 23–30 行按模型名子串映射 tier。track.mjs、counterfactual.mjs、bench.mjs全部从该模块取价——定价变更导致的跨脚本漂移这一失败模式被结构性消除。smoke 作为契约从 27 项到 44 项ADR-0003 记录 smoke 契约从 27 项增长到44 项且全部在 100ms 墙钟时间内完成。当前仓库的 scripts/smoke.sh 仍保持 44 项主检查结构但版本断言已推进到 v0.26.3第 1 步检查plugin.json版本与 22 个关键词技能数也从 v0.15.0 时的 13 个增长到 20 个第 2 步逐一校验 frontmatter 三要素name:/description:/allowed-tools:。持续不变的契约核心包括无通配符工具授权第 10 步每个技能都带紧凑的allowed-tools白名单命名空间路由正确性第 3 步cost-report必须用memory_*且不得再出现agentdb_hierarchical-recallcost-tracking的组合双写路径文档第 4 步cost-optimize必须同时记录 ReasoningBank 路径与memory_store --namespace cost-patterns路径ADR 状态门第 8 步ADR-0001/0002/0003 必须为Accepted回归门第 23 步latest.json的 Tier 1 winRate ≥ 0.80文件不存在时放行基准未跑不阻塞。运行方式bash plugins/ruflo-cost-tracker/scripts/smoke.sh期望输出44 passed, 0 failed。五、后果评估ADR 以正/负/中三栏评估了这次实现弧的后果。积极面插件拥有了真正的生产者cost-track写入cost-tracking和同一份数据上的四重视角report、optimize、conversation、summary。此前每个技能都在消费空命名空间。预算强制成为机械化流程——budget check spawn …的 fail-closed 模式为昂贵操作加上了硬护栏。验证语料25 用例、含 7 个对抗产出诚实信号对抗用例上 Booster 正确拒绝升级而 Sonnet 4.6 仅解 2/7。Booster 的质性胜利——正确拒绝——不仅仅是速度。外部可观测性已接通Prometheus 供看板、webhook 供临时报告、程序化 summary 供跨插件消费。联邦消费者在上游 Phase 3 发射前就已就绪生产端落地时插件无需任何改动即可开始聚合。消极面未注册真正的 MCP 工具把cost_report/cost_summary注册为 MCP 工具需要修改v3/claude-flow/cli/src/mcp-tools/超出插件本地范围值得单独立 ADR。当前summary.mjs经 Bash shell-out 提供等价功能但它不是 MCP 工具。预算 upsert 的 workaroundmemory store拒绝memory retrieve看不到的 keyclaude-flow/cli memory 层的 UNIQUE 约束不一致budget.mjs用带时间戳的budget-config-ms键规避功能可用但反映上游 bug。联邦消费者在 Phase 3 落地前处于休眠直到federation_send完成事件流入federation-spend命名空间该指标恒为零已在文档中声明。CI 基准仅限 BoosterLLM/Anthropic 基线不在 CI 运行成本考量其漂移只能靠BENCH_LLM_BASELINE1 BENCH_ANTHROPIC1手动捕获。中性面插件停在 0.x 线内的 v0.15.0增量式表面积变化是常态。smoke 契约从 27 项扩到 44 项全部在 100ms 墙钟时间内完成。13 个技能加载进 Agent 上下文每个都有紧凑allowed-tools无通配符smoke 第 10 步强制此约束。六、最危险的三个假设不跑基准时插件在未安装 agent-booster 的环境下也能工作。所有其他技能track、budget、outcome、trend、conversation、export、federation、summary完全避开 booster 导入。已实测cost-track、cost-budget-check、cost-summary在 v3/ 目录之外均干净运行。Sonnet 4.6 / Opus 4.7 的延迟具有代表性。Anthropic 基线实测平均延迟 1270 / 1563 ms是真实的 GCP 区域影响数值会随时间波动——cost-trend的漂移标记正是为此设计。25 用例语料能反映生产工作模式。它很可能低估了大规模上下文重构类任务若真实负载差异显著胜率/升级率可能变化。缓解手段扩展语料、重跑基准smoke 第 23 步会在回归时让 CI 失败。七、验证实测记录ADR 的 Verification 章节记录了该弧完成时的实况live verifiedcost-track捕获当次会话1597 条消息Opus 4.7 上 $1546.36cost-budgetset / get / check$2500 预算61.9% 利用率 → INFOoutcome.mjs向路由器发射haikusuccess输出[OK] Outcome recordedcost-trend分析 6 次运行100% 胜率稳定延迟从 0.58ms 漂移到 0.36mscost-export --prometheustextfile 干净写出全部 6 类指标cost-federation用 mock 事件验证peer-bob $7.50 → ⚠ 超过 $5/24h 阈值被标记cost-summary --format json稳定契约验证通过。基准结果持久化于 docs/benchmarks/runs/latest.jsoncorpus v3、4 端点历史 run 保存在 docs/benchmarks/runs 目录下含 2026-05-05 当天多个时间戳 run 及 codemod 系列。八、关联决策与延期项关联链ADR-0001 — 命名空间路由修复本 ADR 的消费者/生产者缺口正是在其修复之上暴露的ADR-0002 — Agent Booster 集成与验证提供了本 ADR 落地所需的 hooks 与集成面ADR-097 — 联邦预算熔断Phase 3 消费者在本 ADR 的 P6 接通。其federation_send工具接受调用方传入的预算上限maxHops默认 8递归委派硬上限、maxTokens/maxUsd默认无界超限返回常量字符串BUDGET_EXCEEDED不泄露 oracle、hopCount透传、spent.{tokens,usd}调用方上报负值钳零。Phase 2 的 peer 状态机ACTIVE/SUSPENDED/EVICTED默认 $5/24h 挂起阈值 1h 失败率 50% 且 ≥10 次发送30 分钟冷却自动恢复仍在延期中。明确延期到后续 ADR 的事项真正的 MCP 工具注册cost_report/cost_summary作为注册 MCP 工具而非 Bash shell-out上游修复memory store的 UNIQUE 约束不一致Federation Phase 3 生产者在ruflo-federation插件内不在本插件对抗语料扩展到 50 用例以获取更紧的信号。九、在仓库中查看与复现本文讨论的全部代码与证据都位于当前仓库的plugins/ruflo-cost-tracker/下可按以下路径深入插件总览与 23 个子命令清单README.md命令参考cost track、cost budget set/get/check、cost outcome、cost trend、cost summary、cost export、cost federation等commands/ruflo-cost.md定价与 tier 分类的单一事实源scripts/_prices.mjs共享会话加载器iter 73 收敛后的唯一加载路径scripts/_sessions.mjs会话自动采集的 Stop 钩子接线hooks/hooks.json 与 scripts/ruflo-hook.cjs验证契约scripts/smoke.shbash plugins/ruflo-cost-tracker/scripts/smoke.sh期望44 passed, 0 failed基准语料与结果bench/booster-corpus.json、docs/benchmarks/runs/latest.json需要说明的适用前提文中的实测基准与命令行为均以当前仓库为准——ADR-0003 成文时插件为 v0.15.0仓库现状已演进到 v0.26.3smoke 第 1 步断言技能面从 13 个扩展到 20 个ADR 中claimed upstream, not yet verified的措辞纪律不把上游营销数字当作本仓库实测事实至今仍是该插件 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），仅供参考