1. 项目概述为什么你需要一个统一的AI编码工具用量追踪器如果你和我一样是个深度依赖AI辅助编程的开发者那你手头肯定不止一个工具。Claude Code、Cursor、GitHub Copilot、Warp AI... 这些工具各自为政每个都有自己的用量统计界面有的藏在设置深处有的干脆不提供详细数据。我每天切换着用月底收到账单时总是一头雾水我这个月到底用了多少token哪个工具用得最狠成本大头花在哪了更实际的是在团队协作和招聘场景里这个问题被放大了。作为技术负责人我面试过不少声称“精通AI编程”的候选人但光凭嘴说很难判断。简历上写“熟练使用Copilot”和真正把AI深度集成到工作流里完全是两码事。我们需要一个客观的、量化的指标来评估开发者对AI工具的真实使用习惯和深度而不仅仅是“会不会用”。这就是我动手开发a2zusage的初衷。它不是什么复杂的监控平台而是一个极简的、本地的命令行工具一个命令就能把你所有AI编码工具的用量数据聚合起来用一张清晰的表格呈现给你。它的核心价值就两点对自己是成本与习惯的可视化对团队是能力与效率的量化参考。你不用再在各个应用、网站之间跳转也不用去翻找那些藏在犄角旮旯的日志文件a2zusage帮你把这些脏活累活都干了。2. 核心设计思路如何安全、无侵入地聚合异构数据设计这样一个工具最大的挑战在于数据源的多样性和安全性。每个AI工具存储用量数据的方式千奇百怪有的是明文JSON有的是SQLite数据库有的通过API还有的甚至加密了。我的设计原则非常明确隐私第一、本地优先、零配置启动。2.1 数据源探测与适配器模式a2zusage的核心架构采用了经典的“适配器模式”。我为每一个支持的AI工具如Claude Code、Cursor编写了一个独立的“Provider”提供者。每个Provider只做三件事探测检查该工具的特定数据文件或目录在本地是否存在例如检查~/.claude/projects/或~/.config/Code/User/globalStorage/tabnine.tabnine-vscode等路径。解析如果存在则按照该工具独有的格式JSONL、SQLite、日志文本等读取并解析出用量数据如token数、请求次数。标准化将解析出的原始数据统一转换成a2zusage内部定义的标准数据结构包含今日、本周、本月、总计的输入/输出token及请求数。这样做的好处是隔离性极强。新增对一个工具的支持就是新增一个Provider模块完全不会影响其他工具的代码。所有Provider并行执行最后将结果汇总。这也是为什么项目初期就能快速支持14个工具的原因。2.2 隐私安全的实现细节“所有数据读取都在本地进行”这句话不是口号是架构约束。这意味着无网络请求绝大多数Provider如Claude、Cursor、Windsurf在运行时根本不会发起任何网络连接。它们只是在读取你硬盘上已经存在的文件。API密钥隔离对于少数需要联网获取数据的工具如GitHub Copilot、OpenAI Codexa2zusage严格遵循“显式配置”原则。它不会尝试自动扫描你的环境变量或密钥链。你必须主动通过环境变量如GITHUB_TOKEN,OPENAI_API_KEY或命令行参数提供密钥它才会调用相应的官方API。如果你不配置相关Provider会直接返回“未配置”或“不可用”状态绝不会尝试偷取或泄露你的密钥。数据不出本地解析后的用量数据仅在内存中处理并直接输出到你的终端。a2zusage本身没有后端服务没有任何数据上报、收集或存储功能。你可以完全审计其开源的Rust代码来确认这一点。2.3 为什么选择Rust实现项目用Rust写不是跟风。基于以下几点考量性能与零开销工具需要快速扫描、解析可能很大的日志文件或数据库。Rust的零成本抽象和极致性能保证了即使数据量巨大也能在瞬间完成聚合用户体验流畅。单二进制文件与跨平台Rust编译生成的是静态链接的单可执行文件。用户无需安装复杂的运行时环境如Node.js、Python解释器直接下载一个二进制就能跑。这对于需要分发给团队不同操作系统成员macOS、Linux、Windows的工具来说部署成本极低。内存安全与可靠性工具会处理用户磁盘上各种格式的数据用Rust能最大程度避免因内存错误导致的崩溃或数据损坏这对于一个需要“默默工作”的CLI工具来说至关重要。丰富的生态系统对于SQLite解析、JSON处理、命令行参数解析等需求Rust的crate生态已经非常成熟和完善。3. 安装与快速上手三种方式总有一种适合你让用户快速用起来是第一要务。a2zusage提供了多种安装方式适应不同用户的使用习惯。3.1 最推荐使用npx零安装运行如果你只是偶尔想查看一下或者想在别人的机器上快速检查强烈推荐使用npx。这是Node.js自带的一个工具允许你直接运行npm仓库里的包而无需先进行全局安装。npx a2zusagelatest执行这条命令npx会自动去下载最新版本的a2zusage一个预编译好的二进制文件运行它然后在你不需要时可以清理掉缓存。这几乎没有任何使用门槛只要你的系统有Node.js环境现在绝大多数开发机都有就行。注意首次使用npx运行可能会慢几秒因为它需要下载。后续运行会有缓存速度就很快了。3.2 长期使用全局安装如果你打算频繁使用把它当作一个日常命令那么全局安装更合适。# 使用 npm 安装 npm install -g a2zusage # 安装后直接在终端任何位置运行 a2zusage对于Rust开发者也可以通过Cargo安装这通常会获得理论上最佳的性能因为是本地编译cargo install a2zusage3.3 从源码构建对于想贡献代码、修改功能或者单纯喜欢“从源码构建”这种仪式感的硬核用户git clone https://github.com/aezizhu/a2zaiusage.git cd a2zaiusage cargo build --release # 编译后的二进制位于 ./target/release/a2zusage ./target/release/a2zusage从源码构建需要你本地安装有完整的Rust工具链。3.4 首次运行与“医生”模式第一次运行a2zusage它会自动扫描你的系统寻找所有已支持的AI工具的痕迹。如果某个工具你没安装过或者数据文件不在默认路径它对应的行会显示为“未找到”或“未配置”。如果你发现某个你认为应该被检测到的工具没有出现或者数据看起来不对可以使用内置的doctor命令进行诊断a2zusage doctor这个命令会做两件事列出所有a2zusage支持的工具。针对每一个工具显示它尝试查找的具体文件路径并标明该路径是否存在、是否可读。这能帮你快速定位问题是工具根本没安装是数据文件被移动了还是权限不足输出结果非常直观是排查问题的第一把钥匙。4. 核心功能详解从基础查询到高级过滤安装好了我们来仔细看看a2zusage到底能干什么。它的功能设计遵循了Unix哲学做好一件事并通过参数组合提供灵活性。4.1 默认表格视图一目了然的全局概览不带任何参数直接运行a2zusage你会得到一个精心格式化的ASCII表格输出就像项目介绍里展示的那样。这个视图是为你快速“瞥一眼”整体情况设计的。表格的列设计包含了核心维度Tool工具名称。Status状态。✓ Active表示成功找到并解析了数据○ N/A表示未找到/未配置⚠️ Partial表示找到了数据但可能不完整如只有请求数没有token数。Today / This Week / This Month / Total分别显示今日、本周、本月和总计的用量。单位可能是tokens也可能是requests请求次数这取决于该工具提供的数据粒度。-表示在该时间周期内无数据。这个视图让你在5秒内就能回答“我现在主要在用哪几个工具”、“今天哪个工具消耗最大”、“GitHub Copilot我这个月激活了吗” 这类问题。4.2 按工具筛选聚焦深度分析当你需要深入研究某一个特定工具的用量细节时可以使用-t或--tool参数进行过滤。# 只看 Claude Code 的用量 a2zusage -t claude-code # 只看 Cursor 的用量 a2zusage -t cursor # 可以同时指定多个工具用逗号分隔 a2zusage -t claude-code,warp这个功能在对比两个相似工具比如Claude Code和Cursor的使用习惯时特别有用。你可以清晰地看到在相同的时间周期内你在每个工具上分别投入了多少“计算量”。4.3 灵活的输-出格式适配自动化流程命令行工具的另一个强大之处是易于集成和自动化。a2zusage支持多种输出格式方便你将数据导入其他系统进行分析。JSON格式 (-f json)这是最结构化的输出包含了最完整的数据。每个工具的状态、用量详情细分到输入/输出token、数据源路径等信息都以标准JSON格式呈现。你可以用jq这样的工具进行二次处理或者写个脚本把数据存入数据库、生成图表。a2zusage -f json | jq .[] | select(.name claude-code) | .usage.totalCSV格式 (-f csv)如果你习惯用Excel、Numbers或Google Sheets做数据分析CSV格式是首选。它可以直接被电子表格软件导入进行排序、筛选和制作图表。# 将输出重定向到文件 a2zusage -f csv ai_usage_$(date %Y%m%d).csv表格格式 (-f table)默认格式适合人类阅读。4.4 其他实用命令a2zusage list列出所有a2zusage理论上支持的工具无论你的电脑上是否安装了它们。这可以帮助你了解工具的全貌也许会发现一些你没用过但值得尝试的AI编程工具。a2zusage --help查看完整的帮助信息包括所有参数和命令的详细说明。a2zusage -v详细模式。在输出表格的同时额外显示每个工具的数据是从哪个具体文件或API读取的。这在调试或验证数据准确性时非常有用。5. 支持的AI工具深度解析与数据准确性a2zusage声称支持14种工具但“支持”的深度各不相同。理解每种工具的数据来源和准确性能帮助你正确解读输出结果。5.1 高精度组数据可靠通常包含Token计数这组工具通常将详细的用量日志以结构化格式JSON、SQLite存储在本地a2zusage可以直接解析出精确的token数。Claude Code数据来自~/.claude/projects/目录下的JSONL文件。这是目前支持得最好的工具之一能准确区分输入token、输出token甚至在某些情况下包含缓存token。数据几乎实时更新可靠性极高。Cursor数据来自其内部的SQLite数据库文件。Cursor会记录每次交互的token消耗a2zusage通过查询特定表格来汇总这些数据。准确性取决于Cursor自身日志的完整性通常很好。Warp AI同样基于SQLite数据库。不过需要注意的是Warp AI的日志可能只记录总token数而不区分输入和输出。Gemini CLI (原生会话)如果你使用的是Google官方Gemini CLI工具它会将会话历史保存在~/.gemini/tmp/等目录下。a2zusage可以解析这些本地会话文件来统计token无需API调用。5.2 中精度组有数据但可能不完整这组工具能提供用量证据但可能缺少token级别的细节。GitHub Copilot这是最特殊的一个。a2zusage采用混合策略本地日志尝试从VS Code或JetBrains IDE的Copilot插件日志中读取请求次数。GitHub API如果你配置了GITHUB_TOKEN环境变量它会调用GitHub的API来获取Copilot订阅的用量概览。但请注意GitHub官方API不提供精确到每日的token级别数据通常只提供月度总使用情况如“接受/建议的代码行数”。因此Copilot行的“Token”列经常是-我们主要看请求次数或API返回的用量指标。Windsurf数据来自~/.codeium/目录下的会话文件。然而Windsurf对核心的token数据进行了加密a2zusage无法解密。因此它只能统计你开启了多少个会话而无法知道每个会话消耗了多少token。输出中会明确提示“Session count only”。Sourcegraph Cody / Tabnine等这些工具的VS Code扩展会将部分用量数据存储在本地存储中。a2zusage会尝试读取但能获取到什么字段是完整的token数还是只有请求计数完全取决于扩展本身存储了什么。输出状态会标明⚠️ Partial。5.3 链接或API组需要额外配置这组工具的数据不在本地必须通过互联网获取。OpenAI Codex (ChatGPT API等)如果你通过OpenAI的API进行编程例如使用一些封装了OpenAI API的CLI工具a2zusage可以通过配置OPENAI_API_KEY并指定你的组织ID来调用OpenAI的官方用量API。这能获取到非常精确的、按模型划分的token消耗数据。这是唯一需要网络权限且可能产生额外API请求的Provider调用OpenAI的用量查询端点。Amazon Q Developer需要配置AWS凭证。它会尝试读取AWS CLI的日志或调用AWS的特定API来获取用量信息实现程度取决于AWS公开的API粒度。Replit Ghostwriter目前仅提供一个网页链接引导你到Replit的网站后台查看用量a2zusage本身不直接获取数据。重要提示数据准确性首先取决于AI工具本身是否记录和暴露了这些数据。a2zusage是一个“读取者”而不是“创造者”。如果某个工具本身就不记录细粒度的token使用情况比如只记录“活跃天数”那么a2zusage也无法无中生有。doctor命令和-v详细模式是你验证数据来源的最佳工具。6. 高级应用场景超越个人用量查看a2zusage的设计初衷虽然是为了个人查看用量但其简单的命令行接口和结构化输出让它能轻松融入更高级的工作流。6.1 场景一团队成本监控与优化假设你是一个小团队的Tech Lead公司为成员购买了多个AI编程工具的团队订阅。你可以创建一个简单的共享脚本定期收集使用Cron job或CI/CD流水线如GitHub Actions定期在每个成员的机器上运行a2zusage -f json。数据聚合将所有人的JSON输出收集到一个中心位置需要妥善处理隐私例如匿名化后聚合。分析与洞察分析团队整体在哪些工具上花费最多不同职能前端、后端、算法的成员使用模式有何不同哪些工具的性价比最高这些数据可以为下一周期的工具采购预算提供有力依据。最佳实践分享发现团队里的“高效能用户”邀请他们分享是如何将特定AI工具深度融入工作流的从而提升整个团队的效率。6.2 场景二量化评估开发者对AI的适应度Vibe Coding这就是项目README中提到的核心招聘场景。所谓“Vibe Coding”我理解为一种开发者与AI助手之间流畅、自然、高频的协作状态。这种状态很难通过面试问答来检验但用量数据不会说谎。在征得候选人同意并确保隐私的前提下例如在技术面试环节使用公司提供的、已安装好工具的临时环境可以让候选人完成一个小的编程挑战。之后运行a2zusage查看其过程数据总用量与频率是否真的频繁使用了AI工具还是仅仅打开放着工具多样性是只依赖一个工具还是能根据任务特点灵活切换例如用Claude Code写业务逻辑注释用Cursor进行复杂重构这反映了学习能力和工具适应性。请求模式通过查看时间周期数据是持续性的小规模交互还是集中性的爆发式使用前者可能更符合“结对编程”式的深度集成。必须强调伦理这种方法必须透明、征得同意且数据仅用于评估“工具使用习惯”而非直接等同于“编码能力”。它应该作为传统技术面试的补充视角而不是唯一标准。6.3 场景三个人生产力回顾与习惯养成你可以将a2zusage的输出与你自己的时间日志或项目日志结合。例如对比“高强度编码日”和“会议日”的AI用量差异量化AI工具对你核心生产力的真实影响。观察当你学习使用一个新工具如从Copilot切换到Cursor时用量模式如何迁移从而评估学习曲线和最终收益。设定个人用量目标比如“将每周的无效提示产生极短或无意义代码的请求比例降低”。7. 常见问题与故障排查实录在实际使用和推广a2zusage的过程中我和其他用户遇到了一些典型问题。这里记录下来希望能帮你快速排雷。7.1 问题工具检测不到或状态为“N/A”可能原因1工具未安装或数据路径非标准。排查运行a2zusage doctor查看该工具预期的数据路径是什么然后手动去检查该路径是否存在。解决确认AI工具已正确安装并运行过。有些工具的数据目录可能在首次使用后才创建。可能原因2权限不足。排查在doctor输出中如果路径存在但状态是“不可读”可能是文件权限问题。在终端尝试ls -la 路径查看权限。解决调整文件或目录的读取权限。但需谨慎不要随意修改系统或应用核心文件的权限以免影响工具本身运行。可能原因3a2zusage版本过旧。排查某些AI工具更新后可能会更改数据存储格式或位置。旧版的a2zusage可能无法识别。解决升级到最新版本。使用npx a2zusagelatest或npm update -g a2zusage。7.2 问题数据看起来不准特别是Token数可能原因1工具本身不提供Token数据。现象例如Windsurf只显示会话数GitHub Copilot的Token列常为-。理解这不是a2zusage的bug而是数据源的局限。请回顾第5节了解不同工具的数据精度。可能原因2时间区间统计口径差异。现象你觉得“我今天明明用了很多怎么显示为0”。排查确认AI工具和a2zusage的时区设置。a2zusage默认使用系统本地时区来定义“今天”、“本周”的起止时间。如果AI工具的服务端记录使用的是UTC时间在特定时间点查看可能会有几个小时的偏差。解决查看“Total”总计列这通常是最准确的。周期统计主要用于趋势观察而非绝对精确的会计。可能原因3缓存或延迟。现象刚用完AI工具立刻运行a2zusage没看到数据。理解有些工具不是实时将每次请求都写入磁盘可能会有一个短暂的缓存或批量写入机制。解决等待几分钟再运行或者尝试退出并重启AI工具这会触发它写入日志。7.3 问题配置了API密钥但依然无法获取数据如GitHub Copilot可能原因1令牌权限不足。排查用于GitHub Copilot的GITHUB_TOKEN需要至少包含read:copilot权限。用于OpenAI的OPENAI_API_KEY需要属于一个有用量查询权限的组织。解决检查令牌的权限范围重新生成一个具备正确权限的令牌。可能原因2环境变量未生效。排查在终端中运行echo $GITHUB_TOKEN或echo $OPENAI_API_KEY看是否正确输出注意隐私不要在公共场合这样做。解决确保环境变量是在当前终端会话中设置的或者已经写入了正确的shell配置文件如.zshrc,.bashrc并重新加载了终端。7.4 性能与使用技巧运行速度第一次运行可能会稍慢因为它需要扫描所有可能的路径。后续运行会有缓存速度很快。如果觉得慢可以用-t指定特定工具只查询你关心的部分。输出太宽默认的表格视图在窄终端上可能会换行影响可读性。可以尝试将终端窗口拉宽或者使用-f json输出后通过jq过滤出你需要的字段。自动化集成结合cron或launchd(macOS) /systemd timer(Linux) 可以定期运行a2zusage -f json并将结果追加到一个日志文件中实现长期的用量追踪。记得处理好日志文件的轮转和清理。开发这个工具的初衷很朴素就是解决自己的一个痛点。但在开源后看到它被用于个人成本管理、团队效率分析甚至招聘评估这些我未曾设想的场景让我觉得这件事的价值超出了工具本身。它像一面镜子量化了人机协作的新模式。最后分享一个我自己的小习惯我现在每周一早上会跑一次a2zusage看看上周的“AI算力”都花在了哪些项目上这成了我回顾工作重点的一个有趣视角。工具是冷的但用它来理解和优化我们的工作流这个过程始终是热的。