@jungtz/ai-helper
v0.7.0
Published
AI Helper - AI 對話助手微服務，支援多租戶知識庫、Function Calling 與可嵌入 Widget
Readme
🚀 AI-Helper - 現代化全棧 AI 對話與知識檢索架構
專案定位：這是一個高度模組化的全棧 AI 應用程式，集成了 AI 路由引擎、多租戶 Agentic Wiki、向量 RAG 以及 持久化對話管理。旨在提供極簡配置、極致體驗的 AI 基礎設施。
✨ 核心亮點 (Core Features)
1. 🤖 統一 AI 路由引擎
基於 @jungtz/ai-router，實現了跨供應商（OpenAI, Ollama, Claude 等）的無縫切換。
- 配置中心化：透過
models.json統一管理 API 連線資訊。 - 本地自動偵測：系統自動掃描本地 Ollama 模型並同步至介面，無需手動配置清單。
2. 📚 多租戶雙模式 Wiki 系統
不僅僅是 RAG，更具備自主決策與靈活適配能力的知識檢索模組。
- 雙模式架構：
- 向量 RAG 模式 (
rag)：基於@jungtz/wiki-router，透過 Embedding 模型進行智能段落檢索，適合大規模知識庫。 - 全量知識庫模式 (
full)：免 RAG/Embedding 運算，直接同步遍歷並格式化知識庫目錄（如.md,.txt,.json），最適合小量說明文件（建議小於 50KB）。
- 向量 RAG 模式 (
- 多租戶支持：支援多個獨立知識庫（Tenants），可根據
tenantId隔離資料。 - 智能 Persona：系統能根據 Wiki 內容自動生成專屬的角色設定（Persona），並支援手動自定義。
- 無模型自適應降級：若未配置 Wiki 模型，系統會自適應設定為
full模式，並在初始化、重建等環節靜默跳過 RAG 索引，保障服務無縫流暢。 - 自動化索引：透過
/api/wiki/rebuild一鍵重建知識庫。
3. 💾 持久化與 Session 管理
- SQLite 驅動：使用
sqlite驅動（非 C++ 原生 better-sqlite3）實現高效、跨平台相容的對話與歷史記錄持久化。 - 自動遷移：支援從舊版檔案型歷史記錄自動遷移至資料庫。
- OAuth 整合：預留 Google OAuth 接口，支援多使用者 Session 管理。
4. 🎨 現代化 UI/UX 體驗
- 極致設計：採用玻璃擬態（Glassmorphism）、平滑過渡動畫與深色模式支援。
- 響應式佈局：完美適配行動端與桌面端，支援側邊欄收合與手機手勢操作。
- 富文本渲染：完整支援 Markdown、代碼高亮、數學公式及即時串流（Streaming）回應。
5. 🔍 自動化文件生成 (Scanner Engine)
- 智能掃描：一鍵掃描目標專案，利用 LLM 分析程式碼邏輯。
- 自動產出：自動推導生成符合 OpenAPI 3.0 標準的 API 規格與 Markdown 使用者手冊。
6. 🧩 跨專案嵌入式 Widget (Embeddable Widget)
- 隨插即用：只需引入
<script>即可在任何目標網站嵌入專屬的 AI 聊天面板。 - 無污染隔離：採用 Web Component (Shadow DOM) 技術，確保樣式完全隔離並自帶 Tool Calling 操作驗證。
- 工具回流推理：在 Widget 中執行工具 (如呼叫外部 API) 後，執行結果會自動回送給 LLM 進行二次推理，實現真正的 Agent 對話體驗。
🛠 技術棧 (Tech Stack)
後端 (Backend)
- Runtime: Node.js / Express
- Database: SQLite (
better-sqlite3) - AI Routing:
@jungtz/ai-router - Agentic Framework:
@jungtz/wiki-router - Auth: Google OAuth (Optional)
前端 (Frontend)
- Build Tool: Vite
- Styling: SCSS / Bootstrap 5 / Vanilla CSS
- Interactions: Native JavaScript (ESM)
- Markdown: Marked.js + Highlight.js
🤖 配置與部署
1. 模型路由管理 (models.json)
定義您的雲端供應商。本地 Ollama 會自動掛載為 ollama-local。
2. 環境變數 (.env)
# --- 伺服器 ---
# NODE_ENV=production
# PORT=3001
# BASE_URL=/chat/
# --- AI Helper ---
# 知識庫檔案目錄
# KNOWLEDGE_DIR=./knowledge
# 資料庫路徑
# DB_PATH=./data/chat-session.db
# WIKI_DB_PATH=./data/wiki.db
# 知識庫模式 (自動偵測，無需手動設定)
# 有 WIKI_MODEL 或 WIKI_ROUTER_MODEL → rag
# 兩者皆無 → full
# KNOWLEDGE_MODE=full
# Wiki 模型 (若要用 RAG 模式才需設定)
# WIKI_MODEL=ollama-local/gemma4:31b
# WIKI_ROUTER_MODEL=ollama-local/gemma4:26b
# --- 選填 ---
# 本地 Ollama
# OLLAMA_HOST=http://localhost:11434
# 預設 Tenant
# DEFAULT_TENANT_ID=default3. 快速啟動
npm install
npm start📂 專案結構
src/: 前端原始碼與樣式。server/:modules/: 核心邏輯（模型路由、Wiki、RAG、歷史管理）。data/: SQLite 資料庫存放區（gitignored）。knowledge/: Wiki 原始檔案存儲。prompts/: 系統提示詞與角色設定範本。
📦 NPM 安裝與整合 (Integration Guide)
如果您希望將 AI-Helper 作為微服務整合進現有的 Node.js 專案，您可以透過 NPM 直接安裝本套件。
1. 安裝套件
npm install @jungtz/ai-helper2. 後端整合範例 (Express)
在您的主專案中，您可以將 AI-Helper 當作一個獨立的 Router 掛載，這能讓兩者共用同一個 Port，並免去 CORS 設定的煩惱。
⚠️ 給開發者與 AI 助手的強烈建議： 整合時，務必透過
options傳入dbPath等路徑參數，將資料庫存放在主專案的data/目錄下。否則預設會在node_modules內建立資料庫，導致重新安裝時資料遺失！
const express = require('express');
const { createChatAPI } = require('@jungtz/ai-helper');
const app = express();
// 建立 AI-Helper 實例
const { app: chatApp } = createChatAPI({
baseUrl: '/ai-helper', // 決定前端 Widget 的存取路徑
dbPath: './data/chat-session.db', // 強烈建議自訂資料庫路徑
defaultTenantId: 'my-project', // 預設知識庫與設定的租戶 ID
modelsPath: './models.json', // 模型提供者設定檔路徑 (可選，預設使用套件內建)
knowledgeDir: './knowledge', // 知識庫檔案目錄 (可選，預設使用套件內建)
knowledgeMode: 'rag', // 知識庫模式：'rag' (RAG) 或 'full' (全量讀取，未配置 WIKI_MODEL 時會自動降級為 full)
corsOrigins: ['http://localhost:5173'] // 跨域設定 (選填)
});
// 將 AI-Helper 掛載到主專案路由
app.use('/ai-helper', chatApp);
app.listen(8080, () => {
console.log('Main App Server started on http://localhost:8080');
});3. 前端 Widget 整合範例
在您的目標網頁 index.html 的 <body> 底部加入以下標籤，即可無縫渲染浮動聊天面板。
由於已經與主服務整合，您可以直接使用同源相對路徑：
<!-- src 路徑對應到上方 createChatAPI 設定的 baseUrl -->
<script
src="/ai-helper/widget/aihelper.js"
data-project="my-project"
data-theme="auto">
</script>