@jungtz/wiki-router 1.0.5 → 1.2.0

package/README.md

@@ -95,12 +95,30 @@ const wikiB = wikiOf(7)   // 旅館 B
 
 ✱ `source` 與 `knowledgeDir` 至少擇一；`store` 與 `outputDir` 至少擇一。
 
-### `wiki.build()`
+### `wiki.build(options?)`
 
 建構或增量更新 Wiki 知識庫。回傳 `Promise<boolean>`。
 
+| 選項 | 類型 | 預設 | 說明 |
+|------|------|------|------|
+| `force` | `boolean` | `false` | 為 `true` 時跳過 fingerprint 比對，無條件重新呼叫 LLM 生成 |
+
 - 首次（`store.list()` 為空）：對 JSON 來源執行 split prompt，拆分成多個 `.md`
 - 後續：使用 merge prompt，將新來源合併到既有檔案
+- **快取**：若 source 提供 `getFingerprint()` 且 store 提供 `readManifest()` / `writeManifest()`，build 會比對來源指紋，未變動時直接跳過 LLM（詳見「來源變更偵測」）
+
+### 來源變更偵測 (Fingerprint)
+
+當 source 與 store 都實作對應的選用方法時，`build()` 會自動進行內容指紋比對：
+
+1. 進入 build → 呼叫 `source.getFingerprint()` 取得當前來源指紋
+2. 呼叫 `store.readManifest()` 取得上次 build 留下的指紋
+3. 兩者相等且 store 已有檔案 → 跳過 LLM，回傳 `true`
+4. 不等 → 走原本流程，build 成功後呼叫 `store.writeManifest()` 寫入新指紋
+
+`force: true` 跳過比對直接重建。內建 `fsSource` / `fsStore` 已實作這組方法（manifest 存在 store 目錄下的 `.manifest.json`）。
+
+自訂 adapter 沒實作這些方法時，build 仍會正常執行（每次都重跑 LLM），向下相容。
 
 ### `wiki.getContext(prompt)`
 
@@ -118,6 +136,7 @@ const wikiB = wikiOf(7)   // 旅館 B
 interface Source {
   list(): Promise<string[]>                                  // 來源 key 清單
   read(key: string): Promise<{ type: 'json' | 'markdown', content: string }>
+  getFingerprint?(): Promise<Record<string, string>>         // 選用：來源指紋 { key: hash }
 }
 ```
 
@@ -128,23 +147,117 @@ interface Store {
   list(): Promise<string[]>                                  // 已生成的 wiki 檔名（含 .md）
   read(filename: string): Promise<string | null>             // 不存在回 null
   write(filename: string, content: string): Promise<void>
+  readManifest?(): Promise<Record<string, string> | null>    // 選用：讀上次 build 指紋
+  writeManifest?(m: Record<string, string>): Promise<void>   // 選用：寫本次 build 指紋
 }
 ```
 
+`getFingerprint` / `readManifest` / `writeManifest` 是選用介面，用於來源變更偵測快取。**三者必須同時實作才會啟用快取**；缺其一則 build 仍會正常執行（每次都重跑 LLM）。
+
+#### 自訂 adapter 範例（API + DB）
+
+```js
+source: {
+  async list()            { return ['base.json'] },
+  async read()            { /* fetch from API */ },
+  async getFingerprint() {
+    const res = await fetch(`/api/hotels/${hotelId}/etag`)
+    return { 'base.json': await res.text() }   // 用 ETag 當指紋
+  },
+},
+store: {
+  async list()                  { /* DB query */ },
+  async read(filename)          { /* ... */ },
+  async write(filename, body)   { /* ... */ },
+  async readManifest()          { return await db.wikiManifest.get(hotelId) },
+  async writeManifest(manifest) { await db.wikiManifest.upsert(hotelId, manifest) },
+},
+```
+
 ### 內建 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 過的租戶清單 |
+
 ## 子模組
 
 ### 解析器
@@ -201,7 +314,21 @@ npm run preview -- --knowledge ./my-knowledge --output ./my-wiki
 
 支援指令：`:list` 查看維基頁面、`:build` 重建維基、`:files` 顯示檔案、`:quit` 離開。
 
-## 發布腳本
+## 發布
+
+### 自動發布（推薦）
+
+push 到 `master` 分支時，CI 會自動掃描自上個 tag 以來的 commit message，依 gitmoji 決定 bump 類型並 publish 到 npm：
+
+| Commit message 包含 | Bump 類型 | 例 |
+|--------------------|----------|----|
+| `:boom:` 💥 / `BREAKING CHANGE` | major | 1.0.5 → 2.0.0 |
+| `:sparkles:` ✨ | minor | 1.0.5 → 1.1.0 |
+| 其他 (`:bug:` / `:hammer:` / ...) | patch | 1.0.5 → 1.0.6 |
+
+只要照常用 gitmoji 寫 commit，版號自己對齊語意。
+
+### 本地手動發布腳本（備用）
 
 ```bash
 npm run bump:patch   # 版號 patch +1 並自動 git commit + tag

package/dist/index.cjs

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 
 /**
  * LLM Wiki 提示詞 — 從 src/prompts/*.md 檔案載入
@@ -97,6 +98,8 @@ function parseWikiOutput(output) {
  */
 
 
+const MANIFEST_FILE = '.manifest.json';
+
 /**
  * 建立讀取本地檔案的 Source adapter
  * @param {string} dir - knowledge 來源目錄
@@ -104,19 +107,30 @@ function parseWikiOutput(output) {
  */
 function fsSource(dir) {
   const resolved = path.resolve(dir);
+  async function list() {
+    if (!fs.existsSync(resolved)) return []
+    return fs
+      .readdirSync(resolved)
+      .filter(f => f.endsWith('.json') || f.endsWith('.md'))
+      .sort()
+  }
+  async function read(key) {
+    const filePath = path.join(resolved, key);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const type = key.endsWith('.json') ? 'json' : 'markdown';
+    return { type, content }
+  }
   return {
-    async list() {
-      if (!fs.existsSync(resolved)) return []
-      return fs
-        .readdirSync(resolved)
-        .filter(f => f.endsWith('.json') || f.endsWith('.md'))
-        .sort()
-    },
-    async read(key) {
-      const filePath = path.join(resolved, key);
-      const content = fs.readFileSync(filePath, 'utf-8');
-      const type = key.endsWith('.json') ? 'json' : 'markdown';
-      return { type, content }
+    list,
+    read,
+    async getFingerprint() {
+      const keys = await list();
+      const fp = {};
+      for (const key of keys) {
+        const { content } = await read(key);
+        fp[key] = crypto.createHash('sha256').update(content).digest('hex');
+      }
+      return fp
     },
   }
 }
@@ -145,17 +159,29 @@ function fsStore(dir) {
       ensure();
       fs.writeFileSync(path.join(resolved, filename), content);
     },
+    async readManifest() {
+      const filePath = path.join(resolved, MANIFEST_FILE);
+      if (!fs.existsSync(filePath)) return null
+      try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'))
+      } catch {
+        return null
+      }
+    },
+    async writeManifest(manifest) {
+      ensure();
+      fs.writeFileSync(
+        path.join(resolved, MANIFEST_FILE),
+        JSON.stringify(manifest, null, 2),
+        'utf-8'
+      );
+    },
   }
 }
 
 /**
- * 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 的循環依賴。
  */
 
 
@@ -196,10 +222,6 @@ function createWikiRouter(config) {
 
   let modelsFetched = false;
 
-  /**
-   * 預先獲取本地模型清單（仿照 models.js 的 getModelsList 邏輯）
-   * 確保 switchModel 能識別動態發現的 local 模型
-   */
   async function ensureModels() {
     if (modelsFetched) return
     try {
@@ -212,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,
           }));
         }
       });
@@ -222,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;
@@ -243,7 +258,6 @@ function createWikiRouter(config) {
         modelName = parts.slice(1).join('/');
       }
 
-      // 使用 AI Router 進行對話
       if (router && provider) {
         await ensureModels();
         await router.switchModel(provider, modelName);
@@ -268,11 +282,16 @@ function createWikiRouter(config) {
     }
   }
 
-  /**
-   * 建構或更新 LLM Wiki 知識庫
-   * @returns {Promise<boolean>}
-   */
-  async function build() {
+  function fingerprintsEqual(a, b) {
+    if (!a || !b) return false
+    const ak = Object.keys(a);
+    const bk = Object.keys(b);
+    if (ak.length !== bk.length) return false
+    return ak.every(k => a[k] === b[k])
+  }
+
+  async function build(options = {}) {
+    const { force = false } = options;
     try {
       const knowledgeKeys = await activeSource.list();
 
@@ -281,6 +300,24 @@ function createWikiRouter(config) {
         return false
       }
 
+      let currentFp = null;
+      const sourceSupportsFp = typeof activeSource.getFingerprint === 'function';
+      const storeSupportsManifest =
+        typeof activeStore.readManifest === 'function' &&
+        typeof activeStore.writeManifest === 'function';
+
+      if (sourceSupportsFp && storeSupportsManifest) {
+        currentFp = await activeSource.getFingerprint();
+        if (!force) {
+          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)');
+            return true
+          }
+        }
+      }
+
       let totalFiles = 0;
 
       for (const key of knowledgeKeys) {
@@ -322,6 +359,11 @@ function createWikiRouter(config) {
       }
 
       if (totalFiles === 0) return false
+
+      if (currentFp && storeSupportsManifest) {
+        await activeStore.writeManifest(currentFp);
+      }
+
       return true
     } catch (err) {
       console.error('[Wiki Generation Error]', err);
@@ -329,11 +371,6 @@ function createWikiRouter(config) {
     }
   }
 
-  /**
-   * 根據使用者問題取得相關的 Wiki 上下文
-   * @param {string} prompt - 使用者問題
-   * @returns {Promise<string>}
-   */
   async function getContext(prompt) {
     try {
       let wikiFiles = await activeStore.list();
@@ -354,11 +391,15 @@ function createWikiRouter(config) {
         .replace('{{indexContent}}', indexContent);
 
       const routeModel = routerModelId || process.env.WIKI_ROUTER_MODEL || modelId || process.env.WIKI_MODEL;
-      const output = await chat(
-        [{ role: 'user', content: selectionPrompt }],
-        routeModel
-      );
-      if (!output) return ''
+      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);
+      }
+      if (!output) {
+        console.warn('[Wiki] Router LLM returned empty after retry.');
+        return ''
+      }
 
       const selectedFilesStr = output.trim();
       if (selectedFilesStr === 'NONE' || !selectedFilesStr) {
@@ -382,7 +423,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);
     }
@@ -392,10 +432,275 @@ 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 = '# 知識庫目錄';
+
+/**
+ * @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 promise = (async () => {
+      const { wiki, store } = getWiki(tenantId);
+      const ok = await wiki.build({ force });
+      if (!ok) 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);
+      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 []
+    }
+    logger.log && logger.log(`[Wiki] Pre-building ${tenants.length} tenant(s): ${tenants.join(', ')}`);
+    const results = await Promise.allSettled(tenants.map(t => build(t)));
+    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

@@ -12,6 +12,7 @@
  * @typedef {Object} Source
  * @property {() => Promise<string[]>} list - 列出所有 knowledge 來源 key（檔名 / DB id）
  * @property {(key: string) => Promise<SourceEntry>} read - 讀取單一來源內容
+ * @property {() => Promise<Record<string, string>>} [getFingerprint] - 選用；回傳來源指紋（如 { key: hash }）供 build 判斷是否需要重新生成
  */
 
 /**
@@ -19,6 +20,8 @@
  * @property {() => Promise<string[]>} list - 列出已生成的 wiki 檔名（含副檔名）
  * @property {(filename: string) => Promise<string|null>} read - 讀取 wiki 檔；不存在回 null
  * @property {(filename: string, content: string) => Promise<void>} write - 寫入 wiki 檔
+ * @property {() => Promise<Record<string, string>|null>} [readManifest] - 選用；讀取上次 build 的來源指紋；不存在回 null
+ * @property {(manifest: Record<string, string>) => Promise<void>} [writeManifest] - 選用；寫入本次 build 的來源指紋
  */
 
 /**
@@ -36,9 +39,14 @@
  * @property {string} [routerPrompt] - 自訂 Router prompt 字串，未提供時使用內建預設
  */
 
+/**
+ * @typedef {Object} BuildOptions
+ * @property {boolean} [force=false] - 為 true 時跳過 fingerprint 比對，無條件重建
+ */
+
 /**
  * @typedef {Object} WikiRouterInstance
- * @property {() => Promise<boolean>} build - 建構或更新 Wiki 知識庫
+ * @property {(options?: BuildOptions) => Promise<boolean>} build - 建構或更新 Wiki 知識庫
  * @property {(prompt: string) => Promise<string>} getContext - 根據問題取得相關 Wiki 上下文
  */
 
@@ -48,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

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import path from 'path';
+import crypto from 'crypto';
 
 /**
  * LLM Wiki 提示詞 — 從 src/prompts/*.md 檔案載入
@@ -95,6 +96,8 @@ function parseWikiOutput(output) {
  */
 
 
+const MANIFEST_FILE = '.manifest.json';
+
 /**
  * 建立讀取本地檔案的 Source adapter
  * @param {string} dir - knowledge 來源目錄
@@ -102,19 +105,30 @@ function parseWikiOutput(output) {
  */
 function fsSource(dir) {
   const resolved = path.resolve(dir);
+  async function list() {
+    if (!fs.existsSync(resolved)) return []
+    return fs
+      .readdirSync(resolved)
+      .filter(f => f.endsWith('.json') || f.endsWith('.md'))
+      .sort()
+  }
+  async function read(key) {
+    const filePath = path.join(resolved, key);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const type = key.endsWith('.json') ? 'json' : 'markdown';
+    return { type, content }
+  }
   return {
-    async list() {
-      if (!fs.existsSync(resolved)) return []
-      return fs
-        .readdirSync(resolved)
-        .filter(f => f.endsWith('.json') || f.endsWith('.md'))
-        .sort()
-    },
-    async read(key) {
-      const filePath = path.join(resolved, key);
-      const content = fs.readFileSync(filePath, 'utf-8');
-      const type = key.endsWith('.json') ? 'json' : 'markdown';
-      return { type, content }
+    list,
+    read,
+    async getFingerprint() {
+      const keys = await list();
+      const fp = {};
+      for (const key of keys) {
+        const { content } = await read(key);
+        fp[key] = crypto.createHash('sha256').update(content).digest('hex');
+      }
+      return fp
     },
   }
 }
@@ -143,17 +157,29 @@ function fsStore(dir) {
       ensure();
       fs.writeFileSync(path.join(resolved, filename), content);
     },
+    async readManifest() {
+      const filePath = path.join(resolved, MANIFEST_FILE);
+      if (!fs.existsSync(filePath)) return null
+      try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'))
+      } catch {
+        return null
+      }
+    },
+    async writeManifest(manifest) {
+      ensure();
+      fs.writeFileSync(
+        path.join(resolved, MANIFEST_FILE),
+        JSON.stringify(manifest, null, 2),
+        'utf-8'
+      );
+    },
   }
 }
 
 /**
- * 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 的循環依賴。
  */
 
 
@@ -194,10 +220,6 @@ function createWikiRouter(config) {
 
   let modelsFetched = false;
 
-  /**
-   * 預先獲取本地模型清單（仿照 models.js 的 getModelsList 邏輯）
-   * 確保 switchModel 能識別動態發現的 local 模型
-   */
   async function ensureModels() {
     if (modelsFetched) return
     try {
@@ -210,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,
           }));
         }
       });
@@ -220,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;
@@ -241,7 +256,6 @@ function createWikiRouter(config) {
         modelName = parts.slice(1).join('/');
       }
 
-      // 使用 AI Router 進行對話
       if (router && provider) {
         await ensureModels();
         await router.switchModel(provider, modelName);
@@ -266,11 +280,16 @@ function createWikiRouter(config) {
     }
   }
 
-  /**
-   * 建構或更新 LLM Wiki 知識庫
-   * @returns {Promise<boolean>}
-   */
-  async function build() {
+  function fingerprintsEqual(a, b) {
+    if (!a || !b) return false
+    const ak = Object.keys(a);
+    const bk = Object.keys(b);
+    if (ak.length !== bk.length) return false
+    return ak.every(k => a[k] === b[k])
+  }
+
+  async function build(options = {}) {
+    const { force = false } = options;
     try {
       const knowledgeKeys = await activeSource.list();
 
@@ -279,6 +298,24 @@ function createWikiRouter(config) {
         return false
       }
 
+      let currentFp = null;
+      const sourceSupportsFp = typeof activeSource.getFingerprint === 'function';
+      const storeSupportsManifest =
+        typeof activeStore.readManifest === 'function' &&
+        typeof activeStore.writeManifest === 'function';
+
+      if (sourceSupportsFp && storeSupportsManifest) {
+        currentFp = await activeSource.getFingerprint();
+        if (!force) {
+          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)');
+            return true
+          }
+        }
+      }
+
       let totalFiles = 0;
 
       for (const key of knowledgeKeys) {
@@ -320,6 +357,11 @@ function createWikiRouter(config) {
       }
 
       if (totalFiles === 0) return false
+
+      if (currentFp && storeSupportsManifest) {
+        await activeStore.writeManifest(currentFp);
+      }
+
       return true
     } catch (err) {
       console.error('[Wiki Generation Error]', err);
@@ -327,11 +369,6 @@ function createWikiRouter(config) {
     }
   }
 
-  /**
-   * 根據使用者問題取得相關的 Wiki 上下文
-   * @param {string} prompt - 使用者問題
-   * @returns {Promise<string>}
-   */
   async function getContext(prompt) {
     try {
       let wikiFiles = await activeStore.list();
@@ -352,11 +389,15 @@ function createWikiRouter(config) {
         .replace('{{indexContent}}', indexContent);
 
       const routeModel = routerModelId || process.env.WIKI_ROUTER_MODEL || modelId || process.env.WIKI_MODEL;
-      const output = await chat(
-        [{ role: 'user', content: selectionPrompt }],
-        routeModel
-      );
-      if (!output) return ''
+      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);
+      }
+      if (!output) {
+        console.warn('[Wiki] Router LLM returned empty after retry.');
+        return ''
+      }
 
       const selectedFilesStr = output.trim();
       if (selectedFilesStr === 'NONE' || !selectedFilesStr) {
@@ -380,7 +421,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);
     }
@@ -390,4 +430,266 @@ 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 = '# 知識庫目錄';
+
+/**
+ * @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 promise = (async () => {
+      const { wiki, store } = getWiki(tenantId);
+      const ok = await wiki.build({ force });
+      if (!ok) 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);
+      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 []
+    }
+    logger.log && logger.log(`[Wiki] Pre-building ${tenants.length} tenant(s): ${tenants.join(', ')}`);
+    const results = await Promise.allSettled(tenants.map(t => build(t)));
+    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.0.5",
+  "version": "1.2.0",
   "description": "LLM Wiki 知識庫路由引擎 - 將結構化知識轉為 Markdown 維基，智慧路由查詢",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",

package/src/types.d.ts

@@ -12,6 +12,7 @@
  * @typedef {Object} Source
  * @property {() => Promise<string[]>} list - 列出所有 knowledge 來源 key（檔名 / DB id）
  * @property {(key: string) => Promise<SourceEntry>} read - 讀取單一來源內容
+ * @property {() => Promise<Record<string, string>>} [getFingerprint] - 選用；回傳來源指紋（如 { key: hash }）供 build 判斷是否需要重新生成
  */
 
 /**
@@ -19,6 +20,8 @@
  * @property {() => Promise<string[]>} list - 列出已生成的 wiki 檔名（含副檔名）
  * @property {(filename: string) => Promise<string|null>} read - 讀取 wiki 檔；不存在回 null
  * @property {(filename: string, content: string) => Promise<void>} write - 寫入 wiki 檔
+ * @property {() => Promise<Record<string, string>|null>} [readManifest] - 選用；讀取上次 build 的來源指紋；不存在回 null
+ * @property {(manifest: Record<string, string>) => Promise<void>} [writeManifest] - 選用；寫入本次 build 的來源指紋
  */
 
 /**
@@ -36,9 +39,14 @@
  * @property {string} [routerPrompt] - 自訂 Router prompt 字串，未提供時使用內建預設
  */
 
+/**
+ * @typedef {Object} BuildOptions
+ * @property {boolean} [force=false] - 為 true 時跳過 fingerprint 比對，無條件重建
+ */
+
 /**
  * @typedef {Object} WikiRouterInstance
- * @property {() => Promise<boolean>} build - 建構或更新 Wiki 知識庫
+ * @property {(options?: BuildOptions) => Promise<boolean>} build - 建構或更新 Wiki 知識庫
  * @property {(prompt: string) => Promise<string>} getContext - 根據問題取得相關 Wiki 上下文
  */
 
@@ -48,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 {}