1. 项目概述一个为AI开发者打造的“油表”工具如果你和我一样日常开发中重度依赖多个AI服务——比如用Codex写代码、Claude分析文档、Cursor辅助重构那么每个月收到账单时心里总会“咯噔”一下。各个平台的用量分散在不同的后台费用构成不透明想做个预算或者分析一下哪个模型性价比最高得打开五六个网页来回切换非常麻烦。更头疼的是有些用量比如本地IDE插件的调用甚至没有直观的查询入口。Fuelcheck CLI就是为了解决这个痛点而生的它就像给你的AI消费装了一个统一的“数字油表”让你能在一个终端窗口里实时监控所有AI服务的“燃料”即用量和费用消耗情况。这个用Rust写的命令行工具核心目标就一个聚合。它把来自不同AI提供商Provider的用量和成本数据通过统一的接口拉取下来并以简洁的文本或结构化的JSON格式输出。它的设计深受另一个优秀工具 CodexBar 的启发但走得更远。CodexBar主要专注于在macOS菜单栏展示OpenAI的用量而Fuelcheck CLI则立志成为一个跨平台、支持多提供商、且功能更强大的“瑞士军刀”。无论是想快速看一眼剩余额度还是想把数据接入自己的监控看板或是深度分析本地会话的成本它都能胜任。2. 核心功能与设计哲学拆解2.1 功能全景不止于查询初次接触Fuelcheck CLI你可能会觉得它就是个“查余额”的工具。但深入使用后你会发现它的功能分层非常清晰覆盖了从日常监控到深度分析的全场景。第一层基础用量与成本查询。这是工具的立身之本。fuelcheck-cli usage命令是最高频的操作它能一次性拉取你在配置中启用的所有AI服务的当前使用情况比如本月已用额度、剩余额度、总配额等。而fuelcheck-cli cost命令则更进一步当提供商支持本地日志分析时如Codex它能计算出基于本地调用记录的详细成本这对于审计和优化非常有价值。第二层结构化报告与自动化。工具提供了--report参数来生成周期性的报告目前主要针对Codex的本地会话数据。你可以生成daily每日、monthly月度或session会话级报告。更重要的是通过--format json或--json-only参数你可以获得纯净的JSON输出。这意味着你可以轻松地将数据管道化pipe到jq进行过滤或者写入文件供Grafana、Prometheus等监控系统消费实现AI成本的可观测性。第三层交互式实时监控。--watch参数开启了一个基于TUI终端用户界面的实时监视模式。在这个模式下用量信息会以可读的表格形式在终端里持续刷新就像top或htop命令一样。这对于在长时间运行任务如模型微调、批量处理时保持对消耗的感知非常有用。第四层配置与诊断。工具提供了完善的配置管理子命令config validate,config dump帮助你检查和调试复杂的多账户、多源设置。setup命令还能尝试自动探测本地的凭证极大地简化了初始化流程。这种功能分层体现了一个核心设计哲学提供从简到繁的平滑路径。新手可以通过setup和usage立刻获得价值高级用户则可以利用JSON输出和报告功能构建复杂的自动化流程而所有用户都能从直观的TUI中受益。2.2 架构设计清晰的责任边界Fuelcheck CLI采用了一个典型的多Crate Rust工作区Workspace架构这保证了代码的模块化和可维护性。理解这个架构有助于你未来可能进行的二次开发或问题排查。fuelcheck-core(core/目录)这是整个项目的“发动机”。所有与具体AI提供商打交道的逻辑都封装在这里。比如如何调用OpenAI的API查询用量如何解析Claude官网的Cookie来模拟网页查询如何读取Codex本地会话日志并计算成本。此外核心的领域模型如Provider配置、Usage用量数据、CostReport成本报告以及配置文件的序列化/反序列化逻辑也在这里。这个Crate力求保持“纯净”不包含任何命令行交互或UI渲染逻辑。fuelcheck-cli(cli/目录)这是项目的“驾驶舱”。它负责解析用户输入的命令行参数使用clap这类库根据命令调用core中相应的功能并处理程序的退出码和错误信息。它的核心职责是“编排”而不是具体执行。例如当用户执行usage --provider codex --provider claude时CLI层会解析这个请求然后分别调用core中对应Codex和Claude的模块来获取数据最后将结果交给UI层去渲染。fuelcheck-ui(ui/目录)这是项目的“仪表盘”。它包含了所有面向用户的输出渲染器。这包括将数据渲染为适合终端阅读的纯文本表格生成美观的JSON带--pretty时以及构建和运行那个实时的TUI监视界面通常使用ratatui或crossterm这类库。UI层决定了用户最终看到的是什么样子。注意这种架构分离带来了巨大的灵活性。理论上你可以基于fuelcheck-core开发一个图形桌面应用、一个Web后端服务或者一个Telegram机器人而无需改动任何底层的提供商集成逻辑。CLI只是其众多可能的前端之一。3. 从零开始安装、配置与初体验3.1 多种安装方式详解作为Rust项目Fuelcheck CLI提供了几种主流的安装方式你可以根据自身情况选择。1. 从Crates.io安装推荐大多数用户这是最快捷、最标准的方式前提是你的系统已经安装了Rust工具链rustc和cargo。cargo install fuelcheck-cli这条命令会从Rust的官方包仓库下载、编译并全局安装fuelcheck-cli。安装完成后直接在终端输入fuelcheck-cli即可使用。这是体验工具最快的方式。2. 从源码构建适合开发者或想使用最新特性如果你想贡献代码或者需要基于某个特定分支进行测试可以从GitHub克隆仓库并自行构建。# 克隆仓库 git clone https://github.com/chasebuild/fuelcheck-cli.git cd fuelcheck-cli # 编译发布版本 cargo build --release -p fuelcheck-cli编译完成后可执行文件位于target/release/fuelcheck-cli。你可以将其移动到系统PATH包含的目录如/usr/local/bin或者直接使用完整路径运行。3. 本地安装用于开发测试在项目根目录下你可以直接将CLI安装到Cargo的本地bin目录这通常用于开发过程中的频繁测试。cargo install --path cli这等同于从本地路径进行cargo install。4. 开发中直接运行如果你正在修改代码不想每次编译安装可以使用cargo runcargo run -p fuelcheck-cli -- --help--之后的部分会作为参数传递给编译后运行的fuelcheck-cli程序。这是最快速的开发迭代方式。3.2 核心配置实战一次搞懂多账户与多数据源配置文件是Fuelcheck CLI发挥威力的关键。默认情况下它会寻找~/.codexbar/config.json文件。你可以通过--config /path/to/config.json在任何命令中覆盖这个路径。一个最小化的配置看起来是这样的{ version: 1, providers: [ { id: codex, enabled: true, source: oauth }, { id: claude, enabled: true, source: oauth } ] }这表示启用Codex和Claude两个提供商并尝试使用OAuth方式获取数据。但对于高级用法我们需要深入每个字段。id提供商标识这是必须的且必须是指定列表中的值。目前支持包括codex,claude,cursor,gemini,kimi,opencode等在内的众多服务。你可以通过运行fuelcheck-cli usage --provider all来查看所有支持的ID及其连接状态。source数据获取源这是配置中最具技巧性的部分它决定了工具如何获取数据。理解每种源的适用场景和配置方法至关重要。auto: 默认值。工具会按照一个预定的优先级顺序通常是oauth-web-api-cli-local自动尝试直到找到一种可用的方式。oauth: 最方便但支持有限。工具会尝试使用你系统中已有的、该提供商官方CLI工具如OpenAI的openai Anthropic的claude的认证状态。这要求你先通过codex auth login或claude auth login等命令完成登录。web: 通过模拟浏览器访问用户后台页面来抓取数据。这通常需要你提供cookie_header字段即从浏览器开发者工具中复制出的Cookie:请求头。这种方式不依赖官方API但可能因网页改版而失效。api: 使用官方提供的API密钥进行查询。你需要在该提供商的网站上生成API Key并填入配置文件的api_key字段。这是最稳定、最推荐的方式但并非所有提供商都公开了用量查询API。cli/local: 主要用于成本计算。例如对于Codexlocal源会读取~/.codex/sessions目录下的本地日志文件来计算花费这完全离线不涉及网络请求。多账户管理 (token_accounts)对于像Claude、Codex这样支持多团队或多项目账户的服务token_accounts字段非常有用。它允许你在一个提供商配置下管理多个令牌Token并快速切换。{ providers: [ { id: claude, enabled: true, source: api, // 使用API源时token_accounts的token字段生效 token_accounts: { active_index: 0, // 默认使用第一个账户 accounts: [ { label: Work_ProjectA, token: sk-ant-oat-xxxxxxxxxxxxxxxxxxxxxxxx }, { label: Personal, token: sk-ant-oat-yyyyyyyyyyyyyyyyyyyyyyyy } ] } } ] }当你执行查询时工具会使用active_index指定的账户令牌。你可以在运行时通过环境变量或未来的CLI参数如果工具支持来动态切换这为自动化脚本按账户查询提供了可能。实操心得配置的黄金法则是“从简到繁”。我建议先用fuelcheck-cli setup命令它会尝试自动探测你系统里已有的凭证比如~/.codex/config.json或浏览器Cookie并生成一个初始配置文件。在这个基础上再手动添加那些它没能自动发现的、或者你需要特殊配置如多账户、API Key的提供商。这样可以避免一开始就面对一个复杂的JSON文件而感到困惑。3.3 快速上手你的第一个命令假设你已经通过cargo install安装了工具并且通过setup或手动编辑拥有了一个基本的配置文件。1. 一键查看所有已启用提供商的用量fuelcheck-cli usage输出会是一个清晰的表格列出每个提供商的本周期用量、限额、百分比和状态。这是你每天可能运行无数次的命令。2. 获取单个提供商的JSON格式数据fuelcheck-cli usage --provider codex --format json --pretty--pretty参数会让JSON格式化输出更易于阅读。去掉它则获得紧凑的JSON适合程序解析。3. 计算本地Codex会话成本如果你使用Codex IDE插件并且本地保存了会话日志这个命令能告诉你实际花了多少钱。fuelcheck-cli cost --provider codex4. 生成月度成本报告fuelcheck-cli cost --report monthly --provider codex --since 20241001 --until 20241031这会分析指定时间段内所有本地会话汇总出一个成本报告。5. 开启实时监控面板fuelcheck-cli usage --watch按下这个命令一个动态更新的监控面板就会出现在你的终端里。通常按q键可以退出。4. 高级用法与集成实践4.1 自动化与数据管道集成Fuelcheck CLI的真正威力在于其可脚本化Scriptable的特性。通过JSON输出你可以轻松地将AI用量数据集成到现有的运维监控体系中。场景一每日用量报告邮件你可以写一个简单的Shell脚本放在Cron任务里每天定时运行将用量数据格式化成HTML表格并发送邮件。#!/bin/bash # 获取所有提供商的JSON格式用量数据 DATA$(fuelcheck-cli usage --format json) # 使用jq解析并格式化示例提取名称和用量百分比 echo AI服务用量日报 report.txt echo report.txt echo $DATA | jq -r .providers[] | \(.id): \(.usage.used_percentage)% 已用 (\(.usage.used)/\(.usage.limit)) report.txt # 调用邮件发送命令这里以mailx为例 # mailx -s AI用量日报 $(date) your-emailexample.com report.txt场景二接入Prometheus/Grafana监控你可以创建一个小的导出器Exporter定期运行Fuelcheck CLI将数据转换为Prometheus的指标格式。#!/bin/bash # 模拟一个简单的Prometheus exporter端点 while true; do # 获取数据 METRICS# HELP ai_usage_percentage The usage percentage of AI providers.\n METRICS# TYPE ai_usage_percentage gauge\n fuelcheck-cli usage --format json | jq -r .providers[] | ai_usage_percentage{provider\\(.id)\} \(.usage.used_percentage) /tmp/metrics.prom # 将/tmp/metrics.prom暴露给Prometheus抓取 # 这里简化处理实际需用HTTP服务器提供/metrics端点 sleep 60 # 每分钟更新一次 done然后在Grafana中你就可以创建像监控服务器CPU一样的面板来可视化各个AI服务的消耗趋势和预算余量。场景三用量超限告警#!/bin/bash THRESHOLD80 # 设置告警阈值为80% fuelcheck-cli usage --format json | jq -r .providers[] | select(.usage.used_percentage $THRESHOLD) | 警告: \(.id) 用量已达 \(.usage.used_percentage)% | while read -r alert; do # 触发告警发送Slack消息、钉钉机器人、或执行某个降级操作 echo $(date): $alert /var/log/ai_usage_alert.log # curl -X POST -H Content-type: application/json --data {\text\:\$alert\} YOUR_SLACK_WEBHOOK_URL done4.2 报告功能的深度使用cost --report命令是针对Codex本地会话分析的利器。理解其参数能帮你更精准地分析数据。--report daily: 生成每日汇总报告。这对于追踪每天在AI辅助编程上的花费习惯非常有用。--report monthly --since YYYYMMDD --until YYYYMMDD: 生成自定义时间段的月度报告。since和until参数让你可以分析任意历史区间而不只是自然月。--report session --timezone Asia/Shanghai: 生成按会话拆分的详细报告并按指定时区显示时间。这对于分析哪些具体的编码任务会话消耗了最多成本至关重要可以帮助你识别低效的使用模式。JSON报告的结构差异这里有一个非常重要的细节当为单个提供商生成JSON报告时输出会保持与ccusage一个类似的工具兼容的顶层键名。fuelcheck-cli cost --report daily --provider codex --json输出可能类似{total_cost: 1.23, session_count: 45, ...}而当为多个提供商生成报告时输出结构会变为一个包装器里面以提供商ID为键。fuelcheck-cli cost --report daily --provider codex --provider claude --json输出会变成{codex: {...}, claude: {error: Local report not supported for this provider}}注意Claude返回了错误因为本地报告功能目前仅支持Codex。这种设计保证了输出的明确性让你知道每个提供商的处理结果。4.3 配置验证与调试技巧当你配置了多个复杂的提供商后可能会遇到查询失败的情况。此时内置的配置工具是你的好帮手。1. 验证配置语法fuelcheck-cli config validate这个命令会检查你的config.json文件格式是否正确必填字段是否缺失枚举值如source是否有效。它能在你执行命令前提前发现配置错误。2. 查看完整配置含解析后状态fuelcheck-cli config dump --prettydump命令不仅会打印出配置文件的内容还会显示工具内部解析后的最终配置状态包括哪些提供商被启用、使用的具体源是什么。这对于调试“为什么这个提供商没被查询”或“它到底用了哪个认证方式”非常有用。3. 使用--json-output进行高级调试如果你在开发或排查一个复杂问题可以启用JSONLJSON Lines日志输出到标准错误stderr。fuelcheck-cli usage --provider codex --json-output 2 debug.log这会将工具执行过程中的详细步骤、网络请求、响应等信息以结构化的JSON格式记录到debug.log文件中而正常的输出文本或JSON仍然在标准输出stdout上。这比看普通的文本日志要清晰得多。5. 常见问题排查与实战心得5.1 认证与连接失败问题这是新手最常遇到的问题“我配置了但为什么查不到数据” 请按照以下清单逐步排查问题现象可能原因排查步骤与解决方案Provider ‘codex‘: Not configured (disabled or no valid source)1. 配置中enabled为false。2. 配置的source所需凭证缺失或无效。3. 该提供商在配置文件中完全未定义。1. 运行fuelcheck-cli config dump确认该提供商是否被启用且配置正确。2. 检查对应source的凭证-oauth: 确保已通过官方CLI如codex auth login登录。-api: 检查api_key字段是否正确是否有查询权限。-web: 检查cookie_header是否过期Cookie通常有有效期。3. 将其添加到配置文件的providers数组中。Provider ‘claude‘: Failed to fetch usage (Network error)1. 网络连接问题。2. 提供商API端点临时不可用。3. 请求频率过高被限制。1. 使用curl或ping测试网络连通性。2. 稍后重试或查看该提供商的服务状态页面。3. 如果是web源可能是网站反爬策略生效考虑切换为api源如果可用。Provider ‘gemini‘: Unsupported source ‘oauth‘ for this provider为该提供商配置了它不支持的数据源。1. 查阅项目的PROVIDER.md文档确认该提供商支持哪些source。2. 将source改为auto或明确指定的支持源如api。多账户配置下查询到的数据不对token_accounts.active_index指向了错误的账户。1. 检查配置中active_index的值从0开始计数。2. 确认对应索引的accounts中的token是否有效且属于你想查询的账户。实操心得对于web源获取cookie_header是个技术活。以Chrome浏览器为例打开AI提供商的用量查询页面如https://platform.openai.com/usage按F12打开开发者工具切换到Network网络标签页刷新页面。在第一个请求通常是usage或类似名称的Headers标头选项卡下找到Cookie:这一行右键选择Copy value复制值粘贴到配置文件的cookie_header字段中。注意这个Cookie可能过几天就失效需要重新获取因此api源是更稳定的长期选择。5.2 性能与输出问题1. 命令执行缓慢如果查询所有提供商时速度很慢可能是因为其中某个提供商的源如web模拟响应很慢或者网络状况不佳。解决方案使用--provider参数指定你真正关心的少数几个提供商而不是all。或者考虑将source从web切换到更快的api或oauth。2. JSON输出格式不符合预期问题脚本解析--json输出时出错。排查确保你使用了--json-only参数。如果没有这个参数工具可能会在JSON数据前后输出一些状态信息或表格标题尤其是在非TTY环境下这会导致JSON解析器失败。--json-only保证了标准输出只有JSON干净无杂质。3. TUI监视模式 (--watch) 不显示或显示错乱原因你的终端可能不支持完整的TUI功能或者终端尺寸太小。解决尝试放大终端窗口。确保你是在一个支持ANSI转义序列的现代终端如 iTerm2, Windows Terminal, GNOME Terminal中运行。在极少数情况下可能需要设置环境变量TERMxterm-256color。5.3 为新的AI提供商做贡献如果你使用的AI服务不在支持列表中并且你有一定的Rust开发能力可以考虑为其贡献一个Provider实现。这通常涉及以下步骤在fuelcheck-core中创建新模块在core/src/providers/目录下新建一个Rust文件例如my_new_ai.rs。实现ProviderTrait该Trait定义了fetch_usage等方法。你需要研究目标服务的用量查询接口可能是网页抓取、官方API或CLI工具的输出解析。处理认证根据该服务支持的认证方式实现对应的逻辑。可能需要添加新的Source枚举变体。注册提供商在core/src/providers/mod.rs中引入你的模块并将其添加到提供商注册表中。更新文档修改PROVIDER.md添加新提供商的支持状态、认证方式说明和配置示例。测试与提交PR编写单元测试和集成测试确保功能正常然后向原仓库提交Pull Request。这个过程不仅能让你用上自己需要的功能也是深入理解Rust异步编程、HTTP客户端使用和API设计的绝佳实践。最后我想分享一点个人体会在AI工具消费日益增长的今天成本透明化和可观测性不是可选项而是必需品。Fuelcheck CLI这样的工具将原本琐碎、被动的成本查询变成了一个主动、可编程的监控环节。它节省的不仅仅是打开多个网页的时间更重要的是它提供的数据驱动视角能帮助你更理性地评估不同AI工具的投资回报率优化使用习惯最终让这些强大的“副驾驶”在可控的成本下真正为你的生产力赋能。