CodeBurn 版本演进与技术架构解析从本地 AI 用量追踪器到全平台观测工具【免费下载链接】codeburnFree, local tool to track AI coding token usage and cost across 37 tools and agents (Claude Code, Cursor, Codex, Gemini and more), by model, project, and task. npx codeburn项目地址: https://gitcode.com/gh_mirrors/co/codeburn本篇文章基于 CodeBurn 仓库根目录的 CHANGELOG.md涵盖 0.1.0 至 0.9.24 及 Unreleased 的全部变更记录系统梳理这款本地优先的 AI 编程 Token 用量与成本追踪工具的技术演进脉络它如何从 0.1.0 的一个 Ink 终端仪表盘成长为覆盖 CLI、TUI、Web 仪表盘、macOS 菜单栏应用、Windows 托盘应用、GNOME 扩展与 MCP 服务器七大表面的完整观测平台。阅读本文后你将掌握 CodeBurn 的提供商适配体系、分层定价机制、多级缓存与并发解析架构、实时配额quota读取模型、成果追踪yield方法论以及它在数据准确性、隐私与性能上反复打磨的工程细节并可直接在 README.md 中定位对应命令与用法。一、项目的技术定位与演进总览CodeBurn 是 AgentSeal 开源的本地工具MIT 许可核心定位在 README.md 中写得很清楚读取 AI 编码工具已经写在你磁盘上的会话文件按任务、模型、工具、项目四个维度拆解每一笔 Token 与美元开销。它不代理任何 API 请求、不上传数据定价数据来自 LiteLLM 快照并本地缓存。从 CHANGELOG.md 的时间线看其演进可以划分为四个阶段阶段版本区间标志性能力起步0.1.0 – 0.4.x2026-04Ink TUI 仪表盘、13 类任务分类器、Claude Code Codex 双提供商、CSV/JSON 导出生态扩张0.5.0 – 0.7.x2026-04Cursor/Goose/Gemini/Copilot 等提供商、optimize浪费扫描、compare模型对比、原生 macOS 菜单栏应用准确性强化0.8.x – 0.9.42026-04 至 2026-04-29每日缓存daily cache、逐提供商缓存分片、模型别名与价格覆盖、安全审计修复平台化0.9.5 – 0.9.242026-05 至 2026-09常驻serve进程、Windows 托盘与 Capacity Dock、quota 实时配额、跨设备 sync、工作单元work units、性能基线体系当前版本为0.9.24见 package.jsonREADME 宣称覆盖 41 款 AI 工具从 src/providers/index.ts 的注册表结构看核心提供商与懒加载提供商分别维护--provider参数校验与展示名映射都通过该注册表驱动。二、提供商适配体系一个提供商一个文件CHANGELOG 从 0.4.0 起确立了添加一个新提供商就是一个文件的插件式架构Provider plugin system. Adding a new provider (Pi, OpenCode, Amp) is a single file in src/providers/该约定延续至今README 也以 src/providers/codex.ts 作为范例。src/providers/index.ts 展示了这套体系的实现细节核心提供商数组coreProviders与懒加载提供商列表lazyProviderNames分离Antigravity、Forge、Goose、Cursor、OpenCode、Cursor Agent、Crush、Warp、Vercel AI Gateway、ZCode、Zed 等依赖可选原生模块如node:sqlite或平台能力的提供商延迟加载加载失败只影响自身不会拖垮整个扫描。发现失败隔离discoverOne单个提供商在discoverSessions()中抛出异常例如损坏的数据库、意外磁盘结构时只向 stderr 打印一行警告并跳过返回空源列表保证其他提供商的会话照常统计——这是 CHANGELOG 0.9.12per-file parse isolation思想的提供商级延伸。并发发现0.9.21 起提供商发现改为跨提供商并发执行元数据系统调用readdir/stat再按注册表顺序拼接结果保证与串行版本字节级一致实测在 21k 文件 / 9 提供商语料上warmcodeburn today从 5.30s 降到 2.99s。提供商适配的核心契约是读会话 → 出会话源SessionSource。每个提供商的解析器负责把各自工具的历史格式归一化例如 Cursor 的 SQLitestate.vscdb、Codex 的 JSONL rollout、OpenCode 的session/message/part表、Kimi Code 的wire.jsonl、DSH 的 zstd 分帧日志等统一输出标准 Token 与成本字段再进入下游聚合。三、定价体系LiteLLM 快照、兜底表与三层用户覆盖成本计算是 CodeBurn 的数据正确性根基CHANGELOG 中关于定价的条目贯穿始终可以归纳为三层定价 三类用户手段。3.1 三层定价来源主表随包发布的 LiteLLM 定价快照src/data/litellm-snapshot.json0.9.24 声称已含 5,942 条主条目、覆盖 0.9.24 bundle并在每次发版时刷新例如 0.9.24 从 4669 增至 4739 个模型。兜底表src/data/pricing-fallback.json0.9.24 从 203 增至 212 条覆盖 LiteLLM 尚未收录的模型。代码内建行Claude 全系与 GPT-5 系列等关键模型使用硬编码兜底避免模糊匹配误定价0.4.0、0.12 均有相关记录。Unreleased 条目还描述了一套bundled pricing 刷新守护规则运行时解析器getModelCosts按精确键查找只会剥离段peel segments与去掉变体后缀绝不自行添加厂商前缀防止~x-ai/grok-latest主条目错误地应答裸grok-latest查询完整性保护是严格的槽位填充slot-filling仅当上游行的输入/输出费率与已有条目完全一致时才允许补填 cache-write/cache-read 槽位刷新无权替换不同费率的行被上游删除或改名的主条目会原样带入兜底层保证升级不丢定价。3.2 三类用户手段均在 README.md 有完整命令手段命令作用别名codeburn model-alias from to把代理改写的模型名映射到规范定价名存于~/.config/codeburn/config.json价格覆盖codeburn price-override my-model --input 0.27 --output 1.10为私有部署或定价错误的模型指定精确费率USD/每百万 Token订阅 SKU 标记codeburn model-flat-rate auto-genius标记订阅计费的 SKU$0 是正确结果抑制未定价告警3.3 路由包装器的剥离规则0.9.21 起路由网关形态的模型 IDomniroute:、cp/、cline-pass/、cmd/、antigravity/、orcarouter/、cliproxy/按被包装的模型定价但只剥离受信任的命名空间LiteLLM 快照中的厂商前缀 上述路由包装器 客户端拼写kimi/、mimo/、zhipu/、litellm_proxy/、openai_like/未知厂商前缀保持未定价并如实报告ollama/、lmstudio/、hosted_vllm/、local/等本地运行器前缀被刻意排除防止未收录的本地 Tag 凭空发明云端开销。四、缓存与性能从单一大文件到按提供商、按月份分片缓存体系是 CodeBurn 能在大语料上保持流畅的关键CHANGELOG 记录了这条清晰的演进线0.9.21会话缓存从单一 blob 改为按提供商分片的版本后缀目录每个提供商一个 shard 一个小 envelope通过一次 envelope rename 发布warm 启动只重写发生变化的提供商。0.9.21续每个提供商的 shard 再按会话首个 turn 的 UTC 月份拆分追加一个会话只重写一个月--period today/week等短区间查询跳过不可能贡献 turn 的月份分片。0.9.21DAILY_CACHE_VERSION这类版本号体系贯穿始终每次账务规则变更如 Grok 4.6 双层定价、Copilot 逐请求 Token 读取都会 bump 版本强制一次性重新推导且重新推导带永不丢失守护新切片只有携带不少于旧基线的调用数calls时才允许替换已结算日期的基线防止会话文件部分过期导致历史金额被截断。0.9.20引入常驻codeburn serve --stdio进程桌面端、Web 仪表盘与 macOS 菜单栏共享一个保持热缓存的内存进程替代每次面板请求都冷启动 CLI 的模式配合文件系统 watcher无变化请求直接跳过扫描。0.9.24 / Unreleasedserve进程的每条响应都携带{generation:{n:4,at:...}}派生世代戳客户端可判断多个面板是否共享同一份语料读数。worker_threads 并行解析0.9.21 让大体积冷解析跨 worker 线程并行Claude 6GB 语料冷启动status从 27.5s 降到 14.8sCodex 整文件 rollout 解码同池并行父进程按串行顺序安装结果保证字节一致线程数受核心数、可用内存与待处理字节数的多重门槛控制CODEBURN_PARSE_WORKERS0/N可强制串行或指定线程数。增量解析追加式文件从缓存偏移量续读而非从头解析0.9.19Codex rollout 记录任务边界重启点增长后只解析尾部0.9.21。此外perf/BASELINES.md 与npm run perf:all0.9.24 Internal 条目建立了一套隔离 HOME 的固定性能基线体系用 28MB 合成 fixture 钉住冷解析、增量重解析、周期切换等关键路径的延迟基线。五、四类用户界面与两个常驻形态5.1 CLI / TUIInk 终端仪表盘从 0.1.0 的 Ink 交互仪表盘开始逐渐沉淀出完整命令族today、month、report、overview、status、export、models、optimize、compare、yield、context、audit、doctor、quota、plan、currency、guard、mcp、web、share/devices、sync等。0.9.21 起 TUI 冷启动采用先画当日、后台补索引的分层加载21k 文件语料上首屏时间从 36.3s 降到 9.9s并带indexing history · N/M files横幅。5.2 桌面应用Electron与 Windows 托盘Tauri0.9.19 起桌面端获得 Windows 支持、应用内更新通知与 Today 默认周期0.9.20 起每个面板改为与常驻serve进程对话。0.9.24 新增 WindowsCapacity Dock无边框、透明、置顶的屏幕边缘配额栏从codeburn quota --format json取数每 5 分钟刷新双击触发即时刷新托盘菜单可开关状态持久化于~/.config/codeburn/windows-dock.json。桌面端与托盘之间共享同一套status --format menubar-json负载契约通过 src/menubar-json.ts 等模块生成。5.3 macOS 菜单栏原生 Swift/SwiftUI0.7.2 起以codeburn menubar一条命令完成下载、校验、安装与启动0.9.23 引入原生Capacity Dock屏幕边缘配额小组件单提供商折叠态、悬停展开、按严重度变色、Graphite/Liquid Glass 外观、圆形/圆角方形仪表0.9.24 为其加入第二行菜单栏文本配额剩余、今日成本、今日 Token、运行中会话数、KVO 跨进程响应桌面端开关、本地化en/zh-Hans628 个键键即英文文案、额度重置通知与 80% 告警。相关实现位于 mac/ 目录。5.4 常驻serve与 MCPcodeburn servesrc/serve.ts是桌面端/菜单栏/Web 的数据后端0.9.24 起具备孤儿回收、进度心跳CODEBURN_PROGRESS1下每 10 秒输出 keepalive替换原先会误杀慢解析的 45 秒总时长上限与请求级备忘录按查询与语料指纹缓存。codeburn mcpsrc/mcp/server.ts提供 stdio MCP 服务器暴露get_usage与get_savings两个工具默认对项目名做假名化src/mcp/redact.tsinclude_project_names: true时可见真实名称。六、实时配额quota读取工具自有的本地凭据codeburn quota0.9.24 引入src/quota/index.ts实时读取每款编码工具已登录账号的配额窗口只读本地凭据不发新请求到厂商12 个适配器注册在READERS数组中Claude、Codex、Gemini、GitHub Copilot、Antigravity、Kimi、Cursor、Z.ai、ZCode、Grok、Grok Bot、ClinePassGrok Bot 是桌面应用而非登录账号仅在检测到其安装时才注册对应 reader。读取带 5 秒 AbortSignal 超时超时输出available: false与 Timed out.命令恒以 0 退出方便状态栏/托盘轮询。ZCode 与 Z.ai 读取同一 z.ai 端点二者都连通时隐藏 ZCode 行并附说明避免重复展示同一计划。每条窗口输出label、usedPct、resetsAt--format json输出完整结构。桌面端app/electron/quota/与 CLI 侧src/quota/存在历史双份实现注释说明后续将去重。0.9.24 的 Codex 限制重置积分banked/goodwill resets通知读取已有刷新响应中的积分清单并与上次读数对比首次出现即发通知无新端点、无新轮询。七、成果追踪yield与工作单元work units7.1 yieldgit 关联的投入产出分类codeburn yield0.9.1 引入src/yield.ts把 AI 会话与 git 提交按时间窗口关联将开销划分为 productive / reverted / abandoned / ambiguous 四类JSON 输出携带methodology: timestamp-window。Unreleased 条目描述了一项重要的方法论修正squash merge 救援。时间戳窗口法会把会话结束之后才合并的分支误判为 abandoned而 GitHub squash 合并在 main 上生成全新 SHA窗口永远看不到原提交。当会话日志记录了运行分支Claude Code 每轮记录多数提供商不记录时yield 会救援满足以下条件的会话分支自带提交、分支 tip 的树哈希与 main 上某个提交一致squash 后的树与分支 tip 字节级相同且 tip 不同于分支 base避免未改动或自回滚分支误匹配、且至少一个提交落在会话窗口内。救援仅发生在computeYield同步归因记录保持纯时间窗口方法论。7.2 work units提供商记录的会话谱系0.9.22 的codeburn sessions --by-work-unitsrc/work-units.ts基于 0.9.22 解析器捕获的lineage字段仅采用提供商记录的证据Claude agent 转录的 parent 引用、Kimi Code 子代理目录把子会话折叠到编排根之下。单位 ID 使用deriveTraceId(rootSessionId)——与 sync 使用的 trace id 推导完全一致证据严格限定无 lineage 的会话自成一个unknown角色单位循环/自引用/跨提供商 ID 冲突一律 fail closed。八、跨设备同步与团队遥测sync / sharesync0.9.23 起docs/sync/README.mdcodeburn sync push按 CB-3 规格发送加法式使用跨度字段ai.work_unit_id、ai.session_role、ai.lineage_evidence、ai.cache_read_tokens/ai.cache_write_tokens、ai.call_count、ai.session_duration_ms、ai.subscription_covered全部可选且仅在证据充分时发出sync auto提供同意一次的自动同步以 sha256 指纹钉住组织、目标、线协议版本、外发字段集与节奏指纹不匹配则零网络调用。隐私防线包括外发项目名只取目录叶名src/sync/归因跨度不再携带明文会话 IDai.project仅来自提供商记录的绝对 cwd。share / devices0.9.14 起src/sharing/本机局域网 PIN 配对聚合多设备用量。0.9.24 修复了共享/ MCP 脱敏负载携带 PR URL 与owner/repo#123标签的问题src/sharing/sanitize.tsPR 块被整体丢弃或经加盐哈希假名化。九、安全与隐私设计CHANGELOG 中的安全条目可分为三类输入防御0.7.1 外部安全审计1 HIGH/2 MEDIUM/1 LOW推动的改动包括 breakdown 映射改用Object.create(null)防原型污染src/parser.ts、文件读取上限 128MB / 8MB 以上走流式解析src/fs-utils.ts、菜单栏标签允许名单 14 字符截断防注入0.8.7 修复__proto__别名解析原型污染0.9.24 的 GitHub 主机字段在拼 URL 前做字符校验构造值如evil.com?.ghe.com直接失败关闭。凭据处理Copilot 令牌发现采用首个命中只读链Keychain 读取非交互且在锁定时跳过菜单栏的 Claude/Codex 凭据从 Application Support 迁入登录 Keychain迁移含O_NOFOLLOW、所有权校验、0600 修复、写回验证后删除Grok 适配器对$GROK_HOME/auth.json只读、令牌仅驻留内存、走无 cookie 的临时会话。遥测边界README.md Telemetry 节CLI 零外发桌面端可选匿名遥测usage_snapshot每日至多一次所有量级均为桶而非精确值EU/EEA/UK/CH 默认关闭永不收集提示词、代码、文件/项目/分支名、精确金额与时钟时间。十、跨版本数据一致性的代表性修复CHANGELOG 记录了多轮同一数字在多个界面不一致的系统性修复这些案例对使用者判断版本升级收益最有参考价值0.9.19 Every surface now shows the same numbersCLI、TUI、菜单栏、桌面端、Web 仪表盘全部收敛到同一条持久化聚合路径。0.9.24 Every period headline comes from one aggregation修复周期切换混用不同时刻快照导致 Lifetime 小于其所含的六个月的问题状态负载携带所有 headline 窗口的 cost/calls页面只读最新世代。0.9.24 usage streak is one number for the machine连击数改为从跨所有提供商的已水合每日缓存中取单一数值。0.9.24modelRowKey统一模型行键所有报告models、仪表盘、菜单栏topModels共用 src/models.ts 中的modelRowKey以短名 计费通道标签区分Haiku 4.5、Haiku 4.5 (Bedrock)与Haiku 4.5 (Bedrock us)此前models与菜单栏可能互相矛盾。0.9.24 Codex 推理 Token 双重计数修复OpenAI 把 reasoning 计入output_tokens此前 CodeBurn 再加一次导致成本虚高 3.5%、展示输出虚高 34.6%src/codex-throughput.ts 的billableOutputTokens成为唯一计费出口避免冷/热运行分叉。十一、升级指引与数据说明版本要求CLI 需要 Node.js 22.13package.json0.7.3 起放弃better-sqlite3改用内置node:sqlite安装包从 167 个依赖降到 40 个。升级路径多数账务/解析改动通过缓存版本号如DAILY_CACHE_VERSION31、CACHE_SCHEMA_VERSION3、STATUS_SNAPSHOT_VERSION4/9触发一次性重新推导重新推导基于热会话缓存、通常仅耗时数秒且带永不丢失守卫不会截断历史。环境变量完整的目录覆盖变量表见 README.md Environment Variables 节如CLAUDE_CONFIG_DIRS、CODEX_HOME、OPENCODE_DATA_DIR、KIMI_SHARE_DIR、CODEBURN_CACHE_DIR等CODEBURN_CACHE_SCOPEall可强制全量读取会话缓存以排查范围化读取导致的可疑数字。十二、继续深入仓库的入口命令全集与键盘快捷键README.md Commands 节各提供商的数据位置、格式与已知怪癖docs/providers/如 docs/providers/copilot.md优化扫描与健康评分docs/optimize.md同步协议与字段披露docs/sync/README.md、docs/sync/DEVELOPER.md性能基线与迭代记录perf/BASELINES.md、perf/ITERATION-LOG.md核心实现src/providers/index.ts、src/quota/index.ts、src/yield.ts、src/work-units.ts、src/models.ts总而言之CodeBurn 的 CHANGELOG 不只记录缺陷与功能更是一部关于如何让一个本地工具在大规模会话语料上保持准确、快速与可信的工程实录——多级缓存与版本号推导机制保证账务可重放、并发解析与常驻进程保证交互流畅、只读凭据读取与脱敏边界保证隐私不越线这些设计对任何构建本地优先 AI 观测工具的开发者都有直接借鉴价值。【免费下载链接】codeburnFree, local tool to track AI coding token usage and cost across 37 tools and agents (Claude Code, Cursor, Codex, Gemini and more), by model, project, and task. npx codeburn项目地址: https://gitcode.com/gh_mirrors/co/codeburn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
