1. 项目概述Budi你的AI编码助手成本管家如果你和我一样日常开发已经离不开Claude Code、Cursor这类AI编码助手那你肯定也经历过那种“账单焦虑”——月底收到账单时看着那个数字心里直犯嘀咕“我到底在哪儿花了这么多钱” 更头疼的是你很难说清楚上个月那个重构了三天的大项目具体消耗了多少token或者团队里谁在哪个分支上“烧”得最猛。这种模糊的成本感知在团队协作和项目复盘时尤其让人抓狂。Budi就是为了解决这个问题而生的。它是一个用Rust编写的本地优先Local-first的AI编码助手成本分析工具。简单来说它就像一个安静的观察者默默运行在你的电脑后台自动追踪和分析你所有AI编码助手目前支持Claude Code、Codex CLI、Cursor、Copilot CLI的使用情况告诉你钱和token都花哪儿了。它的核心思路非常巧妙不干扰、不代理只观察。Budi不会去拦截或修改你的AI助手流量它只是去“偷看”这些工具在本地磁盘上已经生成的会话日志文件比如Claude Code的JSONL文件。通过解析这些日志它就能计算出每次交互的token消耗和成本并按照仓库、分支、工单Ticket、活动类型等维度进行归因分析。所有原始数据你的提示词、代码、AI回复都默认留在你的本地机器上只有聚合后的成本数据可以选择性地同步到一个云端仪表盘供团队查看。我第一次用上Budi是在一个为期两周的密集开发冲刺之后。当时我们团队三个人都在用Cursor月底对账时完全是一笔糊涂账。安装了Budi运行了budi db import导入历史数据后仪表盘上清晰的图表立刻让我们恍然大悟原来超过40%的成本都花在了一个长期存在的、上下文不断膨胀的旧会话里。自那以后Budi就成了我开发环境里的标配。2. 核心设计理念与架构解析2.1 为什么是“本地优先”在隐私和安全至上的今天Budi选择“本地优先”架构是经过深思熟虑的。AI编码助手处理的往往是公司核心代码库和业务逻辑任何原始数据的泄露都可能带来灾难性后果。因此Budi的设计遵循一个铁律原始数据不出门。具体来说Budi在本地~/.local/share/budi/或%LOCALAPPDATA%\budi维护一个SQLite数据库。它从本地日志文件中提取的主要是元数据时间戳、模型名称、token数量、计算出的成本以及归因标签如repo:github.com/org/projectticket_id:PROJ-123。你的具体提示词、生成的代码块、AI的完整回复这些敏感内容永远不会被上传。即使你启用了可选的云端同步功能发送出去的也只是按天聚合的数值型摘要比如“项目A在7月15日花费了$2.34”。这种设计带来了几个好处绝对隐私开发者可以放心使用无需担心代码泄露。离线可用所有核心分析功能在断网环境下依然完整。低延迟数据在本地处理状态栏的成本显示和budi stats查询都是瞬间响应。2.2 无侵入式的数据采集策略与一些需要通过代理服务器拦截流量的方案不同Budi采用了更优雅、更稳定的“文件尾随File Tailing”机制。这基于一个事实像Claude Code、Cursor这样的现代AI助手为了自身调试和用户体验都会在本地写入结构化的会话日志。Budi的守护进程budi-daemon会持续监控这些日志文件的默认存储路径。一旦检测到文件有新的追加写入它就实时解析新增的内容提取成本数据并存入数据库。这种方式有三大优势零配置你不需要修改任何AI助手的配置不需要设置代理也不需要注入任何环境变量。安装Budi运行budi init然后像往常一样使用你的AI助手即可。高稳定性不依赖网络代理避免了代理崩溃导致AI助手无法使用的风险。只要AI助手本身能正常工作并写日志Budi就能采集到数据。跨版本兼容性只要AI助手输出的日志格式没有颠覆性变化Budi通常只需要小幅调整解析逻辑即可适配用户端无需任何操作。2.3 模块化架构与数据流Budi的架构清晰地将核心功能解耦确保了系统的可维护性和可扩展性。整个数据流可以概括为“采集 - 处理 - 存储 - 展示”。用户使用AI助手 (Claude Code, Cursor...) | v (本地写入日志文件) [budi-daemon 文件尾随监控] | v (提取、规范化、丰富数据) [数据处理管道] | v [SQLite 数据库] --- [CLI/状态栏/扩展] 查询 | v (可选) [云端同步服务] --- [团队仪表盘]核心组件详解budi-daemon(守护进程)这是Budi的大脑一个常驻后台的Rust程序监听在本地7878端口。它负责三件大事文件尾随监控各AI助手的日志目录实时处理新增数据。数据管道执行核心的数据处理逻辑包括成本计算、标签归因、会话健康度分析。HTTP服务为CLI命令、状态栏、VS Code扩展提供查询接口。所有对数据库的读写都必须通过daemonCLI只是一个轻量级的HTTP客户端这保证了数据的一致性和安全性。SQLite数据库采用经典的“事实表维度标签”设计。messages表是核心事实表每条AI助手的API调用对应一行存储token、成本等核心指标。sessions表记录会话的起止时间和元数据。tags表以键值对形式存储所有归因信息仓库、分支、工单等与messages表关联。这种设计非常灵活可以轻松添加新的归因维度。此外还有message_rollups_hourly和message_rollups_daily等聚合表用于加速仪表盘和统计查询。CLI工具提供丰富的命令行接口用于查询数据、管理服务、诊断问题。例如budi stats、budi sessions等。集成组件Claude Code状态栏在Claude Code界面底部显示实时成本。Cursor扩展在Cursor/VS Code的状态栏显示Cursor专用的成本。云端仪表盘一个可选的Web界面用于团队级别的成本可视化和协作。3. 从零开始安装、配置与初体验3.1 选择适合你的安装方式Budi提供了多种安装途径总有一款适合你的工作流。我的建议是如果你在用macOS或Linux优先使用Homebrew如果是Windows用PowerShell脚本。这样能获得最好的自动更新和管理体验。macOS / Linux (Homebrew)这是最推荐的方式管理起来最省心。brew install siropkin/budi/budi budi init安装完成后务必手动运行一次budi init。这个命令会初始化本地数据库、启动守护进程、配置开机自启并安装默认的集成Claude Code状态栏和Cursor扩展。macOS / Linux (Shell脚本)如果你没有Homebrew或者想快速体验可以使用一键安装脚本。curl -fsSL https://raw.githubusercontent.com/siropkin/budi/main/scripts/install-standalone.sh | bash这个脚本会自动下载预编译的二进制文件安装到~/.local/bin/并自动执行budi init。Windows (PowerShell)Windows用户可以通过PowerShell一键安装。irm https://raw.githubusercontent.com/siropkin/budi/main/scripts/install-standalone.ps1 | iex脚本会将Budi安装到%LOCALAPPDATA%\budi\bin并自动将其加入用户PATH环境变量。安装后需要重启终端才能使PATH生效。重要提示避免二进制冲突不要混用多种安装方式例如不要既用Homebrew装了一遍又手动把二进制文件拷到~/.local/bin。这会导致你的系统里存在多个不同版本的budi和budi-daemon引发不可预知的行为。如果你遇到命令行为异常可以用command -v budiLinux/macOS或Get-Command budi -AllWindows PowerShell检查当前生效的是哪个二进制文件并清理掉多余的安装。3.2 五分钟快速验证清单安装完成后按照以下步骤可以最快地验证一切是否正常工作发送第一个提示像平常一样打开Claude Code或Cursor问AI一个简单的问题比如“写一个Python的hello world函数”。这个操作会触发AI助手在本地生成日志文件Budi的守护进程才能检测到并开始采集数据。运行全面诊断打开终端运行budi doctor。这是Budi的“健康检查”命令它会检查守护进程是否在运行。文件尾随器是否就绪并能找到日志文件。数据库模式是否正常。是否有遗留的旧版本8.0/8.1代理配置需要清理。 如果一切正常你会看到“All checks passed.”的输出。如果还没有数据它可能会友好地提示“No activity recorded yet.”这是正常的因为你刚刚开始使用。查看今日成本运行budi status。这个命令会给你一个快速的概览显示守护进程状态和今日至今的花费。初次使用数字可能是0或很小。可选导入历史数据如果你已经使用AI助手有一段时间了并且本地有历史日志文件可以运行budi db import。这个命令会扫描默认路径导入Claude Code的JSONL文件、Codex/Copilot的会话文件等让你看到过去的使用情况。导入进度会按AI助手类型分别显示。3.3 理解核心配置文件Budi的配置采用TOML格式集中在~/.config/budi/目录下Windows在%APPDATA%\budi\。安装后这里会有几个关键文件agents.toml: 记录已检测到并启用的AI助手及其日志路径。通常不需要手动修改。integrations.toml: 记录已安装的集成如状态栏、扩展。可以通过budi integrations命令管理。cloud.toml:云端同步的配置文件默认不存在。只有当你决定启用云端仪表盘时才需要通过budi cloud init命令创建它。关于budi init的深入理解 这个初始化命令做的事情比看起来多创建目录结构在~/.local/share/budi/下创建SQLite数据库文件。启动守护进程启动budi-daemon并使其监听7878端口。安装自启服务根据你的操作系统launchd, systemd, Windows服务配置开机自启。安装默认集成自动为Claude Code安装成本状态栏为Cursor安装VS Code扩展除非你用--no-integrations跳过。扫描并报告快速扫描系统告诉你它发现了哪些AI助手的痕迹。 它不会修改你的shell配置文件如.bashrc,.zshrc也不会修改Cursor或Codex的任何设置。这种“最小侵入”原则是Budi设计的哲学。4. 核心功能实战成本归因、健康度与会话分析4.1 成本归因让每一分钱都有出处Budi最强大的能力之一就是将模糊的AI花费精确地关联到具体的工作上下文上。这主要依靠一套灵活的标签Tag系统来实现。每一条AI助手的消息对应messages表的一行都会被打上一系列标签。内置的归因维度包括repo_id: 代码仓库的唯一标识如github.com/org/repo。git_branch: 当前工作的Git分支。ticket_id: 工单ID如PROJ-123。Budi会尝试从分支名中提取此类信息。activity: 活动类型如bugfix修复bug、refactor重构、feature新功能开发等。这是通过启发式规则从对话内容中推断的。file_path: 当前编辑的文件路径仅限仓库内的相对路径绝对路径和外部路径会被安全地过滤掉。你可以通过budi stats命令从各个维度来透视你的花费# 查看所有项目的花费排名 budi stats --projects # 输出示例 # | repo | cost | messages | # |-------------------------------|-------|----------| # | github.com/mycompany/api | $42.1 | 127 | # | github.com/mycompany/web | $18.5 | 89 | # | (no repository) | $5.2 | 23 | # 查看特定分支的花费 budi stats --branch feat/new-authentication # 查看与特定工单相关的所有花费 budi stats --ticket PROJ-456 # 查看不同活动类型的花费 budi stats --activities自定义标签规则 如果内置的归因不够用你可以在~/.config/budi/tags.toml中定义自己的规则。例如你想给特定仓库的所有花费打上团队标签[[rules]] key team value platform match_repo github.com/org/platform-repo [[rules]] key team value backend match_repo *backend*这样所有在platform-repo仓库中的AI使用都会被标记为teamplatform所有仓库名包含“backend”的则标记为teambackend。这些自定义标签也会出现在budi stats --tag team的统计结果中。4.2 会话健康度识别低效的AI交互AI编码助手用久了很容易陷入一些低效的模式导致成本激增而产出有限。Budi的“会话健康度Session Health”功能就像一个随时在线的教练帮你识别这些问题。它会从四个维度监控你当前的AI会话上下文膨胀Context GrowthAI模型有上下文窗口限制。随着对话轮数增加整个对话历史包括你的提示和AI的回复都会被送入模型导致每次调用的成本越来越高。Budi会检测上下文大小的增长速率。如果增长超过3倍且有实质性的绝对增长它会给出黄色警告超过6倍且上下文已经很大时会给出红色警报建议你使用/clear或/compact如果AI助手支持来开启一个新会话。缓存复用率低Low Cache Reuse一些AI模型如Claude具有缓存机制如果连续的问题相似后续回答可以更快、更便宜。Budi会计算在当前模型下最近几次调用的缓存命中率。低于60%会触发黄色警告低于35%则是红色警报。这可能意味着你的问题过于跳跃或者应该考虑把相关任务集中在一个会话中完成。成本加速Cost Acceleration这指的是在同一个会话中越往后的每次回复成本比前期显著增高。Budi会计算成本增长趋势。2倍以上的增长且单次成本可观时触发黄色警告4倍以上且成本很高时触发红色警报。这是上下文膨胀和问题复杂化共同作用的结果是提醒你“重启会话”的最强信号。重试循环Retry Loops当AI助手反复尝试执行一个失败的工具调用如运行一个错误的命令时就会陷入重试循环白白消耗token。Budi会检测这种模式该功能目前基于工具结果信号重建中。如何查看健康度在Claude Code中如果你在~/.config/budi/statusline.toml中设置了preset coach或preset full状态栏就会显示当前会话的健康状态如“session healthy”或“context growing”。在终端中使用budi vitals查看最近会话的健康详情或budi vitals --session session_id查看特定会话。在云端仪表盘中每个会话的详情页都有健康度可视化。我的实战经验我曾经有一个持续了2天的重构会话Budi一直显示“context growing (yellow)”。我没在意直到它变成红色并且budi vitals显示成本加速达到了5倍。我果断开启了新会话并将旧会话的核心上下文摘要后粘贴进去。结果完成剩余任务的花费只有原来的三分之一。这个功能帮我养成了“定期清理会话”的好习惯。4.3 深入会话分析除了健康度Budi还提供了强大的会话分析工具。budi sessions命令可以列出所有会话。# 列出最近的会话包含ID、时间、成本、健康状态 budi sessions # 查看某个特定会话的详细信息包括每条消息的成本、使用的模型、所有标签 budi sessions session_id # 过滤出与某个工单相关的所有会话 budi sessions --ticket PROJ-789 # 过滤出某种活动类型的会话 budi sessions --activity refactor在会话详情视图里你可以清晰地看到会话的起止时间和总时长。总成本和总token数。每条消息的详细记录角色用户/助手、token数、成本、使用的模型。该会话所有的归因标签。会话的健康度评估和建议。这对于复盘特别有用。你可以找出那些成本异常高的会话回顾当时的对话分析是任务本身复杂还是使用方式可以优化。5. 状态栏、扩展与云端仪表盘5.1 Claude Code状态栏实时成本感知安装并初始化后Budi默认会在Claude Code的界面底部添加一个状态栏。它看起来是这样的budi · $1.24 1d · $8.50 7d · $32.10 30d这里有一个非常重要的概念需要理解滚动窗口 vs. 日历窗口。状态栏显示的是“滚动窗口Rolling Window”1d代表过去24小时从此刻往前推7d代表过去7天30d代表过去30天。这个数字是持续滚动的不会在午夜清零。它的目的是回答“我最近的花费速度如何”。budi stats命令和云端仪表盘默认使用“日历窗口Calendar Window”--period today指的是从今天零点到现在--period week指的是过去7个日历日包含今天。这是为了财务报告和复盘。所以周一早上9点状态栏的1d成本可能还包含周日下午的花费而budi stats --period today则只显示周一零点以来的花费。两者都是正确的只是回答的问题不同。自定义状态栏 默认的显示可能不符合你的喜好。你可以创建~/.config/budi/statusline.toml文件来定制# 显示会话成本和健康状态 preset coach # 状态栏会显示为budi · $2.15 session · session healthy # 或者完全自定义显示的“槽位” slots [session, health, 7d] # 这将显示budi · $2.15 session · session healthy · $8.50 7d可用的槽位包括1d,7d,30d,session当前会话成本,health健康状态,branch当前分支,project当前项目等。5.2 Cursor扩展专属的成本监视器对于Cursor用户Budi提供了一个轻量级的VS Code扩展。它不像Claude Code那样深度集成而是在Cursor的状态栏添加一个独立的条目专门显示Cursor的花费。其显示格式和逻辑与Claude Code状态栏完全一致只是数据源限定于Cursor。安装后你会在Cursor状态栏看到一个类似 budi · $X 1d · $Y 7d · $Z 30d的条目。前面的圆点颜色表示守护进程的连接状态绿色正常黄色安静可能无活动红色无法连接白色未安装。一个贴心的设计这个扩展还是一个“引导入口”。如果你先在VS Code市场发现了Budi扩展并安装但还没装CLI扩展会显示一个欢迎页面里面直接给出了安装命令。你点击后它会在集成终端里帮你运行安装脚本体验非常流畅。5.3 云端仪表盘团队成本可视化可选对于团队负责人或想从更高维度查看趋势的个人开发者Budi提供了可选的云端同步和仪表盘功能app.getbudi.dev。启用步骤在仪表盘网站注册/登录在设置中创建一个API Key。在本地终端运行budi cloud init --api-key budi_your_key_here。这个命令会创建并配置~/.config/budi/cloud.toml文件。运行budi init重启守护进程以加载新配置。运行budi cloud status检查同步状态显示state: ready即可。隐私再强调云端同步只发送聚合数据。具体来说是每天每个维度如每个仓库、每个分支、每个模型聚合后的token总数和成本。你的提示词、代码、回复、原始文件路径、邮箱地址等永远不会离开你的电脑。同步是单向的本地推送到云端云端无法主动拉取你的数据。仪表盘提供了丰富的视图总览团队整体花费趋势图。仓库与工单下钻查看每个仓库、每个分支、每个工单的花费详情。会话列表查看团队所有成员最近的会话包括健康状态。模型分析查看不同AI模型的花费占比。这对于技术负责人进行资源规划、项目成本核算和优化团队AI使用习惯非常有价值。6. 高级技巧、问题排查与维护6.1 数据导入与管理导入历史数据budi db import是神器。它能从以下来源导入历史数据Claude Code: 本地的JSONL格式对话记录。Codex Desktop/CLI: 本地会话文件。Copilot CLI: 本地会话文件。Cursor: 通过其Usage API拉取历史用量数据需要网络。导入是增量且幂等的。Budi会记录每个文件的导入进度重复运行不会重复导入相同数据。如果你因为某些原因需要强制重新导入所有数据可以使用budi db import --force。数据库维护 Budi的SQLite数据库通常不需要手动维护。但在极少数情况下如异常关机导致数据库锁死你可以使用以下命令budi db repair: 尝试修复模式漂移并运行迁移检查。budi db migrate: 显式运行数据库迁移通常升级时自动完成。budi doctor --deep: 执行完整的SQLite完整性检查速度较慢但更彻底。6.2 常见问题排查1. 状态栏不显示或显示“未连接”首先运行budi doctor这是诊断一切问题的起点。它会告诉你守护进程是否在运行是否能找到日志文件。检查守护进程ps aux | grep budi-daemon(Linux/macOS) 或Get-Process budi-daemon(Windows PowerShell)。如果不在运行尝试budi init重启它。检查集成是否安装运行budi integrations list确认claude-code-statusline或cursor-extension状态是installed。如果不是运行budi integrations install --with integration-name重新安装。重启AI助手安装或更新集成后需要完全退出并重新启动Claude Code或Cursor。2. 检测不到AI助手活动确认AI助手正在写日志Budi依赖本地日志。确保你的AI助手如Claude Code正在正常运行并生成对话。检查日志路径运行budi doctor它会列出它正在监控的路径。你可以手动检查这些路径下是否有新的.jsonl或类似文件产生。等待一下Budi是尾随模式可能有几秒的延迟。发送一条消息后稍等片刻再检查。3. 成本计算为0或不准检查定价清单运行budi pricing status。Budi使用LiteLLM社区的定价清单来计算成本。如果清单里没有你使用的模型成本会显示为0或不准。可以运行budi pricing status --refresh手动刷新清单。查看成本置信度在budi sessions id的详细输出或云端仪表盘中查看每条消息的cost_confidence标签。exact表示精确计算来自Cursor API或Claude JSONLestimated是估算可能缺少“思考token”estimated_unknown_model则表示模型不在定价清单中。4. 升级后出现问题运行budi update这是推荐的升级方式它会处理数据库迁移和守护进程重启。检查版本一致性确保budi和budi-daemon版本一致。budi --version和查看进程信息确认。清理旧配置如果你是从8.0/8.1版本使用代理模式升级而来运行budi init --cleanup来检查和移除旧的代理配置。6.3 隐私与数据保留策略Budi提供了细粒度的隐私控制通过环境变量来配置BUDI_PRIVACY_MODEfull(默认): 存储原始值。hash: 对敏感字段如user_email,cwd进行哈希处理后再存储。omit: 完全不存储敏感的原始/会话字段。数据保留策略BUDI_RETENTION_RAW_DAYS: 设置sessions.raw_json原始会话数据的保留天数默认30天。设为off则永久保留。BUDI_RETENTION_SESSION_METADATA_DAYS: 设置会话元数据如用户邮箱、工作区根路径的保留天数默认90天。保留策略的清理会在同步和实时数据摄入后自动执行。关于数据库加密目前默认的SQLite数据库未加密。如果你在共享或受管制的机器上使用并且需要静态加密有两种选择将Budi的数据目录~/.local/share/budi放在加密卷上如macOS的FileVaultWindows的BitLocker。等待未来可能支持的SQLCipher编译版本这涉及密钥管理用户体验和打包复杂性因此不是当前默认选项。6.4 进阶使用脚本化与自动化Budi的CLI输出支持--format json这为自动化打开了大门。# 获取JSON格式的今日花费便于用jq等工具处理 budi stats --period today --format json | jq .total_cost # 将每日成本报告发送到Slack或邮件结合cron定时任务 #!/bin/bash DAILY_COST$(budi stats --period today --format json | jq -r .total_cost) curl -X POST -H Content-type: application/json \ --data {\text\:\ Todays AI coding cost: \$$DAILY_COST\} \ YOUR_SLACK_WEBHOOK_URL # 监控异常高消费设置警报 #!/bin/bash THRESHOLD10.00 # 美元 CURRENT_COST$(budi stats --period today --format json | jq -r .total_cost | sed s/[^0-9.]//g) if (( $(echo $CURRENT_COST $THRESHOLD | bc -l) )); then echo Warning: Todays AI cost (\$$CURRENT_COST) exceeds threshold (\$$THRESHOLD) | mail -s AI Cost Alert youremail.com fi通过这些脚本你可以将Budi集成到你的DevOps监控流程中实现成本管理的自动化和智能化。