tokenusage-cli 0.2.6 → 0.4.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 (53) hide show
  1. package/CHANGELOG.md +70 -0
  2. package/README.md +52 -11
  3. package/bin/tokenusage.js +14 -2
  4. package/package.json +1 -2
  5. package/src/cli.js +325 -78
  6. package/src/commands/device-login.js +3 -3
  7. package/src/commands/init.js +343 -153
  8. package/src/commands/pause.js +11 -23
  9. package/src/commands/reconcile.js +485 -0
  10. package/src/commands/sessions.js +57 -14
  11. package/src/commands/status.js +5 -2
  12. package/src/commands/sync.js +77 -18
  13. package/src/commands/uninstall.js +6 -9
  14. package/src/commands/upload.js +147 -0
  15. package/src/lib/cli-errors.js +33 -0
  16. package/src/lib/cli-ui.js +93 -0
  17. package/src/lib/ingest-sanitize.js +9 -0
  18. package/src/lib/queue-row-normalize.js +55 -0
  19. package/src/lib/rollout.js +39 -2
  20. package/src/lib/scheduled-task.js +597 -75
  21. package/src/lib/session-analytics.js +171 -3
  22. package/src/lib/session-upload.js +6 -0
  23. package/src/lib/sync-report.js +8 -2
  24. package/src/lib/trae-db.js +6 -1
  25. package/src/lib/antigravity-paths.js +0 -48
  26. package/src/lib/async-queue-reader.js +0 -138
  27. package/src/lib/atomic-json.js +0 -27
  28. package/src/lib/bearer-token.js +0 -11
  29. package/src/lib/cloud-account.js +0 -541
  30. package/src/lib/codex-context-breakdown.js +0 -806
  31. package/src/lib/context-health.js +0 -124
  32. package/src/lib/grok-context-breakdown.js +0 -890
  33. package/src/lib/heatmap-compact.js +0 -114
  34. package/src/lib/local-api.js +0 -3574
  35. package/src/lib/outcomes-engine.js +0 -253
  36. package/src/lib/pet-packages.js +0 -722
  37. package/src/lib/skill-usage.js +0 -267
  38. package/src/lib/skills-manager.js +0 -1591
  39. package/src/lib/source-metadata.js +0 -48
  40. package/src/lib/subscription-manager.js +0 -293
  41. package/src/lib/wrapped-aggregator.js +0 -236
  42. package/test/audit-fixes.test.js +0 -249
  43. package/test/branding.test.js +0 -24
  44. package/test/cli-options.test.js +0 -43
  45. package/test/cli-smoke.test.js +0 -53
  46. package/test/cli-ui.test.js +0 -47
  47. package/test/collection-controls.test.js +0 -255
  48. package/test/ingest-sanitize.test.js +0 -162
  49. package/test/packaging.test.js +0 -107
  50. package/test/quiet-warnings.test.js +0 -53
  51. package/test/runtime-copy.test.js +0 -111
  52. package/test/session-upload.test.js +0 -427
  53. package/test/zstd-native.test.js +0 -36
package/CHANGELOG.md CHANGED
@@ -3,6 +3,76 @@
3
3
  本包(`tokenusage-cli`)的用户可见变更记录。发版时在顶部新增一节,
4
4
  `## <版本号>` 行会被 release workflow 取作 GitHub Release 正文。
5
5
 
6
+ ## 0.4.0
7
+
8
+ 2026-11-01。错误提示更友好(一行 `Error:` + `Hint:` 且不再刷堆栈),帮助信息改为
9
+ 命令表驱动,新增 `upload` / `reconcile` 两条命令,`init` 可按工具挑选要接管的集成,
10
+ 自动采集在 macOS / Linux 也改用系统原生调度;包内不再携带从未接线的本地服务模块。
11
+
12
+ - **用户输入错误统一为 `UsageError`**:未知命令 / 未知参数 / 非法取值只打一行
13
+ `Error: ...` 加 `Hint:`,退出码 2,不再刷堆栈;`--debug` 才展开。
14
+ - **命令表驱动 help**:`tokenusage help <cmd>` 与 `tokenusage <cmd> --help` 对每条
15
+ 命令都有效,未知命令抛 `UNKNOWN_COMMAND`。
16
+ - **新增 `tokenusage upload`**:只刷本地队列、不扫描来源(`--drain` / `--force`
17
+ 抬批次上限,`--json` 输出结构),与 `sync` 共用 `drainQueueToCloud` 与
18
+ `sync.lock`;`sync --upload-only` 为同一实现的别名。积压较多时不必再等
19
+ 全量扫描。
20
+ - **`--source` 严格校验**:非法 id 直接报错并列出可用列表(此前静默降级为全量
21
+ 扫描,容易误以为只采了某个来源)。
22
+ - **`sessions` 严格解析**:未知参数、缺值、非法 `--format` 均报错;`--out` 改为
23
+ 原子写(0600),避免脚本拿到半截 JSON / CSV。
24
+ - **`--watch` 失败退避**:连续失败按 1x → 2x → 5x 拉长间隔并在 stderr 提示,
25
+ 成功一次即归零;此前固定间隔会持续打服务端。
26
+ - **`init --integrations <ids|all|none>`**:可只接管部分集成;不带该参数时在交互
27
+ 确认里提供多选(空格切换 / `a` 全选 / `n` 清空),`--no-integrations` 仍等于
28
+ `none`。12 个 hook 型集成逐个 gate,被动读取器不受影响。
29
+ - **移除浏览器登录期死参数**:`--email` / `--password` / `--device-name` /
30
+ `--link-code` / `--no-auth` 改为报错并指向 `device-login`。
31
+ - **调度多平台**:Windows 计划任务改用 `schtasks /Create /XML` 定义
32
+ (`StartWhenAvailable`、登录触发、失败重试 3 次、无执行时限;XML 被拒时回退
33
+ `-SC HOURLY`);macOS 用 launchd(`com.token-usage.sync`);Linux 用 systemd
34
+ user timer(`token-usage-sync.timer`,`Persistent=true`)。`pause` / `resume` /
35
+ `uninstall` 走同一分发层。
36
+ - **`sync.log` 改 JSONL**:`{ts,msg,...}` 每行一条,带上 `phase` / `status` /
37
+ `parsed_files` / `buckets` / `inserted` / `skipped` / `pending_bytes` 等结构化
38
+ 字段;TTY 输出仍是人类可读行,1 MiB 滚动一代不变。
39
+ - **清理死模块**:删除从未接线的本地服务模块图(`local-api.js` 与 18 个可达性为零
40
+ 的模块,约 550 KB),`normalizeQueueRow` 抽到 `src/lib/queue-row-normalize.js`
41
+ 并补空值守卫。
42
+ - **打包收紧**:`files` 去掉 `test/`;`test/packaging.test.js` 新增两条守卫——
43
+ 已退役模块不得回归、`src/` 内每个文件都必须能从 CLI 入口可达。
44
+ - **新增 `tokenusage reconcile`**(只读对账):把本地 `queue.jsonl` 的 last-wins
45
+ 基线与云端**本设备**的桶明细按 `(hour_start, source, model)` 逐键比对,输出
46
+ `missing_on_server` / `server_only` / `mismatch` 三类漂移(mismatch 附逐字段
47
+ `local → cloud`),任一存在即退出码 1。窗口默认最近 7 天(`--days`,上限 366),
48
+ 也可 `--from` / `--to` 指定 UTC 日历日(`--to` 含当天整天);`--json` 输出结构化
49
+ 明细。命令不上传、不改写队列、不动上传 offset,后端读取面为
50
+ `GET /api/functions/token-usage-reconcile`(契约 §2.13)。
51
+ - 测试 76 → 130 条(新增 `cli-dispatch` / `args-strict` / `scheduled-task` /
52
+ `queue-row-normalize` / `integration-gate` / `reconcile`;`integration-gate` 锁定
53
+ 「选中才写工具配置」与 `upload` 未配对即拒绝,`reconcile` 锁定窗口解析、last-wins
54
+ 基线、漂移分类与退出码)。
55
+
56
+ ## 0.3.0
57
+
58
+ 新增三个采集来源/维度,修复 Windows 下 Qoder 会话的发现与口径问题。
59
+
60
+ - **Trae CN 本地库接入**:`resolveTraeDbPaths` 新增 `Trae CN` 安装目录
61
+ (与 `Trae` / `TRAE SOLO` 同 schema,共享应用密钥直接解密)。此前国内版
62
+ 安装的整个本地用量库被静默漏扫。
63
+ - **Qoder credits 维度**:Qoder 新版会话日志是 credits-only(token 全零),
64
+ 现按桶记录 `credits`(独立维度,不并入 token 列与成本);会话级 credits
65
+ 随 sessions 上报;sync-run 遥测新增 `credits_ingested`。
66
+ - **Qoder 会话进入 Sessions**:新增 qoder / qoder-cn 会话清单读取器
67
+ (一文件 = 一会话),并应用与桶解析器一致的 billable 门槛——
68
+ `billable:false` 行是未扣费理论值(实测占总量 81%),不计入消耗。
69
+ `SIDECAR_VERSION` 随之重建一次 sidecar。
70
+ - 模型口径:读侧按 model 小写折叠分组(大小写漂移不再拆行),展示名取
71
+ 组内 token 份额最大的写法。
72
+ - 采集期修复:会话清单缓存签名纳入 qoder 文件(否则永远复用旧 sidecar);
73
+ `listRolloutFilesDeep` 为异步且只认 `rollout-*` 文件名,qoder 改用专用
74
+ `.jsonl` 深遍历。
75
+
6
76
  ## 0.2.6
7
77
 
8
78
  移除从未接线的错误上报 SDK,安装体积与运行时副本明显变小;采集行为不变。
package/README.md CHANGED
@@ -30,21 +30,50 @@ tokenusage sync --drain # 首次/积压补传(更大的批处理预算)
30
30
 
31
31
  | 命令 | 说明 |
32
32
  |---|---|
33
- | `tokenusage init` | 本地初始化:扫描根配置、各工具 hook 安装、注册每小时计划任务(Windows 隐藏窗口)。`--no-task` 跳过任务;`--run-report=off` 关闭运行记录上报;`--no-integrations` 不装任何 hook/notify/插件,只做纯定时采集;`--yes` 非交互;`--dry-run` 只预览不落盘;`--no-open` 不打开浏览器;`--link-code <code>` 用已有配对码。不含配对 |
33
+ | `tokenusage init` | 本地初始化:扫描根配置、各工具 hook 安装、注册每小时计划任务(Windows 隐藏窗口)。`--no-task` 跳过任务;`--run-report=off` 关闭运行记录上报;`--integrations <ids,all,none>` 逐工具选择要接管的集成(缺省在交互确认里多选),`--no-integrations` 等于 `none`(只做纯定时采集);`--yes` 非交互;`--dry-run` 只预览不落盘;`--no-open` 不打开浏览器。不含配对 |
34
34
  | `tokenusage device-login` | 设备流配对:输出 `user_code`,在站点 `/device` 页批准后本机拿到设备令牌 |
35
35
  | `tokenusage sync` | 解析本地 AI 工具日志 → 上报小时桶 + 会话元数据 |
36
+ | `tokenusage upload` | 只刷本地队列,不扫描来源(`--drain` / `--force` 抬批次上限、`--json` 输出结构化结果) |
37
+ | `tokenusage reconcile` | 只读对账:本地 `queue.jsonl` 的 last-wins 基线 vs 云端该设备的桶明细,按 `(hour_start, source, model)` 逐键比对,有漂移退出码 1 |
36
38
  | `tokenusage sync --watch` | 常驻模式,默认每 15 分钟增量一轮(`--interval <ms>` 可调,≥60000) |
37
39
  | `tokenusage sync --no-sessions` | 只上报小时桶,跳过会话元数据 |
38
40
  | `tokenusage sync --drain` | 补传模式:更大的批处理预算,适合首次接入/长期积压 |
39
- | `tokenusage pause` / `resume` | 暂停/恢复自动采集:定时任务、hook、`--watch` 全部静默停手,手动 `sync` 不受影响(Windows 上同步启停计划任务) |
41
+ | `tokenusage pause` / `resume` | 暂停/恢复自动采集:定时任务、hook、`--watch` 全部静默停手,手动 `sync` 不受影响(同步启停系统的调度项) |
40
42
  | `tokenusage status` | 本地状态:Base URL、令牌、采集状态、运行上报开关、队列积压、最近解析/上传时间 |
41
43
  | `tokenusage doctor` | 体检(运行时 / 网络 / 各工具配置),`--json` 输出 |
42
44
  | `tokenusage diagnostics` | 诊断信息导出 |
43
- | `tokenusage sessions` | 本地导出会话分析(JSON/CSV,元数据级) |
45
+ | `tokenusage sessions` | 本地导出会话分析(JSON/CSV,元数据级);`--out <file>` 原子写(0600) |
44
46
  | `tokenusage uninstall [--purge]` | 移除 hook 与计划任务;`--purge` 连数据目录一起删 |
45
47
 
46
48
  配置优先级:CLI 参数 > `~/.tokenusage/.../config.json` > 环境变量(`TOKENUSAGE_BASE_URL` 等)> 内置默认(你的部署地址 + 其公开 publishable key)。
47
49
 
50
+ 帮助与错误:`tokenusage help`、`tokenusage help <命令>`、`tokenusage <命令> --help` 都可用。
51
+ 参数写错(未知命令 / 未知参数 / 非法取值)只输出一行 `Error: ...` 加 `Hint:`,退出码
52
+ `2`;其余运行错误退出码 `1`。要堆栈加 `--debug`。
53
+
54
+ 只补传积压、不重扫本地日志:
55
+
56
+ ```bash
57
+ tokenusage upload # 刷队列(默认最多 5 批,每批 200 条)
58
+ tokenusage upload --drain # 大积压补传(最多 100 批)
59
+ tokenusage upload --json # 结构化结果,便于脚本消费
60
+ ```
61
+
62
+ 对账(只读,不上传、不改队列、不动上传 offset):
63
+
64
+ ```bash
65
+ tokenusage reconcile # 最近 7 天
66
+ tokenusage reconcile --days 30 # 最近 30 天(上限 366)
67
+ tokenusage reconcile --from 2026-10-25 --to 2026-10-31 # UTC 日历日,--to 当天整天包含
68
+ tokenusage reconcile --json # 结构化漂移明细,供脚本/看板消费
69
+ ```
70
+
71
+ - 基线就是 `sync` / `upload` 会发出的同一批行:整份 `queue.jsonl` 按
72
+ `(hour_start, source, model)` last-wins,读时同样经过 legacy 修正与 ingestion 形状归一。
73
+ - 漂移分三类:`missing_on_server`(本地有、云端没有,通常是待补传)、`server_only`
74
+ (云端有、本地已无,队列被裁剪或换过机器身份)、`mismatch`(同键不同值,附逐字段
75
+ `local → cloud` 差异)。任一存在即以退出码 `1` 结束,便于 cron / CI 判定。
76
+
48
77
  ## `sync --watch`:常驻自动上报
49
78
 
50
79
  ```bash
@@ -56,6 +85,7 @@ tokenusage sync --watch --interval 3600000 --no-sessions # 每小时,只传
56
85
  - `--interval` 毫秒,最小 60000(小于该值回落到默认 15 分钟——每轮至少要跑一次本地扫描,过密无意义)。
57
86
  - **停止**:在运行的终端 Ctrl+C 即可;`--watch` 只是前台进程,不注册任何系统计划任务/守护。随时终止都安全——队列与水位都已落盘,下次 `sync` 从断点继续。
58
87
  - 每轮增量:首轮解析全部历史日志(可能较慢),之后只重扫有变化的文件;上报侧队列 offset + 会话水位双断点,多轮之间不重不漏。
88
+ - 失败退避:连续失败按 1x → 2x → 5x 拉长间隔(stderr 提示原因),成功一次即回到正常间隔——服务端抖动时不会持续敲。
59
89
 
60
90
  ## 采集控制:pause / resume 与计划任务
61
91
 
@@ -65,13 +95,23 @@ tokenusage resume # 恢复
65
95
  tokenusage status # 查看当前采集状态
66
96
  ```
67
97
 
68
- - 暂停是持久标志:`sync --auto`、hook/notify 触发、`--watch`、计划任务都会静默
98
+ - 暂停是持久标志:`sync --auto`、hook/notify 触发、`--watch`、定时任务都会静默
69
99
  退出(不报错、不上报、不留运行记录);**手动 `tokenusage sync` 永远可用**。
70
- - Windows 上 init 会注册每小时计划任务 `TokenUsageSync`(隐藏窗口,无黑框),
71
- pause/resume 顺势 disable/enable 它;`uninstall` 一并删除任务与脚本。
72
- 任务以 `--from-scheduled` 运行:运行记录标记为"定时"并写入滚动日志。
73
- - 自动采集的日志落在 `~/.tokenusage/tracker/logs/sync.log`(1 MiB 滚动一代),
74
- 不依赖终端重定向。
100
+ - init 会在系统里注册每小时自动采集,按平台分发;pause/resume 顺势停用/启用它,
101
+ `uninstall` 一并删除调度项与脚本。任务以 `--from-scheduled` 运行:运行记录标记
102
+ 为"定时"并写入滚动日志。
103
+
104
+ | 平台 | 调度形态 |
105
+ |---|---|
106
+ | Windows | 计划任务 `TokenUsageSync`(`schtasks /Create /XML`,隐藏窗口 VBS 启动,登录后可用、错过启动会补跑、失败重试 3 次、无执行时限) |
107
+ | macOS | launchd `~/Library/LaunchAgents/com.token-usage.sync.plist`(`StartInterval` 3600 + `RunAtLoad`) |
108
+ | Linux | systemd user timer `token-usage-sync.timer`(`Persistent=true`,开机/错过补跑) |
109
+ | 其他 | 不支持原生调度,请用 `tokenusage sync --watch` 常驻或手动 `sync` |
110
+
111
+ - 自动采集的日志落在 `~/.tokenusage/tracker/logs/sync.log`(**JSONL**:每行
112
+ `{ts,msg,...}`,带 `phase` / `status` / `parsed_files` / `buckets` / `inserted` /
113
+ `skipped` / `pending_bytes` 等字段,方便 `jq` 过滤;1 MiB 滚动一代),不依赖终端
114
+ 重定向。前台终端输出仍是人类可读行。
75
115
 
76
116
  ## 运行记录上报
77
117
 
@@ -98,8 +138,9 @@ CLI 未配对也能正常用,只是**降级为“只采集、不上报”**:
98
138
 
99
139
  上报内容只有**聚合用量**:
100
140
 
101
- - 小时桶:每工具每小时六项 token 计数与模型名。
102
- - 会话元数据:`session_id`(厂商会话 UUID,或无 UUID 来源的本地稳定指纹)、来源、起止时间、项目 basename、token 拆分、每模型用量。
141
+ - 小时桶:每工具每小时六项 token 计数、模型名,以及积分(仅积分制来源上报,
142
+ 如 Qoder;独立维度,不参与 token 与成本口径)。
143
+ - 会话元数据:`session_id`(厂商会话 UUID,或无 UUID 来源的本地稳定指纹)、来源、起止时间、项目 basename、token 拆分、每模型用量、积分(仅积分制来源)。
103
144
 
104
145
  **永不上传**:prompt / 助手正文 / 工具参数 / 命令输出 / diff / 会话标题 / 本地绝对路径 / resume 命令。测试(`test/session-upload.test.js`)用字段白名单锁定该边界。
105
146
 
package/bin/tokenusage.js CHANGED
@@ -42,8 +42,20 @@ if (applyResult && applyResult.unprotected === true) {
42
42
  process.exit(1);
43
43
  }
44
44
 
45
+ const { isUsageError } = require('../src/lib/cli-errors');
46
+
45
47
  run(argv).catch((err) => {
46
- console.error(err?.stack || String(err));
48
+ // Usage errors are the user's input, not a crash: message + hint, exit 2.
49
+ // Everything else prints a single readable line and points at --debug —
50
+ // dumping a stack for `tokenusage bogus` or `sync --help` made every typo
51
+ // look like an internal failure.
52
+ const usage = isUsageError(err);
53
+ if (debug) console.error(err?.stack || String(err));
54
+ else console.error(`Error: ${err?.message || String(err)}`);
55
+ if (err?.hint) console.error(`Hint: ${err.hint}`);
56
+ if (!debug && !usage) {
57
+ console.error('Re-run with --debug to see the full stack trace.');
58
+ }
47
59
  if (debug) {
48
60
  if (typeof err?.status === 'number') {
49
61
  console.error(`Status: ${err.status}`);
@@ -59,5 +71,5 @@ run(argv).catch((err) => {
59
71
  console.error(`Next actions: ${err.nextActions.trim()}`);
60
72
  }
61
73
  }
62
- process.exitCode = 1;
74
+ process.exitCode = usage ? (Number.isInteger(err?.exitCode) ? err.exitCode : 2) : 1;
63
75
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tokenusage-cli",
3
- "version": "0.2.6",
3
+ "version": "0.4.0",
4
4
  "description": "Self-hosted AI coding token usage collector for the Token Usage dashboard.",
5
5
  "keywords": [
6
6
  "token-usage",
@@ -27,7 +27,6 @@
27
27
  "files": [
28
28
  "bin/",
29
29
  "src/",
30
- "test/",
31
30
  "CHANGELOG.md",
32
31
  "LICENSE",
33
32
  "THIRD_PARTY_NOTICES.md",