# 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);
```

使用情境：通常在本地資料處理或同步查詢時呼叫。

預期結果：回傳對應資料、設定、字串或布林值。

