给 ZCode 装上一个"油耗表"：zcode-token-usage-statusbar 实测

管理员 2026年09月20日 171 次阅读 391 字 约 2 分钟
项目地址：https://github.com/xhwxt/zcode-token-usage-statusbar
平台：Windows / macOS ｜ 依赖：Python 3.8+（零第三方依赖）｜ 许可：MIT

用 ZCode 干活的时候，我心里常年悬着三个问题：这次对话烧了多少 token？上下文窗口还剩多少，什么时候该开新会话？模型现在生成得快不快？ ZCode 桌面客户端本身没有一个随时可见的答案，而 zcode-token-usage-statusbar 就是补上这块的悬浮状态栏——装完后它常驻对话窗口最底部，像汽车的油耗表一样，把每一轮请求的消耗实时摆在眼前。

状态条整体效果

它是什么、怎么工作的

先说清楚一个技术事实：这不是常规的 ZCode marketplace 插件。ZCode 的插件机制（plugin.json）只能提供 MCP、skills、commands、hooks，没有客户端 UI 能力——想在主窗口里画一个状态条，唯一的路线是往 app.asar 主入口注入一行 loader。所以它选择了"注入"这条路，这也是全文唯一需要你心理建设的点：它修改客户端文件，ZCode 每次升级覆盖 app.asar 后需要重跑一次安装。

数据侧则非常克制：只读本地 SQLite（~/.zcode/cli/db/db.sqlite），全程不联网、零轮询——空闲时零进程，有请求落库才触发刷新。不碰网络意味着它不构成额外的隐私面。

状态条上有什么

8 个模块，全部可以在 ⚙ 面板里独立开关：

  1. 生成速度：最近一次请求的 tokens/s，三档变色（≥70 绿 / 40–70 黄 / <40 红），模型快不快一眼可读；
  2. 上下文容量：微进度条 + 百分比，绿转黄转红；百万级大窗口提前在 40%/60% 预警。请求因超窗被拒时进度条亮红闪烁，并弹出三条处置建议（回滚上一轮 / 换大窗口模型或压缩会话 / 新开会话）——这是我个人觉得最贴心的设计，把"上下文爆炸"从一次莫名其妙的报错变成了可决策的信号；
  3. 本轮：最近一轮对话的消耗、缓存命中率、请求数、首 token 延迟；
  4. 会话累计：当前会话总消耗，明细里还有代码改动行数/文件数；多窗口各显各的，互不串数据；
  5. 工具调用：会话内工具调用总数，出错亮红色徽标；
  6. 今日合计：跨会话汇总当天用量；
  7. 子代理：后台子代理用量单独追踪，蓝色 ● 表示运行中，点击可看每个子代理的派发任务名与四项拆分；
  8. 设置面板：模块开关、上下文窗口手动覆盖、中英文界面即时切换。
上下文容量

安装：一条命令

前提很简单：Windows 或 macOS、Python 3.8+，没有任何第三方依赖。

git clone https://github.com/xhwxt/zcode-token-usage-statusbar.git
cd zcode-token-usage-statusbar
python install.py

我在 Windows 上的完整体验：脚本自动定位到了 ZCode 安装目录，复制运行时到 ~/.zcode/zcode-token-usage-statusbar/，重打包 asar（307MB，十几秒）、注册 MCP、装好 /usage 命令。唯一的小插曲：ZCode 正在运行时 asar 文件被占用、原子替换失败——安装器弹出了一个监控窗口，提示"完全退出 ZCode 后会自动完成替换"。我退出 ZCode，替换自动完成，重启后状态条就出现在窗口底部了。收尾逻辑不依赖计划任务，这个细节处理得挺稳。

两个提醒：

  • ZCode 升级会覆盖 app.asar，状态条消失就重跑一次 python install.py，秒级完成；
  • 卸载同样一条命令：python install.py --remove，它只增删自己的注入行，不依赖备份、不影响其它注入。

三种查询姿势

状态条是"看"，真要查账还有三种方式：

  • 对话内输入 /usage，直接在聊天里拉一份用量报告；
  • MCP 工具 token_usage(scope)：让 Agent 自己查，scope 支持 current / today / week / days:N / sessions:N / models:days / session:<id> / workspace:<目录>，可以按模型、按工作区聚合，子代理按 parent_id 归并去重，不会重复计数；
  • CLI：
python zusage.py now        # 当前会话
python zusage.py today      # 今日汇总
python zusage.py models 7   # 近 7 天按模型分布
python zusage.py watch 5    # 每 5 秒刷新

我装完随手跑了一下 zusage.py now，输出直接给出当前会话的轮次、请求数、input/output 拆分、缓存命中和最后活动时间——数据库里有什么，它就如实报什么。

几个值得说道的细节

  • 口径诚实：合计 = input + output，缓存读取已含在 input 内，README 明确提醒你"不要重复相加"；推理（thinking）token 只按厂商上报展示，不编数。对要写用量统计的人来说，这种把口径说破的文档比什么都重要。
  • SSH 远程会话：桌面客户端连远端 zcode-server 时，数据落在远端机的库里，本地查不到。配置 config.json 的 remote 段后，它自动切到 SSH 远端查询，条面出现 ☁ 徽标。远程办公场景算是被考虑到了。
  • 更新很省心：overlay.js 改动在 hot_reload 开启时约 2 秒热更新免重启；zusage.py 改动由常驻泵检测 mtime 自动重启。
  • 上下文窗口自动识别：优先读 ZCode 原生 UI 的读数（服务端下发、跟随模型）→ 内置模型目录 → config.json 兜底，基本不用手动配。

已知限制

改客户端 asar 属于非官方路线，作者在 README 里没有回避这一点：依赖 EmbeddedAsarIntegrityValidation=0 这个 fuse，官方一旦收紧或改入口结构，注入路线即失效（届时 --remove 即恢复原样）。macOS 支持自 v60 起加入，但作者自述没有 macOS 设备、未经实测。Windows 是全功能实测平台，我这次安装也确实顺利。

总结

它解决的问题很小很具体——"我的 token 去哪了"——但完成度很高：只读、离线、零轮询、口径清晰、卸载干净、连"安装时 ZCode 没关"这种边缘情况都给了优雅的兜底。如果你每天重度使用 ZCode，装一个不亏。

返回首页