@mai0313/vct 2.2.0 → 2.2.2

package/README.md

@@ -276,12 +276,15 @@ Totals (by Provider)
       "output_tokens": 936186,
       "cache_read_input_tokens": 138099926,
       "cache_creation_input_tokens": 6057836,
-      "reasoning_output_tokens": 0
+      "reasoning_output_tokens": 0,
+      "total_tokens": 145495885
     }
   }
 ]
 ```
 
+Every row serializes the same flat token fields regardless of provider (Codex's internal nested shape is normalized before output).
+
 ### What It Scans
 
 The tool automatically scans these directories:
@@ -342,7 +345,7 @@ A panel appears only for a provider whose credentials are present. When four pan
 | `--json`                                       | Complete parser results as JSON: one object for `<FILE>`, otherwise an array of objects  |
 | `--daily` / `--weekly` / `--monthly` / `--all` | Time range filter for all-session analysis (see table above; not accepted with `<FILE>`) |
 
-See [`examples/`](examples/) for sample inputs and matching JSON outputs for the four JSONL providers, plus the Grok session fixture under [`examples/grok_session/`](examples/grok_session/).
+See [`tests/fixtures/sessions/`](tests/fixtures/sessions/) for sample inputs and matching JSON outputs for the four JSONL providers, plus the Grok session fixture under [`tests/fixtures/sessions/grok/`](tests/fixtures/sessions/grok/).
 
 ### Basic Usage
 
@@ -400,7 +403,7 @@ vct analysis --json --daily > today.json
 
 ### Preview: Table & JSON (`vct analysis`)
 
-`--table` renders the per-model breakdown plus a per-provider summary (with an Active Days column). `--text` and `--table` are compact projections of the same normalized parser records. `--json` keeps the complete records, including per-operation details and token usage. With no `<FILE>`, the outer array contains one `CodeAnalysis` object per session; with `<FILE>`, stdout is that single object and matches the corresponding shape under [`examples/`](examples/).
+`--table` renders the per-model breakdown plus a per-provider summary (with an Active Days column). `--text` and `--table` are compact projections of the same normalized parser records. `--json` keeps the complete records, including per-operation details and token usage. With no `<FILE>`, the outer array contains one `CodeAnalysis` object per session; with `<FILE>`, stdout is that single object and matches the corresponding shape under [`tests/fixtures/sessions/`](tests/fixtures/sessions/).
 
 ```text
 Analysis Statistics
@@ -656,12 +659,15 @@ vct config migrate
 4. **Fuzzy (AI-powered)**: Uses Jaro-Winkler similarity (70% threshold)
 5. **Fallback**: Shows $0.00 if no match found
 
+Generic placeholder names (e.g. `default`, what cursor-agent records for auto-mode sessions) and very short names never take a substring/fuzzy match — unpriced is safer than a coincidental neighbor's price.
+
 ### Cost Details
 
+- **Context tiers are per request**: LiteLLM's "above Nk tokens" rates (e.g. GPT-5.x above 272k, Gemini above 200k) apply only to requests whose own prompt context crossed the threshold. Providers without per-request granularity — and offline scans — bill at base rates, so tiered-model costs are a lower bound there.
 - **Beyond tokens**: Claude web-search tool calls (`server_tool_use.web_search_requests`) are billed per query on top of the token cost; every other model's per-query charge is $0.
 - **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.
 - **Hermes**: priced the same way as OpenCode — an **exact** LiteLLM match prices from tokens, otherwise vct uses Hermes's own stored cost.
-- **Grok**: `contextTokensUsed` is priced as cache-read tokens only; this is a point-in-time local context estimate, not cumulative billed usage.
+- **Grok**: `contextTokensUsed` is priced as cache-read tokens only (falling back to the input rate when the model publishes no cache-read price); this is a point-in-time local context estimate, not cumulative billed usage.
 - **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.
 
 ---

package/README.zh-CN.md

@@ -276,12 +276,15 @@ Totals (by Provider)
       "output_tokens": 936186,
       "cache_read_input_tokens": 138099926,
       "cache_creation_input_tokens": 6057836,
-      "reasoning_output_tokens": 0
+      "reasoning_output_tokens": 0,
+      "total_tokens": 145495885
     }
   }
 ]
 ```
 
+无论来源 provider 是什么，每一行都会输出相同的扁平 token 字段（Codex 内部的嵌套结构会在输出前规范化）。
+
 ### 扫描范围
 
 该工具会自动扫描以下目录：
@@ -342,7 +345,7 @@ Grok 的 `usage` 是单一时点的本地 context 估算：vct 会把 `signals.j
 | `--json`                                       | 完整 parser 结果. 搭配 `<FILE>` 时为单一 object, 否则为 object 数组          |
 | `--daily` / `--weekly` / `--monthly` / `--all` | 所有 session 的时间范围筛选. 不可与 `<FILE>` 同时使用, 其他说明见上方表格    |
 
-参见 [`examples/`](examples/) 目录，其中包含四种 JSONL provider 的示例输入与对应 JSON 输出，以及 [`examples/grok_session/`](examples/grok_session/) 下的 Grok session fixture。
+参见 [`tests/fixtures/sessions/`](tests/fixtures/sessions/) 目录，其中包含四种 JSONL provider 的示例输入与对应 JSON 输出，以及 [`tests/fixtures/sessions/grok/`](tests/fixtures/sessions/grok/) 下的 Grok session fixture。
 
 ### 基本用法
 
@@ -400,7 +403,7 @@ vct analysis --json --daily > today.json
 
 ### 预览：表格与 JSON（`vct analysis`）
 
-`--table` 会显示各 model 的明细, 并附上各 provider 的汇总, 包含 Active Days 列. `--text` 与 `--table` 都是相同 normalized parser records 的精简 projection. `--json` 会保留完整 records, 包括每次操作的 details 与 token usage. 未提供 `<FILE>` 时, 外层数组中的每个元素都是一个 session 的 `CodeAnalysis` object. 提供 `<FILE>` 时, stdout 只会输出该 object, shape 与 [`examples/`](examples/) 中对应的结果相同.
+`--table` 会显示各 model 的明细, 并附上各 provider 的汇总, 包含 Active Days 列. `--text` 与 `--table` 都是相同 normalized parser records 的精简 projection. `--json` 会保留完整 records, 包括每次操作的 details 与 token usage. 未提供 `<FILE>` 时, 外层数组中的每个元素都是一个 session 的 `CodeAnalysis` object. 提供 `<FILE>` 时, stdout 只会输出该 object, shape 与 [`tests/fixtures/sessions/`](tests/fixtures/sessions/) 中对应的结果相同.
 
 ```text
 Analysis Statistics
@@ -655,12 +658,15 @@ vct config migrate
 4. **模糊匹配（AI 驱动）**：使用 Jaro-Winkler 相似度算法（70% 阈值）
 5. **兜底方案**：如果未找到匹配，显示 $0.00
 
+通用的占位名称（例如 cursor-agent 在 auto 模式写入的 `default`）与过短的名称不会进行子串或模糊匹配——宁可不计价，也不捡相似名称的价格。
+
 ### 费用细节
 
+- **Context tier 按单个 request 计**：LiteLLM 的「above Nk tokens」费率（如 GPT-5.x 超过 272k、Gemini 超过 200k）只应用在自身 prompt context 超过阈值的那些 request 上。没有 per-request 粒度的 provider（以及离线扫描）一律按基础费率计价，因此这类 model 的费用是下界。
 - **不止 token**：Claude 的 web-search 工具调用（`server_tool_use.web_search_requests`）会在 token 费用之外按每次查询计费；其他所有 model 的每次查询费用均为 $0。
 - **OpenCode**：只有在 LiteLLM 上**精确**匹配时，才会根据 token 为一个全新的 model 名称定价；若没有精确匹配，vct 会信任该 assistant message 自身存储的费用，而不是从一个只是大致相似的名称去猜测。
 - **Hermes**：与 OpenCode 相同，LiteLLM 上**精确**匹配时按 token 定价，否则使用 Hermes 自身存储的费用。
-- **Grok**：只会把 `contextTokensUsed` 作为 cache-read token 计价；这是单一时点的本地 context 估算，不是累计的 billed usage。
+- **Grok**：只会把 `contextTokensUsed` 作为 cache-read token 计价（若该 model 未公布 cache-read 费率则改用 input 费率）；这是单一时点的本地 context 估算，不是累计的 billed usage。
 - **缓存为原始数据**: 每日 cache 保存经过筛选的 LiteLLM 上游原始 JSON (而非派生结构), 因此 tiered / batch 定价无需重新获取即可使用. 每个 pricing map 各自拥有一个小型 process-local LRU, 重复查找保持低开销, 也不会在不同 map 之间互相污染.
 
 ---

package/README.zh-TW.md

@@ -276,12 +276,15 @@ Totals (by Provider)
       "output_tokens": 936186,
       "cache_read_input_tokens": 138099926,
       "cache_creation_input_tokens": 6057836,
-      "reasoning_output_tokens": 0
+      "reasoning_output_tokens": 0,
+      "total_tokens": 145495885
     }
   }
 ]
 ```
 
+無論來源 provider 為何，每一列都會輸出相同的扁平 token 欄位（Codex 內部的巢狀結構會在輸出前正規化）。
+
 ### 掃描範圍
 
 此工具會自動掃描以下目錄：
@@ -342,7 +345,7 @@ Grok 的 `usage` 是單一當下的本地 context 估算：vct 會把 `signals.j
 | `--json`                                       | 完整 parser 結果. 搭配 `<FILE>` 時為單一 object, 否則為 object 陣列          |
 | `--daily` / `--weekly` / `--monthly` / `--all` | 所有 session 的時間範圍篩選. 不可與 `<FILE>` 同時使用, 其他說明見上方表格    |
 
-請參考 [`examples/`](examples/) 目錄，裡面有四種 JSONL provider 的範例輸入與對應的 JSON 輸出，以及 [`examples/grok_session/`](examples/grok_session/) 下的 Grok session fixture。
+請參考 [`tests/fixtures/sessions/`](tests/fixtures/sessions/) 目錄，裡面有四種 JSONL provider 的範例輸入與對應的 JSON 輸出，以及 [`tests/fixtures/sessions/grok/`](tests/fixtures/sessions/grok/) 下的 Grok session fixture。
 
 ### 基本用法
 
@@ -400,7 +403,7 @@ vct analysis --json --daily > today.json
 
 ### 預覽：表格與 JSON（`vct analysis`）
 
-`--table` 會顯示各 model 的明細, 並附上各 provider 的摘要, 包含 Active Days 欄位. `--text` 與 `--table` 都是相同 normalized parser records 的精簡 projection. `--json` 會保留完整 records, 包括每次操作的 details 與 token usage. 未提供 `<FILE>` 時, 外層陣列中的每個元素都是一個 session 的 `CodeAnalysis` object. 提供 `<FILE>` 時, stdout 只會輸出該 object, shape 與 [`examples/`](examples/) 中對應的結果相同.
+`--table` 會顯示各 model 的明細, 並附上各 provider 的摘要, 包含 Active Days 欄位. `--text` 與 `--table` 都是相同 normalized parser records 的精簡 projection. `--json` 會保留完整 records, 包括每次操作的 details 與 token usage. 未提供 `<FILE>` 時, 外層陣列中的每個元素都是一個 session 的 `CodeAnalysis` object. 提供 `<FILE>` 時, stdout 只會輸出該 object, shape 與 [`tests/fixtures/sessions/`](tests/fixtures/sessions/) 中對應的結果相同.
 
 ```text
 Analysis Statistics
@@ -655,12 +658,15 @@ vct config migrate
 4. **模糊比對（AI 驅動）**：使用 Jaro-Winkler 相似度（70% 門檻值）
 5. **備援方案**：若無法配對則顯示 $0.00
 
+泛用的佔位名稱（例如 cursor-agent 在 auto 模式寫入的 `default`）與過短的名稱不會進行子字串或模糊比對——寧可不計價，也不撿相似名稱的價格。
+
 ### 費用細節
 
+- **Context tier 以單一 request 計**：LiteLLM 的「above Nk tokens」費率（如 GPT-5.x 超過 272k、Gemini 超過 200k）只套用在自身 prompt context 超過門檻的那些 request 上。沒有 per-request 粒度的 provider（以及離線掃描）一律以基本費率計價，因此這類 model 的費用是下界。
 - **不只 token**：Claude 的網頁搜尋工具呼叫（`server_tool_use.web_search_requests`）會在 token 費用之外，按每次查詢計費；其他所有 model 的每次查詢費用皆為 $0。
 - **OpenCode**：只有在 LiteLLM **完全比對**成功時，才會依 token 為新型 model 計價；若沒有完全比對，vct 會採信該 assistant 訊息本身儲存的費用，而不是從名稱相近的 model 去猜測。
 - **Hermes**：與 OpenCode 相同，LiteLLM **完全比對**成功時依 token 計價，否則使用 Hermes 本身儲存的費用。
-- **Grok**：只會把 `contextTokensUsed` 當成 cache-read token 計價；這是單一當下的本地 context 估算，不是累計的 billed usage。
+- **Grok**：只會把 `contextTokensUsed` 當成 cache-read token 計價（若該 model 沒有公布 cache-read 費率則改用 input 費率）；這是單一當下的本地 context 估算，不是累計的 billed usage。
 - **原始 cache**: 每日 cache 儲存經過篩選的 LiteLLM 上游原始 JSON (而非衍生結構), 因此 tiered / batch 定價不需重新取得即可使用. 每個 pricing map 各自擁有一個小型 process-local LRU, 重複查詢維持低成本, 也不會在不同 map 之間互相污染.
 
 ---

package/package.json

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