@jungtz/wiki-router 1.0.1

package/dist/index.mjs

@@ -0,0 +1,449 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * 內嵌 LLM Wiki 提示詞模板
+ * 與原始 server/prompts/ 目錄中的檔案保持同步
+ */
+
+const SPLIT_PROMPT = `# 角色：專業文件架構師 (Documentation Architect)
+
+## 任務目標
+將提供的 JSON 資料完整解析並轉換為多個獨立的 Markdown \`.md\` 檔案。
+JSON 可能來自 CMS、API 回應、設定檔或任何結構化資料來源。
+
+## 原始 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 標記（如代碼塊 \` \`\`\` \` \`\`\` 或清單 \`-\`）。
+
+**正確輸出範例：**
+Introduction.md,Policy_Info.md`;
+
+/**
+ * LLM 輸出解析器
+ * 將 LLM 回應中的 Markdown 程式碼區塊解析為獨立檔案
+ */
+
+/**
+ * @typedef {{ filename: string, content: string }} WikiFile
+ */
+
+/**
+ * 解析 LLM 回應，提取程式碼區塊作為獨立檔案
+ * @param {string} output - LLM 原始回應文字
+ * @returns {WikiFile[]}
+ */
+function parseWikiOutput(output) {
+  const lines = output.split(/\r?\n/);
+  let currentFilename = null;
+  let insideCodeBlock = false;
+  let currentContent = [];
+  const results = [];
+
+  for (const line of lines) {
+    if (line.trim().startsWith('```')) {
+      if (!insideCodeBlock) {
+        insideCodeBlock = true;
+        currentContent = [];
+      } else {
+        insideCodeBlock = false;
+        if (!currentFilename) {
+          currentFilename = results.length === 0 ? 'Index.md' : `Unknown_File_${results.length}.md`;
+        }
+        if (currentFilename) {
+          const content = currentContent.join('\n');
+          results.push({ filename: currentFilename, content });
+          currentFilename = null;
+        }
+      }
+      continue
+    }
+
+    if (insideCodeBlock) {
+      currentContent.push(line);
+    } else {
+      let name = null;
+      const titleMatch = line.match(/^#{1,4}\s+([^#]+)/);
+      if (titleMatch) {
+        name = titleMatch[1].replace(/[<>:"/\\|?*\[\]]/g, '').trim();
+      } else {
+        const mdMatch = line.match(/([a-zA-Z0-9_.-]+\.md)/i);
+        if (mdMatch) name = mdMatch[1].trim();
+      }
+
+      if (name && name.length < 50) {
+        if (!name.toLowerCase().endsWith('.md')) name += '.md';
+        currentFilename = name;
+      }
+    }
+  }
+
+  return results
+}
+
+/**
+ * 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')
+ */
+
+
+/** @typedef {import('./types').WikiRouterConfig} WikiRouterConfig */
+/** @typedef {import('./types').WikiRouterInstance} WikiRouterInstance */
+
+/**
+ * 建立 WikiRouter 實例
+ * @param {WikiRouterConfig} config
+ * @returns {WikiRouterInstance}
+ */
+function createWikiRouter(config) {
+  const {
+    router,
+    knowledgeDir,
+    outputDir,
+    modelId,
+    routerModelId,
+  } = config;
+
+  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);
+
+  /**
+   * 向 LLM 發送對話並取得完整回應
+   * @param {{ role: string, content: string }[]} messages
+   * @param {string} [overrideModelId]
+   * @returns {Promise<string|null>}
+   */
+  async function chat(messages, overrideModelId) {
+    const wikiModelId = overrideModelId || modelId || process.env.WIKI_MODEL || 'ollama-local/gemma4:31b';
+
+    try {
+      let provider;
+      let modelName = wikiModelId;
+
+      if (wikiModelId.includes('/')) {
+        const parts = wikiModelId.split('/');
+        provider = parts[0];
+        modelName = parts.slice(1).join('/');
+      }
+
+      // 使用 AI Router 進行對話
+      if (router && provider) {
+        await router.switchModel(provider, modelName);
+        let content = '';
+        const stream = router.chat(messages);
+        for await (const chunk of stream) {
+          if (chunk.type === 'content') content += chunk.content;
+        }
+        return content
+      }
+
+      return null
+    } catch (err) {
+      console.error(`[Wiki Chat Error] Model: ${wikiModelId}, Error:`, err.message);
+      return null
+    }
+  }
+
+  /**
+   * 建構或更新 LLM Wiki 知識庫
+   * @returns {Promise<boolean>}
+   */
+  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();
+
+      if (knowledgeFiles.length === 0) {
+        console.warn(`[Wiki] No .json or .md files found in: ${resolvedKnowledgeDir}`);
+        return false
+      }
+
+      let totalFiles = 0;
+
+      for (const knowledgeFile of knowledgeFiles) {
+        const existingFiles = fs.readdirSync(resolvedOutputDir).filter(f => f.endsWith('.md'));
+        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';
+
+        console.log(`[Wiki] Processing: ${knowledgeFile} (type: ${fileType}, mode: ${isFirstTime ? 'first' : 'merge'})`);
+
+        let finalPrompt;
+        if (isFirstTime && fileType === 'json') {
+          finalPrompt = SPLIT_PROMPT.replace('{{context}}', fileContent);
+        } else {
+          const indexPath = path.join(resolvedOutputDir, 'Index.md');
+          const indexContent = fs.existsSync(indexPath)
+            ? fs.readFileSync(indexPath, 'utf-8')
+            : '';
+          finalPrompt = MERGE_PROMPT
+            .replace('{{indexContent}}', indexContent)
+            .replace('{{fileType}}', fileType)
+            .replace('{{contentBlock}}', fileType === 'json' ? 'json' : 'markdown')
+            .replace('{{newContent}}', fileContent);
+        }
+
+        const output = await chat([{ role: 'user', content: finalPrompt }]);
+        if (!output) {
+          console.warn(`[Wiki] No output for: ${knowledgeFile}`);
+          continue
+        }
+
+        const parsed = parseWikiOutput(output);
+        if (parsed.length === 0) {
+          console.error(`[Wiki] Failed to parse output for: ${knowledgeFile}. Raw:`, output);
+          continue
+        }
+
+        for (const { filename, content } of parsed) {
+          fs.writeFileSync(path.join(resolvedOutputDir, filename), content);
+          console.log(`[Wiki] ${isFirstTime ? 'Generated' : 'Updated'}: ${filename}`);
+        }
+        totalFiles += parsed.length;
+      }
+
+      if (totalFiles === 0) return false
+      return true
+    } catch (err) {
+      console.error('[Wiki Generation Error]', err);
+      return false
+    }
+  }
+
+  /**
+   * 根據使用者問題取得相關的 Wiki 上下文
+   * @param {string} prompt - 使用者問題
+   * @returns {Promise<string>}
+   */
+  async function getContext(prompt) {
+    try {
+      if (!fs.existsSync(resolvedOutputDir)) fs.mkdirSync(resolvedOutputDir, { recursive: true });
+
+      let wikiFiles = fs.readdirSync(resolvedOutputDir).filter(f => f.endsWith('.md'));
+
+      if (wikiFiles.length === 0) {
+        const success = await build();
+        if (!success) return ''
+      }
+
+      const indexPath = path.join(resolvedOutputDir, 'Index.md');
+      if (!fs.existsSync(indexPath)) {
+        console.warn('[Wiki] Index.md not found.');
+        return ''
+      }
+
+      const indexContent = fs.readFileSync(indexPath, 'utf-8');
+      const selectionPrompt = ROUTER_PROMPT
+        .replace('{{prompt}}', prompt)
+        .replace('{{indexContent}}', indexContent);
+
+      const routeModel = routerModelId || process.env.WIKI_ROUTER_MODEL || modelId || process.env.WIKI_MODEL;
+      const output = await chat(
+        [{ role: 'user', content: selectionPrompt }],
+        routeModel
+      );
+      if (!output) return ''
+
+      const selectedFilesStr = output.trim();
+      if (selectedFilesStr === 'NONE' || !selectedFilesStr) {
+        console.log('[Wiki] No relevant files selected by LLM.');
+        return ''
+      }
+
+      const selectedFiles = selectedFilesStr.split(',').map(s => s.trim());
+      let relevantContext = '\n[Wiki 相關參考資料]:\n';
+      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`;
+          loadedCount++;
+        }
+      }
+
+      if (loadedCount > 0) {
+        console.log(`[Wiki] LLM correctly routed to ${loadedCount} file(s): ${selectedFiles.join(', ')}`);
+        return relevantContext
+      }
+
+    } catch (err) {
+      console.error('[Wiki Context Error]', err);
+    }
+    return ''
+  }
+
+  return { build, getContext }
+}
+
+export { MERGE_PROMPT, ROUTER_PROMPT, SPLIT_PROMPT, createWikiRouter, parseWikiOutput };

package/dist/parser.cjs

@@ -0,0 +1,65 @@
+'use strict';
+
+/**
+ * LLM 輸出解析器
+ * 將 LLM 回應中的 Markdown 程式碼區塊解析為獨立檔案
+ */
+
+/**
+ * @typedef {{ filename: string, content: string }} WikiFile
+ */
+
+/**
+ * 解析 LLM 回應，提取程式碼區塊作為獨立檔案
+ * @param {string} output - LLM 原始回應文字
+ * @returns {WikiFile[]}
+ */
+function parseWikiOutput(output) {
+  const lines = output.split(/\r?\n/);
+  let currentFilename = null;
+  let insideCodeBlock = false;
+  let currentContent = [];
+  const results = [];
+
+  for (const line of lines) {
+    if (line.trim().startsWith('```')) {
+      if (!insideCodeBlock) {
+        insideCodeBlock = true;
+        currentContent = [];
+      } else {
+        insideCodeBlock = false;
+        if (!currentFilename) {
+          currentFilename = results.length === 0 ? 'Index.md' : `Unknown_File_${results.length}.md`;
+        }
+        if (currentFilename) {
+          const content = currentContent.join('\n');
+          results.push({ filename: currentFilename, content });
+          currentFilename = null;
+        }
+      }
+      continue
+    }
+
+    if (insideCodeBlock) {
+      currentContent.push(line);
+    } else {
+      let name = null;
+      const titleMatch = line.match(/^#{1,4}\s+([^#]+)/);
+      if (titleMatch) {
+        name = titleMatch[1].replace(/[<>:"/\\|?*\[\]]/g, '').trim();
+      } else {
+        const mdMatch = line.match(/([a-zA-Z0-9_.-]+\.md)/i);
+        if (mdMatch) name = mdMatch[1].trim();
+      }
+
+      if (name && name.length < 50) {
+        if (!name.toLowerCase().endsWith('.md')) name += '.md';
+        currentFilename = name;
+      }
+    }
+  }
+
+  return results
+}
+
+exports.parseWikiOutput = parseWikiOutput;

package/dist/parser.d.ts

@@ -0,0 +1 @@
+export { parseWikiOutput, WikiFile } from './index.js';

package/dist/parser.mjs

@@ -0,0 +1,63 @@
+/**
+ * LLM 輸出解析器
+ * 將 LLM 回應中的 Markdown 程式碼區塊解析為獨立檔案
+ */
+
+/**
+ * @typedef {{ filename: string, content: string }} WikiFile
+ */
+
+/**
+ * 解析 LLM 回應，提取程式碼區塊作為獨立檔案
+ * @param {string} output - LLM 原始回應文字
+ * @returns {WikiFile[]}
+ */
+function parseWikiOutput(output) {
+  const lines = output.split(/\r?\n/);
+  let currentFilename = null;
+  let insideCodeBlock = false;
+  let currentContent = [];
+  const results = [];
+
+  for (const line of lines) {
+    if (line.trim().startsWith('```')) {
+      if (!insideCodeBlock) {
+        insideCodeBlock = true;
+        currentContent = [];
+      } else {
+        insideCodeBlock = false;
+        if (!currentFilename) {
+          currentFilename = results.length === 0 ? 'Index.md' : `Unknown_File_${results.length}.md`;
+        }
+        if (currentFilename) {
+          const content = currentContent.join('\n');
+          results.push({ filename: currentFilename, content });
+          currentFilename = null;
+        }
+      }
+      continue
+    }
+
+    if (insideCodeBlock) {
+      currentContent.push(line);
+    } else {
+      let name = null;
+      const titleMatch = line.match(/^#{1,4}\s+([^#]+)/);
+      if (titleMatch) {
+        name = titleMatch[1].replace(/[<>:"/\\|?*\[\]]/g, '').trim();
+      } else {
+        const mdMatch = line.match(/([a-zA-Z0-9_.-]+\.md)/i);
+        if (mdMatch) name = mdMatch[1].trim();
+      }
+
+      if (name && name.length < 50) {
+        if (!name.toLowerCase().endsWith('.md')) name += '.md';
+        currentFilename = name;
+      }
+    }
+  }
+
+  return results
+}
+
+export { parseWikiOutput };