AI 编程助手的「电费账单」：本地化 AI Token 消耗与成本追踪神器

你是否曾好奇：每天用 Claude Code、Cursor 或 Gemini CLI 写代码时，到底“烧”掉了多少 Token？花了多少钱？哪个项目最费模型？哪天在调试上悄悄超支了？tokentab 就是专为开发者设计的本地化 AI 使用计量仪——它不联网、不传数据、不需 API 密钥，只读取你电脑上已有的日志文件，秒级生成按模型、项目、日期、任务类型（编码/调试/重构/测试）细分的 Token 消耗与成本报表。告别黑盒式调用，让每一次 AI 协作都清晰可计、可查、可优化。

核心功能

自动识别并汇总主流 AI 编程工具的真实消耗：无需手动导出或配置，tokentab 开箱即支持 Claude Code（读取 ~/.claude/projects/**/*.jsonl）、Codex（~/.codex/sessions/**/rollout-*.jsonl）和 Gemini CLI（~/.gemini/tmp/**/session-*.json）的原始日志，自动提取每轮请求的精确输入/输出 Token 数——所有数字均来自工具自身记录，零估算、零猜测。
智能去重计费，避免「缓存税」：Claude 的缓存读写分离、Gemini 的输入含缓存字段等易导致重复计费的细节，tokentab 全部主动识别并剔除缓存 Token，确保你只为实际计算付费，不为「被缓存的旧字节」买单。
多维度穿透式分析：一条命令即可切片查看——按「今天」（-today）、「本月」（-month）、「全历史」（-p all）、「指定日期区间」（--from 2024-06-01 --to 2024-06-15）、「单一模型」（--provider claude）或「特定项目」（--project my-react-app），彻底解决“钱花在哪了”的模糊焦虑。
零依赖本地 Web 仪表盘：执行 tokentab -web 即启动纯 Python 标准库 HTTP 服务（无 Flask/FastAPI 等额外依赖），打开 http://localhost:4747 即见月度费用总览+明细表格+交互式图表；所有数据实时读取本地磁盘，离线可用，字体完全使用系统默认，连 CDN 都不加载，真正隐私闭环。
结构化输出，无缝接入工作流：支持 --json 输出标准 JSON，可直接管道给 jq 处理、存入数据库或嵌入 CI 报告；终端输出自动适配——粘贴到 GitHub PR 或 Slack 时自动禁用 ANSI 彩色，避免乱码污染协作环境。
活动类型智能归类（非调用大模型）：基于会话首条消息关键词（如含 “debug”、“fix bug” 归为调试，“refactor” 归为重构）及工具行为模式，确定性分类每轮会话用途，全程离线运行，快且可验证，帮你发现「80% 时间其实花在调试而非写新逻辑」这类真实瓶颈。
极简扩展机制，轻松接入新工具：新增支持 Cursor 或其他 CLI 工具？只需在 tokentab/providers/ 下新建一个模块，实现返回 UsageRecord 列表的 collect() 函数，并注册到 __init__.py ——后续所有分组、计价、Web 展示逻辑自动复用，无需重复开发。
价格表本地化托管，稳定抗变更：所有模型单价（美元/百万 Token）硬编码在 tokentab/pricing/prices.py 中，采用模糊匹配（如 claude-opus-4-6-20240514 自动对齐 claude-opus-4-6），既规避厂商突然改名导致崩溃，又杜绝网络请求失败引发的统计中断；若遇未覆盖型号，CLI 明确提示并指导你一行代码补全。

技术亮点

零外部依赖架构：全栈基于 Python 标准库构建——日志解析用内置 json/pathlib，HTTP 服务用 http.server，无第三方 Web 框架、无数据库、无前端构建流程。安装即用，pip install . 后无任何运行时依赖，适合嵌入 Docker 环境或老旧开发机。
数据主权优先设计：从不上传日志、不收集设备信息、不连接任何远程 API；Web 服务绑定 localhost 且默认不自动打开浏览器（可加 --no-open）；所有计算在内存中完成，原始日志文件保持只读，真正实现「你的数据，你的规则」。
统一抽象层驱动多源兼容：通过 UsageRecord 数据类（定义于 types.py）强制约束各工具解析器的输出格式，上游解析（provider）与下游分析（计价、分组、渲染）完全解耦。这种「协议先行」设计让新增工具成本趋近于零，也保障了统计口径绝对一致。
终端友好型交互哲学：色彩自动降级（pipe 时关闭 ANSI）、JSON 输出无多余空格、错误提示直指问题根源（如「模型 xxx 未在 prices.py 中定义，请添加」），所有设计围绕开发者真实 CLI 使用场景打磨，拒绝「为炫技而复杂」。

适合哪些人用

本工具特别适合三类人群：AI 增强型开发者（频繁使用 Claude/Codex/Gemini 进行日常编码，希望量化投入产出比）、团队技术负责人（需监控团队整体 AI 成本趋势，识别高消耗项目并制定优化策略）、开源项目维护者（在 PR 描述中附带 tokentab -today --project my-lib 的消耗快照，向社区透明展示 AI 辅助开发的真实开销）。

真实场景案例：
• 某 SaaS 团队发现其「前端组件库重构」项目单日 Token 消耗是其他项目的 3 倍，深入分析后定位到大量重复的「描述性 prompt」——随即推动建立 prompt 模板库，当月成本下降 42%；
• 个人开发者用 tokentab -web 发现每周五下午调试会话激增，结合日志确认是 CI 环境配置问题，将问题解决前置，显著减少无效 AI 调试调用。

快速上手

无需复杂配置，三步启用：

安装：终端执行
git clone https://github.com/damejan80/tokentab && cd tokentab && pip install -e .
首次运行：直接输入 tokentab 查看最近 7 天汇总；常用命令：
• tokentab -today（今日明细）
• tokentab --provider gemini --project my-api（仅 Gemini 的 my-api 项目）
• tokentab -web（启动本地仪表盘）
自定义价格：若遇到未覆盖模型，在 tokentab/pricing/prices.py 中按示例添加一行，如：
"claude-sonnet-4-6": {"input": 3.0, "output": 15.0},

同类对比 / 注意事项

vs 商业监控平台（如 Langfuse、PromptLayer）：后者需注入 SDK、上报数据、依赖云服务，适合生产环境可观测性；tokentab 专注开发阶段「本地即时反馈」，轻量、隐私、零部署成本，是前者的互补而非替代。
vs 手动日志分析脚本：tokentab 封装了日志路径发现、缓存去重、模糊价格匹配、多维分组、Web 渲染等重复劳动，节省数小时/周的胶水代码编写时间。
注意事项：Cursor 支持目前为预留占位（README 明确标注「stub」），暂不可用；所有日志路径基于 macOS/Linux，默认 home 目录，Windows 用户需手动调整路径配置（详见 README 扩展章节）；首次运行建议先执行 tokentab -p all 确认日志路径是否被正确扫描。