@jungtz/wiki-router 1.0.1 → 1.0.4

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 = readPrompt('split.md');
+const MERGE_PROMPT = readPrompt('merge.md');
+const ROUTER_PROMPT = readPrompt('router.md');
 
 /**
  * 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,27 +170,68 @@ 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;
+
+  /**
+   * 預先獲取本地模型清單（仿照 models.js 的 getModelsList 邏輯）
+   * 確保 switchModel 能識別動態發現的 local 模型
+   */
+  async function ensureModels() {
+    if (modelsFetched) return
+    try {
+      const { models } = await router.getModels();
+      const localProviders = Object.keys(router.config.providers).filter(
+        p => router.config.providers[p].type === 'local'
+      );
+      localProviders.forEach(pName => {
+        const pModels = models.filter(m => m.provider === pName);
+        if (pModels.length > 0) {
+          router.config.providers[pName].models = pModels.map(m => ({
+            model: m.model,
+            description: m.description
+          }));
+        }
+      });
+      modelsFetched = true;
+    } catch (e) {
+      console.warn('[Wiki] Failed to fetch models:', e.message);
+    }
+  }
 
   /**
    * 向 LLM 發送對話並取得完整回應
    * @param {{ role: string, content: string }[]} messages
    * @param {string} [overrideModelId]
+   * @param {number} [overrideTimeout]
    * @returns {Promise<string|null>}
    */
-  async function chat(messages, overrideModelId) {
+  async function chat(messages, overrideModelId, overrideTimeout) {
     const wikiModelId = overrideModelId || modelId || process.env.WIKI_MODEL || 'ollama-local/gemma4:31b';
+    const effectiveTimeout = overrideTimeout || timeout;
 
     try {
       let provider;
@@ -296,10 +245,17 @@ function createWikiRouter(config) {
 
       // 使用 AI Router 進行對話
       if (router && provider) {
+        await ensureModels();
         await router.switchModel(provider, modelName);
         let content = '';
         const stream = router.chat(messages);
+
+        const deadline = Date.now() + effectiveTimeout;
         for await (const chunk of stream) {
+          if (Date.now() > deadline) {
+            console.warn(`[Wiki Chat] Timeout after ${effectiveTimeout}ms`);
+            break
+          }
           if (chunk.type === 'content') content += chunk.content;
         }
         return content
@@ -318,37 +274,28 @@ function createWikiRouter(config) {
    */
   async function build() {
     try {
-      if (!fs.existsSync(resolvedOutputDir)) fs.mkdirSync(resolvedOutputDir, { recursive: true });
-
-      const knowledgeFiles = fs.readdirSync(resolvedKnowledgeDir)
-        .filter(f => f.endsWith('.json') || f.endsWith('.md'))
-        .sort();
+      const knowledgeKeys = await activeSource.list();
 
-      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')
@@ -357,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;
@@ -389,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);
 
@@ -427,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++;
         }
       }
@@ -452,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;

package/dist/index.d.ts

@@ -2,13 +2,38 @@
  * Type definitions for @jungtz/wiki-router
  */
 
+/**
+ * @typedef {Object} SourceEntry
+ * @property {'json' | 'markdown'} type - 內容格式
+ * @property {string} content - 原始內容字串
+ */
+
+/**
+ * @typedef {Object} Source
+ * @property {() => Promise<string[]>} list - 列出所有 knowledge 來源 key（檔名 / DB id）
+ * @property {(key: string) => Promise<SourceEntry>} read - 讀取單一來源內容
+ */
+
+/**
+ * @typedef {Object} Store
+ * @property {() => Promise<string[]>} list - 列出已生成的 wiki 檔名（含副檔名）
+ * @property {(filename: string) => Promise<string|null>} read - 讀取 wiki 檔；不存在回 null
+ * @property {(filename: string, content: string) => Promise<void>} write - 寫入 wiki 檔
+ */
+
 /**
  * @typedef {Object} WikiRouterConfig
  * @property {import('@jungtz/ai-router').AIProviderRouter} router - AI Router 實例 (required)
- * @property {string} knowledgeDir - 知識庫來源目錄路徑 (required)
- * @property {string} outputDir - 輸出 Wiki 檔案的目錄路徑 (required)
+ * @property {Source} [source] - Knowledge 來源 adapter；未提供時使用 knowledgeDir
+ * @property {Store} [store] - Wiki 儲存 adapter；未提供時使用 outputDir
+ * @property {string} [knowledgeDir] - 知識庫來源目錄路徑（fsSource 簡寫）
+ * @property {string} [outputDir] - 輸出 Wiki 檔案的目錄路徑（fsStore 簡寫）
  * @property {string} [modelId] - Wiki 生成使用的模型 ID，格式: 'provider/model'
  * @property {string} [routerModelId] - 路由選擇使用的模型 ID，預設同 modelId
+ * @property {number} [timeout=300000] - 每次 LLM 對話的逾時毫秒數
+ * @property {string} [splitPrompt] - 自訂 Split prompt 字串，未提供時使用內建預設
+ * @property {string} [mergePrompt] - 自訂 Merge prompt 字串，未提供時使用內建預設
+ * @property {string} [routerPrompt] - 自訂 Router prompt 字串，未提供時使用內建預設
  */
 
 /**