1468 lines
51 KiB
Markdown
1468 lines
51 KiB
Markdown
# 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);
|
|
```
|
|
|
|
使用情境：通常在本地資料處理或同步查詢時呼叫。
|
|
|
|
預期結果：回傳對應資料、設定、字串或布林值。
|
|
|