@tsa-group/claude-usage 0.3.4 → 0.4.0

package/README.md

@@ -22,6 +22,19 @@ ingest server，彙整成團隊用量儀表。
 
 原始碼很短，`src/events.ts` 就是「哪些欄位會被送出去」的唯一權威來源，可以自己讀過再裝。
 
+**它會怎麼取得你的 token**（只用於認證，永不上傳）：
+
+| 平台 | 來源 |
+|---|---|
+| macOS | Keychain（`Claude Code-credentials`），檔案版只是可能過時的副本 |
+| Windows / Linux · CLI | `%USERPROFILE%\.claude\.credentials.json`（**純文字**，Claude Code 自己就是這樣存的） |
+| Windows · 桌面版 | 桌面版的加密憑證庫 —— 用 DPAPI 解出金鑰後以 AES-256-GCM 解密 |
+
+最後一項值得你知道再決定要不要裝：**只用桌面版、沒登入過終端機 `claude` 的人，
+除此之外沒有任何取得 token 的方式**，而沒有 token 就沒有額度資料。解密只在你自己的
+機器、你自己的 Windows 帳號下進行（DPAPI 的設計就綁這兩件事），解出的內容只留在
+記憶體。不想要這條路徑就登入一次終端機的 `claude`，工具會優先用那份純文字憑證。
+
 ---
 
 ## 需求
@@ -29,7 +42,7 @@ ingest server，彙整成團隊用量儀表。
 - **Node.js >= 20**
 - **Claude Code** 已登入（工具讀它的憑證來認證，見上方隱私說明）
 - macOS：完整支援並實測
-- Windows：程式路徑已備妥但**尚未在真機驗證**（見「已知限制」）
+- Windows：CLI 與**桌面版（Microsoft Store / MSIX）**都支援；桌面版憑證路徑見「已知限制」
 - Linux：背景任務（systemd timer）未實作，其餘指令可用
 
 ---
@@ -202,9 +215,15 @@ Client 對 server 只用兩個端點，皆為 `application/json`：
 ## 已知限制
 
 - **非官方 endpoint**：額度 % 來自 Claude Code 內部的 `/api/oauth/usage`，Anthropic 可能變更。
-- **Windows 未實機驗證**：憑證改讀檔案版（mac 走 Keychain）、背景任務用 schtasks +
-  VBS 隱藏視窗啟動器。程式路徑都在，但沒有在真的 Windows 上跑過。裝完請用
+- **Windows 桌面版憑證是逆向出來的**：桌面版把 OAuth token 存在
+  `%LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\config.json` 的
+  `oauth:tokenCacheV2`，以 Chromium 的 `v10` 方案（DPAPI + AES-256-GCM）加密。
+  這是**未公開的內部格式**，Anthropic 改版就可能失效 —— 與 `/api/oauth/usage` 同一個
+  風險類別。失效時會在 `claude-usage doctor` 顯示卡在哪一步，不會靜默。
+- **Windows 背景任務未完整實機驗證**：schtasks + VBS 隱藏視窗啟動器。裝完請用
   `claude-usage status` 確認有心跳。
+- **PowerShell 執行原則**：若整台停用指令碼執行，`npm i -g` 會失敗（載不進 `npm.ps1`）。
+  用 `npm.cmd i -g …`，或 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`（免管理員）。
 - **Linux 背景任務未實作**（systemd --user timer）。其餘指令可用。
 - **`session_id` 跨 compaction / resume 不穩定**：session **數**會高估。token 與成本不受影響
   （那是 per-event 去重的，與 session 身份無關）。

package/dist/creds-win.js

@@ -0,0 +1,249 @@
+/**
+ * Windows 桌面版（Microsoft Store / MSIX）的 Claude OAuth 憑證讀取。
+ *
+ * 為什麼需要這條路徑：**沒登入過 CLI 的人，`~/.claude/.credentials.json` 裡根本沒有
+ * `claudeAiOauth`**。第一台實機（2026-08-27）就是這樣——工具報「多半是用 API key
+ * 登入的」，但她其實是正常的訂閱制使用者，只是用桌面版。
+ *
+ * 三件事讓這個憑證庫「看起來不存在」，全碟搜尋也找不到：
+ *   1. **MSIX 路徑重導向**：App 命令列寫的是 `--user-data-dir=%APPDATA%\Claude`，但
+ *      MSIX 封裝會把它重導到 `%LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude`。
+ *      直接看 `%APPDATA%\Claude` 會說不存在。
+ *   2. **鍵名不同**：桌面版用 `oauth:tokenCacheV2`，不是 CLI 的 `claudeAiOauth`。
+ *   3. **值是密文**：base64 包住的 Chromium `v10` 區塊，所以搜明文鍵名永遠搜不到。
+ *
+ * 解出來的 token 與 CLI 的**完全同型**（`sk-ant-oat01-…`），打同一支
+ * `/api/oauth/usage`，所以下游一律不必分辨來源。
+ *
+ * ⚠️ 這是未公開的內部儲存格式，Anthropic 改版就可能失效——與 `/api/oauth/usage`
+ * 同一個風險類別。失敗一律回可辨識的 source 字串，不要拋例外把 daemon 打掛。
+ *
+ * SECURITY：解出的 master key 與 token 只留在記憶體，**永不列印、永不寫檔、永不上傳**。
+ */
+import { spawnSync } from "node:child_process";
+import { createDecipheriv } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Chromium 加密區塊的前綴。看到別的就是格式變了，不要硬解。 */
+const V10 = "v10";
+/** DPAPI 密文在 `os_crypt.encrypted_key` 裡的前綴，要先剝掉 */
+const DPAPI_PREFIX = "DPAPI";
+/**
+ * 桌面版資料目錄的候選清單，依可能性排序。
+ *
+ * `Claude_pzs8sxrjxfjjc` 那串是 Store 封裝的發行者雜湊。**刻意不寫死** —— 它理論上
+ * 固定，但賭這件事沒有好處，用 glob 找 `Claude_*` 成本一樣。
+ */
+export function desktopDataDirs() {
+    const out = [];
+    const local = process.env["LOCALAPPDATA"];
+    if (local) {
+        const packages = join(local, "Packages");
+        try {
+            for (const name of readdirSync(packages)) {
+                if (!name.startsWith("Claude_"))
+                    continue;
+                out.push({
+                    dir: join(packages, name, "LocalCache", "Roaming", "Claude"),
+                    kind: "desktop-msix",
+                });
+            }
+        }
+        catch {
+            // 沒有 Packages 目錄是正常的（非 Store 安裝）
+        }
+    }
+    // 非 MSIX（直接下載的安裝檔）會用一般的 %APPDATA%\Claude
+    const roaming = process.env["APPDATA"];
+    if (roaming)
+        out.push({ dir: join(roaming, "Claude"), kind: "desktop-appdata" });
+    return out.filter((c) => existsSync(join(c.dir, "config.json")));
+}
+/**
+ * 用 DPAPI 解出 Chromium 的 master key。
+ *
+ * Node 沒有 `CryptUnprotectData`，而我們是零執行期依賴 —— 裝 native addon 會同時
+ * 打破零依賴與免編譯兩個前提。改成 spawn PowerShell 呼叫 .NET，**與 mac 上
+ * spawn `security` 讀 Keychain 是同一個做法**，架構對稱。
+ *
+ * ★ 只讓 PowerShell 做 DPAPI 這一步，AES-GCM 交給 Node 的 crypto。這樣才避開
+ * 「AES-GCM 需要 PowerShell 7、否則要用 CNG P/Invoke」那個限制 —— 那個限制只在
+ * 整段都用 PowerShell 做時才存在，而實機上很可能只有 Windows PowerShell 5.1。
+ *
+ * 密文走 stdin 不走 argv：argv 會出現在行程清單裡。
+ */
+function dpapiUnprotect(encryptedB64) {
+    const script = [
+        "$ErrorActionPreference='Stop'",
+        "Add-Type -AssemblyName System.Security",
+        "$b64 = [Console]::In.ReadToEnd().Trim()",
+        "$enc = [Convert]::FromBase64String($b64)",
+        "$dec = [System.Security.Cryptography.ProtectedData]::Unprotect(" +
+            "$enc, $null, [System.Security.Cryptography.DataProtectionScope]::CurrentUser)",
+        "[Convert]::ToBase64String($dec)",
+    ].join("; ");
+    // 5.1 一定在；pwsh 當備援。-ExecutionPolicy Bypass 是必要的：實機遇過整台
+    // 停用指令碼執行（npm.ps1 都載不進去），而 -Command 帶的字串仍受原則約束。
+    for (const exe of ["powershell.exe", "pwsh"]) {
+        let r;
+        try {
+            r = spawnSync(exe, ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script], { input: encryptedB64, encoding: "utf8", timeout: 20_000, windowsHide: true });
+        }
+        catch {
+            continue; // 這個直譯器不存在，換下一個
+        }
+        if (r.error || r.status !== 0)
+            continue;
+        const out = (r.stdout ?? "").trim();
+        if (!out)
+            continue;
+        try {
+            const key = Buffer.from(out, "base64");
+            // AES-256 的金鑰必須是 32 byte。長度不對代表解出來的不是我們以為的東西。
+            if (key.length !== 32)
+                return [null, `dpapi-bad-key-len:${key.length}`];
+            return [key, "ok"];
+        }
+        catch {
+            return [null, "dpapi-bad-base64"];
+        }
+    }
+    return [null, "dpapi-failed"];
+}
+/** 讀 `Local State` 的 os_crypt.encrypted_key，DPAPI 解成 32-byte AES 金鑰 */
+function masterKey(dir) {
+    const p = join(dir, "Local State");
+    let raw;
+    try {
+        raw = readFileSync(p, "utf8");
+    }
+    catch {
+        return [null, "no-local-state"];
+    }
+    let encB64;
+    try {
+        encB64 = JSON.parse(raw)?.os_crypt
+            ?.encrypted_key;
+    }
+    catch {
+        return [null, "local-state-bad-json"];
+    }
+    if (typeof encB64 !== "string" || !encB64)
+        return [null, "no-encrypted-key"];
+    let blob;
+    try {
+        blob = Buffer.from(encB64, "base64");
+    }
+    catch {
+        return [null, "encrypted-key-bad-base64"];
+    }
+    if (blob.subarray(0, DPAPI_PREFIX.length).toString("latin1") !== DPAPI_PREFIX) {
+        return [null, "encrypted-key-no-dpapi-prefix"];
+    }
+    return dpapiUnprotect(blob.subarray(DPAPI_PREFIX.length).toString("base64"));
+}
+/**
+ * 拆 Chromium 的 v10 區塊並用 AES-256-GCM 解密。
+ * 結構：`"v10"`(3B) │ nonce(12B) │ ciphertext(…) │ GCM tag(16B)
+ */
+export function decryptV10(b64, key) {
+    let blob;
+    try {
+        blob = Buffer.from(b64, "base64");
+    }
+    catch {
+        return [null, "cache-bad-base64"];
+    }
+    if (blob.subarray(0, 3).toString("latin1") !== V10) {
+        return [null, `cache-not-v10:${blob.subarray(0, 3).toString("latin1")}`];
+    }
+    // 3 + 12 + 16 = 31 是「空密文」的最小長度，比這短就是壞掉的
+    if (blob.length < 32)
+        return [null, "cache-too-short"];
+    const nonce = blob.subarray(3, 15);
+    const tag = blob.subarray(blob.length - 16);
+    const ct = blob.subarray(15, blob.length - 16);
+    try {
+        const d = createDecipheriv("aes-256-gcm", key, nonce);
+        d.setAuthTag(tag);
+        return [Buffer.concat([d.update(ct), d.final()]).toString("utf8"), "ok"];
+    }
+    catch {
+        // GCM tag 驗證失敗 = 金鑰不對或資料被改過。不要當成「格式變了」。
+        return [null, "cache-decrypt-failed"];
+    }
+}
+/**
+ * 從解密後的 token cache 挑出可用的那一筆。
+ *
+ * key 的形狀是 `clientId:orgUUID:audience:scopes`，一個 cache 裡會有多筆（不同
+ * client / scope）。要的是含 **`user:inference`** 的那筆 —— 那是 Claude Code 用來
+ * 推論的 token，也是唯一打得動 `/api/oauth/usage` 的。
+ */
+export function pickEntry(plain) {
+    let obj;
+    try {
+        obj = JSON.parse(plain);
+    }
+    catch {
+        return [null, "cache-plain-bad-json"];
+    }
+    const hit = Object.entries(obj).find(([k, v]) => k.includes("user:inference") && typeof v?.token === "string" && v.token);
+    if (!hit)
+        return [null, "cache-no-inference-entry"];
+    const e = hit[1];
+    return [
+        {
+            accessToken: e.token,
+            expiresAt: e.expiresAt,
+            subscriptionType: e.subscriptionType,
+            rateLimitTier: e.rateLimitTier,
+        },
+        "ok",
+    ];
+}
+/**
+ * Windows 桌面版憑證。回 `[creds, source]`；失敗時 creds 為 null，而 source 是
+ * **可辨識的失敗原因**（會被記進 health / cred_source，之後從資料就看得出卡在哪一步）。
+ */
+export function fromWindowsDesktop() {
+    if (process.platform !== "win32")
+        return [null, "not-windows"];
+    const dirs = desktopDataDirs();
+    if (!dirs.length)
+        return [null, "desktop-no-datadir"];
+    let lastWhy = "desktop-no-datadir";
+    for (const { dir, kind } of dirs) {
+        const [key, keyWhy] = masterKey(dir);
+        if (!key) {
+            lastWhy = `desktop-${keyWhy}`;
+            continue;
+        }
+        let cfg;
+        try {
+            cfg = JSON.parse(readFileSync(join(dir, "config.json"), "utf8"));
+        }
+        catch {
+            lastWhy = "desktop-config-unreadable";
+            continue;
+        }
+        // V2 是新版；舊版鍵名沒有 V2 後綴。兩個都試，先新後舊。
+        const cached = cfg["oauth:tokenCacheV2"] ?? cfg["oauth:tokenCache"];
+        if (typeof cached !== "string" || !cached) {
+            lastWhy = "desktop-no-token-cache";
+            continue;
+        }
+        const [plain, decWhy] = decryptV10(cached, key);
+        if (!plain) {
+            lastWhy = `desktop-${decWhy}`;
+            continue;
+        }
+        const [creds, pickWhy] = pickEntry(plain);
+        if (!creds) {
+            lastWhy = `desktop-${pickWhy}`;
+            continue;
+        }
+        return [creds, kind];
+    }
+    return [null, lastWhy];
+}

package/dist/creds.js

@@ -13,6 +13,7 @@ import { spawnSync } from "node:child_process";
 import { userInfo } from "node:os";
 import { readFileSync } from "node:fs";
 import { claudeDir, credsPath } from "./paths.js";
+import { fromWindowsDesktop } from "./creds-win.js";
 /** 可區分的結束碼 —— daemon 靠這個把「token 過期」和「網路壞掉」分開記錄。
  *  過去兩者都是 exit 1，daemon 只能寫 sample-failed，於是 2026-08-22 那次
  *  token 過期靜默死了 17.6 小時沒人發現。 */
@@ -101,40 +102,67 @@ function fromFile() {
  * Claude Code 拿舊的去用會失敗，可能把使用者登出。這個風險不值得為了背景採樣承擔
  * —— 過期就大聲回報，讓使用者自己 /login。
  */
+const expired = (o) => Boolean(o.expiresAt && Date.now() >= o.expiresAt);
+/**
+ * 憑證來源，依「先便宜、先可能命中」排序，且**惰性求值** —— 前面的來源拿到堪用的
+ * token 就不會往下試。順序有成本意義：`fromWindowsDesktop` 會 spawn PowerShell
+ * （數百毫秒），不該在 CLI 檔案好好的機器上每次採樣都跑一次。
+ */
+const SOURCES = [
+    fromKeychain, // macOS 主儲存
+    fromFile, // CLI 的檔案（Windows/Linux 是主儲存；mac 上只是過時副本）
+    fromWindowsDesktop, // Windows 桌面版（MSIX，加密）
+];
 export function loadToken() {
-    let [o, source] = fromKeychain();
-    if (!o?.accessToken) {
-        const kcWhy = source;
-        [o, source] = fromFile();
+    const why = [];
+    let staleFound = null;
+    for (const get of SOURCES) {
+        const [o, source] = get();
         if (!o?.accessToken) {
-            const hints = {
-                "keychain-locked": "解鎖 login keychain（不是重新登入）",
-                "keychain-no-item": "在 Claude Code 裡跑 /login",
-                "file-not-found": `找不到 ${credsPath()} —— 在 Claude Code 裡跑 /login；` +
-                    `若你用的是 API key / Bedrock / Vertex 而非帳號登入，本工具無法取得額度資訊`,
-                "file-no-permission": `沒有權限讀 ${credsPath()}`,
-                "file-bad-json": `${credsPath()} 不是合法 JSON（檔案損毀？）`,
-                "file-no-oauth-key": `${credsPath()} 裡沒有 claudeAiOauth —— 多半是用 API key 登入的`,
-                "file-no-token": `${credsPath()} 裡沒有 accessToken —— 在 Claude Code 裡跑 /login`,
-            };
-            const hint = hints[source] ?? hints[kcWhy] ?? "";
-            throw new CuError(`cannot read credentials (keychain: ${kcWhy}; file: ${source})` +
-                (hint ? `\n  -> ${hint}` : "") +
-                `\n  設定目錄: ${claudeDir()}` +
-                (process.env["CLAUDE_CONFIG_DIR"] ? "  (來自 CLAUDE_CONFIG_DIR)" : ""), EXIT.NO_TOKEN);
+            why.push(source);
+            continue;
+        }
+        // ★ 過期不代表要放棄：CLI 的檔可能是舊的，而桌面版是新的（或反過來）。
+        // 記下來繼續往下找，全部都過期了才報 TOKEN_EXPIRED。
+        if (expired(o)) {
+            staleFound ??= { creds: o, source };
+            why.push(`${source}(expired)`);
+            continue;
         }
+        return {
+            token: o.accessToken,
+            subscription: o.subscriptionType ?? null,
+            tier: o.rateLimitTier ?? null,
+            source,
+        };
     }
-    if (o.expiresAt && Date.now() >= o.expiresAt) {
-        const hrs = (Date.now() - o.expiresAt) / 3_600_000;
-        throw new CuError(`access token EXPIRED ${hrs.toFixed(1)}h ago — run /login in Claude Code ` +
-            `(Claude Code 不會把刷新後的 token 寫回這個檔案)`, EXIT.TOKEN_EXPIRED);
+    if (staleFound) {
+        const hrs = (Date.now() - staleFound.creds.expiresAt) / 3_600_000;
+        throw new CuError(`access token EXPIRED ${hrs.toFixed(1)}h ago (${staleFound.source}) — ` +
+            `在 Claude Code 或桌面版重新登入即可換發`, EXIT.TOKEN_EXPIRED);
     }
-    return {
-        token: o.accessToken,
-        subscription: o.subscriptionType ?? null,
-        tier: o.rateLimitTier ?? null,
-        source,
+    const hints = {
+        "keychain-locked": "解鎖 login keychain（不是重新登入）",
+        "keychain-no-item": "在 Claude Code 裡跑 /login",
+        "file-not-found": `找不到 ${credsPath()} —— 在 Claude Code 裡跑 /login；` +
+            `若你用的是 API key / Bedrock / Vertex 而非帳號登入，本工具無法取得額度資訊`,
+        "file-no-permission": `沒有權限讀 ${credsPath()}`,
+        "file-bad-json": `${credsPath()} 不是合法 JSON（檔案損毀？）`,
+        // ⚠️ 這句以前寫「多半是用 API key 登入的」，實機證明那個推測是錯的：
+        // 第一台 Windows 是正常訂閱制，只是用桌面版而沒登入過 CLI。
+        "file-no-oauth-key": `${credsPath()} 只有 CLI 的資料、沒有 claudeAiOauth —— ` +
+            `你可能只用桌面版而沒登入過終端機的 claude`,
+        "file-no-token": `${credsPath()} 裡沒有 accessToken —— 在 Claude Code 裡跑 /login`,
+        "desktop-no-datadir": "找不到桌面版資料目錄（沒裝桌面版，或不是 Store 版）",
+        "desktop-dpapi-failed": "DPAPI 解密失敗 —— 必須在裝了桌面版的那台、用同一個 Windows 帳號執行",
+        "desktop-no-token-cache": "桌面版設定裡沒有 oauth:tokenCache —— 桌面版可能沒登入",
+        "desktop-cache-decrypt-failed": "桌面版憑證解密失敗（金鑰不符或格式已變更）",
     };
+    const hint = why.map((w) => hints[w]).find(Boolean) ?? "";
+    throw new CuError(`cannot read credentials (${why.join("; ")})` +
+        (hint ? `\n  -> ${hint}` : "") +
+        `\n  設定目錄: ${claudeDir()}` +
+        (process.env["CLAUDE_CONFIG_DIR"] ? "  (來自 CLAUDE_CONFIG_DIR)" : ""), EXIT.NO_TOKEN);
 }
 /** 打 Anthropic OAuth API 用的共同 headers。token 只出現在這裡。 */
 export const authHeaders = (token) => ({

package/dist/daemon.js

@@ -8,10 +8,10 @@
 import { statSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
-import { EXIT } from "./creds.js";
+import { EXIT, loadToken } from "./creds.js";
 import { healthWarning, lastSnapshot, loadHealth, saveHealth, } from "./health.js";
 import { devicePath, projectsDir } from "./paths.js";
-import { report } from "./upload.js";
+import { enroll, report } from "./upload.js";
 import { sample } from "./usage.js";
 import { nowIso, parseIso } from "./util.js";
 // ── 自適應策略 ──
@@ -137,8 +137,26 @@ export function decide() {
  * 都只記錄不拋出 —— daemon 絕不能因為上傳失敗就整個死掉。
  */
 async function flushUploads() {
-    if (!existsSync(devicePath()))
-        return "not-enrolled";
+    if (!existsSync(devicePath())) {
+        // install 當下 enroll 失敗（幾乎都是憑證還沒好）時，由這裡負責補上。
+        // 否則 install 印的「下次會自動重試」就是一句空話 —— 而使用者會合理地以為
+        // 自己不用再做什麼。第一台 Windows 機器就是這樣卡住的：憑證修好之後仍然
+        // 不會有任何資料，因為沒有人再跑一次 enroll。
+        try {
+            loadToken();
+        }
+        catch {
+            // 憑證還是壞的 -> 這次 enroll 必定失敗，安靜跳過，不要每 5 分鐘去騷擾 server
+            return "not-enrolled";
+        }
+        try {
+            if ((await enroll([])) !== 0)
+                return "enroll-failed";
+        }
+        catch {
+            return "enroll-failed";
+        }
+    }
     try {
         return (await report([])) === 0 ? "uploaded" : "upload-failed";
     }

package/dist/doctor.js

@@ -13,6 +13,7 @@ import { existsSync, readdirSync, statSync } from "node:fs";
 import { homedir, platform, release, userInfo } from "node:os";
 import { join } from "node:path";
 import { EXIT, loadToken } from "./creds.js";
+import { desktopDataDirs } from "./creds-win.js";
 import { claudeDir, claudeSettingsPath, configPath, credsPath, devicePath, projectsDir, serverUrl, stateDir, } from "./paths.js";
 import { healthWarning, loadHealth } from "./health.js";
 import { readJson } from "./util.js";
@@ -86,6 +87,31 @@ export async function doctor() {
     out.push(info(`憑證主儲存  ${isMac ? "macOS Keychain（檔案只是副本，可能過時）" : "檔案"}`));
     out.push(info(`憑證檔      ${cp}  ->  ${existsSync(cp) ? `存在 ${statSync(cp).size} bytes` : "不存在"}` +
         (!existsSync(cp) && !isMac ? "   <- 這個平台只有檔案這條路，所以是問題" : "")));
+    // ── Windows 桌面版（MSIX）──
+    // 只用桌面版、沒登入過 CLI 的人，.credentials.json 裡根本不會有 claudeAiOauth。
+    // 這一段把「桌面版憑證庫在哪、有沒有東西」攤開，否則診斷又會退回「猜 + 手寫指令」。
+    if (platform() === "win32") {
+        const dirs = desktopDataDirs();
+        if (!dirs.length) {
+            out.push(info("桌面版      找不到資料目錄（沒裝桌面版就正常）。MSIX 會把 %APPDATA%\\Claude " +
+                "重導到 %LOCALAPPDATA%\\Packages\\Claude_*\\LocalCache\\Roaming\\Claude"));
+        }
+        for (const { dir, kind } of dirs) {
+            out.push(info(`桌面版      ${dir}  (${kind})`));
+            const ls = join(dir, "Local State");
+            const cfgPath = join(dir, "config.json");
+            out.push(info(`            Local State ${existsSync(ls) ? "存在" : "不存在"} / ` +
+                `config.json ${existsSync(cfgPath) ? `${statSync(cfgPath).size} bytes` : "不存在"}`));
+            // 只印「有沒有這個鍵」，不印值 —— 值是加密的 token。
+            const cfg = readJson(cfgPath);
+            if (cfg) {
+                const keys = ["oauth:tokenCacheV2", "oauth:tokenCache"].filter((k) => cfg[k]);
+                out.push(keys.length
+                    ? info(`            token cache 鍵: ${keys.join(", ")}`)
+                    : bad(`            config.json 裡沒有 oauth:tokenCache* —— 桌面版可能沒登入`));
+            }
+        }
+    }
     let credOk = false;
     try {
         const t = loadToken();
@@ -99,7 +125,8 @@ export async function doctor() {
             out.push(`         ${line.trim()}`);
         problems.push(err.code === EXIT.TOKEN_EXPIRED
             ? "token 過期 —— 在 Claude Code 裡跑 /login"
-            : "讀不到憑證（細節見上）。本工具需要**帳號登入**（/login）；用 API key / Bedrock / Vertex 時取不到額度資訊");
+            : "讀不到憑證（細節見上）。本工具需要**帳號登入**：終端機 /login，或桌面版登入；" +
+                "用 API key / Bedrock / Vertex 時取不到額度資訊");
     }
     // ── session 資料 ──
     const pd = projectsDir();

package/dist/install.js

@@ -230,7 +230,12 @@ async function enrollStep(argv) {
             throw new Error("enroll returned non-zero");
     }
     catch (e) {
-        console.error(`enroll: FAILED (${e.message}) — hook/背景任務仍會安裝，下次 report 會自動重試`);
+        // 這句話必須與 daemon.flushUploads 的實際行為一致。它曾經承諾「會自動重試」
+        // 而程式碼並不會，於是卡住的人以為自己不用再做什麼。
+        console.error(`enroll: FAILED — ${e.message}`);
+        console.error("         hook 與背景任務仍會安裝。憑證問題解決後，背景任務會在 5 分鐘內自動完成註冊，" +
+            "不需要重跑 install。\n" +
+            "         先跑 claude-usage doctor 看是哪一種問題。");
     }
 }
 export async function install(argv = []) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsa-group/claude-usage",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Per-user Claude usage collector — measures Claude Code token detail and account-level rate-limit utilization locally, reports to your own ingest server.",
   "type": "module",
   "bin": {