botrun-horse 1.0.0

package/lib/core/dag.mjs

@@ -0,0 +1,114 @@
+// lib/core/dag.mjs — 通用 DAG 依賴追蹤器
+// 管理任務的狀態、依賴關係、平行調度
+// 支援多專案：透過 project 參數決定路徑
+
+import fs from 'fs';
+import path from 'path';
+import * as paths from './paths.mjs';
+
+/**
+ * 載入 DAG 定義
+ * @param {string} [project='nstc'] - 專案名稱
+ * @param {string} [dagPath] - 自訂 DAG 檔路徑（覆蓋預設）
+ */
+export function loadDag(project = 'nstc', dagPath = null) {
+  const filePath = dagPath || paths.dagDefinitionPath(project);
+  const raw = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  const allDocs = raw.categories.flatMap(c =>
+    c.documents.map(d => ({ ...d, category: c.name }))
+  );
+  return { meta: raw, documents: allDocs };
+}
+
+export function initState(documents) {
+  const state = {};
+  for (const doc of documents) {
+    state[doc.id] = {
+      id: doc.id,
+      type: doc.type,
+      title: doc.title,
+      category: doc.category,
+      deps: doc.deps || [],
+      status: 'pending',
+      startedAt: null,
+      finishedAt: null,
+      outputPath: null,
+      error: null,
+    };
+  }
+  return state;
+}
+
+export function saveState(state, project = 'nstc') {
+  const stateFile = paths.dagStatePath(project);
+  fs.mkdirSync(path.dirname(stateFile), { recursive: true });
+  fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+}
+
+export function loadState(project = 'nstc') {
+  const stateFile = paths.dagStatePath(project);
+  if (fs.existsSync(stateFile)) {
+    return JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+  }
+  return null;
+}
+
+export function getReady(state) {
+  return Object.values(state).filter(task => {
+    if (task.status !== 'pending') return false;
+    return task.deps.every(depId => state[depId]?.status === 'done');
+  });
+}
+
+export function markRunning(state, id) {
+  state[id].status = 'running';
+  state[id].startedAt = new Date().toISOString();
+}
+
+export function markDone(state, id, outputPath) {
+  state[id].status = 'done';
+  state[id].finishedAt = new Date().toISOString();
+  state[id].outputPath = outputPath;
+}
+
+export function markFailed(state, id, error) {
+  state[id].status = 'failed';
+  state[id].finishedAt = new Date().toISOString();
+  state[id].error = String(error);
+}
+
+export function getStatusSummary(state) {
+  const all = Object.values(state);
+  const done = all.filter(t => t.status === 'done').length;
+  const running = all.filter(t => t.status === 'running').length;
+  const pending = all.filter(t => t.status === 'pending').length;
+  const ready = getReady(state).length;
+  const failed = all.filter(t => t.status === 'failed').length;
+  const total = all.length;
+  const pct = Math.floor(done / total * 100);
+  return { total, done, running, pending, ready, failed, pct };
+}
+
+export function formatStatus(state) {
+  const s = getStatusSummary(state);
+  const bar = '█'.repeat(Math.floor(s.pct / 2.5)) + '░'.repeat(40 - Math.floor(s.pct / 2.5));
+  const lines = [
+    `========== DAG 狀態 ==========`,
+    `總計: ${s.total} | 完成: ${s.done} | 執行中: ${s.running} | 就緒: ${s.ready} | 等待中: ${s.pending} | 失敗: ${s.failed}`,
+    `進度: [${bar}] ${s.pct}%`,
+    `==============================`,
+  ];
+
+  // 分類統計
+  const byCategory = {};
+  for (const t of Object.values(state)) {
+    if (!byCategory[t.category]) byCategory[t.category] = { done: 0, total: 0 };
+    byCategory[t.category].total++;
+    if (t.status === 'done') byCategory[t.category].done++;
+  }
+  for (const [cat, info] of Object.entries(byCategory)) {
+    lines.push(`  ${cat}: ${info.done}/${info.total}`);
+  }
+
+  return lines.join('\n');
+}

package/lib/core/db.mjs

@@ -0,0 +1,412 @@
+// lib/core/db.mjs — 通用文件 SQLite 存儲模組
+//
+// 設計原則：SOLID / DRY / KISS
+//   - 單一職責：只負責 SQLite 讀寫，不含業務邏輯
+//   - 冪等設計：INSERT OR IGNORE，重複入庫不拋例外
+//   - 斷點續作：ingestion_log 記錄每個檔案的匯入狀態
+//   - AI/LLM 友善：_meta 表詳細說明 schema 用法
+//
+// 執行時需加 --experimental-sqlite flag
+//   node --experimental-sqlite bin/bh.mjs ...
+//
+// 相依：Node.js 22+ 內建 node:sqlite (DatabaseSync)
+
+import { DatabaseSync } from 'node:sqlite';
+import fs from 'fs';
+import path from 'path';
+
+// ── _meta 表的完整使用說明（供 AI/LLM 引證）──
+const META_USAGE_GUIDE = `
+此 SQLite 資料庫由 botrun-horse 自動建立，用於儲存 PDF/Office 文件的逐頁文字內容。
+
+## 核心資料表
+
+### documents — 文件 metadata
+  id          INTEGER  主鍵（用於 JOIN pages）
+  source_path TEXT     原始檔案完整路徑（唯一）
+  filename    TEXT     原始檔案名稱
+  doc_type    TEXT     文件類型（公文/手冊/法規/報告/論文等）
+  title       TEXT     文件標題
+  total_pages INTEGER  總頁數
+  file_size   INTEGER  檔案大小（bytes）
+  created_at  TEXT     入庫時間（UTC）
+
+### pages — 逐頁文字（引證核心）
+  id          INTEGER  主鍵
+  doc_id      INTEGER  → documents.id
+  page_number INTEGER  頁碼（從 1 開始）
+  page_text   TEXT     該頁全文文字（AI/LLM 使用此欄位）
+  char_count  INTEGER  字元數
+  source_path TEXT     原始檔案完整路徑（引證用）
+  source_file TEXT     原始檔案名稱（引證用）
+  source_page INTEGER  原始頁碼（引證用，與 page_number 相同）
+  split_pdf   TEXT     單頁獨立 PDF 路徑（可 NULL，僅在執行 doc split 後有值）
+
+### pages_fts — FTS5 trigram 全文檢索虛擬表
+  搜尋語法: SELECT ... FROM pages_fts WHERE pages_fts MATCH '關鍵字'
+  特性: trigram tokenizer，天然支援繁體中文/日文/韓文（≥3 字元子字串搜尋）
+
+### ingestion_log — 匯入紀錄（斷點續作）
+  source_path TEXT     原始檔案完整路徑（唯一鍵）
+  doc_id      INTEGER  對應 documents.id（NULL 表示尚未完成）
+  status      TEXT     done | failed
+  pages       INTEGER  成功匯入的頁數
+  ingested_at TEXT     完成時間（UTC）
+  error_msg   TEXT     失敗原因（status=failed 時有值）
+
+## AI/LLM 建議查詢模式
+
+### 1. 全文搜尋（關鍵字引證）
+  SELECT p.source_file, p.source_page, d.title, d.doc_type,
+         snippet(pages_fts, 0, '【', '】', '...', 64) AS context
+  FROM pages_fts
+  JOIN pages p ON p.id = pages_fts.rowid
+  JOIN documents d ON d.id = p.doc_id
+  WHERE pages_fts MATCH '搜尋關鍵字'
+  ORDER BY rank LIMIT 10;
+
+### 2. 取得特定文件的所有頁面
+  SELECT page_number, page_text, source_file, source_page
+  FROM pages WHERE doc_id = ? ORDER BY page_number;
+
+### 3. 引證格式（LLM 回答時建議附上）
+  「根據《{title}》第 {source_page} 頁（{source_file}）：{context}」
+
+### 4. 統計資訊
+  SELECT d.doc_type, COUNT(*) AS 文件數, SUM(d.total_pages) AS 總頁數
+  FROM documents d GROUP BY d.doc_type;
+
+## 後續疊加建議
+  - 新增 tags 表：關聯 documents，支援多標籤分類
+  - 新增 summaries 表：儲存 AI 生成的頁面/章節摘要
+  - 新增 embeddings 表：儲存向量嵌入，支援語義搜尋
+  - 使用 SQLite 的 JSON 欄位擴充任意 metadata（documents.extra_json）
+`.trim();
+
+/**
+ * DocStore — 通用文件 SQLite 存儲層
+ *
+ * 單一職責：存取 SQLite，不含業務邏輯。
+ * 所有寫入操作皆使用 INSERT OR IGNORE，保證冪等性（可重複執行）。
+ */
+export class DocStore {
+  /**
+   * 開啟或建立 SQLite 資料庫
+   * @param {string} dbPath - 資料庫檔案路徑
+   */
+  constructor(dbPath = './output/pdf_docs.db') {
+    const dir = path.dirname(dbPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    this.dbPath = dbPath;
+    this.db = new DatabaseSync(dbPath);
+
+    // WAL 模式：提升並發寫入效能（讀寫可同時進行）
+    this.db.exec('PRAGMA journal_mode = WAL');
+    // 外鍵約束
+    this.db.exec('PRAGMA foreign_keys = ON');
+    // 提升寫入效能（匯入大量頁面時明顯加速）
+    this.db.exec('PRAGMA synchronous = NORMAL');
+  }
+
+  /**
+   * 建立所有資料表、FTS 虛擬表、觸發器與 _meta 說明
+   * 使用 IF NOT EXISTS，可安全重複呼叫（冪等）
+   */
+  initSchema() {
+    // ── _meta：AI/LLM 友善的 schema 說明 ──
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS _meta (
+        key   TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      )
+    `);
+
+    // 插入使用說明（OR REPLACE：每次 initSchema 更新最新說明）
+    this.db.prepare(`
+      INSERT OR REPLACE INTO _meta (key, value) VALUES (?, ?)
+    `).run('schema_version', '2');
+    this.db.prepare(`
+      INSERT OR REPLACE INTO _meta (key, value) VALUES (?, ?)
+    `).run('usage_guide', META_USAGE_GUIDE);
+    this.db.prepare(`
+      INSERT OR REPLACE INTO _meta (key, value) VALUES (?, ?)
+    `).run('created_by', 'botrun-horse');
+    this.db.prepare(`
+      INSERT OR REPLACE INTO _meta (key, value) VALUES (?, ?)
+    `).run('updated_at', new Date().toISOString());
+
+    // ── documents：文件 metadata 總表 ──
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS documents (
+        id            INTEGER PRIMARY KEY AUTOINCREMENT,
+        source_path   TEXT NOT NULL UNIQUE,
+        filename      TEXT NOT NULL,
+        doc_type      TEXT,
+        title         TEXT,
+        total_pages   INTEGER,
+        file_size     INTEGER,
+        created_at    TEXT DEFAULT (datetime('now'))
+      )
+    `);
+
+    // ── pages：逐頁文字（引證鏈核心）──
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS pages (
+        id            INTEGER PRIMARY KEY AUTOINCREMENT,
+        doc_id        INTEGER NOT NULL REFERENCES documents(id),
+        page_number   INTEGER NOT NULL,
+        page_text     TEXT,
+        char_count    INTEGER,
+        source_path   TEXT NOT NULL,
+        source_file   TEXT NOT NULL,
+        source_page   INTEGER NOT NULL,
+        split_pdf     TEXT,
+        UNIQUE(doc_id, page_number)
+      )
+    `);
+
+    // ── pages_fts：FTS5 trigram 全文檢索 ──
+    // trigram tokenizer：三字元組比對，天然支援 CJK（繁中/日/韓）
+    this.db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS pages_fts USING fts5(
+        page_text,
+        content='pages',
+        content_rowid='id',
+        tokenize='trigram case_sensitive 0 remove_diacritics 0'
+      )
+    `);
+
+    // ── FTS 自動同步觸發器 ──
+    this.db.exec(`
+      CREATE TRIGGER IF NOT EXISTS pages_ai AFTER INSERT ON pages BEGIN
+        INSERT INTO pages_fts(rowid, page_text) VALUES (new.id, new.page_text);
+      END
+    `);
+    this.db.exec(`
+      CREATE TRIGGER IF NOT EXISTS pages_ad AFTER DELETE ON pages BEGIN
+        INSERT INTO pages_fts(pages_fts, rowid, page_text) VALUES('delete', old.id, old.page_text);
+      END
+    `);
+    this.db.exec(`
+      CREATE TRIGGER IF NOT EXISTS pages_au AFTER UPDATE ON pages BEGIN
+        INSERT INTO pages_fts(pages_fts, rowid, page_text) VALUES('delete', old.id, old.page_text);
+        INSERT INTO pages_fts(rowid, page_text) VALUES (new.id, new.page_text);
+      END
+    `);
+
+    // ── ingestion_log：匯入紀錄（斷點續作）──
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ingestion_log (
+        source_path TEXT PRIMARY KEY,
+        doc_id      INTEGER REFERENCES documents(id),
+        status      TEXT NOT NULL DEFAULT 'done',
+        pages       INTEGER,
+        ingested_at TEXT DEFAULT (datetime('now')),
+        error_msg   TEXT
+      )
+    `);
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // ingestion_log：斷點續作
+  // ─────────────────────────────────────────────────────────
+
+  /**
+   * 檢查檔案是否已成功匯入（斷點續作用）
+   * @param {string} sourcePath - 原始檔案完整路徑
+   * @returns {boolean} true = 已匯入，可跳過
+   */
+  isIngested(sourcePath) {
+    const row = this.db.prepare(
+      `SELECT status FROM ingestion_log WHERE source_path = ?`
+    ).get(sourcePath);
+    return row?.status === 'done';
+  }
+
+  /**
+   * 記錄匯入成功
+   * @param {string} sourcePath
+   * @param {number} docId
+   * @param {number} pages
+   */
+  logIngested(sourcePath, docId, pages) {
+    this.db.prepare(`
+      INSERT OR REPLACE INTO ingestion_log (source_path, doc_id, status, pages, ingested_at)
+      VALUES (?, ?, 'done', ?, datetime('now'))
+    `).run(sourcePath, docId, pages);
+  }
+
+  /**
+   * 記錄匯入失敗
+   * @param {string} sourcePath
+   * @param {string} errorMsg
+   */
+  logFailed(sourcePath, errorMsg) {
+    this.db.prepare(`
+      INSERT OR REPLACE INTO ingestion_log (source_path, status, error_msg, ingested_at)
+      VALUES (?, 'failed', ?, datetime('now'))
+    `).run(sourcePath, errorMsg);
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // documents：文件 metadata CRUD
+  // ─────────────────────────────────────────────────────────
+
+  /**
+   * 新增文件 metadata（冪等：已存在時回傳現有 ID）
+   *
+   * @param {Object} doc
+   * @param {string} doc.sourcePath   - 來源檔案路徑（唯一鍵）
+   * @param {string} doc.filename     - 檔案名稱
+   * @param {string} [doc.docType]    - 文件類型
+   * @param {string} [doc.title]      - 文件標題
+   * @param {number} [doc.totalPages] - 總頁數
+   * @param {number} [doc.fileSize]   - 檔案大小（bytes）
+   * @returns {number} doc_id（新建或現有）
+   */
+  insertDocument({ sourcePath, filename, docType = null, title = null, totalPages = null, fileSize = null }) {
+    // OR IGNORE：source_path 重複時靜默忽略
+    this.db.prepare(`
+      INSERT OR IGNORE INTO documents (source_path, filename, doc_type, title, total_pages, file_size)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(sourcePath, filename, docType, title, totalPages, fileSize);
+
+    // 回傳現有或剛插入的 ID
+    const row = this.db.prepare(`SELECT id FROM documents WHERE source_path = ?`).get(sourcePath);
+    return Number(row.id);
+  }
+
+  /**
+   * 新增單頁文字內容（冪等：(doc_id, page_number) 重複時靜默忽略）
+   *
+   * @param {Object} page
+   * @param {number} page.docId      - 所屬文件 ID
+   * @param {number} page.pageNumber - 頁碼
+   * @param {string} [page.pageText] - 頁面文字內容
+   * @param {string} page.sourcePath - 來源檔案完整路徑（引證用）
+   * @param {string} page.sourceFile - 來源檔案名稱（引證用）
+   * @param {number} page.sourcePage - 來源頁碼（引證用）
+   * @param {string} [page.splitPdf] - 拆分後的單頁 PDF 路徑
+   * @returns {number} page_id（新建或現有）
+   */
+  insertPage({ docId, pageNumber, pageText = null, sourcePath, sourceFile, sourcePage, splitPdf = null }) {
+    const charCount = pageText ? pageText.length : 0;
+    // OR IGNORE：(doc_id, page_number) 重複時靜默忽略
+    this.db.prepare(`
+      INSERT OR IGNORE INTO pages
+        (doc_id, page_number, page_text, char_count, source_path, source_file, source_page, split_pdf)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(docId, pageNumber, pageText, charCount, sourcePath, sourceFile, sourcePage, splitPdf);
+
+    const row = this.db.prepare(
+      `SELECT id FROM pages WHERE doc_id = ? AND page_number = ?`
+    ).get(docId, pageNumber);
+    return Number(row.id);
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // 查詢
+  // ─────────────────────────────────────────────────────────
+
+  /**
+   * FTS5 trigram 全文檢索
+   * 自動將查詢字串拆成三字元組，天然支援 CJK 子字串搜尋（≥3 字元）
+   *
+   * @param {string} query  - 搜尋關鍵字（≥3 字元）
+   * @param {number} [limit] - 最多回傳筆數（預設不限）
+   * @returns {Array<Object>} 搜尋結果（含引證資訊與 snippet）
+   */
+  search(query, limit = null) {
+    if (!query || query.trim().length === 0) return [];
+
+    let sql = `
+      SELECT
+        p.doc_id,
+        p.id          AS page_id,
+        p.page_number,
+        p.source_path,
+        p.source_file,
+        p.source_page,
+        p.split_pdf,
+        snippet(pages_fts, 0, '【', '】', '...', 64) AS snippet,
+        d.doc_type,
+        d.title
+      FROM pages_fts
+      JOIN pages p ON p.id = pages_fts.rowid
+      JOIN documents d ON d.id = p.doc_id
+      WHERE pages_fts MATCH ?
+      ORDER BY rank
+    `;
+    if (limit && limit > 0) sql += ` LIMIT ${parseInt(limit)}`;
+
+    return this.db.prepare(sql).all(query);
+  }
+
+  /**
+   * 依 ID 取得單一文件 metadata
+   * @param {number} id - 文件 ID
+   * @returns {Object|undefined}
+   */
+  getDocument(id) {
+    return this.db.prepare('SELECT * FROM documents WHERE id = ?').get(id);
+  }
+
+  /**
+   * 取得指定文件的所有頁面（依頁碼排序）
+   * @param {number} docId - 文件 ID
+   * @returns {Array<Object>}
+   */
+  getPages(docId) {
+    return this.db.prepare('SELECT * FROM pages WHERE doc_id = ? ORDER BY page_number').all(docId);
+  }
+
+  /**
+   * 取得資料庫統計資訊
+   * @returns {{ documents, pages, totalChars, byType, ingestionLog }}
+   */
+  stats() {
+    const docCount  = this.db.prepare('SELECT COUNT(*) AS count FROM documents').get();
+    const pageCount = this.db.prepare('SELECT COUNT(*) AS count FROM pages').get();
+    const totalChars = this.db.prepare('SELECT COALESCE(SUM(char_count), 0) AS total FROM pages').get();
+
+    const byType = this.db.prepare(`
+      SELECT doc_type, COUNT(*) AS count
+      FROM documents
+      GROUP BY doc_type
+      ORDER BY count DESC
+    `).all();
+
+    const ingestionLog = this.db.prepare(`
+      SELECT status, COUNT(*) AS count
+      FROM ingestion_log
+      GROUP BY status
+    `).all();
+
+    return {
+      documents: docCount.count,
+      pages: pageCount.count,
+      totalChars: totalChars.total,
+      byType,
+      ingestionLog,
+    };
+  }
+
+  /**
+   * 取得 _meta 表中的 schema 使用說明（供 AI/LLM 參考）
+   * @returns {string} 使用說明 Markdown
+   */
+  getUsageGuide() {
+    const row = this.db.prepare(`SELECT value FROM _meta WHERE key = 'usage_guide'`).get();
+    return row?.value || '';
+  }
+
+  /**
+   * 關閉資料庫連線
+   */
+  close() {
+    this.db.close();
+  }
+}

package/lib/core/env.mjs

@@ -0,0 +1,64 @@
+// lib/core/env.mjs — 零依賴 .env 載入器
+//
+// 設計原則：KISS / DRY
+//   - 不引入 dotenv npm 套件，純 Node.js fs 讀取
+//   - 預設覆蓋已有環境變數（.env 是專案級設定，優先於 shell 全域 export）
+//   - 支援 # 註解、空行、雙引號值、等號左右無空格
+//
+// 使用方式（必須在所有 import 之前）：
+//   import { loadEnv } from '../core/env.mjs';
+//   loadEnv();   // 自動從專案根目錄讀取 .env
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = path.resolve(__dirname, '../..');
+
+/**
+ * 載入 .env 檔案到 process.env
+ *
+ * @param {string} [envPath] - .env 檔案路徑（預設為專案根目錄 .env）
+ * @param {object} [opts]
+ * @param {boolean} [opts.override=true] - .env 優先覆蓋 shell 全域環境變數
+ * @returns {number} 成功載入的變數數量
+ */
+export function loadEnv(envPath, opts = {}) {
+  const filePath = envPath || path.join(PROJECT_ROOT, '.env');
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return 0; // 檔案不存在，靜默跳過
+  }
+
+  let count = 0;
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    // 跳過空行和註解
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // 解析 KEY=VALUE（支援 export KEY=VALUE）
+    const match = trimmed.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!match) continue;
+
+    const key = match[1];
+    let value = match[2].trim();
+
+    // 去掉包裹的引號（"value" 或 'value'）
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+
+    // .env 專案級設定優先於 shell 全域 export（除非 override=false）
+    const override = opts.override ?? true;
+    if (!override && process.env[key] !== undefined) continue;
+
+    process.env[key] = value;
+    count++;
+  }
+
+  return count;
+}

package/lib/core/llm.mjs

@@ -0,0 +1,58 @@
+// lib/core/llm.mjs — LLM 統一介面 (Factory Pattern)
+// 遵循 SOLID OCP：新增 provider 不需修改既有程式碼
+//
+// Provider 選擇策略：
+//   1. 明確指定 provider 參數
+//   2. 若 provider='gemini-auto'（或未指定）→ 自動偵測：
+//      - 有 GOOGLE_CLOUD_PROJECT + ADC → gemini（Vertex AI）
+//      - 有 GEMINI_API_KEY → gemini-api（Direct API）
+
+/**
+ * 自動偵測最佳 Gemini provider
+ * @returns {'gemini' | 'gemini-api' | null}
+ */
+function detectGeminiProvider() {
+  if (process.env.GOOGLE_CLOUD_PROJECT) return 'gemini';
+  if (process.env.GEMINI_API_KEY) return 'gemini-api';
+  return null;
+}
+
+/**
+ * 建立 LLM adapter
+ * @param {object} config - { provider, ...adapterOpts }
+ * @param {string} [config.provider='gemini-auto'] - LLM provider
+ * @returns {Promise<object>} adapter 實例
+ */
+export async function createLLM(config = {}) {
+  const { provider: rawProvider, ...opts } = config;
+
+  // 自動偵測
+  const provider = (rawProvider === 'gemini-auto' || !rawProvider)
+    ? (detectGeminiProvider() || 'gemini')
+    : rawProvider;
+
+  switch (provider) {
+    case 'gemini': {
+      const { GeminiVertexAdapter } = await import('./adapters/gemini-vertex.mjs');
+      return new GeminiVertexAdapter(opts);
+    }
+    case 'gemini-api': {
+      const { GeminiApiAdapter } = await import('./adapters/gemini-api.mjs');
+      return new GeminiApiAdapter(opts);
+    }
+    case 'claude': {
+      const { ClaudeAdapter } = await import('./adapters/claude.mjs');
+      return new ClaudeAdapter(opts);
+    }
+    case 'nchc': {
+      const { NchcAdapter } = await import('./adapters/nchc.mjs');
+      return new NchcAdapter(opts);
+    }
+    case 'openrouter': {
+      const { OpenRouterAdapter } = await import('./adapters/openrouter.mjs');
+      return new OpenRouterAdapter(opts);
+    }
+    default:
+      throw new Error(`LLM provider "${provider}" 尚未實作。可用: gemini, gemini-api, claude, nchc, openrouter`);
+  }
+}