Skip to content
Back to search

llm-cost-audit

SkillWorks with Claude CodeGitHub

执行 LLM/AI 成本审计与降本落地(LLM cost audit / FinOps)。当任务涉及 API 账单分析、token 成本过高、上下文膨胀、prompt 缓存命中、模型路由降级、批处理定价、成本归因与分账,或要给客户出一份成本审计报告时使用。也用于写/审成本报告、设计基线与两期对账、判断某项降本建议值不值得做。Use for API bill analysis, runaway token cost, context bloat, prompt caching, model routing, batch pricing, cost attribution, or writing a cost audit report.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lapisli--llm-cost-audit/badge.svg)](/listings/lapisli--llm-cost-audit)

HTML

<a href="/listings/lapisli--llm-cost-audit"><img src="/api/listings/lapisli--llm-cost-audit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 165 lines
  1. ---
  2. name: llm-cost-audit
  3. description: 执行 LLM/AI 成本审计与降本落地(LLM cost audit / FinOps)。当任务涉及 API 账单分析、token 成本过高、上下文膨胀、prompt 缓存命中、模型路由降级、批处理定价、成本归因与分账,或要给客户出一份成本审计报告时使用。也用于写/审成本报告、设计基线与两期对账、判断某项降本建议值不值得做。Use for API bill analysis, runaway token cost, context bloat, prompt caching, model routing, batch pricing, cost attribution, or writing a cost audit report.
  4. whenToUse: 接到成本审计的单、要给自己或客户降 LLM 成本、要出成本审计报告、要评估某个降本手段的真实收益、要看两期账单到底省了多少时。
  5. license: MIT
  6. version: 2.1.0
  7. ---
  8. # LLM 成本审计与降本
  9. ## 这是什么
  10. 一套可执行的成本审计流程 + 15 份带来源的知识库 + **一个能跑的计算器**。
  11. 输出物是**一份客户能自己复核的报告**,核心是三个数字:锁定基线、已识别节省、已验证节省。
  12. **这个技能的价值不在「找出浪费」,而在「结论能被财务复核」。**
  13. 报告里每个数字都要有来源或算式 —— 算不出来的就说算不出来,那是结论,不是失败。
  14. ## 快速开始
  15. > 以下命令都在**技能根目录**执行(安装后即 `~/.claude/skills/llm-cost-audit/`、
  16. > `~/.codex/skills/llm-cost-audit/` 或仓库根目录)。脚本用相对路径找 `lib/`,换目录会找不到。
  17. ```bash
  18. # 1. 把你的账单/用量导出归一化(支持 OpenAI / Anthropic / LiteLLM / 自定义 CSV)
  19. node scripts/ingest.mjs usage.json --from openai --out bill.json
  20. # 2. 跑 18 项矩阵,出金额
  21. node scripts/estimate.mjs bill.json
  22. # 3. 出 Markdown 报告片段,套进 templates/report-template.md
  23. node scripts/estimate.mjs bill.json --format md --out section4.md
  24. node scripts/estimate.mjs bill.json --format html --out report.html --client "客户名"
  25. # 看价格表(14 个模型,每个带来源与抓取日期)
  26. node scripts/estimate.mjs --list-prices
  27. # 客户模型不在表里:外部价格表覆盖
  28. node scripts/estimate.mjs bill.json --prices my-prices.json
  29. # 两期对比:算出真实省了多少(剔除用量变化)
  30. node scripts/compare.mjs before.json after.json
  31. ```
  32. 没有账单也能先看矩阵长什么样:`node scripts/estimate.mjs --list`
  33. **计算器不是可选项。** 先跑数,再写报告。凭感觉估的数字,客户一核对就崩。
  34. ## 模板与工具的分工
  35. `templates/report-template.md` 是**手工路径**(客户现场不能装 Node、或要复核工具输出时用)。
  36. 能跑代码就用 `scripts/estimate.mjs --format html`,两条路径结论必须一致。
  37. 模板里的「不建议做」区块**不许删**——删了报告就退化成一份只会说「你能省」的推销材料。
  38. ## 硬约束
  39. - **compare 只报剔除用量后的数。** 总成本差额里混着业务量变化,直接报「省了 35%」会被客户当场问倒。一律以「每千次请求成本」为准,且必须带上 `caveats`。
  40. - **价格表可以覆盖,但覆盖项标「未核实」。** 用户自己填的价格不冒充官方,相关结论只能当提示。(不可协商,先读这一节)
  41. 1. **禁止编造**:客户名、评价、logo、案例、省费率、百分比、URL —— 一律不许编。抓不到就写「抓取失败 / 未核实」。
  42. 2. **两个节省数字必须分开报**:「已识别节省」(动手前的估算)和「已验证节省」(对账后)。**绝不许合并成一个数字。**
  43. 3. **报告第一页必须有「诊断深度声明」**:本次是结构性诊断还是行为性诊断,以及因此没覆盖什么。
  44. 4. **必须有「不建议做」一页**:列出看过但认定不值得改的项及理由。这是可信度的来源。
  45. 5. **默认只读**:只要账单、用量导出、网关日志、聚合元数据。提示词正文必须逐个功能单独批准才可抽样。
  46. 6. **单价必须现查并截图存档**:价格过期是这类报告最容易被挑错的地方。
  47. 7. **交付 .md 和 .html 两种格式**(很多用户没有 Markdown 阅读器)。
  48. 8. **建议错峰之前必须先量时段分布。** 不许凭直觉说「挪到夜间打五折」——
  49. 实测过的高峰占比可能只有 **18.1%**,此时该杠杆上限仅约 **9%**,套模板会误伤客户。
  50. **没有时段数据就不许提这一条。**
  51. 9. **百分比不可相加。** 把「路由省 85% + 缓存省 90% + 批处理省 50%」加成一个数,是本行业最容易被当场戳穿的错误。能相加的是钱,不是百分比。
  52. ## 计算器的三条纪律(已写死在代码里,不是建议)
  53. `lib/estimate.mjs` 强制执行,违反会直接反映在输出上:
  54. | 纪律 | 代码怎么做的 | 你在报告里怎么写 |
  55. |---|---|---|
  56. | **联合反事实,不叠百分比** | 同源项(W3/W11、W2/W10、W9/W16)取组内最大;独立项相加;总额封顶到账单 | 写「合计 ¥X,方法:同源取最大 + 独立相加」 |
  57. | **realized 默认 null** | 没有 A/B 数据就返回 `null`,不给任何默认值 | 写「已验证节省:待 A/B 复测」,别填 0 |
  58. | **证据不足不进合计** | `厂商宣传` / `未核实` 的金额自动进 `excludedFromTotal`,不计入 `identifiedTotal` | 单独列一节「未计入的线索」 |
  59. **看到 `null` 就写「待核实」。看到 0 才写「没有节省」。两者不能混。**
  60. ## 执行流程
  61. | 步 | 做什么 | 关键产物 / 工具 |
  62. |---|---|---|
  63. | 0 | 判定档位与诊断深度 | 免费诊断 / 完整审计 / 实施+持续 |
  64. | 1 | Intake:要数据 | `templates/intake-email.md` |
  65. | 2 | 锁定基线 | 基线定义 + 数据来源 + 基线漏洞 |
  66. | 3 | 账单归一化 | `scripts/ingest.mjs` → 统一 JSON |
  67. | 4 | 逐项跑浪费清单 | `scripts/estimate.mjs`,标命中/未命中/待核实 |
  68. | 5 | 算两个节省数字 | `identifiedTotal` 与 `realizedTotal` 分开 |
  69. | 6 | 出报告 | `templates/report-template.md` |
  70. | 7 | 实施与验证 | A/B ≥7 天对生产基线,回归自动回滚 |
  71. | 8 | 结案 | 脱敏案例 + 回写本技能 |
  72. **第 8 步不是可选项。** 没有回写技能的案例等于白做。
  73. ## 知识库地图(按需读,不要一次全读)
  74. **开工先读 `reference/00-index.md`** —— 它是总目录,写明每份资料里有什么、证据等级怎么标、哪些数字还没核实。
  75. | 文件 | 里面有什么 | 什么时候读 |
  76. |---|---|---|
  77. | `reference/00-index.md` | 总目录 + 证据等级约定 + 未核实清单汇总 | **开工第一份** |
  78. | `reference/01-waste-matrix.md` | 18 项主表全文(判据/怎么量/幅度/证据/值不值得做) | 第 4 步 |
  79. | `reference/09-price-cn.md` | 国内 6 家官方定价全表(缓存价/错峰价/批处理/阶梯) | 算钱 |
  80. | `reference/02-compression.md` | 提示词压缩与上下文工程(含论文数字与陷阱) | 找修法 |
  81. | `reference/03-semantic-cache.md` | 语义缓存真实命中率与 prompt caching 门槛 | 找修法 |
  82. | `reference/04-routing.md` | 模型路由/级联(含「路由反而更贵」的反杀算例) | 找修法 |
  83. | `reference/05-batch.md` | 批处理官方折扣与工程代价 | 找修法 |
  84. | `reference/06-agent-token.md` | Agent/多智能体 token 倍率(官方数字)与缓存击穿 | 客户是 agent 产品 |
  85. | `reference/07-tooling.md` | 计量与归因工具链:能归因到哪一层、许可 | 要埋点/搭计量 |
  86. | `reference/08-selfhost.md` | 自托管 break-even(含「自托管更贵」的硬数据) | 客户想自建 |
  87. | `reference/11-finops-cn.md` | 国内云节省计划/预留实例券机制 | 国内客户 |
  88. | `reference/13-methodology.md` | 基线设计、对账、审计标准、认证 | 第 2、5 步 |
  89. | `templates/` | 报告模板、Intake 邮件、结案模板 | 第 1、6、8 步 |
  90. ## 代码结构
  91. ```
  92. lib/matrix.mjs 18 项矩阵的数据结构(evidence / verdict / kind / scope 四维)
  93. lib/prices.mjs 价格表 + 错峰判定 + 账单内联价格回落
  94. lib/estimate.mjs 计算器核心(三条纪律在这里执行)
  95. lib/ingest.mjs 账单适配纯函数(OpenAI / Anthropic / LiteLLM / 通用 CSV)
  96. lib/render-html.mjs 自包含 HTML 报告(无 CDN、可打印、自动转义)
  97. lib/compare.mjs 两期账单对比(单位成本 + 用量剔除 + caveats)
  98. scripts/estimate.mjs CLI:text / json / md / html 四种输出
  99. scripts/ingest.mjs 四路适配:OpenAI / Anthropic / LiteLLM / 通用 CSV
  100. scripts/compare.mjs 两期对比 CLI
  101. tests/ 97 项单测(estimate 26 + ingest 22 + html 12 + prices 20 + compare 17)
  102. ```
  103. **价格表只收录有可引用来源的价格。** 遇到没收录的模型,两个选择:
  104. ① 在账单 JSON 里加 `"prices": {"模型名": {"inputCached":..., "inputUncached":..., "output":...}}`(推荐,客户合同价永远比公开价准)
  105. ② 在 `lib/prices.mjs` 补一条并注明来源与抓取时间。
  106. **工具不会猜价格。** 缺价时它说「不在价格表里,无法折算金额」,不会给一个 0 让你误以为没有节省。
  107. ## 最容易犯的四个错
  108. 1. **把「缓存重发」当成浪费去修。** 缓存命中通常是**好事**(实测命中率 96.8%,按约 1/10 价计费)。要降成本只能降**上下文长度**。
  109. 2. **把 identified 当成 realized 报出去。** 已识别写在幻灯片上,已实现对在账单里,两者极少相同。Azure Advisor 官方都承认自己的建议节省「可能高于实际可达」。
  110. 3. **把厂商降价算成自己的功劳。** 推理成本每年约降 10 倍,不排除厂商降价,你可以把「什么都没做」报成节省。
  111. 4. **把「用户消息通道」当成用户 prompt 去优化。** 案例 001 里它占上下文的 **10.0%**,
  112. 但按 `source.kind` 拆开后**真人才 0.8%**,其余 **91.9%** 是指令 / 插件 / 技能目录 / 压缩检查点等**系统注入**。
  113. **不拆开会把「机器注入过大」误诊成「用户 prompt 太长」**,给出的建议完全无效。
  114. 凡是要动「用户通道」,必须先按 `source.kind` 出拆分表再下结论。
  115. ## 报价底线
  116. - 首单卖 **$300–800 固定费审计**;客户月 API 支出超过 $5,000 再谈 20% 分成。
  117. - **不要照抄同业「审计全免费」**(llmcfo 这么做是因为它有后续分成和现金储备)。
  118. - 对外报价的降幅口径只承诺 **40–60%**,且每一项都要有官方单价支撑。
  119. ## 结案与进化
  120. 做完一单,按 `templates/case-template.md` 写脱敏案例,更新案例索引,然后**改这个技能里过时的那几节**。
  121. 每 5 单做一次总复盘:哪些话术失效了、哪些建议反复被客户拒绝。
  122. ---
  123. *建立 2026-10-22,v2.0 重构 2026-11-21。知识库来自 14 路并行调研(408 KB,全部带来源与性质标注)。*
README.md · README · 381 lines
  1. **中文** | [English](README.en.md)
  2. # llm-cost-audit
  3. **LLM 成本审计工具。输入账单,输出浪费清单和可省金额。**
  4. 18 项判据覆盖缓存、路由、上下文、批处理这些常见问题。每个金额都标了证据来源,另外单独列出不建议做的项——只说「你能省」的报告没有可信度。
  5. > **谁该用**:每月 API 账单超过 ¥500 的开发者 / 团队;要给客户出成本审计报告的顾问;以及任何被「AI 成本优化」文章说了一堆手段、却不知道自己该动哪里的人。
  6. >
  7. > **谁不用**:账单只有几块钱的,省下来的钱不够你读这份文档的时间。
  8. [![CI](https://github.com/lapisli/llm-cost-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/lapisli/llm-cost-audit/actions/workflows/ci.yml)
  9. [![tests](https://img.shields.io/badge/tests-97%20passing-brightgreen)]()
  10. [![license](https://img.shields.io/badge/license-MIT-blue)]()
  11. ---
  12. ## 它解决什么问题
  13. 你打开 LLM 账单,看到一个数字。然后呢?
  14. 大多数「AI 成本优化」资料停在第一步:列一堆手段 —— 缓存、路由、批处理、压缩 —— 却不告诉你**在你这张账单上**哪些真的有钱、能省多少、值不值得动。
  15. | | 大多数「AI 成本优化」资料 | 这个项目 |
  16. |---|---|---|
  17. | 给你什么 | 一堆手段清单 | **你这张账单上**哪些真的有钱 |
  18. | 金额怎么来的 | 「能省 90%」 | 联合反事实算出来,同源组不重复计,总额封顶 |
  19. | 哪些不该动 | 不提 | 4 项明确写「不建议做」,附理由 |
  20. | 证据 | 无 | 五级证据(官方 / 论文 / 第三方实测 / 厂商宣传 / 未核实),每个数字标来源 |
  21. | 已实现节省 | 拿「已识别」冒充 | `null` —— 直到你做了两期对比才给数 |
  22. 这个项目把它做成了一个**能跑的计算器**:
  23. ```bash
  24. node scripts/ingest.mjs usage.json --from openai --out bill.json
  25. node scripts/estimate.mjs bill.json
  26. ```
  27. ```
  28. LLM 成本审计结果
  29. ════════════════════════════════════════════════════════════
  30. 账单期间 2026-10
  31. 总成本 ¥751.5
  32. 模型数 1
  33. 【已识别节省(identified)】
  34. 金额合计 ¥28.78
  35. 占总额 3.83%
  36. 计算方法 联合反事实:同源组取最大 + 独立项相加 + 总额封顶
  37. 【已实现节省(realized)】
  38. 数值 null(未做 A/B 对照)
  39. ```
  40. 注意最后那个 `null`。**它没有给你一个漂亮的百分比。** 这是刻意的。
  41. ---
  42. ## 三个和别处不一样的地方
  43. ### 1. 它敢说「不建议做」
  44. 18 项里有 4 项被明确标为不建议做,并给出理由:
  45. | 项 | 为什么劝你别做 |
  46. |---|---|
  47. | **W5 失败与重试** | 429 是被拒绝的请求,通常不计费。把 380 次重试报成节省就是忽悠 |
  48. | **W13 供应商价差套利** | 无可引用的实时价差表;中转站有合规风险,不适合作承重点 |
  49. | **W14 自托管替代 API** | 利用率 7% 才与 API 打平,5% 比 API 还贵。break-even 算错是交付者责任 |
  50. | **W15 微调 / 蒸馏** | 要碰客户训练数据与评测集,交付风险与报价量级不匹配 |
  51. 一份只会说「你这里可以省」的报告没有可信度。**说得出哪里不该动,才是专业的标志。**
  52. ### 2. 百分比不许相加
  53. 把「路由省 85% + 缓存省 90% + 批处理省 50%」加成一个数字,是这个行业最容易被客户当场戳穿的错误。五条理由:分母不同、叠加无条文、杠杆互相反杀、identified ≠ realized、只有可验算的才敢承诺。
  54. 代码里的做法是**联合反事实**:
  55. - 同源项(W3/W11 上下文、W2/W10 缓存、W9/W16 调用次数)取组内**最大**,不相加
  56. - 独立项相加
  57. - 总额封顶到账单实际金额
  58. - `厂商宣传` 和 `未核实` 的金额自动排除在合计之外
  59. ### 3. 每个数字带证据等级
  60. 只用五个词:`官方` / `论文` / `第三方实测` / `厂商宣传` / `未核实`。
  61. **「厂商宣传」的数字不得当作独立证据。** 工具会把它单独列在 `excludedFromTotal` 里,让你看得见但不算进钱。
  62. ---
  63. ## 快速开始
  64. 需要 Node.js 18+,**无第三方依赖**。
  65. ### 一行体验(不用 clone)
  66. 已发布到 npm:[`llm-cost-audit`](https://www.npmjs.com/package/llm-cost-audit)
  67. ```bash
  68. npx llm-cost-audit --list
  69. ```
  70. 或者全局装:
  71. ```bash
  72. npm i -g llm-cost-audit
  73. llm-cost-audit --list
  74. ```
  75. 装完有四个命令:
  76. | 命令 | 干什么 |
  77. |---|---|
  78. | `llm-cost-audit` | 主入口,等同于 `estimate` |
  79. | `llm-cost-ingest` | 账单归一化(OpenAI / Anthropic / LiteLLM / 通用 CSV) |
  80. | `llm-cost-estimate` | 跑 18 项判据,出报告 |
  81. | `llm-cost-compare` | 两期账单对比 |
  82. ### 完整用法(本地)
  83. ```bash
  84. git clone https://github.com/lapisli/llm-cost-audit.git
  85. cd llm-cost-audit
  86. # 看 18 项矩阵长什么样(不需要账单)
  87. node scripts/estimate.mjs --list
  88. # 用内置示例跑一遍(数据来自一次真实自审)
  89. node scripts/estimate.mjs examples/sample-bill.json
  90. # 看价格表(14 个模型,带来源和抓取日期)
  91. node scripts/estimate.mjs --list-prices
  92. # 两期账单对比(算出真实省了多少)
  93. node scripts/compare.mjs examples/sample-bill.json examples/sample-bill-after.json
  94. # 跑测试(97 项)
  95. npm test
  96. # 端到端验收(21 项)
  97. npm run selftest
  98. ```
  99. ### 输入格式
  100. 支持四种来源:
  101. ```bash
  102. node scripts/ingest.mjs usage.json --from openai --out bill.json
  103. node scripts/ingest.mjs usage.json --from anthropic --out bill.json
  104. node scripts/ingest.mjs logs.jsonl --from litellm --out bill.json
  105. node scripts/ingest.mjs data.csv --from generic \
  106. --map model=model,input_tokens=inputTotalTokens,cached_tokens=inputCachedTokens,\
  107. output_tokens=outputTokens,requests=requestCount,cost=totalCost --out bill.json
  108. ```
  109. 认不出的字段会写进 `warnings`,**不会猜一个值填进去**。
  110. 关于 `inputTotalTokens`:多数导出的 `input_tokens` **包含**缓存命中部分。
  111. 映射成 `inputTotalTokens` 后,适配器会自动减掉 `cached_tokens` 得到真实未命中量;
  112. 如果直接映射成 `inputUncachedTokens`,就会把缓存命中的 token 按未命中价重复计费。
  113. `examples/usage.csv` 是一个可直接跑的样例。
  114. ### 账单里自带价格(推荐)
  115. 客户手上的合同价永远比公开价准。任何模型都能算,不必等我们收录:
  116. ```json
  117. {
  118. "meta": { "currency": "CNY", "period": "2026-10" },
  119. "prices": {
  120. "your-model": { "inputCached": 0.5, "inputUncached": 4, "output": 16 }
  121. },
  122. "models": {
  123. "your-model": {
  124. "inputCachedTokens": 1970990000,
  125. "inputUncachedTokens": 65220000,
  126. "outputTokens": 14200000,
  127. "requestCount": 11503
  128. }
  129. },
  130. "totalCost": 751.5
  131. }
  132. ```
  133. ---
  134. ## 18 项矩阵
  135. | 编号 | 浪费项 | 证据 | 结论 |
  136. |---|---|---|---|
  137. | W1 | 模型超配:低复杂度功能走旗舰模型 | 论文 | 视情况 |
  138. | W2 | 固定前缀未缓存 | 官方 | 视情况 |
  139. | W3 | 上下文过长 | 第三方实测 | **建议做** |
  140. | W4 | 输出无上限 | 未核实 | 视情况 |
  141. | W5 | 失败与重试浪费 | 未核实 | **不建议** |
  142. | W6 | 可批处理却走同步 | 官方 | **建议做** |
  143. | W7 | 环境未分离 | 未核实 | **建议做** |
  144. | W8 | 重复嵌入 / 重复注入 | 未核实 | 视情况 |
  145. | W9 | Agent 循环失控与隐藏调用 | 官方 | **建议做** |
  146. | W10 | 超长 preamble / 重复工具定义 | 未核实 | 视情况 |
  147. | W11 | 上下文膨胀 | 第三方实测 | **建议做** |
  148. | W12 | 语义缓存未启用 | 论文 | 视情况 |
  149. | W13 | 供应商价差 / 中转站套利 | 未核实 | **不建议** |
  150. | W14 | 自托管替代 API | 第三方实测 | **不建议** |
  151. | W15 | 微调 / 蒸馏 | 未核实 | **不建议** |
  152. | W16 | 多智能体放大 | 官方 | 视情况 |
  153. | W17 | 无成本归因 / 无标签 / 无预算告警 | 未核实 | **建议做** |
  154. | W18 | 错峰调度未做 | 官方 | 视情况 |
  155. 每项的完整判据、怎么量、典型幅度,见 [`reference/01-waste-matrix.md`](reference/01-waste-matrix.md)。
  156. ---
  157. ## 安装为 Agent Skill
  158. 这个项目同时是一个 **Agent Skill**,可以装进支持 skills 规范的客户端:
  159. ```bash
  160. # 一条命令全装(推荐)
  161. npx skills add lapisli/llm-cost-audit --all
  162. # 或手动复制
  163. cp -r llm-cost-audit ~/.claude/skills/ # Claude Code
  164. cp -r llm-cost-audit ~/.codex/skills/ # Codex
  165. cp -r llm-cost-audit ~/.cursor/skills/ # Cursor
  166. cp -r llm-cost-audit ~/.config/opencode/skills/ # OpenCode
  167. cp -r llm-cost-audit .agents/skills/ # 项目内(Codex/Cursor/OpenCode 通用)
  168. cp -r llm-cost-audit .claude/skills/ # 项目内(Claude Code)
  169. ```
  170. 装好后,AI 助手在你说「帮我看看这个月 LLM 花了多少钱 / 出个成本审计报告」时会自动加载这套流程。
  171. ### 装完先自检
  172. ```bash
  173. node scripts/verify.mjs
  174. ```
  175. 它跑 11 项检查,全是真会出问题的事:frontmatter 合规性、`name` 与目录名是否一致、
  176. SKILL.md 引用的文件是否都在、所有 `.mjs` 语法、`bin` 是否指向真实文件、
  177. 矩阵引用的文档是否存在、**私有目录有没有被误提交**。同时打印各客户端的安装路径。
  178. ---
  179. ## 项目结构
  180. ```
  181. llm-cost-audit/
  182. ├── SKILL.md Agent Skill 主文件(流程 + 硬约束)
  183. ├── lib/
  184. │ ├── matrix.mjs 18 项矩阵数据结构
  185. │ ├── prices.mjs 价格表 + 错峰判定 + 内联价回落
  186. │ ├── estimate.mjs 计算器核心
  187. │ ├── ingest.mjs 账单适配纯函数
  188. │ ├── render-html.mjs 自包含 HTML 报告
  189. │ └── compare.mjs 两期账单对比
  190. ├── scripts/
  191. │ ├── estimate.mjs CLI(text / json / md / html)
  192. │ ├── ingest.mjs 四路账单适配 CLI
  193. │ ├── compare.mjs 两期对比 CLI
  194. │ ├── verify.mjs 分发自检(装完跑这个)
  195. │ └── selftest.mjs 端到端验收(CI 用)
  196. ├── tests/
  197. │ ├── estimate.test.mjs 26 项(计算器纪律)
  198. │ ├── ingest.test.mjs 22 项(四路适配 + 金额解析)
  199. │ ├── render-html.test.mjs 12 项(自包含 + 转义 + 打印)
  200. │ ├── prices.test.mjs 20 项(归一化 + 覆盖 + 来源完整性)
  201. │ └── compare.test.mjs 17 项(单位成本 + 用量剔除 + 对齐)
  202. ├── reference/ 12 份带来源的知识库
  203. ├── templates/ 报告模板 / Intake 邮件 / 结案模板
  204. ├── adapters/dsh/ 某个平台的账本适配(参考实现,非通用)
  205. ├── prices.example.json 外部价格表模板(--prices 用)
  206. └── examples/
  207. ├── sample-bill.json 可直接跑的示例账单
  208. ├── sample-bill-after.json 对比期账单(compare 用)
  209. └── usage.csv CSV 适配示例
  210. ```
  211. ---
  212. ## 价格表怎么维护
  213. 内置 14 个模型,每个都带 `source` 和 `capturedAt`:
  214. ```bash
  215. node scripts/estimate.mjs --list-prices
  216. ```
  217. **价格一定会过时。** 用前核对最后一列那个日期,对不上就去官方页面确认。表里只收「有可引用来源」的价格,宁可留空判「待核实」,也不编一个数。
  218. 你用的模型不在表里,有两种办法:
  219. **① 账单里内联价格**(最省事,推荐)
  220. ```json
  221. {
  222. "models": { "your-model": { "inputUncachedTokens": 1000000, "outputTokens": 100000 } },
  223. "prices": { "your-model": { "inputUncached": 3, "inputCached": 0.6, "output": 6 } }
  224. }
  225. ```
  226. **② 外部价格表**
  227. ```bash
  228. cp prices.example.json my-prices.json # 照着填
  229. node scripts/estimate.mjs bill.json --prices my-prices.json
  230. ```
  231. 外部表里的项默认标 `未核实`,不会冒充官方价格。模型名会自动归一化——`Qwen3.8-Max`、`qwen3.8-max`、`qwen-max` 都能匹配上;`gpt-4o-2024-08-06` 这种带日期后缀的也能识别。
  232. ---
  233. ## 两期对比:算出真实省了多少
  234. 单期账单证明不了因果,所以 `estimate()` 的 `realizedTotal` 永远是 `null`。做完优化、下个月拿到新账单,用 `compare` 才能给出一个**更强但仍不完美**的证据:
  235. ```bash
  236. node scripts/compare.mjs before.json after.json
  237. ```
  238. ```
  239. 指标 基线期 对比期 变化
  240. 总成本 ¥751.50 ¥486.50 -35.26%
  241. 请求数 11503 11503 0.00%
  242. 每千次请求成本 ¥65.33 ¥42.29 -35.26%
  243. 每百万 token 成本 ¥0.37 ¥0.35 -5.07%
  244. 缓存命中率 96.80% 96.82% +0.02%
  245. 单请求平均上下文 178,250 121,551 -31.81%
  246. 剔除用量变化后的已实现节省:¥265.00
  247. ```
  248. **关键在第三行。** 总成本降了 35%,但如果请求数也降了 35%,那就不是优化、是业务缩水。所以它算的是「每千次请求成本」,并且用基期用量折算:
  249. ```
  250. 已实现节省 = (基期单位成本 − 对比期单位成本) ÷ 1000 × 基期请求数
  251. ```
  252. 用量变化超过 10% 时它会主动报警,提醒你「差额里有相当部分是业务量变化,不能全部归因于降本动作」。币种不同、周期相同、上下文剧变都会触发对应的 caveat。
  253. **它自己会说「这不是 A/B 对照」**——同期业务结构、模型换代、厂商调价都会污染结论。要证因果,得留对照组。这句话永远出现在输出末尾,删不掉。
  254. ---
  255. ## 性能
  256. 10 万行账单(3.78 MB CSV)实测:
  257. | 步骤 | 耗时 |
  258. |---|---|
  259. | `ingest` 归一化 | 189 ms |
  260. | `estimate` 计算 | 39 ms |
  261. | 内存峰值 | 117 MB |
  262. 单文件整体读入,不做流式处理。百万行量级会吃到 1 GB 左右——到那个规模,建议先在数据库里按 model 聚合再导出,没必要把原始行喂进来。
  263. ---
  264. ## 已知局限
  265. 诚实列出来,避免你踩坑:
  266. 1. **不做流式解析。** 10 万行 0.2 秒够用,百万行会吃内存(1 GB 左右)。超大账单先在数据库按 model 聚合再导出。
  267. 2. **价格表需要维护。** 收录了 DeepSeek 官方价与几个 Claude 模型;其他厂商请用「账单内联价格」,或自行补 `lib/prices.mjs` 并注明抓取时间。
  268. 3. **需要账单数据才能算钱。** 只有用量没有金额时,能算百分比但算不出绝对金额。
  269. 4. **W3 的「可裁剪比例」必须来自你自己的 A/B 实测。** 工具不会替你假设一个压缩比。
  270. 5. **它不连任何 API。** 纯本地跑,不读你的密钥,不联网。
  271. 6. **`realizedTotal` 永远是 `null`,除非你手动填入 A/B 复测结果。** 这是设计,不是缺陷。
  272. ---
  273. ## 许可
  274. MIT。见 [LICENSE](LICENSE)。
  275. 知识库中的第三方数字保留其原始出处;引用时请一并注明证据等级。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.