Token Monitor 开发者指南从零接入你自己的 AI 工具Tracked Client 注册流程详解【免费下载链接】token-monitorLocal-first desktop widget for tracking token usage, costs, and limits across 43 AI coding tools—including Claude Code, Codex, Cursor, OpenCode, OpenClaw, and more—with multi-device sync.项目地址: https://gitcode.com/gh_mirrors/tok/token-monitorToken Monitor 是一个本地优先local-first的桌面监控组件用于追踪 43 款 AI 编程工具如 Claude Code、Codex、Cursor、OpenCode 等的 Token 用量、花费与配额限制并支持多设备同步。本文面向贡献者带你完整走一遍Tracked Client被追踪客户端注册流程从零接入你自己的 AI 工具只需修改约 8 个约定位置即可让它出现在用量面板、设置列表与托盘图标中。先搞懂核心概念Tracked Client 的 id 贯穿一切Token Monitor 的数据采集依赖一个名为tokscale的解析内核它直接读取各 AI 工具在本地留下的会话文件transcript无需任何 API Key。因此接入一个新工具的本质是让监控系统知道这个工具的数据放在哪、叫什么名字、用什么颜色展示。整个流程围绕一个唯一标识id如claude、zed展开。新增客户端时要触碰的位置如下表环节位置作用客户端身份clientCatalog.jsid、显示名、默认是否追踪数据源根目录clientSourceRegistration.jsWSL 发现标记显式扫描根clientSources.js平台/环境相关路径健康检查 idclientHealth.jscheckId 白名单名称归一化usage.jstokscale 数据行归属视觉呈现vendorPresentation.js品牌色与图标Token 契约verify-vendored-tokscale.js计费口径校验文档与守卫README.md与tests/一致性测试官方注册清单详见 docs/providers/README.md架构背景见 docs/architecture.md。一键上手8 步注册流程第 1 步在 CLIENT_CATALOG 登记身份在 clientCatalog.js 的CLIENT_CATALOG数组中插入一条记录插入位置即显示顺序设置列表、README 表格都按此排序{ id: fx, label: fx }两个可选布尔值defaultTracked: false表示新安装时默认不追踪保持已接线但关闭locallyParsed: true表示该工具不走 tokscale 而由本地适配器解析如 providers/qodercn/。第 2 步声明数据源根目录先在 clientSourceRegistration.js 的SOURCE_MARKERS中登记 home 相对路径主机与 WSL 相同的路径声明一次即可{ marker: .fx/sessions, client: fx, hostCheckId: fx-sessions }若路径依赖平台或环境变量如 Windows 的AppData/Roaming/...则在 clientSources.js 的clientSourceRoots()中用显式add([checkId, dir])补充。注意根目录必须与 tokscale 上游 Rust 代码的读取方式保持一致不能凭猜测填写。第 3 步把 checkId 加入健康检查白名单每个上一步用到的checkId都必须出现在 clientHealth.js 的CLIENT_SOURCE_CHECK_IDS中保持字母序。这一步漏掉不会报错但会导致该客户端的整个 checks 数组被丢弃诊断面板从此失明。改完记得执行npm run sync:worker同步 Worker 副本。第 4 步补全名称归一化分支在 usage.js 的normalizeClientName()中添加映射分支把 tokscale 上报的各种写法归一到你的 id。例如 OpenClaw 家族就归并了openclaw/clawd/moltbot等多个别名。第 5 步配置视觉呈现与图标在 vendorPresentation.js 的VENDOR_PRESENTATION中按目录顺序添加品牌color再按约定放置图标资产assets/icons/ 下的id.svg界面图标.github/assets/tools-icon/ 下的id.pngREADME 展示图图表配色、外观选择器、托盘图案全部从这张表派生无需额外注册。第 6 步通过 Tokscale Token 契约测试每个由 tokscale 解析的客户端都需要一个代表会话进入 verify-vendored-tokscale.js 的TOKEN_CONTRACT_CASES校验 JSON 分桶与归一化总数是否一致——重点确认output是否包含 reasoning、reasoning 是否叠加计费。缺少用例时tokscaleTokenContracts.test.js 会直接失败。第 7 步更新文档与示例修改README.md及各语言翻译README.*.md中的支持工具表格并补充.env.example。各语言正文中的工具数量必须与表格一致否则 readmeConsistency.test.js 报错。第 8 步更新守卫测试并验证把新 id 加入 clientTracking.test.js 的期望列表和 clientCatalog.test.js 的固定 CSV它们守护持久化设置请谨慎更新最后运行测试套件确认全绿。避坑指南三条分区不变量定向监听targeted watch以客户端 id 为正确性边界监听侧按 id 决定改动的路径归谁统计侧按 id 决定tokscale 的数据行归谁。两条方向必须对齐clientPartitionInvariants.test.js 会强制校验id 必须是normalizeClientName()的不动点——否则一次定向监听扫描会清零该客户端分区向月度/累计统计注入负增量每个 tokscale 别名必须归一回父 id——例如antigravity-cli归一到antigravity否则定向扫描会漏掉别名数据过滤器永远不能输出synthetic——它会使 tokscale 启用所有客户端定向扫描退化为全量扫描数字正确但失去性能收益。可选扩展什么时候需要更多文件本地解析适配器工具数据无法被 tokscale 解析时在 src/shared/providers/ 下新建id/目录并在目录中登记locallyParsed: true会话元数据扫描无法回答的信息如会话标题、实时上下文 Token在 sessionMetadata.js 中补一条自同步客户端仅 cursor / antigravity 这类需要主动拉取缓存的工具才加入SELF_SYNCED_CLIENTS本地解析型不要加入Provider 笔记数据源有非显而易见的回退或安全边界时按 docs/providers/ 的规范撰写一篇笔记如 zed.md。验证清单提交前逐项确认全部完成后依次核对node --test tests/shared/clientTracking.test.js通过node --test tests/shared/clientCatalog.test.js通过node --test tests/shared/tokscaleTokenContracts.test.js通过诊断面板能看到新客户端的来源根目录状态为 detected设置列表、README 表格、托盘图标三处均出现新工具接入完成后你的 AI 工具的 Token 用量就会像 Claude Code、Codex 一样实时出现在仪表盘、菜单栏与多设备同步的统计中。祝开发顺利【免费下载链接】token-monitorLocal-first desktop widget for tracking token usage, costs, and limits across 43 AI coding tools—including Claude Code, Codex, Cursor, OpenCode, OpenClaw, and more—with multi-device sync.项目地址: https://gitcode.com/gh_mirrors/tok/token-monitor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考