botrun-horse 1.0.0

package/lib/flows/opencode-agent.mjs

@@ -0,0 +1,240 @@
+// lib/flows/opencode-agent.mjs — @opencode-ai/sdk Agentic Coding 代理
+//
+// 架構：
+//   createOpencodeServer() → 嵌入式 OpenCode server（注入 NCHC provider 設定）
+//   createOpencodeClient() → REST client
+//   session.create()       → 建立會話（自動批准所有權限）
+//   session.prompt()       → 發送任務（指定 NCHC 675B model）
+//   event.subscribe() SSE  → 串流回應事件直到 session.idle
+//
+// DDD 領域概念：
+//   CodeSession   — OpenCode 會話（由 session.create 建立）
+//   AgentEvent    — 代理執行事件（delta/text/done/session_created/timeout）
+//   ProviderConfig — NCHC provider 設定（Value Object）
+//
+// SOLID：
+//   SRP — OpencodeAgent 只負責 session 生命週期；事件處理獨立
+//   OCP — _factory 注入讓 server/client 可替換（測試 + 切換 provider）
+//   LSP — 與 NchcAgent 相同 run() AsyncGenerator 介面
+//   DIP — createServer / createClient 依賴抽象工廠，非直接 import
+//
+// 注意：需要 `opencode` CLI 安裝（npm install -g opencode-ai）
+//       且 @ai-sdk/openai-compatible 套件可被 OpenCode 存取
+
+import { createOpencodeServer, createOpencodeClient } from '@opencode-ai/sdk';
+
+// ── 常數 ───────────────────────────────────────────────────────────────────
+
+const NCHC_BASE_URL = 'https://portal.genai.nchc.org.tw/api/v1';
+export const OPENCODE_NCHC_PROVIDER_ID = 'nchc';
+export const OPENCODE_NCHC_MODEL_ID = 'Mistral-Large-3-675B-Instruct-2512';
+const DEFAULT_SERVER_PORT = 14096;
+const DEFAULT_MAX_WAIT_MS = 120_000; // 2 分鐘（agentic coding 可能需較長時間）
+const DEFAULT_SERVER_START_TIMEOUT = 15_000;
+
+// ── NCHC Provider 設定（DDD Value Object） ────────────────────────────────
+
+/**
+ * 建立 OpenCode NCHC provider 設定物件
+ * 傳入 createOpencodeServer({ config: buildNchcConfig(apiKey) }) 使用
+ *
+ * @param {string} apiKey - NCHC GenAI API Key
+ * @returns {object} OpenCode Config 物件（符合 types.gen.d.ts Config 型別）
+ */
+export function buildNchcConfig(apiKey) {
+  return {
+    providers: {
+      [OPENCODE_NCHC_PROVIDER_ID]: {
+        npm: '@ai-sdk/openai-compatible',
+        name: 'NCHC GenAI',
+        options: {
+          baseURL: NCHC_BASE_URL,
+          apiKey,
+        },
+        models: {
+          [OPENCODE_NCHC_MODEL_ID]: {
+            name: 'Mistral Large 3 675B',
+            tool_call: true,
+          },
+        },
+      },
+    },
+  };
+}
+
+// ── OpencodeAgent ─────────────────────────────────────────────────────────
+
+/**
+ * OpenCode SDK Agentic Coding 代理
+ *
+ * 透過 @opencode-ai/sdk 的 REST + SSE API 與 OpenCode server 溝通，
+ * 讓 OpenCode 以 NCHC 675B 為 LLM 執行 agentic coding 任務。
+ *
+ * @example
+ * // 自動啟動嵌入式 OpenCode server（需 opencode CLI）
+ * const agent = new OpencodeAgent();
+ * for await (const event of agent.run('寫一個 hello.mjs 並執行')) {
+ *   if (event.type === 'delta') process.stdout.write(event.text);
+ *   if (event.type === 'done')  console.log('\n完成，共', event.turns, '輪');
+ * }
+ *
+ * @example
+ * // 連接到現有的 OpenCode server
+ * const agent = new OpencodeAgent({ serverUrl: 'http://localhost:4096' });
+ */
+export class OpencodeAgent {
+  /**
+   * @param {object} [opts]
+   * @param {string}   [opts.nchcApiKey]    - NCHC GenAI API Key（預設 NCHC_GENAI_API_KEY）
+   * @param {string}   [opts.providerID]    - OpenCode provider ID（預設 'nchc'）
+   * @param {string}   [opts.modelID]       - 模型 ID（預設 675B）
+   * @param {string}   [opts.cwd]           - 工作目錄（OpenCode session 目錄）
+   * @param {number}   [opts.port]          - 嵌入式 server 埠號（預設 14096）
+   * @param {number}   [opts.maxWaitMs]     - 等待回應最大毫秒數（預設 120000）
+   * @param {string}   [opts.serverUrl]     - 使用現有 server URL（跳過自動啟動）
+   * @param {object}   [opts._factory]      - 注入假工廠（測試用，DIP）
+   *   _factory.createServer(opts) → Promise<{url, close}>
+   *   _factory.createClient(cfg)  → OpencodeClient
+   */
+  constructor(opts = {}) {
+    const apiKey = opts.nchcApiKey || process.env.NCHC_GENAI_API_KEY;
+    if (!apiKey && !opts._factory) {
+      throw new Error(
+        'OpencodeAgent: 需要 NCHC GenAI API Key。\n' +
+        '請設定環境變數 NCHC_GENAI_API_KEY 或傳入 nchcApiKey 參數。'
+      );
+    }
+
+    this.apiKey = apiKey;
+    this.providerID = opts.providerID || OPENCODE_NCHC_PROVIDER_ID;
+    this.modelID = opts.modelID || OPENCODE_NCHC_MODEL_ID;
+    this.cwd = opts.cwd || process.cwd();
+    this.port = opts.port || DEFAULT_SERVER_PORT;
+    this.maxWaitMs = opts.maxWaitMs || DEFAULT_MAX_WAIT_MS;
+    this.serverUrl = opts.serverUrl || null; // 若有值則跳過自動啟動
+
+    // DIP：測試時注入假工廠以隔離 HTTP 呼叫
+    this._factory = opts._factory || {
+      createServer: createOpencodeServer,
+      createClient: (cfg) => createOpencodeClient(cfg),
+    };
+  }
+
+  /**
+   * 執行 Agentic Coding 任務（AsyncGenerator）
+   *
+   * @param {string} task - 任務描述
+   * @yields {AgentEvent}
+   *   { type: 'session_created', sessionID }      — 會話建立成功
+   *   { type: 'delta',           text }            — 串流文字片段
+   *   { type: 'text',            text }            — 完整回應（累積）
+   *   { type: 'done',            text, timedOut }  — 任務完成
+   */
+  async *run(task) {
+    const ac = new AbortController();
+    let ownedServer = false;
+
+    try {
+      // 1. 啟動或連接 OpenCode server ──────────────────────────────────────
+      let serverUrl = this.serverUrl;
+
+      if (!serverUrl) {
+        const config = buildNchcConfig(this.apiKey);
+        const srv = await this._factory.createServer({
+          port: this.port,
+          signal: ac.signal,
+          config,
+          timeout: DEFAULT_SERVER_START_TIMEOUT,
+        });
+        serverUrl = srv.url;
+        ownedServer = true;
+      }
+
+      const client = this._factory.createClient({ baseUrl: serverUrl });
+
+      // 2. 訂閱全域 SSE 事件（在 session 建立前訂閱，避免錯過早期事件）
+      const { stream } = await client.event.subscribe({ directory: this.cwd });
+
+      // 3. 建立 session（自動批准所有工具呼叫權限）
+      const sessionRes = await client.session.create({
+        directory: this.cwd,
+        permission: [
+          { permission: '*', pattern: '*', action: 'allow' },
+        ],
+      });
+
+      const sessionID = sessionRes.data?.id;
+      if (!sessionID) {
+        throw new Error(
+          'OpencodeAgent: 無法建立 OpenCode session。\n' +
+          `API 回應：${JSON.stringify(sessionRes)}`
+        );
+      }
+
+      yield { type: 'session_created', sessionID };
+
+      // 4. 發送任務（指定 NCHC 675B model）──────────────────────────────────
+      await client.session.prompt({
+        sessionID,
+        directory: this.cwd,
+        parts: [{ type: 'text', text: task }],
+        model: {
+          providerID: this.providerID,
+          modelID: this.modelID,
+        },
+      });
+
+      // 5. 監聽 SSE 事件流直到 session.idle ────────────────────────────────
+      let fullText = '';
+      const deadline = Date.now() + this.maxWaitMs;
+
+      for await (const event of stream) {
+        // 逾時保護
+        if (Date.now() > deadline) {
+          yield { type: 'text', text: fullText };
+          yield { type: 'done', text: fullText, timedOut: true };
+          return;
+        }
+
+        const { type, properties } = event ?? {};
+        if (!type) continue;
+
+        // 文字串流 delta（session 範圍過濾）
+        if (
+          type === 'message.part.delta' &&
+          properties?.sessionID === sessionID
+        ) {
+          const delta = properties.delta ?? '';
+          if (delta) {
+            fullText += delta;
+            yield { type: 'delta', text: delta };
+          }
+        }
+
+        // 任務完成
+        if (
+          type === 'session.idle' &&
+          properties?.sessionID === sessionID
+        ) {
+          yield { type: 'text', text: fullText };
+          yield { type: 'done', text: fullText, timedOut: false };
+          return;
+        }
+
+        // 錯誤處理
+        if (
+          type === 'session.error' &&
+          (properties?.sessionID === sessionID || !properties?.sessionID)
+        ) {
+          throw new Error(
+            `OpencodeAgent session error: ${JSON.stringify(properties)}`
+          );
+        }
+      }
+
+    } finally {
+      // 只有自己啟動的 server 才需要關閉
+      if (ownedServer) ac.abort();
+    }
+  }
+}

package/lib/flows/openrouter-ask.mjs

@@ -0,0 +1,111 @@
+// lib/flows/openrouter-ask.mjs — OpenRouter 提問流程（Application Layer）
+// 職責: 組裝 adapter + 格式化輸出
+// 原則: KISS — 流程越簡單越好，複雜邏輯在 adapter
+
+import { createLLM } from '../core/llm.mjs';
+
+/**
+ * 執行 OpenRouter 提問流程（非串流）
+ * @param {object} params
+ * @param {string} params.prompt           - 使用者提問
+ * @param {string} [params.systemInstruction] - 系統提示詞
+ * @param {string} [params.model]          - 模型名稱（預設 openai/gpt-4o-mini）
+ * @param {boolean} [params.webSearch]     - 啟用網路搜尋
+ * @param {number} [params.maxResults]     - 搜尋最大結果數
+ * @param {number} [params.maxTokens]      - 最大輸出 tokens
+ * @param {number} [params.temperature]    - 溫度
+ * @returns {Promise<LlmResponse>}
+ */
+export async function openrouterAsk({
+  prompt,
+  systemInstruction,
+  model,
+  webSearch = false,
+  maxResults = 5,
+  maxTokens,
+  temperature,
+}) {
+  const adapter = await createLLM({
+    provider: 'openrouter',
+    model,
+    webSearch,
+    maxResults,
+    maxTokens,
+    temperature,
+  });
+  return adapter.generateContent({ prompt, systemInstruction });
+}
+
+/**
+ * 串流執行 OpenRouter 提問流程（AsyncGenerator）
+ * yield* 委託 adapter.generateContentStream()
+ * @param {object} params - 同 openrouterAsk 參數
+ * @yields {{ type: 'text', text: string } | { type: 'metadata', ... }}
+ */
+export async function* openrouterAskStream({
+  prompt,
+  systemInstruction,
+  model,
+  webSearch = false,
+  maxResults = 5,
+  maxTokens,
+  temperature,
+}) {
+  const adapter = await createLLM({
+    provider: 'openrouter',
+    model,
+    webSearch,
+    maxResults,
+    maxTokens,
+    temperature,
+  });
+  yield* adapter.generateContentStream({ prompt, systemInstruction });
+}
+
+/**
+ * 格式化回應為純文字（含引證 + 效能）
+ * @param {object} result - openrouterAsk 回應
+ * @returns {string} 格式化文字
+ */
+export function formatTextOutput(result) {
+  const lines = [result.text];
+
+  if (result.sources?.length > 0) {
+    lines.push('');
+    lines.push('--- 引證來源 ---');
+    for (const src of result.sources) {
+      lines.push(`  [${src.title || src.uri}] ${src.uri}`);
+    }
+  }
+
+  if (result.perf) {
+    lines.push('');
+    lines.push('--- 效能測量 ---');
+    lines.push(`  延遲:     ${result.perf.latencySec}s`);
+    if (result.perf.ttftSec !== undefined) {
+      lines.push(`  TTFT:     ${result.perf.ttftSec}s`);
+    }
+    lines.push(`  輸出速度: ${result.perf.outputTokensPerSec} tokens/s`);
+    lines.push(`  token:    prompt=${result.usage.promptTokens} output=${result.usage.outputTokens} total=${result.usage.totalTokens}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * 格式化回應為 JSON（含效能指標）
+ * @param {object} result - openrouterAsk 回應
+ * @param {string} model  - 模型名稱
+ * @param {string} elapsed - 總耗時
+ * @returns {string} JSON 字串
+ */
+export function formatJsonOutput(result, model, elapsed) {
+  return JSON.stringify({
+    _meta: { command: 'openrouter ask', model: result.model || model, elapsed },
+    text: result.text,
+    sources: result.sources,
+    usage: result.usage,
+    perf: result.perf || null,
+    finishReason: result.finishReason || null,
+  }, null, 2);
+}

package/lib/flows/review-doc.mjs

@@ -0,0 +1,18 @@
+// lib/flows/review-doc.mjs — 文件審閱業務流程
+// 串接：doc/ingest → search → 格式化
+
+/**
+ * 執行文件審閱流程
+ * 1. 匯入 PDF 到 SQLite
+ * 2. 全文檢索相關段落
+ * 3. 格式化輸出
+ *
+ * @param {object} opts
+ * @param {string} opts.project - 專案名稱
+ * @param {string[]} opts.files - PDF 檔案路徑
+ * @param {string} [opts.query] - 搜尋關鍵字
+ */
+export async function reviewDoc(opts = {}) {
+  // TODO: 實作完整文件審閱流程
+  throw new Error('reviewDoc flow 尚未實作');
+}

package/lib/ocr/index.mjs

@@ -0,0 +1,6 @@
+// lib/ocr/index.mjs — OCR 辨識模組
+// TODO: 實作 PDF/圖片 OCR 辨識
+
+export async function recognize(filePath, opts = {}) {
+  throw new Error('ocr.recognize() 尚未實作');
+}

package/lib/portal/hatch.mjs

@@ -0,0 +1,6 @@
+// lib/portal/hatch.mjs — 全自動孵化
+// TODO: 實作端到端文件處理自動化流程
+
+export async function hatch(config) {
+  throw new Error('portal.hatch() 尚未實作');
+}

package/lib/portal/index.mjs

@@ -0,0 +1,6 @@
+// lib/portal/index.mjs — 智慧入口
+// TODO: 實作文件智慧分類與路由
+
+export async function classify(input) {
+  throw new Error('portal.classify() 尚未實作');
+}

package/lib/prompt/prompt-search.mjs

@@ -0,0 +1,55 @@
+// lib/prompt/prompt-search.mjs — 加權評分模糊搜尋
+// 依 slug → alias → title → tag → series → content 順序加權比對
+
+const WEIGHTS = { slug: 10, alias: 8, title: 6, tag: 5, series: 4, content: 1 };
+
+/**
+ * 加權模糊搜尋
+ * @param {Array<{ slug, meta, body }>} prompts - 所有提示詞
+ * @param {string} query - 搜尋關鍵字
+ * @param {{ tag?: string }} [opts] - 過濾選項
+ * @returns {Array<{ prompt, score }>} 按分數降序排列
+ */
+export function searchPrompts(prompts, query, opts = {}) {
+  const q = query.toLowerCase();
+  const results = [];
+
+  for (const p of prompts) {
+    // --tag 前置過濾
+    if (opts.tag) {
+      const tags = (p.meta.tags || []).map(t => t.toLowerCase());
+      if (!tags.some(t => t.includes(opts.tag.toLowerCase()))) continue;
+    }
+
+    let score = 0;
+    const slug = p.slug.toLowerCase();
+    const aliases = (p.meta.aliases || []).map(a => a.toLowerCase());
+    const title = (p.meta.title || '').toLowerCase();
+    const tags = (p.meta.tags || []).map(t => t.toLowerCase());
+    const series = (p.meta.series || '').toLowerCase();
+    const body = p.body.toLowerCase();
+
+    // slug 精確匹配 → 滿分；部分匹配 → 6 分
+    if (slug === q) score += WEIGHTS.slug;
+    else if (slug.includes(q)) score += 6;
+
+    // alias 包含查詢（讓「切」匹配 alias「切片」）
+    if (aliases.some(a => a.includes(q) || q.includes(a))) score += WEIGHTS.alias;
+
+    // title 包含
+    if (title.includes(q)) score += WEIGHTS.title;
+
+    // tag 匹配
+    if (tags.some(t => t.includes(q) || q.includes(t))) score += WEIGHTS.tag;
+
+    // series 匹配
+    if (series.includes(q)) score += WEIGHTS.series;
+
+    // 全文內容包含
+    if (body.includes(q)) score += WEIGHTS.content;
+
+    if (score > 0) results.push({ prompt: p, score });
+  }
+
+  return results.sort((a, b) => b.score - a.score);
+}

package/lib/prompt/prompt-store.mjs

@@ -0,0 +1,94 @@
+// lib/prompt/prompt-store.mjs — 提示詞 Repository 層
+// 掃描 lib/prompt/prompts/ 目錄，解析 YAML frontmatter，提供 listPrompts / getPrompt
+
+import fs from 'fs';
+import path from 'path';
+import { root } from '../core/paths.mjs';
+
+/** 提示詞目錄（相對於專案根目錄） */
+const PROMPTS_DIR = () => path.join(root(), 'lib', 'prompt', 'prompts');
+
+/**
+ * 零依賴 YAML frontmatter 解析
+ * 支援 key: value 與 key: [a, b, c] 陣列語法
+ * @param {string} content - .md 檔案原始內容
+ * @returns {{ meta: object, body: string }}
+ */
+export function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return { meta: {}, body: content };
+
+  const meta = {};
+  for (const line of match[1].split('\n')) {
+    const kv = line.match(/^(\w[\w-]*):\s*(.+)$/);
+    if (!kv) continue;
+    const [, key, rawVal] = kv;
+    // YAML 陣列: [a, b, c]
+    if (rawVal.startsWith('[') && rawVal.endsWith(']')) {
+      meta[key] = rawVal.slice(1, -1).split(',').map(s => s.trim()).filter(Boolean);
+    } else {
+      meta[key] = rawVal.trim();
+    }
+  }
+  return { meta, body: match[2] };
+}
+
+/**
+ * 遞迴掃描目錄下所有 .md 檔案
+ * @param {string} dir - 起始目錄
+ * @param {string} baseDir - 根目錄（用於計算相對路徑）
+ * @returns {string[]} 相對路徑陣列
+ */
+function scanMarkdownFiles(dir, baseDir) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...scanMarkdownFiles(fullPath, baseDir));
+    } else if (entry.name.endsWith('.md') && entry.name !== 'README.md') {
+      results.push(path.relative(baseDir, fullPath));
+    }
+  }
+  return results.sort();
+}
+
+/**
+ * 載入並解析單一提示詞檔案
+ * @param {string} relPath - 相對於 prompts/ 的路徑（如 zero-framework/coding.md）
+ * @param {string} baseDir - prompts/ 目錄絕對路徑
+ * @returns {{ slug, meta, body, filePath, series }}
+ */
+function loadPromptFile(relPath, baseDir) {
+  const fullPath = path.join(baseDir, relPath);
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const { meta, body } = parseFrontmatter(content);
+  const slug = path.basename(relPath, '.md');
+  const series = path.dirname(relPath) === '.' ? null : path.dirname(relPath);
+  return {
+    slug,
+    meta: { ...meta, series: meta.series || series },
+    body: body.trim(),
+    filePath: fullPath,
+  };
+}
+
+/**
+ * 列出所有提示詞
+ * @returns {Array<{ slug, meta, body, filePath }>}
+ */
+export function listPrompts() {
+  const baseDir = PROMPTS_DIR();
+  const files = scanMarkdownFiles(baseDir, baseDir);
+  return files.map(f => loadPromptFile(f, baseDir));
+}
+
+/**
+ * 取得單一提示詞（精確 slug 匹配檔名）
+ * @param {string} slug - 提示詞 slug（如 'coding'）
+ * @returns {{ slug, meta, body, filePath } | null}
+ */
+export function getPrompt(slug) {
+  const all = listPrompts();
+  return all.find(p => p.slug === slug) || null;
+}

package/lib/prompt/prompts/zero-framework/coding.md

@@ -0,0 +1,15 @@
+---
+title: 零框架扣頂 coding
+series: zero-framework
+tags: [換位思考, 三方案, 六軟工, BDD, TDD, SOLID, DRY, KISS, DDD, HTTPS代理, 待辦]
+aliases: [coding, 扣頂, 寫程式, 開發]
+---
+
+# 零框架扣頂 coding
+
+- **換位思考**：先掃描資料與提問，推理需求背後動機，具體列出 5 個潛在動機
+- **新文件**：根據提問與需求上網查詢最新 SDK API 文件，因為隨時都在變化
+- **三方案**：提出 3 替代方案多維度打分，以使用者為中心選最適合方案
+- **六軟工**：採用 BDD TDD SOLID DRY KISS DDD 實作
+- **待辦**：在 `./todo/` 設計 DAG todo list，盡力平行子代理實作，追蹤測試完整
+- **HTTPS 代理**：系統有機率在沙盒 HTTPS proxy 環境變數之下執行，必須相容

package/lib/prompt/prompts/zero-framework/search.md

@@ -0,0 +1,12 @@
+---
+title: 零框架搜尋
+series: zero-framework
+tags: [搜尋, grounding, 引證, URL, 網路搜尋]
+aliases: [search, 搜尋, 查詢, 找資料]
+---
+
+# 零框架搜尋
+
+- **搜尋接地**：啟用 Google Search grounding，確保回應以真實搜尋結果為依據
+- **引證 URL**：回應必須包含引證來源的 URL，讓使用者可驗證
+- **零幻覺**：不捏造不存在的資料，所有事實陳述須有搜尋結果佐證

package/lib/prompt/prompts/zero-framework/slice.md

@@ -0,0 +1,11 @@
+---
+title: 零框架切片
+series: zero-framework
+tags: [切片, 零幻覺引證, PDF, Office, 頁碼, 純文字]
+aliases: [slice, 切片, 切頁, 文件處理]
+---
+
+# 零框架切片
+
+- **切片**：如果資料檔案是 PDF 或 Office，記得先切頁（保留頁碼可引證）轉為純文字才去處理
+- **零幻覺引證**：回應須引證來源，包含：網址、檔案名稱、頁碼、時間點、不竄改的原始文字

package/lib/search/crawler.mjs

@@ -0,0 +1,6 @@
+// lib/search/crawler.mjs — 聯網爬取
+// TODO: 實作網頁爬取與結構化擷取
+
+export async function crawl(url, opts = {}) {
+  throw new Error('crawler.crawl() 尚未實作');
+}

package/lib/search/index.mjs

@@ -0,0 +1,7 @@
+// lib/search/index.mjs — 搜尋模組入口
+// 整合 FTS5 全文檢索與聯網搜尋
+
+export { DocStore } from '../core/db.mjs';
+export { crawl } from './crawler.mjs';
+
+// TODO: 實作統一搜尋介面