@mai0313/vct 2.0.0 → 2.1.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.
Files changed (10) hide show
  1. package/README.md +28 -18
  2. package/README.zh-CN.md +33 -23
  3. package/README.zh-TW.md +36 -26
  4. package/binaries/linux-arm64-gnu/vibe_coding_tracker +0 -0
  5. package/binaries/linux-x64-gnu/vibe_coding_tracker +0 -0
  6. package/binaries/macos-arm64/vibe_coding_tracker +0 -0
  7. package/binaries/macos-x64/vibe_coding_tracker +0 -0
  8. package/binaries/windows-arm64/vibe_coding_tracker.exe +0 -0
  9. package/binaries/windows-x64/vibe_coding_tracker.exe +0 -0
  10. package/package.json +1 -1
package/README.md CHANGED
@@ -35,13 +35,13 @@ Stop wondering how much your AI coding sessions cost. Get **real-time cost track
35
35
 
36
36
  ### Ultra-Lightweight
37
37
 
38
- Built with Rust for minimal resource footprint. The interactive TUI dashboard typically sits at **under ~50 MB of resident memory** once the first refresh is done, even with hundreds of long-context sessions on disk — no Electron, no bloated runtimes. The usage path parses each session file in a lean usage-only mode and bypasses the cache, and we tune glibc's arena count at startup to keep long-running RSS honest.
38
+ Built with Rust for minimal resource footprint. The interactive TUI dashboard typically sits at **under ~50 MB of resident memory** once the first refresh is done, even with hundreds of long-context sessions on disk — no Electron, no bloated runtimes. A compact process-local summary cache reparses only new or changed sources after the first scan, while dedicated scan workers and glibc allocator tuning keep long-running CPU and RSS honest.
39
39
 
40
40
  ### Beautiful Visualizations
41
41
 
42
42
  Choose your preferred view:
43
43
 
44
- - **Interactive Dashboard**: Auto-refreshing terminal UI with live updates, scrollable model list (arrow keys), and compact K/M/B number formatting
44
+ - **Interactive Dashboard**: Responsive terminal UI with an immediate loading spinner, background incremental refreshes, a scrollable model list (arrow keys), a live per-process CPU/memory readout, and compact K/M/B number formatting
45
45
  - **Static Reports**: Professional tables for documentation
46
46
  - **Script-Friendly**: Plain text and JSON for automation
47
47
  - **Full Precision**: Export exact costs for accounting
@@ -62,15 +62,15 @@ Automatically detects and processes logs from Claude Code, Codex, Copilot, Gemin
62
62
 
63
63
  ## Key Features
64
64
 
65
- | Feature | Description |
66
- | --------------------- | ----------------------------------------------------------------------- |
67
- | **Multi-Provider** | Claude Code, Codex, Copilot, Gemini, OpenCode, Cursor, Hermes, and Grok |
68
- | **Smart Pricing** | Fuzzy model matching + daily cache from LiteLLM |
69
- | **4 Display Modes** | Interactive TUI, static table, plain text, and JSON |
70
- | **Dual Analysis** | Token/cost stats (`usage`) + code operation stats (`analysis`) |
71
- | **Live Quota Panels** | Live remaining quota for Claude, Codex, Copilot, and Cursor |
72
- | **Ultra-Lightweight** | Under ~50 MB RSS in the TUI, streaming session parse — built with Rust |
73
- | **Live Updates** | Auto-refreshing dashboard (every 10s) with change highlighting |
65
+ | Feature | Description |
66
+ | --------------------- | ------------------------------------------------------------------------ |
67
+ | **Multi-Provider** | Claude Code, Codex, Copilot, Gemini, OpenCode, Cursor, Hermes, and Grok |
68
+ | **Smart Pricing** | Fuzzy model matching + daily cache from LiteLLM |
69
+ | **4 Display Modes** | Interactive TUI, static table, plain text, and JSON |
70
+ | **Dual Analysis** | Token/cost stats (`usage`) + code operation stats (`analysis`) |
71
+ | **Live Quota Panels** | Live remaining quota for Claude, Codex, Copilot, and Cursor |
72
+ | **Ultra-Lightweight** | Under ~50 MB RSS in the TUI, compact incremental scans — built with Rust |
73
+ | **Live Updates** | Responsive loading and background refreshes with change highlighting |
74
74
 
75
75
  ---
76
76
 
@@ -230,11 +230,13 @@ vct usage --table --merge-providers
230
230
  │ Gemini 207K $0.40 │
231
231
  └─────────────────────────────────────────────────────────────────────────────────────────────┘
232
232
  ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
233
- │ Total Cost: $79.33 | Total Tokens: 49.3M | Models: 3 | Memory: 42.8 MB │
233
+ │ Total Cost: $79.33 | Total Tokens: 49.3M | Models: 3 | Memory: 42.8 MB | CPU: 17.9% │
234
234
  └─────────────────────────────────────────────────────────────────────────────────────────────┘
235
235
  ↑/↓ scroll m merge r refresh q quit | Star on GitHub
236
236
  ```
237
237
 
238
+ Both interactive dashboards draw a centered `Loading sessions...` spinner as soon as terminal setup finishes. Loading stays responsive to `q`, Ctrl+C, and resize events. Later scans run in one background worker, keep the last successful data visible with a `Refreshing...` footer, and coalesce repeated refresh requests into at most one pending scan. A failed refresh keeps the last-known-good view and retries on the next scheduled or manual refresh.
239
+
238
240
  ### Preview: Table & JSON (`vct usage`)
239
241
 
240
242
  `--table` prints the same numbers as a static report with a per-provider summary; `--json` emits one enriched row per model (each with `cost_usd`) for scripting.
@@ -295,6 +297,8 @@ The tool automatically scans these directories:
295
297
 
296
298
  Grok `usage` is one point-in-time local context estimate: vct records `signals.json`'s `contextTokensUsed` as cache-read tokens and estimates cost at the model's cache-read price. It is not cumulative billed usage. `analysis` reconstructs completed Read / Write / Edit / Bash / TodoWrite operations from the sibling `updates.jsonl`. Grok does not support quota panels or `vct fetch`.
297
299
 
300
+ For noninteractive `usage` and `analysis` scans, vct exits with an error when every discovered source fails. If only some sources fail, it keeps the successful results and prints one diagnostic summary to stderr. The TUI stays best-effort and preserves its last successful payload instead.
301
+
298
302
  ### Live Quota Panels
299
303
 
300
304
  `vct usage` shows **live remaining quota for Claude Code, Codex, GitHub Copilot, and Cursor right in the dashboard — with zero setup.** No status-line hook, no credentials to enter: vct reads each provider's own credentials, calls its usage API on a background thread, and keeps the panels current while you work. (Prefer a quieter dashboard? Trim `panels` under `[usage.quota]` in [`config.toml`](#configuration), or set it to `[]` to hide the band.)
@@ -388,7 +392,7 @@ vct analysis --json --daily > today.json
388
392
  │ Gemini 0 0 0 0 0 0 0 0 1 │
389
393
  └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
390
394
  ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
391
- │ Total Lines: 16.1K | Total Tools: 619 | Models: 3 | Memory: 41.2 MB │
395
+ │ Total Lines: 16.1K | Total Tools: 619 | Models: 3 | Memory: 41.2 MB | CPU: 17.9% │
392
396
  └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
393
397
  ↑/↓ scroll r refresh q quit | Star on GitHub
394
398
  ```
@@ -567,6 +571,11 @@ refresh_interval = 60
567
571
  # Seconds between automatic redraws of the analysis TUI (minimum 1).
568
572
  refresh_interval = 10
569
573
 
574
+ [performance]
575
+ # Rayon workers used by CLI session scans. 0 selects the measured auto default;
576
+ # a positive value is capped at the machine's available parallelism.
577
+ scan_threads = 0
578
+
570
579
  [providers]
571
580
  # Include each provider's sessions in usage / analysis. Set a provider to false
572
581
  # to skip it entirely (no directory scan, no API).
@@ -595,6 +604,7 @@ retention_days = 7
595
604
  | `usage.quota.panels` | Which quota panels to show (`claude` / `codex` / `copilot` / `cursor`); drop a name to hide it, `[]` to hide the whole band. |
596
605
  | `usage.quota.refresh_interval` | Poll cadence for every live quota panel (seconds); higher is safer against a provider's rate limits. |
597
606
  | `analysis.refresh_interval` | Redraw cadence of the `analysis` dashboard (seconds). |
607
+ | `performance.scan_threads` | CLI scan workers. `0` uses `RAYON_NUM_THREADS` when positive, otherwise at most two workers; every value is CPU-capped. |
598
608
  | `providers.*` | Skip a provider entirely (no scan, no API) when `false` — handy if you don't use one. |
599
609
  | `logging.level` | Minimum severity written to the log file (`off`..`trace`); never printed to the terminal. |
600
610
  | `logging.retention_days` | Days of daily log files to keep; older `vct-*.log` are pruned on startup (`0` keeps all). |
@@ -630,10 +640,10 @@ vct config migrate
630
640
 
631
641
  ### How It Works
632
642
 
633
- 1. **Automatic Updates**: Fetches pricing from [LiteLLM](https://github.com/BerriAI/litellm) daily
634
- 2. **Smart Caching**: Stores pricing in `~/.vct/` for 24 hours
635
- 3. **Fuzzy Matching**: Finds best match even for custom model names
636
- 4. **Always Accurate**: Ensures you get the latest pricing
643
+ 1. **Automatic Updates**: Fetches pricing from [LiteLLM](https://github.com/BerriAI/litellm) once per UTC day
644
+ 2. **Validated Caching**: Accepts only a successful JSON model map containing real prices, then writes it atomically to `~/.vct/`
645
+ 3. **Deterministic Matching**: Finds the most specific model match even for versioned or provider-prefixed names
646
+ 4. **Failure Safety**: A failed fetch cannot replace a good cache; vct keeps the previous map and backs off for five minutes before another attempt
637
647
 
638
648
  ### Model Matching
639
649
 
@@ -651,7 +661,7 @@ vct config migrate
651
661
  - **OpenCode**: a novel model name is priced from its tokens only on an **exact** LiteLLM match; with no exact match, vct trusts the assistant message's own stored cost instead of guessing from a loosely-similar name.
652
662
  - **Hermes**: priced the same way as OpenCode — an **exact** LiteLLM match prices from tokens, otherwise vct uses Hermes's own stored cost.
653
663
  - **Grok**: `contextTokensUsed` is priced as cache-read tokens only; this is a point-in-time local context estimate, not cumulative billed usage.
654
- - **Cache is raw**: the daily cache stores the filtered upstream LiteLLM JSON (not a derived shape), so tiered / batch pricing stays available without re-fetching, and a small in-process LRU keeps repeated lookups cheap during a TUI refresh.
664
+ - **Cache is raw**: the daily cache stores the filtered upstream LiteLLM JSON (not a derived shape), so tiered / batch pricing stays available without re-fetching, and each pricing map owns a small in-process LRU so repeated lookups stay cheap without cross-map contamination.
655
665
 
656
666
  ---
657
667
 
package/README.zh-CN.md CHANGED
@@ -35,13 +35,13 @@
35
35
 
36
36
  ### 超轻量级
37
37
 
38
- 使用 Rust 构建，资源占用极低。交互式 TUI 面板稳定后常驻内存通常控制在 **约 50 MB 以内**，即使磁盘上有数百个长 context session 文件也不例外——无需 Electron，无需臃肿的运行时。usage 路径以精简模式流式解析每个 session 文件并绕过 cache，启动时还会调整 glibc 的 arena 数量，让长时间运行的 RSS 保持诚实。
38
+ 使用 Rust 构建, 资源占用极低. 交互式 TUI 面板完成首次刷新后, 常驻内存通常控制在 **约 50 MB 以内**, 即使磁盘上有数百个长 context session 文件也不例外. 首次扫描后, 精简的 process-local summary cache 只会重新解析新增或变更的 source, dedicated scan worker 与 glibc allocator 调整也能让长时间运行的 CPU 和 RSS 保持稳定.
39
39
 
40
40
  ### 精美的可视化
41
41
 
42
42
  选择你喜欢的查看方式：
43
43
 
44
- - **交互式面板**：自动刷新的终端 UI，支持实时更新、可滚动的模型列表（方向键），以及 K/M/B 精简数字格式
44
+ - **交互式面板**: 可立即显示 loading spinner 的响应式终端 UI, 支持后台 incremental refresh, 可滚动的模型列表 (方向键), 进程级 CPU/内存实时读数, 以及 K/M/B 精简数字格式
45
45
  - **静态报表**：专业的表格，适合文档记录
46
46
  - **脚本友好**：纯文本和 JSON 格式，方便自动化
47
47
  - **完整精度**：导出精确费用，满足财务核算需求
@@ -69,8 +69,8 @@
69
69
  | **4 种显示模式** | 交互式 TUI、静态表格、纯文本和 JSON |
70
70
  | **双维度分析** | token/费用统计（`usage`）+ 代码操作统计（`analysis`） |
71
71
  | **实时额度面板** | Claude、Codex、Copilot 和 Cursor 的实时剩余额度 |
72
- | **超轻量级** | TUI 常驻内存 50 MB 以内、流式 session 解析——基于 Rust 构建 |
73
- | **实时更新** | 面板自动刷新（每 10 秒），并高亮变化 |
72
+ | **超轻量级** | TUI 常驻内存 50 MB 以内、精简的 incremental scan, 基于 Rust 构建 |
73
+ | **实时更新** | 响应式 loading 与后台 refresh, 并高亮变化 |
74
74
 
75
75
  ---
76
76
 
@@ -80,7 +80,7 @@
80
80
 
81
81
  选择最适合你的安装方式：
82
82
 
83
- > **开发者**：如果你想从源码构建或参与项目开发，请参阅 [CONTRIBUTING.md](.github/CONTRIBUTING.md)。
83
+ > **开发者**: 如果你想从源码构建或参与项目开发, 请参阅 [CONTRIBUTING.md](.github/CONTRIBUTING.md).
84
84
 
85
85
  #### 方式一：通过 npm 安装
86
86
 
@@ -230,11 +230,13 @@ vct usage --table --merge-providers
230
230
  │ Gemini 207K $0.40 │
231
231
  └─────────────────────────────────────────────────────────────────────────────────────────────┘
232
232
  ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
233
- │ Total Cost: $79.33 | Total Tokens: 49.3M | Models: 3 | Memory: 42.8 MB │
233
+ │ Total Cost: $79.33 | Total Tokens: 49.3M | Models: 3 | Memory: 42.8 MB | CPU: 17.9% │
234
234
  └─────────────────────────────────────────────────────────────────────────────────────────────┘
235
235
  ↑/↓ scroll m merge r refresh q quit | Star on GitHub
236
236
  ```
237
237
 
238
+ 两个交互式面板都会在 terminal setup 完成后立即绘制居中的 `Loading sessions...` spinner. Loading 期间仍可响应 `q`, Ctrl+C 与 resize event. 后续扫描由单一 background worker 执行, 并在 `Refreshing...` footer 下保留上一次成功的数据. 重复的 refresh 请求最多只会合并为一个 pending scan. 如果 refresh 失败, 面板会保留 last-known-good view, 并在下次排程或手动刷新时重试.
239
+
238
240
  ### 预览：表格与 JSON（`vct usage`）
239
241
 
240
242
  `--table` 会以静态报表的形式打印相同的数字，并附带按 provider 的汇总；`--json` 则为每个 model 输出一行富化数据（各自带有 `cost_usd`），方便脚本处理。
@@ -295,6 +297,8 @@ Totals (by Provider)
295
297
 
296
298
  Grok 的 `usage` 是单一时点的本地 context 估算：vct 会把 `signals.json` 的 `contextTokensUsed` 记为 cache-read token，并按该 model 的 cache-read 费率估算费用。这不是累计的 billed usage。`analysis` 会从同层的 `updates.jsonl` 还原已完成的 Read / Write / Edit / Bash / TodoWrite 操作。Grok 不支持 quota panel 或 `vct fetch`。
297
299
 
300
+ 对于非交互式 `usage` 与 `analysis` 扫描, 如果所有找到的 source 都失败, vct 会以错误结束. 如果只有部分 source 失败, vct 会保留成功的结果, 并向 stderr 打印一则诊断摘要. TUI 则保持 best-effort, 并保留上一次成功的 payload.
301
+
298
302
  ### 实时额度面板
299
303
 
300
304
  `vct usage` 会**在仪表盘中直接显示 Claude Code、Codex、GitHub Copilot 与 Cursor 的实时剩余额度——完全零配置。** 不需要 status-line hook，也无需手动输入任何凭证：vct 会读取各 provider 自己的 OAuth 凭证，在后台线程调用其用量 API，并在你工作时保持面板持续更新。（想要更清爽的面板？在 [`config.toml`](#%E9%85%8D%E7%BD%AE) 中精简 `[usage.quota]` 下的 `panels`，或设为 `[]` 隐藏整栏。）
@@ -388,7 +392,7 @@ vct analysis --json --daily > today.json
388
392
  │ Gemini 0 0 0 0 0 0 0 0 1 │
389
393
  └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
390
394
  ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
391
- │ Total Lines: 16.1K | Total Tools: 619 | Models: 3 | Memory: 41.2 MB │
395
+ │ Total Lines: 16.1K | Total Tools: 619 | Models: 3 | Memory: 41.2 MB | CPU: 17.9% │
392
396
  └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
393
397
  ↑/↓ scroll r refresh q quit | Star on GitHub
394
398
  ```
@@ -566,6 +570,11 @@ refresh_interval = 60
566
570
  # analysis TUI 自动刷新的间隔秒数 (最小为 1)
567
571
  refresh_interval = 10
568
572
 
573
+ [performance]
574
+ # CLI session scan 使用的 Rayon worker 数. 0 代表实测最佳的 auto 默认值;
575
+ # 正整数会限制在机器的 available parallelism 以内.
576
+ scan_threads = 0
577
+
569
578
  [providers]
570
579
  # 是否把各 provider 的 session 纳入 usage / analysis, 设为 false
571
580
  # 就会完全跳过它 (不扫描目录, 也不调用 API)
@@ -586,17 +595,18 @@ level = "warn"
586
595
  retention_days = 7
587
596
  ```
588
597
 
589
- | 设置项 | 作用 |
590
- | ------------------------------ | ------------------------------------------------------------------------------------------------ |
591
- | `general.default_time_range` | 当你没有传入 `--daily/--weekly/--monthly/--all` 时使用的时间范围。显式传入的 flag 始终优先。 |
592
- | `usage.merge_models` | 让面板启动时就处于合并状态；`m` 切换会把你上次的选择保存回这里。`--merge-providers` 会强制开启。 |
593
- | `usage.refresh_interval` | `usage` 面板的自动刷新间隔（秒）。 |
594
- | `usage.quota.panels` | 显示哪些额度面板（`claude` / `codex` / `copilot` / `cursor`）；删除名称即可隐藏，`[]` 隐藏整栏。 |
595
- | `usage.quota.refresh_interval` | 每个实时额度面板的轮询间隔（秒）；数值越大越不容易触发 provider 的速率限制。 |
596
- | `analysis.refresh_interval` | `analysis` 面板的自动刷新间隔（秒）。 |
597
- | `providers.*` | 设为 `false` 时完全跳过某个 provider（不扫描、不调用 API）——如果你不用某个 provider 会很方便。 |
598
- | `logging.level` | 写入日志文件的最低级别（`off`..`trace`）；从不打印到终端。 |
599
- | `logging.retention_days` | 保留多少天的每日日志文件；更旧的 `vct-*.log` 会在启动时清除（`0` 表示全部保留）。 |
598
+ | 设置项 | 作用 |
599
+ | ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
600
+ | `general.default_time_range` | 当你没有传入 `--daily/--weekly/--monthly/--all` 时使用的时间范围。显式传入的 flag 始终优先。 |
601
+ | `usage.merge_models` | 让面板启动时就处于合并状态；`m` 切换会把你上次的选择保存回这里。`--merge-providers` 会强制开启。 |
602
+ | `usage.refresh_interval` | `usage` 面板的自动刷新间隔（秒）。 |
603
+ | `usage.quota.panels` | 显示哪些额度面板（`claude` / `codex` / `copilot` / `cursor`）；删除名称即可隐藏，`[]` 隐藏整栏。 |
604
+ | `usage.quota.refresh_interval` | 每个实时额度面板的轮询间隔（秒）；数值越大越不容易触发 provider 的速率限制。 |
605
+ | `analysis.refresh_interval` | `analysis` 面板的自动刷新间隔（秒）。 |
606
+ | `performance.scan_threads` | CLI scan worker 数. `0` 优先采用正数的 `RAYON_NUM_THREADS`, 否则最多使用两个 worker; 所有值都会受 CPU 数量限制. |
607
+ | `providers.*` | 设为 `false` 时完全跳过某个 provider（不扫描、不调用 API）——如果你不用某个 provider 会很方便。 |
608
+ | `logging.level` | 写入日志文件的最低级别（`off`..`trace`）；从不打印到终端。 |
609
+ | `logging.retention_days` | 保留多少天的每日日志文件；更旧的 `vct-*.log` 会在启动时清除（`0` 表示全部保留）。 |
600
610
 
601
611
  > [!NOTE]
602
612
  > vct 会把诊断信息写入 `~/.vct/logs/vct-YYYY-MM-DD.log`（纯文本，仅写文件，绝不显示在面板上）。健康运行时保持安静（默认级别 `warn`），且文件是惰性创建的，所以一次正常运行不会留下任何文件。当额度获取失败或某个 session 被跳过时，原因就记录在这里——需要完整细节时把 `logging.level` 调到 `debug`。
@@ -629,10 +639,10 @@ vct config migrate
629
639
 
630
640
  ### 工作原理
631
641
 
632
- 1. **自动更新**：每天从 [LiteLLM](https://github.com/BerriAI/litellm) 获取最新定价
633
- 2. **智能缓存**：将定价信息存储在 `~/.vct/` 目录中，有效期 24 小时
634
- 3. **模糊匹配**：即使是自定义模型名称也能找到最佳匹配
635
- 4. **始终精确**：确保你获取到最新的定价信息
642
+ 1. **自动更新**: 每个 UTC 日期从 [LiteLLM](https://github.com/BerriAI/litellm) 获取一次最新定价
643
+ 2. **校验后缓存**: 只接受成功且包含实际价格的 JSON model map, 再 atomic 写入 `~/.vct/`
644
+ 3. **确定性匹配**: 即使 model 名称含有版本或 provider 前缀, 也会选择最具体的匹配
645
+ 4. **失败保护**: 获取失败不会覆盖有效 cache, vct 会保留旧 map, 并在五分钟 backoff 后才再次尝试
636
646
 
637
647
  ### 模型匹配
638
648
 
@@ -650,7 +660,7 @@ vct config migrate
650
660
  - **OpenCode**：只有在 LiteLLM 上**精确**匹配时，才会根据 token 为一个全新的 model 名称定价；若没有精确匹配，vct 会信任该 assistant message 自身存储的费用，而不是从一个只是大致相似的名称去猜测。
651
661
  - **Hermes**：与 OpenCode 相同，LiteLLM 上**精确**匹配时按 token 定价，否则使用 Hermes 自身存储的费用。
652
662
  - **Grok**：只会把 `contextTokensUsed` 作为 cache-read token 计价；这是单一时点的本地 context 估算，不是累计的 billed usage。
653
- - **缓存为原始数据**：每日缓存存储的是经过筛选的上游 LiteLLM JSON（而非派生后的结构），因此无需重新获取即可保留分层 / 批量定价；此外还有一个小型的进程内 LRU，让 TUI 刷新期间的重复查询保持低开销。
663
+ - **缓存为原始数据**: 每日 cache 保存经过筛选的 LiteLLM 上游原始 JSON (而非派生结构), 因此 tiered / batch 定价无需重新获取即可使用. 每个 pricing map 各自拥有一个小型 process-local LRU, 重复查找保持低开销, 也不会在不同 map 之间互相污染.
654
664
 
655
665
  ---
656
666
 
package/README.zh-TW.md CHANGED
@@ -35,16 +35,16 @@
35
35
 
36
36
  ### 超輕量
37
37
 
38
- 以 Rust 打造，資源佔用極低。互動式 TUI 儀表板穩定後通常維持在 **~50 MB 以內的常駐記憶體**，即使硬碟上有數百個長 context session 也一樣——不用 Electron，不用臃腫的執行環境。usage 路徑用精簡模式串流 parse 每個 session 檔案並繞過 cache，啟動時也會調整 glibc 的 arena 數量，讓長時間執行的 RSS 保持誠實。
38
+ 以 Rust 打造, 資源佔用極低. 互動式 TUI 儀表板完成首次刷新後通常維持在 **~50 MB 以內的常駐記憶體**, 即使硬碟上有數百個長 context session 也一樣. 首次掃描後, 精簡的 process-local summary cache 只會重新解析新增或變更的 source, dedicated scan worker 與 glibc allocator 調整也能讓長時間執行時的 CPU 和 RSS 維持穩定.
39
39
 
40
40
  ### 精美視覺化
41
41
 
42
42
  選擇你偏好的檢視方式：
43
43
 
44
- - **互動式儀表板**：自動更新的終端機 UI,即時顯示最新資訊、可捲動的 model 清單(方向鍵),以及 K/M/B 精簡數字格式
45
- - **靜態報表**：專業的表格格式，適合撰寫文件
46
- - **腳本友好**：純文字及 JSON 輸出，方便自動化處理
47
- - **完整精度**：匯出精確費用供會計使用
44
+ - **互動式儀表板**: 可立即顯示 loading spinner 的響應式終端 UI, 支援背景 incremental refresh, 可捲動的 model 清單 (方向鍵), process 層級的 CPU/記憶體即時讀數, 以及 K/M/B 精簡數字格式
45
+ - **靜態報表**:專業的表格格式,適合撰寫文件
46
+ - **腳本友好**:純文字及 JSON 輸出,方便自動化處理
47
+ - **完整精度**:匯出精確費用供會計使用
48
48
 
49
49
  ### 零設定
50
50
 
@@ -69,8 +69,8 @@
69
69
  | **4 種顯示模式** | 互動式 TUI、靜態表格、純文字及 JSON |
70
70
  | **雙重分析** | Token / 費用統計（`usage`）+ 程式碼操作統計（`analysis`） |
71
71
  | **即時額度面板** | 即時顯示 Claude、Codex、Copilot 與 Cursor 的剩餘額度 |
72
- | **超輕量** | TUI 常駐記憶體 ~50 MB 以內、串流 session 解析——以 Rust 打造 |
73
- | **即時更新** | 每 10 秒自動刷新的儀表板並突顯變更 |
72
+ | **超輕量** | TUI 常駐記憶體 ~50 MB 以內、精簡的 incremental scan, 以 Rust 打造 |
73
+ | **即時更新** | 響應式 loading 與背景 refresh, 並突顯變更 |
74
74
 
75
75
  ---
76
76
 
@@ -80,7 +80,7 @@
80
80
 
81
81
  選擇最適合你的安裝方式：
82
82
 
83
- > **開發者**：如果你想從原始碼建置或參與開發，請參閱 [CONTRIBUTING.md](.github/CONTRIBUTING.md)。
83
+ > **開發者**: 如果你想從原始碼建置或參與開發, 請參閱 [CONTRIBUTING.md](.github/CONTRIBUTING.md).
84
84
 
85
85
  #### 方法一：透過 npm 安裝
86
86
 
@@ -230,11 +230,13 @@ vct usage --table --merge-providers
230
230
  │ Gemini 207K $0.40 │
231
231
  └─────────────────────────────────────────────────────────────────────────────────────────────┘
232
232
  ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
233
- │ Total Cost: $79.33 | Total Tokens: 49.3M | Models: 3 | Memory: 42.8 MB │
233
+ │ Total Cost: $79.33 | Total Tokens: 49.3M | Models: 3 | Memory: 42.8 MB | CPU: 17.9% │
234
234
  └─────────────────────────────────────────────────────────────────────────────────────────────┘
235
235
  ↑/↓ scroll m merge r refresh q quit | Star on GitHub
236
236
  ```
237
237
 
238
+ 兩個互動式儀表板都會在 terminal setup 完成後立即繪製置中的 `Loading sessions...` spinner. Loading 期間仍可處理 `q`, Ctrl+C 與 resize event. 後續掃描由單一 background worker 執行, 並在 `Refreshing...` footer 下保留上一次成功的資料. 重複的 refresh 要求最多只會合併為一個 pending scan. 如果 refresh 失敗, 儀表板會保留 last-known-good view, 並在下次排程或手動刷新時重試.
239
+
238
240
  ### 預覽：表格與 JSON（`vct usage`）
239
241
 
240
242
  `--table` 會以靜態報表印出相同的數字，並附上每個供應商的彙總；`--json` 則為每個 model 輸出一列富化資料（各自帶有 `cost_usd`），方便腳本處理。
@@ -295,6 +297,8 @@ Totals (by Provider)
295
297
 
296
298
  Grok 的 `usage` 是單一當下的本地 context 估算：vct 會把 `signals.json` 的 `contextTokensUsed` 記為 cache-read token，並以該 model 的 cache-read 費率估算費用。這不是累計的 billed usage。`analysis` 會從同層的 `updates.jsonl` 還原已完成的 Read / Write / Edit / Bash / TodoWrite 操作。Grok 不支援 quota panel 或 `vct fetch`。
297
299
 
300
+ 對於非互動式 `usage` 與 `analysis` 掃描, 如果所有找到的 source 都失敗, vct 會回傳錯誤. 如果只有部分 source 失敗, vct 會保留成功的結果, 並向 stderr 印出一則診斷摘要. TUI 則保持 best-effort, 並保留上一次成功的 payload.
301
+
298
302
  ### 即時額度面板
299
303
 
300
304
  `vct usage` 會**在儀表板中直接顯示 Claude Code、Codex、GitHub Copilot 與 Cursor 的即時剩餘額度——完全零設定。** 不需要 status-line hook，也不需要手動輸入憑證：vct 會讀取各 provider 自己的 OAuth 憑證，在背景執行緒呼叫其用量 API，並在你工作時讓面板保持最新。（想要更清爽的儀表板嗎？在 [`config.toml`](#%E8%A8%AD%E5%AE%9A) 中精簡 `[usage.quota]` 下的 `panels`,或設為 `[]` 隱藏整條。）
@@ -388,7 +392,7 @@ vct analysis --json --daily > today.json
388
392
  │ Gemini 0 0 0 0 0 0 0 0 1 │
389
393
  └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
390
394
  ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
391
- │ Total Lines: 16.1K | Total Tools: 619 | Models: 3 | Memory: 41.2 MB │
395
+ │ Total Lines: 16.1K | Total Tools: 619 | Models: 3 | Memory: 41.2 MB | CPU: 17.9% │
392
396
  └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
393
397
  ↑/↓ scroll r refresh q quit | Star on GitHub
394
398
  ```
@@ -566,6 +570,11 @@ refresh_interval = 60
566
570
  # analysis TUI 自動刷新的間隔秒數（最少 1）。
567
571
  refresh_interval = 10
568
572
 
573
+ [performance]
574
+ # CLI session scan 使用的 Rayon worker 數. 0 代表實測最佳的 auto 預設值;
575
+ # 正整數會限制在機器的 available parallelism 以內.
576
+ scan_threads = 0
577
+
569
578
  [providers]
570
579
  # 是否把各 provider 的 session 納入 usage / analysis。把某個 provider 設為 false
571
580
  # 就會完全略過它（不掃描目錄，也不呼叫 API）。
@@ -586,17 +595,18 @@ level = "warn"
586
595
  retention_days = 7
587
596
  ```
588
597
 
589
- | 設定項 | 效果 |
590
- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
591
- | `general.default_time_range` | 未指定 `--daily/--weekly/--monthly/--all` 時使用的時間範圍。明確指定的 flag 一律優先。 |
592
- | `usage.merge_models` | 讓儀表板一開始就是合併狀態;`m` 切換會把你最後的選擇存回這裡。`--merge-providers` 會強制開啟。 |
593
- | `usage.refresh_interval` | `usage` 儀表板自動刷新的間隔（秒）。 |
594
- | `usage.quota.panels` | 顯示哪些額度面板（`claude` / `codex` / `copilot` / `cursor`）；移除名稱即可隱藏,`[]` 隱藏整條。 |
595
- | `usage.quota.refresh_interval` | 每個即時額度面板的輪詢間隔（秒）；數值越大越不容易觸發 provider 的速率限制。 |
596
- | `analysis.refresh_interval` | `analysis` 儀表板自動刷新的間隔（秒）。 |
597
- | `providers.*` | 設為 `false` 時完全略過某個 provider（不掃描、不呼叫 API），沒在用的話很方便。 |
598
- | `logging.level` | 寫入日誌檔的最低等級（`off`..`trace`）；絕不會印到終端機。 |
599
- | `logging.retention_days` | 保留幾天的每日日誌檔；更舊的 `vct-*.log` 會在啟動時清除（`0` 表示全部保留）。 |
598
+ | 設定項 | 效果 |
599
+ | ------------------------------ | ------------------------------------------------------------------------------------------------------------- |
600
+ | `general.default_time_range` | 未指定 `--daily/--weekly/--monthly/--all` 時使用的時間範圍。明確指定的 flag 一律優先。 |
601
+ | `usage.merge_models` | 讓儀表板一開始就是合併狀態;`m` 切換會把你最後的選擇存回這裡。`--merge-providers` 會強制開啟。 |
602
+ | `usage.refresh_interval` | `usage` 儀表板自動刷新的間隔（秒）。 |
603
+ | `usage.quota.panels` | 顯示哪些額度面板（`claude` / `codex` / `copilot` / `cursor`）；移除名稱即可隱藏,`[]` 隱藏整條。 |
604
+ | `usage.quota.refresh_interval` | 每個即時額度面板的輪詢間隔（秒）；數值越大越不容易觸發 provider 的速率限制。 |
605
+ | `analysis.refresh_interval` | `analysis` 儀表板自動刷新的間隔（秒）。 |
606
+ | `performance.scan_threads` | CLI scan worker 數. `0` 優先採用正數的 `RAYON_NUM_THREADS`, 否則最多使用兩個 worker; 所有值都受 CPU 數量限制. |
607
+ | `providers.*` | 設為 `false` 時完全略過某個 provider（不掃描、不呼叫 API），沒在用的話很方便。 |
608
+ | `logging.level` | 寫入日誌檔的最低等級（`off`..`trace`）；絕不會印到終端機。 |
609
+ | `logging.retention_days` | 保留幾天的每日日誌檔；更舊的 `vct-*.log` 會在啟動時清除（`0` 表示全部保留）。 |
600
610
 
601
611
  > [!NOTE]
602
612
  > vct 會把診斷訊息寫入 `~/.vct/logs/vct-YYYY-MM-DD.log`（純文字，只寫檔案，絕不顯示在儀表板上）。健康運行時保持安靜（預設等級 `warn`），而且檔案是延遲建立的，所以一次正常執行不會留下任何檔案。當額度抓取失敗或某個 session 被略過時，原因就記錄在這裡——需要完整細節時把 `logging.level` 調到 `debug`。
@@ -629,10 +639,10 @@ vct config migrate
629
639
 
630
640
  ### 運作方式
631
641
 
632
- 1. **自動更新**：每日從 [LiteLLM](https://github.com/BerriAI/litellm) 取得最新價格
633
- 2. **智慧快取**：將價格資料儲存於 `~/.vct/`，有效期 24 小時
634
- 3. **模糊比對**：即使是自訂模型名稱也能找到最佳配對
635
- 4. **始終精準**：確保你取得最新的定價資訊
642
+ 1. **自動更新**: 每個 UTC 日期從 [LiteLLM](https://github.com/BerriAI/litellm) 取得一次最新價格
643
+ 2. **驗證後 cache**: 只接受成功且包含實際價格的 JSON model map, 再 atomic 寫入 `~/.vct/`
644
+ 3. **確定性比對**: 即使 model 名稱含有版本或 provider 前綴, 也會選擇最具體的配對
645
+ 4. **失敗保護**: 取得失敗不會覆蓋有效 cache, vct 會保留舊 map, 並在五分鐘 backoff 後才再次嘗試
636
646
 
637
647
  ### 模型比對
638
648
 
@@ -650,7 +660,7 @@ vct config migrate
650
660
  - **OpenCode**：只有在 LiteLLM **完全比對**成功時，才會依 token 為新型 model 計價；若沒有完全比對，vct 會採信該 assistant 訊息本身儲存的費用，而不是從名稱相近的 model 去猜測。
651
661
  - **Hermes**：與 OpenCode 相同，LiteLLM **完全比對**成功時依 token 計價，否則使用 Hermes 本身儲存的費用。
652
662
  - **Grok**：只會把 `contextTokensUsed` 當成 cache-read token 計價；這是單一當下的本地 context 估算，不是累計的 billed usage。
653
- - **原始 cache**：每日 cache 儲存的是經過篩選的上游 LiteLLM JSON（而非衍生後的結構），因此分層 / 批次定價無需重新抓取即可使用；另外一個小型的行內 LRU 會讓 TUI 刷新期間的重複查詢維持低成本。
663
+ - **原始 cache**: 每日 cache 儲存經過篩選的 LiteLLM 上游原始 JSON (而非衍生結構), 因此 tiered / batch 定價不需重新取得即可使用. 每個 pricing map 各自擁有一個小型 process-local LRU, 重複查詢維持低成本, 也不會在不同 map 之間互相污染.
654
664
 
655
665
  ---
656
666
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mai0313/vct",
3
- "version": "2.0.0",
3
+ "version": "2.1.1",
4
4
  "description": "Vibe Coding Tracker - AI coding assistant telemetry/usage parser, aggregate JSONL events into CodeAnalysis results",
5
5
  "author": "Wei Lee <mai@mai0313.com>",
6
6
  "license": "MIT",