docs(AI Code Review): 補齊 action 與 workflow 註解說明

src/config.js

@@ -51,6 +51,12 @@ export const EXCLUSIONS_PATH = '.gitea/ai-review/exclusions.json';
  * @returns {import('https').Agent} 已關閉憑證驗證的 HTTPS Agent 單例。
  */
 let _insecureHttpsAgent = null;
+/**
+ * 取得一個關閉 TLS 憑證驗證的 HTTPS Agent 單例，供內部服務連線使用。
+ *
+ * @remarks 只應在信任的內網或測試環境使用；若需要完整 TLS 安全性，應改用預設
+ *          `https.Agent`，不要調用這個函式。
+ */
 export function getInsecureHttpsAgent() {
   return (_insecureHttpsAgent ??= new https.Agent({ rejectUnauthorized: false }));
 }
@@ -86,10 +92,22 @@ const CLI_CANDIDATES = [
   },
 ];
 
+/**
+ * 取得目前支援的 LLM CLI 指令名稱清單。
+ *
+ * @remarks 內容直接取自 `CLI_CANDIDATES`，若日後候選清單增減，輸出會同步變動。
+ */
 export function getLLMCLICommands() {
   return CLI_CANDIDATES.map(c => c.command);
 }
 
+/**
+ * 檢查指定 CLI 指令是否可在目前環境中執行。
+ *
+ * @param {string} command - 要檢查的指令名稱。
+ * @returns {boolean} 找得到指令時回傳 `true`，否則回傳 `false`。
+ * @remarks 透過 `/bin/sh -lc "command -v <command>"` 檢查，屬於同步存在性檢查。
+ */
 function commandExists(command) {
   try {
     execFileSync('/bin/sh', ['-lc', `command -v ${command}`], { stdio: 'ignore' });

src/findings.js

@@ -111,6 +111,12 @@ function cleanText(value) {
  *          以模組層級 Map 對「字串輸入」做 memoization，避免重複跑 NFKC／正則替換。
  */
 const _normalizeTextCache = new Map();
+/**
+ * 將文字正規化成比對用形式。
+ *
+ * @param {*} value - 任意值。
+ * @remarks 適合用於誤報過濾與排除條目比對。
+ */
 export function normalizeText(value) {
   if (typeof value === 'string' && _normalizeTextCache.has(value)) return _normalizeTextCache.get(value);
   const result = cleanText(value)

src/llm.js

@@ -56,6 +56,16 @@ function buildPrompt(systemPrompt, userContent) {
   ].join('\n');
 }
 
+/**
+ * 依不同 AI provider 產生 CLI 參數。
+ *
+ * @param {*} provider - AI provider 名稱。
+ * @param {*} model - 模型名稱。
+ * @param {*} promptFile - prompt 檔路徑，供 `opencode` 使用。
+ * @param {*} prompt - 直接傳給 CLI 的 prompt 文字，供部分 provider 使用。
+ * @remarks 適合把不同 CLI 的參數差異集中管理。
+ * @remarks 目前支援的 provider 名稱是硬編碼的，新增 provider 時需人工確認是否同步更新所有呼叫端。
+ */
 function cliArgs({ provider, model, promptFile = null, prompt = null }) {
   if (provider === 'codex') {
     return ['exec', '--model', model, '--sandbox', 'read-only', '--skip-git-repo-check', '-'];
@@ -92,12 +102,30 @@ export function extractMeaningfulError(raw, limit = 1000) {
   return picked.length > limit ? picked.slice(-limit) : picked;
 }
 
+/**
+ * 將 CLI 例外整理成較精簡的錯誤摘要。
+ *
+ * @param {*} e - 被拋出的錯誤物件，可能含 `stderr`、`stdout`、`message`。
+ * @remarks 適合在 log 與錯誤重新拋出前先整理訊息。
+ * @remarks 若錯誤物件結構和預期不同，仍會退回字串化處理，屬保守容錯。
+ */
 function summarizeCliError(e) {
   const stderr = String(e.stderr || '').trim();
   const stdout = String(e.stdout || '').trim();
   return extractMeaningfulError(stderr || stdout || e.message || String(e));
 }
 
+/**
+ * 執行 AI 助理 CLI 並回傳純文字結果。
+ *
+ * @param {*} provider - CLI provider 名稱。
+ * @param {*} command - 實際可執行指令。
+ * @param {*} model - 要使用的模型名稱。
+ * @param {*} prompt - 送給 CLI 的完整 prompt 內容。
+ * @remarks 適合用在需呼叫外部 AI CLI 的情境。
+ * @remarks 逾時與輸出上限由環境變數控制，預設值是保守設定。
+ * @remarks 若子行程回傳非 0，錯誤訊息會由上層摘要處理。
+ */
 async function runAssistantCLI({ provider, command, model }, prompt) {
   let tempDir = null;
   let promptFile = null;
@@ -120,7 +148,6 @@ async function runAssistantCLI({ provider, command, model }, prompt) {
         child.kill('SIGTERM');
         reject(new Error(`${provider} CLI 逾時 (${timeout}ms)`));
       }, timeout);
-
       const append = (kind, chunk) => {
         if (kind === 'stdout') stdout += chunk;
         else stderr += chunk;