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) |
+
+## 使用範例
+
+### <a id="parselocation"></a>parseLocation
+
+解析 finding location 為檔案與行號。
+
+檔案位置：`src/comments.js` 第 66 行。
+
+```js
+const result = parseLocation(location);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="formatfindingsstats"></a>formatFindingsStats
+
+產生 findings 統計表格。
+
+檔案位置：`src/comments.js` 第 150 行。
+
+```js
+const result = formatFindingsStats(findings);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="formatfindingsstatsline"></a>formatFindingsStatsLine
+
+產生 findings 單行統計摘要。
+
+檔案位置：`src/comments.js` 第 171 行。
+
+```js
+const result = formatFindingsStatsLine(findings);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="postfindingsreview"></a>postFindingsReview
+
+發布 findings 的 Gitea review。
+
+檔案位置：`src/comments.js` 第 220 行。
+
+```js
+const result = await postFindingsReview(findings, deps);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：完成對外部系統的寫入、發佈或執行動作。
+
+### <a id="savefindings"></a>saveFindings
+
+將 findings 寫入工作區與鏡像目錄。
+
+檔案位置：`src/comments.js` 第 259 行。
+
+```js
+const result = saveFindings(workspace, findings, mirrorDir);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：完成對外部系統的寫入、發佈或執行動作。
+
+### <a id="postoldfindingscomment"></a>postOldFindingsComment
+
+發布舊問題的 comment。
+
+檔案位置：`src/comments.js` 第 274 行。
+
+```js
+const result = await postOldFindingsComment(findings);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：完成對外部系統的寫入、發佈或執行動作。
+
+### <a id="postnewnoncriticalcomment"></a>postNewNonCriticalComment
+
+發布新問題中的非嚴重 comment。
+
+檔案位置：`src/comments.js` 第 288 行。
+
+```js
+const result = await postNewNonCriticalComment(findings);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：完成對外部系統的寫入、發佈或執行動作。
+
+### <a id="postnewcriticalcomments"></a>postNewCriticalComments
+
+發布新嚴重問題的 comment。
+
+檔案位置：`src/comments.js` 第 304 行。
+
+```js
+const result = await postNewCriticalComments(findings, deps);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：完成對外部系統的寫入、發佈或執行動作。
+
+### <a id="getinsecurehttpsagent"></a>getInsecureHttpsAgent
+
+取得一個關閉 TLS 憑證驗證的 HTTPS Agent 單例，供內部服務連線使用。
+
+檔案位置：`src/config.js` 第 60 行。
+
+```js
+const result = getInsecureHttpsAgent();
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="getllmclicommands"></a>getLLMCLICommands
+
+取得目前支援的 LLM CLI 指令名稱清單。
+
+檔案位置：`src/config.js` 第 100 行。
+
+```js
+const result = getLLMCLICommands();
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="getllmconfig"></a>getLLMConfig
+
+依環境變數與 CLI 可用性解析目前可用的 LLM 提供者設定。
+
+檔案位置：`src/config.js` 第 130 行。
+
+```js
+const result = getLLMConfig(commandExistsFn);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="analyzewithrole"></a>analyzeWithRole
+
+用指定角色分析 diff 並產生 findings。
+
+檔案位置：`src/findings.js` 第 14 行。
+
+```js
+const result = await analyzeWithRole(role, diff);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="normalizetext"></a>normalizeText
+
+將文字正規化成比對用形式。
+
+檔案位置：`src/findings.js` 第 120 行。
+
+```js
+const result = normalizeText(value);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="loadoldfindings"></a>loadOldFindings
+
+讀取舊 findings 並標記為舊問題。
+
+檔案位置：`src/findings.js` 第 302 行。
+
+```js
+const result = loadOldFindings(workspace);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="mergefindings"></a>mergeFindings
+
+合併新舊 findings 並去重。
+
+檔案位置：`src/findings.js` 第 319 行。
+
+```js
+const result = mergeFindings(oldFindings, newFindings);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="sortbylevel"></a>sortByLevel
+
+依嚴重度排序 findings。
+
+檔案位置：`src/findings.js` 第 335 行。
+
+```js
+const result = sortByLevel(findings);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="resolvemissinglinenumbers"></a>resolveMissingLineNumbers
+
+為缺少行號的 findings 補上行號。
+
+檔案位置：`src/findings.js` 第 376 行。
+
+```js
+const result = await resolveMissingLineNumbers(findings, diff, deps);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="deduplicatewithai"></a>deduplicateWithAI
+
+用 AI 進行 findings 語意去重。
+
+檔案位置：`src/findings.js` 第 423 行。
+
+```js
+const result = await deduplicateWithAI(findings);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="loadexclusions"></a>loadExclusions
+
+讀取並正規化 exclusions。
+
+檔案位置：`src/findings.js` 第 450 行。
+
+```js
+const result = loadExclusions(workspace, repoState, mirrorWorkspace);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="appendexclusions"></a>appendExclusions
+
+將新的排除條目追加到 exclusions 檔。
+
+檔案位置：`src/findings.js` 第 500 行。
+
+```js
+const result = appendExclusions(workspace, newEntries, mirrorWorkspace);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：完成對外部系統的寫入、發佈或執行動作。
+
+### <a id="applyexclusions"></a>applyExclusions
+
+依 exclusions 過濾 findings。
+
+檔案位置：`src/findings.js` 第 544 行。
+
+```js
+const result = applyExclusions(findings, exclusions);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="filterfalsepositiveswithai"></a>filterFalsePositivesWithAI
+
+用 AI 過濾誤報 findings。
+
+檔案位置：`src/findings.js` 第 577 行。
+
+```js
+const result = await filterFalsePositivesWithAI(findings, exclusions, chatFn);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="getrepostate"></a>getRepoState
+
+讀取指定 git repo 的基本狀態快照，包含 HEAD、分支與 commit 時間。
+
+檔案位置：`src/git.js` 第 120 行。
+
+```js
+const result = getRepoState(repoDir, _spawnSync);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="getheadcommitmessage"></a>getHeadCommitMessage
+
+讀取指定 repo 的 HEAD commit 完整 commit message，失敗時保守回傳空字串。
+
+檔案位置：`src/git.js` 第 138 行。
+
+```js
+const result = getHeadCommitMessage(repoDir, _spawnSync);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="isbotautocommit"></a>isBotAutoCommit
+
+判斷 HEAD commit 是否由 AI Review bot 自動產生，避免重複觸發後續流程。
+
+檔案位置：`src/git.js` 第 153 行。
+
+```js
+const result = isBotAutoCommit(repoDir, _spawnSync);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="verifyremoteaccess"></a>verifyRemoteAccess
+
+先用 `git ls-remote` 驗證 remote 認證與連線是否可用，失敗時回傳結構化錯誤。
+
+檔案位置：`src/git.js` 第 163 行。
+
+```js
+const result = verifyRemoteAccess(workspace, _spawnSync);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳驗證成功/失敗的結構化結果。
+
+### <a id="clonerepo"></a>cloneRepo
+
+以可重入方式抓取 PR head branch 到工作目錄內的 `repo` 資料夾。
+
+檔案位置：`src/git.js` 第 178 行。
+
+```js
+const result = cloneRepo(workspace, _spawnSync);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：完成對外部系統的寫入、發佈或執行動作。
+
+### <a id="commitandpush"></a>commitAndPush
+
+將 AI 審查產出的檔案結轉、提交並推回 PR head branch，失敗時保守記錄 log 而不中斷流程。
+
+檔案位置：`src/git.js` 第 220 行。
+
+```js
+const result = await commitAndPush(workspace, repoDir, _spawnSync, _sourceRoot, reviewOutcome);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：完成對外部系統的寫入、發佈或執行動作。
+
+### <a id="getbotreviewoutcome"></a>getBotReviewOutcome
+
+解析 AI Review bot 的結果標記，回傳 success、failure 或 unknown。
+
+檔案位置：`src/gitea.js` 第 39 行。
+
+```js
+const result = getBotReviewOutcome(message);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="parsereviewignore"></a>parseReviewIgnore
+
+把 `.reviewignore` 文字解析成可用的排除前綴陣列。
+
+檔案位置：`src/gitea.js` 第 62 行。
+
+```js
+const result = parseReviewIgnore(text);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="getreviewignore"></a>getReviewIgnore
+
+讀取並解析 PR 的 `.reviewignore`，沒有自訂規則時回退預設排除清單。
+
+檔案位置：`src/gitea.js` 第 74 行。
+
+```js
+const result = await getReviewIgnore();
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="getprdiff"></a>getPRDiff
+
+取得目前 PR 的 unified diff，並套用 `.reviewignore` 與內建過濾規則。
+
+檔案位置：`src/gitea.js` 第 89 行。
+
+```js
+const result = await getPRDiff();
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="getcommitmessagebysha"></a>getCommitMessageBySha
+
+依 commit SHA 讀取 Gitea 上的 commit message，失敗時保守回空字串。
+
+檔案位置：`src/gitea.js` 第 101 行。
+
+```js
+const result = await getCommitMessageBySha(sha);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="getbranchheadcommitmessage"></a>getBranchHeadCommitMessage
+
+讀取指定分支 head commit 的訊息，失敗時保守回空字串。
+
+檔案位置：`src/gitea.js` 第 122 行。
+
+```js
+const result = await getBranchHeadCommitMessage(branch);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="shouldskipbotcommit"></a>shouldSkipBotCommit
+
+判斷目前 PR head 是否為 bot 自動提交，若是就跳過後續審查流程。
+
+檔案位置：`src/gitea.js` 第 147 行。
+
+```js
+const result = await shouldSkipBotCommit(sha, branch);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="filterdiff"></a>filterDiff
+
+過濾 unified diff 中不需要審查的路徑區塊，保留其餘內容。
+
+檔案位置：`src/gitea.js` 第 164 行。
+
+```js
+const result = filterDiff(diff, excludePrefixes);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="postcomment"></a>postComment
+
+在 PR 底下發布一則 Markdown 留言，適合非行內評論用途。
+
+檔案位置：`src/gitea.js` 第 184 行。
+
+```js
+const result = await postComment(body);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：完成對外部系統的寫入、發佈或執行動作。
+
+### <a id="postpullreviewcomment"></a>postPullReviewComment
+
+對 PR 指定檔案與行號發送單筆行內 review comment。
+
+檔案位置：`src/gitea.js` 第 203 行。
+
+```js
+const result = await postPullReviewComment(pathfilePath, line, body);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：完成對外部系統的寫入、發佈或執行動作。
+
+### <a id="postpullreview"></a>postPullReview
+
+建立一則包含摘要與多筆行內 comment 的 PR review。
+
+檔案位置：`src/gitea.js` 第 226 行。
+
+```js
+const result = await postPullReview(body, comments);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：完成對外部系統的寫入、發佈或執行動作。
+
+### <a id="listpullreviews"></a>listPullReviews
+
+列出目前 PR 的所有 review，回應格式不正確時保守回空陣列。
+
+檔案位置：`src/gitea.js` 第 246 行。
+
+```js
+const result = await listPullReviews();
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="getpullreviewcomments"></a>getPullReviewComments
+
+依 review ID 取得該 review 底下的所有行內 comment。
+
+檔案位置：`src/gitea.js` 第 260 行。
+
+```js
+const result = await getPullReviewComments(reviewId);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="listallreviewcomments"></a>listAllReviewComments
+
+彙整目前 PR 的所有 review comments，單筆失敗時略過並持續處理。
+
+檔案位置：`src/gitea.js` 第 274 行。
+
+```js
+const result = await listAllReviewComments();
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="resolvepullreviewcomment"></a>resolvePullReviewComment
+
+解決指定 review comment 對話，對應 Gitea 的 resolve API。
+
+檔案位置：`src/gitea.js` 第 296 行。
+
+```js
+const result = await resolvePullReviewComment(commentId);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="getfilecontentatref"></a>getFileContentAtRef
+
+讀取指定 ref 下的檔案文字內容，支援 base64 解碼並在失敗時保守回空字串。
+
+檔案位置：`src/gitea.js` 第 313 行。
+
+```js
+const result = await getFileContentAtRef(filePath, ref);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="stripcodefence"></a>stripCodeFence
+
+移除文字外層的 markdown code fence，並清理前後空白。
+
+檔案位置：`src/json.js` 第 17 行。
+
+```js
+const result = stripCodeFence(text);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="repairjsonarraywithai"></a>repairJSONArrayWithAI
+
+透過 LLM 將原始內容修復成可直接 JSON.parse 的 JSON 陣列字串。
+
+檔案位置：`src/json.js` 第 43 行。
+
+```js
+const result = await repairJSONArrayWithAI(fullPath, label, rawText, chatFn);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="validatejsonarrayfile"></a>validateJSONArrayFile
+
+驗證 JSON 檔案是否合法，必要時嘗試透過 AI 修復一次。
+
+檔案位置：`src/json.js` 第 93 行。
+
+```js
+const result = await validateJSONArrayFile(fullPath, label, repairer);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：回傳驗證成功/失敗的結構化結果。
+
+### <a id="ensurejsonarrayfileexists"></a>ensureJSONArrayFileExists
+
+確保指定路徑存在一個 JSON 檔案，不存在時建立空陣列檔。
+
+檔案位置：`src/json.js` 第 134 行。
+
+```js
+const result = ensureJSONArrayFileExists(fullPath, label);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="mapwithconcurrency"></a>mapWithConcurrency
+
+以可控制併發數的方式並行處理陣列項目。
+
+檔案位置：`src/llm.js` 第 25 行。
+
+```js
+const result = await mapWithConcurrency(items, limit, fn);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="extractmeaningfulerror"></a>extractMeaningfulError
+
+從 CLI 原始輸出中擷取最有用的錯誤訊息。
+
+檔案位置：`src/llm.js` 第 96 行。
+
+```js
+const result = extractMeaningfulError(raw, limit);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="chat"></a>chat
+
+呼叫可用的 AI 助理 CLI，並回傳文字回應。
+
+檔案位置：`src/llm.js` 第 190 行。
+
+```js
+const result = await chat(systemPrompt, userContent);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="chatjson"></a>chatJSON
+
+呼叫 AI 助理並把回應解析成 JSON。
+
+檔案位置：`src/llm.js` 第 218 行。
+
+```js
+const result = await chatJSON(systemPrompt, userContent);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="extractbalancedjson"></a>extractBalancedJSON
+
+從指定索引開始擷取完整平衡的 JSON 片段。
+
+檔案位置：`src/llm.js` 第 255 行。
+
+```js
+const result = extractBalancedJSON(text, startIndex);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="extractjsontext"></a>extractJSONText
+
+從雜訊文字中抽出最可能的 JSON 內容。
+
+檔案位置：`src/llm.js` 第 298 行。
+
+```js
+const result = extractJSONText(text);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="section"></a>section
+
+輸出最上層區塊標題，用來切分整體執行流程。
+
+檔案位置：`src/log.js` 第 9 行。
+
+```js
+const result = section(title);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="step"></a>step
+
+輸出流程中的步驟標題，標示某一小段工作內容。
+
+檔案位置：`src/log.js` 第 22 行。
+
+```js
+const result = step(stepName, title);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="line"></a>line
+
+輸出一行中性的明細資訊。
+
+檔案位置：`src/log.js` 第 34 行。
+
+```js
+const result = line(message);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="input"></a>input
+
+輸出某一步驟的輸入描述，方便追蹤資料來源。
+
+檔案位置：`src/log.js` 第 45 行。
+
+```js
+const result = input(message);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="output"></a>output
+
+輸出某一步驟的產出描述，方便追蹤結果。
+
+檔案位置：`src/log.js` 第 56 行。
+
+```js
+const result = output(message);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="result"></a>result
+
+依布林值輸出成功或失敗的檢查結果。
+
+檔案位置：`src/log.js` 第 69 行。
+
+```js
+const result = result(passed, message);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="ok"></a>ok
+
+輸出一筆成功或完成訊息。
+
+檔案位置：`src/log.js` 第 81 行。
+
+```js
+const result = ok(message);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="warn"></a>warn
+
+輸出一筆警告訊息到 stderr。
+
+檔案位置：`src/log.js` 第 93 行。
+
+```js
+const result = warn(message);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="error"></a>error
+
+輸出一筆錯誤訊息到 stderr。
+
+檔案位置：`src/log.js` 第 105 行。
+
+```js
+const result = error(message);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="main"></a>main
+
+執行 AI Code Review Pipeline 的完整流程。
+
+檔案位置：`src/main.js` 第 55 行。
+
+```js
+const result = await main();
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="checkrequiredenv"></a>checkRequiredEnv
+
+檢查前置驗證所需的必要環境值是否齊全。
+
+檔案位置：`src/preflight.js` 第 60 行。
+
+```js
+const result = checkRequiredEnv(token, repo, pr);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="verifygiteatoken"></a>verifyGiteaToken
+
+驗證 Gitea token 是否可讀取指定 repository。
+
+檔案位置：`src/preflight.js` 第 77 行。
+
+```js
+const result = await verifyGiteaToken(token, repo);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：回傳驗證成功/失敗的結構化結果。
+
+### <a id="verifycommenttoken"></a>verifyCommentToken
+
+驗證 comment token 是否可用；未提供時回傳 skipped。
+
+檔案位置：`src/preflight.js` 第 94 行。
+
+```js
+const result = await verifyCommentToken(token);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：回傳驗證成功/失敗的結構化結果。
+
+### <a id="fetchcodexmodels"></a>fetchCodexModels
+
+讀取本機 codex 認證檔並取得目前可用的模型 slug 清單。
+
+檔案位置：`src/preflight.js` 第 118 行。
+
+```js
+const result = await fetchCodexModels();
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="verifyllm"></a>verifyLLM
+
+驗證目前環境是否有可用的 LLM CLI 與對應模型設定。
+
+檔案位置：`src/preflight.js` 第 171 行。
+
+```js
+const result = await verifyLLM(fetchCodexModelsFn);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：回傳驗證成功/失敗的結構化結果。
+
+### <a id="runpreflight"></a>runPreflight
+
+執行所有前置驗證流程，任一失敗即回傳 false。
+
+檔案位置：`src/preflight.js` 第 203 行。
+
+```js
+const result = await runPreflight(workspace, deps);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：完成對外部系統的寫入、發佈或執行動作。
+
+### <a id="parsebotreviewcomment"></a>parseBotReviewComment
+
+解析 bot 產生的 review comment，還原成 finding 欄位物件。
+
+檔案位置：`src/resolve.js` 第 51 行。
+
+```js
+const result = parseBotReviewComment(body);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="groupconversations"></a>groupConversations
+
+依檔案路徑與行號把 review comments 收斂成對話群組。
+
+檔案位置：`src/resolve.js` 第 73 行。
+
+```js
+const result = groupConversations(comments);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="codewindow"></a>codeWindow
+
+擷取目標行附近的程式碼片段，供 AI 判讀。
+
+檔案位置：`src/resolve.js` 第 100 行。
+
+```js
+const result = codeWindow(content, lineNum, radius);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="judgeconversations"></a>judgeConversations
+
+處理 judgeConversations 相關邏輯。
+
+檔案位置：`src/resolve.js` 第 126 行。
+
+```js
+const result = await judgeConversations(items, chatFn);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="issaferepopath"></a>isSafeRepoPath
+
+檢查路徑是否安全，避免讀取 repo 外檔案。
+
+檔案位置：`src/resolve.js` 第 174 行。
+
+```js
+const result = isSafeRepoPath(p);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="reconcileconversations"></a>reconcileConversations
+
+收斂 PR review 對話，並依 AI 裁定回填 findings 的去向。
+
+檔案位置：`src/resolve.js` 第 190 行。
+
+```js
+const result = await reconcileConversations(deps);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="dropresolvedfindings"></a>dropResolvedFindings
+
+移除已解決對話對應的 findings。
+
+檔案位置：`src/resolve.js` 第 329 行。
+
+```js
+const result = dropResolvedFindings(findings, resolvedFindings);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="addcarriedfindings"></a>addCarriedFindings
+
+將仍成立但缺漏的 findings 補回清單。
+
+檔案位置：`src/resolve.js` 第 338 行。
+
+```js
+const result = addCarriedFindings(findings, carriedFindings);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="parserolefile"></a>parseRoleFile
+
+解析角色 Markdown 檔，取出 frontmatter 與本文。
+
+檔案位置：`src/roles.js` 第 25 行。
+
+```js
+const result = parseRoleFile(content);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="loadroles"></a>loadRoles
+
+只載入攻擊方角色。
+
+檔案位置：`src/roles.js` 第 71 行。
+
+```js
+const result = loadRoles();
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="loadrole"></a>loadRole
+
+依名稱查找單一角色。
+
+檔案位置：`src/roles.js` 第 85 行。
+
+```js
+const result = loadRole(name);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="buildanalysisprompt"></a>buildAnalysisPrompt
+
+產生攻擊方角色的程式碼審查 system prompt。
+
+檔案位置：`src/roles.js` 第 104 行。
+
+```js
+const result = buildAnalysisPrompt(role);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="buildlocatelineprompt"></a>buildLocateLinePrompt
+
+產生用來補 finding 行號的 prompt。
+
+檔案位置：`src/roles.js` 第 149 行。
+
+```js
+const result = buildLocateLinePrompt(role);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="buildverdictprompt"></a>buildVerdictPrompt
+
+產生單條 finding 的誤報裁決 prompt。
+
+檔案位置：`src/roles.js` 第 173 行。
+
+```js
+const result = buildVerdictPrompt(role, exclusionHint);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="getroleintro"></a>getRoleIntro
+
+產生 AI Code Review 團隊的 Markdown 介紹表。
+
+檔案位置：`src/roles.js` 第 206 行。
+
+```js
+const result = getRoleIntro(roles);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="extractusage"></a>extractUsage
+
+從 LLM 回應抽出 token usage。
+
+檔案位置：`src/usage.js` 第 24 行。
+
+```js
+const result = extractUsage(data);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="recordusage"></a>recordUsage
+
+記錄一次 LLM 呼叫使用量。
+
+檔案位置：`src/usage.js` 第 65 行。
+
+```js
+const result = recordUsage(data);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：完成對外部系統的寫入、發佈或執行動作。
+
+### <a id="getrunusage"></a>getRunUsage
+
+取得目前累積的使用量。
+
+檔案位置：`src/usage.js` 第 77 行。
+
+```js
+const result = getRunUsage();
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="resetrunusage"></a>resetRunUsage
+
+重置執行中的 usage 累計。
+
+檔案位置：`src/usage.js` 第 82 行。
+
+```js
+const result = resetRunUsage();
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="recordratelimit"></a>recordRateLimit
+
+記錄最近一次速率配額資訊。
+
+檔案位置：`src/usage.js` 第 109 行。
+
+```js
+const result = recordRateLimit(headers);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：完成對外部系統的寫入、發佈或執行動作。
+
+### <a id="getratelimit"></a>getRateLimit
+
+取得最近一次 rate limit 快照。
+
+檔案位置：`src/usage.js` 第 130 行。
+
+```js
+const result = getRateLimit();
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="resetratelimit"></a>resetRateLimit
+
+重置 rate limit 快照。
+
+檔案位置：`src/usage.js` 第 135 行。
+
+```js
+const result = resetRateLimit();
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="fetchaccountquota"></a>fetchAccountQuota
+
+查詢指定平台的帳號額度。
+
+檔案位置：`src/usage.js` 第 209 行。
+
+```js
+const result = await fetchAccountQuota(provider, config, deps);
+```
+
+使用情境：通常在需要等待外部 I/O 或其他非同步回應時呼叫。
+
+預期結果：依函式用途回傳對應結果。
+
+### <a id="resolveremainingpercent"></a>resolveRemainingPercent
+
+計算可用額度剩餘百分比。
+
+檔案位置：`src/usage.js` 第 278 行。
+
+```js
+const result = resolveRemainingPercent(quota, rate);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="formatusagestats"></a>formatUsageStats
+
+產生 AI 助理使用量 Markdown 區塊。
+
+檔案位置：`src/usage.js` 第 315 行。
+
+```js
+const result = formatUsageStats(provider, model, usage, quota, rate);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+
+### <a id="formatusagestatsline"></a>formatUsageStatsLine
+
+產生使用量單行摘要。
+
+檔案位置：`src/usage.js` 第 334 行。
+
+```js
+const result = formatUsageStatsLine(provider, model, usage, quota, rate);
+```
+
+使用情境：通常在本地資料處理或同步查詢時呼叫。
+
+預期結果：回傳對應資料、設定、字串或布林值。
+