botrun-horse 1.0.0

package/bin/commands/help.mjs

@@ -0,0 +1,109 @@
+// bin/commands/help.mjs — 說明輸出（showHelp / showCommandHelp）
+import { parseArgs, VERSION } from '../../lib/core/cli-utils.mjs';
+import { COMMANDS } from './schema.mjs';
+
+export function showCommandHelp(cmdName) {
+  const cmd = COMMANDS[cmdName];
+  if (!cmd) return;
+
+  const { flags } = parseArgs(process.argv);
+  if (flags.format === 'json') {
+    process.stdout.write(JSON.stringify({ _meta: { tool: 'bh', version: VERSION }, command: cmd }, null, 2) + '\n');
+    return;
+  }
+
+  const lines = [];
+  lines.push(`${cmd.name} — ${cmd.description}`);
+  lines.push('');
+  if (cmd.requires_sqlite) {
+    lines.push('注意: 需要 --experimental-sqlite flag');
+    lines.push('');
+  }
+  lines.push('用法:');
+  const prefix = cmd.requires_sqlite ? 'node --experimental-sqlite bin/bh.mjs' : 'node bin/bh.mjs';
+  if (cmd.subcommands) {
+    lines.push(`  ${prefix} ${cmd.name} <子指令> [選項]`);
+    lines.push('');
+    lines.push('子指令:');
+    for (const [sub, desc] of Object.entries(cmd.subcommands)) {
+      lines.push(`  ${sub.padEnd(20)} ${desc}`);
+    }
+  }
+  if (cmd.options && Object.keys(cmd.options).length > 0) {
+    lines.push('');
+    lines.push('選項:');
+    for (const [opt, info] of Object.entries(cmd.options)) {
+      const def = info.default !== undefined ? ` (預設: ${info.default})` : '';
+      lines.push(`  ${opt.padEnd(24)} ${info.description}${def}`);
+    }
+  }
+  if (cmd.examples) {
+    lines.push('');
+    lines.push('範例:');
+    for (const ex of cmd.examples) lines.push(`  ${ex}`);
+  }
+  lines.push('');
+  process.stdout.write(lines.join('\n') + '\n');
+}
+
+export function showHelp(flags = {}) {
+  if (flags.format === 'json') {
+    process.stdout.write(JSON.stringify({
+      _meta: { tool: 'bh', version: VERSION, description: 'botrun-horse 多專案文件處理系統' },
+      commands: COMMANDS,
+      global_options: {
+        '--help': '顯示說明',
+        '--project=<名稱>': '指定專案（預設: nstc）',
+        '--format=json|text': '輸出格式',
+        '--concurrency=N': '平行處理數量',
+        '--quiet': '靜默模式（不輸出進度到 stderr）',
+        '--print0': 'NUL 分隔路徑輸出（與 xargs -0 相容）',
+      },
+    }, null, 2) + '\n');
+    return;
+  }
+
+  process.stdout.write(`
+botrun-horse — 多專案文件處理系統 CLI v${VERSION}
+===================================================
+
+用法:
+  node bin/bh.mjs <指令群組> [子指令] [選項]
+  node --experimental-sqlite bin/bh.mjs <指令>    (SQLite 相關功能)
+
+指令群組:
+  doc <子指令>        文件處理 (split|text|ingest)
+  writing <子指令>    公文撰寫 (generate)
+  gemini <子指令>     Gemini AI 提問 (ask) — thinking + grounding + url context
+  nchc <子指令>       國網 GenAI 提問 (ask|agent|code|models) — Mistral 系列
+  dag <子指令>        DAG 依賴追蹤 (init|status|ready|list)
+  search <子指令>     全文檢索 (query) [需 --experimental-sqlite]
+  db <子指令>         資料庫管理 (stats|docs|pages) [需 --experimental-sqlite]
+  prompt [關鍵字]     提示詞管理（無參數=全列出，帶關鍵字=模糊搜尋）
+  portal <子指令>     智慧入口 (預留)
+  ocr <子指令>        OCR 辨識 (預留)
+  commands           所有指令的結構化 JSON schema
+
+共通選項:
+  --help             顯示說明
+  --project=<名稱>    指定專案（預設: nstc）
+  --format=json|text 輸出格式
+  --concurrency=N    平行處理數量
+  --quiet            靜默模式（不輸出進度到 stderr，GNU parallel 友善）
+  --print0           NUL 分隔路徑輸出（與 xargs -0 相容）
+
+組合範例:
+  # GNU parallel 批次處理
+  find . -name "*.pdf" -print0 | xargs -0 -P 8 node bin/bh.mjs doc text --quiet
+
+  # 文件處理（PDF + Office 全系列）
+  node --experimental-sqlite bin/bh.mjs doc ingest --dir=pdfs/ --project=nstc
+
+  # Gemini AI 提問
+  node bin/bh.mjs gemini ask "量子糾纏的原理是什麼？"
+  echo "解釋 AI" | node bin/bh.mjs gemini ask --format=json
+
+  # AI/LLM schema 探索
+  node bin/bh.mjs commands --format=json | jq 'keys'
+`);
+}

package/bin/commands/legal.mjs

@@ -0,0 +1,174 @@
+// bin/commands/legal.mjs — legal 指令群組（ask / cache / stats）
+//
+// 設計原則：
+//   - Unix pipe 友善：支援 stdin 輸入、stdout 輸出、--quiet 靜默模式
+//   - KISS：指令層只做 I/O 與格式化，業務邏輯委派至 lib/flows/legal-ask.mjs
+//   - DDD：projects/legal-cache/config.json 為薄殼配置層
+//
+// 用法：
+//   node --experimental-sqlite bin/bh.mjs legal ask "問題" [--project=legal-cache]
+//   node --experimental-sqlite bin/bh.mjs legal cache list [--project=legal-cache]
+//   node --experimental-sqlite bin/bh.mjs legal cache stats [--project=legal-cache]
+//   node --experimental-sqlite bin/bh.mjs legal cache clear [--project=legal-cache]
+
+import { timer, emitError, readStdin } from '../../lib/core/cli-utils.mjs';
+import { projectConfig as resolveConfigPath, dbPath as resolveDbPath } from '../../lib/core/paths.mjs';
+import fs from 'fs';
+
+// ── 輔助：載入專案 config.json ──────────────────────────────────────────────
+
+/**
+ * 讀取專案 config.json（不存在時回傳空物件）
+ * @param {string} project - 專案名稱
+ */
+function loadConfig(project) {
+  const cfgPath = resolveConfigPath(project);
+  if (!fs.existsSync(cfgPath)) return {};
+  try { return JSON.parse(fs.readFileSync(cfgPath, 'utf8')); } catch { return {}; }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * legal ask — 法律查詢（AI Router + 兩步驟提示工程 + SQLite 快取）
+ *
+ * @param {string[]} positionals - 位置參數（問題文字）
+ * @param {object} flags         - 解析後的旗標
+ */
+export async function cmdLegalAsk(positionals, flags) {
+  const elapsed = timer();
+  const format = flags.format || 'text';
+  const project = flags.project || 'legal-cache';
+
+  // ── 讀取問題（positionals 或 stdin pipe）──
+  let question = positionals.join(' ');
+  if (!question || question === '-') question = await readStdin();
+  if (!question || !question.trim()) {
+    emitError('legal ask', '請提供法律問題。用法: bh legal ask "房東可以隨意趕走我嗎？"', format);
+    process.exit(1);
+  }
+
+  // ── 讀取專案配置 ──
+  const config = loadConfig(project);
+
+  if (!flags.quiet) {
+    process.stderr.write(`\x1b[90m⏳ 法律查詢中（專案: ${project}）...\x1b[0m\n`);
+  }
+
+  try {
+    const { legalAsk, formatLegalResult, formatLegalResultJson } = await import('../../lib/flows/legal-ask.mjs');
+
+    const result = await legalAsk({
+      question: question.trim(),
+      project,
+      config,
+      skipCache: !!flags['skip-cache'],
+      skipSave: !!flags['skip-save'],
+    });
+
+    if (format === 'json') {
+      process.stdout.write(formatLegalResultJson(result) + '\n');
+    } else {
+      process.stdout.write(formatLegalResult(result) + '\n');
+    }
+
+    if (!flags.quiet) {
+      const fromCache = result.fromCache ? '✓ 快取命中' : '→ 大模型搜尋';
+      process.stderr.write(
+        `\n[${fromCache}] 總耗時=${result.perf.totalMs}ms 標籤=${result.tags.join('、')}\n`
+      );
+    }
+  } catch (err) {
+    emitError('legal ask', err.message, format);
+    process.exit(1);
+  }
+}
+
+/**
+ * legal cache list — 列出快取問答
+ * @param {object} flags
+ */
+export async function cmdLegalCacheList(flags) {
+  const format = flags.format || 'text';
+  const project = flags.project || 'legal-cache';
+  const limit = flags.limit ? parseInt(flags.limit) : 20;
+
+  try {
+    const { AiCache } = await import('../../lib/core/ai-cache.mjs');
+    const dbPath = resolveDbPath(project);
+
+    if (!fs.existsSync(dbPath)) {
+      process.stdout.write('快取資料庫尚未建立（尚無快取問答）\n');
+      return;
+    }
+
+    const cache = new AiCache(dbPath);
+    cache.initSchema();
+    const entries = cache.listAll(limit);
+    cache.close();
+
+    if (format === 'json') {
+      process.stdout.write(JSON.stringify({ entries }, null, 2) + '\n');
+    } else {
+      if (entries.length === 0) {
+        process.stdout.write('快取為空（尚無問答紀錄）\n');
+        return;
+      }
+      process.stdout.write(`快取問答列表（最近 ${entries.length} 筆）：\n\n`);
+      for (const e of entries) {
+        process.stdout.write(
+          `  [${String(e.id).padStart(4)}] 命中=${e.hitCount} 標籤=[${e.tags.join('、')}]\n` +
+          `         問題：${e.question.slice(0, 60)}\n`
+        );
+      }
+    }
+  } catch (err) {
+    emitError('legal cache list', err.message, format);
+    process.exit(1);
+  }
+}
+
+/**
+ * legal cache stats — 顯示快取統計
+ * @param {object} flags
+ */
+export async function cmdLegalCacheStats(flags) {
+  const format = flags.format || 'text';
+  const project = flags.project || 'legal-cache';
+
+  try {
+    const { AiCache } = await import('../../lib/core/ai-cache.mjs');
+    const dbPath = resolveDbPath(project);
+
+    if (!fs.existsSync(dbPath)) {
+      process.stdout.write('快取資料庫尚未建立\n');
+      return;
+    }
+
+    const cache = new AiCache(dbPath);
+    cache.initSchema();
+    const stats = cache.stats();
+    cache.close();
+
+    if (format === 'json') {
+      process.stdout.write(JSON.stringify(stats, null, 2) + '\n');
+    } else {
+      process.stdout.write('── 法律快取統計 ──────────────────────────────\n');
+      process.stdout.write(`  已快取問答：${stats.cachedQuestions} 筆\n`);
+      process.stdout.write(`  總快取命中：${stats.totalCacheHits} 次\n`);
+      process.stdout.write('\n  路由決策分布：\n');
+      for (const d of stats.routerDecisions) {
+        process.stdout.write(`    ${d.decision}: ${d.count} 次\n`);
+      }
+      if (stats.topHitQuestions.length > 0) {
+        process.stdout.write('\n  最常命中問題（Top 5）：\n');
+        for (const q of stats.topHitQuestions) {
+          process.stdout.write(`    [命中 ${q.hit_count} 次] ${q.question.slice(0, 50)}\n`);
+        }
+      }
+    }
+  } catch (err) {
+    emitError('legal cache stats', err.message, format);
+    process.exit(1);
+  }
+}

package/bin/commands/nchc.mjs

@@ -0,0 +1,212 @@
+// bin/commands/nchc.mjs — nchc 指令群組（ask / agent / code / models）
+import { timer, emitError, readStdin } from '../../lib/core/cli-utils.mjs';
+
+export async function cmdNchcAsk(positionals, flags) {
+  const elapsed = timer();
+  const format = flags.format || 'text';
+
+  let prompt = positionals.join(' ');
+  if (!prompt || prompt === '-') prompt = await readStdin();
+  if (!prompt || !prompt.trim()) {
+    emitError('nchc ask', '請提供提問內容。用法: bh nchc ask "你的問題"', format);
+    process.exit(1);
+  }
+
+  const { NchcAdapter } = await import('../../lib/core/adapters/nchc.mjs');
+  const adapter = new NchcAdapter({
+    model: flags.model || 'Mistral-Large-3-675B-Instruct-2512',
+    maxTokens: parseInt(flags['max-tokens']) || 8192,
+    temperature: parseFloat(flags.temperature) ?? 0.7,
+  });
+
+  const askParams = { prompt: prompt.trim(), systemInstruction: flags['system-prompt'] || undefined };
+
+  try {
+    if (flags['no-stream']) {
+      const result = await adapter.generateContent(askParams);
+      if (format === 'json') {
+        process.stdout.write(JSON.stringify({
+          _meta: { command: 'nchc ask', model: result.model, elapsed: elapsed() },
+          text: result.text, usage: result.usage, perf: result.perf,
+        }, null, 2) + '\n');
+      } else {
+        process.stdout.write(result.text + '\n');
+        if (!flags.quiet) process.stderr.write(
+          `\n[${result.model || adapter.model}] ${result.perf?.outputTokensPerSec || '?'}tok/s ` +
+          `${result.perf?.latencySec || '?'}s (${result.usage?.totalTokens || '?'}tok)\n`
+        );
+      }
+    } else {
+      const stream = adapter.generateContentStream(askParams);
+      let meta = null;
+      const isTTY = process.stderr.isTTY;
+      const t0 = performance.now();
+      let textStarted = false;
+
+      if (isTTY && !flags.quiet) process.stderr.write('\x1b[90m⏳ 等待國網 GenAI 回應中...\x1b[0m');
+
+      for await (const chunk of stream) {
+        const sec = ((performance.now() - t0) / 1000).toFixed(1);
+        if (chunk.type === 'text') {
+          if (!textStarted && isTTY && !flags.quiet) {
+            process.stderr.write(`\r\x1b[K\x1b[90m▶ [${sec}s] 串流回應中...\x1b[0m\n`);
+            textStarted = true;
+          }
+          if (format === 'text') process.stdout.write(chunk.text);
+        } else if (chunk.type === 'metadata') {
+          meta = chunk;
+        }
+      }
+
+      if (format === 'json') {
+        const result = meta || {};
+        process.stdout.write(JSON.stringify({
+          _meta: { command: 'nchc ask', model: result.model || adapter.model, elapsed: elapsed() },
+          text: result.text, usage: result.usage, perf: result.perf,
+        }, null, 2) + '\n');
+      } else {
+        process.stdout.write('\n');
+        const p = meta?.perf || {};
+        if (!flags.quiet) process.stderr.write(
+          `\n[${meta?.model || adapter.model}] TTFT=${p.ttftSec ?? '?'}s ` +
+          `${p.outputTokensPerSec || '?'}tok/s ${p.latencySec || '?'}s\n`
+        );
+      }
+    }
+  } catch (err) {
+    emitError('nchc ask', err.message, format);
+    process.exit(1);
+  }
+}
+
+export async function cmdNchcAgent(positionals, flags) {
+  const format = flags.format || 'text';
+
+  let task = positionals.join(' ');
+  if (!task || task === '-') task = await readStdin();
+  if (!task || !task.trim()) {
+    emitError('nchc agent', '請提供任務描述。用法: bh nchc agent "你的任務"', format);
+    process.exit(1);
+  }
+
+  const { NchcAgent } = await import('../../lib/flows/openai-agent.mjs');
+  const agent = new NchcAgent({
+    model: flags.model || 'Mistral-Large-3-675B-Instruct-2512',
+    maxTurns: parseInt(flags['max-turns']) || 20,
+    systemPrompt: flags['system-prompt'] || undefined,
+    cwd: process.cwd(),
+  });
+
+  const isTTY = process.stderr.isTTY;
+
+  try {
+    if (isTTY && !flags.quiet) process.stderr.write(`\x1b[90m🤖 [nchc agent] 啟動代理任務...\x1b[0m\n`);
+
+    for await (const event of agent.run(task.trim())) {
+      if (event.type === 'tool_call') {
+        if (format === 'text' && isTTY && !flags.quiet) {
+          process.stderr.write(`\x1b[33m🔧 [工具呼叫] ${event.name}(${JSON.stringify(event.args)})\x1b[0m\n`);
+        } else if (format === 'json') {
+          process.stdout.write(JSON.stringify({ event: 'tool_call', name: event.name, args: event.args }) + '\n');
+        }
+      } else if (event.type === 'tool_result') {
+        if (format === 'text' && isTTY && !flags.quiet) {
+          const preview = event.result.length > 120 ? event.result.slice(0, 120) + '...' : event.result;
+          process.stderr.write(`\x1b[32m✅ [工具結果] ${event.name}: ${preview}\x1b[0m\n`);
+        } else if (format === 'json') {
+          process.stdout.write(JSON.stringify({ event: 'tool_result', name: event.name, result: event.result }) + '\n');
+        }
+      } else if (event.type === 'text') {
+        if (format === 'text') {
+          if (isTTY && !flags.quiet) process.stderr.write('\x1b[90m▶ 最終回應：\x1b[0m\n');
+          process.stdout.write(event.text + '\n');
+        }
+      } else if (event.type === 'done') {
+        const turns = event.turns;
+        if (format === 'json') {
+          process.stdout.write(JSON.stringify({
+            _meta: { command: 'nchc agent', model: agent.model, turns },
+            text: event.text,
+          }, null, 2) + '\n');
+        } else if (isTTY && !flags.quiet) {
+          process.stderr.write(`\x1b[90m[完成] ${turns} 輪對話\x1b[0m\n`);
+        }
+      }
+    }
+  } catch (err) {
+    emitError('nchc agent', err.message, format);
+    process.exit(1);
+  }
+}
+
+export async function cmdNchcCode(positionals, flags) {
+  const format = flags.format || 'text';
+
+  let task = positionals.join(' ');
+  if (!task || task === '-') task = await readStdin();
+  if (!task || !task.trim()) {
+    emitError('nchc code', '請提供任務描述。用法: bh nchc code "你的 coding 任務"', format);
+    process.exit(1);
+  }
+
+  const { OpencodeAgent } = await import('../../lib/flows/opencode-agent.mjs');
+  const agent = new OpencodeAgent({
+    modelID: flags.model || 'Mistral-Large-3-675B-Instruct-2512',
+    serverUrl: flags['server-url'] || undefined,
+    port: parseInt(flags.port) || 14096,
+    cwd: process.cwd(),
+  });
+
+  const isTTY = process.stderr.isTTY;
+
+  try {
+    if (isTTY && !flags.quiet) process.stderr.write(`\x1b[90m🤖 [nchc code] 啟動 OpenCode Agentic Coding...\x1b[0m\n`);
+
+    let finalText = '';
+
+    for await (const event of agent.run(task.trim())) {
+      if (event.type === 'session_created') {
+        if (isTTY && !flags.quiet) process.stderr.write(`\x1b[90m📋 [Session] ${event.sessionID}\x1b[0m\n`);
+        else if (format === 'json') process.stdout.write(JSON.stringify({ event: 'session_created', sessionID: event.sessionID }) + '\n');
+      } else if (event.type === 'delta') {
+        if (format === 'text') process.stdout.write(event.text);
+      } else if (event.type === 'text') {
+        finalText = event.text;
+        if (format === 'text' && !finalText.endsWith('\n')) process.stdout.write('\n');
+      } else if (event.type === 'done') {
+        if (format === 'json') {
+          process.stdout.write(JSON.stringify({
+            _meta: { command: 'nchc code', model: agent.modelID, timedOut: event.timedOut },
+            text: event.text,
+          }, null, 2) + '\n');
+        } else if (isTTY && !flags.quiet) {
+          process.stderr.write(`\x1b[90m${event.timedOut ? '⚠️ 逾時' : '✅ 完成'}\x1b[0m\n`);
+        }
+      }
+    }
+  } catch (err) {
+    if (err.message.includes('opencode') || err.message.includes('spawn')) {
+      emitError('nchc code', `OpenCode CLI 未安裝或無法啟動。\n請執行：npm install -g opencode-ai\n原始錯誤：${err.message}`, format);
+    } else {
+      emitError('nchc code', err.message, format);
+    }
+    process.exit(1);
+  }
+}
+
+export function cmdNchcModels(flags) {
+  const format = flags.format || 'text';
+  const models = [
+    { id: 'Mistral-Large-3-675B-Instruct-2512', description: '最強旗艦模型（675B），適合複雜分析、長文生成' },
+    { id: 'Devstral-2-123B-Instruct-2512', description: '程式碼專精模型（123B），適合程式生成、技術文件' },
+    { id: 'Ministral-3-14B-Instruct-2512', description: '輕量快速模型（14B），適合簡單問答、快速測試' },
+  ];
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify({ models }, null, 2) + '\n');
+  } else {
+    process.stdout.write('國網 GenAI 可用模型:\n\n');
+    for (const m of models) process.stdout.write(`  ${m.id}\n    ${m.description}\n\n`);
+    process.stdout.write('環境變數: NCHC_GENAI_API_KEY\n');
+    process.stdout.write('端點: https://portal.genai.nchc.org.tw/api/v1\n');
+  }
+}

package/bin/commands/openrouter.mjs

@@ -0,0 +1,154 @@
+// bin/commands/openrouter.mjs — openrouter 指令群組（ask / models）
+//
+// 設計原則：
+//   - Unix pipe 友善：支援 stdin 輸入、stdout 輸出、--quiet 靜默模式
+//   - GNU parallel 友善：--quiet 關閉 stderr 進度、--format=json 結構化輸出
+//   - Agentic AI 友善：--format=json 回傳結構化 LlmResponse（含 sources、usage、perf）
+//   - KISS：指令層只做 I/O 與格式化，業務邏輯委派至 adapter
+
+import { timer, emitError, readStdin } from '../../lib/core/cli-utils.mjs';
+
+/**
+ * openrouter ask — 向 OpenRouter 任意模型提問
+ * 支援網路搜尋（--web-search）、串流（預設）、JSON 輸出
+ *
+ * @param {string[]} positionals - 命令列位置參數（提問文字）
+ * @param {object} flags         - 解析後的旗標
+ */
+export async function cmdOpenrouterAsk(positionals, flags) {
+  const elapsed = timer();
+  const format = flags.format || 'text';
+
+  // ── 讀取提問（positionals 或 stdin pipe）──
+  let prompt = positionals.join(' ');
+  if (!prompt || prompt === '-') prompt = await readStdin();
+  if (!prompt || !prompt.trim()) {
+    emitError('openrouter ask', '請提供提問內容。用法: bh openrouter ask "你的問題"', format);
+    process.exit(1);
+  }
+
+  // ── 組裝 adapter（直接使用，不經 createLLM factory，保留完整選項控制）──
+  const { OpenRouterAdapter } = await import('../../lib/core/adapters/openrouter.mjs');
+  const adapter = new OpenRouterAdapter({
+    model:        flags.model || undefined,               // 預設由 adapter DEFAULTS 決定
+    maxTokens:    flags['max-tokens'] ? parseInt(flags['max-tokens']) : undefined,
+    temperature:  flags.temperature   ? parseFloat(flags.temperature) : undefined,
+    webSearch:    !!flags['web-search'],
+    maxResults:   flags['max-results'] ? parseInt(flags['max-results']) : undefined,
+  });
+
+  const askParams = {
+    prompt: prompt.trim(),
+    systemInstruction: flags['system-prompt'] || undefined,
+  };
+
+  try {
+    if (flags['no-stream']) {
+      // ── 非串流模式：等待完整回應 ──
+      const result = await adapter.generateContent(askParams);
+      if (format === 'json') {
+        const { formatJsonOutput } = await import('../../lib/flows/openrouter-ask.mjs');
+        process.stdout.write(formatJsonOutput(result, adapter.model, elapsed()) + '\n');
+      } else {
+        const { formatTextOutput } = await import('../../lib/flows/openrouter-ask.mjs');
+        process.stdout.write(formatTextOutput(result) + '\n');
+        if (!flags.quiet) {
+          const p = result.perf || {};
+          process.stderr.write(
+            `\n[${result.model}] 引證=${result.sources.length}筆 ` +
+            `${p.outputTokensPerSec || '?'}tok/s ${p.latencySec || '?'}s (${result.usage.totalTokens}tok)\n`
+          );
+        }
+      }
+    } else {
+      // ── 串流模式：即時輸出（預設）──
+      const stream = adapter.generateContentStream(askParams);
+      let meta = null;
+      const isTTY = process.stderr.isTTY;
+      const t0 = performance.now();
+      let textStarted = false;
+
+      if (isTTY && !flags.quiet) {
+        process.stderr.write(`\x1b[90m⏳ [${adapter.model}] 等待回應中...\x1b[0m`);
+      }
+
+      for await (const chunk of stream) {
+        const sec = ((performance.now() - t0) / 1000).toFixed(1);
+        if (chunk.type === 'text') {
+          if (!textStarted && isTTY && !flags.quiet) {
+            process.stderr.write(`\r\x1b[K\x1b[90m▶ [${sec}s] 串流回應中...\x1b[0m\n`);
+            textStarted = true;
+          }
+          if (format === 'text') process.stdout.write(chunk.text);
+        } else if (chunk.type === 'metadata') {
+          meta = chunk;
+        }
+      }
+
+      if (format === 'json') {
+        const { formatJsonOutput } = await import('../../lib/flows/openrouter-ask.mjs');
+        process.stdout.write(formatJsonOutput(meta || {}, adapter.model, elapsed()) + '\n');
+      } else {
+        process.stdout.write('\n');
+        // 引證來源（網路搜尋時）
+        if (meta?.sources?.length > 0) {
+          process.stdout.write('\n--- 引證來源 ---\n');
+          for (const src of meta.sources) {
+            process.stdout.write(`  [${src.title || src.uri}] ${src.uri}\n`);
+          }
+        }
+        if (!flags.quiet) {
+          const p = meta?.perf || {};
+          process.stderr.write(
+            `\n[${meta?.model || adapter.model}] 引證=${meta?.sources?.length || 0}筆 ` +
+            `TTFT=${p.ttftSec ?? '?'}s ${p.outputTokensPerSec || '?'}tok/s ` +
+            `${p.latencySec || '?'}s (${meta?.usage?.totalTokens || '?'}tok)\n`
+          );
+        }
+      }
+    }
+  } catch (err) {
+    emitError('openrouter ask', err.message, format);
+    process.exit(1);
+  }
+}
+
+/**
+ * openrouter models — 列出常用 OpenRouter 模型（供參考）
+ * OpenRouter 支援 400+ 模型，此處僅列出常用代表性型號
+ *
+ * @param {object} flags
+ */
+export function cmdOpenrouterModels(flags) {
+  const format = flags.format || 'text';
+  const models = [
+    // OpenAI 系列
+    { id: 'openai/gpt-4o',            description: 'GPT-4o（旗艦，多模態）' },
+    { id: 'openai/gpt-4o-mini',       description: 'GPT-4o Mini（輕量快速，預設）' },
+    { id: 'openai/o3-mini',           description: 'o3-mini（推理專精）' },
+    // Anthropic 系列
+    { id: 'anthropic/claude-opus-4',  description: 'Claude Opus 4（最強推理）' },
+    { id: 'anthropic/claude-sonnet-4-6', description: 'Claude Sonnet 4.6（平衡）' },
+    // Google 系列
+    { id: 'google/gemini-2.5-pro',    description: 'Gemini 2.5 Pro（長文脈）' },
+    { id: 'google/gemini-2.0-flash-001', description: 'Gemini 2.0 Flash（快速）' },
+    // Meta 系列
+    { id: 'meta-llama/llama-3.3-70b-instruct', description: 'Llama 3.3 70B（開源最強）' },
+    // 網路搜尋模型（:online 後綴）
+    { id: 'openai/gpt-4o:online',     description: 'GPT-4o + 網路搜尋（Exa）' },
+    { id: 'perplexity/sonar-pro',     description: 'Perplexity Sonar Pro（原生網路搜尋）' },
+  ];
+
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify({ models }, null, 2) + '\n');
+  } else {
+    process.stdout.write('OpenRouter 常用模型（完整列表：https://openrouter.ai/models）:\n\n');
+    for (const m of models) {
+      process.stdout.write(`  ${m.id.padEnd(48)} ${m.description}\n`);
+    }
+    process.stdout.write('\n提示：任何 model 名稱加上 :online 後綴可啟用網路搜尋\n');
+    process.stdout.write('提示：使用 --web-search 旗標透過 plugins 啟用 Exa 搜尋（適用所有模型）\n');
+    process.stdout.write('\n環境變數: OPENROUTER_API_KEY\n');
+    process.stdout.write('端點: https://openrouter.ai/api/v1\n');
+  }
+}