vole

Vole 是一款针对 AI 编程代理的本地优先使用量、成本和异常监控工具。它解决了多个代理并行运行且各自独立消耗 Token，且在陷入工具循环、针对损坏的 API 重试或重复读取大上下文时无法发出信号的问题。其他工具关注“我花了多少钱？”，而 Vole 则关注“现在是否出了问题？”，并将支出作为一项副作用进行报告。 数据处理 Vole 读取工具已写入磁盘的日志文件——例如 Claude Code 的 ~/.claude/projects/**/*.jsonl、OpenCode 的 ~/.local/share/opencode/opencode.db、Codex CLI 的 ~/.codex/sessions/**/rollout-*.jsonl、Grok CLI 的 ~/.grok/logs/unified.jsonl，以及 Cursor、Devin 和 Antigravity 的本地存储——并将它们统一为单一模式。所有操作均在本地运行：无需抓取，无需云端 API，无需登录，且不存储提示词或工具内容。唯一请求的可选权限是通知，用于在触发关键事件时发出警报。 支持的工具与保真度策略 覆盖范围因工具而异：Claude Code 和 OpenCode 提供精确的 Token 和成本；Codex CLI 和 Grok CLI 提供精确的 Token 但无公开费率；Cursor、Devin 和 Antigravity 在本地不记录 Token，因此仅作为活动记录。项目策略规定不设“估算”层级——Token 计数要么直接从工具日志中读取，要么标记为缺失；没有 Token 的行仍计为调用，但被排除在 Token 和成本汇总之外。项目明确拒绝了通过代码行数估算 Cursor Token 的方案。 应用程序 菜单栏项目显示实时 Token、成本或仅显示图标，在有事件发生时会改变颜色。点击可打开包含核心数据、趋势图和分工具条形图的面板；仪表盘则提供完整视图。其标志性元素是一个带有事件标注的时间轴，可堆叠显示每个工具的 Token，并在悬停时显示桶名称、Token 数及触发的事件。应用内置了采集器并自行启动且原位更新：发布带有校验和的存档可实现一键安装（在替换 Bundle 前验证 SHA-256），而没有校验和的发布版本绝不会静默安装。 命令行与 MCP 除了应用外，Vole 还通过相同的数据提供终端命令：pnpm top（实时会话、上下文与窗口对比、每分钟 Token、缓存倒计时）、pnpm digest（带范围和 JSON 选项的 Markdown 代理使用摘要）、pnpm pr（用于 PR 描述的当前分支使用量）、pnpm statusline 以及 pnpm mcp（一个 stdio MCP 服务器）。MCP 服务器公开了 vole_summary, vole_live_sessions, vole_session, vole_incidents, vole_breakdown, vole_whatif 和 vole_digest，使代理能够询问自身会话的成本或 Vole 是否对其标记了异常。服务器读取本地数据库并通过 stdout 回答。 异常规则 内置五条规则：billable_burn_spike（10 分钟窗口成本超过该会话典型窗口的 3 倍）、repeat_call_loop（5 分钟内调用 45 次以上且输出保持不变）、error_storm（15 分钟内错误率超过 20% 且至少有 5 个错误）、rate_limit_pressure（Codex 报告配额消耗超过 80%）以及 context_pressure（单次调用占用模型上下文窗口的 80% 以上）。基准线采用留一法（leave-one-out），将当前窗口与所有其他窗口的中位数对比，且循环检测需要两个信号，以避免将高效的调用爆发误认为循环。 成本模型 成本基于列表价格的等效 API 价值（即通过 API 使用时的成本），UI 中会注明订阅计划并非按 Token 计费。费率存储在 packages/core/src/data/pricing.json 中，并带有 effective_from 版本控制；用户可通过 ~/.vole/pricing.json 进行覆盖，从而在无需发布新版本的情况下添加模型。在模型拥有费率之前存储的行将追溯重新定价。未知模型返回 NULL 而非 0。 验证与测试 项目提供 pnpm test 用于规则、查询、分桶和置信不变性的单元测试，以及 pnpm verify，后者使用独立实现的成本公式将每行存储数据与其源记录进行核对。验证是基于单条记录而非总量进行的，且在存储为空时会失败，以防止出现空跑通过的情况。pnpm seed 命令可写入 30 天的合成历史记录（标记为 source='seed'），并与实时数据分开图表化。 构建与限制 从源码构建需要 Node 22+、pnpm 和 Xcode 26，在 macOS 26 arm64 上测试；pnpm app:bundle 可构建并打开应用，采集器和应用也可分开运行。记录的限制包括：对不记录本地 Token 的工具覆盖度较低；is_error 仅涵盖 API 错误，可能导致 error_storm 低估；部分工具的生成速度为下限；上下文窗口仅能解析第一方模型 ID；Antigravity 的时间计算基于文件 mtime。项目采用 MIT 许可并欢迎贡献，审阅规则为：绝不凭空捏造数字，且每个采集器必须是幂等的。