token-pilot ⚡

所有 AI 工具的本地账单，一抬头就看见

同时用 Claude Code / Codex / Kimi Code 跑国产模型的人，终于能答上「这个月给 AI 烧了多少钱」——只读本地日志，数据不出本机。

快速开始 · 状态栏应用 · 数据准确性 · 什么时候别用它 · 讨论 · 贡献 · English

状态栏常驻 ⚡ ¥今日 · 预算%。左键弹面板，「打开完整看板」看全部。我的真实 10 月：47.8 亿 tokens · ¥8,265 · 32,643 次调用（怎么算的）。

⚠️ npm 上另有一个别人家的 token-pilot（MCP 代码导航工具，会往 Claude Code 写 hooks）。我们的包是 @anthonyhan/token-pilot，下面命令都带 scope，照抄即可。

🚀 快速开始

For Humans：

npm install -g @anthonyhan/token-pilot
token-pilot month     # 本月账单 + 月底预测 + 打转检测 + 省钱建议

For AI Agents：（把这句粘贴给你的 Agent）

帮我安装 token-pilot：npm install -g @anthonyhan/token-pilot，然后跑 token-pilot month 告诉我这个月 AI 花了多少钱、哪里在浪费。

状态栏应用

安装启动后只在状态栏显示一个闪电图标——无 Dock 图标、无启动窗口；左键弹面板，右键出菜单。

macOS（Apple Silicon / Intel）：

# 方式一：Homebrew（推荐，自动处理 Gatekeeper，装完即用）
brew install --cask anthonyhann/token-pilot/token-pilot

# 方式二：Releases 手动下载 .dmg，拖入「应用程序」后跑一次（解决未签名的「已损坏」误报）
xattr -dr com.apple.quarantine /Applications/token-pilot.app

Windows：Releases 下载 .msi，SmartScreen 选「仍要运行」。

长期解：Apple 开发者签名+公证（$99/年）在 TODO 里，有赞助再开。

自己构建：cd menubar && npm install && npx tauri build

🎯 为什么做这个

我同时用 Claude Code、Codex 和 Kimi Code 跑国产模型，账单散在三个地方：Claude 记一笔、Codex 记一笔、Kimi 记一笔，没有一个地方能回答「这个月总共烧了多少」。

试过几个现有方案，都不合用：

核心区别只有一句：它把国产模型和海外模型放在同一张账单里，而且全程不出本机。

✨ 功能清单：它能做什么

兼容你的工具链： Claude Code ✅ · Codex ✅ · Kimi Code ✅ · OpenCode ✅（全量 token）· DeepSeek/GLM/Kimi/Qwen/MiniMax/混元/MiMo/LongCat/Doubao ✅（模型归一）· 其余 12 款仅检测 · 桌面订阅端记固定月费

📈 数据准确性

账单工具不准就是误导。所以准确性可验证：

python3 scripts/reconcile.py month    # 第三方视角独立重算原始日志，与 CLI 逐项对账
python3 scripts/verify-dashboard.py   # 看板 36 项算法不变量校验
npm test                              # 69 个单元测试（定价/采集口径/聚合/注入/熔断/RTK/额度/并发）

实测修过的口径坑（2026-10-21，本机 4787 个日志文件）：

📊 凭什么信我

• 我自己的 AI 账单就是它管的：本月 ¥8,265 / 47.8 亿 tokens（2026-10-29 本机实时数据）
• 36 项看板算法不变量 + 69 个单测 + 独立对账脚本，全部开箱可跑
• 诚实披露速率口径：日志按「调用完成时刻」记账，生成中的调用完成前不计入（看板内有注明）

⚠️ 什么时候别用它

• 你想管的工具不写本地用量日志（Antigravity / Copilot / Cursor 等 12 款）——只能检测到装没装，读不到 token
• 桌面订阅 App（Kimi.app / ChatGPT.app）——不按 token 计费，只能登记固定月费
• 想拦在请求前面节流——它是事后分析，不拦截请求（拦截需要代理层，在 Roadmap）

🔋 订阅额度与余额

账单回答「花了多少钱」，额度回答「还能用多少」。后者来自平台自己的接口，不是本地推算。

已实测可用（用真实 key 打出真实数据验证过）：

已探到端点、等待实测（界面上标「待验证」，拿到对应 key 就能启用）：

为什么分两栏：探到 401 不代表接口能用——很多网关对不存在的路径也返 401。 只有用真实 key 拿到真实 JSON、确认字段语义无误的，才算「可用」。 这个原则避免了两次误判：OpenRouter 的「累计充值」差点被当成余额 （会显示「还剩 $0.34」而实际已用光），MiniMax 的鉴权头格式错差点被当成 key 无效。

凭证从哪来（三级降级，装了哪个用哪个）：

1. 你在看板「数据设置」里填的 key —— 永远可用
2. 平台自己的登录凭据（如 OpenCode 的 ~/.local/share/opencode/auth.json）—— 装了该工具就有
3. CC Switch 的配置 —— 装了才自动读取，不装完全可以正常用

第 3 层是便利不是依赖：不装 CC Switch 的用户，点「+ 添加平台」填一次 key 就能获得全部额度功能。 CC Switch 里配过的平台会自动回填成「CC Switch 读取」并设为只读，避免你手填一遍算两次。

怎么加平台：

1. 设置里点「+ 添加平台」→ 下拉选平台 → 粘贴 key → 确定。余额和订阅是两套 key，分开填
2. 内置列表没有的，选「添加自定义平台」，填「名称 + 接口地址 + 金额字段路径（如 data.balance）」即可
3. 内置平台的端点定义在 catalog.ts，加一条数据就是加一个平台

余额和订阅是两件事，所以分开配置、分开显示：

同一个平台可以两套都配（比如 MiniMax 查订阅用普通 key、查余额用 admin key），key 按「平台 + 场景」分开存，互不覆盖。

关于接口字段的坑：有些平台不返回「余额」，只给「累计充值」和「累计已用」两个数（OpenRouter 就是这样）。直接拿累计充值当余额会显示成「还剩 $0.34」，而实际一分不剩——所以这类平台会做减法。没验证过字段语义的接口一律标为未启用，不会拿错的数字糊弄你。

诚实说明：Coding Plan 类套餐平台只下发百分比，不发绝对值。所以看板上不会出现「已用 1500/20000」这种编造的数字——有什么显示什么。

节奏判断：单看「已用 60%」没意义，知道「窗口才过 40% 就已经用了 60%」才知道该不该踩刹车。所以有窗口长度和重置时间的平台，会额外标注「比线性节奏快/慢 N%」。

🧩 它和别的工具有什么不同

省 token 这件事分好几个环节，token-pilot 只做其中一环——算清楚钱。想省得更多，通常要几个工具配合：

关于重名： npm 上有一个同名的 token-pilot（Digital-Threads/token-pilot），它做的是上面第三行那件事——用 AST 让 AI 少读代码。它不统计花费，本工具也不读代码结构，两者解决的是同一个成本问题的不同环节，可以一起用。

本工具的正确包名是带 scope 的 @anthonyhan/token-pilot，安装命令都在上面，照抄即可。

👥 开发者与交流

一个人 + 几个 AI Agent 在做，想法和坑都摆在明面上。token-pilot 是本地工具，你的账单数据不会离开本机，所以交流群里聊的主要是「怎么算得更准」「怎么支持更多工具」，不用发任何日志或账单截图。

微信交流群：让 AI 先试试

扫码进群。适合：用着遇到问题想问、想提新工具/新平台的接入需求、或者单纯想看看别人怎么管理 AI 账单。

⏳ 群二维码 2026 年 11 月 6 日前有效。过期后扫码会失败——到 Discussions 留言，或在 Issues 提一句，我更新二维码并回复你新的入群方式。

其他渠道

想参与开发

• 写 adapter：新增一个 AI 工具的支持，只需要在 src/adapters/ 下实现 detect() + collect()，不需要读任何中心服务。想接哪个工具，先开 Discussion 说一声，避免撞车
• 提 PR：npm test 和 cargo test 必须全绿，.github/workflows/ci.yml 会在每次 push 自动跑；分支合并前请保持工作区干净
• 报数据不准：最有价值的反馈。附上「哪个工具、哪个模型、你预期的数字、token-pilot 显示的数字」就够了，不用贴原始日志

💬 参与讨论

• Discussions ——「这个模型算得对不对」「能不能支持某某工具」这类问题放这里，比开 issue 合适
• Issues ——数据算错、功能异常

💰 支持这个项目

token-pilot 免费且 MIT。如果它帮你省下了 AI 账单，可以请我喝杯咖啡：

支付宝	微信

也想出现在这里？→ [email protected]（赞助位招租）

⭐ Star 本仓库 = 告诉我你在用哪个宿主——下一个 adapter 优先做 Star 用户提名最多的那个。

🙋 关于我

一个人 + 几个 AI Agent 在做产品实验（西安远程）。token-pilot 是我自己每天真在用的工具——它先抓出了我 kimi-code 里一个打了 120 次调用的打转会话，又告诉我这个月缓存帮我省了 ¥3,048。

保持联系： X @AnthonyHan_ · [email protected]

📝 更新日志

完整分版本说明见 RELEASE_NOTES.md（也是客户端自动更新弹窗的文案来源）。

• v0.3.2 RTK 改用含压缩引擎的完整版，装完自动接 hook（备份/回滚保护）；新增发布数据回流脚本
• v0.3.1 npm 包缺 web 目录修复、看板前端编入 app 二进制
• v0.3.0 新增「压缩潜力」板块，修省钱建议卡被静默丢弃
• v0.2.9 自动发布链路修复（三平台产物上传与命名）
• v0.2.6 激活自动更新链路 + 打转熔断主动通知（含防轰炸）
• v0.2.5 npm scope 校正为 @anthonyhann，包可运行性修复
• v0.2.3 2B 压缩执行第一层（自动压缩 + autoCompact 写入 + RTK）、价格核对台
• v0.2.1 定价表对齐 8 家官方目录价、DeepSeek 分时、面板布局修复
• v0.2.0 压缩潜力量化、9 源采集覆盖、三处口径修复
• v0.1.0 首版 → CLI 账单 + 本地看板 + macOS/Windows 状态栏应用，三形态一次给齐

✅ TODO LIST

图例：[x] 已完成 · [ ] 计划中 · [⏸] 卡在外部条件，短期不会动（原因写在后面）

采集覆盖

• OpenCode adapter（SQLite）
• Qoder adapter（仅会话数，model 全为 auto——诚实标注）
• pi adapter
• Cursor spike（结论：无 token 用量数据，ai-code-tracking 是代码追踪非用量 → 诚实归「仅检测」）
• 云端用量 API：Doubao 火山（arkcli usage stats，日粒度）
• [⏸] 云端用量 API：OpenAI / Kimi 开放平台
  • 实测结论（2026-11）：Kimi 的余额已接通（GET /v1/users/me/balance → data.available_balance，真实 key 验证通过）。但没有用量查询端点——/v1/usage、/v1/users/me/usage、/api/v1/usage 全部 404。所以「还剩多少」能查，「今天花了多少」查不到
  • OpenAI 有 /v1/organization/usage/* 这类用量端点，但都是组织级接口，需要 Organization Admin key 才能调。我没有 admin key，无法验证个人 key 是否也可用——所以这项标「卡住」而不是「简单待办」
  • 如果你手上有 OpenAI 的 admin key 或知道 Kimi 的用量接口，发我实测一次，验证通过我当天就能接上

节流（Step 2）

• 2A 压缩潜力量化（规则引擎：陈旧输出/重复读取/超长输出 → 本月可省多少，实测 $63-95）
• 2B 压缩执行第一层：自动压缩提醒 + Claude autoCompact 写入 + RTK 安装（含 engine 的完整版；自动接 hook，改动 settings.json 前备份、失败还原）
• 异常重试自动熔断提醒（breaker.ts：单会话 ≥30 次调用即主动通知，每轮最多提 1 个防首跑轰炸）
• [⏸] 2B 压缩执行第二层：代理网关（LiteLLM / 自研）
  • 卡点不是技术，是边界：本地代理会接管你所有 AI 工具的请求链路。要做就得先回答「失败怎么无感回退」「改了网络出问题怎么一键还原」「凭什么让用户信它不劫持 key」。这三条没有令人信服的答案之前不做——宁可不做，也不能做一个会偷偷影响你网络的中间层
• [⏸] 低价模型路由（同上，是代理网关的一个子功能）
  • 依赖上一条；另外自动路由会导致「同一段对话前后模型不一致」，对连贯性有损，需要先验证收益是否盖过代价

平台与工程

• macOS 状态栏应用（arm64 + Intel x64 双架构 .app/.dmg）
• Windows 核查 + 分平台图标 + CI（.msi 由 Actions 产出）
• 自动更新（tauri-updater，v0.2.6 起生效，三平台共用一份 latest.json）
• CI 自动发布：打 tag 后三平台产物 + 合并版 latest.json 自动进 Release，并回写 brew cask
• [⏸] Windows .msi 实机安装验证
  • 现状：CI 只验证到「产物成功生成 + 签名文件存在 + 文件大小合理」，没有在真实 Windows 上装过、跑过、验证过自动更新。开发环境是 macOS，手上没有 Windows 机器
  • 需要：一台 Windows 10/11 机器。谁愿意帮忙实测，开 Discussion 说一声，我把验证步骤整理成清单发你
• [⏸] 统一二进制（universal2 单包替代 arm64/x64 两个 dmg）
  • 技术上可行：依赖全是纯 Rust（tauri / serde / open，没有 C 库），lipo 能合并
  • 代价明确：两个架构的代码合并后，单包体积必然大于现在任一个 dmg（现在 arm64 是 5.4MB、x64 是 5.7MB）。具体多大需实际构建后才能确认，这里是预估不是实测
  • 而且 latest.json 仍要按架构分发，等于要多维护一条合并流程
  • 结论：只有在「用户分不清该下哪个」真的成为常见问题时才值得做。现在两个 dmg 名字里已经标了 aarch64 / x64，暂时不是瓶颈
• [⏸] 签名与公证
  • 阻塞原因：Apple Developer Program $99/年，目前项目没有收入来源
  • 影响：未签名的 app 首次打开会被 Gatekeeper 拦一次，需要右键打开或跑一次 xattr -dr com.apple.quarantine（快速开始里有写）。brew 安装的会自动处理
  • 若将来有赞助覆盖这笔开销，优先做这个——它比任何新功能都更能降低新用户的第一次使用摩擦

English

README in English → README-en.md

token-pilot — local billing + budget control for all your AI coding tools. Reads local logs only (no hooks, no telemetry). CLI + local dashboard + menubar app (macOS/Windows). Chinese models (DeepSeek/GLM/Kimi…) auto-normalized via host-log model field.

License

MIT © anthonyhann