botrun-horse 1.0.0

package/bin/commands/prompt.mjs

@@ -0,0 +1,175 @@
+// bin/commands/prompt.mjs — prompt 指令群組（list / show / search）
+// 無參數 → 列出全部提示詞
+// 不認識的子指令 → 當關鍵字做全文模糊搜尋
+import { timer, jsonOut, emitError, logProgress } from '../../lib/core/cli-utils.mjs';
+
+/**
+ * prompt 指令主路由
+ *
+ * bh prompt             → list（列出全部）
+ * bh prompt list        → list
+ * bh prompt show <slug> → show
+ * bh prompt search <kw> → search
+ * bh prompt 零幻覺      → 自動搜尋「零幻覺」
+ *
+ * @param {string} subcommand - list / show / search / 或任意關鍵字
+ * @param {string[]} positionals - 位置參數
+ * @param {object} flags - CLI 旗標
+ */
+export async function cmdPrompt(subcommand, positionals, flags) {
+  // --help（可能被 parseArgs 當成 subcommand）
+  if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+    if (subcommand === '--help' || subcommand === '-h' || flags.help) {
+      const { showCommandHelp } = await import('./help.mjs');
+      showCommandHelp('prompt'); return;
+    }
+    // 無參數 → 列出全部
+    await cmdPromptList(flags);
+    return;
+  }
+
+  switch (subcommand) {
+    case 'list': await cmdPromptList(flags); break;
+    case 'show': await cmdPromptShow(positionals, flags); break;
+    case 'search': await cmdPromptSearch(positionals, flags); break;
+    default:
+      // 不認識的子指令 → 把 subcommand + positionals 合併為搜尋關鍵字
+      await cmdPromptSearch([subcommand, ...positionals], flags);
+  }
+}
+
+/** list — 列出所有提示詞（依系列分組） */
+async function cmdPromptList(flags) {
+  const elapsed = timer();
+  const format = flags.format || 'text';
+  const { listPrompts } = await import('../../lib/prompt/prompt-store.mjs');
+
+  const all = listPrompts();
+  const filtered = flags.series
+    ? all.filter(p => p.meta.series === flags.series)
+    : all;
+
+  if (format === 'json') {
+    const data = filtered.map(p => ({
+      slug: p.slug,
+      title: p.meta.title,
+      series: p.meta.series,
+      tags: p.meta.tags || [],
+      aliases: p.meta.aliases || [],
+      body: p.body,
+    }));
+    process.stdout.write(jsonOut('prompt list', { count: data.length, prompts: data }, elapsed()));
+    return;
+  }
+
+  for (let i = 0; i < filtered.length; i++) {
+    const p = filtered[i];
+    if (i > 0) process.stdout.write('\n---\n\n');
+    process.stdout.write(`[${p.meta.series || ''}/${p.slug}] ${p.meta.title || p.slug}\n\n`);
+    process.stdout.write(p.body + '\n');
+  }
+}
+
+/** show — 顯示單一提示詞全文 */
+async function cmdPromptShow(positionals, flags) {
+  const elapsed = timer();
+  const format = flags.format || 'text';
+  const slug = positionals[0];
+
+  if (!slug) {
+    emitError('prompt show', '請提供提示詞 slug。用法: bh prompt show <slug>', format);
+    process.exit(1);
+  }
+
+  const { getPrompt, listPrompts } = await import('../../lib/prompt/prompt-store.mjs');
+  let prompt = getPrompt(slug);
+
+  // 智慧 fallback：精確 slug 找不到 → 自動轉搜尋
+  if (!prompt) {
+    const { searchPrompts } = await import('../../lib/prompt/prompt-search.mjs');
+    const all = listPrompts();
+    const results = searchPrompts(all, slug);
+
+    if (results.length === 0) {
+      emitError('prompt show', `找不到提示詞「${slug}」，搜尋也無結果`, format);
+      process.exit(1);
+    }
+
+    if (results.length === 1) {
+      prompt = results[0].prompt;
+      logProgress(`提示: slug「${slug}」不存在，自動搜尋命中「${prompt.slug}」`, flags);
+    } else {
+      // 多筆命中 → 列出候選
+      if (format === 'json') {
+        const data = results.map(r => ({ slug: r.prompt.slug, title: r.prompt.meta.title, score: r.score }));
+        process.stdout.write(jsonOut('prompt show', { match: 'multiple', candidates: data }, elapsed()));
+      } else {
+        process.stderr.write(`找不到精確 slug「${slug}」，搜尋到 ${results.length} 筆候選：\n`);
+        for (const r of results) {
+          process.stderr.write(`  ${r.prompt.slug.padEnd(16)} ${r.prompt.meta.title} (分數: ${r.score})\n`);
+        }
+        process.stderr.write(`\n請使用精確 slug，例如: bh prompt show ${results[0].prompt.slug}\n`);
+      }
+      return;
+    }
+  }
+
+  if (format === 'json') {
+    const data = {
+      slug: prompt.slug,
+      title: prompt.meta.title,
+      series: prompt.meta.series,
+      tags: prompt.meta.tags || [],
+      aliases: prompt.meta.aliases || [],
+      body: prompt.body,
+    };
+    process.stdout.write(jsonOut('prompt show', data, elapsed()));
+  } else {
+    process.stdout.write(prompt.body + '\n');
+  }
+}
+
+/** search — 模糊搜尋提示詞（加權全文比對） */
+async function cmdPromptSearch(positionals, flags) {
+  const elapsed = timer();
+  const format = flags.format || 'text';
+  const query = positionals.join(' ');
+
+  if (!query) {
+    emitError('prompt search', '請提供搜尋關鍵字。用法: bh prompt search <關鍵字>', format);
+    process.exit(1);
+  }
+
+  const { listPrompts } = await import('../../lib/prompt/prompt-store.mjs');
+  const { searchPrompts } = await import('../../lib/prompt/prompt-search.mjs');
+
+  const all = listPrompts();
+  const results = searchPrompts(all, query, { tag: flags.tag });
+
+  if (format === 'json') {
+    const data = results.map(r => ({
+      slug: r.prompt.slug,
+      title: r.prompt.meta.title,
+      series: r.prompt.meta.series,
+      score: r.score,
+      tags: r.prompt.meta.tags || [],
+      body: r.prompt.body,
+    }));
+    process.stdout.write(jsonOut('prompt search', { query, count: data.length, results: data }, elapsed()));
+    return;
+  }
+
+  if (results.length === 0) {
+    process.stdout.write(`搜尋「${query}」：無結果\n`);
+    return;
+  }
+
+  logProgress(`搜尋「${query}」：${results.length} 筆結果`, flags);
+
+  for (let i = 0; i < results.length; i++) {
+    const r = results[i];
+    if (i > 0) process.stdout.write('\n---\n\n');
+    process.stdout.write(`[${r.prompt.meta.series || ''}/${r.prompt.slug}] ${r.prompt.meta.title}\n\n`);
+    process.stdout.write(r.prompt.body + '\n');
+  }
+}

package/bin/commands/schema.mjs

@@ -0,0 +1,258 @@
+// bin/commands/schema.mjs — 所有指令的結構化 schema（AI/LLM 友善）
+// 集中管理：方便 AI agent 讀取完整指令清單
+
+export const COMMANDS = {
+  doc: {
+    name: 'doc',
+    description: '文件處理（拆頁、轉文字、入庫）— 支援 PDF 與 Office 全系列',
+    requires_sqlite: false,
+    subcommands: {
+      split: '通用 PDF 拆頁（每頁輸出為獨立 PDF）',
+      text: 'PDF 轉純文字（保留頁碼與排版，不需先拆頁）',
+      ingest: 'PDF/Office 入庫流水線（轉文字 → SQLite FTS5）[需 --experimental-sqlite]',
+    },
+    options: {
+      '--project=<名稱>': { type: 'string', default: 'nstc', description: '專案名稱' },
+      '--dir=<路徑>': { type: 'string', description: '掃描單一目錄內所有文件' },
+      '--dirs=<路徑1,路徑2>': { type: 'string', description: '掃描多個目錄（逗號分隔）' },
+      '--outdir=<路徑>': { type: 'string', description: '拆頁輸出目錄（split 指令用）' },
+      '--split-pdf': { type: 'boolean', default: false, description: '[ingest] 同時拆頁成獨立 PDF' },
+      '--recursive': { type: 'boolean', default: false, description: '遞迴掃描子目錄' },
+      '--force': { type: 'boolean', default: false, description: '強制重新入庫（忽略斷點續作紀錄）' },
+      '--concurrency=N': { type: 'integer', default: 5, description: '平行處理數' },
+      '--quiet': { type: 'boolean', default: false, description: '靜默模式（不輸出進度到 stderr，GNU parallel 友善）' },
+      '--print0': { type: 'boolean', default: false, description: 'NUL 分隔路徑輸出（與 xargs -0 相容）' },
+      '--format=json|text': { type: 'string', default: 'text', description: '輸出格式' },
+    },
+    examples: [
+      'bh doc split file1.pdf file2.pdf --project=nstc',
+      'bh doc text --dir=projects/nstc/output/pdfs',
+      'node --experimental-sqlite bin/bh.mjs doc ingest --dir=projects/nstc/pdfs --project=nstc',
+      'node --experimental-sqlite bin/bh.mjs doc ingest --dirs=pdfs/,docs/ --project=nstc --recursive',
+      'node --experimental-sqlite bin/bh.mjs doc ingest file.docx report.xlsx --project=nstc',
+      'node --experimental-sqlite bin/bh.mjs doc ingest --dir=pdfs/ --force --split-pdf --project=nstc',
+      'ls pdfs/*.pdf | node --experimental-sqlite bin/bh.mjs doc ingest --project=nstc',
+      'find . -name "*.pdf" -print0 | xargs -0 -P 4 node bin/bh.mjs doc text --quiet',
+    ],
+  },
+  writing: {
+    name: 'writing',
+    description: '公文撰寫（生成 PDF）',
+    requires_sqlite: false,
+    subcommands: {
+      generate: '平行生成 PDF 文件（DAG 依賴感知批次處理）',
+    },
+    options: {
+      '--project=<名稱>': { type: 'string', default: 'nstc', description: '專案名稱' },
+      '--concurrency=N': { type: 'integer', default: 10, description: '平行並發數' },
+      '--ids=1,2,3': { type: 'string', description: '指定文件 ID（逗號分隔）' },
+      '--format=json|text': { type: 'string', default: 'text', description: '輸出格式' },
+    },
+    examples: [
+      'bh writing generate --project=nstc',
+      'bh writing generate --project=nstc --ids=1,2,3',
+    ],
+  },
+  dag: {
+    name: 'dag',
+    description: 'DAG 依賴追蹤管理',
+    requires_sqlite: false,
+    subcommands: {
+      init: '初始化 DAG 狀態',
+      status: '顯示整體 DAG 進度摘要',
+      ready: '列出目前可執行的任務',
+      list: '列出所有任務及其狀態',
+    },
+    options: {
+      '--project=<名稱>': { type: 'string', default: 'nstc', description: '專案名稱' },
+      '--format=json|text': { type: 'string', default: 'text', description: '輸出格式' },
+    },
+    examples: [
+      'bh dag init --project=nstc',
+      'bh dag status --project=nstc',
+      'bh dag ready --format=json --project=nstc',
+    ],
+  },
+  search: {
+    name: 'search',
+    description: 'FTS5 trigram 全文檢索',
+    requires_sqlite: true,
+    subcommands: { query: '搜尋關鍵字' },
+    options: {
+      '--project=<名稱>': { type: 'string', default: 'nstc', description: '專案名稱' },
+      '--db=<DB路徑>': { type: 'string', description: 'SQLite 資料庫路徑' },
+      '--limit=N': { type: 'integer', description: '限制結果數量' },
+      '--format=json|text': { type: 'string', default: 'text', description: '輸出格式' },
+    },
+    examples: ['bh search query "研究計畫" --project=nstc'],
+  },
+  db: {
+    name: 'db',
+    description: 'SQLite 資料庫管理',
+    requires_sqlite: true,
+    subcommands: {
+      stats: '顯示 DB 統計',
+      docs: '列出所有文件 metadata',
+      'pages <doc_id>': '列出指定文件的所有頁面',
+    },
+    options: {
+      '--project=<名稱>': { type: 'string', default: 'nstc', description: '專案名稱' },
+      '--db=<DB路徑>': { type: 'string', description: 'SQLite 路徑' },
+      '--format=json|text': { type: 'string', default: 'text', description: '輸出格式' },
+    },
+    examples: ['bh db stats --project=nstc', 'bh db docs --format=json --project=nstc'],
+  },
+  gemini: {
+    name: 'gemini',
+    description: 'Gemini 3 Flash Preview AI 提問（thinking + grounding + url context）',
+    requires_sqlite: false,
+    subcommands: { ask: '向 Gemini 提問（預設啟用深度思考、搜尋接地、URL 擷取）' },
+    options: {
+      '--project=<名稱>': { type: 'string', default: 'nstc', description: '專案名稱' },
+      '--provider=<名稱>': { type: 'string', default: 'auto', description: 'LLM provider (auto|gemini|gemini-api)' },
+      '--thinking=<等級>': { type: 'string', default: 'MEDIUM', description: '思考等級 (NONE|MINIMAL|LOW|MEDIUM|HIGH)' },
+      '--system-prompt=<文字>': { type: 'string', default: '', description: '系統提示詞' },
+      '--no-grounding': { type: 'boolean', default: false, description: '停用 Google Search 接地' },
+      '--no-url-context': { type: 'boolean', default: false, description: '停用 URL 內容擷取' },
+      '--no-stream': { type: 'boolean', default: false, description: '停用串流（等待完整回應）' },
+      '--format=json|text': { type: 'string', default: 'text', description: '輸出格式' },
+    },
+    examples: [
+      'bh gemini ask "量子糾纏的原理是什麼？"',
+      'bh gemini ask "2026 台灣經濟預測" --format=json',
+      'echo "解釋 AI" | bh gemini ask',
+    ],
+  },
+  nchc: {
+    name: 'nchc',
+    description: '國網 GenAI AI 提問（Mistral 系列，OpenAI 相容介面）',
+    requires_sqlite: false,
+    subcommands: {
+      ask: '向國網 GenAI 提問（支援串流輸出）',
+      agent: '啟動 Agentic AI 代理（工具呼叫、多輪對話）',
+      code: '啟動 Agentic Coding 代理（@opencode-ai/sdk + 675B，需 opencode CLI）',
+      models: '列出可用模型',
+    },
+    options: {
+      '--model=<名稱>': { type: 'string', default: 'Mistral-Large-3-675B-Instruct-2512', description: '模型名稱' },
+      '--system-prompt=<文字>': { type: 'string', default: '', description: '系統提示詞' },
+      '--max-tokens=N': { type: 'integer', default: 8192, description: '最大輸出 tokens' },
+      '--temperature=N': { type: 'number', default: 0.7, description: '溫度（0.0~1.0）' },
+      '--no-stream': { type: 'boolean', default: false, description: '停用串流' },
+      '--max-turns=N': { type: 'integer', default: 20, description: '[agent] 最大迴圈次數' },
+      '--format=json|text': { type: 'string', default: 'text', description: '輸出格式' },
+    },
+    examples: [
+      'bh nchc ask "台灣半導體產業分析"',
+      'bh nchc agent "列出 lib/ 目錄下所有 .mjs 檔案並說明架構"',
+      'bh nchc models',
+    ],
+  },
+  openrouter: {
+    name: 'openrouter',
+    description: 'OpenRouter AI 提問（400+ 模型，支援網路搜尋）',
+    requires_sqlite: false,
+    subcommands: {
+      ask: '向 OpenRouter 任意模型提問（支援串流 + 網路搜尋）',
+      models: '列出常用模型（含網路搜尋支援說明）',
+    },
+    options: {
+      '--model=<名稱>': { type: 'string', default: 'openai/gpt-4o-mini', description: '模型名稱（任意 OpenRouter 模型 ID，可加 :online 後綴）' },
+      '--web-search': { type: 'boolean', default: false, description: '啟用網路搜尋（plugins: web，適用所有模型）' },
+      '--max-results=N': { type: 'integer', default: 5, description: '搜尋最大結果數（--web-search 時有效）' },
+      '--system-prompt=<文字>': { type: 'string', default: '', description: '系統提示詞' },
+      '--max-tokens=N': { type: 'integer', default: 8192, description: '最大輸出 tokens' },
+      '--temperature=N': { type: 'number', default: 0.7, description: '溫度（0.0~2.0）' },
+      '--no-stream': { type: 'boolean', default: false, description: '停用串流（等待完整回應）' },
+      '--quiet': { type: 'boolean', default: false, description: '靜默模式（不輸出進度到 stderr，GNU parallel 友善）' },
+      '--format=json|text': { type: 'string', default: 'text', description: '輸出格式（json 含 sources、usage、perf，適合 Agentic AI）' },
+    },
+    examples: [
+      'bh openrouter ask "台灣今日重要新聞" --web-search',
+      'bh openrouter ask "分析 React vs Vue" --model=anthropic/claude-sonnet-4-6',
+      'bh openrouter ask "最新 AI 研究" --model=perplexity/sonar-pro --format=json',
+      'echo "解釋量子糾纏" | bh openrouter ask --model=openai/gpt-4o',
+      'bh openrouter ask "整理今天新聞" --web-search --quiet --format=json | jq .text',
+      'bh openrouter models',
+    ],
+  },
+  legal: {
+    name: 'legal',
+    description: '法律查詢（AI Router + 兩步驟提示工程 + SQLite 快取）[需 --experimental-sqlite]',
+    requires_sqlite: true,
+    subcommands: {
+      ask: '法律問題查詢（Mistral 14B 路由 → 快取命中或 Gemini Pro 搜尋法規 → 法律分析）',
+      cache: '快取管理（list: 列出快取, stats: 統計）',
+    },
+    options: {
+      '--project=<名稱>': { type: 'string', default: 'legal-cache', description: '專案名稱（決定 SQLite 路徑）' },
+      '--skip-cache': { type: 'boolean', default: false, description: '強制跳過快取，直接呼叫大模型' },
+      '--skip-save': { type: 'boolean', default: false, description: '不將結果存入快取' },
+      '--limit=N': { type: 'integer', default: 20, description: '[cache list] 顯示筆數上限' },
+      '--quiet': { type: 'boolean', default: false, description: '靜默模式（不輸出進度到 stderr）' },
+      '--format=json|text': { type: 'string', default: 'text', description: '輸出格式' },
+    },
+    examples: [
+      'node --experimental-sqlite bin/bh.mjs legal ask "房東可以隨意趕走我嗎？"',
+      'node --experimental-sqlite bin/bh.mjs legal ask "勞工被無故解雇有哪些保護？" --format=json',
+      'echo "我的房東說要漲租金，我有辦法拒絕嗎？" | node --experimental-sqlite bin/bh.mjs legal ask',
+      'node --experimental-sqlite bin/bh.mjs legal cache list --project=legal-cache',
+      'node --experimental-sqlite bin/bh.mjs legal cache stats',
+      'node --experimental-sqlite bin/bh.mjs legal ask "問題" --skip-cache --project=legal-cache',
+    ],
+  },
+  prompt: {
+    name: 'prompt',
+    description: '提示詞管理（無參數=全列出，帶關鍵字=模糊搜尋）— 零框架提示系列',
+    requires_sqlite: false,
+    subcommands: {
+      '(無)': '列出所有提示詞（依系列分組）',
+      '<關鍵字>': '模糊搜尋提示詞（加權全文比對）',
+      list: '列出所有提示詞（同無參數）',
+      show: '顯示指定提示詞全文（支援智慧 fallback 搜尋）',
+      search: '模糊搜尋提示詞（同 <關鍵字>）',
+    },
+    options: {
+      '--series=<名稱>': { type: 'string', description: '[list] 過濾指定系列' },
+      '--tag=<標籤>': { type: 'string', description: '[search] 按標籤過濾' },
+      '--format=json|text': { type: 'string', default: 'text', description: '輸出格式' },
+      '--quiet': { type: 'boolean', default: false, description: '靜默模式' },
+    },
+    examples: [
+      'bh prompt                         # 列出全部提示詞',
+      'bh prompt 零幻覺                   # 模糊搜尋「零幻覺」',
+      'bh prompt BDD                     # 搜尋含 BDD 的提示',
+      'bh prompt list --series=zero-framework',
+      'bh prompt show coding',
+      'bh prompt show coding | pbcopy',
+      'bh prompt show coding --format=json',
+      'bh prompt search 寫程式',
+      'bh prompt show 切                 # 智慧 fallback：slug 不存在 → 自動搜尋',
+    ],
+  },
+  portal: {
+    name: 'portal',
+    description: '智慧入口（預留）',
+    requires_sqlite: false,
+    subcommands: { status: '顯示入口狀態' },
+    options: {},
+    examples: ['bh portal status'],
+  },
+  ocr: {
+    name: 'ocr',
+    description: 'OCR 辨識（預留）',
+    requires_sqlite: false,
+    subcommands: { scan: '掃描文件' },
+    options: {},
+    examples: ['bh ocr scan file.pdf'],
+  },
+  commands: {
+    name: 'commands',
+    description: '列出所有指令的結構化 schema（AI/LLM 友善）',
+    requires_sqlite: false,
+    options: {
+      '--format=json|text': { type: 'string', default: 'json', description: '輸出格式' },
+    },
+    examples: ['bh commands', "bh commands --format=json | jq 'keys'"],
+  },
+};

package/bin/commands/search.mjs

@@ -0,0 +1,46 @@
+// bin/commands/search.mjs — search 指令群組（query）
+import * as paths from '../../lib/core/paths.mjs';
+import { timer, jsonOut, emitError, readStdin } from '../../lib/core/cli-utils.mjs';
+
+export async function cmdSearch(subcommand, positionals, flags) {
+  const elapsed = timer();
+  const format = flags.format || 'text';
+  const project = flags.project || 'nstc';
+  const { DocStore } = await import('../../lib/core/db.mjs');
+  const dbPathVal = flags.db || paths.dbPath(project);
+  const limit = flags.limit ? parseInt(flags.limit) : null;
+
+  let query = positionals[0];
+  if (query === '-' || (!query && !process.stdin.isTTY)) {
+    query = await readStdin();
+  }
+  if (!query) {
+    emitError('search', '請提供搜尋關鍵字（至少 3 個字元）', format);
+    process.exit(1);
+  }
+
+  const store = new DocStore(dbPathVal);
+  store.initSchema();
+  let results = store.search(query);
+  if (limit && limit > 0) results = results.slice(0, limit);
+
+  if (format === 'json') {
+    process.stdout.write(jsonOut('search', { query, count: results.length, results }, elapsed()));
+  } else {
+    if (results.length === 0) {
+      process.stdout.write(`查無「${query}」相關結果\n`);
+    } else {
+      process.stdout.write(`搜尋「${query}」找到 ${results.length} 筆結果:\n\n`);
+      for (const r of results) {
+        process.stdout.write(`[${r.doc_type}] ${r.title} — 第 ${r.source_page} 頁\n`);
+        process.stdout.write(`  引證: ${r.source_file}:${r.source_page}\n`);
+        process.stdout.write(`  摘要: ${r.snippet}\n\n`);
+      }
+    }
+  }
+
+  store.close();
+  if (format !== 'json' && !flags.quiet) {
+    process.stderr.write(`檢索完成 (${elapsed()}s)\n`);
+  }
+}

package/bin/commands/writing.mjs

@@ -0,0 +1,33 @@
+// bin/commands/writing.mjs — writing 指令群組（generate）
+import { timer, jsonOut, readStdin } from '../../lib/core/cli-utils.mjs';
+
+export async function cmdWritingGenerate(flags) {
+  const elapsed = timer();
+  const format = flags.format || 'text';
+  const project = flags.project || 'nstc';
+  const concurrency = parseInt(flags.concurrency) || 10;
+
+  const { GENERATORS, TOP5_OVERRIDES } = await import('../../lib/writing/generators/nstc-generators.mjs');
+
+  let ids = null;
+  if (flags.ids === '-' || (flags.ids === true && !process.stdin.isTTY)) {
+    const stdin = await readStdin();
+    if (stdin) ids = stdin.split(/[,\s\n]+/).map(Number).filter(Boolean);
+  } else if (flags.ids && flags.ids !== true) {
+    ids = flags.ids.split(',').map(Number).filter(Boolean);
+  }
+
+  const { generateAll } = await import('../../lib/writing/generate.mjs');
+  const result = await generateAll({
+    concurrency, ids, project,
+    generators: GENERATORS,
+    overrides: TOP5_OVERRIDES,
+  });
+
+  if (format === 'json') {
+    process.stdout.write(jsonOut('writing generate', { ok: result.ok, fail: result.fail }, elapsed()));
+  } else {
+    process.stderr.write(`\n${result.status}\n`);
+    process.stderr.write(`完成: ${result.ok} 成功, ${result.fail} 失敗 (${elapsed()}s)\n`);
+  }
+}

package/lib/core/adapters/base.mjs

@@ -0,0 +1,52 @@
+// lib/core/adapters/base.mjs — LLM Adapter 抽象基類
+//
+// SOLID 原則：
+//   LSP — 所有 Adapter 必須繼承此類並實作抽象方法，保證可替換性
+//   OCP — 透過繼承擴充新 provider，不修改既有 adapter
+//   ISP — 介面精簡：僅定義所有 adapter 共同需要的方法
+//
+// 使用方式：
+//   export class MyAdapter extends BaseAdapter { ... }
+//
+// 強制實作：generateContent() 與 generateContentStream()
+// 預設提供：_formatError() 統一錯誤格式（DRY）
+
+export class BaseAdapter {
+  /**
+   * 向 LLM 提問（非串流）
+   * @abstract
+   * @param {object} params
+   * @param {string} params.prompt - 使用者提問
+   * @param {string} [params.systemInstruction] - 系統指示
+   * @returns {Promise<LlmResponse>}
+   */
+  async generateContent(_params) {
+    throw new Error(`${this.constructor.name}.generateContent() 尚未實作`);
+  }
+
+  /**
+   * 向 LLM 提問（AsyncGenerator 串流）
+   * @abstract
+   * @param {object} params
+   * @param {string} params.prompt - 使用者提問
+   * @param {string} [params.systemInstruction] - 系統指示
+   * @yields {{ type: 'text'|'thinking'|'metadata', text?: string, ... }}
+   */
+  async *generateContentStream(_params) {
+    throw new Error(`${this.constructor.name}.generateContentStream() 尚未實作`);
+  }
+
+  /**
+   * 統一錯誤格式化（DRY — 所有子類共用）
+   * @param {Error} err
+   * @param {number} [code=1]
+   * @returns {{ ok: false, error: string, code: number }}
+   */
+  _formatError(err, code = 1) {
+    return {
+      ok: false,
+      error: err?.message || String(err),
+      code,
+    };
+  }
+}

package/lib/core/adapters/claude.mjs

@@ -0,0 +1,13 @@
+// lib/core/adapters/claude.mjs — Claude LLM adapter
+// TODO: 實作 Anthropic Claude API 呼叫
+
+export class ClaudeAdapter {
+  constructor(config = {}) {
+    this.model = config.model || 'claude-sonnet-4-6';
+    // TODO: 初始化 API client
+  }
+
+  async chat(messages) {
+    throw new Error('ClaudeAdapter.chat() 尚未實作');
+  }
+}