@mai0313/vct 1.11.0 → 1.12.0

package/README.md

@@ -549,6 +549,13 @@ copilot = true
 gemini = true
 opencode = true
 cursor = true
+
+[logging]
+# Minimum level written to ~/.vct/logs/vct-YYYY-MM-DD.log.
+# One of: "off" | "error" | "warn" | "info" | "debug" | "trace".
+level = "warn"
+# Days of daily log files to keep; older files are pruned on startup. 0 keeps every file.
+retention_days = 7
 ```
 
 | Setting                        | Effect                                                                                                                       |
@@ -560,10 +567,15 @@ cursor = true
 | `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.                                        |
+| `logging.level`                | Minimum severity written to the log file (`off`..`trace`); never printed to the terminal.                                    |
+| `logging.retention_days`       | Days of daily log files to keep; older `vct-*.log` are pruned on startup (`0` keeps all).                                    |
 
 > [!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.
 
+> [!NOTE]
+> vct writes diagnostics to `~/.vct/logs/vct-YYYY-MM-DD.log` (plain text, file only — never shown in the dashboard). It stays quiet when healthy (default level `warn`) and the file is created lazily, so a healthy run leaves nothing behind. When a quota fetch fails or a session is skipped, that is where the reason is recorded — bump `logging.level` to `debug` for the full detail.
+
 ### Managing the file
 
 ```bash

package/README.zh-CN.md

@@ -548,6 +548,13 @@ copilot = true
 gemini = true
 opencode = true
 cursor = true
+
+[logging]
+# 写入 ~/.vct/logs/vct-YYYY-MM-DD.log 的最低日志级别。
+# 取值: "off" | "error" | "warn" | "info" | "debug" | "trace"。
+level = "warn"
+# 保留多少天的每日日志文件; 更旧的文件会在启动时清除。0 表示全部保留。
+retention_days = 7
 ```
 
 | 设置项                         | 作用                                                                                             |
@@ -559,6 +566,11 @@ cursor = true
 | `usage.quota.refresh_interval` | 每个实时额度面板的轮询间隔（秒）；数值越大越不容易触发 provider 的速率限制。                     |
 | `analysis.refresh_interval`    | `analysis` 面板的自动刷新间隔（秒）。                                                            |
 | `providers.*`                  | 设为 `false` 时完全跳过某个 provider（不扫描、不调用 API）——如果你不用某个 provider 会很方便。   |
+| `logging.level`                | 写入日志文件的最低级别（`off`..`trace`）；从不打印到终端。                                       |
+| `logging.retention_days`       | 保留多少天的每日日志文件；更旧的 `vct-*.log` 会在启动时清除（`0` 表示全部保留）。                |
+
+> [!NOTE]
+> vct 会把诊断信息写入 `~/.vct/logs/vct-YYYY-MM-DD.log`（纯文本，仅写文件，绝不显示在面板上）。健康运行时保持安静（默认级别 `warn`），且文件是惰性创建的，所以一次正常运行不会留下任何文件。当额度获取失败或某个 session 被跳过时，原因就记录在这里——需要完整细节时把 `logging.level` 调到 `debug`。
 
 > [!NOTE]
 > Cursor 的 `usage` 是从聊天库得出的**本地估算**，因此它会像 Claude Code / Codex / Copilot / Gemini 一样（都是从本地 session 文件计算得出）无需联网。该估算会低估 Cursor 的真实花费，因为其中很大一部分是以 Cursor 内部的 model 名称计费，本地数据无法为这些名称定价，所以请把 Cursor 费用视为近似值。

package/README.zh-TW.md

@@ -548,6 +548,13 @@ copilot = true
 gemini = true
 opencode = true
 cursor = true
+
+[logging]
+# 寫入 ~/.vct/logs/vct-YYYY-MM-DD.log 的最低日誌等級。
+# 取值: "off" | "error" | "warn" | "info" | "debug" | "trace"。
+level = "warn"
+# 保留幾天的每日日誌檔; 更舊的檔案會在啟動時清除。0 表示全部保留。
+retention_days = 7
 ```
 
 | 設定項                         | 效果                                                                                            |
@@ -559,6 +566,11 @@ cursor = true
 | `usage.quota.refresh_interval` | 每個即時額度面板的輪詢間隔（秒）；數值越大越不容易觸發 provider 的速率限制。                    |
 | `analysis.refresh_interval`    | `analysis` 儀表板自動刷新的間隔（秒）。                                                         |
 | `providers.*`                  | 設為 `false` 時完全略過某個 provider（不掃描、不呼叫 API），沒在用的話很方便。                  |
+| `logging.level`                | 寫入日誌檔的最低等級（`off`..`trace`）；絕不會印到終端機。                                      |
+| `logging.retention_days`       | 保留幾天的每日日誌檔；更舊的 `vct-*.log` 會在啟動時清除（`0` 表示全部保留）。                   |
+
+> [!NOTE]
+> vct 會把診斷訊息寫入 `~/.vct/logs/vct-YYYY-MM-DD.log`（純文字，只寫檔案，絕不顯示在儀表板上）。健康運行時保持安靜（預設等級 `warn`），而且檔案是延遲建立的，所以一次正常執行不會留下任何檔案。當額度抓取失敗或某個 session 被略過時，原因就記錄在這裡——需要完整細節時把 `logging.level` 調到 `debug`。
 
 > [!NOTE]
 > Cursor 的 `usage` 是從對話庫產生的**本地估算**，因此行為與 Claude Code / Codex / Copilot / Gemini 一致（全都是從本地 session 檔案計算），而且不需要連網。這個估算會低估 Cursor 的真實花費，因為其中有很大一部分是以 Cursor 內部的 model 名稱計費，而本地資料無法為這些名稱定價，所以請把 Cursor 的費用視為概估值。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mai0313/vct",
-  "version": "1.11.0",
+  "version": "1.12.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",