tokenusage-cli 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. package/CHANGELOG.md +39 -19
  2. package/LICENSE +22 -22
  3. package/README.md +94 -94
  4. package/THIRD_PARTY_NOTICES.md +140 -140
  5. package/bin/tokenusage.js +69 -69
  6. package/package.json +59 -59
  7. package/src/cli.js +146 -134
  8. package/src/commands/device-login.js +205 -205
  9. package/src/commands/diagnostics.js +38 -38
  10. package/src/commands/doctor.js +110 -110
  11. package/src/commands/init.js +2484 -2436
  12. package/src/commands/pause.js +77 -0
  13. package/src/commands/sessions.js +29 -29
  14. package/src/commands/status.js +1758 -1747
  15. package/src/commands/sync.js +8048 -7934
  16. package/src/commands/uninstall.js +322 -312
  17. package/src/lib/account-usage-dedup.js +267 -267
  18. package/src/lib/antigravity-paths.js +48 -48
  19. package/src/lib/ark-agent-plan-limits.js +438 -438
  20. package/src/lib/ark-coding-plan-limits.js +537 -537
  21. package/src/lib/async-queue-reader.js +138 -138
  22. package/src/lib/atomic-json.js +27 -27
  23. package/src/lib/bearer-token.js +11 -11
  24. package/src/lib/categorizer-utils.js +232 -232
  25. package/src/lib/claude-categorizer.js +1343 -1343
  26. package/src/lib/claude-config.js +279 -279
  27. package/src/lib/claude-user-identity.js +56 -56
  28. package/src/lib/cli-ui.js +179 -179
  29. package/src/lib/cloud-account.js +541 -541
  30. package/src/lib/cloud-device-token.js +141 -141
  31. package/src/lib/cloud-sync-prefs.js +14 -14
  32. package/src/lib/cloud-usage-reset.js +115 -115
  33. package/src/lib/codex-config.js +595 -595
  34. package/src/lib/codex-context-breakdown.js +806 -806
  35. package/src/lib/codex-model-attribution.js +128 -128
  36. package/src/lib/codex-rollout-parser.js +1471 -1471
  37. package/src/lib/codex-service-tier.js +49 -49
  38. package/src/lib/codex-token-refresh.js +140 -140
  39. package/src/lib/codex-token-usage.js +195 -195
  40. package/src/lib/codex-usage-record.js +195 -195
  41. package/src/lib/collection-pause.js +77 -0
  42. package/src/lib/command-runner.js +313 -313
  43. package/src/lib/commandcode-limits.js +317 -317
  44. package/src/lib/context-health.js +124 -124
  45. package/src/lib/cursor-config.js +605 -605
  46. package/src/lib/cursor-store.js +1918 -1918
  47. package/src/lib/debug-flags.js +7 -7
  48. package/src/lib/devin-limits.js +249 -249
  49. package/src/lib/devin-usage.js +212 -212
  50. package/src/lib/diagnostics.js +383 -383
  51. package/src/lib/doctor.js +385 -385
  52. package/src/lib/dumate.js +95 -95
  53. package/src/lib/fs.js +455 -455
  54. package/src/lib/function-url.js +14 -14
  55. package/src/lib/gemini-config.js +291 -291
  56. package/src/lib/git-outcomes.js +243 -243
  57. package/src/lib/grok-context-breakdown.js +890 -890
  58. package/src/lib/grok-hook.js +360 -360
  59. package/src/lib/grok-limits.js +865 -865
  60. package/src/lib/grok-usage.js +98 -98
  61. package/src/lib/heatmap-compact.js +114 -114
  62. package/src/lib/ingest-sanitize.js +41 -41
  63. package/src/lib/init-flow.js +42 -42
  64. package/src/lib/install-resolver.js +170 -170
  65. package/src/lib/jsonl-lines.js +134 -134
  66. package/src/lib/kimi-model-repair.js +173 -173
  67. package/src/lib/kimi-profile.js +61 -61
  68. package/src/lib/kimi-session.js +216 -216
  69. package/src/lib/local-api.js +3588 -3588
  70. package/src/lib/machine-id.js +238 -238
  71. package/src/lib/multi-install-parser.js +113 -113
  72. package/src/lib/notify-command.js +38 -38
  73. package/src/lib/omp-hook.js +589 -589
  74. package/src/lib/openclaw-cli.js +104 -104
  75. package/src/lib/openclaw-hook.js +375 -375
  76. package/src/lib/openclaw-session-plugin.js +560 -560
  77. package/src/lib/opencode-config.js +121 -121
  78. package/src/lib/opencode-go-limits.js +807 -807
  79. package/src/lib/outcomes-engine.js +253 -253
  80. package/src/lib/passive-mode.js +219 -219
  81. package/src/lib/pet-packages.js +722 -722
  82. package/src/lib/pricing/curated-overrides.json +822 -822
  83. package/src/lib/pricing/index.js +379 -379
  84. package/src/lib/pricing/litellm-fetcher.js +172 -172
  85. package/src/lib/pricing/matcher.js +456 -456
  86. package/src/lib/pricing/seed-snapshot.json +1 -1
  87. package/src/lib/progress.js +76 -76
  88. package/src/lib/project-usage-purge.js +117 -117
  89. package/src/lib/prompt.js +24 -24
  90. package/src/lib/provider-status.js +104 -104
  91. package/src/lib/proxy-env.js +489 -489
  92. package/src/lib/proxy-settings.js +163 -163
  93. package/src/lib/qoder-cn-cli-limits.js +119 -119
  94. package/src/lib/qoder-limits.js +880 -880
  95. package/src/lib/quiet-warnings.js +26 -26
  96. package/src/lib/rollout.js +26005 -25966
  97. package/src/lib/runtime-config.js +9 -4
  98. package/src/lib/scan-roots.js +277 -277
  99. package/src/lib/scheduled-task.js +145 -0
  100. package/src/lib/sentry.js +231 -231
  101. package/src/lib/session-analytics.js +2972 -2972
  102. package/src/lib/session-performance.js +237 -237
  103. package/src/lib/session-upload.js +379 -379
  104. package/src/lib/skill-usage.js +267 -267
  105. package/src/lib/skills-manager.js +1591 -1591
  106. package/src/lib/source-metadata.js +48 -48
  107. package/src/lib/sqlite-reader.js +215 -215
  108. package/src/lib/star-cta.js +73 -73
  109. package/src/lib/subscription-manager.js +293 -293
  110. package/src/lib/subscriptions.js +508 -508
  111. package/src/lib/sync-report.js +138 -0
  112. package/src/lib/telemetry.js +193 -193
  113. package/src/lib/tracker-paths.js +16 -16
  114. package/src/lib/trae-cn-config.js +548 -548
  115. package/src/lib/trae-db.js +127 -127
  116. package/src/lib/trae-snapshot.js +230 -230
  117. package/src/lib/trae-sqlite.js +143 -143
  118. package/src/lib/trae-usage.js +121 -121
  119. package/src/lib/upload-queue.js +134 -134
  120. package/src/lib/upload-throttle.js +171 -171
  121. package/src/lib/usage-limits.js +4552 -4552
  122. package/src/lib/wrapped-aggregator.js +236 -236
  123. package/src/lib/wsl-probe.js +281 -281
  124. package/src/lib/zcode-limits.js +1172 -1172
  125. package/src/lib/zcode-reset-credits.js +66 -66
  126. package/test/audit-fixes.test.js +200 -0
  127. package/test/cli-smoke.test.js +53 -53
  128. package/test/collection-controls.test.js +181 -0
  129. package/test/ingest-sanitize.test.js +162 -162
  130. package/test/quiet-warnings.test.js +53 -53
  131. package/test/session-upload.test.js +427 -427
package/CHANGELOG.md CHANGED
@@ -1,19 +1,39 @@
1
- # Changelog
2
-
3
- 本包(`tokenusage-cli`)的用户可见变更记录。发版时在顶部新增一节,
4
- `## <版本号>` 行会被 release workflow 取作 GitHub Release 正文。
5
-
6
- ## 0.1.0
7
-
8
- 首个公开发布版本:TokenTracker CLI 采集端 fork,重接到 token-usage 契约
9
- (`docs/cli-contract.md`)。
10
-
11
- - 设备流配对(`device-login`)、`init`、`sync`(含 `--watch` / `--drain`)、
12
- `status`、`sessions`、`doctor`、`diagnostics`、`uninstall`
13
- - 会话上传走隐私白名单:只传聚合 token 数字,标题 / 路径 / 正文永不出本机
14
- - 上传链路防毒行硬化:契约非法的用量桶 / 账户会话状态在出批前丢弃或修正,
15
- 而不是让 ingest 边缘整批 400、队头永久停摆;Grok ACP 小数计数器解析期取整;
16
- 会话 ID 校验对齐服务端的完整 Unicode Cc 控制字符范围
17
- - 请求日志降噪:`node:sqlite` 每次加载都打印的 ExperimentalWarning 不再
18
- 混入重定向的同步日志
19
- - 要求 Node ≥ 22.19(undici 8 的引擎下限;undici 仅用于代理支持)
1
+ # Changelog
2
+
3
+ 本包(`tokenusage-cli`)的用户可见变更记录。发版时在顶部新增一节,
4
+ `## <版本号>` 行会被 release workflow 取作 GitHub Release 正文。
5
+
6
+ ## 0.2.0
7
+
8
+ 采集控制与运行记录:采集器从此可暂停、可审计。
9
+
10
+ - 新增 `tokenusage pause` / `resume`:一键暂停/恢复自动采集。暂停期间
11
+ `sync --auto` / `--watch`(含通知触发)静默退出,手动 `tokenusage sync`
12
+ 不受影响;`status` 显示当前采集状态。
13
+ - `init` 接管 Windows 计划任务注册:每小时任务由 init 创建(默认经 VBS
14
+ 隐藏窗口运行,不再弹 conhost 黑框;`--no-task` 可跳过);pause/resume
15
+ 顺势启停任务;`uninstall` 一并清理任务与脚本。
16
+ - 同步日志改为滚动文件(`~/.tokenusage/tracker/logs/sync.log`,1 MiB 轮转
17
+ 一代),不再依赖注册时的 `>>` 重定向。
18
+ - 每轮 sync 结束后向服务端上报一条运行记录(时间、触发方式、结果、耗时、
19
+ 上报量),仪表盘新增"采集记录"页;空跑也上报,作为采集器心跳。上报为
20
+ 尽力而为,失败只记本地日志,绝不影响用量数据采集;不想上报可在 init 时
21
+ `--run-report=off` 关闭。
22
+ - 正确性修复:zcode 恢复行补齐 billable/cost 字段;含 `|` 的模型名不再破坏
23
+ 用量桶键的往返解析;OpenCode 负 delta 不再产生负计数;`TOKENUSAGE_*`
24
+ 环境变量优先于旧 `INSFORGE_*` 名(旧名保留兼容);移除 init 中的死常量。
25
+
26
+ ## 0.1.0
27
+
28
+ 首个公开发布版本:TokenTracker CLI 采集端 fork,重接到 token-usage 契约
29
+ (`docs/cli-contract.md`)。
30
+
31
+ - 设备流配对(`device-login`)、`init`、`sync`(含 `--watch` / `--drain`)、
32
+ `status`、`sessions`、`doctor`、`diagnostics`、`uninstall`
33
+ - 会话上传走隐私白名单:只传聚合 token 数字,标题 / 路径 / 正文永不出本机
34
+ - 上传链路防毒行硬化:契约非法的用量桶 / 账户会话状态在出批前丢弃或修正,
35
+ 而不是让 ingest 边缘整批 400、队头永久停摆;Grok ACP 小数计数器解析期取整;
36
+ 会话 ID 校验对齐服务端的完整 Unicode Cc 控制字符范围
37
+ - 请求日志降噪:`node:sqlite` 每次加载都打印的 ExperimentalWarning 不再
38
+ 混入重定向的同步日志
39
+ - 要求 Node ≥ 22.19(undici 8 的引擎下限;undici 仅用于代理支持)
package/LICENSE CHANGED
@@ -1,22 +1,22 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 xiufengsun (TokenTracker upstream)
4
- Copyright (c) 2026 baiwumm (token-usage CLI modifications)
5
-
6
- Permission is hereby granted, free of charge, to any person obtaining a copy
7
- of this software and associated documentation files (the "Software"), to deal
8
- in the Software without restriction, including without limitation the rights
9
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
- copies of the Software, and to permit persons to whom the Software is
11
- furnished to do so, subject to the following conditions:
12
-
13
- The above copyright notice and this permission notice shall be included in all
14
- copies or substantial portions of the Software.
15
-
16
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 xiufengsun (TokenTracker upstream)
4
+ Copyright (c) 2026 baiwumm (token-usage CLI modifications)
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
package/README.md CHANGED
@@ -1,94 +1,94 @@
1
- # tokenusage-cli
2
-
3
- 自托管 AI 编码 token 用量采集器,为 [token-usage](https://github.com/baiwumm/token-usage)(自托管仪表盘)上报数据。fork 自 [TokenTracker](https://github.com/xiufengsun/TokenTracker)(MIT,见 `LICENSE` 与 `THIRD_PARTY_NOTICES.md`),指向 token-usage 契约(`docs/cli-contract.md`)。
4
-
5
- > 运行要求:Node ≥ 22.19(由上传依赖 undici 8 的引擎下限决定)。
6
-
7
- ## 快速开始(三步)
8
-
9
- ```bash
10
- # 1) 初始化本地扫描(配置扫描根、安装各工具的用量 hook)
11
- tokenusage init
12
-
13
- # 2) 配对:输出一个 user_code,浏览器打开提示的链接批准
14
- tokenusage device-login
15
- # → https://<你的站点>/device?user_code=XXXX-XXXX
16
- # → 批准后本机自动拿到设备令牌(码 15 分钟内有效)
17
-
18
- # 3) 上报
19
- tokenusage sync # 手动一轮:解析 → 入队 → 上传
20
- tokenusage sync --drain # 首次/积压补传(更大的批处理预算)
21
- ```
22
-
23
- 完成。之后随时跑 `tokenusage sync`,或用 `--watch` 常驻自动上报(见下)。
24
-
25
- **谁批准配对?** 批准者就是配对时登录站点的那个账号——设备与其全部数据绑定到该账号,账号之间数据完全隔离。自托管用户批准自己的设备即可;站点管理员不需要、也无法替别人审批。陌生人可以对公开站点发起配对码,但没有账号就批不了(注册邀请制 / `token_allowed_emails` 白名单),码 15 分钟自动过期。
26
-
27
- ## 命令
28
-
29
- | 命令 | 说明 |
30
- |---|---|
31
- | `tokenusage init` | 本地初始化(扫描根配置、各工具 hook 安装)。不含配对 |
32
- | `tokenusage device-login` | 设备流配对:输出 `user_code`,在站点 `/device` 页批准后本机拿到设备令牌 |
33
- | `tokenusage sync` | 解析本地 AI 工具日志 → 上报小时桶 + 会话元数据 |
34
- | `tokenusage sync --watch` | 常驻模式,默认每 15 分钟增量一轮(`--interval <ms>` 可调,≥60000) |
35
- | `tokenusage sync --no-sessions` | 只上报小时桶,跳过会话元数据 |
36
- | `tokenusage sync --drain` | 补传模式:更大的批处理预算,适合首次接入/长期积压 |
37
- | `tokenusage status` | 本地状态:Base URL、令牌、队列积压、最近解析/上传时间 |
38
- | `tokenusage doctor` | 体检(运行时 / 网络 / 各工具配置),`--json` 输出 |
39
- | `tokenusage diagnostics` | 诊断信息导出 |
40
- | `tokenusage sessions` | 本地导出会话分析(JSON/CSV,元数据级) |
41
- | `tokenusage uninstall [--purge]` | 移除 hook;`--purge` 连数据目录一起删 |
42
-
43
- 配置优先级:CLI 参数 > `~/.tokenusage/.../config.json` > 环境变量(`TOKENUSAGE_BASE_URL` 等)> 内置默认(你的部署地址 + 其公开 publishable key)。
44
-
45
- ## `sync --watch`:常驻自动上报
46
-
47
- ```bash
48
- tokenusage sync --watch # 默认每 15 分钟一轮
49
- tokenusage sync --watch --interval 300000 # 每 5 分钟一轮
50
- tokenusage sync --watch --interval 3600000 --no-sessions # 每小时,只传小时桶
51
- ```
52
-
53
- - `--interval` 毫秒,最小 60000(小于该值回落到默认 15 分钟——每轮至少要跑一次本地扫描,过密无意义)。
54
- - **停止**:在运行的终端 Ctrl+C 即可;`--watch` 只是前台进程,不注册任何系统计划任务/守护。随时终止都安全——队列与水位都已落盘,下次 `sync` 从断点继续。
55
- - 每轮增量:首轮解析全部历史日志(可能较慢),之后只重扫有变化的文件;上报侧队列 offset + 会话水位双断点,多轮之间不重不漏。
56
-
57
- ## 未配对时会发生什么
58
-
59
- CLI 未配对也能正常用,只是**降级为“只采集、不上报”**:
60
-
61
- - `sync` 照常解析并入队,上传步骤提示 `skipped (no device token)`;数据留在本地队列,**不会丢**——配对后下一次 `sync --drain` 自动补传全部积压。
62
- - `sync --auto`(hook 触发的静默档)静默等待令牌,按重试调度挂起。
63
- - `status` / `doctor` 正常运行,令牌缺失显示为 warn。
64
- - 服务端零暴露:没有配对令牌的请求一律 `401`,未配对机器读不到任何数据。
65
-
66
- 所以先装 CLI、后配站点(甚至先本地攒数据)是合法路径;配对完成那一刻,积压数据自动补传。
67
-
68
- ## 隐私边界
69
-
70
- 上报内容只有**聚合用量**:
71
-
72
- - 小时桶:每工具每小时六项 token 计数与模型名。
73
- - 会话元数据:`session_id`(厂商会话 UUID,或无 UUID 来源的本地稳定指纹)、来源、起止时间、项目 basename、token 拆分、每模型用量。
74
-
75
- **永不上传**:prompt / 助手正文 / 工具参数 / 命令输出 / diff / 会话标题 / 本地绝对路径 / resume 命令。测试(`test/session-upload.test.js`)用字段白名单锁定该边界。
76
-
77
- ## 数据目录
78
-
79
- `~/.tokenusage/`(`0700` 目录 + `0600` 文件):上传队列(`queue.jsonl` + offset)、会话分析 sidecar、`session-upload-watermarks.json`(增量水位)。与旧版 tokentracker CLI 的 `~/.tokentracker/` 互不干扰,迁移期两套 CLI 可在同一台机器共存。
80
-
81
- ## provider 支持面
82
-
83
- 解析器随上游全量保留(仅未配置对应工具时休眠不扫描):claude、codex、zcode、opencode、cursor、trae / trae-cn、grok、kimi、gemini、qoder、antigravity、openclaw 等。操作者实际启用面以 `tokenusage status` 为准;未使用的解析器不产生任何上传。
84
-
85
- 注:`cursor` / `trae-cn` 为账户级来源,会话元数据不会为其上传(服务端契约亦整段跳过)。
86
-
87
- ## 开发
88
-
89
- ```bash
90
- pnpm install # 仓库根
91
- pnpm --filter tokenusage-cli test
92
- ```
93
-
94
- 发布(npm)是操作者动作,本包 `private: true`。
1
+ # tokenusage-cli
2
+
3
+ 自托管 AI 编码 token 用量采集器,为 [token-usage](https://github.com/baiwumm/token-usage)(自托管仪表盘)上报数据。fork 自 [TokenTracker](https://github.com/xiufengsun/TokenTracker)(MIT,见 `LICENSE` 与 `THIRD_PARTY_NOTICES.md`),指向 token-usage 契约(`docs/cli-contract.md`)。
4
+
5
+ > 运行要求:Node ≥ 22.19(由上传依赖 undici 8 的引擎下限决定)。
6
+
7
+ ## 快速开始(三步)
8
+
9
+ ```bash
10
+ # 1) 初始化本地扫描(配置扫描根、安装各工具的用量 hook)
11
+ tokenusage init
12
+
13
+ # 2) 配对:输出一个 user_code,浏览器打开提示的链接批准
14
+ tokenusage device-login
15
+ # → https://<你的站点>/device?user_code=XXXX-XXXX
16
+ # → 批准后本机自动拿到设备令牌(码 15 分钟内有效)
17
+
18
+ # 3) 上报
19
+ tokenusage sync # 手动一轮:解析 → 入队 → 上传
20
+ tokenusage sync --drain # 首次/积压补传(更大的批处理预算)
21
+ ```
22
+
23
+ 完成。之后随时跑 `tokenusage sync`,或用 `--watch` 常驻自动上报(见下)。
24
+
25
+ **谁批准配对?** 批准者就是配对时登录站点的那个账号——设备与其全部数据绑定到该账号,账号之间数据完全隔离。自托管用户批准自己的设备即可;站点管理员不需要、也无法替别人审批。陌生人可以对公开站点发起配对码,但没有账号就批不了(注册邀请制 / `token_allowed_emails` 白名单),码 15 分钟自动过期。
26
+
27
+ ## 命令
28
+
29
+ | 命令 | 说明 |
30
+ |---|---|
31
+ | `tokenusage init` | 本地初始化(扫描根配置、各工具 hook 安装)。不含配对 |
32
+ | `tokenusage device-login` | 设备流配对:输出 `user_code`,在站点 `/device` 页批准后本机拿到设备令牌 |
33
+ | `tokenusage sync` | 解析本地 AI 工具日志 → 上报小时桶 + 会话元数据 |
34
+ | `tokenusage sync --watch` | 常驻模式,默认每 15 分钟增量一轮(`--interval <ms>` 可调,≥60000) |
35
+ | `tokenusage sync --no-sessions` | 只上报小时桶,跳过会话元数据 |
36
+ | `tokenusage sync --drain` | 补传模式:更大的批处理预算,适合首次接入/长期积压 |
37
+ | `tokenusage status` | 本地状态:Base URL、令牌、队列积压、最近解析/上传时间 |
38
+ | `tokenusage doctor` | 体检(运行时 / 网络 / 各工具配置),`--json` 输出 |
39
+ | `tokenusage diagnostics` | 诊断信息导出 |
40
+ | `tokenusage sessions` | 本地导出会话分析(JSON/CSV,元数据级) |
41
+ | `tokenusage uninstall [--purge]` | 移除 hook;`--purge` 连数据目录一起删 |
42
+
43
+ 配置优先级:CLI 参数 > `~/.tokenusage/.../config.json` > 环境变量(`TOKENUSAGE_BASE_URL` 等)> 内置默认(你的部署地址 + 其公开 publishable key)。
44
+
45
+ ## `sync --watch`:常驻自动上报
46
+
47
+ ```bash
48
+ tokenusage sync --watch # 默认每 15 分钟一轮
49
+ tokenusage sync --watch --interval 300000 # 每 5 分钟一轮
50
+ tokenusage sync --watch --interval 3600000 --no-sessions # 每小时,只传小时桶
51
+ ```
52
+
53
+ - `--interval` 毫秒,最小 60000(小于该值回落到默认 15 分钟——每轮至少要跑一次本地扫描,过密无意义)。
54
+ - **停止**:在运行的终端 Ctrl+C 即可;`--watch` 只是前台进程,不注册任何系统计划任务/守护。随时终止都安全——队列与水位都已落盘,下次 `sync` 从断点继续。
55
+ - 每轮增量:首轮解析全部历史日志(可能较慢),之后只重扫有变化的文件;上报侧队列 offset + 会话水位双断点,多轮之间不重不漏。
56
+
57
+ ## 未配对时会发生什么
58
+
59
+ CLI 未配对也能正常用,只是**降级为“只采集、不上报”**:
60
+
61
+ - `sync` 照常解析并入队,上传步骤提示 `skipped (no device token)`;数据留在本地队列,**不会丢**——配对后下一次 `sync --drain` 自动补传全部积压。
62
+ - `sync --auto`(hook 触发的静默档)静默等待令牌,按重试调度挂起。
63
+ - `status` / `doctor` 正常运行,令牌缺失显示为 warn。
64
+ - 服务端零暴露:没有配对令牌的请求一律 `401`,未配对机器读不到任何数据。
65
+
66
+ 所以先装 CLI、后配站点(甚至先本地攒数据)是合法路径;配对完成那一刻,积压数据自动补传。
67
+
68
+ ## 隐私边界
69
+
70
+ 上报内容只有**聚合用量**:
71
+
72
+ - 小时桶:每工具每小时六项 token 计数与模型名。
73
+ - 会话元数据:`session_id`(厂商会话 UUID,或无 UUID 来源的本地稳定指纹)、来源、起止时间、项目 basename、token 拆分、每模型用量。
74
+
75
+ **永不上传**:prompt / 助手正文 / 工具参数 / 命令输出 / diff / 会话标题 / 本地绝对路径 / resume 命令。测试(`test/session-upload.test.js`)用字段白名单锁定该边界。
76
+
77
+ ## 数据目录
78
+
79
+ `~/.tokenusage/`(`0700` 目录 + `0600` 文件):上传队列(`queue.jsonl` + offset)、会话分析 sidecar、`session-upload-watermarks.json`(增量水位)。与旧版 tokentracker CLI 的 `~/.tokentracker/` 互不干扰,迁移期两套 CLI 可在同一台机器共存。
80
+
81
+ ## provider 支持面
82
+
83
+ 解析器随上游全量保留(仅未配置对应工具时休眠不扫描):claude、codex、zcode、opencode、cursor、trae / trae-cn、grok、kimi、gemini、qoder、antigravity、openclaw 等。操作者实际启用面以 `tokenusage status` 为准;未使用的解析器不产生任何上传。
84
+
85
+ 注:`cursor` / `trae-cn` 为账户级来源,会话元数据不会为其上传(服务端契约亦整段跳过)。
86
+
87
+ ## 开发
88
+
89
+ ```bash
90
+ pnpm install # 仓库根
91
+ pnpm --filter tokenusage-cli test
92
+ ```
93
+
94
+ 发布(npm)是操作者动作,本包 `private: true`。
@@ -1,140 +1,140 @@
1
- # Third-Party Notices
2
-
3
- This project includes third-party assets and code. The following notices apply.
4
-
5
- ## TokenTracker (upstream)
6
-
7
- The `tokenusage` CLI in this package is forked from
8
- [TokenTracker](https://github.com/xiufengsun/TokenTracker) (MIT License,
9
- Copyright (c) xiufengsun). Substantial portions of `src/` originate from the
10
- upstream repository and were then modified for the token-usage contract
11
- (`docs/cli-contract.md` in the repository root). The upstream MIT license text
12
- and copyright notice are preserved in this package's `LICENSE` file.
13
-
14
- ## RunCat menu bar cat frames
15
-
16
- The running-cat animation frames used by the macOS menu bar icon
17
- (`TokenTrackerBar/TokenTrackerBar/Assets.xcassets/RunnerCat0…4.imageset`)
18
- are from [menubar_runcat](https://github.com/Kyome22/menubar_runcat)
19
- by Takuto Nakamura (Kyome22).
20
-
21
- Copyright © 2019 Takuto Nakamura
22
-
23
- Licensed under the Apache License, Version 2.0 (the "License");
24
- you may not use these files except in compliance with the License.
25
- You may obtain a copy of the License at
26
-
27
- http://www.apache.org/licenses/LICENSE-2.0
28
-
29
- Unless required by applicable law or agreed to in writing, software
30
- distributed under the License is distributed on an "AS IS" BASIS,
31
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
32
- See the License for the specific language governing permissions and
33
- limitations under the License.
34
-
35
- ## Bot companion morphing engine
36
-
37
- The vector morphing engine behind the `bot` pet character and its menu bar icon
38
- (`dashboard/src/lib/bot/`, and the frame data generated from it by
39
- `scripts/gen-bot-frames.cjs`) is from [bloub](https://github.com/jeremy-prt/bloub)
40
- by Jérémy Perret, vendored unmodified at commit
41
- [`b4bb3c1b5f93`](https://github.com/jeremy-prt/bloub/tree/b4bb3c1b5f93c7b87a2e8d620f667c4093d97749).
42
-
43
- Note when re-vendoring: `dashboard/src/lib/bot/README.md` is ours, not upstream's, and
44
- `decor.ts` / `skins.ts` are listed in `scripts/ops/ui-hardcode-baseline.json`, so a
45
- refresh needs that file re-copied and the baseline regenerated.
46
-
47
- Copyright © 2026 Jérémy Perret
48
-
49
- Permission is hereby granted, free of charge, to any person obtaining a copy
50
- of this software and associated documentation files (the "Software"), to deal
51
- in the Software without restriction, including without limitation the rights
52
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
53
- copies of the Software, and to permit persons to whom the Software is
54
- furnished to do so, subject to the following conditions:
55
-
56
- The above copyright notice and this permission notice shall be included in all
57
- copies or substantial portions of the Software.
58
-
59
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
60
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
61
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
62
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
63
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
64
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
65
- SOFTWARE.
66
-
67
- ## Devin brand mark
68
-
69
- `dashboard/public/brand-logos/devin.svg` is a monochrome vector trace of the
70
- official Devin "nodes" mark published by Cognition at
71
- `https://app.devin.ai/assets/pwa/apple-touch-icon.png` (also
72
- `https://app.devin.ai/assets/pwa/pwa-icon-192.png`). The Devin name and logo
73
- are trademarks of Cognition; the mark is bundled solely to identify the Devin
74
- CLI source and subscription quota in the dashboard, recoloured to `currentColor` like the
75
- other provider marks.
76
-
77
- ## Hairline line figures
78
-
79
- The Cloud plan page uses [Hairline](https://github.com/lucasmarkes/hairline) v0.5.0 by Lucas Marques.
80
-
81
- MIT License
82
-
83
- Copyright (c) 2026 Lucas Marques
84
-
85
- Permission is hereby granted, free of charge, to any person obtaining a copy
86
- of this software and associated documentation files (the "Software"), to deal
87
- in the Software without restriction, including without limitation the rights
88
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
89
- copies of the Software, and to permit persons to whom the Software is
90
- furnished to do so, subject to the following conditions:
91
-
92
- The above copyright notice and this permission notice shall be included in all
93
- copies or substantial portions of the Software.
94
-
95
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
96
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
97
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
98
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
99
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
100
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
101
- SOFTWARE.
102
-
103
- ## React Bits ElectricLogo
104
-
105
- The dark Cloud plan artwork adapts the user-provided React Bits ElectricLogo by David Haz.
106
- Source: https://reactbits.dev/animations/electric-logo
107
- Vendored integration: dashboard/vendor/react-bits/.
108
-
109
- MIT + Commons Clause License Condition v1.0
110
-
111
- Copyright (c) 2026 David Haz
112
-
113
- Permission is hereby granted, free of charge, to any person obtaining a copy
114
- of this software and associated documentation files (the "Software"), to deal
115
- in the Software without restriction, including without limitation the rights
116
- to use, copy, modify, merge, publish, and distribute the Software **as part of an application, website, or product**, subject to the following conditions:
117
-
118
- The above copyright notice and this permission notice shall be included in all
119
- copies or substantial portions of the Software.
120
-
121
- ## Commons Clause Restriction
122
-
123
- You may use this Software, including for any commercial purpose, **so long as you do not sell, sublicense, or redistribute the components themselves-whether alone, in a bundle, or as a ported version.**
124
-
125
- ## No Warranty
126
-
127
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
128
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
129
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
130
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
131
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
132
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
133
- SOFTWARE.
134
-
135
-
136
- ## OGL
137
-
138
- The ElectricLogo renderer uses OGL 1.0.11 by Nathan Gordon.
139
- Source: https://github.com/oframe/ogl
140
- License: Unlicense (public domain dedication), as declared in the OGL package metadata.
1
+ # Third-Party Notices
2
+
3
+ This project includes third-party assets and code. The following notices apply.
4
+
5
+ ## TokenTracker (upstream)
6
+
7
+ The `tokenusage` CLI in this package is forked from
8
+ [TokenTracker](https://github.com/xiufengsun/TokenTracker) (MIT License,
9
+ Copyright (c) xiufengsun). Substantial portions of `src/` originate from the
10
+ upstream repository and were then modified for the token-usage contract
11
+ (`docs/cli-contract.md` in the repository root). The upstream MIT license text
12
+ and copyright notice are preserved in this package's `LICENSE` file.
13
+
14
+ ## RunCat menu bar cat frames
15
+
16
+ The running-cat animation frames used by the macOS menu bar icon
17
+ (`TokenTrackerBar/TokenTrackerBar/Assets.xcassets/RunnerCat0…4.imageset`)
18
+ are from [menubar_runcat](https://github.com/Kyome22/menubar_runcat)
19
+ by Takuto Nakamura (Kyome22).
20
+
21
+ Copyright © 2019 Takuto Nakamura
22
+
23
+ Licensed under the Apache License, Version 2.0 (the "License");
24
+ you may not use these files except in compliance with the License.
25
+ You may obtain a copy of the License at
26
+
27
+ http://www.apache.org/licenses/LICENSE-2.0
28
+
29
+ Unless required by applicable law or agreed to in writing, software
30
+ distributed under the License is distributed on an "AS IS" BASIS,
31
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
32
+ See the License for the specific language governing permissions and
33
+ limitations under the License.
34
+
35
+ ## Bot companion morphing engine
36
+
37
+ The vector morphing engine behind the `bot` pet character and its menu bar icon
38
+ (`dashboard/src/lib/bot/`, and the frame data generated from it by
39
+ `scripts/gen-bot-frames.cjs`) is from [bloub](https://github.com/jeremy-prt/bloub)
40
+ by Jérémy Perret, vendored unmodified at commit
41
+ [`b4bb3c1b5f93`](https://github.com/jeremy-prt/bloub/tree/b4bb3c1b5f93c7b87a2e8d620f667c4093d97749).
42
+
43
+ Note when re-vendoring: `dashboard/src/lib/bot/README.md` is ours, not upstream's, and
44
+ `decor.ts` / `skins.ts` are listed in `scripts/ops/ui-hardcode-baseline.json`, so a
45
+ refresh needs that file re-copied and the baseline regenerated.
46
+
47
+ Copyright © 2026 Jérémy Perret
48
+
49
+ Permission is hereby granted, free of charge, to any person obtaining a copy
50
+ of this software and associated documentation files (the "Software"), to deal
51
+ in the Software without restriction, including without limitation the rights
52
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
53
+ copies of the Software, and to permit persons to whom the Software is
54
+ furnished to do so, subject to the following conditions:
55
+
56
+ The above copyright notice and this permission notice shall be included in all
57
+ copies or substantial portions of the Software.
58
+
59
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
60
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
61
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
62
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
63
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
64
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
65
+ SOFTWARE.
66
+
67
+ ## Devin brand mark
68
+
69
+ `dashboard/public/brand-logos/devin.svg` is a monochrome vector trace of the
70
+ official Devin "nodes" mark published by Cognition at
71
+ `https://app.devin.ai/assets/pwa/apple-touch-icon.png` (also
72
+ `https://app.devin.ai/assets/pwa/pwa-icon-192.png`). The Devin name and logo
73
+ are trademarks of Cognition; the mark is bundled solely to identify the Devin
74
+ CLI source and subscription quota in the dashboard, recoloured to `currentColor` like the
75
+ other provider marks.
76
+
77
+ ## Hairline line figures
78
+
79
+ The Cloud plan page uses [Hairline](https://github.com/lucasmarkes/hairline) v0.5.0 by Lucas Marques.
80
+
81
+ MIT License
82
+
83
+ Copyright (c) 2026 Lucas Marques
84
+
85
+ Permission is hereby granted, free of charge, to any person obtaining a copy
86
+ of this software and associated documentation files (the "Software"), to deal
87
+ in the Software without restriction, including without limitation the rights
88
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
89
+ copies of the Software, and to permit persons to whom the Software is
90
+ furnished to do so, subject to the following conditions:
91
+
92
+ The above copyright notice and this permission notice shall be included in all
93
+ copies or substantial portions of the Software.
94
+
95
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
96
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
97
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
98
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
99
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
100
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
101
+ SOFTWARE.
102
+
103
+ ## React Bits ElectricLogo
104
+
105
+ The dark Cloud plan artwork adapts the user-provided React Bits ElectricLogo by David Haz.
106
+ Source: https://reactbits.dev/animations/electric-logo
107
+ Vendored integration: dashboard/vendor/react-bits/.
108
+
109
+ MIT + Commons Clause License Condition v1.0
110
+
111
+ Copyright (c) 2026 David Haz
112
+
113
+ Permission is hereby granted, free of charge, to any person obtaining a copy
114
+ of this software and associated documentation files (the "Software"), to deal
115
+ in the Software without restriction, including without limitation the rights
116
+ to use, copy, modify, merge, publish, and distribute the Software **as part of an application, website, or product**, subject to the following conditions:
117
+
118
+ The above copyright notice and this permission notice shall be included in all
119
+ copies or substantial portions of the Software.
120
+
121
+ ## Commons Clause Restriction
122
+
123
+ You may use this Software, including for any commercial purpose, **so long as you do not sell, sublicense, or redistribute the components themselves-whether alone, in a bundle, or as a ported version.**
124
+
125
+ ## No Warranty
126
+
127
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
128
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
129
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
130
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
131
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
132
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
133
+ SOFTWARE.
134
+
135
+
136
+ ## OGL
137
+
138
+ The ElectricLogo renderer uses OGL 1.0.11 by Nathan Gordon.
139
+ Source: https://github.com/oframe/ogl
140
+ License: Unlicense (public domain dedication), as declared in the OGL package metadata.