当前位置：首页 > news >正文

AI编码助手年度使用数据可视化工具tokely全解析

news 2026/5/2 6:26:30

1. 项目概述：你的AI编码助手年度“体检报告”

如果你和我一样，日常开发重度依赖Claude Code、Cursor这类AI编码助手，那你有没有好奇过，过去一年里，你和这些“数字同事”的合作到底有多紧密？你是在稳步提升效率，还是陷入了某种依赖？你用得最多的模型是哪个？哪个月份是你和AI并肩作战的“高产期”？这些问题，光靠感觉是说不清的，我们需要数据。

tokely就是这样一个能给你答案的命令行工具。它像一位细心的数据管家，默默扫描你本地环境中各大主流AI编码助手（包括Claude Code、Codex、Cursor、Gemini CLI、Open Code、OpenClaw、Pi Coding Agent）在过去一整年（滚动计算，截止到今天）的使用日志。然后，它会生成一张类似GitHub贡献图那样的热力图，直观地展示你每日的token消耗情况。这不仅仅是一张好看的图片，更是一份关于你编程习惯、效率变迁和工具偏好的年度数据报告。

想象一下，运行一条简单的命令tokely，就能得到一张信息密度极高的图表：顶部清晰地标出过去30天的总使用量、输入/输出token数；底部则揭示了你的“最爱模型”、近期使用趋势，甚至计算出了你连续使用AI助手的最长和当前“打卡” streak。这对于量化个人生产力、回顾技术探索路径，或者单纯满足一下好奇心，都极具价值。接下来，我就带你从零开始，深入拆解这个工具，看看它如何工作，以及如何为你所用。

2. 核心设计思路与架构解析

2.1 解决的核心痛点：碎片化数据的统一视图

现代开发者可能同时使用多个AI编码工具。Claude Code将对话记录在JSONL文件里，Cursor的数据可能藏在SQLite数据库或通过API获取，Open Code又有自己的存储格式。这些数据散落在系统各处，格式各异，手动统计几乎是不可能的任务。tokely的核心价值就在于，它定义了一套统一的“数据采集器”（Provider）接口，为每个支持的AI工具编写了适配器，将这些异构的、碎片化的使用日志，聚合、清洗、计算，最终输出为标准化的、可视化的洞察。

2.2 整体架构：模块化的Monorepo设计

从项目结构就能看出其清晰的模块化思想。它采用Monorepo布局，将不同职责的代码分离，便于维护和扩展。

packages/ cli/ # 命令行入口和主要逻辑 registry/ # 所有数据提供者（Provider）的注册与管理中心 tooling/ typescript-config/ # 共享的TypeScript配置

CLI包 (packages/cli)：这是用户直接交互的部分。它负责解析命令行参数（如--today,--output,--format），根据参数决定要加载哪些Provider，协调数据获取、计算和渲染流程，并最终将结果输出到终端或文件。
注册表包 (packages/registry)：这是项目的大脑。它维护着一个所有可用Provider的清单。每个Provider都是一个独立的模块，知道如何去特定的系统路径寻找日志文件，如何解析特定格式（JSONL、SQLite、API响应等），并将原始日志转化为结构化的每日token使用数据。当CLI需要数据时，就向注册表请求对应的Provider实例。
共享配置 (tooling/typescript-config)：确保整个项目使用一致的TypeScript编译选项和代码质量规则，这是现代TypeScript项目保持代码一致性的常见做法。

这种设计的好处非常明显：高内聚、低耦合。如果你想新增对一个AI工具（比如一个新兴的、本地部署的编码助手）的支持，你只需要在registry中实现一个新的Provider类，注册进去即可，完全不需要改动CLI的核心逻辑。这极大地提升了项目的可扩展性。

2.3 数据处理策略：流式处理与内存安全

处理可能长达一年的日志文件，尤其是像Claude Code、Codex这样生成大量JSONL记录的工具，内存占用是一个必须谨慎对待的问题。tokely在这方面做得相当专业。

它没有选择将整个文件读入内存再解析，而是采用了流式处理（Streaming）和有界解析（Bounded Parsing）的策略。通过环境变量TOKELY_MAX_JSONL_RECORD_BYTES（默认64MB）来限制单条记录的最大尺寸。解析器会边读取边计数，一旦某条记录超过这个上限，就会立即抛出明确的错误，指出文件名、行号和限制大小，而不是让进程因内存不足而崩溃。

对于Codex这类可能包含大量与“使用量”无关的记录（如系统消息、配置同步）的日志，tokely的Provider会先进行轻量级的筛选，只解析那些与token消耗相关的记录，无关的大记录会被跳过并仅以警告形式告知。这种设计确保了工具的健壮性，即使面对畸形或意外巨大的数据文件，也能优雅地失败或跳过，而不会影响整体数据统计。

3. 环境准备与项目初始化

3.1 运行环境与依赖安装

tokely使用Bun作为运行时和包管理器。Bun以其快速的启动速度和内置的打包、测试工具链而闻名，非常适合这类CLI工具。如果你的系统上还没有Bun，需要先安装它。

macOS/Linux安装Bun：

curl -fsSL https://bun.sh/install | bash

安装完成后，重启你的终端，运行bun --version确认安装成功。

Windows安装Bun：可以通过Windows的包管理器winget安装：

winget install oven.bun

或者使用PowerShell脚本，具体请参考官方文档。

准备好Bun后，获取tokely的源代码。通常你需要克隆项目仓库：

git clone https://github.com/evoerax/tokely.git cd tokely

接下来，安装项目依赖。在项目根目录下运行：

bun install

这个命令会读取package.json，安装所有必要的依赖包到node_modules目录。由于是Monorepo，Bun会处理好各个子包（cli,registry）之间的内部链接。

注意：确保你的网络环境能够顺畅访问 npm 注册表。如果遇到包下载缓慢或失败的问题，可以尝试配置国内镜像源，例如bun config set registry https://registry.npmmirror.com。

安装完成后，运行项目自带的检查脚本，确保一切就绪：

bun run check

这个脚本通常会执行类型检查（tsc --noEmit）和代码格式化检查（如biome check），确保代码质量。

3.2 构建与开发模式运行

项目使用TypeScript编写，因此需要先编译成JavaScript才能运行。你可以选择一次性构建，或者在开发模式下实时运行。

一次性构建：

bun run build

这会在各包的目录下（如packages/cli/dist）生成编译后的JS文件。之后，你可以直接运行编译产物：

node packages/cli/dist/cli.js

开发模式运行（推荐用于测试或贡献代码）：如果你在修改代码，或者想快速测试，可以使用开发模式。它会利用Bun的即时编译能力，直接运行TypeScript源码。

bun run --cwd packages/cli dev

--cwd packages/cli指定了工作目录为cli包，dev是package.json中定义的一个脚本，通常对应tsx或bun直接运行入口文件。

全局安装使用（最便捷的方式）：对于日常使用，最佳方式是将tokely安装为全局命令行工具。这通常需要在项目的cli包中，将其链接到全局。由于项目文档没有明确给出npm publish或bun link的指引，一种常见的方式是使用npm link或bun link。

首先，进入cli包目录并创建全局链接：

cd packages/cli bun link

如果成功，你应该会看到类似 “Package ‘@tokely/cli’ linked globally” 的提示。之后，你就可以在系统的任何位置，直接使用tokely命令了。

tokely --help

实操心得：在链接全局包时，有时会因为权限问题或现有冲突导致失败。如果bun link不成功，可以尝试加上--global标志，或者使用sudo（Linux/macOS）。更稳妥的做法是，在开发阶段，我更喜欢在项目根目录创建一个别名（alias）或简单的shell脚本，直接指向bun run --cwd packages/cli dev，这样能确保始终使用最新的代码。

4. 命令行使用详解与实战案例

4.1 基础命令与输出解读

安装或链接成功后，tokely的基本使用非常简单。不带任何参数运行，它会执行默认行为。

tokely

默认行为解析：

时间范围：自动计算从今天开始，倒推一整年（365天）的日期范围。
数据源：自动扫描所有已配置的、本机有数据的AI工具（Provider）。
选择逻辑：在所有有数据的Provider中，按照内置的优先级（Claude Code → Codex → Cursor → Open Code → OpenClaw → Amp → Gemini CLI → Pi Coding Agent），选择前5个数据量最丰富的进行渲染。
输出结果：在当前目录下，生成一个名为heatmap-last-year.png的PNG图片文件。

打开生成的PNG图片，你会看到类似下图的结构（此处为文字描述）：

顶部区域：显示每个被选中的Provider的名称和其对应的核心指标。
- LAST 30 DAYS: 过去30天消耗的总token数。
- INPUT TOKENS: 过去一年总的输入token。
- OUTPUT TOKENS: 过去一年总的输出token。
- TOTAL TOKENS: 过去一年总token（包含缓存token，如果该Provider支持统计的话）。
中部热力图：一个经典的周历风格热力图。Y轴是星期几（默认周一为每周起始），X轴是月份。每个小格子代表一天，颜色越深，表示当天消耗的token越多。鼠标悬停（在某些查看器中）或从颜色深浅可以直观比较不同日期的活跃度。
底部区域：显示每个Provider的深度洞察。
- MOST USED MODEL: 你过去一年中使用次数最多（按总token计）的模型名称。tokely会智能地归一化模型名，例如去掉类似-20251101的日期后缀，让claude-3-5-sonnet-20241022和claude-3-5-sonnet-20250201被识别为同一个模型系列，统计更合理。
- RECENT USE (LAST 30 DAYS): 过去30天内，你使用最多的模型。
- LONGEST STREAK: 你连续使用该AI助手的最长天数记录。
- CURRENT STREAK: 你最近一次连续使用的天数（可能仍在继续）。

4.2 常用参数与场景化示例

tokely提供了丰富的参数来定制输出，适应不同场景。

1. 快速查看今日统计：如果你只想看看今天用了多少token，而不是生成一整年的图，可以使用--today标志。

tokely --today

这会在终端直接打印出今日的token使用情况摘要，而不会生成图片文件。非常适合快速检查。

2. 自定义输出路径和格式：默认的PNG格式虽然通用，但SVG格式作为矢量图，缩放无损，更适合嵌入文档或进一步编辑。使用-o(或--output) 指定路径，使用-f(或--format) 指定格式。

# 输出SVG矢量图到指定目录 tokely --output ./my-reports/2024-q4-heatmap.svg # 等价于 tokely -o ./my-reports/2024-q4-heatmap.svg -f svg

如果只指定了输出路径，tokely会根据文件扩展名自动推断格式（支持.png,.svg,.json）。如果路径和格式都未指定，则默认为PNG。

3. 深色主题：生成更适合暗色模式IDE或网站背景的图表。

tokely --dark --format svg

4. 筛选特定AI工具：你可能只关心某几个工具的数据。tokely允许你通过标志位精确选择。

# 只看Claude Code和Cursor的数据 tokely --claude --cursor

当你指定了Provider标志后，tokely的行为会发生变化：

它只加载你指定的这些Provider。
它只检查这些指定Provider的数据可用性。
如果任何一个被指定的Provider没有找到数据，命令会直接报错退出。这确保了当你明确要求看某个工具的数据时，如果看不到，你会立刻知道是数据缺失，而不是工具被静默过滤掉了。
输出文件名会自动加上Provider后缀，例如heatmap-last-year_claude_cursor.png。

5. 合并所有工具数据：如果你想得到一个整体的、跨所有AI工具的编码活动视图，可以使用--all参数。

tokely --all

这会加载所有可用的Provider，将它们的token使用数据合并计算，生成一张统一的、代表你“总AI编码活动”的热力图。输出文件名会变为heatmap-last-year_all.png。底部的模型排名、Streak等数据，也会在所有工具的数据基础上进行全局计算。

注意事项：--all和指定多个Provider标志（如--claude --cursor）的区别在于，--all是“加载所有有数据的”，而后者是“只加载指定的，并且指定的必须全有数据”。同时，--all会生成一张合并图，而指定多个Provider会为每个Provider生成单独的子图（通常并排显示）。

4.3 高级功能：JSON数据导出

热力图是给人看的，但原始数据可能用于更多分析。tokely支持导出结构化的JSON数据。

tokely --format json -o usage_data.json

生成的JSON文件包含一个固定的version字段（如"2026-03-03"），以及每个Provider的详细数据：

title,colors: 提供者名称和配色信息。
daily: 一个数组，包含过去365天里每一天的数据。每个对象有date（日期）、input、output、cache、total（token数）。
daily[].breakdown:这是非常有价值的部分。它提供了当天按模型细分的token使用情况，按总token数排序。你可以清楚地看到在某一天，你分别用了Claude 3.5 Sonnet、Opus等模型各多少token。
insights: 包含mostUsedModel（年度最爱模型）和recentMostUsedModel（近期最爱模型）等信息。

有了这份JSON数据，你就可以用Python、JavaScript等任何你熟悉的工具进行二次分析，比如计算月度趋势、模型使用占比饼图，或者与你自己的Git提交记录进行关联分析，探索AI使用与代码产出效率的关系。

5. 各AI工具数据源定位与配置解析

tokely的强大之处在于它能够自动发现不同AI工具存储在系统各处的日志。了解这些路径，有助于你在工具报“找不到数据”时进行排查，或者手动验证数据是否存在。

5.1 各Provider默认数据路径

工具名称	环境变量 (优先级高)	默认路径 (环境变量未设置时)	数据格式/说明
Claude Code	`$CLAUDE_CONFIG_DIR`	`~/.config/claude/projects` `~/.claude/projects`	逗号分隔的目录列表。扫描这些目录下的JSONL文件。
Codex	`$CODEX_HOME`	`~/.codex/sessions`	会话目录下的JSONL文件。
Cursor	`$CURSOR_STATE_DB_PATH`	macOS:`~/Library/Application Support/Cursor/User/globalStorage/state.vscdb` Windows:`%APPDATA%\Cursor\User\globalStorage\state.vscdb` Linux:`~/.config/Cursor/User/globalStorage/state.vscdb`	首先从上述路径的SQLite数据库中读取认证token，然后调用Cursor的CSV导出API获取使用数据。需要网络连接。
Gemini CLI	`$GEMINI_CONFIG_DIR`	`~/.gemini/tmp/*/chats/session-.json`	通配符匹配会话JSON文件。
Open Code	`$OPENCODE_DATA_DIR`	1.`~/.local/share/opencode/opencode.db`(SQLite，优先) 2.`~/.local/share/opencode/storage/message`(旧版JSON)	优先使用SQLite数据库，回退到旧版JSON文件存储。
OpenClaw	无	`~/.openclaw/agents` `~/.clawdbot/agents` `~/.moltbot/agents` `~/.moldbot/agents`	扫描上述可能目录中的`*.jsonl`会话记录文件。
Pi Coding Agent	`$PI_CODING_AGENT_DIR`	`~/.pi/agent/sessions`	解析会话日志中的助手消息，按处理每轮对话的模型进行分组统计。

5.2 环境变量与性能调优

除了数据路径，tokely还提供了两个关键的环境变量，用于控制资源使用和处理大文件的行为。

TOKELY_FILE_PROCESS_CONCURRENCY：
- 作用：限制同时处理的文件数量。主要影响Claude Code和Codex这类可能包含大量JSONL文件的Provider。
- 默认值：16。
- 调整场景：如果你的系统IO性能较弱（如机械硬盘），或者在处理海量会话文件时内存占用过高，可以适当调低此值（例如设为4或8），以降低并发IO压力。反之，在SSD和高性能CPU上，可以保持或略微调高以加速处理。
TOKELY_MAX_JSONL_RECORD_BYTES：
- 作用：单条JSONL记录允许的最大字节数。这是防止畸形或异常大记录导致内存溢出的安全阀。
- 默认值：67108864(64 MB)。对于正常的AI对话日志，一条记录几乎不可能达到这个大小。
- 调整场景：除非你确信你的日志文件包含合法的、超过64MB的单条记录（这非常罕见），否则不要修改这个值。如果遇到处理失败并提示记录过大，首先应该检查日志文件是否损坏。在极特殊情况下，你可以临时调高此值，但需警惕内存风险。

如何使用环境变量：在运行tokely命令前设置即可。

# 在Linux/macOS的终端中 export TOKELY_FILE_PROCESS_CONCURRENCY=8 export TOKELY_MAX_JSONL_RECORD_BYTES=134217728 # 128MB tokely --all # 在Windows的PowerShell中 $env:TOKELY_FILE_PROCESS_CONCURRENCY=8 $env:TOKELY_MAX_JSONL_RECORD_BYTES=134217728 tokely --all # 或者单次执行时内联设置（Linux/macOS） TOKELY_FILE_PROCESS_CONCURRENCY=8 tokely --claude

排查技巧：如果tokely报告某个Provider“No data available”（无可用数据），首先按照上表检查对应的默认路径是否存在。例如，对于Cursor，检查state.vscdb文件是否存在；对于Claude Code，检查~/.config/claude/projects目录。其次，确认你有该目录或文件的读取权限。对于Cursor，还需要确保网络通畅，因为它需要调用在线API。

6. 常见问题排查与实战心得

在实际使用和集成tokely的过程中，你可能会遇到一些典型问题。以下是我总结的排查清单和解决方案。

6.1 问题排查速查表

问题现象	可能原因	解决方案
运行`tokely`无任何输出，或立即退出。	1. 所有Provider均未找到数据。 2. 构建失败，CLI未正确生成。	1. 使用`tokely --claude`等命令指定一个你确定在用的工具，看是否报错。确认数据路径是否正确。 2. 运行`bun run build`查看是否有编译错误。尝试在项目内直接运行`node packages/cli/dist/cli.js --help`。
错误：`Error: No data available for provider: cursor`	1. Cursor数据路径错误或文件不存在。 2. Cursor的state.vscdb数据库中缺少认证token。 3. 网络问题，无法访问Cursor API。	1. 检查默认路径下的`state.vscdb`文件是否存在。 2. 确保你已登录Cursor并近期使用过，token会被存储。 3. 检查网络连接，尝试使用`--cursor`单独运行看详细错误。
生成的图片是空的，或热力图全灰。	统计时间范围内（过去一年）确实没有使用数据。	使用`--today`参数检查今日是否有数据。确认你使用的AI工具是否将日志存储在了默认路径。
处理大型Claude Code日志时程序卡住或内存激增。	可能遇到了超大的单条JSONL记录。	1. 检查输出中是否有关于“oversized record”的警告或错误。 2. 尝试设置`TOKELY_MAX_JSONL_RECORD_BYTES=67108864`（确认默认值）。 3. 可以尝试用文本编辑器打开可疑的JSONL文件，检查是否有异常行。
命令报错：`Unexpected token... in JSON at position...`	某个日志文件（JSONL或JSON）格式损坏，不符合标准JSON语法。	1. 根据错误信息定位到具体文件和行号。 2. 手动查看该文件，可能文件在写入时被中断，导致记录不完整。可以尝试备份后删除损坏的文件或行。
`--format json`输出的文件内容不全或格式错误。	可能在写入过程中被中断，或其他进程锁定了文件。	1. 确保输出目录有写入权限。 2. 尝试输出到不同目录或使用不同文件名。 3. 用`jq`工具验证JSON格式：`jq . usage_data.json`。

6.2 实战心得与进阶用法

自动化与定期报告：tokely是命令行工具，天生适合自动化。你可以写一个简单的Shell脚本或Cron任务，每周或每月自动运行一次，将生成的SVG或JSON报告保存到特定目录，甚至通过脚本将其嵌入到你的周报Markdown文件中。
```
# 示例：每周一生成上周的报告 # 在 crontab 中添加 (Linux/macOS) 0 9 * * 1 cd /path/to/your/reports && /usr/local/bin/tokely --all --dark -f svg -o ./weekly/ai-usage-$(date +\%Y-\%m-\%d).svg
```
数据清洗与归档：AI编码助手的日志文件可能会随时间增长，占用不少空间。tokely只读取数据，不会修改或删除原始日志。你可以根据自己的需要，定期归档或清理旧的日志文件。在清理前，不妨先用tokely生成一份历史报告作为存档。
模型名称归一化的价值：这个特性非常实用。因为像Claude这样的服务，模型标识符会带有发布日期后缀。如果不做归一化，“claude-3-5-sonnet-20241022”和“claude-3-5-sonnet-20250201”会被算作两个不同的模型，从而分散你的使用统计。tokely的归一化处理让你能清晰地看到自己在“Claude 3.5 Sonnet”这个系列模型上的总投入，洞察更有意义。
理解“Streak”的计算：最长连续使用 streak 和当前 streak 是一个有趣的社交化功能。它计算的是“有使用记录”的天数是否连续。这能侧面反映你的开发节奏。比如，一个长达100天的 streak 可能意味着你有一个长期、持续的项目在进行。而 streak 的中断，也许对应着假期或项目间隙。
贡献与扩展：如果你使用的AI编码工具不在tokely的支持列表中，并且你有一定的TypeScript/JavaScript开发能力，那么为它添加一个新的Provider会是一个很好的开源贡献。核心工作就是在packages/registry/src/providers/目录下，参照现有实现（如claude.ts），创建一个新的Provider类，实现数据定位、解析和标准化输出的方法，然后在注册表中添加它。项目的模块化设计使得这种扩展变得相对清晰。