1. 项目概述Budi你的AI编码助手成本管家如果你和我一样日常开发已经离不开Claude Code、Cursor这类AI编码助手那你肯定也经历过那种“账单焦虑”——用的时候很爽月底看到账单时心里一咯噔。这些工具按token收费但它们的原生界面要么只显示当前会话的粗略消耗要么干脆不显示你根本不知道钱具体花在了哪个项目、哪个功能分支甚至哪个bug修复上。这种黑盒状态对于需要向团队或客户汇报成本或者只是想优化自己使用习惯的开发者来说非常不友好。Budi就是为了解决这个问题而生的。它是一个用Rust编写的本地优先Local-first的AI编码助手成本分析工具。简单来说它就像一个默默运行在你电脑后台的“财务审计员”自动追踪Claude Code、Cursor、Codex CLI、Copilot CLI等工具产生的每一次API调用精确计算token消耗和成本并按项目仓库、Git分支、工单Ticket、活动类型等多个维度进行归因分析。最核心的理念是隐私至上所有原始数据你的提示词、代码、AI回复都留在你的本地机器上Budi只分析元数据。你可以选择将聚合后的每日成本摘要同步到云端仪表盘方便团队查看但这完全是可选的。我第一次接触Budi时最打动我的是它的“无侵入”设计。它不需要你修改任何代理配置、包装命令行或者改动你的工作流。安装后运行一次budi init它就会自动发现并开始“尾随”tail这些AI工具已经在本地磁盘上生成的会话文件JSONL格式。你原来怎么用Claude Code现在还怎么用Budi在后台帮你把账算得明明白白。2. 核心设计思路与架构解析Budi的架构设计充分体现了其“本地优先”和“轻量级”的核心原则。理解这个架构能帮你更好地信任它也能在出问题时知道从哪里排查。2.1 核心组件守护进程与CLI的分离Budi采用经典的客户端-守护进程Client-Daemon模型这与很多现代开发工具如Docker、数据库客户端的思路一致。budi-daemon(守护进程)这是整个系统的大脑和唯一的数据处理中心。它是一个常驻内存的Rust二进制程序默认运行在本地7878端口。它的核心职责有三个数据摄取Ingestion通过一个“文件尾随器”tailer持续监控Claude Code、Cursor等工具写入本地磁盘的会话文件。一旦有新的内容追加它就立即读取、解析并提取出成本相关的元数据如消息ID、时间戳、模型、token数、归属标签等。数据存储与计算将所有处理后的数据写入一个本地的SQLite数据库budi.db。同时它还会实时计算并维护一些聚合表如按小时、按天的滚动汇总为快速查询提供支持。提供API服务守护进程内置了一个HTTP服务器。所有来自CLI的命令实际上都是向localhost:7878发送HTTP请求由守护进程查询数据库后返回结果。这意味着CLI工具本身是无状态的也永远不会直接接触数据库文件这保证了数据的一致性和安全性。budi(CLI命令行工具)这是用户交互的界面。它本身不处理数据只是一个“瘦客户端”。当你运行budi stats或budi sessions时CLI会向本地守护进程发起请求获取格式化后的结果展示给你。这种设计使得CLI可以非常轻量也便于更新。实操心得这种架构的一个巨大好处是稳定性。即使你强制退出了CLI守护进程依然在后台运行继续收集数据。你可以随时重启CLI进行查询。同时因为所有计算都在守护进程内完成CLI的响应速度非常快。2.2 数据流从AI助手到成本报表让我们跟踪一次AI交互在Budi系统中的旅程事件发生你在Claude Code中提问“如何优化这个React组件的渲染性能”本地落盘Claude Code应用程序或Cursor、Codex在后台调用AI API如Anthropic的Claude API后会将完整的会话记录包括你的提问和AI的回复以JSON LinesJSONL格式追加写入一个本地文件。这个文件通常位于像~/Library/Application Support/Claude Code/transcripts/这样的标准目录下。这是AI工具自身的行为Budi没有参与也不会改变。Budi捕获Budi的守护进程通过inotifyLinux/macOS或等效的机制监控着这些已知的目录。它检测到有新数据写入文件立刻读取新增的JSONL记录。数据提取与标准化Budi解析JSONL提取关键字段基础信息时间戳(timestamp)、提供方(provider)、模型(model)。成本核心输入token数(input_tokens)、输出token数(output_tokens)。对于Claude Code的JSONL这些是精确值对于某些其他来源可能是估算值。归属标签这是Budi的精华所在。它会结合当前工作目录cwd、Git仓库信息、可能的工单ID从分支名解析如feature/PROJ-123会解析出工单IDPROJ-123等为这条消息打上repo_id,git_branch,ticket_id,activity如bugfix,refactor等标签。成本计算与存储Budi根据提取的模型名称和token数量查询其内置的定价清单默认从LiteLLM项目同步计算出本次调用的成本以美分为单位连同所有标签一起作为一条记录插入messages表。同时相关的tags表、sessions表会话生命周期以及聚合汇总表也会被更新。查询与展示此时你运行budi statusCLI向守护进程的API发起请求。守护进程快速查询聚合表返回“今日花费 $X.XX”的信息。或者你在云端仪表盘看到按仓库的成本排名也是守护进程如果启用了云同步将每日聚合数据推送后计算的结果。2.3 隐私边界设计什么数据留在本地什么数据可以同步这是Budi设计中最值得称道的一点它明确划定了隐私红线绝对留在本地的数据永不离开原始提示词PromptsAI生成的代码和回复内容具体的文件绝对路径Budi会将其转换为相对于Git仓库的路径后再存储任何可能包含代码片段或敏感信息的原始JSON负载可以同步到云端的数据需手动开启且仅为聚合数据聚合后的数字指标总token数、总成本美元/美分维度标签模型名称、仓库ID哈希值、分支名、工单ID、活动类型会话元数据会话开始/结束时间、持续时间、健康状态如“上下文膨胀”请注意云同步发送的是按天daily聚合的摘要而不是每一条消息的实时流。这意味着云端无法重建出你的原始对话。这种设计让你可以在享受团队协作视图谁在什么项目上花了多少钱的同时完全不用担心代码或业务逻辑泄露。对于企业或敏感项目开发者来说这是至关重要的信任基础。3. 从零开始安装、配置与核心操作3.1 选择与执行安装Budi提供了多种安装方式我个人最推荐使用HomebrewmacOS/Linux或独立安装脚本因为它们能最好地处理后续更新和PATH配置。对于macOS/Linux用户推荐Homebrew# 如果你已经安装了Homebrew brew install siropkin/budi/budi # 安装完成后必须运行初始化命令 budi initHomebrew安装不会自动运行budi init所以别忘了手动执行。budi init命令会做几件关键事创建必要的配置和数据目录、启动守护进程、设置开机自启服务并为你安装默认的集成如Claude Code状态栏。对于所有平台通用脚本安装# macOS/Linux curl -fsSL https://raw.githubusercontent.com/siropkin/budi/main/scripts/install-standalone.sh | bash # Windows (PowerShell) irm https://raw.githubusercontent.com/siropkin/budi/main/scripts/install-standalone.ps1 | iex独立安装脚本会自动执行budi init。安装完成后建议立即运行budi doctor来检查一切是否就绪。注意事项避免混合安装方式。例如不要既用Homebrew装了一遍又运行脚本装到~/.local/bin。这会导致PATH中存在两个不同版本的budi二进制文件可能引发版本冲突和不可预知的行为。如果你发现命令行为异常可以用which -a budi(macOS/Linux) 或Get-Command budi -All(Windows PowerShell) 检查哪个二进制文件被优先执行。3.2 初始化与首次运行检查清单安装并运行budi init后我建议你按照以下“5分钟清单”快速验证整套流程是否畅通验证守护进程运行budi status。你应该能看到类似Daemon: healthy (pid: 12345)和Todays cost: $0.00的输出。如果守护进程没起来budi doctor会给出更详细的错误信息。触发一次AI交互像平常一样打开Claude Code或Cursor问一个简单的问题比如“写一个Python的hello world”。目的是让AI助手在本地生成一个会话文件。检查数据捕获等待几秒钟然后再次运行budi status。如果一切正常“Today‘s cost”应该从一个非常小的数字比如$0.01开始变化。你也可以运行budi sessions查看最近的会话列表应该能看到你刚刚进行的那次交互。查看状态栏可选但推荐如果你使用Claude Code重启它完全退出再打开。你应该能在编辑器窗口底部状态栏的右侧看到Budi添加的成本信息例如budi · $0.05 1d · $0.05 7d · $0.05 30d。这证明状态栏集成已成功。导入历史数据可选如果你已经使用AI助手有一段时间了想看看历史总花费可以运行budi db import。这个命令会扫描本地已有的历史会话文件JSONL并将其导入Budi的数据库。这个过程可能需要几分钟取决于你的历史数据量。你可以通过budi db import --format json来查看详细的导入进度。3.3 核心CLI命令详解Budi的CLI是你与数据交互的主要窗口。除了基础的status以下命令组合能帮你回答各种成本相关的问题“我的钱主要花在哪些模型上了”budi stats --models这个命令会按模型如claude-3-5-sonnet-20241022gpt-4o分组显示总成本、总消息数、总token数。这对于优化模型选择非常有帮助——也许你会发现大部分简单任务用便宜模型就够了。“哪个项目/仓库最烧钱”budi stats --projects这会按Git仓库进行成本排名。没有关联到Git仓库的交互会被归到(no repository)类别。如果你想查看这些非仓库工作的详细目录可以加上--include-non-repo参数。“我正在开发的‘用户登录’功能分支花了多少钱”budi stats --branch feature/user-auth你可以精确查看某个特定分支的总成本。结合--tickets参数你还能看到这个分支上各个工单如果分支名能解析出工单ID的花费情况。“排查BUG和代码重构哪个更费AI”budi stats --activities budi stats --activity bugfix budi stats --activity refactorBudi会尝试从交互内容或上下文中推断“活动”类型。这个功能对于分析团队工作模式非常有用。“我想看看最近具体有哪些会话以及它们健康吗”budi sessions # 查看某个特定会话的详细信息包括健康诊断 budi sessions session_id budi vitals --session session_idsessions命令列出所有会话而vitals则专注于Budi对会话健康的评估比如是否出现“上下文膨胀”或“缓存命中率低”。“我想导出数据做进一步分析。”budi stats --period month --format json cost_report.json budi sessions --format json sessions.json几乎所有数据查询命令都支持--format json参数方便你进行脚本化处理或导入到其他数据分析工具如Excel、Tableau。4. 高级配置与定制化4.1 状态栏个性化默认的状态栏显示滚动1天、7天、30天的成本。但你可以通过创建配置文件~/.config/budi/statusline.toml来定制显示内容。# 示例切换到“教练”模式显示当前会话成本和健康状态 preset coachcoach预设会显示类似budi · $1.24 session · session healthy的信息让你在编码时实时关注当前会话的“健康度”。# 示例完全自定义显示的“槽位” slots [session, health, 1d, project]可用的槽位包括session: 当前会话成本health: 当前会话健康状态绿色勾、黄色叹号、红色叉1d/7d/30d: 滚动窗口成本branch/project: 当前分支/项目成本provider: 当前提供方如claude_code4.2 自定义标签规则Budi自动从Git分支名等地方解析标签但你也可以定义自己的规则。例如你想为特定仓库的所有交互打上团队标签。创建文件~/.config/budi/tags.toml[[rules]] key team # 标签键 value frontend # 标签值 match_repo github.com/your-org/frontend-app # 当仓库匹配此模式时应用 [[rules]] key environment value staging # 你可以使用更灵活的通配符或正则表达式取决于Budi实现 match_branch staging/*自定义标签会出现在budi stats --tag key的统计中让你能按自定义维度进行成本聚合。4.3 配置云端同步可选如果你需要团队协作视图可以启用云端同步。这完全是可选的。生成配置文件并获取API密钥budi cloud init这个命令会在~/.config/budi/下创建一个cloud.toml文件里面是所有配置项的注释模板。获取并配置API密钥访问app.getbudi.dev注册/登录后在设置Settings里找到API Keys。复制你的API密钥形如budi_xxxxxx。编辑~/.config/budi/cloud.toml文件取消enabled false的注释并将其改为enabled true然后在api_key项填入你的密钥。或者更简单的一步到位命令将KEY替换为你的实际密钥budi cloud init --api-key budi_your_key_here重启守护进程以应用配置budi init因为守护进程在启动时读取配置修改后需要重启。检查同步状态budi cloud status如果显示state: ready和last_synced_at时间说明同步已就绪。守护进程会定期或根据配置将本地的每日聚合数据推送到云端。重要提示再次强调云同步只发送高度聚合、去标识化的摘要数据。你的代码、提示词等原始数据绝不会离开你的电脑。云端仪表盘提供的是团队级的成本趋势、排名和健康洞察而非个人对话记录。5. 实战场景解决真实问题与避坑指南5.1 场景一优化团队AI预算分配问题作为一个技术主管你给团队批了一笔月度AI工具预算但发现总是超标且不清楚钱花在哪了。Budi解决方案让团队所有成员安装Budi并启用云同步需统一团队。月底登录app.getbudi.dev团队仪表盘。查看“项目”视图立刻识别出消耗最高的仓库是“用户推荐系统后端”。查看“成员”视图发现资深工程师“张三”的成本远高于其他人。结合“分支”和“活动”视图深入分析发现“张三”在feature/rec-algo-v2分支上的refactor重构活动消耗巨大。行动与“张三”沟通发现他在使用AI进行大规模代码重构时频繁使用了“继续”和“重试”导致上下文不断膨胀成本激增。你可以分享Budi的“会话健康”提示如建议使用/compact清理上下文或建议对大型重构任务进行更细粒度的拆分。5.2 场景二个人开发者控制月度支出问题作为自由职业者你需要将AI成本计入项目报价但缺乏精确数据。Budi解决方案为每个客户项目使用独立的Git仓库或至少是独立分支。正常使用AI编码。每周运行一次budi stats --projects --period week查看各项目成本。在项目结束时运行budi stats --project repo_url --period all获取该项目的总AI成本。精准计费你可以将这部分成本明确列入账单或作为自己定价策略的参考依据确保利润空间。5.3 常见问题与排查技巧实录即使设计得再完善在实际使用中也可能遇到一些小问题。以下是我和社区用户遇到过的一些典型情况及其解决方法问题1budi status显示成本始终为$0.00但明明用了AI。排查步骤运行budi doctor。这是你的第一道诊断工具。它会检查守护进程状态、数据库、以及是否能找到AI工具的会话文件目录。如果“Transcript visibility”检查失败说明Budi没找到你的AI工具数据。确认你的AI工具如Claude Code确实在运行并产生了交互。可以手动去默认的目录如macOS上Claude Code的~/Library/Application Support/Claude Code/transcripts/查看是否有新的.jsonl文件。某些AI工具可能需要特定版本或配置才会写入本地会话文件。查阅Budi官方文档的“Supported agents”部分确认你的工具版本在支持范围内。如果budi doctor显示一切正常但依然没数据尝试重启守护进程pkill budi-daemon然后重新运行budi init。问题2状态栏没有在Claude Code/Cursor中显示。排查步骤运行budi integrations list确认claude-code-statusline或cursor-extension的状态是installed。如果显示available手动安装budi integrations install --with claude-code-statusline。最关键的一步完全退出并重启你的Claude Code或Cursor编辑器。集成是通过修改编辑器的配置文件实现的需要重启才能加载。对于Cursor还可以检查扩展是否已启用在Cursor中按CmdShiftP(macOS) 或CtrlShiftP(Windows/Linux)输入Extensions: Show Enabled Extensions查找budi。问题3成本数字看起来不对偏高或偏低。理解“成本置信度”运行budi stats --format json | jq .messages[] | .cost_confidence需要安装jq查看每条消息的成本置信度标签。exact表示来自官方API的精确token数最准。estimated是Budi根据JSONL里的token数和模型单价估算的可能缺少“思考过程”的token但通常误差在5-10%以内。estimated_unknown_model则表示模型不在定价清单里成本暂时为0。更新定价清单运行budi pricing status --refresh强制更新本地模型定价缓存。AI服务商经常更新模型和价格Budi需要同步这些信息。检查模型识别有些AI工具可能在JSONL里使用了非标准的模型标识符。你可以查看原始数据片段来确认。问题4升级Budi后出现奇怪错误。首先备份你的数据库Budi的数据默认在~/.local/share/budi/budi.db(Unix) 或%LOCALAPPDATA%\budi\budi.db(Windows)。升级前可以手动复制一份。使用内置修复工具运行budi db repair。这个命令会检查数据库模式schema是否有漂移并尝试自动修复。查看日志守护进程的日志通常输出到标准错误stderr。你可以通过系统服务管理器如launchctlon macOS,systemctlon Linux查看日志或者在启动时重定向日志文件以便排查。问题5我想彻底卸载Budi。运行budi uninstall。这会移除CLI二进制文件、守护进程、开机自启服务、状态栏集成以及所有配置文件和数据。如果你只想卸载程序但保留历史数据以便将来重新安装后使用可以运行budi uninstall --keep-data。这样只会移除程序文件和服务保留~/.local/share/budi/目录下的数据库。我个人在实际使用中的体会是Budi最大的价值在于它把“成本”这个模糊的概念变得可观测、可分析、可优化。它不会阻止你使用AI而是让你用得更加明智。当我看到某个重构会话的成本异常高时我会反思是不是我的提示词不够清晰导致了过多的来回交互。当我发现某个项目分支的成本占比过高时我会在代码审查时更加关注那里的AI使用模式。它从一个单纯的记账工具变成了一个提升我与AI协作效率的“教练”。最后再分享一个小技巧定期比如每周一早上运行一下budi stats --period week --models看看上周的模型使用分布能帮你快速调整本周的模型选择策略长期下来能省下不少开销。