@jungtz/wiki-router 1.0.5 → 1.1.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,9 +147,33 @@ 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
@@ -201,7 +244,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,6 +159,23 @@ 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'
+      );
+    },
   }
 }
 
@@ -268,11 +299,28 @@ function createWikiRouter(config) {
     }
   }
 
+  /**
+   * 比對兩個 fingerprint 字典是否完全一致
+   * @param {Record<string,string>|null|undefined} a
+   * @param {Record<string,string>|null|undefined} b
+   * @returns {boolean}
+   */
+  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])
+  }
+
   /**
    * 建構或更新 LLM Wiki 知識庫
+   * @param {{ force?: boolean }} [options]
+   *   force=true 時跳過 fingerprint 比對，無條件重建
    * @returns {Promise<boolean>}
    */
-  async function build() {
+  async function build(options = {}) {
+    const { force = false } = options;
     try {
       const knowledgeKeys = await activeSource.list();
 
@@ -281,6 +329,25 @@ function createWikiRouter(config) {
         return false
       }
 
+      // Fingerprint cache: 若來源未變動且既有 wiki 存在，直接跳過 LLM
+      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 +389,12 @@ function createWikiRouter(config) {
       }
 
       if (totalFiles === 0) return false
+
+      // build 成功 → 寫入 manifest 供下次比對
+      if (currentFp && storeSupportsManifest) {
+        await activeStore.writeManifest(currentFp);
+      }
+
       return true
     } catch (err) {
       console.error('[Wiki Generation Error]', err);
@@ -354,11 +427,22 @@ function createWikiRouter(config) {
         .replace('{{indexContent}}', indexContent);
 
       const routeModel = routerModelId || process.env.WIKI_ROUTER_MODEL || modelId || process.env.WIKI_MODEL;
-      const output = await chat(
+      let output = await chat(
         [{ role: 'user', content: selectionPrompt }],
         routeModel
       );
-      if (!output) return ''
+      // Cloud LLM (e.g. Gemini) 偶爾會回空 stream，retry 一次
+      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) {

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 上下文
  */
 

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,6 +157,23 @@ 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'
+      );
+    },
   }
 }
 
@@ -266,11 +297,28 @@ function createWikiRouter(config) {
     }
   }
 
+  /**
+   * 比對兩個 fingerprint 字典是否完全一致
+   * @param {Record<string,string>|null|undefined} a
+   * @param {Record<string,string>|null|undefined} b
+   * @returns {boolean}
+   */
+  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])
+  }
+
   /**
    * 建構或更新 LLM Wiki 知識庫
+   * @param {{ force?: boolean }} [options]
+   *   force=true 時跳過 fingerprint 比對，無條件重建
    * @returns {Promise<boolean>}
    */
-  async function build() {
+  async function build(options = {}) {
+    const { force = false } = options;
     try {
       const knowledgeKeys = await activeSource.list();
 
@@ -279,6 +327,25 @@ function createWikiRouter(config) {
         return false
       }
 
+      // Fingerprint cache: 若來源未變動且既有 wiki 存在，直接跳過 LLM
+      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 +387,12 @@ function createWikiRouter(config) {
       }
 
       if (totalFiles === 0) return false
+
+      // build 成功 → 寫入 manifest 供下次比對
+      if (currentFp && storeSupportsManifest) {
+        await activeStore.writeManifest(currentFp);
+      }
+
       return true
     } catch (err) {
       console.error('[Wiki Generation Error]', err);
@@ -352,11 +425,22 @@ function createWikiRouter(config) {
         .replace('{{indexContent}}', indexContent);
 
       const routeModel = routerModelId || process.env.WIKI_ROUTER_MODEL || modelId || process.env.WIKI_MODEL;
-      const output = await chat(
+      let output = await chat(
         [{ role: 'user', content: selectionPrompt }],
         routeModel
       );
-      if (!output) return ''
+      // Cloud LLM (e.g. Gemini) 偶爾會回空 stream，retry 一次
+      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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jungtz/wiki-router",
-  "version": "1.0.5",
+  "version": "1.1.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 上下文
  */