@mai0313/vibe-coding-tracker 0.5.11 → 0.5.13

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 +164 -42
  2. package/README.zh-CN.md +210 -88
  3. package/README.zh-TW.md +219 -97
  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
@@ -17,7 +17,7 @@
17
17
 
18
18
  </div>
19
19
 
20
- **Track your AI coding costs in real-time.** Vibe Coding Tracker is a powerful CLI tool that helps you monitor and analyze your Claude Code, Codex, Copilot, and Gemini usage, providing detailed cost breakdowns, token statistics, and code operation insights.
20
+ **Track your AI coding costs in real-time.** Vibe Coding Tracker is a lightweight, high-performance CLI tool built in Rust that monitors and analyzes your Claude Code, Codex, Copilot, and Gemini usage — with detailed cost breakdowns, token statistics, and code operation insights, all while keeping CPU and memory usage minimal.
21
21
 
22
22
  [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
23
23
 
@@ -31,6 +31,10 @@
31
31
 
32
32
  Stop wondering how much your AI coding sessions cost. Get **real-time cost tracking** with automatic pricing updates from [LiteLLM](https://github.com/BerriAI/litellm).
33
33
 
34
+ ### 🪶 Ultra-Lightweight
35
+
36
+ Built with Rust for minimal resource footprint. The interactive TUI dashboard runs at **~3-5% CPU** and **~140 MB memory** even while processing millions of tokens across multiple providers — no Electron, no bloated runtimes.
37
+
34
38
  ### 📊 Beautiful Visualizations
35
39
 
36
40
  Choose your preferred view:
@@ -42,29 +46,29 @@ Choose your preferred view:
42
46
 
43
47
  ### 🚀 Zero Configuration
44
48
 
45
- Automatically detects and processes logs from Claude Code, Codex, Copilot, and Gemini. No setup required—just run and analyze.
49
+ Automatically detects and processes logs from Claude Code, Codex, Copilot, and Gemini. No setup required — just run and analyze.
46
50
 
47
51
  ### 🎨 Rich Insights
48
52
 
49
53
  - Token usage by model and date
50
- - Cost breakdown by cache types
51
- - File operations tracking
52
- - Command execution history
53
- - Git repository information
54
+ - Cost breakdown by cache types (read / create)
55
+ - File operations tracking (edit, read, write lines)
56
+ - Tool call history (Bash, Edit, Read, Write, TodoWrite)
57
+ - Per-provider daily averages
54
58
 
55
59
  ---
56
60
 
57
61
  ## ✨ Key Features
58
62
 
59
- | Feature | Description |
60
- | -------------------------- | -------------------------------------------------------------------- |
61
- | 🤖 **Auto-Detection** | Intelligently identifies Claude Code, Codex, Copilot, or Gemini logs |
62
- | 💵 **Smart Pricing** | Fuzzy model matching + daily cache for speed |
63
- | 🎨 **4 Display Modes** | Interactive, Table, Text, and JSON outputs |
64
- | 📈 **Comprehensive Stats** | Tokens, costs, file ops, and tool calls |
65
- | ⚡ **High Performance** | Built with Rust for speed and reliability |
66
- | 🔄 **Live Updates** | Real-time dashboard refreshes every second |
67
- | 💾 **Efficient Caching** | Smart daily cache reduces API calls |
63
+ | Feature | Description |
64
+ | ------------------------ | -------------------------------------------------------------- |
65
+ | 🤖 **Multi-Provider** | Claude Code, Codex, Copilot, and Gemini — all in one place |
66
+ | 💵 **Smart Pricing** | Fuzzy model matching + daily cache from LiteLLM |
67
+ | 🎨 **4 Display Modes** | Interactive TUI, static table, plain text, and JSON |
68
+ | 📈 **Dual Analysis** | Token/cost stats (`usage`) + code operation stats (`analysis`) |
69
+ | 🪶 **Ultra-Lightweight** | ~3-5% CPU, ~140 MB RAM — built with Rust |
70
+ | 🔄 **Live Updates** | Real-time dashboard refreshes every second |
71
+ | 💾 **Efficient Caching** | Smart daily cache reduces API calls |
68
72
 
69
73
  ---
70
74
 
@@ -114,14 +118,14 @@ cargo install vibe_coding_tracker
114
118
  ### First Run
115
119
 
116
120
  ```bash
117
- # View your usage with the short alias (if available)
121
+ # View your usage with the interactive dashboard
118
122
  vct usage
119
123
 
120
124
  # Or run the binary built by Cargo/pip
121
125
  vibe_coding_tracker usage
122
126
 
123
- # Analyze a specific conversation
124
- vibe_coding_tracker analysis --path ~/.claude/projects/session.jsonl
127
+ # Analyze code operations across all sessions
128
+ vct analysis
125
129
  ```
126
130
 
127
131
  ---
@@ -130,24 +134,43 @@ vibe_coding_tracker analysis --path ~/.claude/projects/session.jsonl
130
134
 
131
135
  ### 🔍 Quick Reference
132
136
 
133
- ```bash
137
+ ```
134
138
  vct <COMMAND> [OPTIONS]
135
139
  # Replace with `vibe_coding_tracker` if you are using the full binary name
136
140
 
137
141
  Commands:
138
- analysis Analyze JSONL conversation files (single file or all sessions)
139
- usage Display token usage statistics
140
- version Display version information
141
- update Update to the latest version from GitHub releases
142
- help Print this message or the help of the given subcommand(s)
142
+ analysis Analyze JSONL conversation files (single file or all sessions)
143
+ usage Display token usage statistics
144
+ version Display version information
145
+ update Update to the latest version from GitHub releases
146
+ help Print this message or the help of the given subcommand(s)
143
147
  ```
144
148
 
149
+ Time range flags (shared by `usage` and `analysis`, mutually exclusive, default `--all`):
150
+
151
+ | Flag | Window |
152
+ | ----------- | --------------------------------- |
153
+ | `--daily` | Sessions modified today |
154
+ | `--weekly` | Current ISO week (Monday → today) |
155
+ | `--monthly` | Current calendar month |
156
+ | `--all` | Every session on disk (default) |
157
+
145
158
  ---
146
159
 
147
160
  ## 💰 Usage Command
148
161
 
149
162
  **Track your spending across all AI coding sessions.**
150
163
 
164
+ ### Flags
165
+
166
+ | Flag | Purpose |
167
+ | ---------------------------------------------- | ----------------------------------- |
168
+ | *(none)* | Interactive TUI dashboard (default) |
169
+ | `--table` | Static table, no TUI |
170
+ | `--text` | Plain text, script-friendly |
171
+ | `--json` | JSON with enriched pricing metadata |
172
+ | `--daily` / `--weekly` / `--monthly` / `--all` | Time range filter (see table above) |
173
+
151
174
  ### Basic Usage
152
175
 
153
176
  ```bash
@@ -160,13 +183,48 @@ vct usage --table
160
183
  # Plain text for scripts
161
184
  vct usage --text
162
185
 
163
- # JSON for data processing
186
+ # JSON for data processing (includes cost_usd and matched_model fields)
164
187
  vct usage --json
188
+
189
+ # Combine time range with output format
190
+ vct usage --weekly
191
+ vct usage --table --monthly
192
+ vct usage --json --daily
165
193
  ```
166
194
 
167
- ### What You Get
195
+ > [!NOTE]
196
+ > 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.
168
197
 
169
- The tool scans these directories automatically:
198
+ ### Preview: Interactive Dashboard (`vct usage`)
199
+
200
+ ```
201
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
202
+ │ 📊 Token Usage Statistics │
203
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
204
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
205
+ │ Model Input Output Cache Read Cache Create Total Cost │
206
+ │ │
207
+ │ gemini-3.1-pro-preview 129,115 10,339 67,385 0 $0.40 │
208
+ │ claude-haiku-4-5-20251001 5,567 19,769 4,627,938 619,816 $1.34 │
209
+ │ claude-opus-4-6 25,651 179,066 40,830,154 2,572,258 $77.59 │
210
+ │ TOTAL 160,333 209,174 45,525,477 3,192,074 $79.33 │
211
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
212
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
213
+ │ Provider Tokens / Day Cost / Day Active Days │
214
+ │ │
215
+ │ 🤖 Claude Code 16,293,406 $26.31 3 │
216
+ │ ✨ Gemini 206,839 $0.40 1 │
217
+ │ ⭐ All Providers 16,362,353 $26.44 3 │
218
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
219
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
220
+ │ 💰 Total: $79.33 | 🔢 Tokens: 49,087,058 | 📊 Models: 3 | ⚡ CPU: 4.6% | 🧠 Mem: 148 MB │
221
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
222
+ Press 'q', 'Esc', 'Ctrl+C' to quit | Press 'r' to refresh
223
+ ```
224
+
225
+ ### What It Scans
226
+
227
+ The tool automatically scans these directories:
170
228
 
171
229
  - `~/.claude/projects/*.jsonl` (Claude Code)
172
230
  - `~/.codex/sessions/*.jsonl` (Codex)
@@ -177,31 +235,73 @@ The tool scans these directories automatically:
177
235
 
178
236
  ## 📊 Analysis Command
179
237
 
180
- **Deep dive into conversation files - single file or batch analysis.**
238
+ **Deep dive into code operations — see exactly what your AI assistant did.**
239
+
240
+ ### Flags
241
+
242
+ | Flag | Purpose |
243
+ | ---------------------------------------------- | ------------------------------------------------------------------ |
244
+ | *(none)* | Interactive TUI dashboard over all sessions |
245
+ | `--path <FILE>` | Analyze a single JSONL/JSON conversation file (prints JSON) |
246
+ | `--table` | Static table with per-provider daily averages |
247
+ | `--output <FILE>` | Save results as pretty-printed JSON |
248
+ | `--by-provider` | Group rows by provider (claude / codex / copilot / gemini) as JSON |
249
+ | `--daily` / `--weekly` / `--monthly` / `--all` | Time range filter (see table above) |
250
+
251
+ See [`examples/`](examples/) for sample inputs and matching JSON outputs for all four providers.
181
252
 
182
253
  ### Basic Usage
183
254
 
184
255
  ```bash
185
- # Single file: Analyze and display
256
+ # Interactive dashboard for all sessions (default)
257
+ vct analysis
258
+
259
+ # Static table output with daily averages
260
+ vct analysis --table
261
+
262
+ # Analyze a single conversation file → stdout JSON
186
263
  vct analysis --path ~/.claude/projects/session.jsonl
187
264
 
188
- # Single file: Save to file
189
- vct analysis --path ~/.claude/projects/session.jsonl --output report.json
265
+ # Save results to JSON
266
+ vct analysis --output report.json
190
267
 
191
- # Batch: Analyze all sessions with interactive table (default)
192
- vct analysis
268
+ # Group results by provider
269
+ vct analysis --by-provider
193
270
 
194
- # Batch: Static table output with daily averages
195
- vct analysis --table
271
+ # Save grouped results
272
+ vct analysis --by-provider --output grouped_report.json
196
273
 
197
- # Batch: Save aggregated results to JSON
198
- vct analysis --output batch_report.json
274
+ # Combine time range with output format
275
+ vct analysis --weekly
276
+ vct analysis --table --monthly
277
+ vct analysis --by-provider --daily --output today.json
278
+ ```
199
279
 
200
- # Batch with provider grouping: Output complete records grouped by provider (JSON format)
201
- vct analysis --all
280
+ ### Preview: Interactive Dashboard (`vct analysis`)
202
281
 
203
- # Save the grouped results to a file
204
- vct analysis --all --output grouped_report.json
282
+ ```
283
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
284
+ │ 🔍 Analysis Statistics │
285
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
286
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
287
+ │ Model Edit Lines Read Lines Write Lines Bash Edit Read Write │
288
+ │ │
289
+ │ claude-haiku-4-5-20251001 0 0 0 43 0 59 0 │
290
+ │ claude-opus-4-6 1,280 13,264 1,575 82 146 209 62 │
291
+ │ gemini-3.1-pro-preview 0 0 0 0 0 0 0 │
292
+ │ TOTAL 1,280 13,264 1,575 125 146 268 62 │
293
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
294
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
295
+ │ Provider EditL/Day ReadL/Day WriteL/Day Bash/Day Edit/Day Read/Day Write/Day Days │
296
+ │ │
297
+ │ 🤖 Claude Code 426.7 4421.3 525.0 41.7 48.7 89.3 20.7 3 │
298
+ │ ✨ Gemini 0 0 0 0.0 0.0 0.0 0.0 1 │
299
+ │ ⭐ All Providers 426.7 4421.3 525.0 41.7 48.7 89.3 20.7 3 │
300
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
301
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
302
+ │ 📝 Lines: 16,119 | 🔧 Tools: 601 | 📊 Models: 3 | ⚡ CPU: 3.6% | 🧠 Mem: 140 MB │
303
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
304
+ Press 'q', 'Esc', 'Ctrl+C' to quit | Press 'r' to refresh
205
305
  ```
206
306
 
207
307
  ---
@@ -221,10 +321,32 @@ vct update --check
221
321
  # Interactive update with confirmation
222
322
  vct update
223
323
 
224
- # Force update - always downloads latest version (even if already up-to-date)
324
+ # Force update — always downloads latest version
225
325
  vct update --force
226
326
  ```
227
327
 
328
+ ### Preview (`vct update --check`)
329
+
330
+ ```
331
+ 📋 Current version: v0.5.10
332
+ 🔍 Checking for latest release...
333
+ ✅ Latest version: v0.5.10 — you are up to date!
334
+ ```
335
+
336
+ ---
337
+
338
+ ## 🏷️ Version Command
339
+
340
+ Report the embedded build metadata (binary version, Rust toolchain, Cargo version):
341
+
342
+ ```bash
343
+ vct version # Pretty table
344
+ vct version --text # One-field-per-line, script-friendly
345
+ vct version --json # Machine-readable JSON
346
+ ```
347
+
348
+ 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.
349
+
228
350
  ---
229
351
 
230
352
  ## 💡 Smart Pricing System
package/README.zh-CN.md CHANGED
@@ -17,54 +17,58 @@
17
17
 
18
18
  </div>
19
19
 
20
- **实时追踪您的 AI 编程成本。** Vibe Coding Tracker 是一个强大的 CLI 工具，帮助您监控和分析 Claude Code、Codex、Copilot 和 Gemini 的使用情况，提供详细的成本分解、token 统计和代码操作洞察。
20
+ **实时追踪你的 AI 编程开销。** Vibe Coding Tracker 是一款基于 Rust 构建的轻量级高性能 CLI 工具，用于监控和分析你在 Claude Code、Codex、Copilot 和 Gemini 上的使用情况——提供详细的费用明细、token 统计和代码操作洞察，同时保持极低的 CPU 和内存占用。
21
21
 
22
22
  [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
23
23
 
24
- > 注意：以下 CLI 示例默认使用短别名 `vct`。若您通过 npm/pip/cargo 安装，二进制文件名称可能为 `vibe_coding_tracker` 或 `vct`，可以自行建立别名，或在执行指令时将 `vct` 换成完整名称。
24
+ > 注意：CLI 示例中使用简写别名 `vct`。如果你是通过 npm/pip/cargo 安装的，二进制文件可能命名为 `vibe_coding_tracker` 或 `vct`。如有需要，请创建别名或在运行命令时将 `vct` 替换为完整名称。
25
25
 
26
26
  ---
27
27
 
28
28
  ## 🎯 为什么选择 Vibe Coding Tracker？
29
29
 
30
- ### 💰 了解您的成本
30
+ ### 💰 掌握你的开销
31
31
 
32
- 不再疑惑您的 AI 编程会话花费多少。通过 [LiteLLM](https://github.com/BerriAI/litellm) 自动更新定价，获取**实时成本追踪**。
32
+ 不用再猜测 AI 编程会话到底花了多少钱。通过 [LiteLLM](https://github.com/BerriAI/litellm) 自动更新定价，获取**实时费用追踪**。
33
+
34
+ ### 🪶 超轻量级
35
+
36
+ 使用 Rust 构建，资源占用极低。交互式 TUI 面板运行时仅需约 **3-5% CPU** 和约 **140 MB 内存**，即使处理来自多个供应商的数百万 token 也是如此——无需 Electron，无需臃肿的运行时。
33
37
 
34
38
  ### 📊 精美的可视化
35
39
 
36
- 选择您偏好的视图：
40
+ 选择你喜欢的查看方式：
37
41
 
38
- - **交互式仪表板**：自动刷新的终端 UI，实时更新
39
- - **静态报表**：专业的表格，适合文档
40
- - **脚本友好**：纯文本和 JSON，便于自动化
41
- - **全精度**：导出精确成本，用于财务核算
42
+ - **交互式面板**：自动刷新的终端 UI，支持实时更新
43
+ - **静态报表**：专业的表格，适合文档记录
44
+ - **脚本友好**：纯文本和 JSON 格式，方便自动化
45
+ - **完整精度**：导出精确费用，满足财务核算需求
42
46
 
43
47
  ### 🚀 零配置
44
48
 
45
- 自动检测并处理 Claude Code、Codex、Copilot 和 Gemini 的日志。无需设置——只需运行和分析。
49
+ 自动检测并处理来自 Claude Code、Codex、Copilot 和 Gemini 的日志。无需任何设置——直接运行即可分析。
46
50
 
47
51
  ### 🎨 丰富的洞察
48
52
 
49
- - 按模型和日期的 token 使用量
50
- - 按缓存类型的成本分解
51
- - 文件操作追踪
52
- - 命令执行历史
53
- - Git 仓库信息
53
+ - 按模型和日期统计 token 使用量
54
+ - 按 cache 类型（读取/创建）细分费用
55
+ - 文件操作追踪（编辑、读取、写入行数）
56
+ - 工具调用历史（Bash、Edit、Read、Write、TodoWrite）
57
+ - 按供应商统计每日平均值
54
58
 
55
59
  ---
56
60
 
57
61
  ## ✨ 核心特性
58
62
 
59
- | 特性 | 描述 |
60
- | ------------------- | --------------------------------------------------- |
61
- | 🤖 **自动检测** | 智能识别 Claude Code、Codex、Copilot 或 Gemini 日志 |
62
- | 💵 **智能定价** | 模糊模型匹配 + 每日缓存以提高速度 |
63
- | 🎨 **4 种显示模式** | 交互式、表格、文本和 JSON 输出 |
64
- | 📈 **全面统计** | Token、成本、文件操作和工具调用 |
65
- | ⚡ **高性能** | 使用 Rust 构建，速度快且可靠 |
66
- | 🔄 **实时更新** | 仪表板每秒刷新 |
67
- | 💾 **高效缓存** | 智能的每日缓存减少 API 调用 |
63
+ | 特性 | 说明 |
64
+ | ------------------- | ----------------------------------------------------- |
65
+ | 🤖 **多供应商支持** | Claude Code、Codex、Copilot 和 Gemini——一站式管理 |
66
+ | 💵 **智能定价** | 模糊模型匹配 + 从 LiteLLM 每日缓存更新 |
67
+ | 🎨 **4 种显示模式** | 交互式 TUI、静态表格、纯文本和 JSON |
68
+ | 📈 **双维度分析** | token/费用统计（`usage`）+ 代码操作统计（`analysis`） |
69
+ | 🪶 **超轻量级** | 约 3-5% CPU、约 140 MB RAM——基于 Rust 构建 |
70
+ | 🔄 **实时更新** | 面板每秒自动刷新 |
71
+ | 💾 **高效缓存** | 智能每日缓存，减少 API 调用次数 |
68
72
 
69
73
  ---
70
74
 
@@ -72,40 +76,40 @@
72
76
 
73
77
  ### 安装
74
78
 
75
- 选择最适合您的安装方式：
79
+ 选择最适合你的安装方式：
76
80
 
77
- > 👨‍💻 **开发者**：如果您想从源码构建或参与开发，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
81
+ > 👨‍💻 **开发者**：如果你想从源码构建或参与项目开发，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
78
82
 
79
- #### 方式 1: 从 npm 安装
83
+ #### 方式一：通过 npm 安装
80
84
 
81
- **前置条件**: [Node.js](https://nodejs.org/) v22 或更高版本
85
+ **前置条件**：[Node.js](https://nodejs.org/) v22 或更高版本
82
86
 
83
- 选择以下任一包名称（三者完全相同）：
87
+ 以下包名任选其一（内容完全相同）：
84
88
 
85
89
  ```bash
86
- # 主要包
90
+ # Main package
87
91
  npm install -g vibe-coding-tracker
88
92
 
89
- # 带 scope 的短别名
93
+ # Short alias with scope
90
94
  npm install -g @mai0313/vct
91
95
 
92
- # 带 scope 的完整名称
96
+ # Full name with scope
93
97
  npm install -g @mai0313/vibe-coding-tracker
94
98
  ```
95
99
 
96
- #### 方式 2: 从 PyPI 安装
100
+ #### 方式二：通过 PyPI 安装
97
101
 
98
- **前置条件**: Python 3.8 或更高版本
102
+ **前置条件**：Python 3.8 或更高版本
99
103
 
100
104
  ```bash
101
105
  pip install vibe_coding_tracker
102
- # 或使用 uv
106
+ # Or with uv
103
107
  uv pip install vibe_coding_tracker
104
108
  ```
105
109
 
106
- #### 方式 3: 从 crates.io 安装
110
+ #### 方式三：通过 crates.io 安装
107
111
 
108
- 使用 Cargo 从 Rust 官方包注册表安装：
112
+ 使用 Cargo 从 Rust 官方包注册中心安装：
109
113
 
110
114
  ```bash
111
115
  cargo install vibe_coding_tracker
@@ -114,14 +118,14 @@ cargo install vibe_coding_tracker
114
118
  ### 首次运行
115
119
 
116
120
  ```bash
117
- # 使用交互式仪表板查看使用量（已设置短别名时）
121
+ # View your usage with the interactive dashboard
118
122
  vct usage
119
123
 
120
- # 或使用完整名称
124
+ # Or run the binary built by Cargo/pip
121
125
  vibe_coding_tracker usage
122
126
 
123
- # 分析特定对话
124
- vibe_coding_tracker analysis --path ~/.claude/projects/session.jsonl
127
+ # Analyze code operations across all sessions
128
+ vct analysis
125
129
  ```
126
130
 
127
131
  ---
@@ -130,43 +134,97 @@ vibe_coding_tracker analysis --path ~/.claude/projects/session.jsonl
130
134
 
131
135
  ### 🔍 快速参考
132
136
 
133
- ```bash
134
- vct <命令 >[选项]
135
- # 若未设置别名，请改用 `vibe_coding_tracker` 完整二进制名称
136
-
137
- 命令：
138
- analysis 分析对话文件并导出数据（支持单文件或所有会话）
139
- usage 显示 token 使用量统计
140
- version 显示版本信息
141
- update 从 GitHub releases 更新到最新版本
142
- help 显示此信息或给定子命令的说明
137
+ ```
138
+ vct <COMMAND> [OPTIONS]
139
+ # Replace with `vibe_coding_tracker` if you are using the full binary name
140
+
141
+ Commands:
142
+ analysis Analyze JSONL conversation files (single file or all sessions)
143
+ usage Display token usage statistics
144
+ version Display version information
145
+ update Update to the latest version from GitHub releases
146
+ help Print this message or the help of the given subcommand(s)
143
147
  ```
144
148
 
149
+ 时间范围 flag（`usage` 与 `analysis` 共用，互斥，默认 `--all`）：
150
+
151
+ | Flag | 范围 |
152
+ | ----------- | ---------------------------- |
153
+ | `--daily` | 今天更新过的 session |
154
+ | `--weekly` | 本 ISO 周（周一 → 今天） |
155
+ | `--monthly` | 本自然月 |
156
+ | `--all` | 磁盘上所有 session（默认值） |
157
+
145
158
  ---
146
159
 
147
160
  ## 💰 Usage 命令
148
161
 
149
- **追踪您所有 AI 编程会话的支出。**
162
+ **追踪你在所有 AI 编程会话中的开销。**
163
+
164
+ ### Flag 一览
165
+
166
+ | Flag | 用途 |
167
+ | ---------------------------------------------- | -------------------------- |
168
+ | *(不带参数)* | 互动式 TUI 面板（默认） |
169
+ | `--table` | 静态表格，不启动 TUI |
170
+ | `--text` | 纯文本，适合脚本处理 |
171
+ | `--json` | JSON 输出，附带定价信息 |
172
+ | `--daily` / `--weekly` / `--monthly` / `--all` | 时间范围筛选（见上方表格） |
150
173
 
151
174
  ### 基本用法
152
175
 
153
176
  ```bash
154
- # 交互式仪表板（推荐）
177
+ # Interactive dashboard (recommended)
155
178
  vct usage
156
179
 
157
- # 静态表格，适合报表
180
+ # Static table for reports
158
181
  vct usage --table
159
182
 
160
- # 纯文本，适合脚本
183
+ # Plain text for scripts
161
184
  vct usage --text
162
185
 
163
- # JSON，适合数据处理
186
+ # JSON 输出，包含 cost_usd 与 matched_model 字段
164
187
  vct usage --json
188
+
189
+ # 时间范围与输出格式可自由组合
190
+ vct usage --weekly
191
+ vct usage --table --monthly
192
+ vct usage --json --daily
165
193
  ```
166
194
 
167
- ### 您将获得什么
195
+ > [!NOTE]
196
+ > Model 行会按 cost 升序排序，因此花费最高的 model 会紧邻在 `TOTAL` 行上方。该排序适用于交互式面板、`--table` 与 `--text` 三种输出；`--json` 也会保持相同顺序。
168
197
 
169
- 该工具自动扫描这些目录：
198
+ ### 预览：交互式面板（`vct usage`）
199
+
200
+ ```
201
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
202
+ │ 📊 Token Usage Statistics │
203
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
204
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
205
+ │ Model Input Output Cache Read Cache Create Total Cost │
206
+ │ │
207
+ │ gemini-3.1-pro-preview 129,115 10,339 67,385 0 $0.40 │
208
+ │ claude-haiku-4-5-20251001 5,567 19,769 4,627,938 619,816 $1.34 │
209
+ │ claude-opus-4-6 25,651 179,066 40,830,154 2,572,258 $77.59 │
210
+ │ TOTAL 160,333 209,174 45,525,477 3,192,074 $79.33 │
211
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
212
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
213
+ │ Provider Tokens / Day Cost / Day Active Days │
214
+ │ │
215
+ │ 🤖 Claude Code 16,293,406 $26.31 3 │
216
+ │ ✨ Gemini 206,839 $0.40 1 │
217
+ │ ⭐ All Providers 16,362,353 $26.44 3 │
218
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
219
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
220
+ │ 💰 Total: $79.33 | 🔢 Tokens: 49,087,058 | 📊 Models: 3 | ⚡ CPU: 4.6% | 🧠 Mem: 148 MB │
221
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
222
+ Press 'q', 'Esc', 'Ctrl+C' to quit | Press 'r' to refresh
223
+ ```
224
+
225
+ ### 扫描范围
226
+
227
+ 该工具会自动扫描以下目录：
170
228
 
171
229
  - `~/.claude/projects/*.jsonl`（Claude Code）
172
230
  - `~/.codex/sessions/*.jsonl`（Codex）
@@ -177,31 +235,73 @@ vct usage --json
177
235
 
178
236
  ## 📊 Analysis 命令
179
237
 
180
- **深入了解对话文件 - 单文件或批量分析。**
238
+ **深入了解代码操作——查看你的 AI 助手到底做了什么。**
239
+
240
+ ### Flag 一览
241
+
242
+ | Flag | 用途 |
243
+ | ---------------------------------------------- | --------------------------------------------------------------- |
244
+ | *(不带参数)* | 互动式 TUI 面板，覆盖所有 session |
245
+ | `--path <FILE>` | 分析单一 JSONL/JSON 对话文件（stdout 输出 JSON） |
246
+ | `--table` | 静态表格，附带每日平均值 |
247
+ | `--output <FILE>` | 将结果以格式化 JSON 保存到文件 |
248
+ | `--by-provider` | 按 provider（claude / codex / copilot / gemini）分组并输出 JSON |
249
+ | `--daily` / `--weekly` / `--monthly` / `--all` | 时间范围筛选（见上方表格） |
250
+
251
+ 参见 [`examples/`](examples/) 目录，其中包含四种 provider 的示例输入与对应 JSON 输出。
181
252
 
182
253
  ### 基本用法
183
254
 
184
255
  ```bash
185
- # 单文件：分析并显示
256
+ # Interactive dashboard for all sessions (default)
257
+ vct analysis
258
+
259
+ # Static table output with daily averages
260
+ vct analysis --table
261
+
262
+ # 分析单一对话文件 → stdout JSON
186
263
  vct analysis --path ~/.claude/projects/session.jsonl
187
264
 
188
- # 单文件：保存到文件
189
- vct analysis --path ~/.claude/projects/session.jsonl --output report.json
265
+ # Save results to JSON
266
+ vct analysis --output report.json
190
267
 
191
- # 批量：使用交互式表格分析所有会话（默认）
192
- vct analysis
268
+ # Group results by provider
269
+ vct analysis --by-provider
193
270
 
194
- # 批量：静态表格输出并显示每日平均
195
- vct analysis --table
271
+ # Save grouped results
272
+ vct analysis --by-provider --output grouped_report.json
196
273
 
197
- # 批量：将汇总结果保存为 JSON
198
- vct analysis --output batch_report.json
274
+ # 时间范围与输出格式可自由组合
275
+ vct analysis --weekly
276
+ vct analysis --table --monthly
277
+ vct analysis --by-provider --daily --output today.json
278
+ ```
199
279
 
200
- # 批量并依提供者分组：输出完整的 records，依提供者分组（JSON 格式）
201
- vct analysis --all
280
+ ### 预览：交互式面板（`vct analysis`）
202
281
 
203
- # 将分组结果保存到文件
204
- vct analysis --all --output grouped_report.json
282
+ ```
283
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
284
+ │ 🔍 Analysis Statistics │
285
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
286
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
287
+ │ Model Edit Lines Read Lines Write Lines Bash Edit Read Write │
288
+ │ │
289
+ │ claude-haiku-4-5-20251001 0 0 0 43 0 59 0 │
290
+ │ claude-opus-4-6 1,280 13,264 1,575 82 146 209 62 │
291
+ │ gemini-3.1-pro-preview 0 0 0 0 0 0 0 │
292
+ │ TOTAL 1,280 13,264 1,575 125 146 268 62 │
293
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
294
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
295
+ │ Provider EditL/Day ReadL/Day WriteL/Day Bash/Day Edit/Day Read/Day Write/Day Days │
296
+ │ │
297
+ │ 🤖 Claude Code 426.7 4421.3 525.0 41.7 48.7 89.3 20.7 3 │
298
+ │ ✨ Gemini 0 0 0 0.0 0.0 0.0 0.0 1 │
299
+ │ ⭐ All Providers 426.7 4421.3 525.0 41.7 48.7 89.3 20.7 3 │
300
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
301
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
302
+ │ 📝 Lines: 16,119 | 🔧 Tools: 601 | 📊 Models: 3 | ⚡ CPU: 3.6% | 🧠 Mem: 140 MB │
303
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
304
+ Press 'q', 'Esc', 'Ctrl+C' to quit | Press 'r' to refresh
205
305
  ```
206
306
 
207
307
  ---
@@ -210,51 +310,73 @@ vct analysis --all --output grouped_report.json
210
310
 
211
311
  **自动保持安装版本为最新。**
212
312
 
213
- update 命令适用于**所有安装方式**（npm/pip/cargo/manual），直接从 GitHub releases 下载并替换二进制文件。
313
+ update 命令适用于**所有安装方式**（npm/pip/cargo/手动安装），它会直接从 GitHub releases 下载并替换二进制文件。
214
314
 
215
315
  ### 基本用法
216
316
 
217
317
  ```bash
218
- # 检查更新
318
+ # Check for updates
219
319
  vct update --check
220
320
 
221
- # 交互式更新（会询问确认）
321
+ # Interactive update with confirmation
222
322
  vct update
223
323
 
224
- # 强制更新 - 总是下载最新版本（即使已是最新版本）
324
+ # Force update — always downloads latest version
225
325
  vct update --force
226
326
  ```
227
327
 
328
+ ### 预览（`vct update --check`）
329
+
330
+ ```
331
+ 📋 Current version: v0.5.10
332
+ 🔍 Checking for latest release...
333
+ ✅ Latest version: v0.5.10 — you are up to date!
334
+ ```
335
+
336
+ ---
337
+
338
+ ## 🏷️ Version 命令
339
+
340
+ 查看内置的构建信息（binary version、Rust toolchain、Cargo version）：
341
+
342
+ ```bash
343
+ vct version # 彩色表格
344
+ vct version --text # 每行一个字段，适合脚本
345
+ vct version --json # 机读 JSON
346
+ ```
347
+
348
+ Binary version 由 `build.rs` 在编译期通过 `git describe` 写入，开发版本会附带 commit 计数、short SHA 与 `dirty` 后缀。
349
+
228
350
  ---
229
351
 
230
352
  ## 💡 智能定价系统
231
353
 
232
- ### 运作原理
354
+ ### 工作原理
233
355
 
234
- 1. **自动更新**：每天从 [LiteLLM](https://github.com/BerriAI/litellm) 获取定价
235
- 2. **智能缓存**：在 `~/.vibe_coding_tracker/` 中存储定价 24 小时
236
- 3. **模糊匹配**：即使对于自定义模型名称也能找到最佳匹配
237
- 4. **始终准确**：确保您获取最新的定价
356
+ 1. **自动更新**：每天从 [LiteLLM](https://github.com/BerriAI/litellm) 获取最新定价
357
+ 2. **智能缓存**：将定价信息存储在 `~/.vibe_coding_tracker/` 目录中，有效期 24 小时
358
+ 3. **模糊匹配**：即使是自定义模型名称也能找到最佳匹配
359
+ 4. **始终精确**：确保你获取到最新的定价信息
238
360
 
239
361
  ### 模型匹配
240
362
 
241
- **优先顺序**：
363
+ **优先级顺序**：
242
364
 
243
365
  1. ✅ **精确匹配**：`claude-sonnet-4` → `claude-sonnet-4`
244
- 2. 🔄 **规范化**：`claude-sonnet-4-20250514` → `claude-sonnet-4`
245
- 3. 🔍 **子字符串**：`custom-gpt-4` → `gpt-4`
246
- 4. 🎯 **模糊（AI 驱动）**：使用 Jaro-Winkler 相似度（70% 阈值）
247
- 5. 💵 **后备**：如果找不到匹配则显示 $0.00
366
+ 2. 🔄 **标准化匹配**：`claude-sonnet-4-20250514` → `claude-sonnet-4`
367
+ 3. 🔍 **子串匹配**：`custom-gpt-4` → `gpt-4`
368
+ 4. 🎯 **模糊匹配（AI 驱动）**：使用 Jaro-Winkler 相似度算法（70% 阈值）
369
+ 5. 💵 **兜底方案**：如果未找到匹配，显示 $0.00
248
370
 
249
371
  ---
250
372
 
251
373
  ## 🐳 Docker 支持
252
374
 
253
375
  ```bash
254
- # 构建镜像
376
+ # Build image
255
377
  docker build -f docker/Dockerfile --target prod -t vibe_coding_tracker:latest .
256
378
 
257
- # 使用您的会话运行
379
+ # Run with your sessions
258
380
  docker run --rm \
259
381
  -v ~/.claude:/root/.claude \
260
382
  -v ~/.codex:/root/.codex \
package/README.zh-TW.md CHANGED
@@ -17,54 +17,58 @@
17
17
 
18
18
  </div>
19
19
 
20
- **即時追蹤您的 AI 程式設計成本。** Vibe Coding Tracker 是一個強大的 CLI 工具，幫助您監控和分析 Claude Code、Codex、Copilot 和 Gemini 的使用情況，提供詳細的成本分解、token 統計和程式碼操作洞察。
20
+ **即時追蹤你的 AI 程式設計花費。** Vibe Coding Tracker 是一款以 Rust 打造的輕量、高效能 CLI 工具，能監控與分析你在 Claude Code、Codex、Copilot 及 Gemini 的使用狀況——提供詳細的費用明細、token 統計資料與程式碼操作分析，同時維持極低的 CPU 與記憶體使用量。
21
21
 
22
22
  [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
23
23
 
24
- > 注意：以下 CLI 範例預設使用短別名 `vct`。若您透過 npm/pip/cargo 安裝，產生的二進位檔名稱可能為 `vibe_coding_tracker` 或 `vct`，可以自行建立別名，或在執行指令時將 `vct` 換成完整名稱。
24
+ > 注意：CLI 範例使用簡短別名 `vct`。如果你是透過 npm/pip/cargo 安裝，執行檔可能命名為 `vibe_coding_tracker` 或 `vct`。如有需要，請建立別名或在執行指令時將 `vct` 替換為完整名稱。
25
25
 
26
26
  ---
27
27
 
28
28
  ## 🎯 為什麼選擇 Vibe Coding Tracker？
29
29
 
30
- ### 💰 了解您的成本
30
+ ### 💰 掌握你的花費
31
31
 
32
- 不再疑惑您的 AI 程式設計會話花費多少。透過 [LiteLLM](https://github.com/BerriAI/litellm) 自動更新定價，獲取**即時成本追蹤**。
32
+ 不用再猜測 AI 程式設計工作階段花了多少錢。透過 [LiteLLM](https://github.com/BerriAI/litellm) 自動更新價格，取得**即時費用追蹤**。
33
33
 
34
- ### 📊 精美的視覺化
34
+ ### 🪶 超輕量
35
35
 
36
- 選擇您偏好的檢視：
36
+ 以 Rust 打造，資源佔用極低。互動式 TUI 儀表板僅需 **~3-5% CPU** 與 **~140 MB 記憶體**，即使處理來自多個供應商的數百萬 token 也不例外——不用 Electron，不用臃腫的執行環境。
37
37
 
38
- - **互動式儀表板**：自動重新整理的終端 UI，即時更新
39
- - **靜態報表**：專業的表格，適合文件
40
- - **指令碼友善**：純文字和 JSON，便於自動化
41
- - **完整精度**：匯出精確成本，用於財務核算
38
+ ### 📊 精美視覺化
39
+
40
+ 選擇你偏好的檢視方式：
41
+
42
+ - **互動式儀表板**：自動更新的終端機 UI，即時顯示最新資訊
43
+ - **靜態報表**：專業的表格格式，適合撰寫文件
44
+ - **腳本友好**：純文字及 JSON 輸出，方便自動化處理
45
+ - **完整精度**：匯出精確費用供會計使用
42
46
 
43
47
  ### 🚀 零設定
44
48
 
45
- 自動偵測並處理 Claude Code、Codex、Copilot 和 Gemini 的日誌。無需設定——只需執行和分析。
49
+ 自動偵測並處理 Claude Code、Codex、Copilot 及 Gemini 的日誌檔。不需要任何設定——直接執行就能分析。
46
50
 
47
- ### 🎨 豐富的洞察
51
+ ### 🎨 豐富洞察
48
52
 
49
- - 按模型和日期的 token 使用量
50
- - 按快取類型的成本分解
51
- - 檔案操作追蹤
52
- - 命令執行歷史
53
- - Git 儲存庫資訊
53
+ - 依模型與日期分類的 token 使用量
54
+ - 依 cache 類型（讀取 / 建立）的費用明細
55
+ - 檔案操作追蹤（編輯、讀取、寫入行數）
56
+ - 工具呼叫歷史（Bash、Edit、Read、Write、TodoWrite）
57
+ - 每個供應商的每日平均值
54
58
 
55
59
  ---
56
60
 
57
- ## ✨ 核心特性
61
+ ## ✨ 主要功能
58
62
 
59
- | 特性 | 描述 |
60
- | ------------------- | --------------------------------------------------- |
61
- | 🤖 **自動偵測** | 智慧識別 Claude Code、Codex、Copilot 或 Gemini 日誌 |
62
- | 💵 **智慧定價** | 模糊模型匹配 + 每日快取以提高速度 |
63
- | 🎨 **4 種顯示模式** | 互動式、表格、文字和 JSON 輸出 |
64
- | 📈 **全面統計** | Token、成本、檔案操作和工具呼叫 |
65
- | ⚡ **高效能** | 使用 Rust 建置，速度快且可靠 |
66
- | 🔄 **即時更新** | 儀表板每秒重新整理 |
67
- | 💾 **高效快取** | 智慧的每日快取減少 API 呼叫 |
63
+ | 功能 | 說明 |
64
+ | ------------------- | --------------------------------------------------------- |
65
+ | 🤖 **多供應商支援** | Claude Code、Codex、Copilot 及 Gemini——一站整合 |
66
+ | 💵 **智慧定價** | 模糊模型比對 + 每日從 LiteLLM cache 更新 |
67
+ | 🎨 **4 種顯示模式** | 互動式 TUI、靜態表格、純文字及 JSON |
68
+ | 📈 **雙重分析** | Token / 費用統計（`usage`）+ 程式碼操作統計（`analysis`） |
69
+ | 🪶 **超輕量** | ~3-5% CPU、~140 MB RAM——以 Rust 打造 |
70
+ | 🔄 **即時更新** | 即時儀表板每秒自動刷新 |
71
+ | 💾 **高效快取** | 智慧每日 cache 減少 API 呼叫次數 |
68
72
 
69
73
  ---
70
74
 
@@ -72,40 +76,40 @@
72
76
 
73
77
  ### 安裝
74
78
 
75
- 選擇最適合您的安裝方式：
79
+ 選擇最適合你的安裝方式：
76
80
 
77
- > 👨‍💻 **開發者**：如果您想從原始碼建置或貢獻開發，請參閱 [CONTRIBUTING.md](CONTRIBUTING.md)。
81
+ > 👨‍💻 **開發者**：如果你想從原始碼建置或參與開發，請參閱 [CONTRIBUTING.md](CONTRIBUTING.md)。
78
82
 
79
- #### 方式 1: 從 npm 安裝
83
+ #### 方法一：透過 npm 安裝
80
84
 
81
- **前置條件**: [Node.js](https://nodejs.org/) v22 或更高版本
85
+ **前置條件**：[Node.js](https://nodejs.org/) v22 或更高版本
82
86
 
83
- 選擇以下任一套件名稱（三者完全相同）：
87
+ 選擇以下任一套件名稱（內容完全相同）：
84
88
 
85
89
  ```bash
86
- # 主要套件
90
+ # Main package
87
91
  npm install -g vibe-coding-tracker
88
92
 
89
- # 帶 scope 的短別名
93
+ # Short alias with scope
90
94
  npm install -g @mai0313/vct
91
95
 
92
- # 帶 scope 的完整名稱
96
+ # Full name with scope
93
97
  npm install -g @mai0313/vibe-coding-tracker
94
98
  ```
95
99
 
96
- #### 方式 2: 從 PyPI 安裝
100
+ #### 方法二：透過 PyPI 安裝
97
101
 
98
- **前置條件**: Python 3.8 或更高版本
102
+ **前置條件**：Python 3.8 或更高版本
99
103
 
100
104
  ```bash
101
105
  pip install vibe_coding_tracker
102
- # 或使用 uv
106
+ # Or with uv
103
107
  uv pip install vibe_coding_tracker
104
108
  ```
105
109
 
106
- #### 方式 3: 從 crates.io 安裝
110
+ #### 方法三：透過 crates.io 安裝
107
111
 
108
- 使用 Cargo 從 Rust 官方套件庫安裝：
112
+ 使用 Cargo 從官方 Rust 套件倉庫安裝：
109
113
 
110
114
  ```bash
111
115
  cargo install vibe_coding_tracker
@@ -114,59 +118,113 @@ cargo install vibe_coding_tracker
114
118
  ### 首次執行
115
119
 
116
120
  ```bash
117
- # 使用互動式儀表板檢視使用量（已設定短別名時）
121
+ # View your usage with the interactive dashboard
118
122
  vct usage
119
123
 
120
- # 或使用完整名稱
124
+ # Or run the binary built by Cargo/pip
121
125
  vibe_coding_tracker usage
122
126
 
123
- # 分析特定對話
124
- vibe_coding_tracker analysis --path ~/.claude/projects/session.jsonl
127
+ # Analyze code operations across all sessions
128
+ vct analysis
125
129
  ```
126
130
 
127
131
  ---
128
132
 
129
- ## 📖 命令指南
133
+ ## 📖 指令指南
130
134
 
131
135
  ### 🔍 快速參考
132
136
 
133
- ```bash
134
- vct <命令 >[選項]
135
- # 若未設定別名，請改用 `vibe_coding_tracker`完整二進位名稱
136
-
137
- 命令：
138
- analysis 分析對話檔案並匯出資料（支援單檔案或所有會話）
139
- usage 顯示 token 使用量統計
140
- version 顯示版本資訊
141
- update 從 GitHub releases 更新到最新版本
142
- help 顯示此訊息或給定子命令的說明
137
+ ```
138
+ vct <COMMAND> [OPTIONS]
139
+ # Replace with `vibe_coding_tracker` if you are using the full binary name
140
+
141
+ Commands:
142
+ analysis Analyze JSONL conversation files (single file or all sessions)
143
+ usage Display token usage statistics
144
+ version Display version information
145
+ update Update to the latest version from GitHub releases
146
+ help Print this message or the help of the given subcommand(s)
143
147
  ```
144
148
 
149
+ 時間範圍 flag（`usage` 與 `analysis` 共用，互斥，預設 `--all`）：
150
+
151
+ | Flag | 範圍 |
152
+ | ----------- | -------------------------- |
153
+ | `--daily` | 今天更新過的 session |
154
+ | `--weekly` | 本 ISO 週（週一 → 今天） |
155
+ | `--monthly` | 本自然月 |
156
+ | `--all` | 磁碟上所有 session（預設） |
157
+
145
158
  ---
146
159
 
147
- ## 💰 Usage 命令
160
+ ## 💰 Usage 指令
161
+
162
+ **追蹤你在所有 AI 程式設計工作階段的花費。**
148
163
 
149
- **追蹤您所有 AI 程式設計會話的支出。**
164
+ ### Flag 一覽
165
+
166
+ | Flag | 用途 |
167
+ | ---------------------------------------------- | ---------------------------- |
168
+ | *(不帶參數)* | 互動式 TUI 儀表板（預設） |
169
+ | `--table` | 靜態表格，不啟動 TUI |
170
+ | `--text` | 純文字，適合腳本處理 |
171
+ | `--json` | JSON 輸出，附帶 pricing 資訊 |
172
+ | `--daily` / `--weekly` / `--monthly` / `--all` | 時間範圍篩選（見上方表格） |
150
173
 
151
174
  ### 基本用法
152
175
 
153
176
  ```bash
154
- # 互動式儀表板（推薦）
177
+ # Interactive dashboard (recommended)
155
178
  vct usage
156
179
 
157
- # 靜態表格，適合報表
180
+ # Static table for reports
158
181
  vct usage --table
159
182
 
160
- # 純文字，適合指令碼
183
+ # Plain text for scripts
161
184
  vct usage --text
162
185
 
163
- # JSON，適合資料處理
186
+ # JSON 輸出，包含 cost_usd 與 matched_model 欄位
164
187
  vct usage --json
188
+
189
+ # 時間範圍與輸出格式可自由組合
190
+ vct usage --weekly
191
+ vct usage --table --monthly
192
+ vct usage --json --daily
165
193
  ```
166
194
 
167
- ### 您將獲得什麼
195
+ > [!NOTE]
196
+ > Model 列會依 cost 由小到大排序，所以花費最高的 model 會緊鄰在 `TOTAL` 列上方。這個排序會套用到互動式儀表板、`--table` 與 `--text` 三種輸出；`--json` 也會保持相同順序。
168
197
 
169
- 該工具自動掃描這些目錄：
198
+ ### 預覽：互動式儀表板（`vct usage`）
199
+
200
+ ```
201
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
202
+ │ 📊 Token Usage Statistics │
203
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
204
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
205
+ │ Model Input Output Cache Read Cache Create Total Cost │
206
+ │ │
207
+ │ gemini-3.1-pro-preview 129,115 10,339 67,385 0 $0.40 │
208
+ │ claude-haiku-4-5-20251001 5,567 19,769 4,627,938 619,816 $1.34 │
209
+ │ claude-opus-4-6 25,651 179,066 40,830,154 2,572,258 $77.59 │
210
+ │ TOTAL 160,333 209,174 45,525,477 3,192,074 $79.33 │
211
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
212
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
213
+ │ Provider Tokens / Day Cost / Day Active Days │
214
+ │ │
215
+ │ 🤖 Claude Code 16,293,406 $26.31 3 │
216
+ │ ✨ Gemini 206,839 $0.40 1 │
217
+ │ ⭐ All Providers 16,362,353 $26.44 3 │
218
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
219
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
220
+ │ 💰 Total: $79.33 | 🔢 Tokens: 49,087,058 | 📊 Models: 3 | ⚡ CPU: 4.6% | 🧠 Mem: 148 MB │
221
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
222
+ Press 'q', 'Esc', 'Ctrl+C' to quit | Press 'r' to refresh
223
+ ```
224
+
225
+ ### 掃描範圍
226
+
227
+ 此工具會自動掃描以下目錄：
170
228
 
171
229
  - `~/.claude/projects/*.jsonl`（Claude Code）
172
230
  - `~/.codex/sessions/*.jsonl`（Codex）
@@ -175,86 +233,150 @@ vct usage --json
175
233
 
176
234
  ---
177
235
 
178
- ## 📊 Analysis 命令
236
+ ## 📊 Analysis 指令
179
237
 
180
- **深入了解對話檔案 - 單檔案或批次分析。**
238
+ **深入分析程式碼操作——精確掌握你的 AI 助手做了哪些事。**
239
+
240
+ ### Flag 一覽
241
+
242
+ | Flag | 用途 |
243
+ | ---------------------------------------------- | --------------------------------------------------------------- |
244
+ | *(不帶參數)* | 互動式 TUI 儀表板，涵蓋所有 session |
245
+ | `--path <FILE>` | 分析單一 JSONL/JSON 對話檔案（stdout 輸出 JSON） |
246
+ | `--table` | 靜態表格，附帶每日平均值 |
247
+ | `--output <FILE>` | 將結果以格式化 JSON 存成檔案 |
248
+ | `--by-provider` | 依 provider（claude / codex / copilot / gemini）分組並輸出 JSON |
249
+ | `--daily` / `--weekly` / `--monthly` / `--all` | 時間範圍篩選（見上方表格） |
250
+
251
+ 請參考 [`examples/`](examples/) 目錄，裡面有四種 provider 的範例輸入與對應的 JSON 輸出。
181
252
 
182
253
  ### 基本用法
183
254
 
184
255
  ```bash
185
- # 單檔案：分析並顯示
256
+ # Interactive dashboard for all sessions (default)
257
+ vct analysis
258
+
259
+ # Static table output with daily averages
260
+ vct analysis --table
261
+
262
+ # 分析單一對話檔案 → stdout JSON
186
263
  vct analysis --path ~/.claude/projects/session.jsonl
187
264
 
188
- # 單檔案：儲存到檔案
189
- vct analysis --path ~/.claude/projects/session.jsonl --output report.json
265
+ # Save results to JSON
266
+ vct analysis --output report.json
190
267
 
191
- # 批次：使用互動式表格分析所有會話（預設）
192
- vct analysis
268
+ # Group results by provider
269
+ vct analysis --by-provider
193
270
 
194
- # 批次：靜態表格輸出並顯示每日平均
195
- vct analysis --table
271
+ # Save grouped results
272
+ vct analysis --by-provider --output grouped_report.json
196
273
 
197
- # 批次：將彙總結果儲存為 JSON
198
- vct analysis --output batch_report.json
274
+ # 時間範圍與輸出格式可自由組合
275
+ vct analysis --weekly
276
+ vct analysis --table --monthly
277
+ vct analysis --by-provider --daily --output today.json
278
+ ```
199
279
 
200
- # 批次並依提供者分組：輸出完整的 records，依提供者分組（JSON 格式）
201
- vct analysis --all
280
+ ### 預覽：互動式儀表板（`vct analysis`）
202
281
 
203
- # 將分組結果儲存到檔案
204
- vct analysis --all --output grouped_report.json
282
+ ```
283
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
284
+ │ 🔍 Analysis Statistics │
285
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
286
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
287
+ │ Model Edit Lines Read Lines Write Lines Bash Edit Read Write │
288
+ │ │
289
+ │ claude-haiku-4-5-20251001 0 0 0 43 0 59 0 │
290
+ │ claude-opus-4-6 1,280 13,264 1,575 82 146 209 62 │
291
+ │ gemini-3.1-pro-preview 0 0 0 0 0 0 0 │
292
+ │ TOTAL 1,280 13,264 1,575 125 146 268 62 │
293
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
294
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
295
+ │ Provider EditL/Day ReadL/Day WriteL/Day Bash/Day Edit/Day Read/Day Write/Day Days │
296
+ │ │
297
+ │ 🤖 Claude Code 426.7 4421.3 525.0 41.7 48.7 89.3 20.7 3 │
298
+ │ ✨ Gemini 0 0 0 0.0 0.0 0.0 0.0 1 │
299
+ │ ⭐ All Providers 426.7 4421.3 525.0 41.7 48.7 89.3 20.7 3 │
300
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
301
+ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
302
+ │ 📝 Lines: 16,119 | 🔧 Tools: 601 | 📊 Models: 3 | ⚡ CPU: 3.6% | 🧠 Mem: 140 MB │
303
+ └─────────────────────────────────────────────────────────────────────────────────────────────┘
304
+ Press 'q', 'Esc', 'Ctrl+C' to quit | Press 'r' to refresh
205
305
  ```
206
306
 
207
307
  ---
208
308
 
209
- ## 🔄 Update 命令
309
+ ## 🔄 Update 指令
210
310
 
211
- **自動保持安裝版本為最新。**
311
+ **自動保持安裝為最新版本。**
212
312
 
213
- update 命令適用於**所有安裝方式**（npm/pip/cargo/manual），直接從 GitHub releases 下載並替換二進位檔。
313
+ Update 指令適用於**所有安裝方式**（npm/pip/cargo/手動安裝），透過直接從 GitHub releases 下載並替換執行檔來完成更新。
214
314
 
215
315
  ### 基本用法
216
316
 
217
317
  ```bash
218
- # 檢查更新
318
+ # Check for updates
219
319
  vct update --check
220
320
 
221
- # 互動式更新（會詢問確認）
321
+ # Interactive update with confirmation
222
322
  vct update
223
323
 
224
- # 強制更新 - 總是下載最新版本（即使已是最新版本）
324
+ # Force update — always downloads latest version
225
325
  vct update --force
226
326
  ```
227
327
 
328
+ ### 預覽（`vct update --check`）
329
+
330
+ ```
331
+ 📋 Current version: v0.5.10
332
+ 🔍 Checking for latest release...
333
+ ✅ Latest version: v0.5.10 — you are up to date!
334
+ ```
335
+
336
+ ---
337
+
338
+ ## 🏷️ Version 指令
339
+
340
+ 檢視內建的建置資訊（binary version、Rust toolchain、Cargo version）：
341
+
342
+ ```bash
343
+ vct version # 彩色表格
344
+ vct version --text # 每行一個欄位，適合腳本
345
+ vct version --json # 機器可讀的 JSON
346
+ ```
347
+
348
+ Binary version 由 `build.rs` 在編譯期透過 `git describe` 寫入，開發版本會附上 commit 數、short SHA 與 `dirty` 後綴。
349
+
228
350
  ---
229
351
 
230
352
  ## 💡 智慧定價系統
231
353
 
232
- ### 運作原理
354
+ ### 運作方式
233
355
 
234
- 1. **自動更新**：每天從 [LiteLLM](https://github.com/BerriAI/litellm) 取得定價
235
- 2. **智慧快取**：在 `~/.vibe_coding_tracker/` 中儲存定價 24 小時
236
- 3. **模糊匹配**：即使對於自訂模型名稱也能找到最佳匹配
237
- 4. **始終準確**：確保您取得最新的定價
356
+ 1. **自動更新**：每日從 [LiteLLM](https://github.com/BerriAI/litellm) 取得最新價格
357
+ 2. **智慧快取**：將價格資料儲存於 `~/.vibe_coding_tracker/`，有效期 24 小時
358
+ 3. **模糊比對**：即使是自訂模型名稱也能找到最佳配對
359
+ 4. **始終精準**：確保你取得最新的定價資訊
238
360
 
239
- ### 模型匹配
361
+ ### 模型比對
240
362
 
241
363
  **優先順序**：
242
364
 
243
- 1. ✅ **精確匹配**：`claude-sonnet-4` → `claude-sonnet-4`
244
- 2. 🔄 **規範化**：`claude-sonnet-4-20250514` → `claude-sonnet-4`
245
- 3. 🔍 **子字串**：`custom-gpt-4` → `gpt-4`
246
- 4. 🎯 **模糊（AI 驅動）**：使用 Jaro-Winkler 相似度（70% 閾值）
247
- 5. 💵 **後備**：如果找不到匹配則顯示 $0.00
365
+ 1. ✅ **完全比對**：`claude-sonnet-4` → `claude-sonnet-4`
366
+ 2. 🔄 **正規化比對**：`claude-sonnet-4-20250514` → `claude-sonnet-4`
367
+ 3. 🔍 **子字串比對**：`custom-gpt-4` → `gpt-4`
368
+ 4. 🎯 **模糊比對（AI 驅動）**：使用 Jaro-Winkler 相似度（70% 門檻值）
369
+ 5. 💵 **備援方案**：若無法配對則顯示 $0.00
248
370
 
249
371
  ---
250
372
 
251
373
  ## 🐳 Docker 支援
252
374
 
253
375
  ```bash
254
- # 建置映像
376
+ # Build image
255
377
  docker build -f docker/Dockerfile --target prod -t vibe_coding_tracker:latest .
256
378
 
257
- # 使用您的會話執行
379
+ # Run with your sessions
258
380
  docker run --rm \
259
381
  -v ~/.claude:/root/.claude \
260
382
  -v ~/.codex:/root/.codex \
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mai0313/vibe-coding-tracker",
3
- "version": "0.5.11",
3
+ "version": "0.5.13",
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",