@jungtz/wiki-router 1.0.2 → 1.0.5

package/README.md

@@ -14,84 +14,142 @@ npm install @jungtz/wiki-router
 ## 運作流程
 
 ```
-知識檔案 (JSON/MD) -> build() -> LLM 生成 Wiki (.md) -> getContext(prompt) -> LLM 路由 -> 相關上下文
+知識來源 -> build() -> LLM 生成 Wiki -> getContext(prompt) -> LLM 路由 -> 相關上下文
 ```
 
-1. **build()**: 將知識庫目錄中的 JSON/Markdown 檔案送交 LLM，拆分成結構化 `.md` 維基頁面
+1. **build()**: 將知識來源 (JSON/Markdown) 送交 LLM，拆分成結構化 `.md` 維基頁面
 2. **getContext(prompt)**: 根據使用者問題，由 LLM 從 Index.md 中選擇相關檔案，回傳合併後的上下文
 
-## 使用方法
+知識的「來源」與 wiki 的「儲存位置」皆透過 **adapter** 介面抽象，可使用內建檔案系統 adapter，亦可自訂 (例如 API + 資料庫)，方便支援多租戶 / 多資料集場景。
+
+## 快速開始（檔案系統）
 
 ```js
 const { createWikiRouter } = require('@jungtz/wiki-router')
 const { createRouter } = require('@jungtz/ai-router')
 
-// 1. 準備 AI Router
 const router = createRouter({
   providers: {
-    'ollama-local': {
-      type: 'local',
-      baseURL: 'http://localhost:11434',
-    },
+    'ollama-local': { type: 'local', baseURL: 'http://localhost:11434' },
   },
 })
 
-// 2. 建立 WikiRouter
 const wiki = createWikiRouter({
-  router,                              // AI Router 實例 (required)
-  knowledgeDir: './knowledge',         // 知識檔案來源目錄 (required)
-  outputDir: './wiki-output',          // Wiki 輸出目錄 (required)
-  modelId: 'ollama-local/gemma4:31b',  // Wiki 生成模型 (可選)
-  routerModelId: 'ollama-local/gemma4:31b', // 路由選擇模型 (可選)
-
+  router,
+  knowledgeDir: './knowledge',          // fs 來源（簡寫）
+  outputDir:    './wiki-output',        // fs 儲存（簡寫）
+  modelId:      'ollama-local/gemma4:31b',
 })
 
-// 3. 建構/更新 Wiki
 await wiki.build()
-
-// 4. 查詢相關上下文
 const ctx = await wiki.getContext('住宿有什麼規定？')
-console.log(ctx)
+```
+
+## 進階：自訂 adapter（多租戶 / API + DB）
+
+當知識來自 API、wiki 要存到資料庫時，傳入 `source` / `store` adapter：
+
+```js
+const { createWikiRouter } = require('@jungtz/wiki-router')
+
+function wikiOf(hotelId) {
+  return createWikiRouter({
+    router,
+    modelId: 'ollama-local/gemma4:31b',
+    source: {
+      async list() { return ['base.json'] },
+      async read() {
+        const res = await fetch(`/api/hotels/${hotelId}/knowledge`)
+        return { type: 'json', content: await res.text() }
+      },
+    },
+    store: {
+      async list()             { return await db.wiki.list(hotelId) },
+      async read(filename)     { return await db.wiki.read(hotelId, filename) },
+      async write(name, body)  { await db.wiki.upsert(hotelId, name, body) },
+    },
+  })
+}
+
+const wikiA = wikiOf(4)   // 旅館 A
+const wikiB = wikiOf(7)   // 旅館 B
 ```
 
 ## API
 
 ### `createWikiRouter(config)`
 
-建立 WikiRouter 實例。
-
 | 參數 | 類型 | 必要 | 說明 |
 |------|------|------|------|
 | `router` | `AIProviderRouter` | ✅ | AI Router 實例 |
-| `knowledgeDir` | `string` | ✅ | 知識檔案來源目錄 |
-| `outputDir` | `string` | ✅ | Wiki 輸出目錄 |
+| `source` | `Source` | ✱ | Knowledge 來源 adapter（與 `knowledgeDir` 二選一） |
+| `store` | `Store` | ✱ | Wiki 儲存 adapter（與 `outputDir` 二選一） |
+| `knowledgeDir` | `string` | ✱ | 簡寫：等同 `source: fsSource(dir)` |
+| `outputDir` | `string` | ✱ | 簡寫：等同 `store: fsStore(dir)` |
 | `modelId` | `string` | | Wiki 生成模型，格式 `provider/model` |
 | `routerModelId` | `string` | | 路由選擇模型，預設同 `modelId` |
 | `timeout` | `number` | | LLM 對話逾時毫秒數，預設 `300000` (5 分鐘) |
+| `splitPrompt` | `string` | | 自訂 Split prompt |
+| `mergePrompt` | `string` | | 自訂 Merge prompt |
+| `routerPrompt` | `string` | | 自訂 Router prompt |
 
+✱ `source` 與 `knowledgeDir` 至少擇一；`store` 與 `outputDir` 至少擇一。
 
 ### `wiki.build()`
 
 建構或增量更新 Wiki 知識庫。回傳 `Promise<boolean>`。
 
-- 首次執行：為每個 JSON 檔案執行 split prompt，拆分成多個 `.md`
-- 後續執行：使用 merge prompt，將新內容合併到既有檔案
+- 首次（`store.list()` 為空）：對 JSON 來源執行 split prompt，拆分成多個 `.md`
+- 後續：使用 merge prompt，將新來源合併到既有檔案
 
 ### `wiki.getContext(prompt)`
 
 根據使用者問題取得相關 Wiki 上下文。回傳 `Promise<string>`。
 
-- 若 Wiki 目錄為空，自動調用 `build()`
-- 由 LLM 根據 Index.md 選擇最相關的檔案
-- 回傳合併後的 Markdown 內容，無相關檔案時回傳空字串
+- 若 store 為空，自動調用 `build()`
+- 由 LLM 根據 `Index.md` 選擇最相關的檔案
+- 回傳合併後的 Markdown 內容；無相關檔案時回傳空字串
+
+## Adapter 介面
+
+### `Source`
+
+```ts
+interface Source {
+  list(): Promise<string[]>                                  // 來源 key 清單
+  read(key: string): Promise<{ type: 'json' | 'markdown', content: string }>
+}
+```
+
+### `Store`
+
+```ts
+interface Store {
+  list(): Promise<string[]>                                  // 已生成的 wiki 檔名（含 .md）
+  read(filename: string): Promise<string | null>             // 不存在回 null
+  write(filename: string, content: string): Promise<void>
+}
+```
+
+### 內建 adapter
+
+```js
+import { fsSource, fsStore } from '@jungtz/wiki-router'
+
+createWikiRouter({
+  router,
+  source: fsSource('./knowledge'),
+  store:  fsStore('./wiki-output'),
+})
+```
+
+`knowledgeDir` / `outputDir` 簡寫即在內部分別包成 `fsSource` / `fsStore`。
 
 ## 子模組
 
 ### 解析器
 
 ```js
-const { parseWikiOutput } = require('@jungtz/wiki-router')
-// 或
 import { parseWikiOutput } from '@jungtz/wiki-router/parser'
 
 const files = parseWikiOutput(llmResponse)
@@ -100,23 +158,35 @@ const files = parseWikiOutput(llmResponse)
 
 ### 提示詞模板
 
+三個內建 prompt 定義於 `src/prompts/*.md`，build 時自動 inline 進 dist：
+
+| 檔案 | 匯出名稱 | 用途 |
+|------|----------|------|
+| `src/prompts/split.md` | `SPLIT_PROMPT` | 將 JSON 資料拆分為多個 `.md` 檔案 |
+| `src/prompts/merge.md` | `MERGE_PROMPT` | 將新內容合併到既有 Wiki 檔案 |
+| `src/prompts/router.md` | `ROUTER_PROMPT` | 根據使用者問題選擇相關檔案 |
+
 ```js
 import { SPLIT_PROMPT, MERGE_PROMPT, ROUTER_PROMPT } from '@jungtz/wiki-router/prompts'
 ```
 
-## 知識庫目錄結構
+#### 自訂 Prompt
 
+於 `createWikiRouter` 設定中傳入 `splitPrompt` / `mergePrompt` / `routerPrompt` 字串可在 runtime 動態覆蓋；不傳則使用內建預設。
+
+```js
+const wiki = createWikiRouter({
+  router,
+  knowledgeDir: './knowledge',
+  outputDir:    './wiki-output',
+  mergePrompt:  readFileSync('./my-custom-merge.md', 'utf-8'),
+})
 ```
-my-project/
-├── knowledge/          # 放入 JSON 或 Markdown 知識檔案
-│   ├── base.json
-│   └── faq.md
-├── wiki-output/        # build() 後自動生成
-│   ├── Index.md
-│   ├── Rooms.md
-│   ├── Facilities.md
-│   └── ...
-```
+
+## 範例
+
+- `examples/basic.js` — 檔案系統用法
+- `examples/multi-tenant.js` — 多租戶 (API + DB) 用法
 
 ## 互動預覽
 

package/dist/index.cjs

@@ -4,179 +4,25 @@ const fs = require('fs');
 const path = require('path');
 
 /**
- * 內嵌 LLM Wiki 提示詞模板
- * 與原始 server/prompts/ 目錄中的檔案保持同步
+ * LLM Wiki 提示詞 — 從 src/prompts/*.md 檔案載入
+ * 欲修改提示詞內容，請直接編輯對應的 .md 檔案
  */
 
-const SPLIT_PROMPT = `# 角色：專業文件架構師 (Documentation Architect)
 
-## 任務目標
-將提供的 JSON 資料完整解析並轉換為多個獨立的 Markdown \`.md\` 檔案。
-JSON 可能來自 CMS、API 回應、設定檔或任何結構化資料來源。
+const PROMPTS_DIR = path.resolve(undefined || __dirname, 'prompts');
 
-## 原始 JSON 資料
-\`\`\`json
-{{context}}
-\`\`\`
-
-## 處理規則：
-
-### 1. 結構識別（自動語義分析）
-- 分析 JSON 的頂層結構（object / array / 巢狀）
-- 若為巢狀物件，以**第一層 key** 作為主題分群依據（如 \`data.rooms\` → 房間主題、\`data.location\` → 地點主題）
-- 若為頂層陣列，每個元素視為獨立條目，依內容主題分組
-
-### 2. 完整性強制規則（最高優先）
-- **逐項清點**：陣列型資料必須逐一列出所有項目，先數原始 JSON 中有幾筆，輸出後再數確認數量一致
-- **巢狀陣列全收**：若某欄位本身是陣列（如設施清單、標籤列表），必須列出該陣列中的**每一項**
-- **不因長度省略**：資料再多也不能用「等」、「...」、「其他」概括
-
-### 3. 資訊提取（語義識別）
-- **標題欄位**：自動識別代表名稱/標題的欄位（\`title\`、\`name\`、\`label\`、\`subject\`）
-- **內文欄位**：自動識別長文字欄位（\`content\`、\`description\`、\`body\`、\`intro\`、\`text\`）
-- **時間欄位**：自動識別時間相關欄位（\`time\`、\`date\`、\`checkin\`、\`checkout\`、\`created_at\`、\`published_at\`）
-- **數值欄位**：自動識別價格/數量欄位（\`price\`、\`qty\`、\`user\`、\`capacity\`、\`size\`）
-- **布林欄位**：自動識別開關欄位（\`enable\`、\`display\`、\`is_*\`），轉為「啟用/停用」
-- **巢狀物件**：遞迴展開，保留層級結構（如 \`social.{instagram_url, instagram_display}\`）
-- **多語言欄位**：若欄位為 \`{zh_tw, en, ja, ...}\` 結構，以 \`zh_tw\` 為主要輸出語言，不存在時依序 fallback
-
-### 4. 格式還原
-- 若內容為 JSON 字串（Quill Delta 等 RTF 格式），解析後還原為純文字
-- 轉義換行 \`\\n\` → 真實換行、\`\\t\` → 縮排
-- 內嵌 HTML（\`<a href>\`, \`<img>\`, \`<br>\`）還原為對應 Markdown 語法
-- 內嵌 URL 保留為可點擊連結
-
-### 5. 檔案拆分原則
-- 依照 JSON 的**第一層 key** 或**語義主題**拆分成獨立 \`.md\` 檔案
-- 每個檔案涵蓋一個獨立主題區塊
-- 檔名使用英文，反映主題（如 \`Rooms.md\`、\`Policies.md\`、\`Facilities.md\`）
-
-### 6. 索引生成 (Index.md)
-- 彙整所有產出的檔案，生成 \`Index.md\`
-- 格式：\`- [顯示名稱](檔名.md)：一句話摘要涵蓋的關鍵主題與具體資訊\`
-- 摘要必須具體，禁止只重複檔名
-
-### 7. 輸出約束
-- **輸出順序**：先 \`Index.md\`，再依序輸出其他檔案
-- **必須標示檔名**：每個程式碼區塊正上方必須有 \`### 檔名.md\` 標題，不可省略
-- 每個檔案以獨立 \` \`\`\`markdown \` 程式碼區塊呈現
-- 所有 JSON 內容一律轉為人類可讀的 Markdown，不可保留原始 JSON 字串
-
-## 輸出格式規範：
-
-### Index.md
-\`\`\`markdown
-# 知識庫目錄
-- [顯示名稱 A](A.md)：涵蓋的關鍵主題與具體資訊摘要
-- [顯示名稱 B](B.md)：涵蓋的關鍵主題與具體資訊摘要
-\`\`\`
-
----
-
-### 檔名.md
-\`\`\`markdown
-[還原後的 Markdown 內容]
-\`\`\`
-
----
-
-(重複上述格式直到所有檔案輸出完畢)`;
-
-const MERGE_PROMPT = `# 角色：知識庫合併架構師 (Knowledge Merge Architect)
-
-## 任務目標
-將新的內容合併到既有的知識庫檔案結構中，根據內容類型與主題智能決定「新增頁面」、「合併到既有頁面」或「更新既有頁面」。
-
-## 既有知識庫目錄 (Index.md)
-\`\`\`markdown
-{{indexContent}}
-\`\`\`
-
-## 新內容類型：{{fileType}}
-## 新內容
-\`\`\`{{contentBlock}}
-{{newContent}}
-\`\`\`
-
-## 處理規則：
-
-### 1. 結構識別（依 fileType）
-
-**json**：
-- 分析 JSON 頂層結構，以第一層 key 或語義主題分群
-- 若為巢狀物件，每個第一層 key 視為一個主題區塊
-- 若為頂層陣列，每個元素視為獨立條目
-
-**markdown**：
-- 依照 \`##\` 或 \`###\` 標題拆分成獨立區塊
-- 每個區塊視為一個新知識條目
-
-### 2. 合併策略判斷
-
-對每個條目，檢查是否與既有 Index.md 中的頁面相關：
-
-- **主題全新**（目錄中無相關頁面）→ 建立**新檔案**，Index.md 追加新條目
-- **主題已存在**（標題或關鍵詞與既有頁面重疊）→ 將新內容**合併**到既有檔案，保留既有結構，新增內容作為補充。合併後輸出該檔案的**完整內容**
-- **既有檔案缺少條目**（例如列表型資料漏了某筆）→ 必須**補齊**，將缺漏條目加入對應區塊
-- **內容衝突**（同一主題但資訊不一致，如價格變動、規則修改）→ 以**新內容為準**更新，標記 \`> 更新於 YYYY-MM-DD\`
-- **內容重複**（完全相同）→ 跳過，不輸出
-
-### 3. 完整性驗證
-- 陣列型資料：比對新內容的項目數與既有檔案收錄數，缺漏必須補齊
-- 巢狀陣列（如設施清單、標籤列表）：逐一檢查是否全數收錄
-- 多語言欄位：以 \`zh_tw\` 為主要輸出語言，不存在時 fallback 到 \`en\`
-- JSON 字串內容（Quill Delta 等）：\`\\n\` → 換行、\`\\t\` → 縮排、HTML → Markdown
-
-### 4. 輸出約束
-- **輸出順序**：先輸出更新後的 \`Index.md\`，再依序輸出所有新增或更新過的檔案
-- 每個檔案前必須有 \`### 檔名.md\` 作為標題，絕對不可省略
-- 每個檔案以獨立 \` \`\`\`markdown \` 程式碼區塊呈現
-- **只輸出有變動的檔案**，未修改的既有檔案不需重複輸出
-- 合併的檔案必須包含**完整內容**（既有 + 新增），不可只輸出差異
-
-## 輸出格式規範：
-
-### Index.md
-\`\`\`markdown
-# 知識庫目錄
-- [顯示名稱 A](A.md)：一句話摘要涵蓋的關鍵主題
-- [顯示名稱 B](B.md)：一句話摘要涵蓋的關鍵主題
-\`\`\`
-
----
-
-### 檔名.md
-\`\`\`markdown
-[完整內容]
-\`\`\`
-
----
-
-(重複上述格式直到所有變動檔案輸出完畢)`;
-
-const ROUTER_PROMPT = `# 角色設定
-你是一個精準的「知識庫路由助手 (Router)」。
-你的唯一任務是分析使用者的問題，並從提供的目錄清單中，挑選出最可能包含解答的檔案名稱。
-
-# 使用者問題
-{{prompt}}
-
-# 知識庫目錄
-{{indexContent}}
-
-# 挑選原則
-- 從目錄中每個檔案的**摘要**判斷相關性，不只比對檔名
-- 考慮同義詞與相關概念（例如：「運動」「健身」→ Facilities.md；「怎麼去」「交通」→ Location_and_Transport.md）
-- 若問題涉及多個主題（如「房價和退房時間」），選取所有相關檔案
-
-# 輸出嚴格規範
-1. **僅輸出檔名**：從「知識庫目錄」中挑選最相關的完整檔案名稱（必須包含 \`.md\` 後綴）。
-2. **多檔處理**：若有多個檔案相關，請以半形逗號 \`,\` 分隔。
-3. **無相關時**：若判斷目錄中的檔案皆不相關，請直接回覆 \`NONE\`。
-4. **禁止任何廢話**：**絕對禁止**輸出任何解釋文字、問候語、符號，也**禁止**使用 Markdown 標記（如代碼塊 \` \`\`\` \` \`\`\` 或清單 \`-\`）。
+function readPrompt(filename) {
+  const filePath = path.join(PROMPTS_DIR, filename);
+  if (fs.existsSync(filePath)) {
+    return fs.readFileSync(filePath, 'utf-8')
+  }
+  console.warn(`[wiki-router] Prompt file not found: ${filePath}, using empty string`);
+  return ''
+}
 
-**正確輸出範例：**
-Introduction.md,Policy_Info.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 輸出解析器
@@ -240,14 +86,76 @@ function parseWikiOutput(output) {
   return results
 }
 
+/**
+ * 檔案系統 adapter — 將 fs 操作包裝成 Source / Store 介面
+ *
+ * 用法：
+ *   import { fsSource, fsStore } from '@jungtz/wiki-router'
+ *   createWikiRouter({ router, source: fsSource('./knowledge'), store: fsStore('./wiki') })
+ *
+ * 也可直接傳 knowledgeDir / outputDir 給 createWikiRouter，內部會自動包成這兩個 adapter。
+ */
+
+
+/**
+ * 建立讀取本地檔案的 Source adapter
+ * @param {string} dir - knowledge 來源目錄
+ * @returns {import('../types').Source}
+ */
+function fsSource(dir) {
+  const resolved = path.resolve(dir);
+  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 }
+    },
+  }
+}
+
+/**
+ * 建立讀寫本地檔案的 Store adapter
+ * @param {string} dir - wiki 輸出目錄
+ * @returns {import('../types').Store}
+ */
+function fsStore(dir) {
+  const resolved = path.resolve(dir);
+  function ensure() {
+    if (!fs.existsSync(resolved)) fs.mkdirSync(resolved, { recursive: true });
+  }
+  return {
+    async list() {
+      ensure();
+      return fs.readdirSync(resolved).filter(f => f.endsWith('.md'))
+    },
+    async read(filename) {
+      const filePath = path.join(resolved, filename);
+      if (!fs.existsSync(filePath)) return null
+      return fs.readFileSync(filePath, 'utf-8')
+    },
+    async write(filename, content) {
+      ensure();
+      fs.writeFileSync(path.join(resolved, filename), content);
+    },
+  }
+}
+
 /**
  * wiki-router - LLM Wiki 知識庫路由引擎
  *
- * 使用方式：
- *   const { createWikiRouter } = require('@jungtz/wiki-router')
+ * 使用方式 (檔案系統)：
  *   const wiki = createWikiRouter({ router, knowledgeDir, outputDir })
- *   await wiki.build()
- *   const ctx = await wiki.getContext('user question')
+ *
+ * 使用方式 (自訂 adapter，例如 API + DB)：
+ *   const wiki = createWikiRouter({ router, source, store })
  */
 
 
@@ -262,19 +170,29 @@ function parseWikiOutput(output) {
 function createWikiRouter(config) {
   const {
     router,
+    source,
+    store,
     knowledgeDir,
     outputDir,
     modelId,
     routerModelId,
     timeout = 300000,
+    splitPrompt,
+    mergePrompt,
+    routerPrompt,
   } = config;
 
+  const activeSplitPrompt = splitPrompt || SPLIT_PROMPT;
+  const activeMergePrompt = mergePrompt || MERGE_PROMPT;
+  const activeRouterPrompt = routerPrompt || ROUTER_PROMPT;
+
   if (!router) throw new Error('[wiki-router] router is required')
-  if (!knowledgeDir) throw new Error('[wiki-router] knowledgeDir is required')
-  if (!outputDir) throw new Error('[wiki-router] outputDir is required')
 
-  const resolvedKnowledgeDir = path.resolve(knowledgeDir);
-  const resolvedOutputDir = path.resolve(outputDir);
+  const activeSource = source || (knowledgeDir ? fsSource(knowledgeDir) : null);
+  const activeStore = store || (outputDir ? fsStore(outputDir) : null);
+
+  if (!activeSource) throw new Error('[wiki-router] source or knowledgeDir is required')
+  if (!activeStore) throw new Error('[wiki-router] store or outputDir is required')
 
   let modelsFetched = false;
 
@@ -356,37 +274,28 @@ function createWikiRouter(config) {
    */
   async function build() {
     try {
-      if (!fs.existsSync(resolvedOutputDir)) fs.mkdirSync(resolvedOutputDir, { recursive: true });
+      const knowledgeKeys = await activeSource.list();
 
-      const knowledgeFiles = fs.readdirSync(resolvedKnowledgeDir)
-        .filter(f => f.endsWith('.json') || f.endsWith('.md'))
-        .sort();
-
-      if (knowledgeFiles.length === 0) {
-        console.warn(`[Wiki] No .json or .md files found in: ${resolvedKnowledgeDir}`);
+      if (knowledgeKeys.length === 0) {
+        console.warn('[Wiki] No knowledge entries found from source.');
         return false
       }
 
       let totalFiles = 0;
 
-      for (const knowledgeFile of knowledgeFiles) {
-        const existingFiles = fs.readdirSync(resolvedOutputDir).filter(f => f.endsWith('.md'));
+      for (const key of knowledgeKeys) {
+        const existingFiles = await activeStore.list();
         const isFirstTime = existingFiles.length === 0;
-        const filePath = path.join(resolvedKnowledgeDir, knowledgeFile);
-        const fileContent = fs.readFileSync(filePath, 'utf-8');
-        const fileType = knowledgeFile.endsWith('.json') ? 'json' : 'markdown';
+        const { type: fileType, content: fileContent } = await activeSource.read(key);
 
-        console.log(`[Wiki] Processing: ${knowledgeFile} (type: ${fileType}, mode: ${isFirstTime ? 'first' : 'merge'})`);
+        console.log(`[Wiki] Processing: ${key} (type: ${fileType}, mode: ${isFirstTime ? 'first' : 'merge'})`);
 
         let finalPrompt;
         if (isFirstTime && fileType === 'json') {
-          finalPrompt = SPLIT_PROMPT.replace('{{context}}', fileContent);
+          finalPrompt = activeSplitPrompt.replace('{{context}}', fileContent);
         } else {
-          const indexPath = path.join(resolvedOutputDir, 'Index.md');
-          const indexContent = fs.existsSync(indexPath)
-            ? fs.readFileSync(indexPath, 'utf-8')
-            : '';
-          finalPrompt = MERGE_PROMPT
+          const indexContent = (await activeStore.read('Index.md')) || '';
+          finalPrompt = activeMergePrompt
             .replace('{{indexContent}}', indexContent)
             .replace('{{fileType}}', fileType)
             .replace('{{contentBlock}}', fileType === 'json' ? 'json' : 'markdown')
@@ -395,18 +304,18 @@ function createWikiRouter(config) {
 
         const output = await chat([{ role: 'user', content: finalPrompt }]);
         if (!output) {
-          console.warn(`[Wiki] No output for: ${knowledgeFile}`);
+          console.warn(`[Wiki] No output for: ${key}`);
           continue
         }
 
         const parsed = parseWikiOutput(output);
         if (parsed.length === 0) {
-          console.error(`[Wiki] Failed to parse output for: ${knowledgeFile}. Raw:`, output);
+          console.error(`[Wiki] Failed to parse output for: ${key}. Raw:`, output);
           continue
         }
 
         for (const { filename, content } of parsed) {
-          fs.writeFileSync(path.join(resolvedOutputDir, filename), content);
+          await activeStore.write(filename, content);
           console.log(`[Wiki] ${isFirstTime ? 'Generated' : 'Updated'}: ${filename}`);
         }
         totalFiles += parsed.length;
@@ -427,23 +336,20 @@ function createWikiRouter(config) {
    */
   async function getContext(prompt) {
     try {
-      if (!fs.existsSync(resolvedOutputDir)) fs.mkdirSync(resolvedOutputDir, { recursive: true });
-
-      let wikiFiles = fs.readdirSync(resolvedOutputDir).filter(f => f.endsWith('.md'));
+      let wikiFiles = await activeStore.list();
 
       if (wikiFiles.length === 0) {
         const success = await build();
         if (!success) return ''
       }
 
-      const indexPath = path.join(resolvedOutputDir, 'Index.md');
-      if (!fs.existsSync(indexPath)) {
+      const indexContent = await activeStore.read('Index.md');
+      if (!indexContent) {
         console.warn('[Wiki] Index.md not found.');
         return ''
       }
 
-      const indexContent = fs.readFileSync(indexPath, 'utf-8');
-      const selectionPrompt = ROUTER_PROMPT
+      const selectionPrompt = activeRouterPrompt
         .replace('{{prompt}}', prompt)
         .replace('{{indexContent}}', indexContent);
 
@@ -465,9 +371,9 @@ function createWikiRouter(config) {
       let loadedCount = 0;
 
       for (const file of selectedFiles) {
-        const filePath = path.join(resolvedOutputDir, file);
-        if (fs.existsSync(filePath)) {
-          relevantContext += `\n--- 檔案: ${file} ---\n${fs.readFileSync(filePath, 'utf-8')}\n`;
+        const content = await activeStore.read(file);
+        if (content !== null && content !== undefined) {
+          relevantContext += `\n--- 檔案: ${file} ---\n${content}\n`;
           loadedCount++;
         }
       }
@@ -490,4 +396,6 @@ exports.MERGE_PROMPT = MERGE_PROMPT;
 exports.ROUTER_PROMPT = ROUTER_PROMPT;
 exports.SPLIT_PROMPT = SPLIT_PROMPT;
 exports.createWikiRouter = createWikiRouter;
+exports.fsSource = fsSource;
+exports.fsStore = fsStore;
 exports.parseWikiOutput = parseWikiOutput;