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

2026-06-23 12:58:43 +08:00
parent a27555b35a
commit 5f468c0d03
2 changed files with 12 additions and 1 deletions
@@ -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` 全數通過。