内容
# Tokenscope
**英文** · [中文](README-zh.md)
<a href="https://www.producthunt.com/products/tokenscope-2?embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-tokenscope-2" target="_blank" rel="noopener noreferrer"><img alt="Tokenscope - MacOS menu-bar dashboard for Claude CLI token usage | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1165012&theme=light&t=1780816780292"></a>
一款 macOS 状态栏应用，用于显示 Claude CLI 的 **每日 Token 使用量、预估成本以及按模型 / MCP / 技能调用的明细**。
技术栈：**Tauri 2 + React + TypeScript**（前端）/ **Rust**（数据层）。
## 功能
- 在状态栏图标旁边显示今日 Token 计数（例如 `⬡ 14.00M`）
- 点击打开面板：日 / 周 / 月切换
- 指标：总 Token（输入/输出）、预估成本、请求 / 会话
- 三种明细：**按模型** / **按 MCP 调用** / **按技能调用**
- 成本饼图（悬停单个模型），全年活动热图
- **仅统计您自己安装的 MCP 服务器 / 技能** — 所有 Claude 内置工具和 Anthropic 的捆绑 MCP 服务器都被过滤掉
## 数据源（零侵入，只读）
| 用途 | 路径 |
|---------|------|
| 会话日志（Token / 模型 / 工具调用） | `~/.claude/projects/**/*.jsonl` |
| 用户 MCP 白名单 | `~/.claude.json` → `mcpServers` + `projects[*].mcpServers` |
| 用户技能白名单 | `~/.claude/skills/` 目录 |
| 模型价格 | **主要**：[models.dev](https://models.dev/api.json)（裸模型名称，与 Claude CLI 日志匹配）→ **备用**：[LiteLLM](https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json) → 内置快照。缓存在 `~/Library/Caches/tokenscope/`，每 24 小时刷新，有离线备用 |
### 关键处理
- 按 `message.id` 去重（流式传输/重试重复使用）；当一条消息跨多行时，其工具调用合并，Token 使用量计一次
- Token 分割：`input`（未缓存）/ `cache`（创建+读取）/ `output`；UI 默认将缓存折叠为“In”，并显示单独的“缓存 %”
- 价格匹配：精确 ID → 规范 ID（剥离供应商前缀 + `.`↔`p`，例如 `glm-5.1`⇄`glm-5p1`）；models.dev 的官方裸名价格优先
- 成本按四种 Token 类型计价；每个模型带有 `priced` 标志 — **未在任一来源中找到的模型仍计 Token，但 UI 中标记为“无价格”**
- 日志仅包含裸模型名称（无供应商）→ 第三方模型默认为官方供应商价格（估计）
- 工具分类：`mcp__<server>__*` 其中服务器在您的配置中 → MCP；技能调用（`Skill` 工具的 `input.skill`，或 `/skill` 斜杠命令）其名称在您的技能目录中 → 技能；其他忽略
> 成本是基于公开价格的 **估计**；订阅用户应将其视为“等效支出价值”。
### Token 类型和成本公式
每个助手消息的 `usage` 报告四个 **相互排斥** 的 Token 计数（它们永远不会重复计算相同的 Token）：
| 阶段 | `usage` 字段 | 是什么 | 价格（相对于输入） |
|-------|---------------|------------|---------------------------|
| **输入**（未缓存） | `input_tokens` | 本次对话发送的新 Token | 1× |
| **缓存写入** | `cache_creation_input_tokens` |写入提示缓存的上下文 | ~1.25× |
| **缓存读取**（命中） | `cache_read_input_tokens` | 从缓存中重放的上下文 | ~0.1×（便宜得多） |
| **输出** | `output_tokens` | 模型生成的 Token | ~5× |
**Token**（按周期，消息汇总）：
```
total = input + cache_creation + cache_read + output
# UI 显示： In = input + cache_creation + cache_read, Out = output, cached % = cache_read / total
```
**成本**（每个阶段按其自己的 Token 费率计价）：
```
cost = input × price.input
+ cache_creation × price.cache_creation
+ cache_read × price.cache_read # 缓存命中按专用（更便宜）`cache_read` 费率计价
+ output × price.output
```
因此，缓存命中 **不** 按正常输入计费 — 它使用专用的（更便宜的）`cache_read` 费率，这就是为什么大量缓存的使用显示出巨大的 Token 计数但适中的成本。UI 仅为显示折叠缓存为“In”；计费始终使用上述四个单独的费率。
## 安装
### 选项 1：Homebrew（推荐）
```bash
brew install --cask hdusy/tokenscope/tokenscope
```
Cask 的 `postflight` 会自动剥离隔离属性（`xattr -cr`），因此 **它会在首次启动时打开，而不会出现“Apple 无法验证”提示**。
您一旦打开它，它就会注册为登录项，然后 **在每次启动时自动在状态栏启动**。
升级：
```bash
rm -rf "$(brew --repository)/Library/Taps/hdusy/homebrew-tokenscope" && brew tap HduSy/tokenscope && brew install --cask tokenscope
```
### 选项 2：下载 .dmg
1. 从 [Releases](https://github.com/HduSy/tokenscope/releases) 下载最新的 `Tokenscope_*_universal.dmg`（适用于 Apple Silicon 和 Intel）
2. 拖入应用程序
3. 由于构建是 **未签名/未经 notarization**，Gatekeeper 阻止首次启动 — 选择：
- 右键单击应用程序 → **打开** → 再次确认 **打开**，或
- 在终端中运行一次：
```bash
xattr -cr /Applications/Tokenscope.app && open /Applications/Tokenscope.app
```
> 未签名是当前的已知限制。真正的“双击打开”体验需要 Apple 开发者 ID 签名 + notarization — 请参见 `PRD.md` §6.4。
### 首次启动后
- 状态栏中出现图标和今日 Token 计数（例如 `⬡ 12.40M`)
- 左键单击图标切换面板；右键单击菜单（打开 / 刷新 / 退出）
- **启动登录已自动设置** — 无需手动配置
## 开发
```bash
pnpm install
pnpm tauri dev # 启动桌面应用程序（需要 Rust 工具链）
```
仅前端预览（使用真实数据快照 `public/dev-dashboard.json`）：
```bash
pnpm dev # http://localhost:1420
# 刷新快照：
cd src-tauri && cargo run --example dump > ../public/dev-dashboard.json
```
## 构建
```bash
pnpm tauri build # 输出 .app / .dmg 到 src-tauri/target/release/bundle/
```
有关分发的详细信息，请参见 `PRD.md` §6.3（推荐 Homebrew Cask；直接 `.dmg` 下载受益于代码签名 + notarization）。
## 结构
```
src/ React 前端
data.ts 类型 + Tauri 桥 + 主题 + 格式化
charts.tsx 图表基元（条形 / 饼图 / 折线图 / 热图 / 分段控件）
App.tsx 主面板
src-tauri/src/
store.rs 增量 JSONL 提取（按 message.id 去重 + 多行合并）
parser.rs 聚合（日/周/月 + 热图）
pricing.rs models.dev / LiteLLM 价格加载和成本计算
config.rs 用户 MCP / 技能白名单
model.rs 返回前端的数据结构
lib.rs Tauri 命令 + 状态栏托盘
```
## 错误日志
开发过程中发现的著名错误 — 症状、根本原因和修复 — 收集在 [docs/BUGFIXES.md](docs/BUGFIXES.md) 中。
MCP 市场