junhoyeo/tokscale

| 概览 | 模型 | |:---:|:---:| |  |  | | 每日摘要 | 统计 | |:---:|:---:| |  |  | | 前端 (3D 贡献图) | 2025 年度回顾 | |:---:|:---:| | | | ## 概览 **Tokscale** 帮助你监控和分析来自以下来源的 token 消耗： | Logo | 客户端 | 数据位置 | 支持情况 | |------|----------|---------------|-----------| | | [OpenCode](https://github.com/sst/opencode) | `~/.local/share/opencode/opencode.db` (1.2+) 或/和 `~/.local/share/opencode/storage/message/` (旧版/未迁移) | ✅ 是 | | | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `~/.claude/projects/` | ✅ 是 | | | [OpenClaw](https://openclaw.ai/) | `~/.openclaw/agents/` (+ 旧版: `.clawdbot`, `.moltbot`, `.moldbot`) | ✅ 是 | | | [Codex CLI](https://github.com/openai/codex) | `~/.codex/sessions/` | ✅ 是 | | | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `~/.gemini/tmp/*/chats/*.json` | ✅ 是 | | | [Cursor IDE](https://cursor.com/) | 通过 `~/.config/tokscale/cursor-cache/` 进行 API 同步 | ✅ 是 | | | [Amp (AmpCode)](https://ampcode.com/) | `~/.local/share/amp/threads/` | ✅ 是 | | | [Droid (Factory Droid)](https://factory.ai/) | `~/.factory/sessions/` | ✅ 是 | | | [Pi](https://github.com/badlogic/pi-mono) | `~/.pi/agent/sessions/` | ✅ 是 | | | [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) | `~/.kimi/sessions/` | ✅ 是 | | | [Qwen CLI](https://github.com/QwenLM/qwen-cli) | `~/.qwen/projects/` | ✅ 是 | | | [Roo Code](https://github.com/RooCodeInc/Roo-Code) | `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/tasks/` (+ 服务端: `~/.vscode-server/data/User/globalStorage/rooveterinaryinc.roo-cline/tasks/`) | ✅ 是 | | | [Kilo](https://github.com/Kilo-Org/kilocode) | `~/.config/Code/User/globalStorage/kilocode.kilo-code/tasks/` (+ 服务端: `~/.vscode-server/data/User/globalStorage/kilocode.kilo-code/tasks/`) | ✅ 是 | | | [Mux](https://github.com/coder/mux) | `~/.mux/sessions/` | ✅ 是 | | | [Synthetic](https://synthetic.new/) | 通过 `hf:` 模型前缀或 `synthetic` 提供商从其他来源重新归因 (+ [Octofriend](https://github.com/synthetic-lab/octofriend): `~/.local/share/octofriend/sqlite.db`) | ✅ 是 | 使用 [🚅 LiteLLM 的定价数据](https://github.com/BerriAI/litellm) 获取实时价格计算，支持阶梯定价模型和缓存 token 折扣。 ### 为什么叫 "Tokscale"？ [](https://tokscale.ai) 本项目的灵感来源于 **[卡尔达肖夫指数](https://en.wikipedia.org/wiki/Kardashev_scale)**，这是天体物理学家尼古拉·卡尔达肖夫提出的一种方法，用于根据能源消耗量来衡量文明的科技发展水平。I 型文明利用其行星上所有可用的能量，II 型文明捕获其恒星的全部输出，III 型文明则掌控整个银河系的能量。 在 AI 辅助开发的时代，**token 就是新的能量**。它们为我们的推理提供动力，提升我们的生产力，并推动我们的创造性产出。正如卡尔达肖夫指数追踪宇宙尺度的能源消耗一样，Tokscale 衡量你的 token 消耗，助你在 AI 增强开发的阶梯上攀升。无论你是普通用户还是每天消耗数百万 token 的重度用户，Tokscale 都能帮助你可视化你的进阶之旅——从行星级开发者到银河系代码架构师。 ## 目录 - [概览](#overview) - [为什么叫 "Tokscale"？](#why-tokscale) - [功能特性](#features) - [安装](#installation) - [快速开始](#quick-start) - [前置条件](#prerequisites) - [开发环境设置](#development-setup) - [构建原生模块](#building-the-native-module) - [使用方法](#usage) - [基本命令](#basic-commands) - [TUI 功能](#tui-features) - [按平台筛选](#filtering-by-platform) - [日期筛选](#date-filtering) - [价格查询](#pricing-lookup) - [社交](#social) - [Cursor IDE 命令](#cursor-ide-commands) - [示例输出](#example-output---light-version) - [配置](#configuration) - [环境变量](#environment-variables) - [前端可视化](#frontend-visualization) - [功能特性](#features-1) - [运行前端](#running-the-frontend) - [社交平台](#social-platform) - [功能特性](#features-2) - [入门指南](#getting-started) - [数据验证](#data-validation) - [2025 年度回顾](#wrapped-2025) - [命令](#command) - [包含内容](#whats-included) - [开发](#development) - [前置条件](#prerequisites-1) - [如何运行](#how-to-run) - [支持的平台](#supported-platforms) - [原生模块目标](#native-module-targets) - [Windows 支持](#windows-support) - [会话数据保留](#session-data-retention) - [数据来源](#data-sources) - [定价](#pricing) - [贡献](#contributing) - [开发指南](#development-guidelines) - [致谢](#acknowledgments) - [许可证](#license) ## 功能特性 - **交互式 TUI 模式** - 由 Ratatui 驱动的精美终端 UI（默认模式） - 4 个交互式视图：概览、模型、每日、统计 - 键盘和鼠标导航 - GitHub 风格的贡献图，提供 9 种颜色主题 - 实时筛选和排序 - 零闪烁渲染 - **多平台支持** - 追踪 OpenCode、Claude Code、Codex CLI、Cursor IDE、Gemini CLI、Amp、Droid、OpenClaw、Pi、Kimi CLI、Qwen CLI、Roo Code、Kilo、Mux 和 Synthetic 的使用情况 - **实时定价** - 从 LiteLLM 获取当前定价，磁盘缓存 1 小时；自动 OpenRouter 回退以及针对新发布模型的 Cursor 模型定价 - **详细分类** - 输入、输出、缓存读/写和推理 token 追踪 - **Rust 原生核心** - 所有解析和聚合均在 Rust 中完成，处理速度提升 10 倍 - **Web 可视化** - 具有 2D 和 3D 视图的交互式贡献图 - **灵活筛选** - 按平台、日期范围或年份筛选 - **导出为 JSON** - 为外部可视化工具生成数据 - **社交平台** - 分享你的使用情况，在排行榜上竞争，查看公开资料 ## 安装 ### 快速开始 ``` # 直接使用 npx 运行 npx tokscale@latest # 或使用 bunx bunx tokscale@latest # 浅色模式（仅表格渲染） npx tokscale@latest --light ``` 就是这样！这为你提供了完整的交互式 TUI 体验，零配置。 ### 前置条件 - [Node.js](https://nodejs.org/) 或 [Bun](https://bun.sh/) - （可选）Rust 工具链，用于从源码构建原生模块 ### 开发环境设置 用于本地开发或从源码构建： ``` # 克隆仓库 git clone https://github.com/junhoyeo/tokscale.git cd tokscale # 安装 Bun（如果尚未安装） curl -fsSL https://bun.sh/install | bash # 安装依赖 bun install # 在开发模式下运行 CLI bun run cli ``` ### 构建原生模块 原生 Rust 模块是 CLI 操作**必需**的。它通过并行文件扫描和 SIMD JSON 解析提供约 10 倍的处理速度： ``` # 构建原生核心（从仓库根目录运行） bun run build:core ``` ## 使用方法 ### 基本命令 ``` # 启动交互式 TUI（默认） tokscale # 启动 TUI 并指定标签页 tokscale models # Models tab tokscale monthly # Daily view (shows daily breakdown) # 使用旧版 CLI 表格输出 tokscale --light tokscale models --light # 显式启动 TUI tokscale tui # 将贡献图数据导出为 JSON tokscale graph --output data.json # 以 JSON 格式输出数据（用于脚本/自动化） tokscale --json # Default models view as JSON tokscale models --json # Models breakdown as JSON tokscale monthly --json # Monthly breakdown as JSON tokscale models --json > report.json # Save to file ``` ### TUI 功能 交互式 TUI 模式提供： - **4 个视图**：概览（图表 + 热门模型）、模型、每日、统计（贡献图） - **键盘导航**： - `1-4` 或 `←/→/Tab`：切换视图 - `↑/↓`：导航列表 - `c/d/t`：按成本/日期/token 排序 - `s`：打开来源选择对话框 - `g`：打开分组方式选择对话框（model, client+model, client+provider+model） - `p`：循环切换 9 种颜色主题 - `r`：刷新数据 - `e`：导出为 JSON - `q`：退出 - **鼠标支持**：点击选项卡、按钮和筛选器 - **主题**：绿色、万圣节、青色、蓝色、粉色、紫色、橙色、单色、黄绿蓝 - **设置持久化**：偏好设置保存至 `~/.config/tokscale/settings.json`（参见 [配置](#configuration)） ### 分组策略 在 TUI 中 `g` 或在 `--light`/`--json` 模式下使用 `--group-by` 来控制模型行的聚合方式： | 策略 | 标志 | TUI 默认 | 效果 | |----------|------|-------------|--------| | **模型** | `--group-by model` | ✅ | 每个模型一行 — 合并所有客户端和提供商 | | **客户端 + 模型** | `--group-by client,model` | | 每个客户端-模型对一行 | | **客户端 + 提供商 + 模型** | `--group-by client,provider,model` | | 最细粒度 — 不合并 | **`--group-by model`**（最合并） | 客户端 | 提供商 | 模型 | 成本 | |---------|-----------|-------|------| | OpenCode, Claude, Amp | github-copilot, anthropic | claude-opus-4-5 | $2,424 | | OpenCode, Claude | anthropic, github-copilot | claude-sonnet-4-5 | $1,332 | **`--group-by client,model`**（CLI 默认） | 客户端 | 提供商 | 模型 | 成本 | |--------|----------|-------|------| | OpenCode | github-copilot, anthropic | claude-opus-4-5 | $1,368 | | Claude | anthropic | claude-opus-4-5 | $970 | **`--group-by client,provider,model`**（最细粒度） | 客户端 | 提供商 | 模型 | 成本 | |--------|----------|-------|------| | OpenCode | github-copilot | claude-opus-4-5 | $1,200 | | OpenCode | anthropic | claude-opus-4-5 | $168 | | Claude | anthropic | claude-opus-4-5 | $970 | ### 按平台筛选 ``` # 仅显示 OpenCode 使用情况 tokscale --opencode # 仅显示 Claude Code 使用情况 tokscale --claude # 仅显示 Codex CLI 使用情况 tokscale --codex # 仅显示 Gemini CLI 使用情况 tokscale --gemini # 仅显示 Cursor IDE 使用情况（需先运行 `tokscale cursor login`） tokscale --cursor # 仅显示 Amp 使用情况 tokscale --amp # 仅显示 Droid 使用情况 tokscale --droid # 仅显示 OpenClaw 使用情况 tokscale --openclaw # 仅显示 Pi 使用情况 tokscale --pi # 仅显示 Kimi CLI 使用情况 tokscale --kimi # 仅显示 Qwen CLI 使用情况 tokscale --qwen # 仅显示 Roo Code 使用情况 tokscale --roocode # 仅显示 Kilo 使用情况 tokscale --kilocode # 仅显示 Mux 使用情况 tokscale --mux # 仅显示 Synthetic (synthetic.new) 使用情况 tokscale --synthetic # 组合过滤器 tokscale --opencode --claude ``` ### 日期筛选 日期筛选器适用于所有生成报告的命令（`tokscale`、`tokscale models`、`tokscale monthly`、`tokscale graph`）： ``` # 快速日期快捷方式 tokscale --today # Today only tokscale --week # Last 7 days tokscale --month # Current calendar month # 自定义日期范围（包含边界，本地时区） tokscale --since 2024-01-01 --until 2024-12-31 # 按年份过滤 tokscale --year 2024 # 与其他选项组合 tokscale models --week --claude --json tokscale monthly --month --benchmark ``` ### 价格查询 查询任何模型的实时价格： ``` # 查询模型定价 tokscale pricing "claude-3-5-sonnet-20241022" tokscale pricing "gpt-4o" tokscale pricing "grok-code" # 强制指定 Provider 来源 tokscale pricing "grok-code" --provider openrouter tokscale pricing "claude-3-5-sonnet" --provider litellm ``` **查询策略：** 价格查询使用多步骤解析策略： 1. **精确匹配** - 在 LiteLLM/OpenRouter 数据库中直接查找 2. **别名解析** - 解析友好名称（例如 `big-pickle` → `glm-4.7`） 3. **层级后缀剥离** - 移除质量层级（`gpt-5.2-xhigh` → `gpt-5.2`） 4. **版本标准化** - 处理版本格式（`claude-3-5-sonnet` ↔ `claude-3.5-sonnet`） 5. **提供商前缀匹配** - 尝试常见前缀（`anthropic/`、`openai/` 等） 6. **Cursor 模型定价** - 针对 LiteLLM/OpenRouter 中尚不存在的模型（例如 `gpt-5.3-codex`）的硬编码定价 7. **模糊匹配** - 针对部分模型名称的词边界匹配 **提供商优先级：** 当存在多个匹配时，原始模型创建者优先于转售商： | 优先（原始） | 降级（转售商） | |---------------------|-------------------------| | `xai/` (Grok) | `azure_ai/` | | `anthropic/` (Claude) | `bedrock/` | | `openai/` (GPT) | `vertex_ai/` | | `google/` (Gemini) | `together_ai/` | | `meta-llama/` | `fireworks_ai/` | 示例：`grok-code` 匹配 `xai/grok-code-fast-1` ($0.20/$1.50) 而非 `azure_ai/grok-code-fast-1` ($3.50/$17.50)。 ### 社交 ``` # 登录 Tokscale（打开浏览器进行 GitHub 认证） tokscale login # 查看当前登录用户 tokscale whoami # 提交使用数据到排行榜 tokscale submit # 带过滤器提交 tokscale submit --opencode --claude --since 2024-01-01 # 预览提交内容（dry run） tokscale submit --dry-run # 登出 tokscale logout ``` ### Cursor IDE 命令 Cursor IDE 需要通过会话 token 单独进行身份验证（不同于社交平台登录）： ``` # 登录 Cursor（需要来自浏览器的会话令牌） # --name 是可选的；它仅用于稍后识别账户 tokscale cursor login --name work # 检查 Cursor 认证状态和会话有效性 tokscale cursor status # 列出已保存的 Cursor 账户 tokscale cursor accounts # 切换活动账户（控制哪个账户同步到 cursor-cache/usage.csv） tokscale cursor switch work # 登出特定账户（保留历史记录；将其排除在聚合之外） tokscale cursor logout --name work # 登出并删除该账户的缓存使用量 tokscale cursor logout --name work --purge-cache # 登出所有 Cursor 账户（保留历史记录；排除在聚合之外） tokscale cursor logout --all # 登出所有账户并删除缓存使用量 tokscale cursor logout --all --purge-cache ``` 默认情况下，tokscale **汇总所有已保存 Cursor 账户的使用情况**（所有 `cursor-cache/usage*.csv`）。 当你登出时，tokscale 会将缓存的使用历史移动到 `cursor-cache/archive/` 来保留它（因此不会被汇总）。如果你想删除缓存的使用数据，请使用 `--purge-cache`。 **凭据存储**：Cursor 账户存储在 `~/.config/tokscale/cursor-credentials.json` 中。使用数据缓存在 `~/.config/tokscale/cursor-cache/`（活跃账户使用 `usage.csv`，额外账户使用 `usage..csv`）。 **获取你的 Cursor 会话 token：** 1. 在浏览器中打开 https://www.cursor.com/settings 2. 打开开发者工具（F12） 3. **方法 A - Network 选项卡**：在页面上执行任何操作，找到一个发往 `cursor.com/api/*` 的请求，在 Request Headers 中查找 `Cookie` 标头，仅复制 `WorkosCursorSessionToken=` 后面的值 4. **方法 B - Application 选项卡**：前往 Application → Cookies → `https://www.cursor.com`，找到 `WorkosCursorSessionToken` cookie，复制其值（不是 cookie 名称） ### 示例输出（`--light` 版本） ### 配置 Tokscale 将设置存储在 `~/.config/tokscale/settings.json` 中： ``` { "colorPalette": "blue", "includeUnusedModels": false } ``` | 设置 | 类型 | 默认值 | 描述 | |---------|------|---------|-------------| | `colorPalette` | string | `"blue"` | TUI 颜色主题 (green, halloween, teal, blue, pink, purple, orange, monochrome, ylgnbu) | | `includeUnusedModels` | boolean | `false` | 在报告中显示零 token 的模型 | | `autoRefreshEnabled` | boolean | `false` | 在 TUI 中启用自动刷新 | | `autoRefreshMs` | number | `60000` | 自动刷新间隔 (30000-3600000ms) | | `nativeTimeoutMs` | number | `300000` | 原生子进程处理的最长时间 (5000-3600000ms) | ### 环境变量 环境变量覆盖配置文件值。适用于 CI/CD 或一次性使用： | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `TOKSCALE_NATIVE_TIMEOUT_MS` | `300000` (5 分钟) | 覆盖 `nativeTimeoutMs` 配置 | ``` # 示例：为超大数据集增加超时时间 TOKSCALE_NATIVE_TIMEOUT_MS=600000 tokscale graph --output data.json ``` ### 无头模式 Tokscale 可以从 **Codex CLI 无头输出** 中汇总 token 使用情况，用于自动化、CI/CD 流水线和批处理。 **什么是无头模式？** 当你使用 JSON 输出标志（例如 `codex exec --json`）运行 Codex CLI 时，它会将使用数据输出到 stdout，而不是存储在常规会话目录中。无头模式允许你捕获和追踪这种使用情况。 **存储位置：** `~/.config/tokscale/headless/` 在 macOS 上，当未设置 `TOKSCALE_HEADLESS_DIR` 时，Tokscale 还会扫描 `~/Library/Application Support/tokscale/headless/`。 Tokscale 自动扫描此目录结构： ``` ~/.config/tokscale/headless/ └── codex/ # Codex CLI JSONL outputs ``` **环境变量：** 设置 `TOKSCALE_HEADLESS_DIR` 以自定义无头日志目录： ``` export TOKSCALE_HEADLESS_DIR="$HOME/my-custom-logs" ``` **推荐（自动捕获）：** | 工具 | 命令示例 | |------|-----------------| | **Codex CLI** | `tokscale headless codex exec -m gpt-5 "implement feature"` | **手动重定向（可选）：** | 工具 | 命令示例 | |------|-----------------| | **Codex CLI** | `codex exec --json "implement feature" > ~/.config/tokscale/headless/codex/ci-run.jsonl` | **诊断：** ``` # 显示扫描位置和 Headless 计数 tokscale sources tokscale sources --json ``` **CI/CD 集成示例：** ``` # 在你的 GitHub Actions 工作流中 - name: Run AI automation run: | mkdir -p ~/.config/tokscale/headless/codex codex exec --json "review code changes" \ > ~/.config/tokscale/headless/codex/pr-${{ github.event.pull_request.number }}.jsonl # 稍后，追踪使用情况 - name: Report token usage run: tokscale --json ``` ## 前端可视化 前端提供 GitHub 风格的贡献图可视化： ### 功能特性 - **2D 视图**：经典 GitHub 贡献日历 - **3D 视图**：基于 token 使用高度的等距 3D 贡献图 - **多种调色板**：GitHub、GitLab、万圣节、冬季等 - **三向主题切换**：浅色 / 深色 / 系统（跟随 OS 偏好） - **GitHub Primer 设计**：使用 GitHub 的官方颜色系统 - **交互式提示框**：悬停查看详细的每日分类 - **每日分类面板**：点击查看按来源和模型的详细信息 - **年份筛选**：在不同年份之间导航 - **来源筛选**：按平台筛选（OpenCode、Claude、Codex、Cursor、Gemini、Amp、Droid、OpenClaw、Pi、Kimi、Qwen、Roo Code、Kilo、Mux、Synthetic） - **统计面板**：总成本、token 数、活跃天数、连续天数 - **FOUC 防护**：主题在 React 注水前应用（无闪烁） ### 运行前端 ``` cd packages/frontend bun install bun run dev ``` 打开 [http://localhost:3000](http://localhost:3000) 访问社交平台。 ## 社交平台 Tokscale 包含一个社交平台，你可以在其中分享使用数据并与其他开发者竞争。 ### 功能特性 - **排行榜** - 查看所有平台上 token 使用量最多的用户 - **用户资料** - 带有贡献图和统计数据的公开资料 - **周期筛选** - 查看所有时间、本月或本周的统计数据 - **GitHub 集成** - 使用 GitHub 账户登录 - **本地查看器** - 私下查看数据而无需提交 ### GitHub 资料嵌入小部件 你可以直接在 GitHub 资料 README 中嵌入你的公开 Tokscale 统计数据： ``` [](https://tokscale.ai/u/) ``` - 将 `` 替换为你的 GitHub 用户名 - 可选查询参数： - `theme=light` 使用浅色主题 - `sort=tokens`（默认）或 `sort=cost` 控制排名依据 - `compact=1` 使用紧凑布局 + 紧凑数字表示法（例如 `1.2M`、`$3.4K`） - 示例： - `https://tokscale.ai/api/embed//svg?theme=light&sort=cost&compact=1` ### 入门指南 1. **登录** - 运行 `tokscale login` 通过 GitHub 进行身份验证 2. **提交** - 运行 `tokscale submit` 上传你的使用数据 3. **查看** - 访问 Web 平台查看你的资料和排行榜 ### 数据验证 提交的数据经过 1 级验证： - 数学一致性（总计匹配，无负数） - 无未来日期 - 必填字段存在 - 重复检测 ## 2025 年度回顾  生成一张精美的年度回顾图片，总结你的 AI 编程助手使用情况——灵感来自 Spotify Wrapped。 | `bunx tokscale@latest wrapped` | `bunx tokscale@latest wrapped --clients` | `bunx tokscale@latest wrapped --agents --disable-pinned` | |:---:|:---:|:---:| |  |  |  | ### 命令 ``` # 生成当年的 Wrapped 图片 tokscale wrapped # 生成特定年份的 tokscale wrapped --year 2025 ``` ### 包含内容 生成的图片包含： - **总 Token 数** - 你一年的总 token 消耗量 - **热门模型** - 按成本排名的 3 个最常用 AI 模型 - **热门客户端** - 3 个最常用的平台（OpenCode、Claude Code、Cursor 等） - **消息数** - AI 交互总数 - **活跃天数** - 至少有一次 AI 交互的天数 - **成本** - 基于 LiteLLM 定价的估计总成本 - **连续天数** - 活跃天数的最长连续记录 - **贡献图** - 年度活动的可视化热力图 生成的 PNG 针对社交媒体分享进行了优化。与社区分享你的编程之旅！ ## 开发 ### 前置条件 ``` # Bun（必需） bun --version # Rust（用于原生模块） rustc --version cargo --version ``` ### 如何运行 按照 [开发环境设置](#development-setup) 完成后，你可以： ``` # 构建原生模块（可选但推荐） bun run build:core # 在开发模式下运行（启动 TUI） cd packages/cli && bun src/cli.ts # 或使用旧版 CLI 模式 cd packages/cli && bun src/cli.ts --light ```

高级开发

### 项目脚本 | 脚本 | 描述 | |--------|-------------| | `bun run cli` | 在开发模式下运行 CLI（使用 Bun 的 TUI） | | `bun run build:core` | 构建原生 Rust 块（release） | | `bun run build:cli` | 构建 CLI TypeScript 到 dist/ | | `bun run build` | 同时构建核心和 CLI | | `bun run dev:frontend` | 运行前端开发服务器 | **特定包脚本**（在包目录内）： - `packages/cli`：`bun run dev`、`bun run tui` - `packages/core`：`bun run build:debug`、`bun run test`、`bun run bench` **注意**：本项目使用 **Bun** 作为开发的包管理器。 ### 测试 ``` # 测试原生模块（Rust） cd packages/core bun run test:rust # Cargo tests bun run test # Node.js integration tests bun run test:all # Both ``` ### 原生模块开发 ``` cd packages/core # 以 Debug 模式构建（编译更快） bun run build:debug # 以 Release 模式构建（已优化） bun run build # 运行 Rust 基准测试 bun run bench ``` ### Graph 命令选项 ``` # 导出图表数据到文件 tokscale graph --output usage-data.json # 日期过滤（所有快捷方式均可用） tokscale graph --today tokscale graph --week tokscale graph --since 2024-01-01 --until 2024-12-31 tokscale graph --year 2024 # 按平台过滤 tokscale graph --opencode --claude # 显示处理时间基准测试 tokscale graph --output data.json --benchmark ``` ### Benchmark 标志 显示处理时间以进行性能分析： ``` tokscale --benchmark # Show processing time with default view tokscale models --benchmark # Benchmark models report tokscale monthly --benchmark # Benchmark monthly report tokscale graph --benchmark # Benchmark graph generation ``` ### 为前端生成数据 ``` # 导出数据以供可视化 tokscale graph --output packages/frontend/public/my-data.json ``` ### 性能 原生 Rust 模块提供了显著的性能提升： | 操作 | TypeScript | Rust Native | 提升倍数 | |-----------|------------|-------------|---------| | 文件发现 | ~500ms | ~50ms | **10x** | | JSON 解析 | ~800ms | ~100ms | **8x** | | 聚合 | ~200ms | ~25ms | **8x** | | **总计** | **~1.5s** | **~175ms** | **~8.5x** | *基于约 1000 个会话文件、100k 条消息的基准测试* #### 内存优化 原生模块还通过以下方式减少了约 45% 的内存使用： - 流式 JSON 解析（无全文件缓冲） - 零拷贝字符串处理 - 使用 map-reduce 的高效并行聚合 #### 运行基准测试 ``` # 生成合成数据 cd packages/benchmarks && bun run generate # 运行 Rust 基准测试 cd packages/core && bun run bench ```

## 支持的平台 ### 原生模块目标 | 平台 | 架构 | 状态 | |----------|--------------|--------| | macOS | x86_64 | ✅ 支持 | | macOS | aarch64 (Apple Silicon) | ✅ 支持 | | Linux | x86_64 (glibc) | ✅ 支持 | | Linux | aarch64 (glibc) | ✅ 支持 | | Linux | x86_64 (musl) | ✅ 支持 | | Linux | aarch64 (musl) | ✅ 支持 | | Windows | x86_64 | ✅ 支持 | | Windows | aarch64 | ✅ 支持 | ### Windows 支持 Tokscale 完全支持 Windows。TUI 和 CLI 的工作方式与 macOS/Linux 相同。 **在 Windows 上安装：** ``` # 安装 Bun (PowerShell) powershell -c "irm bun.sh/install.ps1 | iex" # 运行 tokscale bunx tokscale@latest ``` #### Windows 上的数据位置 AI 编程工具将 会话数据存储在跨平台位置。大多数工具在所有平台上使用相同的相对路径： | 工具 | Unix 路径 | Windows 路径 | 来源 | |------|-----------|--------------|--------| | OpenCode | `~/.local/share/opencode/` | `%USERPROFILE%\.local\share\opencode\` | 使用 [`xdg-basedir`](https://github.com/sindresorhus/xdg-basedir) 确保跨平台一致性 ([源码](https://github.com/sst/opencode/blob/main/packages/opencode/src/global/index.ts)) | | Claude Code | `~/.claude/` | `%USERPROFILE%\.claude\` | 所有平台路径相同 | | OpenClaw | `~/.openclaw/` (+ 旧版: `.clawdbot`, `.moltbot`, `.moldbot`) | `%USERPROFILE%\.openclaw\` (+ 旧版路径) | 所有平台路径相同 | | Codex CLI | `~/.codex/` | `%USERPROFILE%\.codex\` | 可通过 `CODEX_HOME` 环境变量配置 ([源码](https://github.com/openai/codex)) | | Gemini CLI | `~/.gemini/` | `%USERPROFILE%\.gemini\` | 所有平台路径相同 | | Amp | `~/.local/share/amp/` | `%USERPROFILE%\.local\share\amp\` | 像 OpenCode 一样使用 `xdg-basedir` | | Cursor | API 同步 | API 同步 | 通过 API 获取数据，缓存在 `%USERPROFILE%\.config\tokscale\cursor-cache\` | | Droid | `~/.factory/` | `%USERPROFILE%\.factory\` | 所有平台路径相同 | | Pi | `~/.pi/` | `%USERPROFILE%\.pi\` | 所有平台路径相同 | | Kimi CLI | `~/.kimi/` | `%USERPROFILE%\.kimi\` | 所有平台路径相同 | | Qwen CLI | `~/.qwen/` | `%USERPROFILE%\.qwen\` | 所有平台路径相同 | | Roo Code | `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/tasks/` | `%USERPROFILE%\.config\Code\User\globalStorage\rooveterinaryinc.roo-cline\tasks\` | VS Code globalStorage 任务日志 | | Kilo | `~/.config/Code/User/globalStorage/kilocode.kilo-code/tasks/` | `%USERPROFILE%\.config\Code\User\globalStorage\kilocode.kilo-code\tasks\` | VS Code globalStorage 任务日志 | | Mux | `~/.mux/sessions/` | `%USERPROFILE%\.mux\sessions\` | 所有平台路径相同 | | Synthetic | 从其他来源重新归因 | 从其他来源重新归因 | 检测 `hf:` 模型前缀 + `synthetic` 提供商 | #### Windows 特定配置 Tokscale 将其配置存储在： - **配置**：`%USERPROFILE%\.config\tokscale\settings.json` - **缓存**：`%USERPROFILE%\.cache\tokscale\` - **Cursor 凭据**：`%USERPROFILE%\.config\tokscale\cursor-credentials.json` ## 会话数据保留 默认情况下，某些 AI 编程助手会自动删除旧的会话文件。为了保留使用历史以进行准确追踪，请禁用或延长清理周期。 | 平台 | 默认值 | 配置文件 | 禁用设置 | 来源 | |----------|---------|-------------|-------------------|--------| | Claude Code | **⚠️ 30 天** | `~/.claude/settings.json` | `"cleanupPeriodDays": 9999999999` | [文档](https://docs.anthropic.com/en/docs/claude-code/settings) | | Gemini CLI | 已禁用 | `~/.gemini/settings.json` | `"general.sessionRetention.enabled": false` | [文档](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/session-management.md) | | Codex CLI | 已禁用 | N/A | 无清理功能 | [#6015](https://github.com/openai/codex/issues/6015) | | OpenCode | 已禁用 | N/A | 无清理功能 | [#4980](https://github.com/sst/opencode/issues/4980) | ### Claude Code **默认值**：30 天清理周期 添加到 `~/.claude/settings.json`： ``` { "cleanupPeriodDays": 9999999999 } ``` ### Gemini CLI **默认值**：清理已禁用（会话永久保留） 如果你启用了清理并想禁用它，请在 `~/.gemini/settings.json` 中移除或设置 `enabled: false`： ``` { "general": { "sessionRetention": { "enabled": false } } } ``` 或设置一个极长的保留期： ``` { "general": { "sessionRetention": { "enabled": true, "maxAge": "9999999d" } } } ``` ### Codex CLI **默认值**：无自动清理（会话永久保留） Codex CLI 没有内置会话清理功能。`~/.codex/sessions/` 中的会话无限期保留。 ### OpenCode **默认值**：无自动清理（会话永久保留） OpenCode 没有内置会话清理功能。`~/.local/share/opencode/storage/` 中的会话无限期保留。 ## 数据来源 ### OpenCode 位置：`~/.local/share/opencode/opencode.db` (v1.2+) 或 `storage/message/{sessionId}/*.json` (旧版) OpenCode 1.2+ 将会话存储在 SQLite 中。Tokscale 首先从 SQLite 读取，对于旧版本回退到旧版 JSON 文件。 每条消息包含： ``` { "id": "msg_xxx", "role": "assistant", "modelID": "claude-sonnet-4-20250514", "providerID": "anthropic", "tokens": { "input": 1234, "output": 567, "reasoning": 0, "cache": { "read": 890, "write": 123 } }, "time": { "created": 1699999999999 } } ``` ### Claude Code 位置：`~/.claude/projects/{projectPath}/*.jsonl` JSONL 格式，包含带有使用数据的助手消息： ``` {"type": "assistant", "message": {"model": "claude-sonnet-4-20250514", "usage": {"input_tokens": 1234, "output_tokens": 567, "cache_read_input_tokens": 890}}, "timestamp": "2024-01-01T00:00:00Z"} ``` ### Codex CLI 位置：`~/.codex/sessions/*.jsonl` 基于事件的格式，包含 `token_count` 事件： ``` {"type": "event_msg", "payload": {"type": "token_count", "info": {"last_token_usage": {"input_tokens": 1234, "output_tokens": 567}}}} ``` ### Gemini CLI 位置：`~/.gemini/tmp/{projectHash}/chats/*.json` 包含消息数组的会话文件： ``` { "sessionId": "xxx", "messages": [ {"type": "gemini", "model": "gemini-2.5-pro", "tokens": {"input": 1234, "output": 567, "cached": 890, "thoughts": 123}} ] } ``` ### Cursor IDE 位置：`~/.config/tokscale/cursor-cache/`（通过 Cursor API 同步） Cursor 数据使用你的会话 token 从 Cursor API 获取并在本地缓存。运行 `tokscale cursor login` 进行身份验证。有关设置说明，请参阅 [Cursor IDE 命令](#cursor-ide-commands)。 ### OpenClaw 位置：`~/.openclaw/agents/*/sessions/sessions.json`（同时扫描旧版路径：`~/.clawdbot/`、`~/.moltbot/`、`~/.moldbot/`） 指向 JSONL 会话文件的索引文件： ``` { "agent:main:main": { "sessionId": "uuid", "sessionFile": "/path/to/session.jsonl" } } ``` 带有 model_change 事件和助手消息的会话 JSONL 格式： ``` {"type":"model_change","provider":"openai-codex","modelId":"gpt-5.2"} {"type":"message","message":{"role":"assistant","usage":{"input":1660,"output":55,"cacheRead":108928,"cost":{"total":0.02}},"timestamp":1769753935279}} ``` ### Pi 位置：`~/.pi/agent/sessions//*.jsonl` 带有会话头和消息条目的 JSONL 格式： ``` {"type":"session","id":"pi_ses_001","timestamp":"2026-01-01T00:00:00.000Z","cwd":"/tmp"} {"type":"message","id":"msg_001","timestamp":"2026-01-01T00:00:01.000Z","message":{"role":"assistant","model":"claude-3-5-sonnet","provider":"anthropic","usage":{"input":100,"output":50,"cacheRead":10,"cacheWrite":5,"totalTokens":165}}} ``` ### Kimi CLI 位置：`~/.kimi/sessions/{GROUP_ID}/{SESSION_UUID}/wire.jsonl` 带有 StatusUpdate 消息的 wire.jsonl 格式： ``` {"type": "metadata", "protocol_version": "1.3"} {"timestamp": 1770983426.420942, "message": {"type": "StatusUpdate", "payload": {"token_usage": {"input_other": 1562, "output": 2463, "input_cache_read": 0, "input_cache_creation": 0}, "message_id": "chatcmpl-xxx"}}} ``` ### Qwen CLI 位置：`~/.qwen/projects/{PROJECT_PATH}/chats/{CHAT_ID}.jsonl` 格式：JSONL — 每行一个 JSON 对象，每个对象包含 `type`、`model`、`timestamp`、`sessionId` 和 `usageMetadata` 字段。 Token 字段（来自 `usageMetadata`）： - `promptTokenCount` → 输入 token - `candidatesTokenCount` → 输出 token - `thoughtsTokenCount` → 推理/思考 token - `cachedContentTokenCount` → 缓存输入 token ### Roo Code 位置： - 本地：`~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/tasks/{TASK_ID}/ui_messages.json` - 服务端（尽力而为）：`~/.vscode-server/data/User/globalStorage/rooveterinaryinc.roo-cline/tasks/{TASK_ID}/ui_messages.json` 每个任务目录还可能包含带有 `` 块的 `api_conversation_history.json`，用于模型/代理元数据。 `ui_messages.json` 是一个 UI 事件数组。Tokscale 仅统计： - `type == "say"` - `say == "api_req_started"` `text` 字段是包含 token/成本元数据的 JSON： ``` { "type": "say", "say": "api_req_started", "ts": "2026-02-18T12:00:00Z", "text": "{\"cost\":0.12,\"tokensIn\":100,\"tokensOut\":50,\"cacheReads\":20,\"cacheWrites\":5,\"apiProtocol\":\"anthropic\"}" } ``` ### Kilo 位置： - 本地：`~/.config/Code/User/globalStorage/kilocode.kilo-code/tasks/{TASK_ID}/ui_messages.json` - 服务端（尽力而为）：`~/.vscode-server/data/User/globalStorage/kilocode.kilo-code/tasks/{TASK_ID}/ui_messages.json` Kilo 使用与 Roo Code 相同的任务日志格式。Tokscale 应用相同的规则： - 仅统计 `ui_messages.json` 中的 `say/api_req_started` 事件 - 从 `text` JSON 解析 `tokensIn`、`tokensOut`、`cacheReads`、`cacheWrites`、`cost` 和 `apiProtocol` - 在可用时从同级 `api_conversation_history.json` 丰富模型/代理元数据 ### Mux 位置： - `~/.mux/sessions/{WORKSPACE_ID}/session-usage.json` Mux 在 `session-usage.json` 文件中存储累积的每次会话 token 使用情况。每个文件包含一个带有每个模型 token 细分的 `byModel` 映射： - `input`、`cached`（缓存读取）、`cacheCreate`（缓存写入）、`output`、`reasoning` - 模型名称使用 `provider:model` 格式（例如 `anthropic:claude-opus-4-6`）—— tokscale 剥离提供商前缀以进行模型识别 - 子代理使用量会自动汇总到父会话中，因此不会重复计算 ### Synthetic (synthetic.new) Synthetic 使用量通过现有代理会话文件的后处理进行检测。当消息使用 `hf:` 模型 ID 或 synthetic 提供商（`synthetic`、`glhf`、`octofriend`）时，它们会被重新归因为 `synthetic`。 Tokscale 还会检查 `~/.local/share/octofriend/sqlite.db` 的 Octofriend SQLite，并在可用时解析带有 token 的记录。 ## 定价 Tokscale 从 [LiteLLM 的定价数据库](https://github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json) 获取实时定价。 **动态回退**：对于 LiteLLM 中尚不可用的模型（例如，最近发布的模型），Tokscale 自动从 [OpenRouter 的端点 API](https://openrouter.ai/docs/api/api-reference/endpoints/list-endpoints) 获取定价。这确保你从模型的原始提供商（例如 glm-4.7 的 Z.AI）获得准确的定价，而无需等待 LiteLLM 更新。 **Cursor 模型定价**：对于 LiteLL 和 OpenRouter 中尚不存在的极新发布模型（例如 `gpt-5.3-codex`），Tokscale 包含源自 [Cursor 模型文档](https://cursor.com/en-US/docs/models) 的硬编码定价。这些覆盖在检查所有上游源之后但在模糊匹配之前进行，因此一旦真正的上游定价可用，它们会自动让位。 **缓存**：定价数据缓存到磁盘，TTL 为 1 小时，以实现快速启动： - LiteLLM 缓存：`~/.cache/tokscale/pricing-litellm.json` - OpenRouter 缓存：`~/.cache/tokscale/pricing-openrouter.json`（缓存来自支持提供商的模型作者定价） 定价包括： - 输入 token - 输出 token - 缓存读取 token（折扣） - 缓存写入 token - 推理 token（用于 o1 等模型） - 阶梯定价（超过 20 万 token） ## 贡献 欢迎贡献！请遵循以下步骤： 1. Fork 仓库 2. 创建功能分支 (`git checkout -b feature/amazing-feature`) 3. 进行更改 4. 运行测试 (`cd packages/core && bun run test:all`) 5. 提交更改 (`git commit -m 'Add amazing feature'`) 6. 推送到分支 (`git push origin feature/amazing-feature`) 7. 打开 Pull Request ### 开发指南 - 遵循现有代码风格 - 为新功能添加测试 - 根据需要更新文档 - 保持提交专注和原子性 ## 致谢 - [ccusage](https://github.com/ryoppippi/ccusage)、[viberank](https://github.com/sculptdotfun/viberank) 和 [Isometric Contributions](https://github.com/jasonlong/isometric-contributions) 提供灵感 - [Ratatui](https://github.com/ratatui/ratatui) 提供终端 UI 框架 - [Solid.js](https://www.solidjs.com/) 提供响应式渲染 - [LiteLLM](https://github.com/BerriAI/litellm) 提供定价数据 - [napi-rs](https://napi.rs/) 提供 Rust/Node.js 绑定 - [github-contributions-canvas](https://github.com/sallar/github-contributions-canvas) 提供 2D 图谱参考 ## 许可证

MIT © Junho Yeo

如果你觉得这个项目有趣，**请考虑给它点个 Star ⭐** 或 [在 GitHub 上关注我](https://github.com/junhoyeo) 并加入这段旅程（已有 1.1k+ 人参与）。我日夜不停地编码，定期发布令人惊叹的东西——你的支持不会被浪费。

标签：3D图表, AI编程助手, ChatGPT, Claude, Cursor, CVE检测, DLL 劫持, DNS解析, Gemini, Kimi, LLM, NPM包, OpenAI, OSV-Scalibr, Promptflow, Token统计, TypeScript, Unmanaged PE, 代码示例, 使用量监控, 全球排行榜, 内存规避, 可视化界面, 命令行界面, 大语言模型, 威胁情报, 安全插件, 开发者工具, 开源项目, 数据分析, 生产力工具, 通知系统