botrun-horse 1.0.0

package/lib/core/adapters/nchc.mjs

@@ -0,0 +1,236 @@
+// lib/core/adapters/nchc.mjs — 國網 GenAI LLM adapter
+//
+// 端點：https://portal.genai.nchc.org.tw/api/v1  (OpenAI 相容介面)
+// 驗證：NCHC_GENAI_API_KEY（Bearer Token）
+// Proxy：依賴 proxy.mjs 全局 ProxyAgent dispatcher，不自行建立 HTTP client
+//
+// 可用模型：
+//   - Ministral-3-14B-Instruct-2512       （輕量快速）
+//   - Devstral-2-123B-Instruct-2512        （程式碼專精）
+//   - Mistral-Large-3-675B-Instruct-2512   （最強，預設）
+//
+// 介面相容 GeminiVertexAdapter（SOLID LSP）：
+//   generateContent({ prompt, systemInstruction })
+//   generateContentStream({ prompt, systemInstruction })
+//
+// LlmResponse Value Object（DDD — 所有 adapter 共用語言）：
+//   { text: string, sources: [], usage: { promptTokens, outputTokens, totalTokens },
+//     perf: { latencySec, ttftSec?, outputTokensPerSec }, model: string }
+
+import { calcPerfOpenAI, estimateTokens } from './openai-shared.mjs';
+import { BaseAdapter } from './base.mjs';
+
+const NCHC_API_BASE = 'https://portal.genai.nchc.org.tw/api/v1';
+
+/** 預設設定常數 */
+const DEFAULTS = {
+  model: 'Mistral-Large-3-675B-Instruct-2512',
+  maxTokens: 8192,
+  temperature: 0.7,
+};
+
+/**
+ * 國網 GenAI Adapter（OpenAI 相容介面）
+ * 使用全局 fetch（已由 proxy.mjs 設定 ProxyAgent），強制走 HTTPS proxy。
+ *
+ * SOLID：
+ *   SRP — 每個私有方法只做一件事
+ *   OCP — 透過 llm.mjs factory 擴充，不改既有 adapter
+ *   LSP — 介面完全相容 GeminiVertexAdapter
+ *   DIP — 依賴全局 fetch（由外部注入），不自建 HTTP client
+ */
+export class NchcAdapter extends BaseAdapter {
+  /**
+   * @param {object} opts
+   * @param {string} [opts.apiKey]      - NCHC_GENAI_API_KEY（預設讀環境變數）
+   * @param {string} [opts.model]       - 模型名稱（預設 Mistral-Large-3-675B-Instruct-2512）
+   * @param {number} [opts.maxTokens]   - 最大輸出 tokens（預設 8192）
+   * @param {number} [opts.temperature] - 溫度（預設 0.7）
+   */
+  constructor(opts = {}) {
+    super();
+    const apiKey = opts.apiKey || process.env.NCHC_GENAI_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        'NchcAdapter: 需要 NCHC GenAI API Key。\n' +
+        '請設定環境變數 NCHC_GENAI_API_KEY 或傳入 apiKey 參數。'
+      );
+    }
+    this.apiKey = apiKey;
+    this.model = opts.model || DEFAULTS.model;
+    this.maxTokens = opts.maxTokens || DEFAULTS.maxTokens;
+    this.temperature = opts.temperature ?? DEFAULTS.temperature;
+  }
+
+  // ── 私有建構方法（SRP：各自單一職責） ──────────────────────────────────
+
+  /**
+   * 建構 HTTP headers（DRY：兩個 fetch 共用，避免重複）
+   * @param {object} [extra={}] - 額外 headers（如 Accept: text/event-stream）
+   */
+  _buildHeaders(extra = {}) {
+    return {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${this.apiKey}`,
+      ...extra,
+    };
+  }
+
+  /** 建構 messages 陣列（OpenAI 格式） */
+  _buildMessages(prompt, systemInstruction) {
+    const messages = [];
+    if (systemInstruction) {
+      messages.push({ role: 'system', content: systemInstruction });
+    }
+    messages.push({ role: 'user', content: prompt });
+    return messages;
+  }
+
+  /** 建構 request body */
+  _buildBody(prompt, systemInstruction, stream = false) {
+    return {
+      model: this.model,
+      messages: this._buildMessages(prompt, systemInstruction),
+      max_tokens: this.maxTokens,
+      temperature: this.temperature,
+      stream,
+    };
+  }
+
+  /**
+   * 檢查 HTTP 回應狀態（DRY：兩個 fetch 共用錯誤處理）
+   * @param {Response} resp
+   * @param {string} context - 用於錯誤訊息的描述（如「非串流」、「串流」）
+   */
+  async _checkResponse(resp, context) {
+    if (resp.ok) return;
+    const errText = await resp.text().catch(() => '');
+    throw new Error(`NCHC API ${context}錯誤 ${resp.status}: ${errText}`);
+  }
+
+  /**
+   * 解析 SSE 串流（SRP：獨立 SSE 解析職責，從 generateContentStream 抽出）
+   * 逐行解析 `data: {...}` 格式，遇到 `[DONE]` 停止。
+   *
+   * @param {Response} resp - fetch 回應（resp.body 為 ReadableStream）
+   * @yields {object} 每個已解析的 SSE JSON chunk
+   */
+  async *_parseSseStream(resp) {
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    for await (const rawChunk of resp.body) {
+      buffer += decoder.decode(rawChunk, { stream: true });
+
+      const lines = buffer.split('\n');
+      buffer = lines.pop() ?? ''; // 保留最後可能不完整的行
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || !trimmed.startsWith('data: ')) continue;
+
+        const jsonStr = trimmed.slice(6); // 移除 'data: ' 前綴
+        if (jsonStr === '[DONE]') return;
+
+        try {
+          yield JSON.parse(jsonStr);
+        } catch {
+          // 跳過格式錯誤的 SSE 行（網路中斷、partial chunk 等）
+        }
+      }
+    }
+  }
+
+  // ── 公開 API（與 GeminiVertexAdapter 介面相容，SOLID LSP） ──────────────
+
+  /**
+   * 向國網 GenAI 提問（非串流）
+   * @param {object} params
+   * @param {string} params.prompt                  - 使用者提問
+   * @param {string} [params.systemInstruction]     - 系統指示
+   * @returns {Promise<LlmResponse>}
+   */
+  async generateContent({ prompt, systemInstruction }) {
+    const t0 = performance.now();
+
+    const resp = await fetch(`${NCHC_API_BASE}/chat/completions`, {
+      method: 'POST',
+      headers: this._buildHeaders(),
+      body: JSON.stringify(this._buildBody(prompt, systemInstruction, false)),
+    });
+    await this._checkResponse(resp, '非串流');
+
+    const data = await resp.json();
+    const latencyMs = performance.now() - t0;
+    const text = data.choices?.[0]?.message?.content || '';
+    const usage = data.usage || {};
+
+    return {
+      text,
+      sources: [],          // 國網 API 無搜尋接地功能
+      usage: {
+        promptTokens: usage.prompt_tokens || 0,
+        outputTokens: usage.completion_tokens || 0,
+        totalTokens: usage.total_tokens || 0,
+      },
+      perf: calcPerfOpenAI(usage, latencyMs),
+      model: data.model || this.model,
+    };
+  }
+
+  /**
+   * 串流向國網 GenAI 提問（AsyncGenerator）
+   * yield { type: 'text', text }          — 回應文字（即時串流）
+   * yield { type: 'metadata', ...result } — 最終效能指標
+   *
+   * @param {object} params
+   * @param {string} params.prompt                  - 使用者提問
+   * @param {string} [params.systemInstruction]     - 系統指示
+   */
+  async *generateContentStream({ prompt, systemInstruction }) {
+    const t0 = performance.now();
+    let ttftMs = 0;
+    let isFirst = true;
+    let fullText = '';
+    let finishReason = null;
+    let lastModel = this.model;
+
+    const resp = await fetch(`${NCHC_API_BASE}/chat/completions`, {
+      method: 'POST',
+      headers: this._buildHeaders({ 'Accept': 'text/event-stream' }),
+      body: JSON.stringify(this._buildBody(prompt, systemInstruction, true)),
+    });
+    await this._checkResponse(resp, '串流');
+
+    for await (const chunk of this._parseSseStream(resp)) {
+      if (isFirst) { ttftMs = performance.now() - t0; isFirst = false; }
+      if (chunk.model) lastModel = chunk.model;
+
+      const delta = chunk.choices?.[0]?.delta;
+      if (delta?.content) {
+        fullText += delta.content;
+        yield { type: 'text', text: delta.content };
+      }
+
+      const fr = chunk.choices?.[0]?.finish_reason;
+      if (fr) finishReason = fr;
+    }
+
+    const latencyMs = performance.now() - t0;
+    const estimatedOutputTokens = estimateTokens(fullText); // DRY：單一計算，重複使用
+
+    yield {
+      type: 'metadata',
+      text: fullText,
+      sources: [],
+      usage: {
+        promptTokens: 0,                    // 串流模式 NCHC 不回傳 prompt_tokens
+        outputTokens: estimatedOutputTokens,
+        totalTokens: estimatedOutputTokens,
+      },
+      perf: calcPerfOpenAI({ completion_tokens: estimatedOutputTokens }, latencyMs, ttftMs),
+      model: lastModel,
+      finishReason,
+    };
+  }
+}

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

@@ -0,0 +1,34 @@
+// lib/core/adapters/openai-shared.mjs — OpenAI 相容 API 共用純函式
+//
+// DRY：供所有 OpenAI 相容 adapter 共用（NCHC、未來 Claude 等）
+// SOLID SRP：純函式，無副作用，無狀態
+
+/**
+ * 估算 token 數（基於字元數）
+ * 中文字元約 1.5 chars/token，英文約 4 chars/token，混合取 3 為保守估算
+ * 僅用於串流模式（API 不回傳 prompt token 數量時）
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+export function estimateTokens(text) {
+  return Math.ceil(text.length / 3);
+}
+
+/**
+ * 計算 OpenAI 相容 API 效能指標（純函式）
+ *
+ * @param {object} usage         - OpenAI usage 物件 { completion_tokens }
+ * @param {number} latencyMs     - 完整請求延遲 (ms)
+ * @param {number} [ttftMs=0]    - Time To First Token (ms)
+ * @returns {{ latencySec, ttftSec, outputTokensPerSec }}
+ */
+export function calcPerfOpenAI(usage, latencyMs, ttftMs = 0) {
+  const outputTokens = usage?.completion_tokens || 0;
+  const latencySec = +(latencyMs / 1000).toFixed(2);
+  const ttftSec = ttftMs ? +(ttftMs / 1000).toFixed(2) : undefined;
+  const outputTokensPerSec = latencyMs > 0
+    ? +(outputTokens / (latencyMs / 1000)).toFixed(1)
+    : 0;
+  return { latencySec, ttftSec, outputTokensPerSec };
+}

package/lib/core/adapters/openrouter.mjs

@@ -0,0 +1,304 @@
+// lib/core/adapters/openrouter.mjs — OpenRouter LLM adapter
+//
+// 端點：https://openrouter.ai/api/v1  (OpenAI 相容介面)
+// 驗證：OPENROUTER_API_KEY（Bearer Token）
+// Proxy：依賴 proxy.mjs 全局 ProxyAgent dispatcher，不自行建立 HTTP client
+//
+// 特色：
+//   - 支援 400+ 模型（任意指定 model 參數）
+//   - 網路搜尋：plugins: [{ id: 'web' }] 或模型名稱加 :online 後綴
+//   - 引證來源：annotations[].url_citation（搜尋時回傳）
+//
+// 介面相容 GeminiVertexAdapter（SOLID LSP）：
+//   generateContent({ prompt, systemInstruction })
+//   generateContentStream({ prompt, systemInstruction })
+//
+// LlmResponse Value Object（DDD — 所有 adapter 共用語言）：
+//   { text: string, sources: [], usage: { promptTokens, outputTokens, totalTokens },
+//     perf: { latencySec, ttftSec?, outputTokensPerSec }, model: string }
+
+import { calcPerfOpenAI, estimateTokens } from './openai-shared.mjs';
+import { BaseAdapter } from './base.mjs';
+
+const OPENROUTER_API_BASE = 'https://openrouter.ai/api/v1';
+
+/** 預設設定常數 */
+const DEFAULTS = {
+  model: 'openai/gpt-4o-mini',
+  maxTokens: 8192,
+  temperature: 0.7,
+  webSearch: false,
+  maxResults: 5,
+  siteUrl: 'https://github.com/botrun/botrun-horse',
+  siteName: 'botrun-horse',
+};
+
+/**
+ * OpenRouter LLM Adapter（OpenAI 相容介面）
+ * 使用全局 fetch（已由 proxy.mjs 設定 ProxyAgent），強制走 HTTPS proxy。
+ *
+ * SOLID：
+ *   SRP — 每個私有方法只做一件事
+ *   OCP — 透過 llm.mjs factory 擴充，不改既有 adapter
+ *   LSP — 介面完全相容 GeminiVertexAdapter
+ *   DIP — 依賴全局 fetch（由外部注入），不自建 HTTP client
+ */
+export class OpenRouterAdapter extends BaseAdapter {
+  /**
+   * @param {object} opts
+   * @param {string} [opts.apiKey]      - OPENROUTER_API_KEY（預設讀環境變數）
+   * @param {string} [opts.model]       - 模型名稱（預設 openai/gpt-4o-mini，支援任意 OpenRouter 模型）
+   * @param {number} [opts.maxTokens]   - 最大輸出 tokens（預設 8192）
+   * @param {number} [opts.temperature] - 溫度（預設 0.7）
+   * @param {boolean} [opts.webSearch]  - 啟用網路搜尋（預設 false）
+   * @param {number} [opts.maxResults]  - 搜尋最大結果數（預設 5）
+   * @param {string} [opts.reasoningEffort] - 推理層級（'minimal'|'low'|'medium'|'high'，預設 null 不啟用）
+   * @param {string} [opts.siteUrl]     - HTTP-Referer（OpenRouter 排名用）
+   * @param {string} [opts.siteName]    - X-Title（OpenRouter 排名用）
+   */
+  constructor(opts = {}) {
+    super();
+    const apiKey = opts.apiKey || process.env.OPENROUTER_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        'OpenRouterAdapter: 需要 OpenRouter API Key。\n' +
+        '請設定環境變數 OPENROUTER_API_KEY 或傳入 apiKey 參數。\n' +
+        '取得 API Key：https://openrouter.ai/keys'
+      );
+    }
+    this.apiKey = apiKey;
+    this.model = opts.model || DEFAULTS.model;
+    this.maxTokens = opts.maxTokens || DEFAULTS.maxTokens;
+    this.temperature = opts.temperature ?? DEFAULTS.temperature;
+    this.webSearch = opts.webSearch ?? DEFAULTS.webSearch;
+    this.maxResults = opts.maxResults || DEFAULTS.maxResults;
+    this.reasoningEffort = opts.reasoningEffort || null;
+    this.siteUrl = opts.siteUrl || DEFAULTS.siteUrl;
+    this.siteName = opts.siteName || DEFAULTS.siteName;
+  }
+
+  // ── 私有建構方法（SRP：各自單一職責） ──────────────────────────────────
+
+  /**
+   * 建構 HTTP headers（DRY：兩個 fetch 共用，避免重複）
+   * HTTP-Referer 與 X-Title 為 OpenRouter 建議的識別 headers
+   * @param {object} [extra={}] - 額外 headers
+   */
+  _buildHeaders(extra = {}) {
+    return {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${this.apiKey}`,
+      'HTTP-Referer': this.siteUrl,
+      'X-Title': this.siteName,
+      ...extra,
+    };
+  }
+
+  /** 建構 messages 陣列（OpenAI chat 格式） */
+  _buildMessages(prompt, systemInstruction) {
+    const messages = [];
+    if (systemInstruction) {
+      messages.push({ role: 'system', content: systemInstruction });
+    }
+    messages.push({ role: 'user', content: prompt });
+    return messages;
+  }
+
+  /**
+   * 建構 request body
+   * 若啟用 webSearch，加入 plugins 陣列（Exa 搜尋引擎，支援所有模型）
+   * 亦可在模型名稱加 :online 後綴達到相同效果
+   */
+  _buildBody(prompt, systemInstruction, stream = false) {
+    const body = {
+      model: this.model,
+      messages: this._buildMessages(prompt, systemInstruction),
+      max_tokens: this.maxTokens,
+      temperature: this.temperature,
+      stream,
+    };
+
+    if (this.webSearch) {
+      // plugins 方式：細粒度控制搜尋參數（優先於 :online 後綴）
+      body.plugins = [{ id: 'web', max_results: this.maxResults }];
+    }
+
+    if (this.reasoningEffort) {
+      // OpenRouter reasoning 參數：映射到 Gemini thinkingLevel / Claude reasoning
+      body.reasoning = { effort: this.reasoningEffort };
+    }
+
+    return body;
+  }
+
+  /**
+   * 檢查 HTTP 回應狀態（DRY：兩個 fetch 共用錯誤處理）
+   * @param {Response} resp
+   * @param {string} context - 錯誤情境描述
+   */
+  async _checkResponse(resp, context) {
+    if (resp.ok) return;
+    const errText = await resp.text().catch(() => '');
+    throw new Error(`OpenRouter API ${context}錯誤 ${resp.status}: ${errText}`);
+  }
+
+  /**
+   * 從 message 的 annotations 陣列提取搜尋引證來源（SRP）
+   * OpenRouter 網路搜尋結果透過 annotations[].url_citation 回傳
+   *
+   * @param {object} [message] - OpenAI message 或 delta 物件
+   * @returns {Array<{uri: string, title: string, content: string}>}
+   */
+  _extractSources(message) {
+    if (!message?.annotations?.length) return [];
+    return message.annotations
+      .filter(a => a.type === 'url_citation' && a.url_citation?.url)
+      .map(a => ({
+        uri: a.url_citation.url,
+        title: a.url_citation.title || '',
+        content: a.url_citation.content || '',
+      }));
+  }
+
+  /**
+   * 解析 SSE 串流（SRP：獨立 SSE 解析職責）
+   * 逐行解析 `data: {...}` 格式，遇到 `[DONE]` 停止。
+   * 自動忽略 OpenRouter 的 `: OPENROUTER PROCESSING` 心跳注解行。
+   *
+   * @param {Response} resp - fetch 回應（resp.body 為 ReadableStream）
+   * @yields {object} 每個已解析的 SSE JSON chunk
+   */
+  async *_parseSseStream(resp) {
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    for await (const rawChunk of resp.body) {
+      buffer += decoder.decode(rawChunk, { stream: true });
+
+      const lines = buffer.split('\n');
+      buffer = lines.pop() ?? ''; // 保留最後可能不完整的行
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        // 跳過空行與 SSE 注解行（以 ':' 開頭的心跳訊息）
+        if (!trimmed || !trimmed.startsWith('data: ')) continue;
+
+        const jsonStr = trimmed.slice(6); // 移除 'data: ' 前綴
+        if (jsonStr === '[DONE]') return;
+
+        try {
+          yield JSON.parse(jsonStr);
+        } catch {
+          // 跳過格式錯誤的 SSE 行（網路中斷、partial chunk 等）
+        }
+      }
+    }
+  }
+
+  // ── 公開 API（與 GeminiVertexAdapter 介面相容，SOLID LSP） ──────────────
+
+  /**
+   * 向 OpenRouter 提問（非串流）
+   * @param {object} params
+   * @param {string} params.prompt                  - 使用者提問
+   * @param {string} [params.systemInstruction]     - 系統指示
+   * @returns {Promise<LlmResponse>}
+   */
+  async generateContent({ prompt, systemInstruction }) {
+    const t0 = performance.now();
+
+    const resp = await fetch(`${OPENROUTER_API_BASE}/chat/completions`, {
+      method: 'POST',
+      headers: this._buildHeaders(),
+      body: JSON.stringify(this._buildBody(prompt, systemInstruction, false)),
+    });
+    await this._checkResponse(resp, '非串流');
+
+    const data = await resp.json();
+    const latencyMs = performance.now() - t0;
+    const message = data.choices?.[0]?.message;
+    const text = message?.content || '';
+    const usage = data.usage || {};
+    const sources = this._extractSources(message);
+
+    return {
+      text,
+      sources,
+      usage: {
+        promptTokens: usage.prompt_tokens || 0,
+        outputTokens: usage.completion_tokens || 0,
+        totalTokens: usage.total_tokens || 0,
+      },
+      perf: calcPerfOpenAI(usage, latencyMs),
+      model: data.model || this.model,
+    };
+  }
+
+  /**
+   * 串流向 OpenRouter 提問（AsyncGenerator）
+   * yield { type: 'text', text }          — 回應文字（即時串流）
+   * yield { type: 'metadata', ...result } — 最終效能指標 + 引證來源
+   *
+   * 注意：annotations（網路搜尋引證）在串流模式下可能出現於最終 chunk 的 delta
+   *
+   * @param {object} params
+   * @param {string} params.prompt                  - 使用者提問
+   * @param {string} [params.systemInstruction]     - 系統指示
+   */
+  async *generateContentStream({ prompt, systemInstruction }) {
+    const t0 = performance.now();
+    let ttftMs = 0;
+    let isFirst = true;
+    let fullText = '';
+    let finishReason = null;
+    let lastModel = this.model;
+    let lastUsage = null;
+    let annotations = []; // 累積串流中出現的 annotations
+
+    const resp = await fetch(`${OPENROUTER_API_BASE}/chat/completions`, {
+      method: 'POST',
+      headers: this._buildHeaders({ 'Accept': 'text/event-stream' }),
+      body: JSON.stringify(this._buildBody(prompt, systemInstruction, true)),
+    });
+    await this._checkResponse(resp, '串流');
+
+    for await (const chunk of this._parseSseStream(resp)) {
+      if (isFirst) { ttftMs = performance.now() - t0; isFirst = false; }
+      if (chunk.model) lastModel = chunk.model;
+      if (chunk.usage) lastUsage = chunk.usage;
+
+      const delta = chunk.choices?.[0]?.delta;
+      if (delta?.content) {
+        fullText += delta.content;
+        yield { type: 'text', text: delta.content };
+      }
+
+      // 蒐集串流中出現的 annotations（網路搜尋引證，通常在最後一個 chunk）
+      if (delta?.annotations?.length) {
+        annotations = [...annotations, ...delta.annotations];
+      }
+
+      const fr = chunk.choices?.[0]?.finish_reason;
+      if (fr) finishReason = fr;
+    }
+
+    const latencyMs = performance.now() - t0;
+    const usage = lastUsage || {};
+    const outputTokens = usage.completion_tokens || estimateTokens(fullText);
+    const sources = this._extractSources({ annotations });
+
+    yield {
+      type: 'metadata',
+      text: fullText,
+      sources,
+      usage: {
+        promptTokens: usage.prompt_tokens || 0,
+        outputTokens,
+        totalTokens: usage.total_tokens || outputTokens,
+      },
+      perf: calcPerfOpenAI({ completion_tokens: outputTokens }, latencyMs, ttftMs),
+      model: lastModel,
+      finishReason,
+    };
+  }
+}