@jungtz/wiki-router 1.0.1 → 1.0.4

package/README.md

@@ -14,83 +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)
@@ -99,22 +158,57 @@ 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) 用法
+
+## 互動預覽
+
+內建互動式 TUI，可在終端直接問答測試 Wiki 路由效果：
+
+```bash
+npm run preview
+
+# 自訂路徑
+npm run preview -- --knowledge ./my-knowledge --output ./my-wiki
+```
+
+支援指令：`:list` 查看維基頁面、`:build` 重建維基、`:files` 顯示檔案、`:quit` 離開。
+
+## 發布腳本
+
+```bash
+npm run bump:patch   # 版號 patch +1 並自動 git commit + tag
+npm run bump:minor   # 版號 minor +1
+npm run bump:major   # 版號 major +1
+npm run push:version # 推送 commit 與 tag 至 remote
+npm run release      # bump:patch + push:version
 ```
 
 ## 錯誤處理