ruflo-cost-tracker 成本导出实战用 cost-export 将 Agent 成本遥测接入 Prometheus 与 Webhook【免费下载链接】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 生态中的ruflo-cost-tracker插件负责记录 Agent 会话的 token 用量并按模型折算 USD 成本而cost-export技能SKILL.md是这条数据链路的对外出口它把散落在 AgentDBcost-tracking命名空间内的session-*与budget-config-*记录转成 Prometheus textfile 采集器格式或 Webhook JSON 格式供 Grafana、Datadog、Prometheus 及自定义看板消费。读完本文你将掌握export.mjs三种输出模式Prometheus 文件 / Webhook POST / stdout JSON的完整用法、全部导出指标的含义、环境变量覆盖方式以及如何与cost-track生产者、cost-budget-check预算告警配合搭建近实时的外部可观测链路。为什么需要导出让成本数据亮起来cost-track技能把每次会话的 token 用量折算成 USD 后以session-sessionId为键写入cost-tracking命名空间cost-budget-check则通过budget-config-*键读取预算并计算利用率。这些数据默认只存在于 AgentDB 命名空间内没有导出通道就无法进入外部可观测系统。cost-export解决的正是这个缺口一次运行即可把同一批数据同时投喂给 Prometheus 文本文件采集器、Webhook 端点或 stdout让内部成本数据在外部仪表盘上亮起来。该功能在 ADR-0003 中被列为 P10 优先级对应 v0.13.0其核心实现位于 export.mjs并由 smoke.sh 的 step 39a 以 44 项结构化契约中的一环进行校验验证cost_tracker_total_usd、fetch(、cost_tracker_tokens_total、byTierTokens、cache_creation_input_tokens等实现要素齐备。何时使用 cost-export根据 SKILL.md 的定位典型触发时机有三种任何一次 cost-track 运行之后刷新 Grafana / Datadog / Prometheus 上的指标定时循环刷新配合/loop 5m让外部看板保持近实时状态适合 Agent 长期驻留场景一次性 Webhook 上报临时报告Slack 机器人、自定义端点时单发。由于export.mjs只读命名空间、不做任何状态修改它是幂等且可随意重复执行的——这也正是它适合放进定时任务和 CI 流程的前提。三种输出模式与命令用法export.mjs支持三个互不冲突的入口参数--prometheus path、--webhook url以及不传任何参数时输出 stdout JSON。三者可同时指定例如既写 Prometheus 文件又发 Webhook。下面依次说明。模式一Prometheus node_exporter textfile 采集器# Prometheus node_exporter textfile collector node plugins/ruflo-cost-tracker/scripts/export.mjs --prometheus /var/lib/node_exporter/textfile_collector/cost_tracker.prom把.prom文件放入 node_exporter 的 textfile_collector 目录后Prometheus 会自动抓取其中的指标无需额外 exporter 进程。从源码看export.mjs脚本在写入前会调用mkdirSync(dirname(path), { recursive: true })自动创建父目录因此目录不存在也不会报错。所有数值指标使用toFixed(6)保留 6 位小数预算指标为toFixed(2)保证 Prometheus 浮点解析稳定。模式二Webhook POST# Webhook (POSTs JSON; add auth via env) EXPORT_WEBHOOK_HEADERAuthorization: Bearer $TOKEN \ node plugins/ruflo-cost-tracker/scripts/export.mjs --webhook https://hooks.example.com/cost-trackerWebhook 以Content-Type: application/jsonPOST 完整 JSON 载荷与 stdout 输出结构一致。认证信息通过EXPORT_WEBHOOK_HEADER环境变量注入支持逗号分隔的多组K: V键值对。源码中的解析逻辑export.mjs按,拆分后以第一个:为分隔点拆出键值rest.join(:).trim()保证值中即使包含冒号如 Bearer token也不会被截断。失败处理值得注意Webhook 返回非 2xx 状态码时脚本会向 stderr 输出Webhook POST failed: HTTP status并以process.exit(1)退出——这意味着它可以被直接当作 CI 门禁或告警触发条件使用见 export.mjs。模式三stdout JSON默认# Stdout JSON (default if no flag) node plugins/ruflo-cost-tracker/scripts/export.mjs不带任何参数时脚本将gather()聚合出的完整数据以缩进 JSON 打印到 stdoutexport.mjs适合管道式消费| jq、重定向到文件、接入其他脚本。默认确认信息输出到 stderr因此管道中的 stdout 始终是纯净的 JSON不会混入日志噪音。导出的 Prometheus 指标全解SKILL.md 列出了 6 类核心指标而当前源码iter 83 之后实际还会额外导出第 7 类——按层级tier与 token 类型type拆分的cost_tracker_tokens_total。完整指标清单如下指标类型标签含义cost_tracker_total_usdgauge无全部会话累计成本USDcost_tracker_tier_total_usdgaugetieropus\|sonnet\|haiku按层级汇总的成本cost_tracker_session_total_usdgaugesession8-char单会话成本cost_tracker_session_messagescountersession8-char单会话 assistant 消息数cost_tracker_budget_usdgauge无已配置的预算上限若配置了预算才出现cost_tracker_budget_utilizationgauge无预算利用率spent / budget0.0 到正无穷cost_tracker_tokens_totalcountertier…, typeinput\|output\|cache_write\|cache_read按层级 × token 类别的累计 token 数指标生成的实现细节会话标签截断sessionId只取前 8 个字符作为标签值export.mjs避免高基数标签污染 Prometheus 存储。标签转义escLabel()对反斜杠、双引号、换行符做标准转义export.mjs防止恶意会话名注入非法 Prometheus 标签。预算指标的条件性仅当budget.budget_usd存在时才输出cost_tracker_budget_*两组指标export.mjs。预算利用率直接取totalUsd / budget_usd因此可能大于 1超支状态在指标上直接可见。token 明细指标byTierTokens按haiku / sonnet / opus / unknown四个层级、每个层级再按input / output / cache_write / cache_read四类统计export.mjs且只输出计数大于 0 的序列避免空序列噪音。这一设计来自 iter 83 的实际驱动场景光看haiku 花了 X 美元无法定位opus 上 cache_write 暴涨这类问题有了type维度Grafana 就能用sum by (type) (cost_tracker_tokens_total)或cost_tracker_tokens_total{tieropus,typecache_write}精确切分。可直接复用的 PromQL 查询结合指标设计export.mjs 注释以下查询开箱即用# 全量 cache_write 累计定位缓存写入成本暴涨 sum by (type) (cost_tracker_tokens_total) # 每个层级的 token 总量 sum by (tier) (cost_tracker_tokens_total) # opus 的 cache_write 增长iter-82/83 的核心告警 cost_tracker_tokens_total{tieropus,typecache_write} # 预算利用率超过 90% 触发告警 cost_tracker_budget_utilization 0.9Webhook 载荷结构与认证Webhook 收到的 JSON 与 stdout 输出的结构完全一致顶层字段为{ exportedAt: 2026-05-05T03:13:19.596Z, sessions: [ { sessionId: 1dba3b8c-..., total_cost_usd: 1.68, messageCount: 234, byTier: {...}, byModel: {...} } ], budget: { budget_usd: 50.0, setAt: ..., thresholds: { info: 0.5, warning: 0.75, critical: 0.9, hard_stop: 1.0 } }, totalUsd: 12.45, byTier: { haiku: 0.45, sonnet: 8.2, opus: 3.8, unknown: 0 }, byTierTokens: { haiku: {input: 0, output: 0, cache_write: 0, cache_read: 0}, ...: ... } }其中sessions数组来自_sessions.mjs的loadSessions(NS)scripts/_sessions.mjs它通过memoryListSessionKeys列出所有session-前缀键、再逐个memoryRetrieve解析为记录空值自动过滤budget来自budget-config(-数字)键族中最新的一条按键名倒序取首个见 export.mjs这与budget.mjs写入时间戳键budget-config-ms的 upsert 方案ADR-0003 的 Negative 段落完全对应。Webhook 头注入支持多组EXPORT_WEBHOOK_HEADERK1: V1, K2: V2 node plugins/ruflo-cost-tracker/scripts/export.mjs --webhook url逗号分隔、每组独立K: V值内允许冒号。常见用法是Authorization: Bearer tokenSKILL.md 示例或自定义的X-Signature头。环境变量覆盖Env默认值用途EXPORT_NAMESPACEcost-tracking覆盖目标 AgentDB 命名空间EXPORT_WEBHOOK_HEADER未设置逗号分隔的K: V键值对用于 Webhook 认证EXPORT_QUIET1未设置抑制非错误确认输出错误仍会打印设置EXPORT_QUIET1后Exported N sessions, total $X与Wrote Prometheus textfile: …、Webhook POST ok (HTTP …)等确认信息全部静默export.mjs适合 cron 静默执行错误输出与process.exit(1)行为不受影响不会吞掉失败信号。EXPORT_NAMESPACE的存在意味着你可以对同一套脚本切换命名空间——例如先导出cost-tracking主命名空间再指向其他插件写入的命名空间做聚合。数据来源链路从 track 到 export要理解导出内容的可靠性需要看清上游数据的产生方式生产者cost-track读取 Claude Code 会话 jsonl~/.claude/projects/encoded-cwd/session.jsonl按模型汇总input_tokens / output_tokens / cache_creation_input_tokens / cache_read_input_tokens用定价表折算 USD 后写入cost-tracking:session-sessionId。定价源见 REFERENCE.md 的 Model pricing 表Haiku $0.25/$1.25/$0.30/$0.03Sonnet $3.00/$15.00/$3.75/$0.30Opus $15.00/$75.00/$18.75/$1.50均为每 1M token成本公式为四类 token 分别乘价后求和。共享加载器_sessions.mjsiter 73 起anomaly / burn / projection / counterfactual / conversation / budget / summary / export统一从 scripts/_sessions.mjs 加载会话数据export.mjs因此直接复用memoryListAllKeys/memoryRetrieve/loadSessions无需自行实现命名空间访问。消费者cost-budget-check读取cost-tracking:budget-config按 50/75/90/100% 四级告警阶梯输出INFO / WARNING / CRITICAL / HARD_STOP 100% 时以退出码 1 实现 fail-closed见 cost-budget-check/SKILL.md。导出的cost_tracker_budget_*指标与该告警阶梯共用同一份预算数据因此可以直接在 Prometheus 里对利用率设阈告警与技能内的硬停止逻辑互为镜像。值得注意的是export.mjs输出的totalUsd是对全部session-*记录的total_cost_usd求和export.mjs而byTier则来自每条记录的byTier字段聚合——两个数字口径不同一个是实测合计一个是各层级累加在 Grafana 面板上对账时不要混用。与成本观测生态的配合cost-export只是 ruflo-cost-tracker 20 个技能中的一环它与其他能力形成闭环cost-track—— 数据的生产者先 track 再 exportcost-budget-check—— 同一份budget-config的告警阶梯cost_tracker_budget_utilization可直接映射到 Prometheus alert rulecost-summary—— 提供稳定的程序化 JSON 契约--format json适合插件间消费export.mjs的 stdout JSON 与之互补一个是内部契约一个是外部投递cost-health/cost-burn/cost-anomaly—— 会话级与窗口级的异常检测cost_export则负责把已确认的成本事实送出去。在 README.md 的 skills 表中cost-export的用途描述是 Emit cost data as Prometheus textfile or POST to a webhook命令形态为cost export [--prometheus] [--webhook]与export.mjs的参数一一对应。验证与运维建议验证契约运行bash plugins/ruflo-cost-tracker/scripts/smoke.sh预期输出44 passed, 0 failed其中 step 39a 专门覆盖export.mjs的指标名与聚合函数存在性smoke.sh。node_exporter 部署将.prom文件放入--collector.textfile.directory指定的目录即可Prometheus 自动抓取无额外进程。定时刷新建议/loop 5m或系统 cron 每 5 分钟执行一次--prometheus实现近实时看板Webhook 模式适合事件驱动的一次性投递。CI 门禁Webhook 失败退出码 1 的语义使其可直接嵌入 pipeline实现导出失败即构建失败。从源码结构看iter 73 与 iter 83 的注释、smoke step 39acost-export是一个持续演进、有契约保护的对外接口每一次改动都伴随版本号与 smoke 契约同步增长。对需要把 Agent 成本纳入公司级可观测体系Grafana 大盘、Datadog 集成、自定义告警的团队而言这正是从内部有数据到外部看得见的最后一块拼图。【免费下载链接】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），仅供参考
