@tsa-group/claude-usage 0.3.5 → 0.4.1

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）未實作，其餘指令可用
 
 ---
@@ -51,6 +64,34 @@ claude-usage install
 claude-usage status
 ```
 
+### Windows / PowerShell 首次執行
+
+多數 Windows 的 PowerShell 執行原則預設是 `Restricted`，會擋掉 npm 產生的 `.ps1`
+啟動器 —— **安裝成功、一執行就被擋**：
+
+```
+因為這個系統上已停用指令碼執行，所以無法載入 ...\npm\claude-usage.ps1
++ FullyQualifiedErrorId : UnauthorizedAccess  (PSSecurityException)
+```
+
+這**不是套件的問題**，`cmd.exe` 與 Node 本身都不受影響。擇一處理：
+
+```powershell
+# 1) 設定一次、永久生效、免系統管理員（推薦）
+Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+
+# 2) 不改原則，改叫 .cmd 啟動器（功能完全一樣）
+claude-usage.cmd status
+```
+
+`RemoteSigned` = 本機與 npm 的腳本可跑，只擋網路下載的未簽章腳本。
+公司用 GPO 鎖了機器層級原則時 (1) 會被覆寫 —— 直接用 (2)。
+現況查詢：`Get-ExecutionPolicy -List`
+
+> 安裝時若偵測到會擋的原則，`postinstall` 會主動提醒；事後也可用
+> `claude-usage.cmd doctor` 檢查。**但工具無法在被擋的當下自己說話** ——
+> PowerShell 在 Node 啟動前就拒絕了，所以這段提示只能寫在這裡。
+
 **兩個可能讓你以為「裝壞了」的情況：**
 
 - **server 開了人工核准** → `enroll` 會回 `status: pending`，你的資料要等管理者核准後才
@@ -202,9 +243,16 @@ 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 執行原則**：預設 `Restricted` 會同時擋掉 `npm.ps1`（安裝時）與
+  `claude-usage.ps1`（執行時）。安裝用 `npm.cmd i -g …`；其餘見上面
+  「Windows / PowerShell 首次執行」。
 - **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/doctor.js

@@ -9,10 +9,12 @@
  * 路徑對不對是使用者一眼就能判斷的事（「那不是我的 Claude Code 裝的地方」），
  * 但前提是我們得把路徑印出來。
  */
+import { spawnSync } from "node:child_process";
 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 +88,51 @@ export async function doctor() {
     out.push(info(`憑證主儲存  ${isMac ? "macOS Keychain（檔案只是副本，可能過時）" : "檔案"}`));
     out.push(info(`憑證檔      ${cp}  ->  ${existsSync(cp) ? `存在 ${statSync(cp).size} bytes` : "不存在"}` +
         (!existsSync(cp) && !isMac ? "   <- 這個平台只有檔案這條路，所以是問題" : "")));
+    // ── Windows：PowerShell 執行原則 ──
+    // 這個問題有個特別惡劣的性質：**它發生時我們的程式碼根本沒機會執行** ——
+    // PowerShell 在 Node 啟動前就拒絕載入 claude-usage.ps1。所以工具無法在出錯當下
+    // 自我診斷，只能在 postinstall 事先講、或在這裡（使用者改用 .cmd 跑得起來時）補講。
+    if (platform() === "win32") {
+        const r = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", "Get-ExecutionPolicy"], { encoding: "utf8", timeout: 10_000, windowsHide: true });
+        const policy = r.error || r.status !== 0 ? null : (r.stdout ?? "").trim();
+        if (!policy) {
+            out.push(info("執行原則    查不到（powershell.exe 不可用？）"));
+        }
+        else if (policy === "Restricted" || policy === "AllSigned") {
+            out.push(bad(`執行原則    ${policy} —— PowerShell 會擋掉 claude-usage.ps1 啟動器`));
+            problems.push(`PowerShell 執行原則是 ${policy}（錯誤含 UnauthorizedAccess / ExecutionPolicy）。` +
+                `擇一：Set-ExecutionPolicy -Scope CurrentUser RemoteSigned（免管理員），` +
+                `或直接用 claude-usage.cmd。公司 GPO 鎖機器層級時只能用後者`);
+        }
+        else {
+            out.push(ok(`執行原則    ${policy}（不會擋 .ps1 啟動器）`));
+        }
+    }
+    // ── 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 +146,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsa-group/claude-usage",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "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": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "postinstall.mjs"
   ],
   "engines": {
     "node": ">=20"
@@ -17,7 +18,8 @@
     "build": "tsc -p tsconfig.json",
     "test": "node --test test/*.test.ts",
     "prepublishOnly": "npm run build && npm test",
-    "check": "tsc -p tsconfig.json --noEmit"
+    "check": "tsc -p tsconfig.json --noEmit",
+    "postinstall": "node postinstall.mjs"
   },
   "keywords": [
     "claude",

package/postinstall.mjs

@@ -0,0 +1,59 @@
+/**
+ * 安裝後提示：Windows 的 PowerShell 執行原則會擋掉 npm 產生的 .ps1 啟動器。
+ *
+ * ★ 為什麼一定要在這裡講：這個失敗發生時**我們的程式碼根本沒機會執行** ——
+ * PowerShell 在 Node 啟動前就拒絕載入 `claude-usage.ps1` 了。所以工具永遠無法在
+ * 出錯當下自我診斷，提示只能前置，而 postinstall 是唯一「撞牆之前還能說話」的
+ * 時機（它由 Node 執行，不受 .ps1 原則管制）。
+ *
+ * ★ 為什麼要先偵測而不是無條件印：無條件每次安裝都印一段警告，就是在訓練人忽略
+ * 它 —— 等真的出事那次也會被跳過。只在**實際會擋**的機器上印，訊息才有訊號價值。
+ *
+ * ★ 為什麼這支檔案刻意獨立、不 import dist/：postinstall 失敗會讓整個安裝失敗。
+ * 它必須在 dist 壞掉、Node 版本奇怪、或任何預期外的狀況下都安靜地成功。
+ * 與 doctor 裡那份偵測有少量重複，那是刻意的隔離。
+ */
+import { spawnSync } from "node:child_process";
+
+// 這兩種原則會擋掉 .ps1 啟動器。RemoteSigned / Unrestricted / Bypass 都不會。
+const BLOCKING = new Set(["Restricted", "AllSigned"]);
+
+function effectivePolicy() {
+  const r = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", "Get-ExecutionPolicy"], {
+    encoding: "utf8",
+    timeout: 10_000,
+    windowsHide: true,
+  });
+  if (r.error || r.status !== 0) return null;
+  return (r.stdout ?? "").trim() || null;
+}
+
+try {
+  if (process.platform === "win32") {
+    const policy = effectivePolicy();
+    if (policy && BLOCKING.has(policy)) {
+      const L = [
+        "",
+        `  ⚠ PowerShell 執行原則是 ${policy} —— 在 PowerShell 直接打 claude-usage 會被擋`,
+        "     （錯誤訊息含 UnauthorizedAccess / PSSecurityException / ExecutionPolicy）",
+        "",
+        "     擇一處理：",
+        "     1) 設定一次、永久生效、免系統管理員：",
+        "          Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned",
+        "        RemoteSigned = 本機與 npm 的腳本可跑，只擋網路下載的未簽章腳本。",
+        "     2) 不改原則，改叫 .cmd 啟動器（功能完全一樣）：",
+        "          claude-usage.cmd status",
+        "",
+        "     公司用 GPO 鎖了機器層級原則時，(1) 會被覆寫 —— 直接用 (2)。",
+        "     現況查詢： Get-ExecutionPolicy -List",
+        "",
+      ];
+      console.log(L.join("\n"));
+    }
+  }
+} catch {
+  // 提示壞掉絕不能讓安裝失敗
+}
+
+// 無論如何都成功收場
+process.exitCode = 0;