@jungtz/wiki-router 1.1.0 → 1.3.0

package/README.md

@@ -177,17 +177,87 @@ store: {
 ### 內建 adapter
 
 ```js
-import { fsSource, fsStore } from '@jungtz/wiki-router'
+import { fsSource, fsStore, sqliteStore, ensureWikiTables } from '@jungtz/wiki-router'
 
+// 檔案系統
 createWikiRouter({
   router,
   source: fsSource('./knowledge'),
   store:  fsStore('./wiki-output'),
 })
+
+// SQLite (better-sqlite3 相容 db 物件)
+ensureWikiTables(db)                                  // 一次性建表（idempotent）
+createWikiRouter({
+  router,
+  source: fsSource('./knowledge'),
+  store:  sqliteStore({ db, tenantId: 'hotel-001' }), // 多租戶用同一個 db、不同 tenantId
+})
 ```
 
 `knowledgeDir` / `outputDir` 簡寫即在內部分別包成 `fsSource` / `fsStore`。
 
+#### `sqliteStore({ db, tenantId, ... })`
+
+| 參數 | 類型 | 必要 | 說明 |
+|------|------|------|------|
+| `db` | better-sqlite3 instance | ✅ | 須有 `prepare(sql)` 與 `exec(sql)` 方法（不直接相依 better-sqlite3 套件） |
+| `tenantId` | `string` | ✅ | 多租戶識別字串，不同 tenant 完全隔離 |
+| `filesTable` | `string` | | 預設 `wiki_files` |
+| `manifestsTable` | `string` | | 預設 `wiki_manifests` |
+
+`sqliteStore` 內部會自動呼叫 `ensureWikiTables(db)`，但若想預先建表也可以單獨匯入使用。
+
+## 多租戶管理 — `createTenantManager`
+
+把「快取 wiki 實例 / 並行 build dedup / buildAll / 已 build 狀態追蹤 / Index.md fallback」統一封裝。其他專案串多 wiki 時只要設定 config 即可。
+
+```js
+import { createTenantManager, fsSource, sqliteStore } from '@jungtz/wiki-router'
+import Database from 'better-sqlite3'
+
+const db = new Database('./wiki.db')
+
+const manager = createTenantManager({
+  router,
+  modelId: 'ollama-local/gemma4:31b',
+
+  // adapter factory：每個 tenantId 各自建立 source / store
+  source: tid => fsSource(`./knowledge/${tid}`),
+  store:  tid => sqliteStore({ db, tenantId: tid }),
+
+  // 選用：buildAll() 才需要
+  listTenants: () => fs.readdirSync('./knowledge'),
+})
+
+await manager.buildAll()                          // 啟動時並行 build 所有租戶
+await manager.build('hotel-001', { force: true }) // 單一租戶強制重建
+const ctx = await manager.getContext('問題', 'hotel-001')
+```
+
+### Config
+
+| 參數 | 類型 | 必要 | 說明 |
+|------|------|------|------|
+| `router` | `AIProviderRouter` | ✅ | AI Router 實例 |
+| `source` | `(tenantId) => Source` | ✅ | Source factory |
+| `store`  | `(tenantId) => Store`  | ✅ | Store factory |
+| `listTenants` | `() => string[] \| Promise<string[]>` | | `buildAll()` 才需要 |
+| `autoIndex` | `boolean` | | 預設 `true`；build 後 store 沒 Index.md 時，從現有 .md 合成一份目錄 |
+| `autoIndexHeader` | `string` | | 預設 `# 知識庫目錄` |
+| `logger` | `{ log, warn, error }` | | 預設 `console` |
+| `modelId` / `routerModelId` / `timeout` / `*Prompt` | | | 同 `createWikiRouter` config，傳給每個 tenant 的 wiki 實例 |
+
+### 回傳 API
+
+| 方法 | 說明 |
+|------|------|
+| `build(tenantId, { force })` | 為單一租戶 build；同租戶並行呼叫共用同一個 promise |
+| `buildAll()` | 並行 build 所有租戶，使用 `Promise.allSettled` 避免單租戶失敗影響其他 |
+| `getContext(prompt, tenantId)` | 取得該租戶的 wiki 上下文；尚未 build 完成時回空字串（不阻塞） |
+| `isBuilt(tenantId)` | 該租戶是否已成功 build 過 |
+| `listBuilt()` | 已 build 過的租戶清單 |
+
 ## 子模組
 
 ### 解析器

package/dist/index.cjs

@@ -180,13 +180,8 @@ function fsStore(dir) {
 }
 
 /**
- * wiki-router - LLM Wiki 知識庫路由引擎
- *
- * 使用方式 (檔案系統)：
- *   const wiki = createWikiRouter({ router, knowledgeDir, outputDir })
- *
- * 使用方式 (自訂 adapter，例如 API + DB)：
- *   const wiki = createWikiRouter({ router, source, store })
+ * createWikiRouter — 單一 wiki 實例工廠
+ * 已從 index.js 拆出，避免 tenant.js → index.js 的循環依賴。
  */
 
 
@@ -227,10 +222,6 @@ function createWikiRouter(config) {
 
   let modelsFetched = false;
 
-  /**
-   * 預先獲取本地模型清單（仿照 models.js 的 getModelsList 邏輯）
-   * 確保 switchModel 能識別動態發現的 local 模型
-   */
   async function ensureModels() {
     if (modelsFetched) return
     try {
@@ -243,7 +234,7 @@ function createWikiRouter(config) {
         if (pModels.length > 0) {
           router.config.providers[pName].models = pModels.map(m => ({
             model: m.model,
-            description: m.description
+            description: m.description,
           }));
         }
       });
@@ -253,13 +244,6 @@ function createWikiRouter(config) {
     }
   }
 
-  /**
-   * 向 LLM 發送對話並取得完整回應
-   * @param {{ role: string, content: string }[]} messages
-   * @param {string} [overrideModelId]
-   * @param {number} [overrideTimeout]
-   * @returns {Promise<string|null>}
-   */
   async function chat(messages, overrideModelId, overrideTimeout) {
     const wikiModelId = overrideModelId || modelId || process.env.WIKI_MODEL || 'ollama-local/gemma4:31b';
     const effectiveTimeout = overrideTimeout || timeout;
@@ -274,7 +258,6 @@ function createWikiRouter(config) {
         modelName = parts.slice(1).join('/');
       }
 
-      // 使用 AI Router 進行對話
       if (router && provider) {
         await ensureModels();
         await router.switchModel(provider, modelName);
@@ -299,12 +282,15 @@ function createWikiRouter(config) {
     }
   }
 
-  /**
-   * 比對兩個 fingerprint 字典是否完全一致
-   * @param {Record<string,string>|null|undefined} a
-   * @param {Record<string,string>|null|undefined} b
-   * @returns {boolean}
-   */
+  function formatElapsed(startMs) {
+    const ms = Date.now() - startMs;
+    if (ms < 1000) return `${ms}ms`
+    if (ms < 60000) return `${(ms / 1000).toFixed(2)}s`
+    const m = Math.floor(ms / 60000);
+    const s = ((ms % 60000) / 1000).toFixed(1);
+    return `${m}m${s}s`
+  }
+
   function fingerprintsEqual(a, b) {
     if (!a || !b) return false
     const ak = Object.keys(a);
@@ -313,14 +299,9 @@ function createWikiRouter(config) {
     return ak.every(k => a[k] === b[k])
   }
 
-  /**
-   * 建構或更新 LLM Wiki 知識庫
-   * @param {{ force?: boolean }} [options]
-   *   force=true 時跳過 fingerprint 比對，無條件重建
-   * @returns {Promise<boolean>}
-   */
   async function build(options = {}) {
     const { force = false } = options;
+    const buildStart = Date.now();
     try {
       const knowledgeKeys = await activeSource.list();
 
@@ -329,7 +310,6 @@ function createWikiRouter(config) {
         return false
       }
 
-      // Fingerprint cache: 若來源未變動且既有 wiki 存在，直接跳過 LLM
       let currentFp = null;
       const sourceSupportsFp = typeof activeSource.getFingerprint === 'function';
       const storeSupportsManifest =
@@ -342,7 +322,7 @@ function createWikiRouter(config) {
           const storedFp = await activeStore.readManifest();
           const existingFiles = await activeStore.list();
           if (existingFiles.length > 0 && fingerprintsEqual(currentFp, storedFp)) {
-            console.log('[Wiki] Source unchanged, skipping build (fingerprint match)');
+            console.log(`[Wiki] Source unchanged, skipping build (fingerprint match) — ${formatElapsed(buildStart)}`);
             return true
           }
         }
@@ -351,6 +331,7 @@ function createWikiRouter(config) {
       let totalFiles = 0;
 
       for (const key of knowledgeKeys) {
+        const keyStart = Date.now();
         const existingFiles = await activeStore.list();
         const isFirstTime = existingFiles.length === 0;
         const { type: fileType, content: fileContent } = await activeSource.read(key);
@@ -371,7 +352,7 @@ function createWikiRouter(config) {
 
         const output = await chat([{ role: 'user', content: finalPrompt }]);
         if (!output) {
-          console.warn(`[Wiki] No output for: ${key}`);
+          console.warn(`[Wiki] No output for: ${key} — ${formatElapsed(keyStart)}`);
           continue
         }
 
@@ -386,27 +367,26 @@ function createWikiRouter(config) {
           console.log(`[Wiki] ${isFirstTime ? 'Generated' : 'Updated'}: ${filename}`);
         }
         totalFiles += parsed.length;
+        console.log(`[Wiki] Done: ${key} — ${parsed.length} file(s), ${formatElapsed(keyStart)}`);
       }
 
-      if (totalFiles === 0) return false
+      if (totalFiles === 0) {
+        console.warn(`[Wiki] Build produced no files — ${formatElapsed(buildStart)}`);
+        return false
+      }
 
-      // build 成功 → 寫入 manifest 供下次比對
       if (currentFp && storeSupportsManifest) {
         await activeStore.writeManifest(currentFp);
       }
 
+      console.log(`[Wiki] Build complete — ${totalFiles} file(s), ${formatElapsed(buildStart)}`);
       return true
     } catch (err) {
-      console.error('[Wiki Generation Error]', err);
+      console.error(`[Wiki Generation Error] (after ${formatElapsed(buildStart)})`, err);
       return false
     }
   }
 
-  /**
-   * 根據使用者問題取得相關的 Wiki 上下文
-   * @param {string} prompt - 使用者問題
-   * @returns {Promise<string>}
-   */
   async function getContext(prompt) {
     try {
       let wikiFiles = await activeStore.list();
@@ -427,17 +407,10 @@ function createWikiRouter(config) {
         .replace('{{indexContent}}', indexContent);
 
       const routeModel = routerModelId || process.env.WIKI_ROUTER_MODEL || modelId || process.env.WIKI_MODEL;
-      let output = await chat(
-        [{ role: 'user', content: selectionPrompt }],
-        routeModel
-      );
-      // Cloud LLM (e.g. Gemini) 偶爾會回空 stream，retry 一次
+      let output = await chat([{ role: 'user', content: selectionPrompt }], routeModel);
       if (!output || !output.trim()) {
         console.warn('[Wiki] Router LLM returned empty, retrying once...');
-        output = await chat(
-          [{ role: 'user', content: selectionPrompt }],
-          routeModel
-        );
+        output = await chat([{ role: 'user', content: selectionPrompt }], routeModel);
       }
       if (!output) {
         console.warn('[Wiki] Router LLM returned empty after retry.');
@@ -466,7 +439,6 @@ function createWikiRouter(config) {
         console.log(`[Wiki] LLM correctly routed to ${loadedCount} file(s): ${selectedFiles.join(', ')}`);
         return relevantContext
       }
-
     } catch (err) {
       console.error('[Wiki Context Error]', err);
     }
@@ -476,10 +448,292 @@ function createWikiRouter(config) {
   return { build, getContext }
 }
 
+/**
+ * SQLite adapter — 將 better-sqlite3（或相容 API）包裝成 Store 介面
+ *
+ * 用法：
+ *   import { sqliteStore } from '@jungtz/wiki-router'
+ *   const store = sqliteStore({ db, tenantId: 'hotel-001' })
+ *
+ * 不直接相依 better-sqlite3；只要傳入的 db 物件支援 prepare(sql) 與 exec(sql) 即可。
+ */
+
+const DEFAULT_FILES_TABLE = 'wiki_files';
+const DEFAULT_MANIFESTS_TABLE = 'wiki_manifests';
+
+/**
+ * 建立 wiki_files / wiki_manifests 兩個表（CREATE TABLE IF NOT EXISTS，可重複呼叫）
+ * @param {*} db - better-sqlite3 相容實例
+ * @param {{ filesTable?: string, manifestsTable?: string }} [opts]
+ */
+function ensureWikiTables(db, opts = {}) {
+  const filesTable = opts.filesTable || DEFAULT_FILES_TABLE;
+  const manifestsTable = opts.manifestsTable || DEFAULT_MANIFESTS_TABLE;
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS ${filesTable} (
+      tenant_id  TEXT NOT NULL,
+      filename   TEXT NOT NULL,
+      content    TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      PRIMARY KEY (tenant_id, filename)
+    );
+    CREATE TABLE IF NOT EXISTS ${manifestsTable} (
+      tenant_id  TEXT PRIMARY KEY,
+      manifest   TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+  `);
+}
+
+/**
+ * 建立 SQLite-backed Store adapter
+ * @param {{ db: *, tenantId: string, filesTable?: string, manifestsTable?: string }} config
+ * @returns {import('../types').Store}
+ */
+function sqliteStore(config) {
+  if (!config || !config.db) {
+    throw new Error('[wiki-router] sqliteStore: db is required')
+  }
+  if (!config.tenantId) {
+    throw new Error('[wiki-router] sqliteStore: tenantId is required')
+  }
+  const { db, tenantId } = config;
+  const filesTable = config.filesTable || DEFAULT_FILES_TABLE;
+  const manifestsTable = config.manifestsTable || DEFAULT_MANIFESTS_TABLE;
+
+  ensureWikiTables(db, { filesTable, manifestsTable });
+
+  const stmts = {
+    list: db.prepare(`SELECT filename FROM ${filesTable} WHERE tenant_id = ? ORDER BY filename`),
+    read: db.prepare(`SELECT content FROM ${filesTable} WHERE tenant_id = ? AND filename = ?`),
+    upsert: db.prepare(
+      `INSERT INTO ${filesTable} (tenant_id, filename, content, updated_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(tenant_id, filename) DO UPDATE SET content = excluded.content, updated_at = excluded.updated_at`
+    ),
+    readManifest: db.prepare(`SELECT manifest FROM ${manifestsTable} WHERE tenant_id = ?`),
+    writeManifest: db.prepare(
+      `INSERT INTO ${manifestsTable} (tenant_id, manifest, updated_at)
+       VALUES (?, ?, ?)
+       ON CONFLICT(tenant_id) DO UPDATE SET manifest = excluded.manifest, updated_at = excluded.updated_at`
+    ),
+  };
+
+  return {
+    async list() {
+      return stmts.list.all(tenantId).map(r => r.filename)
+    },
+    async read(filename) {
+      const row = stmts.read.get(tenantId, filename);
+      return row ? row.content : null
+    },
+    async write(filename, content) {
+      stmts.upsert.run(tenantId, filename, content, new Date().toISOString());
+    },
+    async readManifest() {
+      const row = stmts.readManifest.get(tenantId);
+      if (!row) return null
+      try {
+        return JSON.parse(row.manifest)
+      } catch {
+        return null
+      }
+    },
+    async writeManifest(manifest) {
+      stmts.writeManifest.run(tenantId, JSON.stringify(manifest), new Date().toISOString());
+    },
+  }
+}
+
+/**
+ * Multi-tenant orchestrator — 把多租戶 wiki 的常見管理邏輯封裝成單一 API
+ *
+ * 用法：
+ *   import { createTenantManager, fsSource, sqliteStore } from '@jungtz/wiki-router'
+ *
+ *   const manager = createTenantManager({
+ *     router,
+ *     source: tid => fsSource(`./knowledge/${tid}`),
+ *     store:  tid => sqliteStore({ db, tenantId: tid }),
+ *     listTenants: () => fs.readdirSync('./knowledge'),   // 選用：buildAll 才需要
+ *   })
+ *
+ *   await manager.buildAll()
+ *   const ctx = await manager.getContext('問題', 'tenant-id')
+ */
+
+
+const DEFAULT_AUTO_INDEX_HEADER = '# 知識庫目錄';
+
+function formatElapsed(startMs) {
+  const ms = Date.now() - startMs;
+  if (ms < 1000) return `${ms}ms`
+  if (ms < 60000) return `${(ms / 1000).toFixed(2)}s`
+  const m = Math.floor(ms / 60000);
+  const s = ((ms % 60000) / 1000).toFixed(1);
+  return `${m}m${s}s`
+}
+
+/**
+ * @param {import('./types').TenantManagerConfig} config
+ * @returns {import('./types').TenantManager}
+ */
+function createTenantManager(config) {
+  if (!config || !config.router) {
+    throw new Error('[wiki-router] createTenantManager: router is required')
+  }
+  if (typeof config.source !== 'function') {
+    throw new Error('[wiki-router] createTenantManager: source must be a factory function (tenantId) => Source')
+  }
+  if (typeof config.store !== 'function') {
+    throw new Error('[wiki-router] createTenantManager: store must be a factory function (tenantId) => Store')
+  }
+
+  const {
+    router,
+    source: sourceFactory,
+    store: storeFactory,
+    listTenants,
+    autoIndex = true,
+    autoIndexHeader = DEFAULT_AUTO_INDEX_HEADER,
+    logger = console,
+    ...wikiConfig
+  } = config;
+
+  const wikiCache = new Map();       // tenantId → { wiki, source, store }
+  const buildPromises = new Map();   // tenantId → Promise<boolean>
+  const builtTenants = new Set();    // 已成功 build 過的租戶
+
+  function getWiki(tenantId) {
+    if (!wikiCache.has(tenantId)) {
+      const source = sourceFactory(tenantId);
+      const store = storeFactory(tenantId);
+      const wiki = createWikiRouter({ router, source, store, ...wikiConfig });
+      wikiCache.set(tenantId, { wiki, source, store });
+    }
+    return wikiCache.get(tenantId)
+  }
+
+  /** 從 store 已有 .md 檔合成一份簡單 Index.md（LLM 沒生成時的 fallback） */
+  async function synthesizeIndex(store) {
+    const filenames = (await store.list()).filter(f => f.endsWith('.md')).sort();
+    const lines = [autoIndexHeader];
+    for (const f of filenames) {
+      const content = await store.read(f);
+      if (!content) continue
+      const titleMatch = content.match(/^#\s+(.+)/m);
+      const title = titleMatch ? titleMatch[1].trim() : f.replace('.md', '');
+      const bodyStart = content.indexOf('\n\n');
+      const snippet =
+        bodyStart > 0 ? content.slice(bodyStart).trim().replace(/\n/g, ' ').slice(0, 80) : '';
+      lines.push(`- [${title}](${f})：${snippet}`);
+    }
+    await store.write('Index.md', lines.join('\n'));
+  }
+
+  async function build(tenantId, options = {}) {
+    const { force = false } = options;
+    if (buildPromises.has(tenantId)) return buildPromises.get(tenantId)
+
+    const tenantStart = Date.now();
+    const promise = (async () => {
+      const { wiki, store } = getWiki(tenantId);
+      const ok = await wiki.build({ force });
+      if (!ok) {
+        logger.warn && logger.warn(`[Wiki] Tenant "${tenantId}" build failed — ${formatElapsed(tenantStart)}`);
+        return false
+      }
+
+      if (autoIndex) {
+        const hasIndex = await store.read('Index.md');
+        if (!hasIndex) {
+          await synthesizeIndex(store);
+          logger.log && logger.log(`[Wiki] Auto-generated Index.md for tenant: ${tenantId}`);
+        }
+      }
+
+      builtTenants.add(tenantId);
+      logger.log && logger.log(`[Wiki] Tenant "${tenantId}" ready — ${formatElapsed(tenantStart)}`);
+      return true
+    })().finally(() => {
+      buildPromises.delete(tenantId);
+    });
+
+    buildPromises.set(tenantId, promise);
+    return promise
+  }
+
+  async function buildAll() {
+    if (typeof listTenants !== 'function') {
+      throw new Error('[wiki-router] buildAll: listTenants config is required')
+    }
+    const tenants = await listTenants();
+    if (!tenants || tenants.length === 0) {
+      logger.log && logger.log('[Wiki] No tenants to build');
+      return []
+    }
+    const allStart = Date.now();
+    logger.log && logger.log(`[Wiki] Pre-building ${tenants.length} tenant(s): ${tenants.join(', ')}`);
+    const results = await Promise.allSettled(tenants.map(t => build(t)));
+    const okCount = results.filter(r => r.status === 'fulfilled' && r.value === true).length;
+    logger.log && logger.log(`[Wiki] buildAll done — ${okCount}/${tenants.length} ok, ${formatElapsed(allStart)}`);
+    results.forEach((r, i) => {
+      if (r.status === 'rejected') {
+        logger.error && logger.error(
+          `[Wiki] Build failed for "${tenants[i]}":`,
+          r.reason && r.reason.message ? r.reason.message : r.reason
+        );
+      } else if (r.value === false) {
+        logger.warn && logger.warn(`[Wiki] Build returned false for "${tenants[i]}"`);
+      }
+    });
+    return results
+  }
+
+  /**
+   * 取得指定租戶的 wiki 上下文；尚未 build 完成時回傳空字串（不阻塞主流程）
+   */
+  async function getContext(prompt, tenantId) {
+    if (!builtTenants.has(tenantId)) {
+      if (buildPromises.has(tenantId)) {
+        logger.log && logger.log(`[Wiki] Build in progress for "${tenantId}", returning empty context`);
+      } else {
+        logger.log && logger.log(`[Wiki] No wiki built for "${tenantId}", returning empty context`);
+      }
+      return ''
+    }
+    return getWiki(tenantId).wiki.getContext(prompt)
+  }
+
+  return {
+    build,
+    buildAll,
+    getContext,
+    isBuilt: tenantId => builtTenants.has(tenantId),
+    listBuilt: () => Array.from(builtTenants),
+  }
+}
+
+/**
+ * wiki-router - LLM Wiki 知識庫路由引擎
+ *
+ * 使用方式 (檔案系統)：
+ *   const wiki = createWikiRouter({ router, knowledgeDir, outputDir })
+ *
+ * 使用方式 (自訂 adapter，例如 API + DB)：
+ *   const wiki = createWikiRouter({ router, source, store })
+ *
+ * 多租戶 (推薦)：
+ *   const manager = createTenantManager({ router, source, store, listTenants })
+ */
+
 exports.MERGE_PROMPT = MERGE_PROMPT;
 exports.ROUTER_PROMPT = ROUTER_PROMPT;
 exports.SPLIT_PROMPT = SPLIT_PROMPT;
+exports.createTenantManager = createTenantManager;
 exports.createWikiRouter = createWikiRouter;
+exports.ensureWikiTables = ensureWikiTables;
 exports.fsSource = fsSource;
 exports.fsStore = fsStore;
 exports.parseWikiOutput = parseWikiOutput;
+exports.sqliteStore = sqliteStore;

package/dist/index.d.ts

@@ -56,4 +56,38 @@
  * @property {string} content - 檔案內容
  */
 
+/**
+ * @typedef {Object} SqliteStoreConfig
+ * @property {*} db - better-sqlite3 相容實例（需有 prepare/exec 方法）
+ * @property {string} tenantId - 多租戶識別字串
+ * @property {string} [filesTable='wiki_files'] - 自訂 files 表名
+ * @property {string} [manifestsTable='wiki_manifests'] - 自訂 manifests 表名
+ */
+
+/**
+ * @typedef {Object} TenantManagerConfig
+ * @property {import('@jungtz/ai-router').AIProviderRouter} router - AI Router 實例
+ * @property {(tenantId: string) => Source} source - Source factory（依 tenantId 建立）
+ * @property {(tenantId: string) => Store} store - Store factory（依 tenantId 建立）
+ * @property {() => string[] | Promise<string[]>} [listTenants] - 列出所有租戶；buildAll() 才需要
+ * @property {boolean} [autoIndex=true] - build 後若 store 沒有 Index.md，自動從現有 .md 合成一份目錄
+ * @property {string} [autoIndexHeader='# 知識庫目錄'] - autoIndex 的 header
+ * @property {{log?: Function, warn?: Function, error?: Function}} [logger=console] - 自訂 logger
+ * @property {string} [modelId] - 同 WikiRouterConfig.modelId
+ * @property {string} [routerModelId] - 同 WikiRouterConfig.routerModelId
+ * @property {number} [timeout] - 同 WikiRouterConfig.timeout
+ * @property {string} [splitPrompt] - 同 WikiRouterConfig.splitPrompt
+ * @property {string} [mergePrompt] - 同 WikiRouterConfig.mergePrompt
+ * @property {string} [routerPrompt] - 同 WikiRouterConfig.routerPrompt
+ */
+
+/**
+ * @typedef {Object} TenantManager
+ * @property {(tenantId: string, options?: BuildOptions) => Promise<boolean>} build - 為單一租戶建構 wiki
+ * @property {() => Promise<PromiseSettledResult<boolean>[]>} buildAll - 並行建構所有租戶（需設定 listTenants）
+ * @property {(prompt: string, tenantId: string) => Promise<string>} getContext - 取得指定租戶的 wiki 上下文
+ * @property {(tenantId: string) => boolean} isBuilt - 該租戶是否已成功 build 過
+ * @property {() => string[]} listBuilt - 已成功 build 過的租戶清單
+ */
+
 export {}

package/dist/index.mjs

@@ -178,13 +178,8 @@ function fsStore(dir) {
 }
 
 /**
- * wiki-router - LLM Wiki 知識庫路由引擎
- *
- * 使用方式 (檔案系統)：
- *   const wiki = createWikiRouter({ router, knowledgeDir, outputDir })
- *
- * 使用方式 (自訂 adapter，例如 API + DB)：
- *   const wiki = createWikiRouter({ router, source, store })
+ * createWikiRouter — 單一 wiki 實例工廠
+ * 已從 index.js 拆出，避免 tenant.js → index.js 的循環依賴。
  */
 
 
@@ -225,10 +220,6 @@ function createWikiRouter(config) {
 
   let modelsFetched = false;
 
-  /**
-   * 預先獲取本地模型清單（仿照 models.js 的 getModelsList 邏輯）
-   * 確保 switchModel 能識別動態發現的 local 模型
-   */
   async function ensureModels() {
     if (modelsFetched) return
     try {
@@ -241,7 +232,7 @@ function createWikiRouter(config) {
         if (pModels.length > 0) {
           router.config.providers[pName].models = pModels.map(m => ({
             model: m.model,
-            description: m.description
+            description: m.description,
           }));
         }
       });
@@ -251,13 +242,6 @@ function createWikiRouter(config) {
     }
   }
 
-  /**
-   * 向 LLM 發送對話並取得完整回應
-   * @param {{ role: string, content: string }[]} messages
-   * @param {string} [overrideModelId]
-   * @param {number} [overrideTimeout]
-   * @returns {Promise<string|null>}
-   */
   async function chat(messages, overrideModelId, overrideTimeout) {
     const wikiModelId = overrideModelId || modelId || process.env.WIKI_MODEL || 'ollama-local/gemma4:31b';
     const effectiveTimeout = overrideTimeout || timeout;
@@ -272,7 +256,6 @@ function createWikiRouter(config) {
         modelName = parts.slice(1).join('/');
       }
 
-      // 使用 AI Router 進行對話
       if (router && provider) {
         await ensureModels();
         await router.switchModel(provider, modelName);
@@ -297,12 +280,15 @@ function createWikiRouter(config) {
     }
   }
 
-  /**
-   * 比對兩個 fingerprint 字典是否完全一致
-   * @param {Record<string,string>|null|undefined} a
-   * @param {Record<string,string>|null|undefined} b
-   * @returns {boolean}
-   */
+  function formatElapsed(startMs) {
+    const ms = Date.now() - startMs;
+    if (ms < 1000) return `${ms}ms`
+    if (ms < 60000) return `${(ms / 1000).toFixed(2)}s`
+    const m = Math.floor(ms / 60000);
+    const s = ((ms % 60000) / 1000).toFixed(1);
+    return `${m}m${s}s`
+  }
+
   function fingerprintsEqual(a, b) {
     if (!a || !b) return false
     const ak = Object.keys(a);
@@ -311,14 +297,9 @@ function createWikiRouter(config) {
     return ak.every(k => a[k] === b[k])
   }
 
-  /**
-   * 建構或更新 LLM Wiki 知識庫
-   * @param {{ force?: boolean }} [options]
-   *   force=true 時跳過 fingerprint 比對，無條件重建
-   * @returns {Promise<boolean>}
-   */
   async function build(options = {}) {
     const { force = false } = options;
+    const buildStart = Date.now();
     try {
       const knowledgeKeys = await activeSource.list();
 
@@ -327,7 +308,6 @@ function createWikiRouter(config) {
         return false
       }
 
-      // Fingerprint cache: 若來源未變動且既有 wiki 存在，直接跳過 LLM
       let currentFp = null;
       const sourceSupportsFp = typeof activeSource.getFingerprint === 'function';
       const storeSupportsManifest =
@@ -340,7 +320,7 @@ function createWikiRouter(config) {
           const storedFp = await activeStore.readManifest();
           const existingFiles = await activeStore.list();
           if (existingFiles.length > 0 && fingerprintsEqual(currentFp, storedFp)) {
-            console.log('[Wiki] Source unchanged, skipping build (fingerprint match)');
+            console.log(`[Wiki] Source unchanged, skipping build (fingerprint match) — ${formatElapsed(buildStart)}`);
             return true
           }
         }
@@ -349,6 +329,7 @@ function createWikiRouter(config) {
       let totalFiles = 0;
 
       for (const key of knowledgeKeys) {
+        const keyStart = Date.now();
         const existingFiles = await activeStore.list();
         const isFirstTime = existingFiles.length === 0;
         const { type: fileType, content: fileContent } = await activeSource.read(key);
@@ -369,7 +350,7 @@ function createWikiRouter(config) {
 
         const output = await chat([{ role: 'user', content: finalPrompt }]);
         if (!output) {
-          console.warn(`[Wiki] No output for: ${key}`);
+          console.warn(`[Wiki] No output for: ${key} — ${formatElapsed(keyStart)}`);
           continue
         }
 
@@ -384,27 +365,26 @@ function createWikiRouter(config) {
           console.log(`[Wiki] ${isFirstTime ? 'Generated' : 'Updated'}: ${filename}`);
         }
         totalFiles += parsed.length;
+        console.log(`[Wiki] Done: ${key} — ${parsed.length} file(s), ${formatElapsed(keyStart)}`);
       }
 
-      if (totalFiles === 0) return false
+      if (totalFiles === 0) {
+        console.warn(`[Wiki] Build produced no files — ${formatElapsed(buildStart)}`);
+        return false
+      }
 
-      // build 成功 → 寫入 manifest 供下次比對
       if (currentFp && storeSupportsManifest) {
         await activeStore.writeManifest(currentFp);
       }
 
+      console.log(`[Wiki] Build complete — ${totalFiles} file(s), ${formatElapsed(buildStart)}`);
       return true
     } catch (err) {
-      console.error('[Wiki Generation Error]', err);
+      console.error(`[Wiki Generation Error] (after ${formatElapsed(buildStart)})`, err);
       return false
     }
   }
 
-  /**
-   * 根據使用者問題取得相關的 Wiki 上下文
-   * @param {string} prompt - 使用者問題
-   * @returns {Promise<string>}
-   */
   async function getContext(prompt) {
     try {
       let wikiFiles = await activeStore.list();
@@ -425,17 +405,10 @@ function createWikiRouter(config) {
         .replace('{{indexContent}}', indexContent);
 
       const routeModel = routerModelId || process.env.WIKI_ROUTER_MODEL || modelId || process.env.WIKI_MODEL;
-      let output = await chat(
-        [{ role: 'user', content: selectionPrompt }],
-        routeModel
-      );
-      // Cloud LLM (e.g. Gemini) 偶爾會回空 stream，retry 一次
+      let output = await chat([{ role: 'user', content: selectionPrompt }], routeModel);
       if (!output || !output.trim()) {
         console.warn('[Wiki] Router LLM returned empty, retrying once...');
-        output = await chat(
-          [{ role: 'user', content: selectionPrompt }],
-          routeModel
-        );
+        output = await chat([{ role: 'user', content: selectionPrompt }], routeModel);
       }
       if (!output) {
         console.warn('[Wiki] Router LLM returned empty after retry.');
@@ -464,7 +437,6 @@ function createWikiRouter(config) {
         console.log(`[Wiki] LLM correctly routed to ${loadedCount} file(s): ${selectedFiles.join(', ')}`);
         return relevantContext
       }
-
     } catch (err) {
       console.error('[Wiki Context Error]', err);
     }
@@ -474,4 +446,283 @@ function createWikiRouter(config) {
   return { build, getContext }
 }
 
-export { MERGE_PROMPT, ROUTER_PROMPT, SPLIT_PROMPT, createWikiRouter, fsSource, fsStore, parseWikiOutput };
+/**
+ * SQLite adapter — 將 better-sqlite3（或相容 API）包裝成 Store 介面
+ *
+ * 用法：
+ *   import { sqliteStore } from '@jungtz/wiki-router'
+ *   const store = sqliteStore({ db, tenantId: 'hotel-001' })
+ *
+ * 不直接相依 better-sqlite3；只要傳入的 db 物件支援 prepare(sql) 與 exec(sql) 即可。
+ */
+
+const DEFAULT_FILES_TABLE = 'wiki_files';
+const DEFAULT_MANIFESTS_TABLE = 'wiki_manifests';
+
+/**
+ * 建立 wiki_files / wiki_manifests 兩個表（CREATE TABLE IF NOT EXISTS，可重複呼叫）
+ * @param {*} db - better-sqlite3 相容實例
+ * @param {{ filesTable?: string, manifestsTable?: string }} [opts]
+ */
+function ensureWikiTables(db, opts = {}) {
+  const filesTable = opts.filesTable || DEFAULT_FILES_TABLE;
+  const manifestsTable = opts.manifestsTable || DEFAULT_MANIFESTS_TABLE;
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS ${filesTable} (
+      tenant_id  TEXT NOT NULL,
+      filename   TEXT NOT NULL,
+      content    TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      PRIMARY KEY (tenant_id, filename)
+    );
+    CREATE TABLE IF NOT EXISTS ${manifestsTable} (
+      tenant_id  TEXT PRIMARY KEY,
+      manifest   TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+  `);
+}
+
+/**
+ * 建立 SQLite-backed Store adapter
+ * @param {{ db: *, tenantId: string, filesTable?: string, manifestsTable?: string }} config
+ * @returns {import('../types').Store}
+ */
+function sqliteStore(config) {
+  if (!config || !config.db) {
+    throw new Error('[wiki-router] sqliteStore: db is required')
+  }
+  if (!config.tenantId) {
+    throw new Error('[wiki-router] sqliteStore: tenantId is required')
+  }
+  const { db, tenantId } = config;
+  const filesTable = config.filesTable || DEFAULT_FILES_TABLE;
+  const manifestsTable = config.manifestsTable || DEFAULT_MANIFESTS_TABLE;
+
+  ensureWikiTables(db, { filesTable, manifestsTable });
+
+  const stmts = {
+    list: db.prepare(`SELECT filename FROM ${filesTable} WHERE tenant_id = ? ORDER BY filename`),
+    read: db.prepare(`SELECT content FROM ${filesTable} WHERE tenant_id = ? AND filename = ?`),
+    upsert: db.prepare(
+      `INSERT INTO ${filesTable} (tenant_id, filename, content, updated_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(tenant_id, filename) DO UPDATE SET content = excluded.content, updated_at = excluded.updated_at`
+    ),
+    readManifest: db.prepare(`SELECT manifest FROM ${manifestsTable} WHERE tenant_id = ?`),
+    writeManifest: db.prepare(
+      `INSERT INTO ${manifestsTable} (tenant_id, manifest, updated_at)
+       VALUES (?, ?, ?)
+       ON CONFLICT(tenant_id) DO UPDATE SET manifest = excluded.manifest, updated_at = excluded.updated_at`
+    ),
+  };
+
+  return {
+    async list() {
+      return stmts.list.all(tenantId).map(r => r.filename)
+    },
+    async read(filename) {
+      const row = stmts.read.get(tenantId, filename);
+      return row ? row.content : null
+    },
+    async write(filename, content) {
+      stmts.upsert.run(tenantId, filename, content, new Date().toISOString());
+    },
+    async readManifest() {
+      const row = stmts.readManifest.get(tenantId);
+      if (!row) return null
+      try {
+        return JSON.parse(row.manifest)
+      } catch {
+        return null
+      }
+    },
+    async writeManifest(manifest) {
+      stmts.writeManifest.run(tenantId, JSON.stringify(manifest), new Date().toISOString());
+    },
+  }
+}
+
+/**
+ * Multi-tenant orchestrator — 把多租戶 wiki 的常見管理邏輯封裝成單一 API
+ *
+ * 用法：
+ *   import { createTenantManager, fsSource, sqliteStore } from '@jungtz/wiki-router'
+ *
+ *   const manager = createTenantManager({
+ *     router,
+ *     source: tid => fsSource(`./knowledge/${tid}`),
+ *     store:  tid => sqliteStore({ db, tenantId: tid }),
+ *     listTenants: () => fs.readdirSync('./knowledge'),   // 選用：buildAll 才需要
+ *   })
+ *
+ *   await manager.buildAll()
+ *   const ctx = await manager.getContext('問題', 'tenant-id')
+ */
+
+
+const DEFAULT_AUTO_INDEX_HEADER = '# 知識庫目錄';
+
+function formatElapsed(startMs) {
+  const ms = Date.now() - startMs;
+  if (ms < 1000) return `${ms}ms`
+  if (ms < 60000) return `${(ms / 1000).toFixed(2)}s`
+  const m = Math.floor(ms / 60000);
+  const s = ((ms % 60000) / 1000).toFixed(1);
+  return `${m}m${s}s`
+}
+
+/**
+ * @param {import('./types').TenantManagerConfig} config
+ * @returns {import('./types').TenantManager}
+ */
+function createTenantManager(config) {
+  if (!config || !config.router) {
+    throw new Error('[wiki-router] createTenantManager: router is required')
+  }
+  if (typeof config.source !== 'function') {
+    throw new Error('[wiki-router] createTenantManager: source must be a factory function (tenantId) => Source')
+  }
+  if (typeof config.store !== 'function') {
+    throw new Error('[wiki-router] createTenantManager: store must be a factory function (tenantId) => Store')
+  }
+
+  const {
+    router,
+    source: sourceFactory,
+    store: storeFactory,
+    listTenants,
+    autoIndex = true,
+    autoIndexHeader = DEFAULT_AUTO_INDEX_HEADER,
+    logger = console,
+    ...wikiConfig
+  } = config;
+
+  const wikiCache = new Map();       // tenantId → { wiki, source, store }
+  const buildPromises = new Map();   // tenantId → Promise<boolean>
+  const builtTenants = new Set();    // 已成功 build 過的租戶
+
+  function getWiki(tenantId) {
+    if (!wikiCache.has(tenantId)) {
+      const source = sourceFactory(tenantId);
+      const store = storeFactory(tenantId);
+      const wiki = createWikiRouter({ router, source, store, ...wikiConfig });
+      wikiCache.set(tenantId, { wiki, source, store });
+    }
+    return wikiCache.get(tenantId)
+  }
+
+  /** 從 store 已有 .md 檔合成一份簡單 Index.md（LLM 沒生成時的 fallback） */
+  async function synthesizeIndex(store) {
+    const filenames = (await store.list()).filter(f => f.endsWith('.md')).sort();
+    const lines = [autoIndexHeader];
+    for (const f of filenames) {
+      const content = await store.read(f);
+      if (!content) continue
+      const titleMatch = content.match(/^#\s+(.+)/m);
+      const title = titleMatch ? titleMatch[1].trim() : f.replace('.md', '');
+      const bodyStart = content.indexOf('\n\n');
+      const snippet =
+        bodyStart > 0 ? content.slice(bodyStart).trim().replace(/\n/g, ' ').slice(0, 80) : '';
+      lines.push(`- [${title}](${f})：${snippet}`);
+    }
+    await store.write('Index.md', lines.join('\n'));
+  }
+
+  async function build(tenantId, options = {}) {
+    const { force = false } = options;
+    if (buildPromises.has(tenantId)) return buildPromises.get(tenantId)
+
+    const tenantStart = Date.now();
+    const promise = (async () => {
+      const { wiki, store } = getWiki(tenantId);
+      const ok = await wiki.build({ force });
+      if (!ok) {
+        logger.warn && logger.warn(`[Wiki] Tenant "${tenantId}" build failed — ${formatElapsed(tenantStart)}`);
+        return false
+      }
+
+      if (autoIndex) {
+        const hasIndex = await store.read('Index.md');
+        if (!hasIndex) {
+          await synthesizeIndex(store);
+          logger.log && logger.log(`[Wiki] Auto-generated Index.md for tenant: ${tenantId}`);
+        }
+      }
+
+      builtTenants.add(tenantId);
+      logger.log && logger.log(`[Wiki] Tenant "${tenantId}" ready — ${formatElapsed(tenantStart)}`);
+      return true
+    })().finally(() => {
+      buildPromises.delete(tenantId);
+    });
+
+    buildPromises.set(tenantId, promise);
+    return promise
+  }
+
+  async function buildAll() {
+    if (typeof listTenants !== 'function') {
+      throw new Error('[wiki-router] buildAll: listTenants config is required')
+    }
+    const tenants = await listTenants();
+    if (!tenants || tenants.length === 0) {
+      logger.log && logger.log('[Wiki] No tenants to build');
+      return []
+    }
+    const allStart = Date.now();
+    logger.log && logger.log(`[Wiki] Pre-building ${tenants.length} tenant(s): ${tenants.join(', ')}`);
+    const results = await Promise.allSettled(tenants.map(t => build(t)));
+    const okCount = results.filter(r => r.status === 'fulfilled' && r.value === true).length;
+    logger.log && logger.log(`[Wiki] buildAll done — ${okCount}/${tenants.length} ok, ${formatElapsed(allStart)}`);
+    results.forEach((r, i) => {
+      if (r.status === 'rejected') {
+        logger.error && logger.error(
+          `[Wiki] Build failed for "${tenants[i]}":`,
+          r.reason && r.reason.message ? r.reason.message : r.reason
+        );
+      } else if (r.value === false) {
+        logger.warn && logger.warn(`[Wiki] Build returned false for "${tenants[i]}"`);
+      }
+    });
+    return results
+  }
+
+  /**
+   * 取得指定租戶的 wiki 上下文；尚未 build 完成時回傳空字串（不阻塞主流程）
+   */
+  async function getContext(prompt, tenantId) {
+    if (!builtTenants.has(tenantId)) {
+      if (buildPromises.has(tenantId)) {
+        logger.log && logger.log(`[Wiki] Build in progress for "${tenantId}", returning empty context`);
+      } else {
+        logger.log && logger.log(`[Wiki] No wiki built for "${tenantId}", returning empty context`);
+      }
+      return ''
+    }
+    return getWiki(tenantId).wiki.getContext(prompt)
+  }
+
+  return {
+    build,
+    buildAll,
+    getContext,
+    isBuilt: tenantId => builtTenants.has(tenantId),
+    listBuilt: () => Array.from(builtTenants),
+  }
+}
+
+/**
+ * wiki-router - LLM Wiki 知識庫路由引擎
+ *
+ * 使用方式 (檔案系統)：
+ *   const wiki = createWikiRouter({ router, knowledgeDir, outputDir })
+ *
+ * 使用方式 (自訂 adapter，例如 API + DB)：
+ *   const wiki = createWikiRouter({ router, source, store })
+ *
+ * 多租戶 (推薦)：
+ *   const manager = createTenantManager({ router, source, store, listTenants })
+ */
+
+export { MERGE_PROMPT, ROUTER_PROMPT, SPLIT_PROMPT, createTenantManager, createWikiRouter, ensureWikiTables, fsSource, fsStore, parseWikiOutput, sqliteStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jungtz/wiki-router",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "LLM Wiki 知識庫路由引擎 - 將結構化知識轉為 Markdown 維基，智慧路由查詢",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",

package/src/types.d.ts

@@ -56,4 +56,38 @@
  * @property {string} content - 檔案內容
  */
 
+/**
+ * @typedef {Object} SqliteStoreConfig
+ * @property {*} db - better-sqlite3 相容實例（需有 prepare/exec 方法）
+ * @property {string} tenantId - 多租戶識別字串
+ * @property {string} [filesTable='wiki_files'] - 自訂 files 表名
+ * @property {string} [manifestsTable='wiki_manifests'] - 自訂 manifests 表名
+ */
+
+/**
+ * @typedef {Object} TenantManagerConfig
+ * @property {import('@jungtz/ai-router').AIProviderRouter} router - AI Router 實例
+ * @property {(tenantId: string) => Source} source - Source factory（依 tenantId 建立）
+ * @property {(tenantId: string) => Store} store - Store factory（依 tenantId 建立）
+ * @property {() => string[] | Promise<string[]>} [listTenants] - 列出所有租戶；buildAll() 才需要
+ * @property {boolean} [autoIndex=true] - build 後若 store 沒有 Index.md，自動從現有 .md 合成一份目錄
+ * @property {string} [autoIndexHeader='# 知識庫目錄'] - autoIndex 的 header
+ * @property {{log?: Function, warn?: Function, error?: Function}} [logger=console] - 自訂 logger
+ * @property {string} [modelId] - 同 WikiRouterConfig.modelId
+ * @property {string} [routerModelId] - 同 WikiRouterConfig.routerModelId
+ * @property {number} [timeout] - 同 WikiRouterConfig.timeout
+ * @property {string} [splitPrompt] - 同 WikiRouterConfig.splitPrompt
+ * @property {string} [mergePrompt] - 同 WikiRouterConfig.mergePrompt
+ * @property {string} [routerPrompt] - 同 WikiRouterConfig.routerPrompt
+ */
+
+/**
+ * @typedef {Object} TenantManager
+ * @property {(tenantId: string, options?: BuildOptions) => Promise<boolean>} build - 為單一租戶建構 wiki
+ * @property {() => Promise<PromiseSettledResult<boolean>[]>} buildAll - 並行建構所有租戶（需設定 listTenants）
+ * @property {(prompt: string, tenantId: string) => Promise<string>} getContext - 取得指定租戶的 wiki 上下文
+ * @property {(tenantId: string) => boolean} isBuilt - 該租戶是否已成功 build 過
+ * @property {() => string[]} listBuilt - 已成功 build 過的租戶清單
+ */
+
 export {}