botrun-horse 1.0.0

package/README.md

@@ -0,0 +1 @@
+# official-letter

package/bin/bh.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+// bin/bh.mjs — botrun-horse CLI 總入口（路由分派）
+// 多專案架構：lib 放腦、projects 放料、bin/commands/ 放各指令群組
+//
+// 用法:
+//   node bin/bh.mjs <指令群組> [子指令] [選項]
+//   node --experimental-sqlite bin/bh.mjs <指令>  (需 SQLite 功能時)
+//
+// 所有指令皆支援 --project=<名稱>、--format=json、stdin pipe、--quiet、--print0
+
+import { setupHttpProxy } from '../lib/core/proxy.mjs';
+setupHttpProxy(); // 必須在所有 fetch 呼叫之前執行（含 @google/genai、Anthropic SDK）
+
+import { parseArgs, VERSION } from '../lib/core/cli-utils.mjs';
+import { COMMANDS } from './commands/schema.mjs';
+
+const { command, subcommand, flags, positionals } = parseArgs(process.argv);
+
+// ===== Help 快速路由 =====
+if (flags.help && !command) {
+  const { showHelp } = await import('./commands/help.mjs');
+  showHelp(flags); process.exit(0);
+}
+if (flags.help && command) {
+  const { showCommandHelp } = await import('./commands/help.mjs');
+  showCommandHelp(command); process.exit(0);
+}
+
+// ===== 指令路由 =====
+switch (command) {
+  case 'doc': {
+    const { cmdDocSplit, cmdDocText, cmdDocIngest } = await import('./commands/doc.mjs');
+    switch (subcommand) {
+      case 'split': await cmdDocSplit(positionals, flags); break;
+      case 'text': await cmdDocText(positionals, flags); break;
+      case 'ingest': await cmdDocIngest(positionals, flags); break;
+      default: {
+        const { showCommandHelp } = await import('./commands/help.mjs');
+        if (!subcommand) showCommandHelp('doc');
+        else { process.stderr.write(`doc: 未知子指令 ${subcommand}\n`); process.exit(1); }
+      }
+    }
+    break;
+  }
+
+  case 'writing': {
+    const { cmdWritingGenerate } = await import('./commands/writing.mjs');
+    switch (subcommand) {
+      case 'generate': await cmdWritingGenerate(flags); break;
+      default: {
+        const { showCommandHelp } = await import('./commands/help.mjs');
+        if (!subcommand) showCommandHelp('writing');
+        else { process.stderr.write(`writing: 未知子指令 ${subcommand}\n`); process.exit(1); }
+      }
+    }
+    break;
+  }
+
+  case 'gemini': {
+    const { cmdGeminiAsk } = await import('./commands/gemini.mjs');
+    switch (subcommand) {
+      case 'ask': await cmdGeminiAsk(positionals, flags); break;
+      default: {
+        const { showCommandHelp } = await import('./commands/help.mjs');
+        if (!subcommand) showCommandHelp('gemini');
+        else { process.stderr.write(`gemini: 未知子指令 ${subcommand}\n`); process.exit(1); }
+      }
+    }
+    break;
+  }
+
+  case 'nchc': {
+    const { cmdNchcAsk, cmdNchcAgent, cmdNchcCode, cmdNchcModels } = await import('./commands/nchc.mjs');
+    switch (subcommand) {
+      case 'ask': await cmdNchcAsk(positionals, flags); break;
+      case 'agent': await cmdNchcAgent(positionals, flags); break;
+      case 'code': await cmdNchcCode(positionals, flags); break;
+      case 'models': cmdNchcModels(flags); break;
+      default: {
+        const { showCommandHelp } = await import('./commands/help.mjs');
+        if (!subcommand) showCommandHelp('nchc');
+        else { process.stderr.write(`nchc: 未知子指令 ${subcommand}\n`); process.exit(1); }
+      }
+    }
+    break;
+  }
+
+  case 'openrouter': {
+    const { cmdOpenrouterAsk, cmdOpenrouterModels } = await import('./commands/openrouter.mjs');
+    switch (subcommand) {
+      case 'ask': await cmdOpenrouterAsk(positionals, flags); break;
+      case 'models': cmdOpenrouterModels(flags); break;
+      default: {
+        const { showCommandHelp } = await import('./commands/help.mjs');
+        if (!subcommand) showCommandHelp('openrouter');
+        else { process.stderr.write(`openrouter: 未知子指令 ${subcommand}\n`); process.exit(1); }
+      }
+    }
+    break;
+  }
+
+  case 'legal': {
+    const { cmdLegalAsk, cmdLegalCacheList, cmdLegalCacheStats } = await import('./commands/legal.mjs');
+    switch (subcommand) {
+      case 'ask': await cmdLegalAsk(positionals, flags); break;
+      case 'cache': {
+        // legal cache {list|stats}
+        const cacheSubcmd = positionals[0];
+        switch (cacheSubcmd) {
+          case 'list':  await cmdLegalCacheList(flags); break;
+          case 'stats': await cmdLegalCacheStats(flags); break;
+          default: {
+            process.stderr.write(`legal cache: 未知子指令 ${cacheSubcmd}（可用: list, stats）\n`);
+            process.exit(1);
+          }
+        }
+        break;
+      }
+      default: {
+        const { showCommandHelp } = await import('./commands/help.mjs');
+        if (!subcommand) showCommandHelp('legal');
+        else { process.stderr.write(`legal: 未知子指令 ${subcommand}\n`); process.exit(1); }
+      }
+    }
+    break;
+  }
+
+  case 'dag': {
+    const { cmdDag } = await import('./commands/dag-cmd.mjs');
+    await cmdDag(subcommand, flags);
+    break;
+  }
+
+  case 'search': {
+    const { cmdSearch } = await import('./commands/search.mjs');
+    await cmdSearch(subcommand, positionals, flags);
+    break;
+  }
+
+  case 'db': {
+    const { cmdDb } = await import('./commands/db-cmd.mjs');
+    await cmdDb(subcommand, flags);
+    break;
+  }
+
+  case 'commands': {
+    const format = flags.format || 'json';
+    if (format === 'json') {
+      process.stdout.write(JSON.stringify({
+        _meta: { tool: 'bh', version: VERSION, description: 'botrun-horse 多專案文件處理系統' },
+        commands: COMMANDS,
+      }, null, 2) + '\n');
+    } else {
+      process.stdout.write(`botrun-horse v${VERSION} — 可用指令:\n\n`);
+      for (const [name, cmd] of Object.entries(COMMANDS)) {
+        const sqlite = cmd.requires_sqlite ? ' [需 --experimental-sqlite]' : '';
+        process.stdout.write(`  ${name.padEnd(12)} ${cmd.description}${sqlite}\n`);
+      }
+      process.stdout.write(`\n各指令皆支援 --help、--format=json、--project=<名稱>、--quiet、--print0\n`);
+    }
+    break;
+  }
+
+  case 'prompt': {
+    const { cmdPrompt } = await import('./commands/prompt.mjs');
+    await cmdPrompt(subcommand, positionals, flags);
+    break;
+  }
+
+  case 'portal':
+    process.stdout.write('portal 模組尚在開發中\n');
+    break;
+
+  case 'ocr':
+    process.stdout.write('ocr 模組尚在開發中\n');
+    break;
+
+  case 'help':
+  case '--help':
+  case '-h':
+  case undefined: {
+    const { showHelp } = await import('./commands/help.mjs');
+    showHelp(flags);
+    break;
+  }
+
+  default: {
+    process.stderr.write(`未知指令: ${command}\n`);
+    const { showHelp } = await import('./commands/help.mjs');
+    showHelp();
+    process.exit(1);
+  }
+}

package/bin/commands/dag-cmd.mjs

@@ -0,0 +1,74 @@
+// bin/commands/dag-cmd.mjs — dag 指令群組（init / status / ready / list）
+import { timer, jsonOut, emitError } from '../../lib/core/cli-utils.mjs';
+
+export async function cmdDag(subcommand, flags) {
+  if (!subcommand) {
+    const { showCommandHelp } = await import('./help.mjs');
+    showCommandHelp('dag'); return;
+  }
+  const {
+    loadDag, loadState, saveState, initState,
+    getReady, formatStatus,
+  } = await import('../../lib/core/dag.mjs');
+  const format = flags.format || 'text';
+  const project = flags.project || 'nstc';
+
+  switch (subcommand) {
+    case 'init': {
+      const { documents } = loadDag(project);
+      const state = initState(documents);
+      saveState(state, project);
+      if (format === 'json') {
+        process.stdout.write(jsonOut('dag init', { initialized: documents.length, project }, timer()()));
+      } else {
+        process.stdout.write(`已初始化 ${documents.length} 個文件任務的狀態（專案：${project}）\n`);
+      }
+      break;
+    }
+    case 'status': {
+      const state = loadState(project);
+      if (!state) { emitError('dag status', `尚未初始化。請先執行: bh dag init --project=${project}`, format); process.exit(1); }
+      if (format === 'json') {
+        const all = Object.values(state);
+        const summary = {
+          total: all.length,
+          done: all.filter(t => t.status === 'done').length,
+          pending: all.filter(t => t.status === 'pending').length,
+          running: all.filter(t => t.status === 'running').length,
+          failed: all.filter(t => t.status === 'failed').length,
+        };
+        process.stdout.write(jsonOut('dag status', summary, timer()()));
+      } else {
+        process.stdout.write(formatStatus(state) + '\n');
+      }
+      break;
+    }
+    case 'ready': {
+      const state = loadState(project);
+      if (!state) { emitError('dag ready', `尚未初始化。請先執行: bh dag init --project=${project}`, format); process.exit(1); }
+      const ready = getReady(state);
+      if (format === 'json') {
+        process.stdout.write(jsonOut('dag ready', { count: ready.length, tasks: ready }, timer()()));
+      } else {
+        for (const t of ready) process.stdout.write(`${t.id}\t${t.type}\t${t.title}\n`);
+      }
+      break;
+    }
+    case 'list': {
+      const state = loadState(project);
+      if (!state) { emitError('dag list', `尚未初始化。請先執行: bh dag init --project=${project}`, format); process.exit(1); }
+      if (format === 'json') {
+        process.stdout.write(jsonOut('dag list', { count: Object.keys(state).length, tasks: Object.values(state) }, timer()()));
+      } else {
+        for (const t of Object.values(state)) {
+          const icon = { done: '✅', running: '🔄', pending: '⏳', failed: '❌' }[t.status] || '?';
+          process.stdout.write(`${icon}\t${t.id}\t${t.type}\t${t.title}\t${t.status}\n`);
+        }
+      }
+      break;
+    }
+    default:
+      emitError('dag', `未知子指令: ${subcommand}。可用: init, status, ready, list`, format);
+      process.exit(1);
+  }
+}

package/bin/commands/db-cmd.mjs

@@ -0,0 +1,73 @@
+// bin/commands/db-cmd.mjs — db 指令群組（stats / docs / pages）
+import * as paths from '../../lib/core/paths.mjs';
+import { timer, jsonOut, emitError } from '../../lib/core/cli-utils.mjs';
+
+export async function cmdDb(subcommand, flags) {
+  if (!subcommand) {
+    const { showCommandHelp } = await import('./help.mjs');
+    showCommandHelp('db'); return;
+  }
+  const { DocStore } = await import('../../lib/core/db.mjs');
+  const project = flags.project || 'nstc';
+  const dbPathVal = flags.db || paths.dbPath(project);
+  const format = flags.format || 'text';
+  const elapsed = timer();
+
+  const store = new DocStore(dbPathVal);
+  store.initSchema();
+
+  switch (subcommand) {
+    case 'stats': {
+      const s = store.stats();
+      if (format === 'json') {
+        process.stdout.write(jsonOut('db stats', s, elapsed()));
+      } else {
+        process.stdout.write(`========== DB 統計 ==========\n`);
+        process.stdout.write(`文件數: ${s.documents}\n`);
+        process.stdout.write(`頁面數: ${s.pages}\n`);
+        process.stdout.write(`總字元: ${s.totalChars.toLocaleString()}\n`);
+        process.stdout.write(`各類型:\n`);
+        for (const t of s.byType) process.stdout.write(`  ${t.doc_type}: ${t.count}\n`);
+        process.stdout.write(`============================\n`);
+      }
+      break;
+    }
+    case 'docs': {
+      const docs = store.db.prepare('SELECT * FROM documents ORDER BY id').all();
+      if (format === 'json') {
+        process.stdout.write(jsonOut('db docs', { count: docs.length, documents: docs }, elapsed()));
+      } else {
+        for (const d of docs) {
+          process.stdout.write(`${d.id}\t${d.doc_type || '-'}\t${d.total_pages}頁\t${d.filename}\t${d.title || '-'}\n`);
+        }
+      }
+      break;
+    }
+    case 'pages': {
+      const args = process.argv.slice(2);
+      const docId = args[2] && !args[2].startsWith('--') ? parseInt(args[2]) : null;
+      if (!docId) {
+        emitError('db pages', '請提供文件 ID: bh db pages <doc_id>', format);
+        process.exit(1);
+      }
+      const pages = store.getPages(docId);
+      if (pages.length === 0) {
+        emitError('db pages', `找不到 doc_id=${docId} 的頁面資料`, format);
+        process.exit(1);
+      }
+      if (format === 'json') {
+        process.stdout.write(jsonOut('db pages', { doc_id: docId, count: pages.length, pages }, elapsed()));
+      } else {
+        for (const p of pages) {
+          process.stdout.write(`${p.page_number}\t${p.char_count}字\t${p.source_file}:${p.source_page}\n`);
+        }
+      }
+      break;
+    }
+    default:
+      emitError('db', `未知子指令: ${subcommand}。可用: stats, docs, pages`, format);
+      process.exit(1);
+  }
+
+  store.close();
+}

package/bin/commands/doc.mjs

@@ -0,0 +1,185 @@
+// bin/commands/doc.mjs — doc 指令群組（split / text / ingest）
+import path from 'path';
+import * as paths from '../../lib/core/paths.mjs';
+import {
+  resolveFiles, parallelBatch, timer, jsonOut, emitError,
+} from '../../lib/core/cli-utils.mjs';
+
+export async function cmdDocSplit(positionals, flags) {
+  const elapsed = timer();
+  const format = flags.format || 'text';
+  const project = flags.project || 'nstc';
+  const { splitPdf } = await import('../../lib/doc/split.mjs');
+  const outdir = flags.outdir || path.join(paths.projectOutput(project), 'split');
+  const concurrency = parseInt(flags.concurrency) || 5;
+  const files = await resolveFiles(positionals, flags);
+
+  if (files.length === 0) {
+    emitError('doc split', '請提供 PDF 檔案路徑、--dir 或 stdin pipe', format);
+    process.exit(1);
+  }
+
+  let ok = 0, fail = 0;
+  const allPages = [];
+  const errors = [];
+
+  const results = await parallelBatch(files, concurrency, async (f) => {
+    const baseName = path.basename(f, '.pdf');
+    const pageDir = path.join(outdir, baseName);
+    const pages = await splitPdf(f, pageDir);
+    return { file: f, pages };
+  });
+
+  for (let i = 0; i < results.length; i++) {
+    const r = results[i];
+    const f = files[i];
+    if (r.status === 'fulfilled') {
+      ok++;
+      for (const p of r.value.pages) {
+        if (format === 'json') {
+          allPages.push({ file: path.basename(f), page: p.page, path: p.path });
+        } else {
+          process.stdout.write(`${p.page}\t${p.path}\t${path.basename(f)}\n`);
+        }
+      }
+    } else {
+      fail++;
+      errors.push({ file: path.basename(f), error: r.reason?.message });
+      if (format !== 'json') {
+        process.stderr.write(`FAIL\t${path.basename(f)}\t${r.reason?.message}\n`);
+      }
+    }
+  }
+
+  if (format === 'json') {
+    process.stdout.write(jsonOut('doc split', { ok, fail, total_pages: allPages.length, results: allPages, errors }, elapsed()));
+  } else {
+    if (!flags.quiet) process.stderr.write(`拆頁完成: ${ok} 成功, ${fail} 失敗 (${elapsed()}s)\n`);
+  }
+}
+
+export async function cmdDocText(positionals, flags) {
+  const elapsed = timer();
+  const format = flags.format || 'text';
+  const { extractAllPages, extractPage } = await import('../../lib/doc/pdf2text.mjs');
+  const files = await resolveFiles(positionals, flags);
+  const pageNum = flags.page ? parseInt(flags.page) : null;
+  const concurrency = parseInt(flags.concurrency) || 5;
+
+  if (files.length === 0) {
+    emitError('doc text', '請提供 PDF 檔案路徑、--dir 或 stdin pipe', format);
+    process.exit(1);
+  }
+
+  let ok = 0, fail = 0;
+
+  const results = await parallelBatch(files, concurrency, async (f) => {
+    const filename = path.basename(f);
+    if (pageNum) {
+      const result = await extractPage(f, pageNum);
+      return { filename, pages: [result] };
+    } else {
+      const pages = await extractAllPages(f);
+      return { filename, pages };
+    }
+  });
+
+  for (let i = 0; i < results.length; i++) {
+    const r = results[i];
+    if (r.status === 'fulfilled') {
+      ok++;
+      const { filename, pages } = r.value;
+      for (const p of pages) {
+        if (format === 'json') {
+          process.stdout.write(JSON.stringify({ file: filename, page: p.page, chars: p.text.length, text: p.text }) + '\n');
+        } else {
+          process.stdout.write(`### ${filename} 第 ${p.page} 頁 (${p.text.length} 字) ###\n${p.text}\n`);
+        }
+      }
+    } else {
+      fail++;
+      if (format !== 'json') {
+        process.stderr.write(`FAIL\t${path.basename(files[i])}\t${r.reason?.message}\n`);
+      }
+    }
+  }
+
+  if (!flags.quiet) {
+    process.stderr.write(format === 'json'
+      ? JSON.stringify({ _summary: { ok, fail, elapsed: elapsed() } }) + '\n'
+      : `轉文字完成: ${ok} 成功, ${fail} 失敗 (${elapsed()}s)\n`);
+  }
+}
+
+export async function cmdDocIngest(positionals, flags) {
+  const elapsed = timer();
+  const format = flags.format || 'text';
+  const project = flags.project || 'nstc';
+  const { ingestOne, ingestDir, ingestBatch } = await import('../../lib/doc/index.mjs');
+  const dbPathVal = flags.db || paths.dbPath(project);
+  const concurrency = parseInt(flags.concurrency) || 5;
+  const recursive = !!flags.recursive;
+  const force = !!flags.force;
+  const splitPdfFlag = !!flags['split-pdf'];
+
+  const splitDir = splitPdfFlag
+    ? (flags.splitdir || path.join(paths.projectOutput(project), 'split'))
+    : null;
+
+  const opts = { dbPath: dbPathVal, splitDir, force };
+
+  const dirsList = flags.dirs
+    ? flags.dirs.split(',').map(d => d.trim()).filter(Boolean)
+    : flags.dir
+      ? [flags.dir]
+      : null;
+
+  if (dirsList && dirsList.length > 0) {
+    const result = await ingestDir(dirsList, opts, concurrency, recursive);
+    if (format === 'json') {
+      process.stdout.write(jsonOut('doc ingest', {
+        ok: result.ok, fail: result.fail, skip: result.skip, results: result.results,
+      }, elapsed()));
+    } else {
+      if (!flags.quiet) process.stderr.write(
+        `匯入完成: ${result.ok} 成功, ${result.fail} 失敗, ${result.skip} 跳過 (${elapsed()}s)\n`
+      );
+    }
+    return;
+  }
+
+  const files = await resolveFiles(positionals, flags);
+  if (files.length === 0) {
+    emitError('doc ingest', '請提供檔案路徑、--dir、--dirs 或 stdin pipe', format);
+    process.exit(1);
+  }
+
+  if (files.length === 1) {
+    try {
+      const result = await ingestOne(files[0], opts);
+      const status = result.skipped ? 'SKIP' : 'OK';
+      if (format === 'json') {
+        process.stdout.write(jsonOut('doc ingest', {
+          ok: result.skipped ? 0 : 1, fail: 0, skip: result.skipped ? 1 : 0,
+          results: [{ file: path.basename(files[0]), docId: result.docId, pages: result.pages, status }],
+        }, elapsed()));
+      } else {
+        process.stdout.write(`${status}\t${path.basename(files[0])}\tdoc_id=${result.docId}\t${result.pages}頁\n`);
+      }
+    } catch (err) {
+      emitError('doc ingest', err.message, format);
+      process.exit(1);
+    }
+  } else {
+    const result = await ingestBatch(files, opts, concurrency);
+    if (format === 'json') {
+      process.stdout.write(jsonOut('doc ingest', {
+        ok: result.ok, fail: result.fail, skip: result.skip, results: result.results,
+      }, elapsed()));
+    } else {
+      if (!flags.quiet) process.stderr.write(
+        `匯入完成: ${result.ok} 成功, ${result.fail} 失敗, ${result.skip} 跳過 (${elapsed()}s)\n`
+      );
+    }
+  }
+}

package/bin/commands/gemini.mjs

@@ -0,0 +1,120 @@
+// bin/commands/gemini.mjs — gemini 指令群組（ask）
+import { timer, emitError, readStdin } from '../../lib/core/cli-utils.mjs';
+
+export async function cmdGeminiAsk(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('gemini ask', '請提供提問內容。用法: bh gemini ask "你的問題"', format);
+    process.exit(1);
+  }
+
+  const providerFlag = flags.provider || 'auto';
+  let provider;
+  if (providerFlag === 'auto') {
+    if (process.env.GOOGLE_CLOUD_PROJECT || flags['gcp-project']) {
+      provider = 'gemini';
+    } else if (process.env.GEMINI_API_KEY) {
+      provider = 'gemini-api';
+    } else {
+      emitError('gemini ask',
+        '無法自動偵測 LLM provider。請設定以下任一環境變數：\n' +
+        '  export GOOGLE_CLOUD_PROJECT=your-gcp-project  # Vertex AI\n' +
+        '  export GEMINI_API_KEY=your-api-key            # Direct API\n' +
+        '或使用 --provider=gemini-api / --provider=gemini 明確指定',
+        format);
+      process.exit(1);
+    }
+  } else {
+    provider = providerFlag;
+  }
+
+  const askParams = {
+    provider,
+    prompt: prompt.trim(),
+    systemInstruction: flags['system-prompt'] || undefined,
+    thinking: flags.thinking || 'MEDIUM',
+    grounding: !flags['no-grounding'],
+    urlContext: !flags['no-url-context'],
+    project: flags['gcp-project'] || undefined,
+    location: flags['gcp-location'] || undefined,
+  };
+
+  try {
+    if (flags['no-stream']) {
+      const { geminiAsk, formatTextOutput, formatJsonOutput } = await import('../../lib/flows/gemini-ask.mjs');
+      const result = await geminiAsk(askParams);
+      if (format === 'json') {
+        process.stdout.write(formatJsonOutput(result, 'gemini-3-flash-preview', elapsed()) + '\n');
+      } else {
+        process.stdout.write(formatTextOutput(result) + '\n');
+        const p = result.perf || {};
+        process.stderr.write(
+          `\n[gemini-3-flash-preview] thinking=${flags.thinking || 'MEDIUM'} ` +
+          `引證=${result.sources.length}筆 ` +
+          `${p.outputTokensPerSec || '?'}tok/s ` +
+          `${p.latencySec || '?'}s ` +
+          `(${result.usage.totalTokens}tok)\n`
+        );
+      }
+    } else {
+      const { geminiAskStream, formatJsonOutput } = await import('../../lib/flows/gemini-ask.mjs');
+      const stream = geminiAskStream(askParams);
+      let fullText = '';
+      let meta = null;
+      const isTTY = process.stderr.isTTY;
+      const t0 = performance.now();
+      let thinkingStarted = false;
+      let textStarted = false;
+
+      if (isTTY && !flags.quiet) process.stderr.write('\x1b[90m⏳ 等待 Gemini 回應中...\x1b[0m');
+
+      for await (const chunk of stream) {
+        const sec = ((performance.now() - t0) / 1000).toFixed(1);
+        if (chunk.type === 'thinking') {
+          if (!thinkingStarted && isTTY && !flags.quiet) {
+            process.stderr.write(`\r\x1b[K\x1b[90m💭 [${sec}s] 思考中...\x1b[0m\n`);
+            thinkingStarted = true;
+          }
+          if (format === 'text' && !flags.quiet) process.stderr.write(`\x1b[2m${chunk.text}\x1b[0m`);
+        } else if (chunk.type === 'text') {
+          if (!textStarted && isTTY && !flags.quiet) {
+            if (thinkingStarted) process.stderr.write('\n');
+            process.stderr.write(`\x1b[90m▶ [${sec}s] 串流回應中...\x1b[0m\n`);
+            textStarted = true;
+          }
+          if (format === 'text') process.stdout.write(chunk.text);
+          fullText += chunk.text;
+        } else if (chunk.type === 'metadata') {
+          meta = chunk;
+        }
+      }
+
+      if (format === 'json') {
+        const result = meta || {};
+        result.text = fullText;
+        process.stdout.write(formatJsonOutput(result, 'gemini-3-flash-preview', 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.domain}] ${src.uri}\n`);
+          }
+        }
+        const p = meta?.perf || {};
+        if (!flags.quiet) process.stderr.write(
+          `\n[gemini-3-flash-preview] thinking=${flags.thinking || 'MEDIUM'} ` +
+          `TTFT=${p.ttftSec ?? '?'}s 引證=${meta?.sources?.length || 0}筆 ` +
+          `${p.outputTokensPerSec || '?'}tok/s ${p.latencySec || '?'}s (${meta?.usage?.totalTokens || '?'}tok)\n`
+        );
+      }
+    }
+  } catch (err) {
+    emitError('gemini ask', err.message, format);
+    process.exit(1);
+  }
+}