@mai0313/vct 0.5.12 → 0.5.13

package/README.md

@@ -146,12 +146,31 @@ Commands:
   help        Print this message or the help of the given subcommand(s)
 ```
 
+Time range flags (shared by `usage` and `analysis`, mutually exclusive, default `--all`):
+
+| Flag        | Window                            |
+| ----------- | --------------------------------- |
+| `--daily`   | Sessions modified today           |
+| `--weekly`  | Current ISO week (Monday → today) |
+| `--monthly` | Current calendar month            |
+| `--all`     | Every session on disk (default)   |
+
 ---
 
 ## 💰 Usage Command
 
 **Track your spending across all AI coding sessions.**
 
+### Flags
+
+| Flag                                           | Purpose                             |
+| ---------------------------------------------- | ----------------------------------- |
+| *(none)*                                       | Interactive TUI dashboard (default) |
+| `--table`                                      | Static table, no TUI                |
+| `--text`                                       | Plain text, script-friendly         |
+| `--json`                                       | JSON with enriched pricing metadata |
+| `--daily` / `--weekly` / `--monthly` / `--all` | Time range filter (see table above) |
+
 ### Basic Usage
 
 ```bash
@@ -164,10 +183,18 @@ vct usage --table
 # Plain text for scripts
 vct usage --text
 
-# JSON for data processing
+# JSON for data processing (includes cost_usd and matched_model fields)
 vct usage --json
+
+# Combine time range with output format
+vct usage --weekly
+vct usage --table --monthly
+vct usage --json --daily
 ```
 
+> [!NOTE]
+> Model rows are sorted by cost in ascending order, so the highest-spending model sits right above the `TOTAL` row. This applies to the interactive dashboard, `--table`, and `--text` output; `--json` preserves the same order.
+
 ### Preview: Interactive Dashboard (`vct usage`)
 
 ```
@@ -177,9 +204,9 @@ vct usage --json
 ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
 │ Model                              Input     Output    Cache Read  Cache Create  Total Cost │
 │                                                                                             │
+│ gemini-3.1-pro-preview             129,115   10,339    67,385      0             $0.40      │
 │ claude-haiku-4-5-20251001          5,567     19,769    4,627,938   619,816       $1.34      │
 │ claude-opus-4-6                    25,651    179,066   40,830,154  2,572,258     $77.59     │
-│ gemini-3.1-pro-preview             129,115   10,339    67,385      0             $0.40      │
 │ TOTAL                              160,333   209,174   45,525,477  3,192,074     $79.33     │
 └─────────────────────────────────────────────────────────────────────────────────────────────┘
 ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
@@ -210,6 +237,19 @@ The tool automatically scans these directories:
 
 **Deep dive into code operations — see exactly what your AI assistant did.**
 
+### Flags
+
+| Flag                                           | Purpose                                                            |
+| ---------------------------------------------- | ------------------------------------------------------------------ |
+| *(none)*                                       | Interactive TUI dashboard over all sessions                        |
+| `--path <FILE>`                                | Analyze a single JSONL/JSON conversation file (prints JSON)        |
+| `--table`                                      | Static table with per-provider daily averages                      |
+| `--output <FILE>`                              | Save results as pretty-printed JSON                                |
+| `--by-provider`                                | Group rows by provider (claude / codex / copilot / gemini) as JSON |
+| `--daily` / `--weekly` / `--monthly` / `--all` | Time range filter (see table above)                                |
+
+See [`examples/`](examples/) for sample inputs and matching JSON outputs for all four providers.
+
 ### Basic Usage
 
 ```bash
@@ -219,17 +259,22 @@ vct analysis
 # Static table output with daily averages
 vct analysis --table
 
-# Analyze a single conversation file
+# Analyze a single conversation file → stdout JSON
 vct analysis --path ~/.claude/projects/session.jsonl
 
 # Save results to JSON
 vct analysis --output report.json
 
 # Group results by provider
-vct analysis --all
+vct analysis --by-provider
 
 # Save grouped results
-vct analysis --all --output grouped_report.json
+vct analysis --by-provider --output grouped_report.json
+
+# Combine time range with output format
+vct analysis --weekly
+vct analysis --table --monthly
+vct analysis --by-provider --daily --output today.json
 ```
 
 ### Preview: Interactive Dashboard (`vct analysis`)
@@ -290,6 +335,20 @@ vct update --force
 
 ---
 
+## 🏷️ Version Command
+
+Report the embedded build metadata (binary version, Rust toolchain, Cargo version):
+
+```bash
+vct version          # Pretty table
+vct version --text   # One-field-per-line, script-friendly
+vct version --json   # Machine-readable JSON
+```
+
+The binary version is produced at build time by `build.rs` from `git describe`, so development builds include commit count + short SHA + `dirty` suffix when applicable.
+
+---
+
 ## 💡 Smart Pricing System
 
 ### How It Works

package/README.zh-CN.md

@@ -146,12 +146,31 @@ Commands:
   help        Print this message or the help of the given subcommand(s)
 ```
 
+时间范围 flag（`usage` 与 `analysis` 共用，互斥，默认 `--all`）：
+
+| Flag        | 范围                         |
+| ----------- | ---------------------------- |
+| `--daily`   | 今天更新过的 session         |
+| `--weekly`  | 本 ISO 周（周一 → 今天）     |
+| `--monthly` | 本自然月                     |
+| `--all`     | 磁盘上所有 session（默认值） |
+
 ---
 
 ## 💰 Usage 命令
 
 **追踪你在所有 AI 编程会话中的开销。**
 
+### Flag 一览
+
+| Flag                                           | 用途                       |
+| ---------------------------------------------- | -------------------------- |
+| *(不带参数)*                                   | 互动式 TUI 面板（默认）    |
+| `--table`                                      | 静态表格，不启动 TUI       |
+| `--text`                                       | 纯文本，适合脚本处理       |
+| `--json`                                       | JSON 输出，附带定价信息    |
+| `--daily` / `--weekly` / `--monthly` / `--all` | 时间范围筛选（见上方表格） |
+
 ### 基本用法
 
 ```bash
@@ -164,10 +183,18 @@ vct usage --table
 # Plain text for scripts
 vct usage --text
 
-# JSON for data processing
+# JSON 输出，包含 cost_usd 与 matched_model 字段
 vct usage --json
+
+# 时间范围与输出格式可自由组合
+vct usage --weekly
+vct usage --table --monthly
+vct usage --json --daily
 ```
 
+> [!NOTE]
+> Model 行会按 cost 升序排序，因此花费最高的 model 会紧邻在 `TOTAL` 行上方。该排序适用于交互式面板、`--table` 与 `--text` 三种输出；`--json` 也会保持相同顺序。
+
 ### 预览：交互式面板（`vct usage`）
 
 ```
@@ -177,9 +204,9 @@ vct usage --json
 ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
 │ Model                              Input     Output    Cache Read  Cache Create  Total Cost │
 │                                                                                             │
+│ gemini-3.1-pro-preview             129,115   10,339    67,385      0             $0.40      │
 │ claude-haiku-4-5-20251001          5,567     19,769    4,627,938   619,816       $1.34      │
 │ claude-opus-4-6                    25,651    179,066   40,830,154  2,572,258     $77.59     │
-│ gemini-3.1-pro-preview             129,115   10,339    67,385      0             $0.40      │
 │ TOTAL                              160,333   209,174   45,525,477  3,192,074     $79.33     │
 └─────────────────────────────────────────────────────────────────────────────────────────────┘
 ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
@@ -210,6 +237,19 @@ vct usage --json
 
 **深入了解代码操作——查看你的 AI 助手到底做了什么。**
 
+### Flag 一览
+
+| Flag                                           | 用途                                                            |
+| ---------------------------------------------- | --------------------------------------------------------------- |
+| *(不带参数)*                                   | 互动式 TUI 面板，覆盖所有 session                               |
+| `--path <FILE>`                                | 分析单一 JSONL/JSON 对话文件（stdout 输出 JSON）                |
+| `--table`                                      | 静态表格，附带每日平均值                                        |
+| `--output <FILE>`                              | 将结果以格式化 JSON 保存到文件                                  |
+| `--by-provider`                                | 按 provider（claude / codex / copilot / gemini）分组并输出 JSON |
+| `--daily` / `--weekly` / `--monthly` / `--all` | 时间范围筛选（见上方表格）                                      |
+
+参见 [`examples/`](examples/) 目录，其中包含四种 provider 的示例输入与对应 JSON 输出。
+
 ### 基本用法
 
 ```bash
@@ -219,17 +259,22 @@ vct analysis
 # Static table output with daily averages
 vct analysis --table
 
-# Analyze a single conversation file
+# 分析单一对话文件 → stdout JSON
 vct analysis --path ~/.claude/projects/session.jsonl
 
 # Save results to JSON
 vct analysis --output report.json
 
 # Group results by provider
-vct analysis --all
+vct analysis --by-provider
 
 # Save grouped results
-vct analysis --all --output grouped_report.json
+vct analysis --by-provider --output grouped_report.json
+
+# 时间范围与输出格式可自由组合
+vct analysis --weekly
+vct analysis --table --monthly
+vct analysis --by-provider --daily --output today.json
 ```
 
 ### 预览：交互式面板（`vct analysis`）
@@ -290,6 +335,20 @@ vct update --force
 
 ---
 
+## 🏷️ Version 命令
+
+查看内置的构建信息（binary version、Rust toolchain、Cargo version）：
+
+```bash
+vct version          # 彩色表格
+vct version --text   # 每行一个字段，适合脚本
+vct version --json   # 机读 JSON
+```
+
+Binary version 由 `build.rs` 在编译期通过 `git describe` 写入，开发版本会附带 commit 计数、short SHA 与 `dirty` 后缀。
+
+---
+
 ## 💡 智能定价系统
 
 ### 工作原理

package/README.zh-TW.md

@@ -146,12 +146,31 @@ Commands:
   help        Print this message or the help of the given subcommand(s)
 ```
 
+時間範圍 flag（`usage` 與 `analysis` 共用，互斥，預設 `--all`）：
+
+| Flag        | 範圍                       |
+| ----------- | -------------------------- |
+| `--daily`   | 今天更新過的 session       |
+| `--weekly`  | 本 ISO 週（週一 → 今天）   |
+| `--monthly` | 本自然月                   |
+| `--all`     | 磁碟上所有 session（預設） |
+
 ---
 
 ## 💰 Usage 指令
 
 **追蹤你在所有 AI 程式設計工作階段的花費。**
 
+### Flag 一覽
+
+| Flag                                           | 用途                         |
+| ---------------------------------------------- | ---------------------------- |
+| *(不帶參數)*                                   | 互動式 TUI 儀表板（預設）    |
+| `--table`                                      | 靜態表格，不啟動 TUI         |
+| `--text`                                       | 純文字，適合腳本處理         |
+| `--json`                                       | JSON 輸出，附帶 pricing 資訊 |
+| `--daily` / `--weekly` / `--monthly` / `--all` | 時間範圍篩選（見上方表格）   |
+
 ### 基本用法
 
 ```bash
@@ -164,10 +183,18 @@ vct usage --table
 # Plain text for scripts
 vct usage --text
 
-# JSON for data processing
+# JSON 輸出，包含 cost_usd 與 matched_model 欄位
 vct usage --json
+
+# 時間範圍與輸出格式可自由組合
+vct usage --weekly
+vct usage --table --monthly
+vct usage --json --daily
 ```
 
+> [!NOTE]
+> Model 列會依 cost 由小到大排序，所以花費最高的 model 會緊鄰在 `TOTAL` 列上方。這個排序會套用到互動式儀表板、`--table` 與 `--text` 三種輸出；`--json` 也會保持相同順序。
+
 ### 預覽：互動式儀表板（`vct usage`）
 
 ```
@@ -177,9 +204,9 @@ vct usage --json
 ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
 │ Model                              Input     Output    Cache Read  Cache Create  Total Cost │
 │                                                                                             │
+│ gemini-3.1-pro-preview             129,115   10,339    67,385      0             $0.40      │
 │ claude-haiku-4-5-20251001          5,567     19,769    4,627,938   619,816       $1.34      │
 │ claude-opus-4-6                    25,651    179,066   40,830,154  2,572,258     $77.59     │
-│ gemini-3.1-pro-preview             129,115   10,339    67,385      0             $0.40      │
 │ TOTAL                              160,333   209,174   45,525,477  3,192,074     $79.33     │
 └─────────────────────────────────────────────────────────────────────────────────────────────┘
 ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
@@ -210,6 +237,19 @@ vct usage --json
 
 **深入分析程式碼操作——精確掌握你的 AI 助手做了哪些事。**
 
+### Flag 一覽
+
+| Flag                                           | 用途                                                            |
+| ---------------------------------------------- | --------------------------------------------------------------- |
+| *(不帶參數)*                                   | 互動式 TUI 儀表板，涵蓋所有 session                             |
+| `--path <FILE>`                                | 分析單一 JSONL/JSON 對話檔案（stdout 輸出 JSON）                |
+| `--table`                                      | 靜態表格，附帶每日平均值                                        |
+| `--output <FILE>`                              | 將結果以格式化 JSON 存成檔案                                    |
+| `--by-provider`                                | 依 provider（claude / codex / copilot / gemini）分組並輸出 JSON |
+| `--daily` / `--weekly` / `--monthly` / `--all` | 時間範圍篩選（見上方表格）                                      |
+
+請參考 [`examples/`](examples/) 目錄，裡面有四種 provider 的範例輸入與對應的 JSON 輸出。
+
 ### 基本用法
 
 ```bash
@@ -219,17 +259,22 @@ vct analysis
 # Static table output with daily averages
 vct analysis --table
 
-# Analyze a single conversation file
+# 分析單一對話檔案 → stdout JSON
 vct analysis --path ~/.claude/projects/session.jsonl
 
 # Save results to JSON
 vct analysis --output report.json
 
 # Group results by provider
-vct analysis --all
+vct analysis --by-provider
 
 # Save grouped results
-vct analysis --all --output grouped_report.json
+vct analysis --by-provider --output grouped_report.json
+
+# 時間範圍與輸出格式可自由組合
+vct analysis --weekly
+vct analysis --table --monthly
+vct analysis --by-provider --daily --output today.json
 ```
 
 ### 預覽：互動式儀表板（`vct analysis`）
@@ -290,6 +335,20 @@ vct update --force
 
 ---
 
+## 🏷️ Version 指令
+
+檢視內建的建置資訊（binary version、Rust toolchain、Cargo version）：
+
+```bash
+vct version          # 彩色表格
+vct version --text   # 每行一個欄位，適合腳本
+vct version --json   # 機器可讀的 JSON
+```
+
+Binary version 由 `build.rs` 在編譯期透過 `git describe` 寫入，開發版本會附上 commit 數、short SHA 與 `dirty` 後綴。
+
+---
+
 ## 💡 智慧定價系統
 
 ### 運作方式

package/package.json

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