From f5105d8a468e422f005f6e78e1792fa4d19cc696 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Sat, 11 Jul 2026 12:36:16 +0000 Subject: [PATCH] =?UTF-8?q?docs(README):=20=E9=87=8D=E5=BB=BA=E5=B0=88?= =?UTF-8?q?=E6=A1=88=E6=96=87=E4=BB=B6=E8=88=87=E5=8A=9F=E8=83=BD=E7=B4=A2?= =?UTF-8?q?=E5=BC=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 1467 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1467 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..a999bd1 --- /dev/null +++ b/README.md @@ -0,0 +1,1467 @@ +# AI Code Review + +更新時間：2026/07/11 19:18:23 + +## 專案列表 + +| 專案名稱 | 專案描述 | +| --- | --- | +| [AI Code Review](https://gitea.jsc.idv.tw/actions/ai-code-review/src/branch/develop/) | 此專案提供 Gitea 工作流程中的 AI 程式碼審查、findings / exclusions 管理、LLM CLI 橋接與 git / Gitea 前置驗證工具。 | + +| 專案名稱 | 參考專案列表 | +| --- | --- | +| [AI Code Review](https://gitea.jsc.idv.tw/actions/ai-code-review/src/branch/develop/) | 無 | + +| 專案名稱 | NuGet 套件列表 | +| --- | --- | +| [AI Code Review](https://gitea.jsc.idv.tw/actions/ai-code-review/src/branch/develop/) | 無 | + +## 功能列表 + +### AI Code Review + +| 功能名稱 | 功能描述 | +| --- | --- | +| [parseLocation](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/comments.js#L66) | [解析 finding location 為檔案與行號。](#parselocation) | +| [formatFindingsStats](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/comments.js#L150) | [產生 findings 統計表格。](#formatfindingsstats) | +| [formatFindingsStatsLine](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/comments.js#L171) | [產生 findings 單行統計摘要。](#formatfindingsstatsline) | +| [postFindingsReview](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/comments.js#L220) | [發布 findings 的 Gitea review。](#postfindingsreview) | +| [saveFindings](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/comments.js#L259) | [將 findings 寫入工作區與鏡像目錄。](#savefindings) | +| [postOldFindingsComment](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/comments.js#L274) | [發布舊問題的 comment。](#postoldfindingscomment) | +| [postNewNonCriticalComment](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/comments.js#L288) | [發布新問題中的非嚴重 comment。](#postnewnoncriticalcomment) | +| [postNewCriticalComments](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/comments.js#L304) | [發布新嚴重問題的 comment。](#postnewcriticalcomments) | +| [getInsecureHttpsAgent](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/config.js#L60) | [取得一個關閉 TLS 憑證驗證的 HTTPS Agent 單例，供內部服務連線使用。](#getinsecurehttpsagent) | +| [getLLMCLICommands](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/config.js#L100) | [取得目前支援的 LLM CLI 指令名稱清單。](#getllmclicommands) | +| [getLLMConfig](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/config.js#L130) | [依環境變數與 CLI 可用性解析目前可用的 LLM 提供者設定。](#getllmconfig) | +| [analyzeWithRole](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/findings.js#L14) | [用指定角色分析 diff 並產生 findings。](#analyzewithrole) | +| [normalizeText](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/findings.js#L120) | [將文字正規化成比對用形式。](#normalizetext) | +| [loadOldFindings](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/findings.js#L302) | [讀取舊 findings 並標記為舊問題。](#loadoldfindings) | +| [mergeFindings](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/findings.js#L319) | [合併新舊 findings 並去重。](#mergefindings) | +| [sortByLevel](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/findings.js#L335) | [依嚴重度排序 findings。](#sortbylevel) | +| [resolveMissingLineNumbers](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/findings.js#L376) | [為缺少行號的 findings 補上行號。](#resolvemissinglinenumbers) | +| [deduplicateWithAI](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/findings.js#L423) | [用 AI 進行 findings 語意去重。](#deduplicatewithai) | +| [loadExclusions](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/findings.js#L450) | [讀取並正規化 exclusions。](#loadexclusions) | +| [appendExclusions](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/findings.js#L500) | [將新的排除條目追加到 exclusions 檔。](#appendexclusions) | +| [applyExclusions](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/findings.js#L544) | [依 exclusions 過濾 findings。](#applyexclusions) | +| [filterFalsePositivesWithAI](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/findings.js#L577) | [用 AI 過濾誤報 findings。](#filterfalsepositiveswithai) | +| [getRepoState](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/git.js#L120) | [讀取指定 git repo 的基本狀態快照，包含 HEAD、分支與 commit 時間。](#getrepostate) | +| [getHeadCommitMessage](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/git.js#L138) | [讀取指定 repo 的 HEAD commit 完整 commit message，失敗時保守回傳空字串。](#getheadcommitmessage) | +| [isBotAutoCommit](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/git.js#L153) | [判斷 HEAD commit 是否由 AI Review bot 自動產生，避免重複觸發後續流程。](#isbotautocommit) | +| [verifyRemoteAccess](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/git.js#L163) | [先用 `git ls-remote` 驗證 remote 認證與連線是否可用，失敗時回傳結構化錯誤。](#verifyremoteaccess) | +| [cloneRepo](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/git.js#L178) | [以可重入方式抓取 PR head branch 到工作目錄內的 `repo` 資料夾。](#clonerepo) | +| [commitAndPush](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/git.js#L220) | [將 AI 審查產出的檔案結轉、提交並推回 PR head branch，失敗時保守記錄 log 而不中斷流程。](#commitandpush) | +| [getBotReviewOutcome](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/gitea.js#L39) | [解析 AI Review bot 的結果標記，回傳 success、failure 或 unknown。](#getbotreviewoutcome) | +| [parseReviewIgnore](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/gitea.js#L62) | [把 `.reviewignore` 文字解析成可用的排除前綴陣列。](#parsereviewignore) | +| [getReviewIgnore](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/gitea.js#L74) | [讀取並解析 PR 的 `.reviewignore`，沒有自訂規則時回退預設排除清單。](#getreviewignore) | +| [getPRDiff](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/gitea.js#L89) | [取得目前 PR 的 unified diff，並套用 `.reviewignore` 與內建過濾規則。](#getprdiff) | +| [getCommitMessageBySha](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/gitea.js#L101) | [依 commit SHA 讀取 Gitea 上的 commit message，失敗時保守回空字串。](#getcommitmessagebysha) | +| [getBranchHeadCommitMessage](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/gitea.js#L122) | [讀取指定分支 head commit 的訊息，失敗時保守回空字串。](#getbranchheadcommitmessage) | +| [shouldSkipBotCommit](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/gitea.js#L147) | [判斷目前 PR head 是否為 bot 自動提交，若是就跳過後續審查流程。](#shouldskipbotcommit) | +| [filterDiff](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/gitea.js#L164) | [過濾 unified diff 中不需要審查的路徑區塊，保留其餘內容。](#filterdiff) | +| [postComment](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/gitea.js#L184) | [在 PR 底下發布一則 Markdown 留言，適合非行內評論用途。](#postcomment) | +| [postPullReviewComment](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/gitea.js#L203) | [對 PR 指定檔案與行號發送單筆行內 review comment。](#postpullreviewcomment) | +| [postPullReview](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/gitea.js#L226) | [建立一則包含摘要與多筆行內 comment 的 PR review。](#postpullreview) | +| [listPullReviews](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/gitea.js#L246) | [列出目前 PR 的所有 review，回應格式不正確時保守回空陣列。](#listpullreviews) | +| [getPullReviewComments](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/gitea.js#L260) | [依 review ID 取得該 review 底下的所有行內 comment。](#getpullreviewcomments) | +| [listAllReviewComments](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/gitea.js#L274) | [彙整目前 PR 的所有 review comments，單筆失敗時略過並持續處理。](#listallreviewcomments) | +| [resolvePullReviewComment](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/gitea.js#L296) | [解決指定 review comment 對話，對應 Gitea 的 resolve API。](#resolvepullreviewcomment) | +| [getFileContentAtRef](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/gitea.js#L313) | [讀取指定 ref 下的檔案文字內容，支援 base64 解碼並在失敗時保守回空字串。](#getfilecontentatref) | +| [stripCodeFence](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/json.js#L17) | [移除文字外層的 markdown code fence，並清理前後空白。](#stripcodefence) | +| [repairJSONArrayWithAI](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/json.js#L43) | [透過 LLM 將原始內容修復成可直接 JSON.parse 的 JSON 陣列字串。](#repairjsonarraywithai) | +| [validateJSONArrayFile](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/json.js#L93) | [驗證 JSON 檔案是否合法，必要時嘗試透過 AI 修復一次。](#validatejsonarrayfile) | +| [ensureJSONArrayFileExists](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/json.js#L134) | [確保指定路徑存在一個 JSON 檔案，不存在時建立空陣列檔。](#ensurejsonarrayfileexists) | +| [mapWithConcurrency](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/llm.js#L25) | [以可控制併發數的方式並行處理陣列項目。](#mapwithconcurrency) | +| [extractMeaningfulError](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/llm.js#L96) | [從 CLI 原始輸出中擷取最有用的錯誤訊息。](#extractmeaningfulerror) | +| [chat](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/llm.js#L190) | [呼叫可用的 AI 助理 CLI，並回傳文字回應。](#chat) | +| [chatJSON](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/llm.js#L218) | [呼叫 AI 助理並把回應解析成 JSON。](#chatjson) | +| [extractBalancedJSON](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/llm.js#L255) | [從指定索引開始擷取完整平衡的 JSON 片段。](#extractbalancedjson) | +| [extractJSONText](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/llm.js#L298) | [從雜訊文字中抽出最可能的 JSON 內容。](#extractjsontext) | +| [section](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/log.js#L9) | [輸出最上層區塊標題，用來切分整體執行流程。](#section) | +| [step](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/log.js#L22) | [輸出流程中的步驟標題，標示某一小段工作內容。](#step) | +| [line](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/log.js#L34) | [輸出一行中性的明細資訊。](#line) | +| [input](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/log.js#L45) | [輸出某一步驟的輸入描述，方便追蹤資料來源。](#input) | +| [output](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/log.js#L56) | [輸出某一步驟的產出描述，方便追蹤結果。](#output) | +| [result](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/log.js#L69) | [依布林值輸出成功或失敗的檢查結果。](#result) | +| [ok](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/log.js#L81) | [輸出一筆成功或完成訊息。](#ok) | +| [warn](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/log.js#L93) | [輸出一筆警告訊息到 stderr。](#warn) | +| [error](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/log.js#L105) | [輸出一筆錯誤訊息到 stderr。](#error) | +| [main](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/main.js#L55) | [執行 AI Code Review Pipeline 的完整流程。](#main) | +| [checkRequiredEnv](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/preflight.js#L60) | [檢查前置驗證所需的必要環境值是否齊全。](#checkrequiredenv) | +| [verifyGiteaToken](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/preflight.js#L77) | [驗證 Gitea token 是否可讀取指定 repository。](#verifygiteatoken) | +| [verifyCommentToken](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/preflight.js#L94) | [驗證 comment token 是否可用；未提供時回傳 skipped。](#verifycommenttoken) | +| [fetchCodexModels](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/preflight.js#L118) | [讀取本機 codex 認證檔並取得目前可用的模型 slug 清單。](#fetchcodexmodels) | +| [verifyLLM](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/preflight.js#L171) | [驗證目前環境是否有可用的 LLM CLI 與對應模型設定。](#verifyllm) | +| [runPreflight](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/preflight.js#L203) | [執行所有前置驗證流程，任一失敗即回傳 false。](#runpreflight) | +| [parseBotReviewComment](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/resolve.js#L51) | [解析 bot 產生的 review comment，還原成 finding 欄位物件。](#parsebotreviewcomment) | +| [groupConversations](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/resolve.js#L73) | [依檔案路徑與行號把 review comments 收斂成對話群組。](#groupconversations) | +| [codeWindow](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/resolve.js#L100) | [擷取目標行附近的程式碼片段，供 AI 判讀。](#codewindow) | +| [judgeConversations](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/resolve.js#L126) | [處理 judgeConversations 相關邏輯。](#judgeconversations) | +| [isSafeRepoPath](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/resolve.js#L174) | [檢查路徑是否安全，避免讀取 repo 外檔案。](#issaferepopath) | +| [reconcileConversations](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/resolve.js#L190) | [收斂 PR review 對話，並依 AI 裁定回填 findings 的去向。](#reconcileconversations) | +| [dropResolvedFindings](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/resolve.js#L329) | [移除已解決對話對應的 findings。](#dropresolvedfindings) | +| [addCarriedFindings](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/resolve.js#L338) | [將仍成立但缺漏的 findings 補回清單。](#addcarriedfindings) | +| [parseRoleFile](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/roles.js#L25) | [解析角色 Markdown 檔，取出 frontmatter 與本文。](#parserolefile) | +| [loadRoles](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/roles.js#L71) | [只載入攻擊方角色。](#loadroles) | +| [loadRole](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/roles.js#L85) | [依名稱查找單一角色。](#loadrole) | +| [buildAnalysisPrompt](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/roles.js#L104) | [產生攻擊方角色的程式碼審查 system prompt。](#buildanalysisprompt) | +| [buildLocateLinePrompt](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/roles.js#L149) | [產生用來補 finding 行號的 prompt。](#buildlocatelineprompt) | +| [buildVerdictPrompt](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/roles.js#L173) | [產生單條 finding 的誤報裁決 prompt。](#buildverdictprompt) | +| [getRoleIntro](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/roles.js#L206) | [產生 AI Code Review 團隊的 Markdown 介紹表。](#getroleintro) | +| [extractUsage](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/usage.js#L24) | [從 LLM 回應抽出 token usage。](#extractusage) | +| [recordUsage](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/usage.js#L65) | [記錄一次 LLM 呼叫使用量。](#recordusage) | +| [getRunUsage](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/usage.js#L77) | [取得目前累積的使用量。](#getrunusage) | +| [resetRunUsage](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/usage.js#L82) | [重置執行中的 usage 累計。](#resetrunusage) | +| [recordRateLimit](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/usage.js#L109) | [記錄最近一次速率配額資訊。](#recordratelimit) | +| [getRateLimit](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/usage.js#L130) | [取得最近一次 rate limit 快照。](#getratelimit) | +| [resetRateLimit](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/usage.js#L135) | [重置 rate limit 快照。](#resetratelimit) | +| [fetchAccountQuota](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/usage.js#L209) | [查詢指定平台的帳號額度。](#fetchaccountquota) | +| [resolveRemainingPercent](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/usage.js#L278) | [計算可用額度剩餘百分比。](#resolveremainingpercent) | +| [formatUsageStats](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/usage.js#L315) | [產生 AI 助理使用量 Markdown 區塊。](#formatusagestats) | +| [formatUsageStatsLine](https://gitea.jsc.idv.tw/actions/ai-code-review/blob/develop/src/usage.js#L334) | [產生使用量單行摘要。](#formatusagestatsline) | + +## 使用範例 + +### parseLocation + +解析 finding location 為檔案與行號。 + +檔案位置：`src/comments.js` 第 66 行。 + +```js +const result = parseLocation(location); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### formatFindingsStats + +產生 findings 統計表格。 + +檔案位置：`src/comments.js` 第 150 行。 + +```js +const result = formatFindingsStats(findings); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### formatFindingsStatsLine + +產生 findings 單行統計摘要。 + +檔案位置：`src/comments.js` 第 171 行。 + +```js +const result = formatFindingsStatsLine(findings); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### postFindingsReview + +發布 findings 的 Gitea review。 + +檔案位置：`src/comments.js` 第 220 行。 + +```js +const result = await postFindingsReview(findings, deps); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：完成對外部系統的寫入、發佈或執行動作。 + +### saveFindings + +將 findings 寫入工作區與鏡像目錄。 + +檔案位置：`src/comments.js` 第 259 行。 + +```js +const result = saveFindings(workspace, findings, mirrorDir); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：完成對外部系統的寫入、發佈或執行動作。 + +### postOldFindingsComment + +發布舊問題的 comment。 + +檔案位置：`src/comments.js` 第 274 行。 + +```js +const result = await postOldFindingsComment(findings); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：完成對外部系統的寫入、發佈或執行動作。 + +### postNewNonCriticalComment + +發布新問題中的非嚴重 comment。 + +檔案位置：`src/comments.js` 第 288 行。 + +```js +const result = await postNewNonCriticalComment(findings); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：完成對外部系統的寫入、發佈或執行動作。 + +### postNewCriticalComments + +發布新嚴重問題的 comment。 + +檔案位置：`src/comments.js` 第 304 行。 + +```js +const result = await postNewCriticalComments(findings, deps); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：完成對外部系統的寫入、發佈或執行動作。 + +### getInsecureHttpsAgent + +取得一個關閉 TLS 憑證驗證的 HTTPS Agent 單例，供內部服務連線使用。 + +檔案位置：`src/config.js` 第 60 行。 + +```js +const result = getInsecureHttpsAgent(); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### getLLMCLICommands + +取得目前支援的 LLM CLI 指令名稱清單。 + +檔案位置：`src/config.js` 第 100 行。 + +```js +const result = getLLMCLICommands(); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### getLLMConfig + +依環境變數與 CLI 可用性解析目前可用的 LLM 提供者設定。 + +檔案位置：`src/config.js` 第 130 行。 + +```js +const result = getLLMConfig(commandExistsFn); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### analyzeWithRole + +用指定角色分析 diff 並產生 findings。 + +檔案位置：`src/findings.js` 第 14 行。 + +```js +const result = await analyzeWithRole(role, diff); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### normalizeText + +將文字正規化成比對用形式。 + +檔案位置：`src/findings.js` 第 120 行。 + +```js +const result = normalizeText(value); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### loadOldFindings + +讀取舊 findings 並標記為舊問題。 + +檔案位置：`src/findings.js` 第 302 行。 + +```js +const result = loadOldFindings(workspace); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### mergeFindings + +合併新舊 findings 並去重。 + +檔案位置：`src/findings.js` 第 319 行。 + +```js +const result = mergeFindings(oldFindings, newFindings); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### sortByLevel + +依嚴重度排序 findings。 + +檔案位置：`src/findings.js` 第 335 行。 + +```js +const result = sortByLevel(findings); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### resolveMissingLineNumbers + +為缺少行號的 findings 補上行號。 + +檔案位置：`src/findings.js` 第 376 行。 + +```js +const result = await resolveMissingLineNumbers(findings, diff, deps); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### deduplicateWithAI + +用 AI 進行 findings 語意去重。 + +檔案位置：`src/findings.js` 第 423 行。 + +```js +const result = await deduplicateWithAI(findings); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### loadExclusions + +讀取並正規化 exclusions。 + +檔案位置：`src/findings.js` 第 450 行。 + +```js +const result = loadExclusions(workspace, repoState, mirrorWorkspace); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### appendExclusions + +將新的排除條目追加到 exclusions 檔。 + +檔案位置：`src/findings.js` 第 500 行。 + +```js +const result = appendExclusions(workspace, newEntries, mirrorWorkspace); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：完成對外部系統的寫入、發佈或執行動作。 + +### applyExclusions + +依 exclusions 過濾 findings。 + +檔案位置：`src/findings.js` 第 544 行。 + +```js +const result = applyExclusions(findings, exclusions); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### filterFalsePositivesWithAI + +用 AI 過濾誤報 findings。 + +檔案位置：`src/findings.js` 第 577 行。 + +```js +const result = await filterFalsePositivesWithAI(findings, exclusions, chatFn); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### getRepoState + +讀取指定 git repo 的基本狀態快照，包含 HEAD、分支與 commit 時間。 + +檔案位置：`src/git.js` 第 120 行。 + +```js +const result = getRepoState(repoDir, _spawnSync); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### getHeadCommitMessage + +讀取指定 repo 的 HEAD commit 完整 commit message，失敗時保守回傳空字串。 + +檔案位置：`src/git.js` 第 138 行。 + +```js +const result = getHeadCommitMessage(repoDir, _spawnSync); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### isBotAutoCommit + +判斷 HEAD commit 是否由 AI Review bot 自動產生，避免重複觸發後續流程。 + +檔案位置：`src/git.js` 第 153 行。 + +```js +const result = isBotAutoCommit(repoDir, _spawnSync); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### verifyRemoteAccess + +先用 `git ls-remote` 驗證 remote 認證與連線是否可用，失敗時回傳結構化錯誤。 + +檔案位置：`src/git.js` 第 163 行。 + +```js +const result = verifyRemoteAccess(workspace, _spawnSync); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳驗證成功/失敗的結構化結果。 + +### cloneRepo + +以可重入方式抓取 PR head branch 到工作目錄內的 `repo` 資料夾。 + +檔案位置：`src/git.js` 第 178 行。 + +```js +const result = cloneRepo(workspace, _spawnSync); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：完成對外部系統的寫入、發佈或執行動作。 + +### commitAndPush + +將 AI 審查產出的檔案結轉、提交並推回 PR head branch，失敗時保守記錄 log 而不中斷流程。 + +檔案位置：`src/git.js` 第 220 行。 + +```js +const result = await commitAndPush(workspace, repoDir, _spawnSync, _sourceRoot, reviewOutcome); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：完成對外部系統的寫入、發佈或執行動作。 + +### getBotReviewOutcome + +解析 AI Review bot 的結果標記，回傳 success、failure 或 unknown。 + +檔案位置：`src/gitea.js` 第 39 行。 + +```js +const result = getBotReviewOutcome(message); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### parseReviewIgnore + +把 `.reviewignore` 文字解析成可用的排除前綴陣列。 + +檔案位置：`src/gitea.js` 第 62 行。 + +```js +const result = parseReviewIgnore(text); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### getReviewIgnore + +讀取並解析 PR 的 `.reviewignore`，沒有自訂規則時回退預設排除清單。 + +檔案位置：`src/gitea.js` 第 74 行。 + +```js +const result = await getReviewIgnore(); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### getPRDiff + +取得目前 PR 的 unified diff，並套用 `.reviewignore` 與內建過濾規則。 + +檔案位置：`src/gitea.js` 第 89 行。 + +```js +const result = await getPRDiff(); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### getCommitMessageBySha + +依 commit SHA 讀取 Gitea 上的 commit message，失敗時保守回空字串。 + +檔案位置：`src/gitea.js` 第 101 行。 + +```js +const result = await getCommitMessageBySha(sha); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### getBranchHeadCommitMessage + +讀取指定分支 head commit 的訊息，失敗時保守回空字串。 + +檔案位置：`src/gitea.js` 第 122 行。 + +```js +const result = await getBranchHeadCommitMessage(branch); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### shouldSkipBotCommit + +判斷目前 PR head 是否為 bot 自動提交，若是就跳過後續審查流程。 + +檔案位置：`src/gitea.js` 第 147 行。 + +```js +const result = await shouldSkipBotCommit(sha, branch); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### filterDiff + +過濾 unified diff 中不需要審查的路徑區塊，保留其餘內容。 + +檔案位置：`src/gitea.js` 第 164 行。 + +```js +const result = filterDiff(diff, excludePrefixes); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### postComment + +在 PR 底下發布一則 Markdown 留言，適合非行內評論用途。 + +檔案位置：`src/gitea.js` 第 184 行。 + +```js +const result = await postComment(body); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：完成對外部系統的寫入、發佈或執行動作。 + +### postPullReviewComment + +對 PR 指定檔案與行號發送單筆行內 review comment。 + +檔案位置：`src/gitea.js` 第 203 行。 + +```js +const result = await postPullReviewComment(pathfilePath, line, body); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：完成對外部系統的寫入、發佈或執行動作。 + +### postPullReview + +建立一則包含摘要與多筆行內 comment 的 PR review。 + +檔案位置：`src/gitea.js` 第 226 行。 + +```js +const result = await postPullReview(body, comments); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：完成對外部系統的寫入、發佈或執行動作。 + +### listPullReviews + +列出目前 PR 的所有 review，回應格式不正確時保守回空陣列。 + +檔案位置：`src/gitea.js` 第 246 行。 + +```js +const result = await listPullReviews(); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### getPullReviewComments + +依 review ID 取得該 review 底下的所有行內 comment。 + +檔案位置：`src/gitea.js` 第 260 行。 + +```js +const result = await getPullReviewComments(reviewId); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### listAllReviewComments + +彙整目前 PR 的所有 review comments，單筆失敗時略過並持續處理。 + +檔案位置：`src/gitea.js` 第 274 行。 + +```js +const result = await listAllReviewComments(); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### resolvePullReviewComment + +解決指定 review comment 對話，對應 Gitea 的 resolve API。 + +檔案位置：`src/gitea.js` 第 296 行。 + +```js +const result = await resolvePullReviewComment(commentId); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### getFileContentAtRef + +讀取指定 ref 下的檔案文字內容，支援 base64 解碼並在失敗時保守回空字串。 + +檔案位置：`src/gitea.js` 第 313 行。 + +```js +const result = await getFileContentAtRef(filePath, ref); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### stripCodeFence + +移除文字外層的 markdown code fence，並清理前後空白。 + +檔案位置：`src/json.js` 第 17 行。 + +```js +const result = stripCodeFence(text); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### repairJSONArrayWithAI + +透過 LLM 將原始內容修復成可直接 JSON.parse 的 JSON 陣列字串。 + +檔案位置：`src/json.js` 第 43 行。 + +```js +const result = await repairJSONArrayWithAI(fullPath, label, rawText, chatFn); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### validateJSONArrayFile + +驗證 JSON 檔案是否合法，必要時嘗試透過 AI 修復一次。 + +檔案位置：`src/json.js` 第 93 行。 + +```js +const result = await validateJSONArrayFile(fullPath, label, repairer); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：回傳驗證成功/失敗的結構化結果。 + +### ensureJSONArrayFileExists + +確保指定路徑存在一個 JSON 檔案，不存在時建立空陣列檔。 + +檔案位置：`src/json.js` 第 134 行。 + +```js +const result = ensureJSONArrayFileExists(fullPath, label); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### mapWithConcurrency + +以可控制併發數的方式並行處理陣列項目。 + +檔案位置：`src/llm.js` 第 25 行。 + +```js +const result = await mapWithConcurrency(items, limit, fn); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### extractMeaningfulError + +從 CLI 原始輸出中擷取最有用的錯誤訊息。 + +檔案位置：`src/llm.js` 第 96 行。 + +```js +const result = extractMeaningfulError(raw, limit); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### chat + +呼叫可用的 AI 助理 CLI，並回傳文字回應。 + +檔案位置：`src/llm.js` 第 190 行。 + +```js +const result = await chat(systemPrompt, userContent); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### chatJSON + +呼叫 AI 助理並把回應解析成 JSON。 + +檔案位置：`src/llm.js` 第 218 行。 + +```js +const result = await chatJSON(systemPrompt, userContent); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### extractBalancedJSON + +從指定索引開始擷取完整平衡的 JSON 片段。 + +檔案位置：`src/llm.js` 第 255 行。 + +```js +const result = extractBalancedJSON(text, startIndex); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### extractJSONText + +從雜訊文字中抽出最可能的 JSON 內容。 + +檔案位置：`src/llm.js` 第 298 行。 + +```js +const result = extractJSONText(text); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### section + +輸出最上層區塊標題，用來切分整體執行流程。 + +檔案位置：`src/log.js` 第 9 行。 + +```js +const result = section(title); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### step + +輸出流程中的步驟標題，標示某一小段工作內容。 + +檔案位置：`src/log.js` 第 22 行。 + +```js +const result = step(stepName, title); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### line + +輸出一行中性的明細資訊。 + +檔案位置：`src/log.js` 第 34 行。 + +```js +const result = line(message); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### input + +輸出某一步驟的輸入描述，方便追蹤資料來源。 + +檔案位置：`src/log.js` 第 45 行。 + +```js +const result = input(message); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### output + +輸出某一步驟的產出描述，方便追蹤結果。 + +檔案位置：`src/log.js` 第 56 行。 + +```js +const result = output(message); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### result + +依布林值輸出成功或失敗的檢查結果。 + +檔案位置：`src/log.js` 第 69 行。 + +```js +const result = result(passed, message); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### ok + +輸出一筆成功或完成訊息。 + +檔案位置：`src/log.js` 第 81 行。 + +```js +const result = ok(message); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### warn + +輸出一筆警告訊息到 stderr。 + +檔案位置：`src/log.js` 第 93 行。 + +```js +const result = warn(message); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### error + +輸出一筆錯誤訊息到 stderr。 + +檔案位置：`src/log.js` 第 105 行。 + +```js +const result = error(message); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### main + +執行 AI Code Review Pipeline 的完整流程。 + +檔案位置：`src/main.js` 第 55 行。 + +```js +const result = await main(); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### checkRequiredEnv + +檢查前置驗證所需的必要環境值是否齊全。 + +檔案位置：`src/preflight.js` 第 60 行。 + +```js +const result = checkRequiredEnv(token, repo, pr); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### verifyGiteaToken + +驗證 Gitea token 是否可讀取指定 repository。 + +檔案位置：`src/preflight.js` 第 77 行。 + +```js +const result = await verifyGiteaToken(token, repo); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：回傳驗證成功/失敗的結構化結果。 + +### verifyCommentToken + +驗證 comment token 是否可用；未提供時回傳 skipped。 + +檔案位置：`src/preflight.js` 第 94 行。 + +```js +const result = await verifyCommentToken(token); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：回傳驗證成功/失敗的結構化結果。 + +### fetchCodexModels + +讀取本機 codex 認證檔並取得目前可用的模型 slug 清單。 + +檔案位置：`src/preflight.js` 第 118 行。 + +```js +const result = await fetchCodexModels(); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### verifyLLM + +驗證目前環境是否有可用的 LLM CLI 與對應模型設定。 + +檔案位置：`src/preflight.js` 第 171 行。 + +```js +const result = await verifyLLM(fetchCodexModelsFn); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：回傳驗證成功/失敗的結構化結果。 + +### runPreflight + +執行所有前置驗證流程，任一失敗即回傳 false。 + +檔案位置：`src/preflight.js` 第 203 行。 + +```js +const result = await runPreflight(workspace, deps); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：完成對外部系統的寫入、發佈或執行動作。 + +### parseBotReviewComment + +解析 bot 產生的 review comment，還原成 finding 欄位物件。 + +檔案位置：`src/resolve.js` 第 51 行。 + +```js +const result = parseBotReviewComment(body); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### groupConversations + +依檔案路徑與行號把 review comments 收斂成對話群組。 + +檔案位置：`src/resolve.js` 第 73 行。 + +```js +const result = groupConversations(comments); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### codeWindow + +擷取目標行附近的程式碼片段，供 AI 判讀。 + +檔案位置：`src/resolve.js` 第 100 行。 + +```js +const result = codeWindow(content, lineNum, radius); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### judgeConversations + +處理 judgeConversations 相關邏輯。 + +檔案位置：`src/resolve.js` 第 126 行。 + +```js +const result = await judgeConversations(items, chatFn); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### isSafeRepoPath + +檢查路徑是否安全，避免讀取 repo 外檔案。 + +檔案位置：`src/resolve.js` 第 174 行。 + +```js +const result = isSafeRepoPath(p); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### reconcileConversations + +收斂 PR review 對話，並依 AI 裁定回填 findings 的去向。 + +檔案位置：`src/resolve.js` 第 190 行。 + +```js +const result = await reconcileConversations(deps); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### dropResolvedFindings + +移除已解決對話對應的 findings。 + +檔案位置：`src/resolve.js` 第 329 行。 + +```js +const result = dropResolvedFindings(findings, resolvedFindings); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### addCarriedFindings + +將仍成立但缺漏的 findings 補回清單。 + +檔案位置：`src/resolve.js` 第 338 行。 + +```js +const result = addCarriedFindings(findings, carriedFindings); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### parseRoleFile + +解析角色 Markdown 檔，取出 frontmatter 與本文。 + +檔案位置：`src/roles.js` 第 25 行。 + +```js +const result = parseRoleFile(content); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### loadRoles + +只載入攻擊方角色。 + +檔案位置：`src/roles.js` 第 71 行。 + +```js +const result = loadRoles(); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### loadRole + +依名稱查找單一角色。 + +檔案位置：`src/roles.js` 第 85 行。 + +```js +const result = loadRole(name); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### buildAnalysisPrompt + +產生攻擊方角色的程式碼審查 system prompt。 + +檔案位置：`src/roles.js` 第 104 行。 + +```js +const result = buildAnalysisPrompt(role); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### buildLocateLinePrompt + +產生用來補 finding 行號的 prompt。 + +檔案位置：`src/roles.js` 第 149 行。 + +```js +const result = buildLocateLinePrompt(role); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### buildVerdictPrompt + +產生單條 finding 的誤報裁決 prompt。 + +檔案位置：`src/roles.js` 第 173 行。 + +```js +const result = buildVerdictPrompt(role, exclusionHint); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### getRoleIntro + +產生 AI Code Review 團隊的 Markdown 介紹表。 + +檔案位置：`src/roles.js` 第 206 行。 + +```js +const result = getRoleIntro(roles); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### extractUsage + +從 LLM 回應抽出 token usage。 + +檔案位置：`src/usage.js` 第 24 行。 + +```js +const result = extractUsage(data); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### recordUsage + +記錄一次 LLM 呼叫使用量。 + +檔案位置：`src/usage.js` 第 65 行。 + +```js +const result = recordUsage(data); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：完成對外部系統的寫入、發佈或執行動作。 + +### getRunUsage + +取得目前累積的使用量。 + +檔案位置：`src/usage.js` 第 77 行。 + +```js +const result = getRunUsage(); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### resetRunUsage + +重置執行中的 usage 累計。 + +檔案位置：`src/usage.js` 第 82 行。 + +```js +const result = resetRunUsage(); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### recordRateLimit + +記錄最近一次速率配額資訊。 + +檔案位置：`src/usage.js` 第 109 行。 + +```js +const result = recordRateLimit(headers); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：完成對外部系統的寫入、發佈或執行動作。 + +### getRateLimit + +取得最近一次 rate limit 快照。 + +檔案位置：`src/usage.js` 第 130 行。 + +```js +const result = getRateLimit(); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### resetRateLimit + +重置 rate limit 快照。 + +檔案位置：`src/usage.js` 第 135 行。 + +```js +const result = resetRateLimit(); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### fetchAccountQuota + +查詢指定平台的帳號額度。 + +檔案位置：`src/usage.js` 第 209 行。 + +```js +const result = await fetchAccountQuota(provider, config, deps); +``` + +使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。 + +預期結果：依函式用途回傳對應結果。 + +### resolveRemainingPercent + +計算可用額度剩餘百分比。 + +檔案位置：`src/usage.js` 第 278 行。 + +```js +const result = resolveRemainingPercent(quota, rate); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### formatUsageStats + +產生 AI 助理使用量 Markdown 區塊。 + +檔案位置：`src/usage.js` 第 315 行。 + +```js +const result = formatUsageStats(provider, model, usage, quota, rate); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 + +### formatUsageStatsLine + +產生使用量單行摘要。 + +檔案位置：`src/usage.js` 第 334 行。 + +```js +const result = formatUsageStatsLine(provider, model, usage, quota, rate); +``` + +使用情境：通常在本地資料處理或同步查詢時呼叫。 + +預期結果：回傳對應資料、設定、字串或布林值。 +