botrun-horse 1.0.0

package/lib/core/paths.mjs

@@ -0,0 +1,115 @@
+// lib/core/paths.mjs — 統一路徑解析
+// botrun-horse 架構：lib 放腦、projects 放料
+
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** 專案根目錄 */
+export function root() {
+  return path.resolve(__dirname, '../..');
+}
+
+/** 取得指定專案的根目錄 */
+export function projectDir(name) {
+  return path.join(root(), 'projects', name);
+}
+
+/** 取得指定專案的 config.json 路徑 */
+export function projectConfig(name) {
+  return path.join(projectDir(name), 'config.json');
+}
+
+/** 取得指定專案的 data/ 目錄 */
+export function projectData(name) {
+  return path.join(projectDir(name), 'data');
+}
+
+/** 取得指定專案的 db/ 目錄 */
+export function projectDb(name) {
+  return path.join(projectDir(name), 'db');
+}
+
+/** 取得指定專案的 output/ 目錄 */
+export function projectOutput(name) {
+  return path.join(projectDir(name), 'output');
+}
+
+/** 取得指定專案的 DAG 定義檔路徑 */
+export function dagDefinitionPath(name) {
+  return path.join(projectData(name), 'dag-definition.json');
+}
+
+/** 取得指定專案的 DAG 狀態檔路徑 */
+export function dagStatePath(name) {
+  return path.join(projectData(name), 'dag-state.json');
+}
+
+/** 取得指定專案的 SQLite DB 路徑 */
+export function dbPath(name) {
+  return path.join(projectDb(name), 'docs.db');
+}
+
+/**
+ * 跨平台工具執行檔路徑偵測
+ *
+ * 優先順序：
+ *   1. 環境變數 BH_{NAME}_BIN（如 BH_PDFTOTEXT_BIN=/usr/local/bin/pdftotext）
+ *   2. `which <name>` 系統指令
+ *   3. 常見安裝路徑手動掃描
+ *   4. fallback 參數（預設直接使用工具名稱，期待在 PATH 中）
+ *
+ * @param {string} name     - 工具名稱（如 'pdftotext', 'qpdf', 'libreoffice'）
+ * @param {string} fallback - 找不到時的回退值（預設與 name 相同）
+ * @returns {string} 工具執行檔完整路徑或名稱
+ */
+const _toolCache = {};
+const SEARCH_DIRS = [
+  '/usr/local/bin',
+  '/usr/bin',
+  '/bin',
+  '/opt/homebrew/bin',   // macOS Homebrew (Apple Silicon)
+  '/usr/local/opt/poppler/bin', // macOS Homebrew Poppler
+  '/opt/local/bin',      // MacPorts
+  '/snap/bin',           // Ubuntu Snap
+  '/var/lib/flatpak/exports/bin', // Flatpak
+];
+
+export function toolBin(name, fallback = null) {
+  if (_toolCache[name] !== undefined) return _toolCache[name];
+
+  // 1. 環境變數覆蓋（最高優先）
+  const envKey = `BH_${name.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_BIN`;
+  if (process.env[envKey]) {
+    _toolCache[name] = process.env[envKey];
+    return _toolCache[name];
+  }
+
+  // 2. which 指令（Unix/Linux/macOS）
+  try {
+    const found = execSync(`which ${name} 2>/dev/null`, { stdio: 'pipe' }).toString().trim();
+    if (found) {
+      _toolCache[name] = found;
+      return found;
+    }
+  } catch {
+    // which 失敗，繼續嘗試
+  }
+
+  // 3. 手動掃描常見路徑
+  for (const dir of SEARCH_DIRS) {
+    const candidate = path.join(dir, name);
+    if (fs.existsSync(candidate)) {
+      _toolCache[name] = candidate;
+      return candidate;
+    }
+  }
+
+  // 4. fallback：直接使用工具名稱，期待在 PATH 中
+  const result = fallback || name;
+  _toolCache[name] = result;
+  return result;
+}

package/lib/core/proxy.mjs

@@ -0,0 +1,46 @@
+// lib/core/proxy.mjs — HTTP/HTTPS Proxy 全局設定
+//
+// 問題背景：
+//   容器環境中 no_proxy 包含 *.googleapis.com，但容器本身沒有直連外網的 DNS，
+//   導致 fetch('https://generativelanguage.googleapis.com/...') 出現 EAI_AGAIN 錯誤。
+//   解法：用 undici ProxyAgent 直接接管全局 fetch dispatcher，繞過 no_proxy 限制，
+//   強制所有請求走 HTTPS_PROXY（代理伺服器有完整 DNS 解析能力）。
+//
+// 使用方式（在 bin/bh.mjs 最頂端 import）：
+//   import { setupHttpProxy } from '../lib/core/proxy.mjs';
+//   setupHttpProxy();
+//
+// 環境變數（優先順序）：
+//   HTTPS_PROXY > https_proxy > HTTP_PROXY > http_proxy
+
+import { setGlobalDispatcher, ProxyAgent } from 'undici';
+
+/**
+ * 偵測並設定 HTTP/HTTPS Proxy
+ * 強制使用 ProxyAgent 接管 Node.js 全局 fetch，忽略 no_proxy 限制，
+ * 確保 googleapis.com、anthropic.com 等 AI API 端點可正常連線。
+ *
+ * @returns {boolean} 是否成功設定 proxy
+ */
+export function setupHttpProxy() {
+  const proxyUrl =
+    process.env.HTTPS_PROXY ||
+    process.env.https_proxy ||
+    process.env.HTTP_PROXY ||
+    process.env.http_proxy;
+
+  if (!proxyUrl) return false;
+
+  // 刻意不使用 EnvHttpProxyAgent（它會讀 no_proxy）
+  // 直接用 ProxyAgent 強制所有 fetch 走 proxy
+  // 原因：容器環境 no_proxy 含 *.googleapis.com，但直連 DNS 失敗
+  const dispatcher = new ProxyAgent({ uri: proxyUrl });
+  setGlobalDispatcher(dispatcher);
+
+  if (process.env.BH_DEBUG_PROXY) {
+    const displayUrl = proxyUrl.replace(/:\/\/[^@]+@/, '://***@'); // 隱藏 JWT token
+    process.stderr.write(`[proxy] 已啟用 ProxyAgent: ${displayUrl}\n`);
+  }
+
+  return true;
+}

package/lib/core/watermelon.mjs

@@ -0,0 +1,9 @@
+// lib/core/watermelon.mjs — 波西瓜 SQLite CRUD
+// TODO: 實作通用 SQLite 文件存取介面
+
+export class Watermelon {
+  constructor(dbPath) {
+    this.dbPath = dbPath;
+    // TODO: 初始化 SQLite 連線
+  }
+}

package/lib/doc/index.mjs

@@ -0,0 +1,419 @@
+// lib/doc/index.mjs — 通用文件入庫流水線
+//
+// 支援格式：PDF、Office 全系列（.docx/.xlsx/.pptx/.odt/.odp/.ods 等）
+//
+// Pipeline（方案 E 混合最佳化）：
+//   PDF:    pdftotext 直接按頁萃取（不需先 split）→ SQLite FTS5
+//   Office: LibreOffice --convert-to txt → 換頁符號分頁 → SQLite FTS5
+//   拆頁 PDF：可選（--split-pdf flag），僅在需要頁面級別 PDF 引證時執行
+//
+// 斷點續作：
+//   每個檔案處理前先查 ingestion_log。
+//   status='done' 的檔案預設跳過（除非 --force 重新入庫）。
+//
+// 平行策略（類 GNU parallel -j N）：
+//   - 多個文件以 concurrency semaphore 控制並發數
+//   - 單一文件內部的頁面萃取已在 pdf2text.mjs 內部平行化
+//   - SQLite WAL 模式支援並發寫入
+
+import fs from 'fs';
+import path from 'path';
+import { splitPdf, getPdfPageCount } from './split.mjs';
+import { extractAllPages } from './pdf2text.mjs';
+import { extractOfficePages, extractTextFilePages, isOfficeFile, isTextFile } from './office2text.mjs';
+import { DocStore } from '../core/db.mjs';
+
+// ─────────────────────────────────────────────────────────
+// 核心入庫函式
+// ─────────────────────────────────────────────────────────
+
+/**
+ * 匯入單一 PDF 到 SQLite
+ *
+ * Pipeline: 萃取文字 → 入庫（split PDF 為可選）
+ *
+ * @param {string} filePath - PDF 檔案路徑
+ * @param {object} opts
+ * @param {string}  opts.dbPath     - SQLite DB 路徑
+ * @param {string}  [opts.splitDir] - 拆頁 PDF 輸出目錄（不提供 = 不拆頁）
+ * @param {string}  [opts.docType]  - 文件類型（手動指定）
+ * @param {string}  [opts.title]    - 文件標題（手動指定）
+ * @param {boolean} [opts.force]    - true = 強制重新入庫（忽略 ingestion_log）
+ * @param {number}  [opts.splitConcurrency] - 拆頁並發數（預設不限）
+ * @returns {Promise<{ docId: number, pages: number, skipped: boolean }>}
+ */
+export async function ingestOnePdf(filePath, opts = {}) {
+  const {
+    dbPath = './output/pdf_docs.db',
+    splitDir = null,
+    docType = null,
+    title = null,
+    force = false,
+    splitConcurrency = 0,
+  } = opts;
+
+  const absPath = path.resolve(filePath);
+  const filename = path.basename(absPath);
+
+  const store = new DocStore(dbPath);
+  store.initSchema();
+
+  try {
+    // 斷點續作：已成功匯入的跳過
+    if (!force && store.isIngested(absPath)) {
+      const doc = store.db.prepare('SELECT id, total_pages FROM documents WHERE source_path = ?').get(absPath);
+      store.close();
+      return { docId: doc?.id ?? -1, pages: doc?.total_pages ?? 0, skipped: true };
+    }
+
+    const fileSize = fs.statSync(absPath).size;
+    const parsed = parseFilename(filename);
+    const finalDocType = docType || parsed.type;
+    const finalTitle = title || parsed.title;
+
+    // 1. 萃取所有頁面文字（不需先拆頁）
+    const textResults = await extractAllPages(absPath);
+    const totalPages = textResults.length;
+
+    // 2. 可選：拆頁成獨立 PDF（若有指定 splitDir）
+    let splitMap = {};
+    if (splitDir) {
+      const baseName = path.basename(absPath, '.pdf');
+      const pageSplitDir = path.join(splitDir, baseName);
+      const splitResults = await splitPdf(absPath, pageSplitDir, { concurrency: splitConcurrency });
+      splitMap = Object.fromEntries(splitResults.map(s => [s.page, s.path]));
+    }
+
+    // 3. 入庫
+    const docId = store.insertDocument({
+      sourcePath: absPath,
+      filename,
+      docType: finalDocType,
+      title: finalTitle,
+      totalPages,
+      fileSize,
+    });
+
+    for (const { page, text } of textResults) {
+      store.insertPage({
+        docId,
+        pageNumber: page,
+        pageText: text,
+        sourcePath: absPath,
+        sourceFile: filename,
+        sourcePage: page,
+        splitPdf: splitMap[page] || null,
+      });
+    }
+
+    store.logIngested(absPath, docId, totalPages);
+    return { docId, pages: totalPages, skipped: false };
+  } catch (err) {
+    store.logFailed(absPath, err.message);
+    throw err;
+  } finally {
+    store.close();
+  }
+}
+
+/**
+ * 匯入單一 Office 文件到 SQLite
+ *
+ * Pipeline: LibreOffice 轉換 → 逐頁萃取 → 入庫
+ *
+ * @param {string} filePath - Office 文件路徑
+ * @param {object} opts     - 同 ingestOnePdf
+ * @returns {Promise<{ docId: number, pages: number, skipped: boolean }>}
+ */
+export async function ingestOneOffice(filePath, opts = {}) {
+  const {
+    dbPath = './output/pdf_docs.db',
+    docType = null,
+    title = null,
+    force = false,
+  } = opts;
+
+  const absPath = path.resolve(filePath);
+  const filename = path.basename(absPath);
+
+  const store = new DocStore(dbPath);
+  store.initSchema();
+
+  try {
+    if (!force && store.isIngested(absPath)) {
+      const doc = store.db.prepare('SELECT id, total_pages FROM documents WHERE source_path = ?').get(absPath);
+      store.close();
+      return { docId: doc?.id ?? -1, pages: doc?.total_pages ?? 0, skipped: true };
+    }
+
+    const fileSize = fs.statSync(absPath).size;
+    const parsed = parseFilename(filename);
+    const finalDocType = docType || parsed.type;
+    const finalTitle = title || parsed.title;
+
+    // 1. 萃取所有頁面文字（LibreOffice 轉換）
+    const textResults = await extractOfficePages(absPath);
+    const totalPages = textResults.length;
+
+    // 2. 入庫
+    const docId = store.insertDocument({
+      sourcePath: absPath,
+      filename,
+      docType: finalDocType,
+      title: finalTitle,
+      totalPages,
+      fileSize,
+    });
+
+    for (const { page, text } of textResults) {
+      store.insertPage({
+        docId,
+        pageNumber: page,
+        pageText: text,
+        sourcePath: absPath,
+        sourceFile: filename,
+        sourcePage: page,
+        splitPdf: null,
+      });
+    }
+
+    store.logIngested(absPath, docId, totalPages);
+    return { docId, pages: totalPages, skipped: false };
+  } catch (err) {
+    store.logFailed(absPath, err.message);
+    throw err;
+  } finally {
+    store.close();
+  }
+}
+
+/**
+ * 匯入單一純文字檔案到 SQLite（.txt / .md / .rst 等）
+ *
+ * @param {string} filePath - 純文字檔案路徑
+ * @param {object} opts     - 同 ingestOnePdf
+ * @returns {Promise<{ docId: number, pages: number, skipped: boolean }>}
+ */
+export async function ingestOneText(filePath, opts = {}) {
+  const {
+    dbPath = './output/pdf_docs.db',
+    docType = null,
+    title = null,
+    force = false,
+  } = opts;
+
+  const absPath = path.resolve(filePath);
+  const filename = path.basename(absPath);
+
+  const store = new DocStore(dbPath);
+  store.initSchema();
+
+  try {
+    if (!force && store.isIngested(absPath)) {
+      const doc = store.db.prepare('SELECT id, total_pages FROM documents WHERE source_path = ?').get(absPath);
+      store.close();
+      return { docId: doc?.id ?? -1, pages: doc?.total_pages ?? 0, skipped: true };
+    }
+
+    const fileSize = fs.statSync(absPath).size;
+    const parsed = parseFilename(filename);
+    const finalDocType = docType || parsed.type || '純文字';
+    const finalTitle = title || parsed.title;
+
+    const textResults = await extractTextFilePages(absPath);
+    const totalPages = textResults.length;
+
+    const docId = store.insertDocument({
+      sourcePath: absPath,
+      filename,
+      docType: finalDocType,
+      title: finalTitle,
+      totalPages,
+      fileSize,
+    });
+
+    for (const { page, text } of textResults) {
+      store.insertPage({
+        docId,
+        pageNumber: page,
+        pageText: text,
+        sourcePath: absPath,
+        sourceFile: filename,
+        sourcePage: page,
+        splitPdf: null,
+      });
+    }
+
+    store.logIngested(absPath, docId, totalPages);
+    return { docId, pages: totalPages, skipped: false };
+  } catch (err) {
+    store.logFailed(absPath, err.message);
+    throw err;
+  } finally {
+    store.close();
+  }
+}
+
+/**
+ * 通用匯入單一檔案（自動根據副檔名選擇 PDF / Office / 純文字流程）
+ *
+ * @param {string} filePath - 檔案路徑（.pdf / .docx / .xlsx / .txt / .md 等）
+ * @param {object} opts     - 同 ingestOnePdf
+ * @returns {Promise<{ docId: number, pages: number, skipped: boolean }>}
+ */
+export async function ingestOne(filePath, opts = {}) {
+  if (isTextFile(filePath)) {
+    return ingestOneText(filePath, opts);
+  }
+  if (isOfficeFile(filePath)) {
+    return ingestOneOffice(filePath, opts);
+  }
+  return ingestOnePdf(filePath, opts);
+}
+
+/**
+ * 批次匯入多個檔案（並發控制，類 GNU parallel -j N）
+ *
+ * @param {string[]} filePaths   - 檔案路徑陣列
+ * @param {object}   opts        - 同 ingestOne 的 opts
+ * @param {number}   concurrency - 最大並發文件數（預設 5）
+ * @returns {Promise<{ ok: number, fail: number, skip: number, results: object[] }>}
+ */
+export async function ingestBatch(filePaths, opts = {}, concurrency = 5) {
+  const results = [];
+  let ok = 0, fail = 0, skip = 0;
+
+  // Semaphore 實作（類 GNU parallel -j N）
+  let running = 0;
+  let idx = 0;
+
+  await new Promise((resolve, reject) => {
+    function schedule() {
+      if (idx >= filePaths.length && running === 0) {
+        resolve();
+        return;
+      }
+
+      while (running < concurrency && idx < filePaths.length) {
+        const filePath = filePaths[idx++];
+        running++;
+
+        ingestOne(filePath, opts)
+          .then(r => {
+            running--;
+            if (r.skipped) {
+              skip++;
+              results.push({ path: filePath, ...r, status: 'skip' });
+              process.stdout.write(`SKIP\t${path.basename(filePath)}\t（已入庫）\n`);
+            } else {
+              ok++;
+              results.push({ path: filePath, ...r, status: 'ok' });
+              process.stdout.write(`OK\t${path.basename(filePath)}\t${r.pages}頁\n`);
+            }
+            schedule();
+          })
+          .catch(err => {
+            running--;
+            fail++;
+            results.push({ path: filePath, error: err.message, status: 'fail' });
+            process.stderr.write(`FAIL\t${path.basename(filePath)}\t${err.message}\n`);
+            schedule();
+          });
+      }
+    }
+    schedule();
+  });
+
+  return { ok, fail, skip, results };
+}
+
+/**
+ * 掃描目錄並批次匯入所有 PDF 與 Office 文件
+ *
+ * 遞迴掃描（--recursive flag 控制）或僅掃描頂層。
+ *
+ * @param {string|string[]} dirOrDirs  - 單一目錄路徑或陣列
+ * @param {object}          opts       - 同 ingestOne 的 opts
+ * @param {number}          concurrency - 最大並發數（預設 5）
+ * @param {boolean}         recursive   - 是否遞迴掃描子目錄（預設 false）
+ * @returns {Promise<{ ok, fail, skip, results }>}
+ */
+export async function ingestDir(dirOrDirs, opts = {}, concurrency = 5, recursive = false) {
+  const dirs = Array.isArray(dirOrDirs) ? dirOrDirs : [dirOrDirs];
+  const allFiles = [];
+
+  for (const dir of dirs) {
+    const absDir = path.resolve(dir);
+    const found = scanDir(absDir, recursive);
+    allFiles.push(...found);
+  }
+
+  // 依路徑排序（確保處理順序可預期，方便 debug）
+  allFiles.sort();
+
+  return ingestBatch(allFiles, opts, concurrency);
+}
+
+// ─────────────────────────────────────────────────────────
+// 工具函式
+// ─────────────────────────────────────────────────────────
+
+/**
+ * 掃描目錄，收集所有支援的文件路徑
+ *
+ * @param {string}  dir       - 目錄路徑
+ * @param {boolean} recursive - 是否遞迴
+ * @returns {string[]} 檔案路徑陣列
+ */
+function scanDir(dir, recursive = false) {
+  if (!fs.existsSync(dir)) return [];
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory() && recursive) {
+      files.push(...scanDir(fullPath, true));
+    } else if (entry.isFile()) {
+      const ext = path.extname(entry.name).toLowerCase();
+      if (ext === '.pdf' || isOfficeFile(fullPath) || isTextFile(fullPath)) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  return files;
+}
+
+/**
+ * 從檔名 best-effort 解析文件 metadata
+ *
+ * 支援的命名慣例（依優先順序）：
+ *   1. "{序號}_{類型}_{標題}.pdf"  → { id, type, title }
+ *   2. "{序號}_{標題}.pdf"         → { id, type:null, title }
+ *   3. 其他任何格式                → { id:null, type:null, title: 檔名去副檔名 }
+ *
+ * 永遠回傳有效結果，不拋出錯誤（graceful fallback）
+ *
+ * @param {string} filename - 檔案名稱（含副檔名）
+ * @returns {{ id: string|null, type: string|null, title: string }}
+ */
+export function parseFilename(filename) {
+  const ext = path.extname(filename);
+  const base = filename.slice(0, -ext.length);
+  const parts = base.split('_');
+
+  // 格式 1：{序號}_{類型}_{標題} — 至少三段，第一段是純數字
+  if (parts.length >= 3 && /^\d+$/.test(parts[0])) {
+    return { id: parts[0], type: parts[1], title: parts.slice(2).join('_') };
+  }
+
+  // 格式 2：{序號}_{標題} — 兩段，第一段是純數字
+  if (parts.length === 2 && /^\d+$/.test(parts[0])) {
+    return { id: parts[0], type: null, title: parts[1] };
+  }
+
+  // 格式 3：任何其他命名
+  return { id: null, type: null, title: base };
+}