tokenusage-cli 0.3.0 → 0.4.1
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.
- package/CHANGELOG.md +60 -0
- package/README.md +52 -11
- package/bin/tokenusage.js +14 -2
- package/package.json +1 -2
- package/src/cli.js +325 -78
- package/src/commands/device-login.js +3 -3
- package/src/commands/init.js +343 -153
- package/src/commands/pause.js +11 -23
- package/src/commands/reconcile.js +496 -0
- package/src/commands/sessions.js +57 -14
- package/src/commands/sync.js +69 -15
- package/src/commands/uninstall.js +6 -9
- package/src/commands/upload.js +147 -0
- package/src/lib/cli-errors.js +33 -0
- package/src/lib/cli-ui.js +93 -0
- package/src/lib/queue-row-normalize.js +55 -0
- package/src/lib/scheduled-task.js +597 -75
- package/src/lib/antigravity-paths.js +0 -48
- package/src/lib/async-queue-reader.js +0 -138
- package/src/lib/atomic-json.js +0 -27
- package/src/lib/bearer-token.js +0 -11
- package/src/lib/cloud-account.js +0 -541
- package/src/lib/codex-context-breakdown.js +0 -806
- package/src/lib/context-health.js +0 -124
- package/src/lib/grok-context-breakdown.js +0 -890
- package/src/lib/heatmap-compact.js +0 -114
- package/src/lib/local-api.js +0 -3574
- package/src/lib/outcomes-engine.js +0 -253
- package/src/lib/pet-packages.js +0 -722
- package/src/lib/skill-usage.js +0 -267
- package/src/lib/skills-manager.js +0 -1591
- package/src/lib/source-metadata.js +0 -48
- package/src/lib/subscription-manager.js +0 -293
- package/src/lib/wrapped-aggregator.js +0 -236
- package/test/audit-fixes.test.js +0 -249
- package/test/branding.test.js +0 -24
- package/test/cli-options.test.js +0 -43
- package/test/cli-smoke.test.js +0 -53
- package/test/cli-ui.test.js +0 -47
- package/test/collection-controls.test.js +0 -255
- package/test/ingest-sanitize.test.js +0 -162
- package/test/packaging.test.js +0 -107
- package/test/quiet-warnings.test.js +0 -53
- package/test/runtime-copy.test.js +0 -111
- package/test/session-upload.test.js +0 -427
- package/test/trae-db.test.js +0 -67
- package/test/zstd-native.test.js +0 -36
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,66 @@
|
|
|
3
3
|
本包(`tokenusage-cli`)的用户可见变更记录。发版时在顶部新增一节,
|
|
4
4
|
`## <版本号>` 行会被 release workflow 取作 GitHub Release 正文。
|
|
5
5
|
|
|
6
|
+
## 0.4.1
|
|
7
|
+
|
|
8
|
+
2026-11-01。修复 `tokenusage reconcile` 在真实队列上的误报:队列行写的是
|
|
9
|
+
`conversation_count`(`docs/cli-contract.md` §2.4 的线名),小时表列名是
|
|
10
|
+
`conversations`,按字段名直接比较会把每一行都报成 `conversations local 0 → cloud N`
|
|
11
|
+
(本机首跑 41/43 行误报)。现在按别名归一后比较,真实差异仍照常报出。
|
|
12
|
+
|
|
13
|
+
- 会话数比较读 `conversations`,缺失时回退 `conversation_count`(两者都没有按 0)。
|
|
14
|
+
- 单测按真实队列形态(只带 `conversation_count`)覆盖,并断言真差异仍落在 `conversations` 字段。
|
|
15
|
+
|
|
16
|
+
## 0.4.0
|
|
17
|
+
|
|
18
|
+
2026-11-01。错误提示更友好(一行 `Error:` + `Hint:` 且不再刷堆栈),帮助信息改为
|
|
19
|
+
命令表驱动,新增 `upload` / `reconcile` 两条命令,`init` 可按工具挑选要接管的集成,
|
|
20
|
+
自动采集在 macOS / Linux 也改用系统原生调度;包内不再携带从未接线的本地服务模块。
|
|
21
|
+
|
|
22
|
+
- **用户输入错误统一为 `UsageError`**:未知命令 / 未知参数 / 非法取值只打一行
|
|
23
|
+
`Error: ...` 加 `Hint:`,退出码 2,不再刷堆栈;`--debug` 才展开。
|
|
24
|
+
- **命令表驱动 help**:`tokenusage help <cmd>` 与 `tokenusage <cmd> --help` 对每条
|
|
25
|
+
命令都有效,未知命令抛 `UNKNOWN_COMMAND`。
|
|
26
|
+
- **新增 `tokenusage upload`**:只刷本地队列、不扫描来源(`--drain` / `--force`
|
|
27
|
+
抬批次上限,`--json` 输出结构),与 `sync` 共用 `drainQueueToCloud` 与
|
|
28
|
+
`sync.lock`;`sync --upload-only` 为同一实现的别名。积压较多时不必再等
|
|
29
|
+
全量扫描。
|
|
30
|
+
- **`--source` 严格校验**:非法 id 直接报错并列出可用列表(此前静默降级为全量
|
|
31
|
+
扫描,容易误以为只采了某个来源)。
|
|
32
|
+
- **`sessions` 严格解析**:未知参数、缺值、非法 `--format` 均报错;`--out` 改为
|
|
33
|
+
原子写(0600),避免脚本拿到半截 JSON / CSV。
|
|
34
|
+
- **`--watch` 失败退避**:连续失败按 1x → 2x → 5x 拉长间隔并在 stderr 提示,
|
|
35
|
+
成功一次即归零;此前固定间隔会持续打服务端。
|
|
36
|
+
- **`init --integrations <ids|all|none>`**:可只接管部分集成;不带该参数时在交互
|
|
37
|
+
确认里提供多选(空格切换 / `a` 全选 / `n` 清空),`--no-integrations` 仍等于
|
|
38
|
+
`none`。12 个 hook 型集成逐个 gate,被动读取器不受影响。
|
|
39
|
+
- **移除浏览器登录期死参数**:`--email` / `--password` / `--device-name` /
|
|
40
|
+
`--link-code` / `--no-auth` 改为报错并指向 `device-login`。
|
|
41
|
+
- **调度多平台**:Windows 计划任务改用 `schtasks /Create /XML` 定义
|
|
42
|
+
(`StartWhenAvailable`、登录触发、失败重试 3 次、无执行时限;XML 被拒时回退
|
|
43
|
+
`-SC HOURLY`);macOS 用 launchd(`com.token-usage.sync`);Linux 用 systemd
|
|
44
|
+
user timer(`token-usage-sync.timer`,`Persistent=true`)。`pause` / `resume` /
|
|
45
|
+
`uninstall` 走同一分发层。
|
|
46
|
+
- **`sync.log` 改 JSONL**:`{ts,msg,...}` 每行一条,带上 `phase` / `status` /
|
|
47
|
+
`parsed_files` / `buckets` / `inserted` / `skipped` / `pending_bytes` 等结构化
|
|
48
|
+
字段;TTY 输出仍是人类可读行,1 MiB 滚动一代不变。
|
|
49
|
+
- **清理死模块**:删除从未接线的本地服务模块图(`local-api.js` 与 18 个可达性为零
|
|
50
|
+
的模块,约 550 KB),`normalizeQueueRow` 抽到 `src/lib/queue-row-normalize.js`
|
|
51
|
+
并补空值守卫。
|
|
52
|
+
- **打包收紧**:`files` 去掉 `test/`;`test/packaging.test.js` 新增两条守卫——
|
|
53
|
+
已退役模块不得回归、`src/` 内每个文件都必须能从 CLI 入口可达。
|
|
54
|
+
- **新增 `tokenusage reconcile`**(只读对账):把本地 `queue.jsonl` 的 last-wins
|
|
55
|
+
基线与云端**本设备**的桶明细按 `(hour_start, source, model)` 逐键比对,输出
|
|
56
|
+
`missing_on_server` / `server_only` / `mismatch` 三类漂移(mismatch 附逐字段
|
|
57
|
+
`local → cloud`),任一存在即退出码 1。窗口默认最近 7 天(`--days`,上限 366),
|
|
58
|
+
也可 `--from` / `--to` 指定 UTC 日历日(`--to` 含当天整天);`--json` 输出结构化
|
|
59
|
+
明细。命令不上传、不改写队列、不动上传 offset,后端读取面为
|
|
60
|
+
`GET /api/functions/token-usage-reconcile`(契约 §2.13)。
|
|
61
|
+
- 测试 76 → 130 条(新增 `cli-dispatch` / `args-strict` / `scheduled-task` /
|
|
62
|
+
`queue-row-normalize` / `integration-gate` / `reconcile`;`integration-gate` 锁定
|
|
63
|
+
「选中才写工具配置」与 `upload` 未配对即拒绝,`reconcile` 锁定窗口解析、last-wins
|
|
64
|
+
基线、漂移分类与退出码)。
|
|
65
|
+
|
|
6
66
|
## 0.3.0
|
|
7
67
|
|
|
8
68
|
新增三个采集来源/维度,修复 Windows 下 Qoder 会话的发现与口径问题。
|
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`
|
|
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`
|
|
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
|
-
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
3
|
+
"version": "0.4.1",
|
|
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",
|