botrun-horse 1.0.0

package/lib/core/adapters/gemini-api.mjs

@@ -0,0 +1,174 @@
+// lib/core/adapters/gemini-api.mjs — Gemini 直接 API adapter（API Key 模式）
+//
+// 與 gemini-vertex.mjs 的差異：
+//   - 驗證方式：GEMINI_API_KEY（非 Vertex AI ADC）
+//   - 端點：generativelanguage.googleapis.com（非 aiplatform.googleapis.com）
+//   - 適用場景：無 GCP ADC 的容器環境、本機開發、CI
+//
+// 能力對等（與 Vertex AI 相同）：
+//   - Google Search grounding（googleSearch: {}）→ 引證 URL
+//   - URL Context 擷取（urlContext: {}）
+//   - Thinking（thinkingLevel: MEDIUM）— Direct API 也支援相同列舉
+//   - Streaming
+//
+// 介面設計：完全相容 GeminiVertexAdapter（SOLID LSP）
+// Proxy 相容：依賴 proxy.mjs 的全局 dispatcher，不自行建立 HTTP client
+
+import { GoogleGenAI } from '@google/genai';
+import { parseGeminiResponse, calcPerf, resolveRedirectUrls } from './gemini-shared.mjs';
+import { BaseAdapter } from './base.mjs';
+
+/** 預設設定常數（與 Vertex AI adapter 對等） */
+const DEFAULTS = {
+  model: 'gemini-3-flash-preview',
+  thinkingLevel: 'MEDIUM',
+  includeThoughts: true,
+  grounding: true,
+  urlContext: true,
+  maxOutputTokens: 8192,
+  temperature: 1.0,
+};
+
+/**
+ * Gemini 直接 API Adapter（API Key 模式）
+ * 遵循 SOLID SRP：單一職責 — 封裝直接 Gemini API（非 Vertex AI）呼叫
+ *
+ * Direct API 的 thinkingConfig 與 Vertex AI 相同（thinkingLevel 列舉）：
+ *   NONE / MINIMAL / LOW / MEDIUM / HIGH
+ */
+export class GeminiApiAdapter extends BaseAdapter {
+  /**
+   * @param {object} opts
+   * @param {string} [opts.apiKey] - Gemini API Key（預設讀 GEMINI_API_KEY）
+   * @param {string} [opts.thinkingLevel='MEDIUM'] - 思考等級（NONE|MINIMAL|LOW|MEDIUM|HIGH）
+   * @param {boolean} [opts.grounding=true] - 啟用 Google Search 接地（引證 URL）
+   * @param {boolean} [opts.urlContext=true] - 啟用 URL 內容擷取
+   * @param {boolean} [opts.includeThoughts=true] - 回傳思考摘要
+   */
+  constructor(opts = {}) {
+    super();
+    const apiKey = opts.apiKey || process.env.GEMINI_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        'GeminiApiAdapter: 需要 Gemini API Key。\n' +
+        '請設定環境變數 GEMINI_API_KEY 或傳入 apiKey 參數。'
+      );
+    }
+
+    this.ai = new GoogleGenAI({ apiKey });
+    this.model = DEFAULTS.model;
+    this.thinkingLevel = (opts.thinkingLevel || DEFAULTS.thinkingLevel).toUpperCase();
+    this.includeThoughts = opts.includeThoughts ?? DEFAULTS.includeThoughts;
+    this.grounding = opts.grounding ?? DEFAULTS.grounding;
+    this.urlContext = opts.urlContext ?? DEFAULTS.urlContext;
+    this.maxOutputTokens = opts.maxOutputTokens || DEFAULTS.maxOutputTokens;
+    this.temperature = opts.temperature ?? DEFAULTS.temperature;
+  }
+
+  /**
+   * 建構 tools 陣列
+   * Direct API 工具名稱與 Vertex AI 相同（SDK 統一處理 camelCase）
+   */
+  _buildTools() {
+    const tools = [];
+    if (this.grounding) tools.push({ googleSearch: {} });
+    if (this.urlContext) tools.push({ urlContext: {} });
+    return tools;
+  }
+
+  /** 建構共用 generateContent config */
+  _buildConfig(systemInstruction) {
+    const config = {
+      // Direct API（gemini-3 系列）與 Vertex AI 同樣使用 thinkingLevel 列舉
+      thinkingConfig: {
+        thinkingLevel: this.thinkingLevel,
+        includeThoughts: this.includeThoughts,
+      },
+      tools: this._buildTools(),
+      maxOutputTokens: this.maxOutputTokens,
+      temperature: this.temperature,
+    };
+    if (systemInstruction) config.systemInstruction = systemInstruction;
+    return config;
+  }
+
+  /**
+   * 向 Gemini 提問（非串流）
+   * @param {object} params
+   * @param {string} params.prompt - 使用者提問
+   * @param {string} [params.systemInstruction] - 系統指示
+   * @returns {Promise<object>} 結構化回應（含 sources 引證 + perf 效能）
+   */
+  async generateContent({ prompt, systemInstruction }) {
+    const t0 = performance.now();
+    const response = await this.ai.models.generateContent({
+      model: this.model,
+      contents: prompt,
+      config: this._buildConfig(systemInstruction),
+    });
+    const latencyMs = performance.now() - t0;
+
+    const result = parseGeminiResponse(response);
+    if (result.sources.length > 0) {
+      result.sources = await resolveRedirectUrls(result.sources);
+    }
+    result.perf = calcPerf(result.usage, latencyMs, result.text);
+    return result;
+  }
+
+  /**
+   * 串流向 Gemini 提問（AsyncGenerator）
+   * yield { type: 'thinking', text } — 思考過程（即時串流）
+   * yield { type: 'text', text }    — 回應文字（即時串流）
+   * yield { type: 'metadata', ...result } — 最終 grounding 引證 + 效能指標
+   */
+  async *generateContentStream({ prompt, systemInstruction }) {
+    const t0 = performance.now();
+    const DBG = process.env.BH_DEBUG === '1';
+
+    if (DBG) {
+      process.stderr.write(`[DBG][gemini-api] model=${this.model} thinkingLevel=${this.thinkingLevel} grounding=${this.grounding} urlContext=${this.urlContext}\n`);
+    }
+
+    const streamResponse = await this.ai.models.generateContentStream({
+      model: this.model,
+      contents: prompt,
+      config: this._buildConfig(systemInstruction),
+    });
+
+    const stream = streamResponse[Symbol.asyncIterator]
+      ? streamResponse
+      : streamResponse.stream || streamResponse;
+
+    let ttftMs = 0;
+    let isFirst = true;
+    let lastChunk = null;
+    let fullText = '';
+
+    for await (const chunk of stream) {
+      if (isFirst) { ttftMs = performance.now() - t0; isFirst = false; }
+      lastChunk = chunk;
+
+      for (const part of chunk.candidates?.[0]?.content?.parts || []) {
+        if (part.thought) {
+          yield { type: 'thinking', text: part.text };
+        } else if (part.text) {
+          fullText += part.text;
+          yield { type: 'text', text: part.text };
+        }
+      }
+    }
+
+    const latencyMs = performance.now() - t0;
+    if (lastChunk) {
+      const result = parseGeminiResponse(lastChunk);
+      // 補回串流累積的完整文字（最後一個 chunk 可能不含完整文字）
+      if (!result.text && fullText) result.text = fullText;
+      if (result.sources.length > 0) {
+        result.sources = await resolveRedirectUrls(result.sources);
+      }
+      result.perf = calcPerf(result.usage, latencyMs, result.text, ttftMs);
+      yield { type: 'metadata', ...result };
+    }
+  }
+}

package/lib/core/adapters/gemini-shared.mjs

@@ -0,0 +1,164 @@
+// lib/core/adapters/gemini-shared.mjs — Gemini adapter 共用純函式
+//
+// DRY：被 gemini-vertex.mjs 和 gemini-api.mjs 共同使用
+// 原則：SOLID SRP — 純函式，無副作用，無狀態
+
+/**
+ * 平行解析 grounding redirect URL → 真實 URL
+ * 不跟隨 redirect，只讀 Location header（高效：1 次 HEAD request）
+ * @param {Array<{uri: string}>} sources - grounding 來源陣列
+ * @param {number} [timeoutMs=5000] - 每個請求的超時時間(ms)
+ * @returns {Promise<Array>} 解析後的來源陣列
+ */
+export async function resolveRedirectUrls(sources, timeoutMs = 5000) {
+  const tasks = sources.map(async (src) => {
+    try {
+      const res = await fetch(src.uri, {
+        method: 'HEAD',
+        redirect: 'manual',
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      const location = res.headers.get('location');
+      return { ...src, uri: location || src.uri };
+    } catch {
+      return src;
+    }
+  });
+  return Promise.all(tasks);
+}
+
+/**
+ * 從 Gemini API 回應（單一 candidate 或 chunk）中提取結構化結果
+ * 格式在 Vertex AI 和 Direct API 兩種模式下完全相同
+ * @param {object} response - API 原始回應
+ * @returns {object} 結構化結果
+ */
+export function parseGeminiResponse(response) {
+  const candidate = response.candidates?.[0];
+  if (!candidate) {
+    throw new Error('Gemini API 回應無 candidate');
+  }
+
+  // 提取文字與思考
+  let text = '';
+  let thinking = '';
+  const parts = candidate.content?.parts || [];
+  for (const part of parts) {
+    if (part.thought) {
+      thinking += part.text + '\n';
+    } else if (part.text) {
+      text += part.text;
+    }
+  }
+
+  // 提取 grounding 引證（Vertex AI / Direct API 格式相同）
+  const sources = [];
+  const gm = candidate.groundingMetadata;
+  if (gm?.groundingChunks) {
+    for (const chunk of gm.groundingChunks) {
+      if (chunk.web) {
+        sources.push({
+          uri: chunk.web.uri,
+          title: chunk.web.title || '',
+          domain: chunk.web.domain || '',
+        });
+      }
+    }
+  }
+
+  // 提取 grounding supports（文字段落 → 來源對應）
+  const supports = [];
+  if (gm?.groundingSupports) {
+    for (const s of gm.groundingSupports) {
+      supports.push({
+        text: s.segment?.text || '',
+        startIndex: s.segment?.startIndex || 0,
+        endIndex: s.segment?.endIndex || 0,
+        chunkIndices: s.groundingChunkIndices || [],
+        confidenceScores: s.confidenceScores || [],
+      });
+    }
+  }
+
+  // 搜尋查詢
+  const searchQueries = gm?.webSearchQueries || [];
+
+  // URL context 擷取結果
+  const urlContextResults = [];
+  const ucm = candidate.urlContextMetadata;
+  if (ucm?.urlMetadata) {
+    for (const entry of ucm.urlMetadata) {
+      urlContextResults.push({
+        url: entry.retrievedUrl,
+        status: entry.urlRetrievalStatus === 'URL_RETRIEVAL_STATUS_SUCCESS'
+          ? 'success'
+          : entry.urlRetrievalStatus === 'URL_RETRIEVAL_STATUS_ERROR'
+            ? 'error'
+            : 'unsafe',
+      });
+    }
+  }
+
+  // Token 用量
+  const usage = {
+    promptTokens: response.usageMetadata?.promptTokenCount || 0,
+    candidatesTokens: response.usageMetadata?.candidatesTokenCount || 0,
+    thoughtsTokens: response.usageMetadata?.thoughtsTokenCount || 0,
+    totalTokens: response.usageMetadata?.totalTokenCount || 0,
+  };
+
+  return {
+    text: text.trim(),
+    thinking: thinking.trim(),
+    sources,
+    supports,
+    searchQueries,
+    urlContext: urlContextResults,
+    usage,
+    raw: response,
+  };
+}
+
+/**
+ * 計算效能指標（純函式）
+ * @param {object} usage - token 用量
+ * @param {number} latencyMs - API 回應延遲(ms)
+ * @param {string} text - 回應文字
+ * @param {number} [ttftMs=0] - Time To First Token (ms)
+ * @returns {object} 效能指標
+ */
+export function calcPerf(usage, latencyMs, text, ttftMs = 0) {
+  const latencySec = latencyMs / 1000;
+  const outputTokens = usage.candidatesTokens;
+  const thinkTokens = usage.thoughtsTokens;
+  const totalTokens = usage.totalTokens;
+  const promptTokens = usage.promptTokens;
+
+  const outputTps = latencySec > 0 ? outputTokens / latencySec : 0;
+  const totalTps = latencySec > 0 ? totalTokens / latencySec : 0;
+  const charsPerSec = latencySec > 0 ? text.length / latencySec : 0;
+  const afterTtftSec = (latencyMs - ttftMs) / 1000;
+  const streamTps = afterTtftSec > 0 ? outputTokens / afterTtftSec : 0;
+
+  const thinkRatio = totalTokens > 0 ? thinkTokens / totalTokens : 0;
+  const outputRatio = totalTokens > 0 ? outputTokens / totalTokens : 0;
+  const promptRatio = totalTokens > 0 ? promptTokens / totalTokens : 0;
+  const thinkToOutput = outputTokens > 0 ? thinkTokens / outputTokens : 0;
+  const charsPerToken = outputTokens > 0 ? text.length / outputTokens : 0;
+
+  return {
+    latencyMs: Math.round(latencyMs),
+    latencySec: +latencySec.toFixed(2),
+    ttftMs: Math.round(ttftMs),
+    ttftSec: +(ttftMs / 1000).toFixed(2),
+    outputTokensPerSec: +outputTps.toFixed(1),
+    totalTokensPerSec: +totalTps.toFixed(1),
+    charsPerSec: +charsPerSec.toFixed(1),
+    streamTps: +streamTps.toFixed(1),
+    thinkRatio: +thinkRatio.toFixed(3),
+    outputRatio: +outputRatio.toFixed(3),
+    promptRatio: +promptRatio.toFixed(3),
+    thinkToOutputRatio: +thinkToOutput.toFixed(2),
+    charsPerToken: +charsPerToken.toFixed(2),
+  };
+}

package/lib/core/adapters/gemini-vertex.mjs

@@ -0,0 +1,232 @@
+// lib/core/adapters/gemini-vertex.mjs — Gemini 3 Flash Preview Vertex AI adapter
+// 唯一指定模型: gemini-3-flash-preview
+// 功能: thinking (MEDIUM) + grounding (Google Search) + url context
+// 原則: SOLID SRP — 此 adapter 只負責 Vertex AI Gemini API 呼叫
+
+import { GoogleGenAI } from '@google/genai';
+import { parseGeminiResponse, calcPerf, resolveRedirectUrls } from './gemini-shared.mjs';
+import { BaseAdapter } from './base.mjs';
+
+/** 預設設定常數 */
+const DEFAULTS = {
+  model: 'gemini-3-flash-preview',
+  thinkingLevel: 'MEDIUM',
+  includeThoughts: true,
+  grounding: true,
+  urlContext: true,
+  maxOutputTokens: 8192,
+  temperature: 1.0,
+  apiVersion: 'v1beta1',
+};
+
+/**
+ * Gemini Vertex AI Adapter
+ * 遵循 SOLID 原則：單一職責 — 封裝 Vertex AI Gemini API 呼叫
+ */
+export class GeminiVertexAdapter extends BaseAdapter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.project - GCP 專案 ID（必填或透過環境變數）
+   * @param {string} [opts.location='global'] - GCP 區域
+   * @param {string} [opts.thinkingLevel='MEDIUM'] - 思考等級
+   * @param {boolean} [opts.grounding=true] - 啟用 Google Search 接地
+   * @param {boolean} [opts.urlContext=true] - 啟用 URL 內容擷取
+   * @param {boolean} [opts.includeThoughts=true] - 回傳思考摘要
+   */
+  constructor(opts = {}) {
+    super();
+    const project = opts.project || process.env.GOOGLE_CLOUD_PROJECT;
+    const location = opts.location || process.env.GOOGLE_CLOUD_LOCATION || 'global';
+
+    if (!project) {
+      throw new Error(
+        'GeminiVertexAdapter: 需要 GCP 專案 ID。' +
+        '請設定 GOOGLE_CLOUD_PROJECT 環境變數或傳入 project 參數。'
+      );
+    }
+
+    this.ai = new GoogleGenAI({
+      vertexai: true,
+      project,
+      location,
+      apiVersion: opts.apiVersion || DEFAULTS.apiVersion,
+    });
+
+    this.model = DEFAULTS.model;
+    this.thinkingLevel = (opts.thinkingLevel || DEFAULTS.thinkingLevel).toUpperCase();
+    this.includeThoughts = opts.includeThoughts ?? DEFAULTS.includeThoughts;
+    this.grounding = opts.grounding ?? DEFAULTS.grounding;
+    this.urlContext = opts.urlContext ?? DEFAULTS.urlContext;
+    this.maxOutputTokens = opts.maxOutputTokens || DEFAULTS.maxOutputTokens;
+    this.temperature = opts.temperature ?? DEFAULTS.temperature;
+  }
+
+  /**
+   * 建構 tools 陣列
+   * @returns {Array} tools config
+   */
+  _buildTools() {
+    const tools = [];
+    if (this.grounding) tools.push({ googleSearch: {} });
+    if (this.urlContext) tools.push({ urlContext: {} });
+    return tools;
+  }
+
+  // DRY: _parseResponse 已移至 gemini-shared.mjs 的 parseGeminiResponse()
+
+  /**
+   * 向 Gemini 提問
+   * @param {object} params
+   * @param {string} params.prompt - 使用者提問
+   * @param {string} [params.systemInstruction] - 系統指示
+   * @returns {Promise<object>} 結構化回應
+   */
+  async generateContent({ prompt, systemInstruction }) {
+    const config = {
+      thinkingConfig: {
+        thinkingLevel: this.thinkingLevel,
+        includeThoughts: this.includeThoughts,
+      },
+      tools: this._buildTools(),
+      maxOutputTokens: this.maxOutputTokens,
+      temperature: this.temperature,
+    };
+
+    if (systemInstruction) {
+      config.systemInstruction = systemInstruction;
+    }
+
+    const params = {
+      model: this.model,
+      contents: prompt,
+      config,
+    };
+
+    const t0 = performance.now();
+    const response = await this.ai.models.generateContent(params);
+    const latencyMs = performance.now() - t0;
+
+    const result = parseGeminiResponse(response);
+    // 平行解析 grounding redirect URL → 真實 URL
+    if (result.sources.length > 0) {
+      result.sources = await resolveRedirectUrls(result.sources);
+    }
+    result.perf = calcPerf(result.usage, latencyMs, result.text);
+    return result;
+  }
+
+  /**
+   * 串流向 Gemini 提問（AsyncGenerator）
+   * 每個文字 chunk yield { type: 'text', text }
+   * 最後 yield { type: 'metadata', ...結構化結果 }（含 grounding、usage、perf）
+   * @param {object} params
+   * @param {string} params.prompt - 使用者提問
+   * @param {string} [params.systemInstruction] - 系統指示
+   * @yields {{ type: 'text', text: string } | { type: 'metadata', ... }}
+   */
+  async *generateContentStream({ prompt, systemInstruction }) {
+    const config = {
+      thinkingConfig: {
+        thinkingLevel: this.thinkingLevel,
+        includeThoughts: this.includeThoughts,
+      },
+      tools: this._buildTools(),
+      maxOutputTokens: this.maxOutputTokens,
+      temperature: this.temperature,
+    };
+
+    if (systemInstruction) {
+      config.systemInstruction = systemInstruction;
+    }
+
+    const params = {
+      model: this.model,
+      contents: prompt,
+      config,
+    };
+
+    const t0 = performance.now();
+    const DBG = process.env.BH_DEBUG === '1';
+    if (DBG) {
+      process.stderr.write(`[DBG] === 實際發送的 API 參數 ===\n`);
+      process.stderr.write(`[DBG] model: ${params.model}\n`);
+      process.stderr.write(`[DBG] systemInstruction: ${config.systemInstruction ? JSON.stringify(config.systemInstruction).slice(0, 300) : '(無)'}\n`);
+      process.stderr.write(`[DBG] contents: ${JSON.stringify(params.contents).slice(0, 200)}\n`);
+      process.stderr.write(`[DBG] tools: ${JSON.stringify(config.tools)}\n`);
+      process.stderr.write(`[DBG] thinkingLevel: ${config.thinkingConfig.thinkingLevel}\n`);
+      process.stderr.write(`[DBG] =============================\n`);
+    }
+
+    const streamResponse = await this.ai.models.generateContentStream(params);
+
+    if (DBG) {
+      const dt = ((performance.now() - t0) / 1000).toFixed(2);
+      process.stderr.write(`[DBG] SDK 回傳 streamResponse (${dt}s) type=${typeof streamResponse} keys=${Object.keys(streamResponse || {}).join(',')}\n`);
+      // 檢查 streamResponse 的可迭代性
+      const isAsyncIter = streamResponse && typeof streamResponse[Symbol.asyncIterator] === 'function';
+      const hasStream = streamResponse && typeof streamResponse.stream === 'object';
+      process.stderr.write(`[DBG] asyncIterable=${isAsyncIter} hasStream=${hasStream}\n`);
+    }
+
+    // SDK 可能回傳 { stream: AsyncIterable } 或直接 AsyncIterable
+    const stream = streamResponse[Symbol.asyncIterator]
+      ? streamResponse
+      : streamResponse.stream || streamResponse;
+
+    let ttftMs = 0;
+    let isFirst = true;
+    let lastChunk = null;
+    let chunkIdx = 0;
+
+    for await (const chunk of stream) {
+      const now = performance.now();
+      if (isFirst) {
+        ttftMs = now - t0;
+        isFirst = false;
+      }
+      lastChunk = chunk;
+
+      if (DBG) {
+        const dt = ((now - t0) / 1000).toFixed(2);
+        const parts = chunk.candidates?.[0]?.content?.parts || [];
+        const partsSummary = parts.map((p, i) => {
+          const type = p.thought ? 'thought' : p.text ? 'text' : 'other';
+          const len = (p.text || '').length;
+          return `${type}(${len})`;
+        }).join(', ');
+        const hasGrounding = !!chunk.candidates?.[0]?.groundingMetadata;
+        const groundingCount = chunk.candidates?.[0]?.groundingMetadata?.groundingChunks?.length || 0;
+        const hasUsage = !!chunk.usageMetadata;
+        process.stderr.write(`[DBG] chunk#${chunkIdx} @${dt}s parts=[${partsSummary}] groundingMeta=${hasGrounding}${hasGrounding ? `(${groundingCount}筆)` : ''} usage=${hasUsage}\n`);
+      }
+      chunkIdx++;
+
+      const parts = chunk.candidates?.[0]?.content?.parts || [];
+      for (const part of parts) {
+        if (part.thought) {
+          yield { type: 'thinking', text: part.text };
+        } else if (part.text) {
+          yield { type: 'text', text: part.text };
+        }
+      }
+    }
+
+    if (DBG) {
+      const dt = ((performance.now() - t0) / 1000).toFixed(2);
+      process.stderr.write(`[DBG] 串流結束 共${chunkIdx}個chunk @${dt}s ttft=${(ttftMs/1000).toFixed(2)}s\n`);
+    }
+
+    const latencyMs = performance.now() - t0;
+
+    if (lastChunk) {
+      const result = parseGeminiResponse(lastChunk);
+      if (result.sources.length > 0) {
+        result.sources = await resolveRedirectUrls(result.sources);
+      }
+      result.perf = calcPerf(result.usage, latencyMs, result.text, ttftMs);
+      yield { type: 'metadata', ...result };
+    }
+  }
+
+  // DRY: _calcPerf 已移至 gemini-shared.mjs 的 calcPerf()
+}

package/lib/core/adapters/local.mjs

@@ -0,0 +1,13 @@
+// lib/core/adapters/local.mjs — 本地 LLM adapter
+// TODO: 實作本地 LLM（如 ollama）呼叫
+
+export class LocalAdapter {
+  constructor(config = {}) {
+    this.endpoint = config.endpoint || 'http://localhost:11434';
+    // TODO: 初始化本地 LLM 連線
+  }
+
+  async chat(messages) {
+    throw new Error('LocalAdapter.chat() 尚未實作');
+  }
+}