發布日期：2026-09-07
平時習慣呼叫 Grok 協作的開發者，現在執行 usage report 或切換至互動儀表板時，終於能將它的用量一併納入統計。
先前 macOS 選單列雖有 Grok 的額度卡，讀取器 loaders/grok_loader.py 也能吐出逐次呼叫的 token（AI 處理與計費的文字單位）明細，但轉接層缺少 adapters/grok.py，導致終端機報表與儀表板對它視而不見。這次除了補上轉接器，也同步了四張必須一致的對照表：註冊表的偵測清單、指令列與報表產生器的 AGENT_LOADERS，以及表格介面的 AGENT_SHORT 與 AGENT_LABEL。
想掌握 AI 的實際消耗，過去報表頂部的「燒掉 Tokens」只把四種不同性質的數字加總成單一數值，根本看不出關鍵細節。
本機測試某期 2,565,454,499 個 token（AI 處理與計費的文字單位）裡，高達 93.8% 是讀取快取的舊資料。快取就是把算過或查過的結果暫存起來直接取用；模型真正生成的輸出只佔 0.7%，單看總額毫無意義。現在報表正式拆分為輸入、快取寫入、快取讀取與輸出四類，並計算各工具的快取命中率。算式以快取讀取除以三種輸入脈絡總額，排除掉生成出的輸出。高命中率代表舊脈絡以約十分之一的單價重複取用，五種語言的文案也明確引導此數值象徵體質良好而非無效重複。底層一直都記錄著這四個欄位，先前僅是報表彙整時丟棄，因此不必清理快取或升級資料格式。
你想知道哪款模型最省心、最不需要你回頭反覆插手修正，「一次過關率」現在被拉升成報表第三區的獨立大板塊。這項衡量 AI 能否一次搞定任務的指標早就算好，先前卻埋在第 11 區「使用習慣」的小卡裡，多數人根本捲不到。如今它改排在洞察之後、工具之前，各模型採用排行列版面依過關率由高至低排序，直接回答哪款模型最不用重修，而非單看誰的對話輪次多。頂部關鍵績效指標（KPI，衡量核心表現的量化卡片）也同步移除了重複的一次過關率，解決過去五張卡硬塞在雙欄網格中的難看排版，而且沒有新增任何多國語系文字鍵。
召開 AI 圓桌讓多款模型共同商討問題時，你現在已能指派 Codex 最新的 Astra 模型加入對話。
gpt-6-astra 是 Codex 當前的新預設模型，但圓桌先前的模型白名單寫死了 5.6 版的三款舊變體，導致新旗艦無法登場。這次放行無須更動價目表與報表：LiteLLM 的價格表早已完整收錄該模型的四項實價，報表的顏色分配也只要命中 gpt 前綴就能自動對應，切換選擇毫無阻礙。
每次打開報表看到「燒掉成本」這個標籤，往往讓人誤以為自己真的刷卡付出了這筆費用。這項數值僅是依照官方牌價乘出來的假設數字，對於每個月繳固定月費、邊際成本為零的包月使用者來說相當容易引起誤解。現在五種語言統一改名為「API 等值」，先前繁體中文特有的新台幣換算也一併移除，避免將假設數字再乘上匯率二次失真。該數值本身依然保留，供按量計費的 API 使用者參考。另外，由於「燒掉 Tokens」統計了所有代理工具，而「API 等值」僅能計算具備公開牌價的模型，兩張頭條卡的分母並不相同；因此只有在確實出現無牌價用量時，卡片才會顯示副標題說明兩者的差額。
當單一類別佔比超過九成時，傳統的堆疊長條圖就會變成一場排版災難。先前在快取讀取高達 93.8% 的情況下，其餘三種類別被壓成看不見的細縫，長條內的百分比文字甚至重疊成 4.6% 0.1.93.7% 擠在最左側，圖例色塊也缺乏尺寸樣式。輸入、快取寫入與快取讀取都屬於傳入的脈絡，而輸出是生成的文字，性質本不相同。現在改採排行列呈現，四種類別各自擁有獨立的一列與專屬欄位，且長條設有 2% 的最小寬度，讓僅佔 0.7% 的微小產出依然清晰可辨。各工具的快取命中率也套用同款版面依命中率排序，體質最差的工具直接落在最後一列。同時，測試中針對 TypedDict 型別以迴圈變數當鍵遭 mypy 拒絕的問題，也透過 Any 中介變數順利修復。
檢視報表中不同區塊的數據時，數字與量條不再忽左忽右跳動。
過去排版存在四個獨立缺陷：兩套資料列樣式（.rank-line 與 .tool-row）因欄寬與間距相異，導致數值在各區塊落在不同的水平位置；佔比量條被限制在名稱欄內，只能畫到半列就硬生生中斷；每個區塊層層疊加了區塊、卡片與列框三層多餘邊界；更有兩處區塊缺少欄位表頭。現在資料列改為貫穿整列的進度條，工具區補上了量條元素，且工具的顏色直接綁定代理識別碼（agent id）而非排序位置，避免工具名次互換時發生整批重新塗色的混亂。
追蹤長期消耗趨勢時，報表展示的時間跨度如今更加清晰嚴謹。每週燃燒趨勢區塊移除了原本夾帶的每日折線圖，因該折線既無刻度也無具體數值，不但對不上「每週」的標題，也無法提供任何可化為行動的有效資訊；底下的週次、數值與週增減橫條則維持不變。同時，報表明確講清楚了比較的基準期間，將「較上月」與「較上週」統合成「較前期」；年度統計區塊也正名為「近 53 週」，其週數由程式常數自動傳入，日後常數調整時文案會即時跟上。
當你的模型額度即將用盡時，彈出的警告紅字現在能完整顯示於介面之中。先前那行寫死不換行的警語需要 320 到 470 像素寬度，但選單列面板（popover，點擊狀態列圖示展開的小視窗）的文字框僅有 304 至 320 像素，加上卡片外框設定了隱藏溢出內容以維持復古造型，整行紅字因此直接被切斷。實測 13 個面板在 5 種語言下的表現，日文最慘被削掉 81 至 150 像素，英文也只有三個面板能剛好裝下。現在文案在維持原意下全面縮短，左右對決的世界盃面板更提供省略重置時間的超短版本，完美適應每邊僅 151 像素的狹窄空間。
累積整整一年的 AI 使用紀錄，往後再也不會因為程式升級而無聲無息被歸零蒸發。
年度帳本模組原本有四條路徑會直接回傳空帳本，其中最嚴重的便是資料規格版本不符；過去只要開發者微調欄位並調升版號，全球使用者累積的歷史便會靜靜歸零，且毫無備份可救。開發時實測更發現，一次升版就讓本機熱力圖從 119 天驟降至 36 天。現在版本不符時只會記錄警告，依舊逐日解析舊資料；只有在檔案完全無法讀取或結構徹底損毀時，才會先隔離備份至 ~/.usage/quarantine/ 資料夾，周全守護歷史紀錄。
在裸倉庫（沒有工作目錄的 Git 主儲存庫）中建立工作樹時，同一專案往後不再被報表拆成兩筆紀錄。先前專案名稱解析器將工作樹（Git 讓同一專案平行開多份副本的功能）路徑解回主目錄後直接取尾端名稱，讓專案名多帶了 .git。這使純路徑解析的 Claude 回報 obsidian00，其餘三組讀取器卻回報 obsidian00.git；本機實測達 5997 筆對 3732 筆，報表上同一專案被拆成 21.70% 與 10.80% 兩筆。三層架構已同步修復：解析器會去除結尾的 .git，Codex 分片快取升版以重新解析 28 個舊分片，年度帳本則在讀取時將 .git 摺疊併回原專案名。
當你的 token 消耗量剛好接近單位級距的邊緣時，報表上的數字與單位現在會正確跳級。
函式 _fmt_tokens 過去在格式化 token（AI 處理與計費的文字單位）數值時，先根據未縮放的原始值決定單位級距，完成縮放並執行四捨五入後，卻沒有再次檢查數字是否已經滿額進位。這導致 999,950 遭到四捨五入後被印成古怪的 1000.0K，而 999,950,000 也被印成 1000.0M。現在進位後會重新審查級距，確保單位如實躍升。
Developers who regularly collaborate with Grok can now finally include its usage in statistics when running usage report or switching to the interactive dashboard.
While the macOS menu bar previously had a Grok quota card and the loader loaders/grok_loader.py could produce per-call token details, the adapter layer lacked adapters/grok.py, leaving the terminal report and dashboard blind to it. In addition to adding the adapter, this update synchronizes the four lookup tables that must agree: the registry's detector list, AGENT_LOADERS in the CLI and report generator, and AGENT_SHORT and AGENT_LABEL in the table UI.
To understand actual AI consumption, the headline "tokens burned" at the top of previous reports summed four distinct numbers into a single total, obscuring key details.
In local testing across a period of 2,565,454,499 tokens, as much as 93.8% was cache read while only 0.7% was output the model actually generated, rendering the raw total meaningless. The report now formally breaks down usage into input, cache write, cache read, and output, while calculating cache hit rates for each tool. The formula divides cache read by the sum of the three input contexts, excluding the generated output. A high hit rate indicates that old context is reused at roughly one-tenth the unit price, and the copy across all five languages explicitly frames this metric as a sign of healthy efficiency rather than wasteful repetition. The underlying layer has always recorded all four fields and previous versions merely discarded them during report aggregation, so no cache clearing or data format upgrade is required.
For those wanting to know which model requires the least intervention and fewest follow-up fixes, "one-pass rate" has been promoted to a standalone third section in the report. This metric measuring whether AI completes tasks on the first attempt was already computed, but previously sat buried inside a small card under section 11 "usage habits" where most users never scrolled. It is now positioned after Insights and before Tools, with model rows using a ranked layout sorted by pass rate from highest to lowest to directly answer which model needs the fewest revisions rather than just looking at turn count. The top key performance indicator (KPI) cards also removed the duplicate one-pass rate, fixing an awkward layout where five cards were squeezed into a two-column grid without requiring any new i18n localization keys.
When convening an AI roundtable to deliberate issues across multiple models, you can now assign Codex's latest Astra model to the discussion.
gpt-6-astra is Codex's current new default model, but the roundtable's previous model allowlist hardcoded three older 5.6 variants, preventing the new flagship from appearing. Enabling it required no changes to pricing tables or reports: LiteLLM's price list already covers the model's four actual prices, and report color assignments match automatically on the gpt prefix, so switching works without another change.
Opening the report and seeing the "Cost burned" label often gave the mistaken impression that one had actually paid that amount out of pocket. Because this figure is merely a hypothetical number multiplied out from official list prices, it easily misled subscription users who pay a fixed monthly fee with zero marginal cost. The label is now unified across all five languages as "API equivalent", and the NTD conversion previously unique to Traditional Chinese has been removed to avoid distorting an assumed number a second time through exchange rates. The value itself remains available for pay-as-you-go API users who need it. Furthermore, because "tokens burned" counts all agents while "API equivalent" can only calculate models with published list prices, the two headline cards do not share the same denominator; a subtitle now explains the gap, but only when unpriced usage actually exists.
When a single category exceeds ninety percent, traditional stacked bar charts turn into a layout disaster. Previously, with cache reads reaching 93.8%, the other three categories collapsed into invisible slivers, in-bar percentage text overlapped into 4.6% 0.1.93.7% at the far left edge, and legend color swatches lacked sizing styles entirely. Input, cache write, and cache read all represent incoming context while output consists of generated text, making them fundamentally distinct in nature. The presentation has now shifted to ranked lines where each of the four categories receives its own row and dedicated columns, with bars given a 2% minimum width to keep even a tiny 0.7% output clearly visible. Per-tool cache hit rates adopt the same layout sorted by hit rate, placing the worst-performing tool on the final row. Meanwhile, a test issue where mypy rejected loop variables used as keys on TypedDict types was resolved cleanly using an Any intermediate variable.
When reviewing data across different report sections, numbers and bars no longer jitter unpredictably between left and right.
The previous layout suffered from four separate defects: two row styles (.rank-line and .tool-row) used differing column widths and gaps that placed numbers at different horizontal positions across sections; share bars were trapped inside the name column and abruptly stopped halfway across the row; every section stacked three redundant borders of section, card, and row frames; and two sections lacked column headers entirely. Data rows are now full-width progress bars, the tools section adds bar elements, and tool colors are keyed directly to the agent ID rather than sort position to avoid repainting every tool whenever rankings shift.
When tracking long-term consumption trends, the report's timeframes are now clearer and more rigorous. The weekly burn trend section dropped its embedded daily line chart because it had no scale or values, failed to match the "weekly" heading, and provided no actionable information, while the week numbers, values, and week-over-week bars below remain unchanged. At the same time, the report clarifies its comparison baseline by unifying "vs. last month" and "vs. last week" into "vs. previous period", while the annual section is renamed "last 53 weeks" with the week count passed from program constants so the copy updates automatically if constants change.
When your model quota is running low, the red warning text now displays fully within the interface. Previously, the hardcoded nowrap warning required 320 to 470 pixels of width, but the menu bar panel text box was only 304 to 320 pixels, and because card frames hid overflowing content to preserve a retro aesthetic, the red line was cut off directly. Across 13 panels in 5 languages, Japanese suffered the most by losing 81 to 150 pixels, and English fit in only three panels. The copy is now universally shortened while preserving its original meaning, and the head-to-head World Cup panel provides an ultra-short variant that omits the reset time, fitting neatly into the narrow 151 pixels on each side.
A full year of accumulated AI usage history will no longer vanish silently to zero due to software upgrades.
The year ledger module previously had four execution paths that returned an empty ledger, the most severe being schema version mismatches; whenever developers tweaked fields and bumped the version, users worldwide quietly lost their entire history with no backups to recover from. Testing during development revealed that a single version bump caused the local heatmap to plunge from 119 days to 36. Version mismatches now merely log a warning and continue parsing older data day by day, moving files into the ~/.usage/quarantine/ directory as isolated backups only when they are genuinely unreadable or structurally corrupted to protect historical records.
When creating a worktree from a bare repository, the same project will no longer be split into two separate entries in reports. Previously, the project name resolver resolved worktree paths back to the main directory and took the basename directly, leaving the project name with an unwanted .git suffix. This caused path-only Claude to report obsidian00 while the other three loaders reported obsidian00.git; locally, this amounted to 5997 entries against 3732, splitting the same project in the report into 21.70% and 10.80%. All three architectural layers have been fixed: the resolver strips the trailing .git, the Codex shard cache was bumped to re-parse 28 old shards, and the year ledger folds .git back into the base project name at read time.
When your token consumption nears the boundary of a unit tier, numbers and units on reports will now advance correctly.
When formatting token values, the _fmt_tokens function previously selected unit tiers from unscaled raw values, but failed to re-check whether rounding pushed the number across the tier threshold after scaling. This caused 999,950 to be printed as an awkward 1000.0K after rounding, and 999,950,000 as 1000.0M. Unit tiers are now re-evaluated after rounding to ensure units advance properly.
**Grok now appears in the report and the interactive dashboard.** The menu bar has carried a Grok quota card for a while and `loaders/grok_loader.py` could already produce per-call token detail, but there was no `adapters/grok.py`, so both `usage report` and the dashboard were blind to it. The adapter was added along with the four lookup tables that have to agree: the registry's detector list, the `AGENT_LOADERS` maps in `usage_cli` and `reporter`, and `AGENT_SHORT` / `AGENT_LABEL` in `ui/tables`.**The report breaks tokens into four kinds and shows each tool's cache hit rate.** The headline "tokens burned" was one number summing four different things; locally, 93.8% of a 2,565,454,499-token period was `cache_read` and only 0.7% was output the model actually generated, so the total said nothing. `UsageEntry` has always carried all four fields and `loaders/disk_cache_common.py` serialized all four — `reporter` was dropping them when it built the summary, so no cache and no schema version had to change. Cache hit rate is `cache_read / (input + cache_creation + cache_read)`; output is excluded because it is generated, not sent in. A high rate is the healthy end — old context reused at roughly a tenth of the price instead of re-sent at full rate — and the copy in all five languages is written to keep it from being read as "most of my tokens are wasted repeats."**"One-pass rate" is now a section of its own, third from the top.** Whether the AI finished without you stepping in is a measure with no pre-LLM equivalent; the data was already computed and already drawn, but it sat in a small card inside "usage habits" in section 11, where most people never scrolled. It is now a full section placed after Insights and before Tools, and the model rows use the report's existing rank-line layout sorted by pass rate rather than by turns — the question the section answers is which model needs the least going back over, not which one is used most. No new i18n keys were required.
**The top KPI row no longer repeats the one-pass rate.** Five cards laid out badly in a two-column grid, and the full section below already carries the per-model detail.**The AI roundtable can pick Codex's Astra model.** `gpt-6-astra` is Codex's new default, but the roundtable's model allowlist hard-coded the three 5.6 variants. Pricing and the report needed no change: LiteLLM's table already carries real prices in all four of its fields, and the report's color assignment matches on the `gpt` prefix.**"Cost burned" is now "API equivalent."** The label presented a figure multiplied out from list prices as money actually spent, which is misleading for subscription users whose marginal cost is zero. Renamed in all five languages; the Traditional Chinese-only NTD conversion went with it, since that ran an assumed figure through an exchange rate a second time. The number itself stays — API users still need it. The two headline cards never shared a denominator: "tokens burned" counts every agent, while "API equivalent" can only count models with a published price, so a subtitle now explains the gap, and only when unpriced tokens actually exist.**Token composition is a ranked list instead of a stacked bar.** With one category at 93.8%, the other three collapsed into invisible slivers, the in-bar percentage labels piled up into `4.6% 0.1.93.7%` at the left edge, and the legend's swatches had no size styling at all. A stacked bar is the wrong chart once a single category passes ninety percent, and the four are not peers anyway — input, cache write and cache read are all context sent in, output is generated. Each category now gets its own row with its own columns, and the bar's 2% minimum width keeps a 0.7% share visible. Per-tool cache hit rates use the same layout, sorted by rate, so the weakest tool is the last row rather than something you have to hunt for.
**A type error in the token composition tests.** `data["summary"]` and the elements of `data["by_agent"]` are TypedDicts, so mypy rejects a loop variable used as a key; the two assertions now go through an `Any` intermediate. The lines came from the composition work and were not caught earlier because that batch had not been pushed yet.**The report's data rows are filled bars, with columns that line up across every section.** Four separate problems: the two row systems (`.rank-line` and `.tool-row`) used different track widths and gaps, so numbers sat at different x positions in different sections; the share bar was a child of `.name` and capped by the name column, so it drew to about half the row and stopped; every section nested a section frame, a card frame and a row frame; and two sections used the shared layout with no column headers. The tools section had no bar element at all and now has one, with each tool's color keyed on its agent id rather than its sort position — `by_agent` is ordered by tokens, so a palette indexed by position would repaint every tool whenever two swapped places.**The weekly burn section lost its daily line chart.** It had no scale and no values, did not match the "weekly" heading it sat under, and could not be read for anything actionable. The rows below it, carrying week number, value and week-over-week change, are unchanged.
**The report says which span it is comparing against.** "vs. last month" and "vs. last week" became a single "vs. previous period," and the annual block is now "last 53 weeks" with the week count supplied by `WrappedReportData.weeks` from `_YEAR_WEEKS`, so the copy follows the constant if it ever changes.**The quota warning fits inside the panels.** The red "running out" line was `white-space: nowrap` and needed 320–470px, but the panels' text box is 304–320px and the cards are `overflow: hidden` — deliberate retro chrome, not removable — so the sentence was cut off. Measured across 13 panels × 5 languages: Japanese lost 81–150px, and only three panels' English fit. The wording is now shorter with the same meaning. The World Cup panel gets an even shorter variant that omits the reset time, since its head-to-head layout leaves each side only 151px.**The year ledger is never silently discarded.** `_read_year_ledger()` had four paths that returned an empty ledger, the worst being a `schema_version` mismatch: anyone changing a ledger field and bumping the version would have quietly zeroed every user's accumulated history, with no backup to recover from. This file exists precisely so that history survives after the raw logs rotate away, so clearing it defeats the thing it is for. Measured during development: one version bump took the local heatmap from 119 days to 36. A mismatched version now logs a warning and parses day by day anyway — `_year_day_from_json` already tolerates missing fields — and only a genuinely unreadable or structurally wrong file is moved into `~/.usage/quarantine/` before returning empty, matching what the disk cache already does.**A git worktree whose main repo is bare no longer splits one project into two.** `resolve_project_name()` resolved the worktree back to its main path and took the basename, so the project name carried a `.git` suffix. `adapters/claude.py` parses paths without calling git and reported `obsidian00`, while the other three loaders went through `project_resolver` and reported `obsidian00.git`; locally that was 5997 entries against 3732, and the report listed one project twice, at 21.70% and 10.80%. The same bug sat in three layers: the resolver now strips a trailing `.git`, Codex's shard cache went from schema 4 to 5 so the 28 shards holding the old name are re-parsed, and the year ledger — which cannot be invalidated by a version bump without losing the only copy of that history — folds `X.git` back into `X` at read time instead.**Token units no longer skip a tier when they round up.** `_fmt_tokens` picked the tier from the raw value and rounded afterwards without re-checking, so 999,950 printed as `1000.0K` and 999,950,000 as `1000.0M`.