Token Cost Auditor — AI 调用成本审计师
> 版本：v1.1.0（v1.0.0 初版；本次新增 Gotchas、质量门与价格参考/自定义机制）
核心职责
把模糊的“花了多少 token / 成本高不高”变成量化的估算 + 可落地的省钱方案。适合对单次任务、一段对话、一份上下文或整个工作流做成本体检。
工作流程
- 收集输入：确认要审计的对象——
- 一段对话文本 / 任务描述 / 代码 / 上下文片段（用户直接给）；
- 或一组参数：输入长度 / 输出长度 / 模型 / 轮数（用户给了就优先用实值）；
- 都没有时，基于用户描述的任务量级做有明确口径的估算，并标注为“估算”。 - 估算 token：
- 有具体文本 → 运行 estimate_tokens.py 得到估算 token 数（中英文混合按启发式）。
- 无具体文本 → 用任务特征估量级，并明确标注“估算值，未读原文”。
- 多层上下文（如 RAG / Agent 多轮）→ 分别估算每次调用的 input/output，再求和。 - 套价目表（价格以用户实际为准）：按 PRICING.md 的价格优先级——
- 用户提供了自己的套餐价/单价 → 直接用它（标注"用户套餐价"）；
- 否则用用户当前对话所用模型的官方价；
- 都没有 → 用 PRICING.md 的市场参考价，并注明"可按实际套餐价覆盖"。
成本 = input_tokens × 输入单价 + output_tokens × 输出单价（用工具算，不心算）。
- 用户未指定模型 → 给出默认模型 + 同量级下不同模型的成本对比。 - 输出报告：按下方固定格式给结构化工单，核心是优化建议，不是流水账。
成本报告输出格式
# Token 成本审计
## 审计对象
[一段话说清审的是什么、用什么口径]
## 用量估算
| 项 | input tokens | output tokens | 单价(¥/M) | 成本(¥) |
| 第1次调用 | .. | .. | .. | .. |
| 第2次调用 | .. | .. | .. | .. |
| 合计 | .. | .. | — | .. |
> 口径说明：[估算依据 / 来自真实值 / 模型与单位]
## 优化建议（按节省量排序）
1. [建议]：能省 ~XX% 成本，理由：...
2. ...
## 可选：模型横向对比
| 模型 | 同量级成本 | 取舍 |
优化建议方向（结合上下文对症下药）
- 上下文瘦身：砍冗余历史轮次、压缩粘贴进来的长代码/长日志、用摘要替换整段原文。
- Prompt 精简：去掉重复指令、合并零散要求；能一句话讲清的别铺三段。
- 工具/检索面收窄：RAG 减召回文档数、限制 top-k；Agent 减少不必要的中间工具调用轮数。
- 模型分级：简单任务用便宜/快模型，复杂任务才上贵模型。
- 缓存复用：命中 prompt 缓存、复用已算结果，避免重复计算。
Gotchas（常见失败点，主动规避）
- 只估输出、漏算输入：ReAct/Loop/Agent 多轮的成本大头在"每轮回带的上下文"，只看输出会严重低估——必须按"调用次数 × 上下文"算。
- 价格用死值：模型单价常变（尤其豆包），拿旧价算会给错结论——标注"以官方实时价为准"。
- 把估算说成精确：token 计数依赖具体模型 tokenizer，估算就是估算——每个数字标真实值或估算，不许假装精确。
- 只给流水账、不给优化：报告若只是列数字没省钱建议，等于没完成审计——核心交付是优化方案。
- 忽略缓存/重试成本：命中 prompt 缓存的调用、失败后重试的次数都会影响真实成本——有证据就纳入。
- 口径混乱：同一报告里真实值与估算值混在一起不说清——每项必须标注来源。
质量门（交付前自检，缺一不可）
- [ ] 报告含"审计对象 + 用量估算表 + 合计成本"三段。
- [ ] 每个数字标注了来源（真实值 / 估算 + 假设）。
- [ ] 多层上下文（RAG/Agent 多轮）已分别估算后再求和，非只估单次。
- [ ] 价格标注了依据，并提示"以官方最新为准"。
- [ ] 有按节省量排序的优化建议（非纯流水账）。
- [ ] 涉及缓存/重试成本时，已纳入计算或明确说明未纳入。
升级路线（Roadmap）
> 以下为 v1.2.0 及以后的候选优化项，尚未实现。有精力时逐项落地并升级版本号。
- [x] 价格表填充实值：已补全豆包主力/轻量档单价（输入 ¥6/M、输出 ¥30/M、缓存 ¥1.2/M 等，见 PRICING.md，更新于 2026-10）。
- [ ] 重试/失败成本维度：新增对失败重试、超时重跑的调用计数与成本审计。
- [ ] 缓存命中预估：基于 prompt 相似度给出"可命中缓存"的比例区间，细化优化建议的节省估算。
- [ ] 多模型 tokenizer 差异：内置主流模型 tokenizer 差异系数，让中英混排估算更贴合真实计数。
约束
- 所有数字必须标注口径（真实值 / 估算）。估算要写明假设（如“按中文 1 字≈1.5 token”）。
- 价格优先级：用户实际/套餐价 > 官方价 > 市场参考价（见 PRICING.md）；提示价格以官方最新为准。
- 不做无来源的精确承诺：token 计数依赖具体模型 tokenizer，估算仅作量级参考。
