@kimi.builders/usage

v0.5.3

Published

11 days ago

Local-first usage analytics and optional sync for AI coding agents

0High
0Medium
0Low

kimibuilders

kimi kimi-code claude-code codex ai-coding-agent local-first usage tokens

Kimi Builders Usage

简体中文 · English

把散落在不同 AI Coding Agent 里的本地用量，汇总成一张真正可分析的看板。

Kimi Builders Usage 会读取 Kimi Code、Claude Code、Codex、OpenCode 等工具已经保存在你电脑上的日志，统一展示 Token、标准 API 费用估算、活跃时间、模型、项目和订阅额度。本地看板无需账号、默认不联网；社区同步是独立的可选能力。

3 分钟开始

需要 Node.js 20+，无需安装桌面应用或全局 npm 包：

npx @kimi.builders/usage@latest dashboard

第一次运行时：

npm 会询问是否下载 @kimi.builders/usage，输入 y；安装过程不会扫描或上传数据。
本机看板先检测可用 Agent，但不会直接解析全部历史；在首次向导中选择每个 Agent 的 “关闭 / 仅本机 / 本机并同步”范围后才开始扫描。
扫描完成即可查看本机结果。连接社区、选择同步来源和启用后台同步都是向导中的可选步骤；不熟悉命令行也能完成。使用完按 Ctrl+C 停止。

默认只在本机工作。 打开看板、点击“重新扫描”以及运行 init 都不会上传；init 只连接设备。只有你明确运行 sync、点击“立即同步”、安装后台同步，或使用 init --sync 时，才会发送已标记为“本机并同步”的脱敏聚合数据。

如果看板没有识别到某个工具，先运行完全离线的检查：

npx @kimi.builders/usage@latest inspect --dry-run

查看支持来源 · 兼容矩阵与已知限制 · 排查问题

让 Agent 帮你完成

不熟悉终端也没关系。复制下面的提示词发给 Codex、Claude Code、Kimi Code 或其他能操作本机终端的 Agent，它会检查环境、扫描来源并启动看板：

阅读 https://github.com/kimi-builders/usage/blob/main/README.md，并按照当前文档在
这台电脑上安装和启动 Kimi Builders Usage。

要求：
1. 优先使用已发布的 npm 包和 npx；除非有明确理由，否则不要克隆仓库或全局安装。
2. 先运行 `node --version`。项目要求 Node.js 20+。如果未安装或版本过低，先说明适合
   当前操作系统的最安全安装方式，得到我确认后再安装或升级。
3. 运行 `npx @kimi.builders/usage@latest inspect --dry-run`，简要说明检测到了哪些
   Agent 来源。回复中不要暴露完整本机路径、凭据、会话标识或对话内容。
4. 运行 `npx @kimi.builders/usage@latest dashboard`，保持进程运行并打开已授权的本地
   看板地址。如果无法自动打开，让我从终端直接复制地址；不要把其中的 capability token
   粘贴到聊天中。
5. 这次只使用本地功能。除非我明确要求，否则不要运行 `init`、`sync` 或 `daemon`，
   不要启用额度 Provider、上传数据或修改隐私设置。
6. 如果命令失败，定位真实原因，只做最小且安全的修复后重试；最后简要说明当前运行状态，
   以及如何停止或重新启动。

如果你已经决定连接社区并同步，可以改用下面这个提示词。它会在设备授权时停下来让你确认，不会擅自安装持续同步服务：

阅读并遵循以下文档的当前说明：
- https://github.com/kimi-builders/usage/blob/main/README.md
- https://github.com/kimi-builders/usage/blob/main/PRIVACY.zh.md
- https://github.com/kimi-builders/usage/blob/main/NETWORK.zh.md

帮我把 Kimi Builders Usage 连接到 kimi.builders，并执行一次同步。先确认 Node.js 20+，
再运行离线 dry-run。然后用 `npx @kimi.builders/usage@latest status` 检查现有连接。
如果设备尚未连接，运行 `npx @kimi.builders/usage@latest init`，打开设备批准页面后暂停，
让我检查并批准。批准完成后执行一次 `npx @kimi.builders/usage@latest sync`，核对最终状态，
再启动本地看板。不要输出或复制 API Key、Cookie、凭据、完整本机路径、会话标识或对话内容。
除非我另行明确批准，否则不要安装、重启或移除后台 daemon。

用量中心总览

先看重点

| 你可能关心的问题 | 答案 | | --- | --- | | 会上传对话或代码吗？ | 不会。Token 看板默认纯本地，也不会读取 prompt、response 或文件内容。 | | 必须注册社区账号吗？ | 不需要。本地看板和本地订阅分析可独立使用。 | | 支持哪些 Agent？ | 内置 11 个自动扫描来源，Cursor CSV 可显式启用；详见下方兼容表。 | | 费用是真实账单吗？ | 不是。费用按标准 API 价格估算，并明确显示定价覆盖率和未定价 Token。 | | 支持哪些系统？ | macOS、Linux、Windows；需要 Node.js 20 或更高版本。 |

按你的需求继续

只想看本地用量： 到这里已经完成，不需要 init。

想看订阅额度： 在本地看板进入“权益中心 → 权益设置”，只启用你使用的平台。额度查询默认关闭，不会因为打开 Token 看板而访问供应商。

想同步到社区或跨设备查看： 点击看板中的“同步数据”，完成浏览器设备授权并选择允许同步的 Agent；单次同步、后台同步、断开和删除当前设备云端数据都可在看板中管理。CLI 等价方式是：

npx @kimi.builders/usage@latest init
npx @kimi.builders/usage@latest sync

社区只接收脱敏后的聚合记录，项目名默认不上传。完整步骤见连接与同步社区。

三种能力，三个明确边界

| 能力 | 默认联网 | 是否需要账号 | 数据去向 | | --- | --- | --- | --- | | 本地 Token 看板 | 否 | 否 | 仅本机内存与浏览器 | | 订阅额度 | 否，需逐平台启用 | 供应商本机登录或手动凭据 | 本机直连所选供应商 | | 社区同步 | 否，需主动连接 | kimi.builders | 脱敏后的聚合数据 |

云端不能主动读取你的电脑。完整网络目标和触发条件见网络行为。

你能得到什么

今天、24H、7D、30D、90D 与全部历史的完整本地 Web 看板。
输入、缓存写、缓存读、输出、推理、请求和会话的跨 Agent 统一口径。
趋势、自然周对比、分时活跃、分布、明细、CSV/JSON 导出与分享海报。
模型规范化、推理强度、Agent 版本、终端与操作系统信息（来源可提供时）。
标准 API 费用估算、定价覆盖率和未定价提示，不把估算伪装成订阅账单。
可选的订阅中心：额度历史、消耗节奏、Token 容量和订阅价值观察。

从源码运行

git clone https://github.com/kimi-builders/usage.git
cd usage
npm run setup
npm run dev

npm run setup 只在第一次安装看板开发依赖。npm run dev 会同时启动本地 API 和 Vite 看板，不需要两个终端。下文使用 npx @kimi.builders/usage …；源码目录中可替换为 node ./bin/kbu-usage.js …。

如果不想自动打开浏览器：

npm run dev -- --no-open

本地看板

npx @kimi.builders/usage dashboard

看板每次启动都会生成新的浏览器访问令牌，并拒绝非本机 Host、Origin 和未授权请求。 “重新扫描”只刷新本机数据；“同步数据”才会执行社区增量同步。

价格目录按模型、生效时间、上下文档位和处理档位匹配标准 API 单价。init 会 best-effort 下载社区公开的版本化目录，也可在看板或通过 pricing update 主动更新；下载内容只含公开价格，不会上传本机用量。目录经过严格校验并保留 last-known-good，离线时始终可回退随包内置快照。看板会明确展示定价覆盖率、假设定价与未定价 Token，避免把不完整估算伪装成账单。

会话时间采用跨工具一致的投入时间口径：

活跃时长：同一轮 assistant/tool 事件之间的间隔，每段最多计 5 分钟；
投入时长：user 到 assistant/tool 的轮内时间线，每段最多计 30 分钟；
长期复用的 session ID 不会把离线数天误算成连续工作时间。

数据字段与计算口径见本地快照 v1。

支持的本地用量来源

| Agent | 状态 | 本机来源 | | --- | --- | --- | | Kimi Code | 核心 | ~/.kimi-code 与旧版 ~/.kimi | | Claude Code | 稳定 | $CLAUDE_CONFIG_DIR、~/.claude* 的项目日志 | | Codex | 稳定 | $CODEX_HOME 或 ~/.codex 的当前与归档会话 | | OpenCode | 稳定 | SQLite 数据库，旧版 JSON 回退 | | Gemini CLI | 稳定 | ~/.gemini/tmp 中的 JSONL/JSON 会话 | | Antigravity | 稳定 | App 2.0 / agy CLI 的离线 SQLite 会话库 | | GitHub Copilot CLI | 稳定 | 本机 CLI 会话日志 | | Roo Code | 稳定 | VS Code 扩展的本地任务数据 | | Pi Coding Agent | Beta | ~/.pi/agent/sessions 等 JSONL 会话；格式覆盖仍在扩充 | | ZCode | Beta | 本机 SQLite 会话库；Node 20 可能需要系统 sqlite3 | | WorkBuddy / CodeBuddy | Beta | WorkBuddy/CodeBuddy 本机项目会话存储 | | Cursor | 显式启用 | Cursor Dashboard 主动导出的 Usage CSV |

每个来源独立解析。一个来源损坏、未安装或格式变化，不会阻塞其他来源，也不会清理它原有的同步 checkpoint。可先运行以下命令检查环境，全程不联网：

npx @kimi.builders/usage inspect --dry-run
npx @kimi.builders/usage doctor
npx @kimi.builders/usage sources list

doctor --json 适合附在 Issue 中：它不包含路径、项目、模型、会话 ID 或时间明细，但仍含汇总数量与脱敏错误，分享前请自行检查。

Cursor 是当前唯一需要先提供数据文件的用量来源。新手可在首次设置或看板的 “本机与数据源”中粘贴 CSV 完整路径并验证；终端用户也可以执行：

npx @kimi.builders/usage sources enable cursor --csv /path/to/usage.csv
npx @kimi.builders/usage sources disable cursor

Cursor 的本地来源配置不依赖社区账号或 init。看板验证和启用命令都只保存本机 CSV 路径，不会联网，也不会自动执行社区同步。各来源的成熟度、限制和验证证据见来源兼容矩阵。

订阅额度（可选）

订阅额度与本地 Token 消耗不是同一类数据。它默认关闭；只有你在本地设置里启用某个平台， Collector 才会复用该平台的本机登录或读取你指定的凭据并发起查询。

当前支持 Codex、Claude Code、Kimi Code、Cursor、GitHub Copilot、Antigravity、 DeepSeek、OpenCode Go、Qoder、Warp 与 JetBrains AI。不同平台支持自动检测、环境变量或 macOS 钥匙串中的一种或多种方式。Trae 暂无稳定且可独立验证的个人额度接口，因此只显示“暂不可查”，不会生成猜测数据。

Gemini CLI 的个人版 OAuth 权益入口已由 Google 退役，因此不再作为权益 Provider；已有的 Gemini CLI 本机 Token 历史仍由离线 Parser 保留。Antigravity 会优先复用已经运行并登录的 Antigravity 或 agy 回环服务，读取 Gemini 与 Claude/GPT 的 5 小时和每周额度；工具不会为额度查询自动启动或终止用户进程。没有可用本机服务时，才会使用用户明确配置的 Antigravity OAuth 或 CodexBar 凭据。

DeepSeek 使用用户明确配置的 API Key 查询公开余额接口，只展示按币种返回的总余额、充值余额与赠送余额，不把货币换算成 Token 额度。权益中心会另外按 DeepSeek 模型标识汇总各 Agent 的本机用量；这条模型家族证据可能与对应 Agent 权益视图重叠，也不能证明请求属于当前 API Key 账户，组合总量会按原始记录去重。

额度页默认把 Kimi Code 放在第一位。你可以在设置中抓住手柄直接拖动已启用平台，桌面鼠标和移动端触控都可用；排序保存在本机，并同时用于额度页签和查询顺序。

每次成功刷新都会在本机保存一份脱敏额度快照。订阅中心会把相同供应商、相同时间窗的额度变化与本机 Token 对齐，显示消耗速度、重置时预计用量、近 30 天单位 Token 实际成本、标准 API 等价价值和模型集中度。所有建议都附带证据窗口，仅供续费与工作流决策参考；它不会自动改套餐，也不会把订阅利用率描述成供应商公布的固定 Token 上限。

额度凭据和响应不会进入 Token 快照、导出文件或社区同步。手动 Secret 不写入普通 config.json。脱敏历史最多保留 400 天，较旧数据自动降采样；它同样不会进入导出、海报或社区同步。各平台网络目标和认证边界见网络行为，本地保存字段见隐私说明。

连接与同步社区（可选）

首次连接（也可完全在看板“同步数据”中完成）：

npx @kimi.builders/usage init

终端会显示设备码并打开社区授权页。授权后，设备得到一枚可单独撤销的 kbu_ Key； init 本身不会上传用量，接下来请在看板或 sources set 中确认来源范围，再执行同步。项目名同步默认关闭；关闭时上传 JSON 中根本不存在 project 字段。

连接验证码有效 10 分钟，只临时保留在当前 Collector / 本地看板进程中，不会写入浏览器存储或配置文件。刷新看板可继续当前请求；停止或重启进程后需要生成新验证码。设备 Key 则在批准后仅交付一次，并可随时从本地看板安全撤销。

每个 Agent 都有三个独立模式：

npx @kimi.builders/usage sources list
npx @kimi.builders/usage sources set codex off
npx @kimi.builders/usage sources set kimi-code local
npx @kimi.builders/usage sources set claude-code private

off 不扫描，local 只进入本机分析，private 才允许发送到你的社区账户。改变模式不会自动删除已有云端历史；删除当前设备云端数据是看板中的独立确认操作。新支持的 Agent 默认只在本机启用，不会自动加入同步；这些聚合数据是否公开由社区账号设置另行控制。

单次同步：

npx @kimi.builders/usage sync

持续同步：

npx @kimi.builders/usage daemon install --interval 15
npx @kimi.builders/usage daemon status
npx @kimi.builders/usage daemon restart
npx @kimi.builders/usage daemon uninstall

后台服务以当前用户身份运行，不需要管理员权限：macOS 使用 launchd，Linux 使用 user systemd，Windows 使用 Task Scheduler。设备休眠或离线时不会工作；升级 Collector 后执行一次 daemon restart，让服务使用新版本路径。

同步采用增量 checkpoint、失败来源隔离和并发锁。重复运行不会重复计数。如果你在社区删除了某台设备的数据、更换了设备连接，或看板提示本机与社区 checkpoint 无法确认一致，先核对所有 Agent 的 private 范围，再显式完整同步：

npx @kimi.builders/usage sync --full

--full 只重传标记为 private 的标准化聚合数据，不包含 off 或 local 来源，也不会删除社区数据。checkpoint 会绑定到社区地址和设备凭据的不可逆指纹；重新授权后不会误把旧设备的本机记录当作已经上传。看板遇到相同情况时会展示范围说明并要求二次确认。

常用命令

| 命令 | 作用 | 网络 | | --- | --- | --- | | stats [--period 7d\|30d\|today] [--source agent] | 本地多维离线用量统计与每日 ASCII 趋势图 | 无 | | quota [--provider name] [--all] [--json] | 查询 AI 平台订阅额度、多窗口进度条与倒计时（别名 limits） | 仅限已登录/配置平台 | | top [--period 30d] | 按消耗量查看模型、来源与项目排行 | 无 | | export [--format csv\|json\|jsonl] [-o PATH] | 导出本地用量数据为标准 CSV / JSON / JSONL | 无 | | dashboard [--no-open] [--port N] | 启动本地交互式可视化 Web 看板 | 默认无 | | status | 查看本地运行状态、配置与连接信息 | 无 | | pricing status\|update\|reset | 查看、主动更新价格目录，或恢复随包内置离线快照 | status/reset 无；update 有 | | inspect --dry-run | 显示读取目录与来源扫描结果 | 无 | | doctor [--json] | 生成脱敏兼容性与数据一致性报告 | 无 | | sources list | 查看本地用量来源状态与策略 | 无 | | sources set <agent> off\|local\|private | 设置单个 Agent 的扫描与同步范围 | 无 | | completion [zsh\|bash\|fish] | 生成 Shell 自动补全脚本 | 无 | | init [--api-url URL] [--sync] [--skip-pricing-update] | 连接社区设备并 best-effort 更新公开价格；默认不上传，--sync 才立即同步 | 有 | | sync [--full] | 上传变化的聚合数据；--full 经确认后完整重传允许同步的来源 | 有 | | daemon install/status/restart/uninstall | 管理后台定时同步服务 | 见 NETWORK | | summary [--days N] [--remote] | 查看用量汇总（默认本地优先，--remote 查看云端） | 本地无 / 远端有 | | reset --local | 清除本地同步 checkpoint | 无 |

通用参数：--lang en|zh（指定语言，默认自动检测系统语言）、--no-color / --plain（禁用 ANSI 颜色）、--json（结构化输出）。

本地配置与同步状态位于 ~/.kimi-builders/usage/；POSIX 系统上的敏感配置文件权限为 0600。

隐私承诺

Collector 不会上传：

prompt、response、reasoning 文本或 tool result；
完整路径、文件内容、仓库 remote 或环境变量转储；
原始 session ID；
供应商 Cookie、OAuth Token、API Key 或额度响应；
本地看板的筛选、浏览与操作记录。

Session ID 使用安装级随机盐进行 HMAC-SHA-256 转换，不同设备无法用结果互相对照。本地快照可以保留项目目录的 basename 供私人分析；社区同步默认移除项目字段。

进一步阅读：

开发与验证

npm run setup
npm run dev

提交前：

npm test
npm run dashboard:build
npm run dashboard:test

发布前完整检查：

npm run release:check

它会运行 Collector 测试、构建并测试看板，再执行 npm pack --dry-run 展示实际发布内容。 npm publish 也会通过 prepublishOnly 自动执行同一套检查，但不会在检查命令中被调用。发布流程见发布清单。

测试会把来源、配置和状态目录指向临时 fixture，不读取开发者真实的 HOME。

如果你准备提交 Parser、额度 Provider、同步协议或 UI 改动，请先阅读 CONTRIBUTING.md 中对应类别的隐私与测试清单。安全漏洞请勿公开建 Issue，使用 SUPPORT.md 提供的私密报告入口。

License 与来源说明

初始 parser 层的部分实现与测试改编自 MIT 许可的 @vibe-cafe/vibe-usage。产品与额度能力还参考了 Vibe Usage 的桌面客户端；部分 provider 额度协议与解析实现改编自 CodexBar。代码改编、产品参考与打包依赖被分开记录，不表示相关项目共同拥有、参与维护或为本项目背书。完整来源见 NOTICE。