docs(ai-review 使用量): 補使用量統計流程與階段十四說明

README.md

@@ -15,7 +15,7 @@
 3. 檢查是否為 AI 助理自動提交；若不是，選定 LLM provider/model、載入角色、取得 PR diff，將服務名稱、模型名稱與角色資訊 Comment 到 Pull Request，並讓每個角色個別分析 Git Diff 產生新問題表格(問題等級、角色名稱、問題位置或行數、修改建議)
 4. 讀取來源分支中的所有未解決舊問題(問題檔案 `.gitea/ai-review/findings.json`)，先套用步驟 2.5 的對話收斂結果（移除已解決對話對應的問題、加回未解決但已遺漏的問題；以「檔案路徑＋建議內容」比對，避免行號漂移誤判），再加上新問題後，去除重複產生本次 PR 的問題表格(PR問題表格)覆蓋問題檔案
 5. 讀取來源分支中的排除問題檔案(`.gitea/ai-review/exclusions.json`)，用來過濾 PR 問題表格中不需要處理的問題
-6. 將 PR 問題表格寫入 `.gitea/ai-review/findings.json`，並發布一個 Gitea Review：Review 本文只統計本次新發現的問題，使用「嚴重／警告／建議」三欄呈現各等級數量；之後將可找出檔案與行數的問題依照嚴重等級排序後加入 Review Comments 內，每個 Comment 包含嚴重等級／審查員／問題／建議，其中「問題」是審查員判斷該處有問題的原因，不是檔案路徑或行號
+6. 將 PR 問題表格寫入 `.gitea/ai-review/findings.json`，並發布一個 Gitea Review：Review 本文先以「嚴重／警告／建議」三欄分列新舊問題數量，接著附上「AI 助理使用量」區塊（本次審查累計的 token 消耗，以及目前的帳號額度）；之後將可找出檔案與行數的問題依照嚴重等級排序後加入 Review Comments 內，每個 Comment 包含嚴重等級／審查員／問題／建議，其中「問題」是審查員判斷該處有問題的原因，不是檔案路徑或行號
 7. 驗證來源分支中的 `findings.json` 與 `exclusions.json` 是否為合法 JSON array；格式錯誤時先嘗試透過 AI 修正內容，再重新驗證；修正後仍不合法才 exit 1；檔案不存在則建立並寫入 `[]`
 8. Commit 問題檔案，只將 workspace 中實際存在的 `.gitea/ai-review/findings.json` 與 `.gitea/ai-review/exclusions.json` 覆蓋到記憶區；workspace 沒有的問題檔就略過。自動提交的 commit message 會帶上 `[ai-review-bot]`，供 workflow 判斷是否要跳過重跑
 9. 如果 PR 問題表格中有嚴重問題，則不要讓 workflow 執行成功(exit 1)
@@ -38,6 +38,11 @@
     - 已解決對話以官方 API `resolvePullReviewComment`（`POST /pulls/comments/{id}/resolve`）解決
     - 與既有 findings 流程的銜接：`dropResolvedFindings` 移除已解決問題、`addCarriedFindings` 加回未解決但遺漏的問題，皆以「檔案路徑＋正規化建議內容」為簽章比對，對行號漂移與標點差異穩定，避免重複
     - 為降低 token 用量只送目標行附近視窗；任一外部呼叫失敗都降級為「視為未解決」並繼續流程
+13. AI 助理使用量統計獨立成 `app/usage.js`，於 `Step6` 發布 Review 前蒐集，同時寫入 action log 與 Review 本文，核心是呈現「剩餘可用百分比」：
+    - 本次 token 消耗：每次 LLM 呼叫都經由 `app/llm.js` 的 `chat` 集中以 `recordUsage` 累計；`extractUsage` 容錯解析各平台回應的 usage 欄位（OpenAI 相容 `usage`、OpenAI Responses `input/output_tokens`、Gemini `usageMetadata`、Ollama `eval_count`、OpenCode `tokens`）
+    - 剩餘可用百分比（`resolveRemainingPercent`）依優先序擇一：(1) 帳號額度有上限時用「剩餘 credits ÷ 上限」；(2) 否則用回應 header 的速率配額「當前視窗剩餘 ÷ 上限」。`recordRateLimit` 從回應 header 擷取 `x-ratelimit-*-tokens`（OpenAI 相容）或 `anthropic-ratelimit-tokens-*`（Claude），缺 token 維度時退用 requests 維度——此來源零額外憑證、零 CLI，直接取自既有呼叫的回應
+    - 帳號額度：`fetchAccountQuota` 依平台採不同策略——OpenRouter（`openai` slot 指向 openrouter.ai 時）以 `GET /auth/key` 取得 USD credits 已用／上限／剩餘；Ollama、OpenCode 為本地／自架服務回報「不適用」；OpenAI、Claude、Gemini、Amazon Q 的帳號額度需 org/admin 權限，API key 無法取得時誠實回報原因
+    - 兩種來源皆無法取得（例如帳號無上限且回應無速率 header）時，降級為「無法計算百分比」並附原因，不中斷流程；`formatUsageStats` 產生 Review 本文區塊，`formatUsageStatsLine` 產生單行 log 摘要
 
 # 使用說明
 

TODO.md

@@ -74,3 +74,9 @@
 - 目標：前置驗證通過、且非 AI 助理自動提交後（Step2），讀取 PR 上所有行內 review comment 並收斂成對話，請 AI 對照 PR head 最新程式碼判斷每個對話指出的問題是否已解決：已解決者用 Gitea 官方 API resolve 對話，並在 Step4 從問題清單移除；未解決且可解析回 bot finding 者，於 Step4 加回問題清單。納入判斷的對話包含所有人的留言；任一外部呼叫失敗都降級為「視為未解決」，不中斷流程。
 - 驗收：log 中能看到 `Step2` 的對話總數／已解決／待判斷統計，以及 `對話已解決並 resolve: <path>:<line>`、`對話收斂完成: resolved=.. unresolved=.. 加回 findings=..`；Step4 能看到 `對話收斂套用: N -> M 筆`；resolve / list comments / 取檔案內容 / AI 判斷任一失敗時有對應降級警告。
 - 已驗收：`app/resolve.js` 提供 `parseBotReviewComment` / `groupConversations` / `codeWindow` / `judgeConversationsResolved` / `reconcileConversations` / `dropResolvedFindings` / `addCarriedFindings`；`app/gitea.js` 新增 `listPullReviews` / `getPullReviewComments` / `listAllReviewComments` / `resolvePullReviewComment` / `getFileContentAtRef`；`main.js` 以 `Step2` 呼叫並於 `Step4` 套用結果；`app/resolve.test.js` 與擴充後的 `app/gitea.test.js` 覆蓋解析、收斂、AI 判斷對齊、resolve/降級、移除/加回去重等情境，`node --test *.test.js` 全數通過。
+
+## 階段十四：AI 助理使用量統計（多平台，呈現剩餘可用百分比）
+- 目標：統計階段（Step6 發布 Review 前）一併蒐集目前所採用 AI 助理的使用量，並同時寫入 action log 與 PR Review 本文。使用量含：本次審查累計的 token 消耗，以及「剩餘可用百分比」。需支援本工作流的所有 AI 助理平台（openai、claude、gemini、ollama、amazonq、opencode）。
+- 設計：本次 token 由 `app/llm.js` 的 `chat` 集中以 `recordUsage` 累計，`extractUsage` 容錯解析各平台回應的 usage 欄位。剩餘可用百分比由 `resolveRemainingPercent` 依優先序擇一：(1) 帳號額度有上限（OpenRouter `GET /auth/key`）→ 剩餘 credits / 上限；(2) 否則用回應 header 的速率配額（`recordRateLimit` 擷取 `x-ratelimit-*-tokens` 或 `anthropic-ratelimit-tokens-*`，退而用 requests 維度）→ 當前視窗剩餘 / 上限。`fetchAccountQuota` 依平台分流（本地/自架回報「不適用」、官方平台需 org/admin 權限時回報原因）；兩種來源皆無法取得時降級為「無法計算百分比」+原因，不中斷流程。
+- 驗收：log 中能看到 `使用量統計: 本次 <provider>/<model>: 提示N + 回應M = T token（K 次呼叫）；剩餘可用: X%（<來源> ...）` 或「無法計算」；PR Review 本文在「AI Code Review 統計」之後附上「🤖 AI 助理使用量」區塊（token 表格 + 剩餘可用百分比或無法計算原因）。
+- 已驗收：`app/usage.js` 提供 `extractUsage` / `recordUsage` / `getRunUsage` / `resetRunUsage` / `recordRateLimit` / `getRateLimit` / `resetRateLimit` / `resolveRemainingPercent` / `fetchAccountQuota` / `formatUsageStats` / `formatUsageStatsLine`；`app/llm.js` 於 OpenAI 相容路徑呼叫 `recordUsage` 與 `recordRateLimit`、OpenCode 路徑呼叫 `recordUsage`；`app/comments.js` 的 `postFindingsReview` / `buildReviewSummary` 支援附加 `usageSection`；`main.js` 於 `Step6` 蒐集（含 `getRateLimit`）並寫入 log 與 Review；`app/usage.test.js` 與擴充後的 `app/comments.test.js` 覆蓋 usage 解析/累計、速率 header 擷取、百分比解析與降級、OpenRouter 額度、格式化與 Review 本文附加等情境，`node --test *.test.js` 全數通過。