botrun-horse 1.0.0

package/lib/core/ai-cache.mjs

@@ -0,0 +1,277 @@
+// lib/core/ai-cache.mjs — 通用 AI 問答快取 SQLite 層
+//
+// 設計原則：SOLID / DRY / KISS / DDD
+//   - 單一職責：只負責 SQLite 讀寫，不含路由或 LLM 業務邏輯
+//   - 冪等設計：重複儲存相同問題不拋例外
+//   - DDD Value Object：QaEntry（問題 + 標籤 + 兩步回答 + 來源）
+//   - 通用能力：不限定法律領域，任何領域皆可使用
+//
+// 使用方式：
+//   import { AiCache } from '../core/ai-cache.mjs';
+//   const cache = new AiCache(dbPath);
+//   cache.initSchema();
+//   cache.insertQa({ question, tags, step1Result, step2Answer, sources });
+//   const candidates = cache.findByTags(['租賃', '驅逐']);
+//   cache.incrementHit(id);
+//
+// 需要 Node.js --experimental-sqlite flag：
+//   node --experimental-sqlite bin/bh.mjs ...
+
+import { DatabaseSync } from 'node:sqlite';
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * AiCache — 通用 AI 問答快取存取層
+ *
+ * 表結構：
+ *   qa_cache   — 問答快取主表（問題、標籤、兩步回答、來源）
+ *   router_log — 路由決策紀錄（供效能分析與除錯）
+ */
+export class AiCache {
+  /**
+   * 開啟或建立 SQLite 資料庫
+   * @param {string} dbPath - 資料庫檔案路徑
+   */
+  constructor(dbPath) {
+    const dir = path.dirname(dbPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    this.dbPath = dbPath;
+    this.db = new DatabaseSync(dbPath);
+    this.db.exec('PRAGMA journal_mode = WAL');
+    this.db.exec('PRAGMA foreign_keys = ON');
+    this.db.exec('PRAGMA synchronous = NORMAL');
+  }
+
+  /**
+   * 建立資料表（冪等，可重複呼叫）
+   */
+  initSchema() {
+    // ── qa_cache：問答快取主表 ──
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS qa_cache (
+        id            INTEGER PRIMARY KEY AUTOINCREMENT,
+        question      TEXT NOT NULL,
+        tags          TEXT NOT NULL DEFAULT '[]',
+        step1_laws    TEXT,
+        step2_answer  TEXT,
+        sources       TEXT NOT NULL DEFAULT '[]',
+        model_step1   TEXT,
+        model_step2   TEXT,
+        hit_count     INTEGER NOT NULL DEFAULT 0,
+        created_at    TEXT DEFAULT (datetime('now')),
+        updated_at    TEXT DEFAULT (datetime('now'))
+      )
+    `);
+
+    // ── router_log：路由決策紀錄 ──
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS router_log (
+        id          INTEGER PRIMARY KEY AUTOINCREMENT,
+        question    TEXT NOT NULL,
+        decision    TEXT NOT NULL,
+        cache_id    INTEGER REFERENCES qa_cache(id),
+        confidence  REAL,
+        tags        TEXT NOT NULL DEFAULT '[]',
+        reason      TEXT,
+        latency_ms  INTEGER,
+        created_at  TEXT DEFAULT (datetime('now'))
+      )
+    `);
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // qa_cache：問答快取 CRUD
+  // ─────────────────────────────────────────────────────────
+
+  /**
+   * 儲存問答快取（每次都新增一筆，允許相同問題有多版本）
+   *
+   * @param {object} entry
+   * @param {string} entry.question      - 使用者原始問題
+   * @param {string[]} entry.tags        - 法律領域標籤陣列（由 AI Router 萃取）
+   * @param {string} [entry.step1Laws]   - Step1 搜尋到的法條（JSON 字串）
+   * @param {string} [entry.step2Answer] - Step2 最終回答
+   * @param {Array}  [entry.sources]     - 引證來源陣列 [{uri, title}]
+   * @param {string} [entry.modelStep1]  - Step1 使用的模型
+   * @param {string} [entry.modelStep2]  - Step2 使用的模型
+   * @returns {number} 新建的快取 ID
+   */
+  insertQa({ question, tags = [], step1Laws = null, step2Answer = null, sources = [], modelStep1 = null, modelStep2 = null }) {
+    const result = this.db.prepare(`
+      INSERT INTO qa_cache (question, tags, step1_laws, step2_answer, sources, model_step1, model_step2)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      question,
+      JSON.stringify(tags),
+      step1Laws,
+      step2Answer,
+      JSON.stringify(sources),
+      modelStep1,
+      modelStep2,
+    );
+    return Number(result.lastInsertRowid);
+  }
+
+  /**
+   * 依標籤交集查詢快取候選（標籤重疊數 >= minOverlap 才回傳）
+   *
+   * 策略：JSON 欄位逐一比對，適合快取量 < 10,000 筆的場景。
+   * 大型快取應改用全文索引或向量搜尋。
+   *
+   * @param {string[]} tags      - 查詢標籤陣列
+   * @param {number} [minOverlap=1] - 最少重疊標籤數
+   * @param {number} [limit=10]  - 回傳筆數上限
+   * @returns {Array<QaEntry>} 候選快取條目（降冪排序：hit_count DESC, created_at DESC）
+   */
+  findByTags(tags, minOverlap = 1, limit = 10) {
+    if (!tags || tags.length === 0) return [];
+
+    // 取出所有有 step2_answer 的快取（已完整回答）
+    const rows = this.db.prepare(`
+      SELECT id, question, tags, step1_laws, step2_answer, sources,
+             model_step1, model_step2, hit_count, created_at
+      FROM qa_cache
+      WHERE step2_answer IS NOT NULL
+      ORDER BY hit_count DESC, created_at DESC
+    `).all();
+
+    // 計算標籤交集數量，過濾後排序
+    const candidates = rows
+      .map(row => {
+        let cachedTags = [];
+        try { cachedTags = JSON.parse(row.tags); } catch { /* 忽略 JSON 解析失敗 */ }
+
+        const overlap = tags.filter(t => cachedTags.includes(t)).length;
+        return { ...row, _overlap: overlap };
+      })
+      .filter(row => row._overlap >= minOverlap)
+      .sort((a, b) => b._overlap - a._overlap || b.hit_count - a.hit_count)
+      .slice(0, limit);
+
+    // 還原 JSON 欄位（DDD Value Object）
+    return candidates.map(row => ({
+      id: Number(row.id),
+      question: row.question,
+      tags: (() => { try { return JSON.parse(row.tags); } catch { return []; } })(),
+      step1Laws: row.step1_laws,
+      step2Answer: row.step2_answer,
+      sources: (() => { try { return JSON.parse(row.sources); } catch { return []; } })(),
+      modelStep1: row.model_step1,
+      modelStep2: row.model_step2,
+      hitCount: Number(row.hit_count),
+      overlap: row._overlap,
+    }));
+  }
+
+  /**
+   * 依 ID 取得快取條目
+   * @param {number} id
+   * @returns {QaEntry|undefined}
+   */
+  getById(id) {
+    const row = this.db.prepare('SELECT * FROM qa_cache WHERE id = ?').get(id);
+    if (!row) return undefined;
+    return {
+      id: Number(row.id),
+      question: row.question,
+      tags: (() => { try { return JSON.parse(row.tags); } catch { return []; } })(),
+      step1Laws: row.step1_laws,
+      step2Answer: row.step2_answer,
+      sources: (() => { try { return JSON.parse(row.sources); } catch { return []; } })(),
+      modelStep1: row.model_step1,
+      modelStep2: row.model_step2,
+      hitCount: Number(row.hit_count),
+    };
+  }
+
+  /**
+   * 累加快取命中次數（每次 cache hit 後呼叫）
+   * @param {number} id - 快取條目 ID
+   */
+  incrementHit(id) {
+    this.db.prepare(`
+      UPDATE qa_cache
+      SET hit_count = hit_count + 1, updated_at = datetime('now')
+      WHERE id = ?
+    `).run(id);
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // router_log：路由決策紀錄
+  // ─────────────────────────────────────────────────────────
+
+  /**
+   * 記錄路由決策（供效能分析）
+   *
+   * @param {object} log
+   * @param {string} log.question    - 使用者問題
+   * @param {string} log.decision    - 'cache' | 'search'
+   * @param {number} [log.cacheId]   - 命中的快取 ID（decision='cache' 時有值）
+   * @param {number} [log.confidence]- 信心分數（0.0 ~ 1.0）
+   * @param {string[]} [log.tags]    - 問題標籤
+   * @param {string} [log.reason]    - 決策原因說明
+   * @param {number} [log.latencyMs] - 路由決策耗時（毫秒）
+   */
+  logRouterDecision({ question, decision, cacheId = null, confidence = null, tags = [], reason = null, latencyMs = null }) {
+    this.db.prepare(`
+      INSERT INTO router_log (question, decision, cache_id, confidence, tags, reason, latency_ms)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(question, decision, cacheId, confidence, JSON.stringify(tags), reason, latencyMs);
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // 統計資訊
+  // ─────────────────────────────────────────────────────────
+
+  /**
+   * 取得快取統計
+   * @returns {object} 統計資訊
+   */
+  stats() {
+    const total = this.db.prepare('SELECT COUNT(*) AS count FROM qa_cache WHERE step2_answer IS NOT NULL').get();
+    const totalHits = this.db.prepare('SELECT COALESCE(SUM(hit_count), 0) AS total FROM qa_cache').get();
+    const routerLog = this.db.prepare(`
+      SELECT decision, COUNT(*) AS count FROM router_log GROUP BY decision
+    `).all();
+    const topHit = this.db.prepare(`
+      SELECT question, hit_count FROM qa_cache
+      WHERE step2_answer IS NOT NULL
+      ORDER BY hit_count DESC LIMIT 5
+    `).all();
+
+    return {
+      cachedQuestions: Number(total.count),
+      totalCacheHits: Number(totalHits.total),
+      routerDecisions: routerLog,
+      topHitQuestions: topHit,
+    };
+  }
+
+  /**
+   * 列出所有快取問題（用於除錯）
+   * @param {number} [limit=20]
+   */
+  listAll(limit = 20) {
+    return this.db.prepare(`
+      SELECT id, question, tags, hit_count, created_at
+      FROM qa_cache WHERE step2_answer IS NOT NULL
+      ORDER BY created_at DESC LIMIT ?
+    `).all(limit).map(row => ({
+      id: Number(row.id),
+      question: row.question,
+      tags: (() => { try { return JSON.parse(row.tags); } catch { return []; } })(),
+      hitCount: Number(row.hit_count),
+      createdAt: row.created_at,
+    }));
+  }
+
+  /**
+   * 關閉資料庫連線
+   */
+  close() {
+    this.db.close();
+  }
+}

package/lib/core/ai-router.mjs

@@ -0,0 +1,217 @@
+// lib/core/ai-router.mjs — 通用 AI 路由決策層
+//
+// 功能：用小模型（Mistral 14B）決定是否使用快取還是呼叫大模型
+//
+// 架構設計（SOLID/DDD）：
+//   SRP — 只負責路由決策，不執行 LLM 查詢
+//   OCP — 可換不同小模型而不改介面
+//   DDD — RouterDecision Value Object
+//
+// 兩步路由策略（方案 B：標籤索引 + LLM 確認）：
+//   1. 萃取標籤：Mistral 14B 從問題中萃取法律領域標籤
+//   2. 標籤篩選：SQLite 找到標籤重疊的快取候選
+//   3. LLM 確認：Mistral 14B 確認候選是否語義相關
+//   4. 決策輸出：RouterDecision { decision, cacheId, confidence, tags, reason }
+//
+// RouterDecision Value Object：
+//   { decision: 'cache'|'search', cacheId: number|null,
+//     confidence: float, tags: string[], reason: string }
+
+import { createLLM } from './llm.mjs';
+
+/**
+ * 從可能包含 markdown code block 的文字中萃取 JSON（容錯）
+ * Mistral 14B 常回傳 ```json {...} ``` 格式
+ * @param {string} text
+ * @returns {object|null}
+ */
+function extractJson(text) {
+  const trimmed = (text || '').trim();
+  // 1. 直接嘗試 JSON.parse
+  try { return JSON.parse(trimmed); } catch { /* 繼續 */ }
+  // 2. 去掉 markdown code block 包裝
+  const mdMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+  if (mdMatch) {
+    try { return JSON.parse(mdMatch[1].trim()); } catch { /* 繼續 */ }
+  }
+  // 3. 從文字中提取第一個 {...}
+  const braceMatch = trimmed.match(/\{[\s\S]*\}/);
+  if (braceMatch) {
+    try { return JSON.parse(braceMatch[0]); } catch { /* 繼續 */ }
+  }
+  return null;
+}
+
+// ── 提示詞常數（SOLID OCP：修改提示不改程式結構） ─────────────────────────
+
+/**
+ * Step1 提示：從問題萃取法律領域標籤
+ * 輸出 JSON 格式，方便解析
+ */
+const EXTRACT_TAGS_SYSTEM = `你是法律分類專家。你的任務是從使用者的問題中萃取關鍵的法律領域標籤。
+
+規則：
+1. 只輸出 JSON，不輸出其他文字
+2. 標籤必須是繁體中文、簡短（1-4 個字）
+3. 最多 5 個標籤
+4. 聚焦於法律概念，而非口語描述（例如「驅逐」而非「趕走」）
+
+輸出格式（嚴格遵守）：
+{"tags": ["標籤1", "標籤2", "標籤3"]}`;
+
+/**
+ * Step2 提示：確認快取候選是否適用於當前問題
+ * 輸出 JSON 格式的確認結果
+ */
+const CONFIRM_CACHE_SYSTEM = `你是法律問答助理。你的任務是判斷既有的快取答案是否適合回答新的使用者問題。
+
+規則：
+1. 只輸出 JSON，不輸出其他文字
+2. 若快取答案涵蓋的法律概念與新問題高度重疊（≥ 80%），判定為適用
+3. 考量問題的法律情境是否相同，不只看表面用詞
+
+輸出格式（嚴格遵守）：
+{"useCache": true|false, "cacheId": <數字或null>, "confidence": 0.0~1.0, "reason": "一句話說明"}`;
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * AiRouter — 通用 AI 路由決策器
+ *
+ * 使用小模型（Mistral 14B）判斷是否使用 SQLite 快取，
+ * 避免重複呼叫昂貴的大模型。
+ */
+export class AiRouter {
+  /**
+   * @param {object} opts
+   * @param {string} [opts.provider='nchc']          - 路由用小模型 provider
+   * @param {string} [opts.model]                    - 路由用小模型 ID
+   * @param {number} [opts.tagCacheThreshold=2]      - 標籤重疊數 >= 此值才納入候選
+   * @param {number} [opts.confidenceThreshold=0.75] - 信心分數閾值（低於此值仍呼叫大模型）
+   */
+  constructor({
+    provider = 'nchc',
+    model = 'Ministral-3-14B-Instruct-2512',
+    tagCacheThreshold = 2,
+    confidenceThreshold = 0.75,
+  } = {}) {
+    this.provider = provider;
+    this.model = model;
+    this.tagCacheThreshold = tagCacheThreshold;
+    this.confidenceThreshold = confidenceThreshold;
+  }
+
+  /**
+   * 建立小模型 adapter（DRY：兩個步驟共用）
+   * @returns {Promise<BaseAdapter>}
+   */
+  async _createRouterLlm() {
+    return createLLM({ provider: this.provider, model: this.model, temperature: 0.1 });
+  }
+
+  /**
+   * Step1：從問題萃取法律領域標籤
+   *
+   * @param {string} question - 使用者問題
+   * @returns {Promise<string[]>} 法律標籤陣列
+   */
+  async extractTags(question) {
+    const llm = await this._createRouterLlm();
+    const result = await llm.generateContent({
+      prompt: `使用者問題：${question}`,
+      systemInstruction: EXTRACT_TAGS_SYSTEM,
+    });
+
+    const parsed = extractJson(result.text);
+    if (parsed && Array.isArray(parsed.tags)) return parsed.tags;
+
+    // 最終回退：正則萃取（容錯）
+    const match = result.text.match(/"tags"\s*:\s*\[([^\]]+)\]/);
+    if (match) {
+      return match[1].split(',').map(t => t.replace(/["'\s]/g, '')).filter(Boolean);
+    }
+    return [];
+  }
+
+  /**
+   * Step2：確認快取候選是否適用於當前問題
+   *
+   * @param {string} question            - 使用者問題
+   * @param {Array<QaEntry>} candidates  - 快取候選（來自 AiCache.findByTags）
+   * @returns {Promise<{useCache: boolean, cacheId: number|null, confidence: number, reason: string}>}
+   */
+  async confirmCacheMatch(question, candidates) {
+    if (!candidates || candidates.length === 0) {
+      return { useCache: false, cacheId: null, confidence: 0, reason: '無快取候選' };
+    }
+
+    // 建構候選清單（只給 Mistral 看問題和標籤，不給完整答案，避免 context 過長）
+    const candidateList = candidates.slice(0, 3).map((c, i) =>
+      `[${i + 1}] id=${c.id} 問題：「${c.question}」 標籤：${c.tags.join('、')}`
+    ).join('\n');
+
+    const llm = await this._createRouterLlm();
+    const result = await llm.generateContent({
+      systemInstruction: CONFIRM_CACHE_SYSTEM,
+      prompt: `新問題：「${question}」\n\n快取候選：\n${candidateList}`,
+    });
+
+    const parsed = extractJson(result.text);
+    if (parsed && typeof parsed.useCache !== 'undefined') {
+      return {
+        useCache: Boolean(parsed.useCache),
+        cacheId: parsed.cacheId ? Number(parsed.cacheId) : null,
+        confidence: Number(parsed.confidence) || 0,
+        reason: String(parsed.reason || ''),
+      };
+    }
+    // JSON 解析完全失敗：保守策略，不用快取
+    return { useCache: false, cacheId: null, confidence: 0, reason: `路由模型輸出解析失敗（原文：${result.text.substring(0, 100)}），保守策略不用快取` };
+  }
+
+  /**
+   * 完整路由決策（組合 Step1 + Step2）
+   *
+   * @param {string} question            - 使用者問題
+   * @param {AiCache} cache              - 快取存取層（dependency injection）
+   * @returns {Promise<RouterDecision>}  - 路由決策 Value Object
+   */
+  async route(question, cache) {
+    const t0 = performance.now();
+
+    // Step1：萃取標籤
+    const tags = await this.extractTags(question);
+
+    // Step2：標籤索引查詢候選
+    const candidates = cache.findByTags(tags, this.tagCacheThreshold);
+
+    // Step3：LLM 確認（只有候選存在時才呼叫）
+    let matchResult = { useCache: false, cacheId: null, confidence: 0, reason: '無標籤重疊候選' };
+    if (candidates.length > 0) {
+      matchResult = await this.confirmCacheMatch(question, candidates);
+    }
+
+    const latencyMs = Math.round(performance.now() - t0);
+
+    // Step4：信心分數過低時，保守策略不用快取
+    if (matchResult.useCache && matchResult.confidence < this.confidenceThreshold) {
+      matchResult = {
+        ...matchResult,
+        useCache: false,
+        reason: `信心分數 ${matchResult.confidence} 低於閾值 ${this.confidenceThreshold}，保守策略呼叫大模型`,
+      };
+    }
+
+    /** @type {RouterDecision} */
+    const decision = {
+      decision: matchResult.useCache ? 'cache' : 'search',
+      cacheId: matchResult.useCache ? matchResult.cacheId : null,
+      confidence: matchResult.confidence,
+      tags,
+      reason: matchResult.reason,
+      latencyMs,
+    };
+
+    return decision;
+  }
+}

package/lib/core/cli-utils.mjs

@@ -0,0 +1,170 @@
+// lib/core/cli-utils.mjs — CLI 共用工具
+// 從原 src/cli.mjs 抽出的通用函式
+
+import fs from 'fs';
+import path from 'path';
+
+const VERSION = '2.0.0';
+
+// 支援的文件副檔名（doc 系列指令）
+const DOC_EXTS = new Set(['.pdf', '.docx', '.doc', '.odt', '.pptx', '.ppt', '.odp', '.xlsx', '.xls', '.ods', '.txt', '.md', '.rst']);
+
+/**
+ * 解析 CLI 參數
+ * @param {string[]} argv - process.argv
+ * @returns {{ command, subcommand, flags, positionals }}
+ */
+export function parseArgs(argv) {
+  const args = argv.slice(2);
+  const command = args[0];
+  const subcommand = args[1];
+  const flags = {};
+  const positionals = [];
+
+  // 判斷需跳過子指令的指令群組
+  const hasSubcommand = ['dag', 'db', 'doc', 'writing', 'search', 'portal', 'ocr', 'gemini', 'prompt'].includes(command);
+  const flagStart = hasSubcommand ? 2 : 1;
+  for (const arg of args.slice(flagStart)) {
+    if (arg.startsWith('--')) {
+      const eq = arg.indexOf('=');
+      if (eq > -1) {
+        flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+      } else {
+        flags[arg.slice(2)] = true;
+      }
+    } else {
+      positionals.push(arg);
+    }
+  }
+
+  return { command, subcommand, flags, positionals };
+}
+
+/** 讀取 stdin（非 TTY 時） */
+export async function readStdin() {
+  if (process.stdin.isTTY) return null;
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString().trim();
+}
+
+/**
+ * 解析檔案來源：positional args、--dir flag、或 stdin pipe
+ * 支援任意文件副檔名（PDF / Office / 純文字），不再限制僅 .pdf
+ * 支援 --print0：NUL 分隔的路徑輸出（與 xargs -0 / GNU parallel 相容）
+ */
+export async function resolveFiles(positionals, flags) {
+  const isDoc = (f) => DOC_EXTS.has(path.extname(f).toLowerCase());
+
+  if (flags.dir) {
+    const dir = path.resolve(flags.dir);
+    return fs.readdirSync(dir).filter(isDoc).sort().map(f => path.join(dir, f));
+  }
+  const useStdin = (positionals.length === 1 && positionals[0] === '-') ||
+                   (positionals.length === 0 && !process.stdin.isTTY);
+  if (useStdin) {
+    const stdin = await readStdin();
+    if (!stdin) return [];
+    // 支援 NUL 分隔（--print0 輸出的來源）與換行分隔兩種格式
+    const sep = stdin.includes('\0') ? /\0/ : /\n/;
+    return stdin.split(sep).map(l => l.trim()).filter(l => l && isDoc(l));
+  }
+  if (positionals.length > 0) {
+    return positionals.map(p => path.resolve(p));
+  }
+  return [];
+}
+
+/**
+ * 將檔案路徑列印到 stdout
+ * --print0：NUL 分隔（與 xargs -0 / GNU parallel 相容）
+ * 預設：換行分隔
+ */
+export function printPaths(paths, flags) {
+  if (flags.print0) {
+    process.stdout.write(paths.join('\0') + (paths.length ? '\0' : ''));
+  } else {
+    for (const p of paths) process.stdout.write(p + '\n');
+  }
+}
+
+/**
+ * 進度訊息輸出（僅在非 --quiet 模式下寫到 stderr）
+ * GNU parallel 使用時可加 --quiet 靜默進度輸出
+ */
+export function logProgress(message, flags) {
+  if (!flags?.quiet) process.stderr.write(message + '\n');
+}
+
+/** 平行批次執行 */
+export async function parallelBatch(items, concurrency, fn) {
+  const results = [];
+  for (let i = 0; i < items.length; i += concurrency) {
+    const batch = items.slice(i, i + concurrency);
+    const settled = await Promise.allSettled(batch.map(fn));
+    results.push(...settled);
+  }
+  return results;
+}
+
+/** 計時器 */
+export function timer() {
+  const start = performance.now();
+  return () => ((performance.now() - start) / 1000).toFixed(2);
+}
+
+/**
+ * JSON 結構化成功輸出
+ *
+ * 統一 schema（Agentic AI 友善）：
+ *   { ok: true, data: {...}, meta: { tool, version, command, duration_ms, timestamp } }
+ *
+ * @param {string} command   - 指令名稱（如 'doc ingest'）
+ * @param {object} data      - 指令回傳的結構化資料
+ * @param {string} elapsed   - 耗時秒數字串（由 timer() 產生）
+ * @returns {string}         - JSON 字串（含尾換行）
+ */
+export function jsonOut(command, data, elapsed) {
+  const duration_ms = Math.round(parseFloat(elapsed) * 1000);
+  const meta = {
+    tool: 'bh',
+    version: VERSION,
+    command,
+    duration_ms,
+    elapsed_seconds: parseFloat(elapsed), // 向後相容
+    timestamp: new Date().toISOString(),
+  };
+  return JSON.stringify({ ok: true, data, meta }, null, 2) + '\n';
+}
+
+/**
+ * JSON 結構化錯誤輸出
+ *
+ * 統一 schema（Agentic AI 友善）：
+ *   { ok: false, error: string, code: number, meta: { tool, version, command, timestamp } }
+ *
+ * @param {string} command   - 指令名稱
+ * @param {string} message   - 錯誤訊息
+ * @param {number} [code=1]  - 錯誤代碼
+ * @returns {string}         - JSON 字串（含尾換行）
+ */
+export function jsonError(command, message, code = 1) {
+  const meta = {
+    tool: 'bh',
+    version: VERSION,
+    command,
+    timestamp: new Date().toISOString(),
+  };
+  return JSON.stringify({ ok: false, error: message, code, meta }) + '\n';
+}
+
+/** 統一錯誤輸出 */
+export function emitError(command, message, format) {
+  if (format === 'json') {
+    process.stderr.write(jsonError(command, message));
+  } else {
+    process.stderr.write(`${message}\n`);
+  }
+}
+
+export { VERSION, DOC_EXTS };