READMEmain
We couldn't render this README. Read it on GitHub
HistorIQ
HistorIQ 是一個基於模型上下文協議（Model Context Protocol, MCP）架構的 AI 歷史小說平台。整合了 RAG（Retrieval-Augmented Generation）、AI Agent、與本地部署的大語言模型（LLM），讓使用者能夠以自然語言提問歷史事件、人物與文化主題，系統則透過多階段推理與知識檢索生成具脈絡性的回答。
核心亮點 / 特點
| 項目 | 說明 |
|---|---|
| 🧠 MCP 架構驅動 | 採用「模型上下文協議（MCP）」劃分 Client / Server / Agent / RAG，模組化、可擴展。 |
| ✍️ 歷史小說生成專用模型引導 | AI 扮演「歷史小說作家」角色，自動構思章節、角色心理與文學敘事，支援 Markdown 排版。 |
| 🧵 章節式敘事結構 | 每次生成包含 4~6 章節，標題與主題皆具文學性與劇情連貫性，內容可直接出版。 |
| 📖 人文素養強化 | 明確引導 AI 引用詩詞、經典詞句與歷代語錄，讓讀者同時欣賞歷史與語文之美。 |
| 🌐 全繁體中文設計 | 包含 UI 介面、提示語、故事內容全以繁體中文實作，符合本地文化閱讀習慣。 |
| 🔊 語音朗讀與高亮動畫 | 實作 Web Speech API，支援故事朗讀 + 高亮顯示目前句段，搭配古箏背景音樂。 |
| 🔁 續寫與互動補強 | 使用者可進一步點擊功能如「續寫故事」「風格改寫」「三句摘要」追加故事互動。 |
| 📜 RAG 融合 | 引入檢索式生成（Retrieval-Augmented Generation）模組補充背景知識。 |
MCP（Model Context Protocol）
本專案遵循 MCP（Model Context Protocol）模型上下文協議 的設計原則，並實作以下關鍵模組與規範：
| 模組 | 說明 | 實作狀態 |
|---|---|---|
MCP Server | 作為上下文協議核心中介，處理多輪對話狀態、代理分流、語境管理與任務調度 | ✅ 已完成 |
MCP Client (Web) | 提供使用者互動入口，支援問題輸入、上下文顯示、按鈕互動等 | ✅ 已完成 |
AI Agent | 接收 Server 任務委派，進行多步推理與角色化內容生成 | ✅ 已完成 |
RAG Retriever | 檢索外部知識內容（如歷史資料庫）並回傳上下文給 AI 模型使用 | ✅ 已完成 |
LLM 接口模組 | 支援本地 LLM（如 LM Studio）語言模型的 API 呼叫與回應解析 | ✅ 已完成 |
功能選單控制 | 故事結束後提供互動按鈕，如「延伸故事」、「轉換風格」等操作，並由 MCP Server 分派對應服務 | ✅ 已完成 |
上下文管理機制 | 每位使用者會有獨立 session ID，並記錄歷史問答脈絡，提供語境維持功能 | ✅ 已完成 |
多模組解耦架構 | 各模組（RAG、Agent、Server、Client）具備明確職責與獨立維護界線 | ✅ 已完成 |
延伸任務鏈設計 | 支援故事後續分支與按鈕觸發任務，如「AI 講書人」、「產出摘要」等 | ✅ 已完成 |
MCP 規範相容性 | 遵守 MCP 的 Request/Response 與任務分層邏輯，可擴展至更多 Agent 或 Tool | ✅ 初步完成 |
整體架構與功能模組概覽
| 模組層 | 元件 | 說明 |
|---|---|---|
MCP Client | index.html, app.py | 前端頁面與 Web API 入口 |
MCP Server | mcp_server.py | 實作所有 AI 邏輯與服務功能 |
AI Agent | story_agent.py | 呼叫 LLM 生成內容（Gemma） |
RAG | rag.py | 向量搜尋補充知識背景（已掛入 prompt） |
MCP Server 所提供的服務總表
| 函式 | API | 功能描述 |
|---|---|---|
stream_story() | /stream | 根據輸入主題串流生成歷史小說 |
summarize() | /summarize | 三句話濃縮故事摘要 |
chapter_titles() | /chapter-titles | 自動生成章節標題與概要 |
variant_style() | /variant-style | 以指定風格（如詩意）重寫內容 |
continue_story() | /continue-story | 從原內容延續劇情並追加後續章節 |
使用者互動功能（前端整合）
| 功能按鈕 | 描述 | 對應 API |
|---|---|---|
開始朗讀 | 文字朗讀並同步高亮段落 | Web Speech API |
摘要 | 產出三句簡潔摘要 | /summarize |
章節 | 章節目錄建議（含主題與描述） | /chapter-titles |
換風格 | 詩意/史詩風改寫內容 | /variant-style |
續寫故事 | 延續章節，保持敘事連貫性 | /continue-story |
特殊優化設計亮點
- ✅ 輸入欄與功能區 固定在底部
- ✅ AI 串流輸出時，內容由上往下自然堆疊
- ✅ 使用 Markdown 格式排版，美觀清晰
- ✅ 引導 AI 融合歷代詩詞與經典語錄，提升人文素養
- ✅ 具備基本 RAG 植入，可擴充知識強化模組
