@mai0313/vct 1.8.0 → 1.9.0

package/README.md

@@ -294,7 +294,7 @@ The tool automatically scans these directories:
 
 ### Live Quota Panels
 
-`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 `quota_panels` in [`config.toml`](#configuration), or set it to `[]` to hide the band.)
+`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.)
 
 ```
 ┌ Claude ─────────────────┐┌ Codex ──────────────────┐┌ Copilot ────────────────┐┌ Cursor ─────────────────┐
@@ -511,27 +511,33 @@ vct fetch copilot --table
 
 ## Configuration
 
-vct keeps its user settings in `~/.vct/config.toml`. The file is **created with defaults on first run**, so you never have to write it by hand — edit it only when you want to change a default.
+vct keeps its user settings in `~/.vct/config.toml`. The file is **created with defaults on first run**, so you never have to write it by hand — edit it only when you want to change a default. It is generated from vct's typed settings and carries a `#:schema` directive on the first line, so a schema-aware TOML editor (taplo / VS Code "Even Better TOML") gives you autocomplete and validation. Print the schema yourself with `vct config schema`.
 
 ```toml
+#:schema https://raw.githubusercontent.com/Mai0313/VibeCodingTracker/main/vct.schema.json
+
 [general]
 # Default time range when no --daily/--weekly/--monthly/--all flag is given.
-# one of: "daily" | "weekly" | "monthly" | "all"
+# One of: "daily" | "weekly" | "monthly" | "all".
 default_time_range = "all"
 
 [usage]
 # Start the usage dashboard with models merged across provider prefixes.
 # Toggled live with `m`; the last state is saved back here.
 merge_models = false
-# Which live quota panels to show in the usage TUI. Remove a name to hide that
-# panel; use an empty list ([]) to hide the whole band.
-quota_panels = ["claude", "codex", "copilot", "cursor"]
-# Seconds between automatic refreshes of the usage TUI (minimum 1).
-refresh_interval_secs = 10
+# Seconds between automatic redraws of the usage TUI (minimum 1).
+refresh_interval = 10
+
+[usage.quota]
+# Which live quota panels to show. Remove a name to hide that panel; use an
+# empty list ([]) to hide the whole band.
+panels = ["claude", "codex", "copilot", "cursor"]
+# Seconds between live quota-panel polls, shared by every provider (minimum 1).
+refresh_interval = 60
 
 [analysis]
-# Seconds between automatic refreshes of the analysis TUI (minimum 1).
-refresh_interval_secs = 10
+# Seconds between automatic redraws of the analysis TUI (minimum 1).
+refresh_interval = 10
 
 [providers]
 # Include each provider's sessions in usage / analysis. Set a provider to false
@@ -544,14 +550,15 @@ opencode = true
 cursor = true
 ```
 
-| Setting                          | Effect                                                                                                                       |
-| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `general.default_time_range`     | Period used when you pass no `--daily/--weekly/--monthly/--all`. An explicit flag always wins.                               |
-| `usage.merge_models`             | Seeds the dashboard merged; the `m` toggle saves your last choice back here. `--merge-providers` forces on.                  |
-| `usage.quota_panels`             | Which quota panels to show (`claude` / `codex` / `copilot` / `cursor`); drop a name to hide it, `[]` to hide the whole band. |
-| `usage.refresh_interval_secs`    | Auto-refresh cadence of the `usage` dashboard (seconds).                                                                     |
-| `analysis.refresh_interval_secs` | Auto-refresh cadence of the `analysis` dashboard (seconds).                                                                  |
-| `providers.*`                    | Skip a provider entirely (no scan, no API) when `false` — handy if you don't use one.                                        |
+| Setting                        | Effect                                                                                                                       |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| `general.default_time_range`   | Period used when you pass no `--daily/--weekly/--monthly/--all`. An explicit flag always wins.                               |
+| `usage.merge_models`           | Seeds the dashboard merged; the `m` toggle saves your last choice back here. `--merge-providers` forces on.                  |
+| `usage.refresh_interval`       | Redraw cadence of the `usage` dashboard (seconds).                                                                           |
+| `usage.quota.panels`           | Which quota panels to show (`claude` / `codex` / `copilot` / `cursor`); drop a name to hide it, `[]` to hide the whole band. |
+| `usage.quota.refresh_interval` | Poll cadence for every live quota panel (seconds); higher is safer against a provider's rate limits.                         |
+| `analysis.refresh_interval`    | Redraw cadence of the `analysis` dashboard (seconds).                                                                        |
+| `providers.*`                  | Skip a provider entirely (no scan, no API) when `false` — handy if you don't use one.                                        |
 
 > [!NOTE]
 > Cursor `usage` is a **local estimate** from the chat stores, so it behaves like Claude Code / Codex / Copilot / Gemini (all computed from local session files) and needs no network. It undercounts Cursor's real spend, because much of it is billed under Cursor-internal model names the local data cannot price — treat Cursor cost as approximate.
@@ -567,6 +574,9 @@ vct config show
 
 # Open the file in $VISUAL / $EDITOR (falls back to vi / notepad)
 vct config edit
+
+# Print the JSON schema (regenerate with: vct config schema > vct.schema.json)
+vct config schema
 ```
 
 ---

package/README.zh-CN.md

@@ -294,7 +294,7 @@ Totals (by Provider)
 
 ### 实时额度面板
 
-`vct usage` 会**在仪表盘中直接显示 Claude Code、Codex、GitHub Copilot 与 Cursor 的实时剩余额度——完全零配置。** 不需要 status-line hook，也无需手动输入任何凭证：vct 会读取各 provider 自己的 OAuth 凭证，在后台线程调用其用量 API，并在你工作时保持面板持续更新。（想要更清爽的面板？在 [`config.toml`](#%E9%85%8D%E7%BD%AE) 中精简 `quota_panels`，或设为 `[]` 隐藏整栏。）
+`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`，或设为 `[]` 隐藏整栏。）
 
 ```
 ┌ Claude ─────────────────┐┌ Codex ──────────────────┐┌ Copilot ────────────────┐┌ Cursor ─────────────────┐
@@ -511,9 +511,11 @@ vct fetch copilot --table
 
 ## 配置
 
-vct 会把用户设置保存在 `~/.vct/config.toml` 中。该文件会在**首次运行时以默认值自动生成**，因此你完全不必手动编写——只有想修改某个默认值时才编辑它。
+vct 会把用户设置保存在 `~/.vct/config.toml` 中。该文件会在**首次运行时以默认值自动生成**，因此你完全不必手动编写——只有想修改某个默认值时才编辑它。它由 vct 的类型化设置生成，并在第一行带有 `#:schema` 指令，因此支持 schema 的 TOML 编辑器（taplo / VS Code 的 "Even Better TOML"）会提供自动补全与校验。你也可以用 `vct config schema` 自行打印该 schema。
 
 ```toml
+#:schema https://raw.githubusercontent.com/Mai0313/VibeCodingTracker/main/vct.schema.json
+
 [general]
 # 未指定 --daily/--weekly/--monthly/--all flag 时使用的默认时间范围
 # 取值之一: "daily" | "weekly" | "monthly" | "all"
@@ -523,14 +525,18 @@ default_time_range = "all"
 # 启动 usage 面板时就把跨 provider 前缀的 model 合并显示
 # 可用 `m` 实时切换, 最后一次的状态会保存回这里
 merge_models = false
-# 在 usage TUI 中显示哪些实时额度面板; 删除某个名称即可隐藏该面板, 用空列表 ([]) 隐藏整栏
-quota_panels = ["claude", "codex", "copilot", "cursor"]
 # usage TUI 自动刷新的间隔秒数 (最小为 1)
-refresh_interval_secs = 10
+refresh_interval = 10
+
+[usage.quota]
+# 显示哪些实时额度面板; 删除某个名称即可隐藏该面板, 用空列表 ([]) 隐藏整栏
+panels = ["claude", "codex", "copilot", "cursor"]
+# 每个 provider 共用的实时额度面板轮询间隔秒数 (最小为 1)
+refresh_interval = 60
 
 [analysis]
 # analysis TUI 自动刷新的间隔秒数 (最小为 1)
-refresh_interval_secs = 10
+refresh_interval = 10
 
 [providers]
 # 是否把各 provider 的 session 纳入 usage / analysis, 设为 false
@@ -543,14 +549,15 @@ opencode = true
 cursor = true
 ```
 
-| 设置项                           | 作用                                                                                             |
-| -------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `general.default_time_range`     | 当你没有传入 `--daily/--weekly/--monthly/--all` 时使用的时间范围。显式传入的 flag 始终优先。     |
-| `usage.merge_models`             | 让面板启动时就处于合并状态；`m` 切换会把你上次的选择保存回这里。`--merge-providers` 会强制开启。 |
-| `usage.quota_panels`             | 显示哪些额度面板（`claude` / `codex` / `copilot` / `cursor`）；删除名称即可隐藏，`[]` 隐藏整栏。 |
-| `usage.refresh_interval_secs`    | `usage` 面板的自动刷新间隔（秒）。                                                               |
-| `analysis.refresh_interval_secs` | `analysis` 面板的自动刷新间隔（秒）。                                                            |
-| `providers.*`                    | 设为 `false` 时完全跳过某个 provider（不扫描、不调用 API）——如果你不用某个 provider 会很方便。   |
+| 设置项                         | 作用                                                                                             |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| `general.default_time_range`   | 当你没有传入 `--daily/--weekly/--monthly/--all` 时使用的时间范围。显式传入的 flag 始终优先。     |
+| `usage.merge_models`           | 让面板启动时就处于合并状态；`m` 切换会把你上次的选择保存回这里。`--merge-providers` 会强制开启。 |
+| `usage.refresh_interval`       | `usage` 面板的自动刷新间隔（秒）。                                                               |
+| `usage.quota.panels`           | 显示哪些额度面板（`claude` / `codex` / `copilot` / `cursor`）；删除名称即可隐藏，`[]` 隐藏整栏。 |
+| `usage.quota.refresh_interval` | 每个实时额度面板的轮询间隔（秒）；数值越大越不容易触发 provider 的速率限制。                     |
+| `analysis.refresh_interval`    | `analysis` 面板的自动刷新间隔（秒）。                                                            |
+| `providers.*`                  | 设为 `false` 时完全跳过某个 provider（不扫描、不调用 API）——如果你不用某个 provider 会很方便。   |
 
 > [!NOTE]
 > Cursor 的 `usage` 是从聊天库得出的**本地估算**，因此它会像 Claude Code / Codex / Copilot / Gemini 一样（都是从本地 session 文件计算得出）无需联网。该估算会低估 Cursor 的真实花费，因为其中很大一部分是以 Cursor 内部的 model 名称计费，本地数据无法为这些名称定价，所以请把 Cursor 费用视为近似值。
@@ -566,6 +573,9 @@ vct config show
 
 # 在 $VISUAL / $EDITOR 中打开文件 (回退到 vi / notepad)
 vct config edit
+
+# 打印 JSON schema (可用以下命令重新生成: vct config schema > vct.schema.json)
+vct config schema
 ```
 
 ---

package/README.zh-TW.md

@@ -294,7 +294,7 @@ Totals (by Provider)
 
 ### 即時額度面板
 
-`vct usage` 會**在儀表板中直接顯示 Claude Code、Codex、GitHub Copilot 與 Cursor 的即時剩餘額度——完全零設定。** 不需要 status-line hook，也不需要手動輸入憑證：vct 會讀取各 provider 自己的 OAuth 憑證，在背景執行緒呼叫其用量 API，並在你工作時讓面板保持最新。（想要更清爽的儀表板嗎？在 [`config.toml`](#%E8%A8%AD%E5%AE%9A) 中精簡 `quota_panels`,或設為 `[]` 隱藏整條。）
+`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`,或設為 `[]` 隱藏整條。）
 
 ```
 ┌ Claude ─────────────────┐┌ Codex ──────────────────┐┌ Copilot ────────────────┐┌ Cursor ─────────────────┐
@@ -511,9 +511,11 @@ vct fetch copilot --table
 
 ## 設定
 
-vct 會把使用者設定存放在 `~/.vct/config.toml`。這個檔案會在**首次執行時以預設值自動建立**，所以你完全不必手動撰寫，只有想更改某個預設值時才需要編輯它。
+vct 會把使用者設定存放在 `~/.vct/config.toml`。這個檔案會在**首次執行時以預設值自動建立**，所以你完全不必手動撰寫，只有想更改某個預設值時才需要編輯它。它由 vct 的型別化設定產生，並在第一行帶有 `#:schema` 指令，因此支援 schema 的 TOML 編輯器（taplo / VS Code 的 "Even Better TOML"）會提供自動補全與驗證。你也可以用 `vct config schema` 自行印出該 schema。
 
 ```toml
+#:schema https://raw.githubusercontent.com/Mai0313/VibeCodingTracker/main/vct.schema.json
+
 [general]
 # 未指定 --daily/--weekly/--monthly/--all flag 時使用的預設時間範圍。
 # 可選值："daily" | "weekly" | "monthly" | "all"
@@ -523,14 +525,18 @@ default_time_range = "all"
 # 啟動 usage 儀表板時，是否先把不同 provider 前綴的 model 合併。
 # 可用 `m` 即時切換;最後的狀態會存回這裡。
 merge_models = false
-# 在 usage TUI 中顯示哪些即時額度面板;移除某個名稱即可隱藏該面板,用空列表 ([]) 隱藏整條。
-quota_panels = ["claude", "codex", "copilot", "cursor"]
 # usage TUI 自動刷新的間隔秒數（最少 1）。
-refresh_interval_secs = 10
+refresh_interval = 10
+
+[usage.quota]
+# 顯示哪些即時額度面板;移除某個名稱即可隱藏該面板,用空列表 ([]) 隱藏整條。
+panels = ["claude", "codex", "copilot", "cursor"]
+# 每個 provider 共用的即時額度面板輪詢間隔秒數（最少 1）。
+refresh_interval = 60
 
 [analysis]
 # analysis TUI 自動刷新的間隔秒數（最少 1）。
-refresh_interval_secs = 10
+refresh_interval = 10
 
 [providers]
 # 是否把各 provider 的 session 納入 usage / analysis。把某個 provider 設為 false
@@ -543,14 +549,15 @@ opencode = true
 cursor = true
 ```
 
-| 設定項                           | 效果                                                                                            |
-| -------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `general.default_time_range`     | 未指定 `--daily/--weekly/--monthly/--all` 時使用的時間範圍。明確指定的 flag 一律優先。          |
-| `usage.merge_models`             | 讓儀表板一開始就是合併狀態;`m` 切換會把你最後的選擇存回這裡。`--merge-providers` 會強制開啟。   |
-| `usage.quota_panels`             | 顯示哪些額度面板（`claude` / `codex` / `copilot` / `cursor`）；移除名稱即可隱藏,`[]` 隱藏整條。 |
-| `usage.refresh_interval_secs`    | `usage` 儀表板自動刷新的間隔（秒）。                                                            |
-| `analysis.refresh_interval_secs` | `analysis` 儀表板自動刷新的間隔（秒）。                                                         |
-| `providers.*`                    | 設為 `false` 時完全略過某個 provider（不掃描、不呼叫 API），沒在用的話很方便。                  |
+| 設定項                         | 效果                                                                                            |
+| ------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `general.default_time_range`   | 未指定 `--daily/--weekly/--monthly/--all` 時使用的時間範圍。明確指定的 flag 一律優先。          |
+| `usage.merge_models`           | 讓儀表板一開始就是合併狀態;`m` 切換會把你最後的選擇存回這裡。`--merge-providers` 會強制開啟。   |
+| `usage.refresh_interval`       | `usage` 儀表板自動刷新的間隔（秒）。                                                            |
+| `usage.quota.panels`           | 顯示哪些額度面板（`claude` / `codex` / `copilot` / `cursor`）；移除名稱即可隱藏,`[]` 隱藏整條。 |
+| `usage.quota.refresh_interval` | 每個即時額度面板的輪詢間隔（秒）；數值越大越不容易觸發 provider 的速率限制。                    |
+| `analysis.refresh_interval`    | `analysis` 儀表板自動刷新的間隔（秒）。                                                         |
+| `providers.*`                  | 設為 `false` 時完全略過某個 provider（不掃描、不呼叫 API），沒在用的話很方便。                  |
 
 > [!NOTE]
 > Cursor 的 `usage` 是從對話庫產生的**本地估算**，因此行為與 Claude Code / Codex / Copilot / Gemini 一致（全都是從本地 session 檔案計算），而且不需要連網。這個估算會低估 Cursor 的真實花費，因為其中有很大一部分是以 Cursor 內部的 model 名稱計費，而本地資料無法為這些名稱定價，所以請把 Cursor 的費用視為概估值。
@@ -566,6 +573,9 @@ vct config show
 
 # 用 $VISUAL / $EDITOR 開啟檔案（找不到時回退到 vi / notepad）
 vct config edit
+
+# 印出 JSON schema（可用以下指令重新產生：vct config schema > vct.schema.json）
+vct config schema
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mai0313/vct",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Vibe Coding Tracker - AI coding assistant telemetry/usage parser, aggregate JSONL events into CodeAnalysis results",
   "author": "Wei Lee <mai@mai0313.com>",
   "license": "MIT",