@tsa-group/claude-usage 0.4.1 → 0.4.2

package/README.md

@@ -39,76 +39,168 @@ ingest server，彙整成團隊用量儀表。
 
 ## 需求
 
-- **Node.js >= 20**
-- **Claude Code** 已登入（工具讀它的憑證來認證，見上方隱私說明）
-- macOS：完整支援並實測
-- Windows：CLI 與**桌面版（Microsoft Store / MSIX）**都支援；桌面版憑證路徑見「已知限制」
-- Linux：背景任務（systemd timer）未實作，其餘指令可用
+| | |
+|---|---|
+| **Node.js** | >= 20（`node -v` 確認） |
+| **Claude 帳號登入** | 需要**帳號登入**才拿得到額度資料。用 API key / Bedrock / Vertex 時，token 明細仍可收集，但沒有 5 小時 / 每週額度 % |
+| **平台** | macOS ✅ 完整支援　Windows ✅ CLI 與桌面版皆支援　Linux ⚠️ 指令可用，背景任務未實作 |
+
+---
+
+# 安裝
+
+**三步都一樣**，只有平台細節不同：
+
+```
+1. configure   告訴它你們的 ingest server 在哪
+2. install     取得身份 + 註冊 hook + 裝背景任務
+3. status      確認真的在跑
+```
+
+管理者會給你 **ingest server 位址**。下面用 `https://<你們的 ingest host>` 代表它。
 
 ---
 
-## 安裝（3 步）
+## macOS
 
 ```bash
 npm i -g @tsa-group/claude-usage
 
-# 1) 指向你們的 ingest server
 claude-usage configure --server https://<你們的 ingest host>
-
-# 2) 一鍵安裝：enroll（取得身份）+ 註冊 SessionStart hook + 背景任務
-#    先加 --dry-run 可預覽會做什麼、不動任何系統設定
-claude-usage install --dry-run
+claude-usage install --dry-run     # 先看它會做什麼，不動任何設定
 claude-usage install
-
-# 3) 確認狀態
 claude-usage status
 ```
 
-### Windows / PowerShell 首次執行
+憑證走 **Keychain**（Claude Code 的主儲存）。首次執行可能跳出鑰匙圈授權，允許即可 ——
+背景任務要能在沒有視窗的情況下讀到它。
+
+---
+
+## Windows
+
+### 第 0 步：先確認 PowerShell 不會擋
 
-多數 Windows 的 PowerShell 執行原則預設是 `Restricted`，會擋掉 npm 產生的 `.ps1`
-啟動器 —— **安裝成功、一執行就被擋**：
+多數 Windows 的執行原則預設是 `Restricted`，會擋掉 npm 產生的 `.ps1` 啟動器 ——
+**安裝成功、一執行就被擋**：
 
 ```
 因為這個系統上已停用指令碼執行，所以無法載入 ...\npm\claude-usage.ps1
 + FullyQualifiedErrorId : UnauthorizedAccess  (PSSecurityException)
 ```
 
-這**不是套件的問題**，`cmd.exe` 與 Node 本身都不受影響。擇一處理：
+這不是套件的問題（`cmd.exe` 與 Node 本身都不受影響）。先查現況：
+
+```powershell
+Get-ExecutionPolicy
+```
+
+| 結果 | 怎麼辦 |
+|---|---|
+| `RemoteSigned` / `Unrestricted` / `Bypass` | 不用處理，直接往下 |
+| `Restricted` / `AllSigned` | 用下面 **A** 或 **B** |
+
+**A. 改原則（推薦，免系統管理員、一次搞定）**
 
 ```powershell
-# 1) 設定一次、永久生效、免系統管理員（推薦）
 Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+```
+
+`RemoteSigned` = 本機與 npm 的腳本可跑，只擋網路下載的未簽章腳本。
+
+**B. 不改原則，全程加 `.cmd`**（功能完全一樣）
 
-# 2) 不改原則，改叫 .cmd 啟動器（功能完全一樣）
+```powershell
+npm.cmd i -g @tsa-group/claude-usage
+claude-usage.cmd configure --server https://<你們的 ingest host>
+claude-usage.cmd install
 claude-usage.cmd status
 ```
 
-`RemoteSigned` = 本機與 npm 的腳本可跑，只擋網路下載的未簽章腳本。
-公司用 GPO 鎖了機器層級原則時 (1) 會被覆寫 —— 直接用 (2)。
-現況查詢：`Get-ExecutionPolicy -List`
+> 公司用 GPO 鎖了機器層級原則時，**A 會被覆寫** —— 直接用 B。
+> 查誰在管：`Get-ExecutionPolicy -List`
+
+### 第 1 步：安裝
+
+```powershell
+npm i -g @tsa-group/claude-usage
 
-> 安裝時若偵測到會擋的原則，`postinstall` 會主動提醒；事後也可用
-> `claude-usage.cmd doctor` 檢查。**但工具無法在被擋的當下自己說話** ——
-> PowerShell 在 Node 啟動前就拒絕了，所以這段提示只能寫在這裡。
+claude-usage configure --server https://<你們的 ingest host>
+claude-usage install --dry-run
+claude-usage install
+claude-usage status
+```
+
+（走 B 方案的人全部加 `.cmd`。）
+
+### 你是用終端機的 `claude`，還是桌面版 App？
+
+**兩種都支援，不必改用哪一個** —— 但憑證存放位置完全不同，卡住時要知道差別：
+
+| | 終端機 CLI | 桌面版 App |
+|---|---|---|
+| 憑證位置 | `%USERPROFILE%\.claude\.credentials.json` | 桌面版自己的加密儲存 |
+| 形式 | 純文字 | DPAPI + AES-256-GCM 加密 |
+| 需要什麼 | 跑過 `claude` 並完成登入 | 桌面版登入過 |
+
+**只用桌面版、從沒登入過終端機 `claude` 的人也能用** —— 工具會自動去解桌面版的憑證庫
+（見「隱私」段）。解密只在你自己的機器、你自己的 Windows 帳號下進行。
+
+不想走那條路的話，在終端機跑一次 `claude` 登入即可，工具會優先用那份純文字憑證。
+
+---
+
+## 確認安裝成功
+
+```bash
+claude-usage status
+```
+
+成功長這樣（重點是標示的那三行）：
+
+```
+state dir: /Users/you/.claude-usage
+server:    https://<你們的 ingest host>
+enrolled:  yes                     <-- 拿到身份了
+hook:      registered              <-- 開 session 時會自動採樣
+  last_sample_status  : ok
+  last_upload_state   : uploaded
+  status              : ok         <-- 採集正常
+  state = not running                 (背景任務平常就是閒置，每 5 分鐘才醒一次)
+  runs = 12
+```
+
+`state = not running` 是**正常的** —— 背景任務不是常駐程式，每 5 分鐘被叫醒一次。
+`runs` 有在累加就代表它真的有跑。
+
+`status` 在採集不健康時會 **exit 1**，可以接監控。
 
-**兩個可能讓你以為「裝壞了」的情況：**
+**接著還有一步不在你這邊**：若你們的 server 開了人工核准，`enroll` 會回
+`status: pending` —— 你這邊一切正常，但要等管理者按核准，資料才會開始進去。
+**這是正常的，不是裝壞了。**
 
-- **server 開了人工核准** → `enroll` 會回 `status: pending`，你的資料要等管理者核准後才
-  開始進來。`status` 會顯示已 enroll、心跳正常，但 server 端看不到你的用量。這是正常的。
-- **server 要求 enroll 密語**（多數部署不需要）→ `install --enroll-secret <密語>`，或用
-  環境變數 `CLAUDE_USAGE_ENROLL_SECRET`。⚠️ 寫在指令列會留在你的 shell history 裡，
-  能用環境變數就用環境變數。
+---
+
+## 卡住了？先跑這個
+
+```bash
+claude-usage doctor          # Windows 走 B 方案的人：claude-usage.cmd doctor
+```
+
+它會印出**解析到的每個路徑，與那裡實際有什麼** —— 路徑對不對通常你一眼就看得出來
+（「那不是我 Claude Code 裝的地方」），前提是有人把路徑印出來。
 
-安裝後會發生：
+把整段輸出貼給管理者即可，裡面**不含任何 token 值**。
 
-- **hook**（開 session 時）：抓一筆即時額度快照。註冊在 `~/.claude/settings.json` 的
-  `SessionStart`，**fire-and-forget、失敗永遠安靜、10 分鐘去抖動** —— 採集用量絕不該擋住或
-  拖慢你開 session。
-- **背景任務**（macOS launchd / Windows 工作排程器）：每 5 分鐘喚醒一次，**自我判斷**是否要
-  採樣，並非同步上傳。採樣間隔自適應：有在用 15 分鐘、閒置退避到 60 分鐘。
-- 升級（`npm update -g @tsa-group/claude-usage`）後**請重跑一次 `claude-usage install`**：
-  背景任務與 hook 記的是絕對路徑，換了 Node 版本或安裝位置就要重新註冊。
+常見症狀對照：
+
+| 症狀 | 多半是 |
+|---|---|
+| `UnauthorizedAccess` / `PSSecurityException` | PowerShell 執行原則，見 Windows 第 0 步 |
+| `cannot read credentials (… file-no-oauth-key …)` | 只用桌面版、沒登入過終端機 `claude`。0.4.0 起會自動去讀桌面版憑證；若仍失敗，`doctor` 會指出卡在哪一步 |
+| `access token EXPIRED` | 重新登入 Claude Code（終端機 `/login` 或桌面版）即可換發 |
+| `status` 一切正常但 server 看不到我的用量 | 等管理者核准（見上） |
+| `沒有任何 .jsonl` | 本工具與 Claude Code 不在同一個環境（WSL？另一個帳號？`CLAUDE_CONFIG_DIR`？） |
 
 ---
 
@@ -251,8 +343,7 @@ Client 對 server 只用兩個端點，皆為 `application/json`：
 - **Windows 背景任務未完整實機驗證**：schtasks + VBS 隱藏視窗啟動器。裝完請用
   `claude-usage status` 確認有心跳。
 - **PowerShell 執行原則**：預設 `Restricted` 會同時擋掉 `npm.ps1`（安裝時）與
-  `claude-usage.ps1`（執行時）。安裝用 `npm.cmd i -g …`；其餘見上面
-  「Windows / PowerShell 首次執行」。
+  `claude-usage.ps1`（執行時）。處理方式見上面 **Windows → 第 0 步**。
 - **Linux 背景任務未實作**（systemd --user timer）。其餘指令可用。
 - **`session_id` 跨 compaction / resume 不穩定**：session **數**會高估。token 與成本不受影響
   （那是 per-event 去重的，與 session 身份無關）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsa-group/claude-usage",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "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": {