深度探索 Gemini CLI：如何实现 Token 消耗的全局自动化统计？

1. 从 /stats model 说起：单次会话的“极客看板”

如果你是一名 Gemini CLI 的深度用户，一定被它的 /stats model 命令震撼过。输入这个完整指令，Gemini 会展示出一份极其详尽的“Stats For Nerds”报表：

• 多模型并存：并行展示 flash-lite 与 flash-preview 的消耗指标。
• 精细化 Token 分解：不仅有输入/输出，还包含 Cache Reads (缓存命中) 和 Thoughts (思维 Token)。
• 角色化统计：清晰区分了 main 对话角色、utility_router 路由角色以及 utility_summarizer 总结角色的各自负载。

这份报表对于诊断单次会话的效率非常完美。但问题也随之而来：数据太碎了。

面对如此专业且多维度的单次会话快照，如果你想回答“这个月我的缓存命中率整体是多少？”或“不同项目中 utility 角色的 Token 占比如何？”，仅靠肉眼去翻阅这些复杂的终端看板几乎是不可能的。

---

2. 偶然的发现：隐藏在 .gemini 文件夹下的秘密

为了寻找全局统计的方法，笔者开始深入探索 Gemini CLI 的底层存储逻辑。在 macOS/Linux 的用户目录下，隐藏着一个 .gemini 文件夹。

进入 .gemini/tmp/（或对应的项目临时目录）后，你会发现这里躺着许多以 UUID 命名的 JSON 文件。这些文件其实是 Gemini CLI 为了实现会话持久化而自动保存的“快照”。

通过对这些 JSON 文件的结构化分析，笔者发现：每一次交互的 usage_metadata（包括输入、输出、总 Token 数）都被完整地记录在内。

这意味着：虽然官方没有提供一个“全局用量看板”，但所有的原始数据其实一直静静地躺在你的本地硬盘里。

---

3. 技术方案：从碎片化文件到自动化看板

既然数据源已经找到，剩下的就是如何高效地提取、汇总并可视化这些数据。这就是 LLM Token Analyzer 诞生的初衷。

它通过一套自动化的工作流，将散落在各处的 session 快照转化为具有决策参考价值的报表，填补了官方工具在“长期用量追踪”上的空白。

---

4. 核心功能解析：填补全局统计的空白

A. 自动化增量同步 (/tokens:sync)

手动解析 JSON 文件显然是不现实的。扩展内置了 /tokens:sync 命令，它能智能识别 ~/.gemini/tmp 中的新增文件，增量提取 usage_metadata。它还能利用 AI 自动从会话内容中提取有意义的标题，让你的消耗记录不再只是一串冰冷的 UUID。

B. 多维度全局统计 (/tokens:analyze)

有了结构化的本地数据库，全局分析变得轻而易举。你可以一键查看：

• 跨会话汇总：所有历史对话的总消耗。
• 模型分布：Flash 与 Pro 模型的使用比例。
• 会话排行榜：识别出那些最耗费 Token 的长对话。

C. 交互式可视化看板 (/tokens:chart)

为了更直观地洞察用量趋势，扩展提供了 /tokens:chart 命令。它会启动一个本地服务，为你展示交互式的 HTML 图表。无论是想看最近一个月的消耗波动，还是想定位用量异常，只需指尖轻轻一点。

D. 进阶玩法：Agent Skills 赋能

除了手动的命令操作，本项目还深度集成了 Agent Skills 模式。这意味着你可以直接在对话中要求 Gemini：“帮我分析下今天的 Token 消耗”，AI 会自动激活 llm-token-analyzer 技能，完成从同步到分析的全流程。这种“工具即技能”的设计，让用量管理真正融入到了你的 AI 协作流中。

---

5. 如何集成到你的工作流？

LLM Token Analyzer 秉持着“本地优先”的原则，所有数据均保存在本地 ~/.token_usage/ 目录中，确保隐私安全。

快速安装：

gemini extensions install https://github.com/pityfish/llm-token-analyzer

日常使用：

1. 输入 /tokens:sync 同步数据。
2. 输入 /tokens:analyze 或 /tokens:chart 即可获取全局用量洞察。

---

6. 结语：让每一次调用都“心中有数”

虽然 Gemini CLI 目前对开发者非常友好且暂未收费，但了解自己的“数字足迹”和资源消耗习惯，是迈向专业化的重要一步。通过探索 .gemini 文件夹下的隐藏数据，我们不仅找回了对 Token 用量的掌控感，也为未来的 AI 应用开发积累了宝贵的基准数据。

如果你也在寻找一种更透明、更自动化的 Token 管理方案，不妨试试 LLM Token Analyzer。