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

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;