@jungtz/wiki-router 1.0.4 → 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 檔案載入
@@ -20,9 +21,9 @@ function readPrompt(filename) {
   return ''
 }
 
-const SPLIT_PROMPT = readPrompt('split.md');
-const MERGE_PROMPT = readPrompt('merge.md');
-const ROUTER_PROMPT = readPrompt('router.md');
+const SPLIT_PROMPT = "# 角色：專業文件架構師 (Documentation Architect)\n\n## 任務目標\n將提供的 JSON 資料完整解析並轉換為多個獨立的 Markdown `.md` 檔案。\nJSON 可能來自 CMS、API 回應、設定檔或任何結構化資料來源。\n\n## 原始 JSON 資料\n```json\n{{context}}\n```\n\n## 處理規則：\n\n### 1. 結構識別（自動語義分析）\n- 分析 JSON 的頂層結構（object / array / 巢狀）\n- 若為巢狀物件，以**第一層 key** 作為主題分群依據（如 `data.rooms` → 房間主題、`data.location` → 地點主題）\n- 若為頂層陣列，每個元素視為獨立條目，依內容主題分組\n\n### 2. 完整性強制規則（最高優先）\n- **逐項清點**：陣列型資料必須逐一列出所有項目，先數原始 JSON 中有幾筆，輸出後再數確認數量一致\n- **巢狀陣列全收**：若某欄位本身是陣列（如設施清單、標籤列表），必須列出該陣列中的**每一項**\n- **不因長度省略**：資料再多也不能用「等」、「...」、「其他」概括\n\n### 3. 資訊提取（語義識別）\n- **標題欄位**：自動識別代表名稱/標題的欄位（`title`、`name`、`label`、`subject`）\n- **內文欄位**：自動識別長文字欄位（`content`、`description`、`body`、`intro`、`text`）\n- **時間欄位**：自動識別時間相關欄位（`time`、`date`、`checkin`、`checkout`、`created_at`、`published_at`）\n- **數值欄位**：自動識別價格/數量欄位（`price`、`qty`、`user`、`capacity`、`size`）\n- **布林欄位**：自動識別開關欄位（`enable`、`display`、`is_*`），轉為「啟用/停用」\n- **巢狀物件**：遞迴展開，保留層級結構（如 `social.{instagram_url, instagram_display}`）\n- **多語言欄位**：若欄位為 `{zh_tw, en, ja, ...}` 結構，以 `zh_tw` 為主要輸出語言，不存在時依序 fallback\n\n### 4. 格式還原\n- 若內容為 JSON 字串（Quill Delta 等 RTF 格式），解析後還原為純文字\n- 轉義換行 `\\n` → 真實換行、`\\t` → 縮排\n- 內嵌 HTML（`<a href>`, `<img>`, `<br>`）還原為對應 Markdown 語法\n- 內嵌 URL 保留為可點擊連結\n\n### 5. 檔案拆分原則\n- 依照 JSON 的**第一層 key** 或**語義主題**拆分成獨立 `.md` 檔案\n- 每個檔案涵蓋一個獨立主題區塊\n- 檔名使用英文，反映主題（如 `Rooms.md`、`Policies.md`、`Facilities.md`）\n\n### 6. 索引生成 (Index.md)\n- 彙整所有產出的檔案，生成 `Index.md`\n- 格式：`- [顯示名稱](檔名.md)：一句話摘要涵蓋的關鍵主題與具體資訊`\n- 摘要必須具體，禁止只重複檔名\n\n### 7. 輸出約束\n- **輸出順序**：先 `Index.md`，再依序輸出其他檔案\n- **必須標示檔名**：每個程式碼區塊正上方必須有 `### 檔名.md` 標題，不可省略\n- 每個檔案以獨立 ` ```markdown ` 程式碼區塊呈現\n- 所有 JSON 內容一律轉為人類可讀的 Markdown，不可保留原始 JSON 字串\n\n## 輸出格式規範：\n\n### Index.md\n```markdown\n# 知識庫目錄\n- [顯示名稱 A](A.md)：涵蓋的關鍵主題與具體資訊摘要\n- [顯示名稱 B](B.md)：涵蓋的關鍵主題與具體資訊摘要\n```\n\n---\n\n### 檔名.md\n```markdown\n[還原後的 Markdown 內容]\n```\n\n---\n\n(重複上述格式直到所有檔案輸出完畢)\n";
+const MERGE_PROMPT = "# 角色：知識庫合併架構師 (Knowledge Merge Architect)\n\n## 任務目標\n將新的內容合併到既有的知識庫檔案結構中，根據內容類型與主題智能決定「新增頁面」、「合併到既有頁面」或「更新既有頁面」。\n\n## 既有知識庫目錄 (Index.md)\n```markdown\n{{indexContent}}\n```\n\n## 新內容類型：{{fileType}}\n## 新內容\n```{{contentBlock}}\n{{newContent}}\n```\n\n## 處理規則：\n\n### 1. 結構識別（依 fileType）\n\n**json**：\n- 分析 JSON 頂層結構，以第一層 key 或語義主題分群\n- 若為巢狀物件，每個第一層 key 視為一個主題區塊\n- 若為頂層陣列，每個元素視為獨立條目\n\n**markdown**：\n- 依照 `##` 或 `###` 標題拆分成獨立區塊\n- 每個區塊視為一個新知識條目\n\n### 2. 合併策略判斷\n\n對每個條目，檢查是否與既有 Index.md 中的頁面相關：\n\n- **主題全新**（目錄中無相關頁面）→ 建立**新檔案**，Index.md 追加新條目\n- **主題已存在**（標題或關鍵詞與既有頁面重疊）→ 將新內容**合併**到既有檔案，保留既有結構，新增內容作為補充。合併後輸出該檔案的**完整內容**\n- **既有檔案缺少條目**（例如列表型資料漏了某筆）→ 必須**補齊**，將缺漏條目加入對應區塊\n- **內容衝突**（同一主題但資訊不一致，如價格變動、規則修改）→ 以**新內容為準**更新，標記 `> 更新於 YYYY-MM-DD`\n- **內容重複**（完全相同）→ 跳過，不輸出\n\n### 3. 完整性驗證\n- 陣列型資料：比對新內容的項目數與既有檔案收錄數，缺漏必須補齊\n- 巢狀陣列（如設施清單、標籤列表）：逐一檢查是否全數收錄\n- 多語言欄位：以 `zh_tw` 為主要輸出語言，不存在時 fallback 到 `en`\n- JSON 字串內容（Quill Delta 等）：`\\n` → 換行、`\\t` → 縮排、HTML → Markdown\n\n### 4. 輸出約束\n- **輸出順序**：先輸出更新後的 `Index.md`，再依序輸出所有新增或更新過的檔案\n- 每個檔案前必須有 `### 檔名.md` 作為標題，絕對不可省略\n- 每個檔案以獨立 ` ```markdown ` 程式碼區塊呈現\n- **只輸出有變動的檔案**，未修改的既有檔案不需重複輸出\n- 合併的檔案必須包含**完整內容**（既有 + 新增），不可只輸出差異\n\n## 輸出格式規範：\n\n### Index.md\n```markdown\n# 知識庫目錄\n- [顯示名稱 A](A.md)：一句話摘要涵蓋的關鍵主題\n- [顯示名稱 B](B.md)：一句話摘要涵蓋的關鍵主題\n```\n\n---\n\n### 檔名.md\n```markdown\n[完整內容]\n```\n\n---\n\n(重複上述格式直到所有變動檔案輸出完畢)\n";
+const ROUTER_PROMPT = "# 角色設定\n你是一個精準的「知識庫路由助手 (Router)」。\n你的唯一任務是分析使用者的問題，並從提供的目錄清單中，挑選出最可能包含解答的檔案名稱。\n\n# 使用者問題\n{{prompt}}\n\n# 知識庫目錄\n{{indexContent}}\n\n# 挑選原則\n- 從目錄中每個檔案的**摘要**判斷相關性，不只比對檔名\n- 考慮同義詞與相關概念（例如：「運動」「健身」→ Facilities.md；「怎麼去」「交通」→ Location_and_Transport.md）\n- 若問題涉及多個主題（如「房價和退房時間」），選取所有相關檔案\n\n# 輸出嚴格規範\n1. **僅輸出檔名**：從「知識庫目錄」中挑選最相關的完整檔案名稱（必須包含 `.md` 後綴）。\n2. **多檔處理**：若有多個檔案相關，請以半形逗號 `,` 分隔。\n3. **無相關時**：若判斷目錄中的檔案皆不相關，請直接回覆 `NONE`。\n4. **禁止任何廢話**：**絕對禁止**輸出任何解釋文字、問候語、符號，也**禁止**使用 Markdown 標記（如代碼塊 ` ``` ` 或清單 `-`）。\n\n**正確輸出範例：**\nIntroduction.md,Policy_Info.md\n";
 
 /**
  * LLM 輸出解析器
@@ -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 檔案載入
@@ -18,9 +19,9 @@ function readPrompt(filename) {
   return ''
 }
 
-const SPLIT_PROMPT = readPrompt('split.md');
-const MERGE_PROMPT = readPrompt('merge.md');
-const ROUTER_PROMPT = readPrompt('router.md');
+const SPLIT_PROMPT = "# 角色：專業文件架構師 (Documentation Architect)\n\n## 任務目標\n將提供的 JSON 資料完整解析並轉換為多個獨立的 Markdown `.md` 檔案。\nJSON 可能來自 CMS、API 回應、設定檔或任何結構化資料來源。\n\n## 原始 JSON 資料\n```json\n{{context}}\n```\n\n## 處理規則：\n\n### 1. 結構識別（自動語義分析）\n- 分析 JSON 的頂層結構（object / array / 巢狀）\n- 若為巢狀物件，以**第一層 key** 作為主題分群依據（如 `data.rooms` → 房間主題、`data.location` → 地點主題）\n- 若為頂層陣列，每個元素視為獨立條目，依內容主題分組\n\n### 2. 完整性強制規則（最高優先）\n- **逐項清點**：陣列型資料必須逐一列出所有項目，先數原始 JSON 中有幾筆，輸出後再數確認數量一致\n- **巢狀陣列全收**：若某欄位本身是陣列（如設施清單、標籤列表），必須列出該陣列中的**每一項**\n- **不因長度省略**：資料再多也不能用「等」、「...」、「其他」概括\n\n### 3. 資訊提取（語義識別）\n- **標題欄位**：自動識別代表名稱/標題的欄位（`title`、`name`、`label`、`subject`）\n- **內文欄位**：自動識別長文字欄位（`content`、`description`、`body`、`intro`、`text`）\n- **時間欄位**：自動識別時間相關欄位（`time`、`date`、`checkin`、`checkout`、`created_at`、`published_at`）\n- **數值欄位**：自動識別價格/數量欄位（`price`、`qty`、`user`、`capacity`、`size`）\n- **布林欄位**：自動識別開關欄位（`enable`、`display`、`is_*`），轉為「啟用/停用」\n- **巢狀物件**：遞迴展開，保留層級結構（如 `social.{instagram_url, instagram_display}`）\n- **多語言欄位**：若欄位為 `{zh_tw, en, ja, ...}` 結構，以 `zh_tw` 為主要輸出語言，不存在時依序 fallback\n\n### 4. 格式還原\n- 若內容為 JSON 字串（Quill Delta 等 RTF 格式），解析後還原為純文字\n- 轉義換行 `\\n` → 真實換行、`\\t` → 縮排\n- 內嵌 HTML（`<a href>`, `<img>`, `<br>`）還原為對應 Markdown 語法\n- 內嵌 URL 保留為可點擊連結\n\n### 5. 檔案拆分原則\n- 依照 JSON 的**第一層 key** 或**語義主題**拆分成獨立 `.md` 檔案\n- 每個檔案涵蓋一個獨立主題區塊\n- 檔名使用英文，反映主題（如 `Rooms.md`、`Policies.md`、`Facilities.md`）\n\n### 6. 索引生成 (Index.md)\n- 彙整所有產出的檔案，生成 `Index.md`\n- 格式：`- [顯示名稱](檔名.md)：一句話摘要涵蓋的關鍵主題與具體資訊`\n- 摘要必須具體，禁止只重複檔名\n\n### 7. 輸出約束\n- **輸出順序**：先 `Index.md`，再依序輸出其他檔案\n- **必須標示檔名**：每個程式碼區塊正上方必須有 `### 檔名.md` 標題，不可省略\n- 每個檔案以獨立 ` ```markdown ` 程式碼區塊呈現\n- 所有 JSON 內容一律轉為人類可讀的 Markdown，不可保留原始 JSON 字串\n\n## 輸出格式規範：\n\n### Index.md\n```markdown\n# 知識庫目錄\n- [顯示名稱 A](A.md)：涵蓋的關鍵主題與具體資訊摘要\n- [顯示名稱 B](B.md)：涵蓋的關鍵主題與具體資訊摘要\n```\n\n---\n\n### 檔名.md\n```markdown\n[還原後的 Markdown 內容]\n```\n\n---\n\n(重複上述格式直到所有檔案輸出完畢)\n";
+const MERGE_PROMPT = "# 角色：知識庫合併架構師 (Knowledge Merge Architect)\n\n## 任務目標\n將新的內容合併到既有的知識庫檔案結構中，根據內容類型與主題智能決定「新增頁面」、「合併到既有頁面」或「更新既有頁面」。\n\n## 既有知識庫目錄 (Index.md)\n```markdown\n{{indexContent}}\n```\n\n## 新內容類型：{{fileType}}\n## 新內容\n```{{contentBlock}}\n{{newContent}}\n```\n\n## 處理規則：\n\n### 1. 結構識別（依 fileType）\n\n**json**：\n- 分析 JSON 頂層結構，以第一層 key 或語義主題分群\n- 若為巢狀物件，每個第一層 key 視為一個主題區塊\n- 若為頂層陣列，每個元素視為獨立條目\n\n**markdown**：\n- 依照 `##` 或 `###` 標題拆分成獨立區塊\n- 每個區塊視為一個新知識條目\n\n### 2. 合併策略判斷\n\n對每個條目，檢查是否與既有 Index.md 中的頁面相關：\n\n- **主題全新**（目錄中無相關頁面）→ 建立**新檔案**，Index.md 追加新條目\n- **主題已存在**（標題或關鍵詞與既有頁面重疊）→ 將新內容**合併**到既有檔案，保留既有結構，新增內容作為補充。合併後輸出該檔案的**完整內容**\n- **既有檔案缺少條目**（例如列表型資料漏了某筆）→ 必須**補齊**，將缺漏條目加入對應區塊\n- **內容衝突**（同一主題但資訊不一致，如價格變動、規則修改）→ 以**新內容為準**更新，標記 `> 更新於 YYYY-MM-DD`\n- **內容重複**（完全相同）→ 跳過，不輸出\n\n### 3. 完整性驗證\n- 陣列型資料：比對新內容的項目數與既有檔案收錄數，缺漏必須補齊\n- 巢狀陣列（如設施清單、標籤列表）：逐一檢查是否全數收錄\n- 多語言欄位：以 `zh_tw` 為主要輸出語言，不存在時 fallback 到 `en`\n- JSON 字串內容（Quill Delta 等）：`\\n` → 換行、`\\t` → 縮排、HTML → Markdown\n\n### 4. 輸出約束\n- **輸出順序**：先輸出更新後的 `Index.md`，再依序輸出所有新增或更新過的檔案\n- 每個檔案前必須有 `### 檔名.md` 作為標題，絕對不可省略\n- 每個檔案以獨立 ` ```markdown ` 程式碼區塊呈現\n- **只輸出有變動的檔案**，未修改的既有檔案不需重複輸出\n- 合併的檔案必須包含**完整內容**（既有 + 新增），不可只輸出差異\n\n## 輸出格式規範：\n\n### Index.md\n```markdown\n# 知識庫目錄\n- [顯示名稱 A](A.md)：一句話摘要涵蓋的關鍵主題\n- [顯示名稱 B](B.md)：一句話摘要涵蓋的關鍵主題\n```\n\n---\n\n### 檔名.md\n```markdown\n[完整內容]\n```\n\n---\n\n(重複上述格式直到所有變動檔案輸出完畢)\n";
+const ROUTER_PROMPT = "# 角色設定\n你是一個精準的「知識庫路由助手 (Router)」。\n你的唯一任務是分析使用者的問題，並從提供的目錄清單中，挑選出最可能包含解答的檔案名稱。\n\n# 使用者問題\n{{prompt}}\n\n# 知識庫目錄\n{{indexContent}}\n\n# 挑選原則\n- 從目錄中每個檔案的**摘要**判斷相關性，不只比對檔名\n- 考慮同義詞與相關概念（例如：「運動」「健身」→ Facilities.md；「怎麼去」「交通」→ Location_and_Transport.md）\n- 若問題涉及多個主題（如「房價和退房時間」），選取所有相關檔案\n\n# 輸出嚴格規範\n1. **僅輸出檔名**：從「知識庫目錄」中挑選最相關的完整檔案名稱（必須包含 `.md` 後綴）。\n2. **多檔處理**：若有多個檔案相關，請以半形逗號 `,` 分隔。\n3. **無相關時**：若判斷目錄中的檔案皆不相關，請直接回覆 `NONE`。\n4. **禁止任何廢話**：**絕對禁止**輸出任何解釋文字、問候語、符號，也**禁止**使用 Markdown 標記（如代碼塊 ` ``` ` 或清單 `-`）。\n\n**正確輸出範例：**\nIntroduction.md,Policy_Info.md\n";
 
 /**
  * LLM 輸出解析器
@@ -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.4",
+  "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 上下文
  */