1. 项目概述一个AI编程成本监控工具的诞生上个月我的信用卡账单给了我一个不大不小的“惊喜”。账单上显示我在AI编程工具上的花费远超我的预估。问题不在于我用得太多而在于我根本不知道自己用了多少。我的工作流是这样的一个终端开着Claude Code另一个跑着Gemini CLI同时Cursor还在处理一个副项目。三个独立的工具三个独立的计费页面却没有任何一个统一的视图能告诉我总共花了多少钱。于是我决定自己动手解决这个痛点。这个项目就是cc-statistics。它是一个开源工具核心目标是为使用多个AI编程助手如Claude Code, Gemini CLI, Codex CLI, Cursor的开发者提供一个统一的成本与使用情况监控视图。它通过读取这些工具在本地存储的会话数据进行聚合分析并以命令行界面CLI、网页仪表盘和原生macOS菜单栏应用三种方式呈现结果。如果你和我一样在日常开发中混合使用多种AI工具并且对“钱花哪儿了”感到困惑那么这个工具就是为你准备的。1.1 核心痛点分散的数据与缺失的全局视图当前AI编程工具生态的一个普遍现状是每个工具都是一个数据孤岛。它们为了提供流畅的体验和上下文记忆都会在本地存储详细的会话日志但格式和路径各不相同Claude Code: 将JSONL格式的会话文件存储在~/.claude/projects/目录下。Gemini CLI: 日志文件通常位于~/.gemini/tmp/下的项目文件夹中。Codex CLI: 会话数据保存在~/.codex/sessions/目录的JSONL文件里。Cursor: 其状态信息包括会话记录被整合进一个SQLite数据库路径通常是~/Library/Application Support/Cursor/User/globalStorage/state.vscdbmacOS。这种设计对单个工具而言是合理的但对于同时使用多个工具的用户来说就成了一场噩梦。你无法快速回答一些简单却关键的问题“我今天在所有AI工具上总共用了多少Token”、“哪个项目最‘烧钱’”、“我调用最频繁的工具函数是什么”。你不得不像会计一样在几个不同的界面或日志文件之间来回切换进行心算或手动汇总效率低下且极易出错。更令人沮丧的是市面上已有的监控工具大多只支持单一平台尤其是Claude Code。对于一个根据任务场景灵活选用不同工具的开发者来说这种“偏科”的解决方案显然不够用。真正的成本是所有这些工具开销的总和只盯着其中一部分无异于管中窥豹。1.2 解决方案概览cc-statistics的设计哲学基于上述痛点我构建cc-statistics时遵循了几个核心设计原则无侵入式数据采集绝不干扰或修改原有AI工具的工作流程。工具只读取它们已经生成在本地的会话文件完全被动。这意味着零风险不会影响Claude Code或Cursor等工具的稳定性和功能。多平台统一聚合核心价值在于“聚合”。工具需要能够识别并解析上述四个主流平台的本地数据格式将分散的Token计数、模型调用、成本估算整合到一个逻辑视图中。提供多维洞察除了最基础的Token和成本还要挖掘会话数据中的其他价值。例如分析工具调用模式以优化工作流统计AI生成的代码行数以衡量产出甚至区分AI“思考”时间和用户交互时间以评估协作效率。极简的部署与使用必须足够轻便一键安装无需复杂的依赖或配置。同时提供多种交互方式CLI、Web、原生App以适应不同场景下的使用习惯。最终诞生的cc-statistics就是一个纯Python编写的工具依赖标准库通过uv或pipx一行命令即可安装。它像是一个为你所有AI编程助手配备的“统一财务与数据分析后台”。2. 核心功能深度解析与使用场景cc-statistics的功能设计完全围绕实际开发中的监控与优化需求展开。下面我们来拆解它的几个核心模块看看它们如何解决具体问题。2.1 统一成本仪表盘你的AI花费“总控台”这是工具的基石功能。安装并运行后cc-statistics会自动扫描配置路径下的所有会话文件。CLI快速汇总 最直接的用法是通过命令行获取报告。例如想查看过去7天在所有平台上的总花费只需执行cc-stats --all --since 7d这条命令会输出一个清晰的摘要包含总输入/输出Token数、根据各平台官方定价估算的总成本、按模型如claude-3-5-sonnet, gemini-2.0-flash细分的开销以及活跃项目列表。原生macOS菜单栏应用核心体验 对于Mac用户这是提升最大的功能。运行cc-stats-app后一个常驻菜单栏的应用便启动了。状态栏上会显示一个Claude风格的图标旁边实时更新着当日的Token消耗和估算成本就像一个汽车油表。你可以通过右键点击来切换显示模式如只显示Token数、只显示成本、或显示会话数。当你的花费接近预设的每日限额时这个指示器会变成醒目的红色无需你主动去查看任何面板。按下全局快捷键CmdShiftC可以呼出一个完整的原生仪表盘窗口。这个用SwiftUI构建的界面提供了数据源切换器可以查看单个平台如只看Cursor的数据也可以查看所有平台聚合后的数据。主题切换支持深色、浅色或跟随系统设置。数据导出一键将当前视图的数据导出为JSON或CSV格式文件会自动保存到桌面并打开。进程管理显示所有正在运行的Claude相关进程的内存占用情况便于资源管理。这个设计将成本监控从一项“需要主动执行的任务”变成了一个“持续存在的环境信息”极大地降低了监控的心智负担。2.2 会话深度检索与无缝恢复告别“断片”我们在使用AI编程时经常会有这样的经历一个长达数小时的复杂会话解决了某个棘手问题然后你关闭了终端。几天后类似问题再次出现或者你需要回顾当时的解决方案却怎么也找不到那个具体的会话了只记得一些模糊的关键词。cc-statistics内置的全文搜索功能就是为了解决这个问题。它不仅仅索引会话的元数据如时间、项目名还会索引会话中的消息内容。你可以这样搜索cc-stats --search “数据库迁移 优化 索引”工具会返回所有包含这些关键词的会话并附上时间戳和一个可以直接执行的恢复命令例如找到 3 个相关会话 [2023-10-27 15:30] 项目backend-api - “重构用户数据库迁移脚本” 恢复命令claude --resume session_abc123xyz复制并执行claude --resume session_abc123xyz你就能立刻回到那个会话的上下文中包括之前的所有对话历史和代码变更。这个功能跨越所有历史会话和所有支持的平台相当于为你所有的AI编程对话建立了一个本地搜索引擎。2.3 超越成本工具调用与代码产出分析只关注Token成本可能会错过优化AI使用效率的更佳视角。cc-statistics提供了几项更深层的分析。工具调用分析针对Claude Code Claude Code的强大之处在于其“技能”Skills和“模型上下文协议”MCP工具可以让AI读写文件、执行命令、查询网络等。cc-statistics会统计每个会话中各种工具被调用的次数并生成一个“Top 10工具调用榜”。这个榜单的价值在于性能调试与工作流优化。例如如果你发现mcp__filesystem__read_file文件系统读取在某个会话中被调用了上百次这可能意味着你的智能体Agent正在低效地反复读取同一个文件提示你可能需要调整提示词让AI一次性读取更多内容或更好地缓存信息。又或者如果你自定义的某个MCP工具被频繁调用这个数据可以帮你评估该工具的实际价值和使用频率。代码变更统计 Token花了但到底产出了多少代码cc-statistics通过在你项目目录中执行git log --numstat命令并将提交与AI会话时间关联起来估算出每个会话所导致的代码行数变更增加/删除并按编程语言进行归类。你会得到这样的洞察“本周在AI辅助的会话中新增了约3400行TypeScript代码和800行Python代码。” 这有助于区分“讨论型会话”高Token低代码产出和“执行型会话”高Token高代码产出让你更清楚地了解AI在哪些方面真正提升了你的编码效率。AI时间 vs. 用户时间 工具会计算一个会话中Claude处于“思考”生成响应状态的总时间与你处于“输入”AI等待你状态的总时间。这个比例很有趣。一个“AI时间”占比很高的短会话可能意味着你发出了一个复杂的提示然后等待结果而一个比例均衡的长会话则可能代表一场深入的、交互式的“结对编程”。观察这个指标可以帮助你反思自己的使用模式。如果你发现自己总是在进行简短的、高AI时间占比的交互也许可以考虑将多个小问题合并成一个更详细、更结构化的提示词一次性提交这样可能更高效、更节省Token。3. 安装、配置与核心工作流程3.1 跨平台安装指南cc-statistics力求安装过程简单至极提供了多种包管理器的支持。推荐使用uv(最快)uv是一个新兴的、速度极快的Python包管理器和安装器。如果你的系统没有安装可以按照其官方文档快速安装。之后安装cc-statistics只需一行命令uv tool install cc-statistics这条命令会处理好一切包括创建必要的可执行文件链接。使用pipxpipx是另一个优秀的工具用于在独立环境中安装和运行Python应用避免污染全局环境。如果你已经安装了pipx可以这样安装pipx install cc-statisticsmacOS用户使用 Homebrew对于习惯使用Homebrew的Mac用户可以通过添加第三方Tap来安装brew install androidZzT/tap/cc-statistics所有安装方式都是“零依赖”的因为工具核心仅使用Python标准库。macOS的菜单栏应用则直接提供了预编译的二进制文件无需安装Xcode或进行本地编译。3.2 首次使用与数据扫描安装完成后无需任何配置即可开始使用。工具会自动在默认路径下寻找支持的AI编程工具的会话数据。第一步生成你的第一份聚合报告打开终端运行cc-stats --all --since 7d这个命令会执行一次全盘扫描查找Claude Code、Gemini CLI、Codex CLI和Cursor的数据然后汇总显示过去7天的所有活动。输出结果会清晰地列出每个平台检测到的会话数、总Token消耗、估算成本以及主要使用的模型。注意首次运行时如果某个工具的会话文件非常多例如积累了数月的Claude Code历史记录扫描可能需要几秒钟到一分钟的时间。后续运行会利用缓存速度会快很多。第二步macOS用户启动常驻菜单栏应用如果你使用的是macOS并且希望获得实时的成本提醒可以在终端运行cc-stats-app应用启动后你会立刻在屏幕右上角的菜单栏看到它。建议首次启动后在应用内打开设置面板勾选“Login at Launch”登录时启动。这样每次开机后它都会自动在后台运行为你提供持续的监控。3.3 日常使用工作流示例一个典型的开发者日常可能是这样使用cc-statistics的早晨开工时瞥一眼菜单栏看到Token计数从零开始。心里对今天的AI使用有个基线。深度编程会话中当进行一个涉及大量AI交互的重构任务时偶尔看到菜单栏的数字在跳动对当前会话的“消耗速度”有个直观感受。遇到问题需要回溯时突然想起上周用AI解决过一个类似的API认证问题但忘了细节。打开终端运行cc-stats --search “OAuth2 认证 过期”快速找到并恢复那个会话。每日下班前运行cc-stats --today快速回顾今天在所有AI工具上的总开销看看是否在预算内。每周复盘时运行cc-stats --report week生成一份详细的Markdown周报查看各项目的Token分布、最常用的工具、代码产出情况用于个人复盘或向团队汇报AI工具的投资回报率ROI。4. 高级功能与集成方案4.1 自动化报告与团队通知对于个人或团队定期复盘至关重要。cc-statistics支持生成结构化的报告。生成周期报告# 生成本周报告 cc-stats --report week # 生成本月报告 cc-stats --report month命令会生成一个格式清晰的Markdown文件内容包含周期内总Token和成本、按模型和项目划分的明细、工具调用排行榜、代码变更统计等。这份报告可以直接归档作为个人效率回顾或成本核算的依据。集成团队协作工具Webhook推送 如果你在团队中推广AI编程工具可能需要让相关成员了解整体使用情况。cc-statistics支持通过Webhook推送报告摘要到常见的协作平台。cc-stats --report week --notify https://hooks.slack.com/services/YOUR/WEBHOOK/URL你可以将上述命令放入服务器的cron作业或本地的自动化脚本如使用launchd或crontab设定为每周一上午自动执行将上周的AI使用周报推送到指定的Slack、飞书或钉钉频道。这为团队提供了透明的成本与使用情况可见性有助于合理规划预算和评估工具效益。4.2 用量预警与预算管理预防总是优于补救。cc-statistics提供了主动预警机制。在macOS菜单栏应用的设置面板中你可以设置每日和每周的Token或成本预算上限。当你的实际使用量接近例如达到80%或超过这个阈值时工具会通过macOS原生的通知中心发送系统提醒。这个提醒是“非侵入式”的——它会像其他应用通知一样出现在屏幕右上角并尊重你的系统“专注模式”设置。结合菜单栏图标变红的视觉提示双保险确保你不会在不知不觉中超额使用。4.3 网页仪表盘跨平台的全功能视图虽然菜单栏应用非常方便但有时你需要一个更大的屏幕来仔细分析数据或者你正在使用Windows/Linux系统。这时网页仪表盘就派上用场了。cc-stats-web执行这个命令会在你的默认浏览器中打开一个本地服务器提供的、采用深色主题的仪表盘。它的功能与原生应用基本一致提供了会话列表、按时间趋势图、模型开销饼图、工具调用详情等所有核心数据的可视化展示非常适合进行深度数据分析。5. 常见问题排查与实战技巧在实际使用和与社区用户的交流中我总结了一些常见问题和处理技巧。5.1 数据读取与兼容性问题问题工具运行后显示“未检测到会话数据”或数据明显不全。检查点1路径权限。确保你的用户账户有权限读取~/.claude,~/.gemini等目录。在极少数情况下如果这些工具是以其他用户身份如sudo安装运行的其生成的数据文件可能权限不足。检查点2自定义安装路径。Claude Code等工具理论上使用标准路径但如果你通过非常规方式安装或修改了配置数据可能不在默认位置。目前cc-statistics遵循官方默认路径。如果遇到此情况可以考虑在GitHub仓库提交Issue提供你的环境信息。检查点3工具版本。AI编程工具更新频繁其本地数据存储格式有可能发生变化。cc-statistics会持续更新以适配主流版本。如果你使用的是Beta或非常旧的版本可能会遇到解析错误。建议查看项目GitHub页面的兼容性说明。问题Cursor的数据统计似乎不准确比如会话数对不上。原因解析Cursor将所有数据包括编辑器状态、扩展配置、会话记录都打包存储在一个SQLite数据库文件state.vscdb中。cc-statistics需要从中解析出与AI交互相关的会话结构。Cursor自身的版本更新可能导致内部表结构或字段含义的细微变化。应对技巧首先确保你安装的是cc-statistics的最新版本。其次理解Cursor提供的数据维度可能与其他工具不同。它可能更侧重于“交互事件”而非严格的“会话”因此统计口径上可能存在差异。关注相对趋势如本周 vs 上周比绝对数值有时更有意义。5.2 性能优化与使用技巧技巧1管理扫描范围与缓存如果你的历史会话数据量特别庞大例如超过一万个会话文件首次全量扫描可能会比较慢。cc-statistics使用了缓存机制来提升后续查询速度。缓存文件通常位于~/.cache/cc-statistics目录下。如果你确信数据源发生了变化而工具显示旧数据可以尝试通过cc-stats --clear-cache命令如果支持或手动删除该缓存目录来强制刷新。技巧2精准查询以提升效率避免总是使用--all和很宽的时间范围。结合项目过滤和更短的时间窗口可以极大提升查询速度尤其是在CLI操作时。# 更高效的查询只查某个项目最近3天的数据 cc-stats my-project-name --since 3d # 只查看今天Claude Code的数据 cc-stats --platform claude --today技巧3理解成本估算的局限性重要提示cc-statistics显示的成本是估算值。它根据各AI平台官方公开的API定价输入Token每百万美元X元输出Token每百万美元Y元和会话中记录的Token数量计算得出。这通常非常接近实际账单但可能存在细微差异因为实际账单可能包含税费。平台可能对长期用户有阶梯定价或优惠。某些工具特别是Cursor的某些模式的计费方式可能更复杂不完全等同于标准API调用。 因此请始终以官方账单为最终准绳。cc-statistics的核心价值在于提供实时、可比的趋势分析和跨平台汇总帮助你建立成本感知而非替代会计系统。5.3 自定义与扩展可能性cc-statistics是一个开源项目这为有特定需求的用户提供了扩展空间。场景你需要监控一个自定义的、本地部署的AI编码工具。该工具也会在本地~/.my-ai-tool/sessions/目录下生成JSON格式的日志。你可以通过以下步骤尝试集成Fork项目仓库在GitHub上fork cc-statistics的项目。阅读数据解析模块核心的解析逻辑位于src/cc_statistics/parsers/目录下每个平台如claude.py,cursor.py都有一个对应的解析器。它们的主要工作是读取特定格式的本地文件并将其转化为内部统一的“会话”数据模型。仿写解析器参考现有解析器的结构编写一个新的解析器例如my_ai_tool.py实现从你的日志文件到内部数据模型的转换逻辑。注册解析器在平台注册列表中添加你的新解析器使其能被主程序扫描到。测试与提交完成开发后可以在本地测试。如果功能稳定且具有通用性非常欢迎向原项目提交Pull Request惠及更多有同样需求的用户。这种开放性使得cc-statistics不仅能解决当前主流工具的问题也具备了适应未来新兴AI编程工具生态的潜力。