Immerseai
MCP server: Immerseai
Installation
npx immerseaiAsk AI about Immerseai
Powered by Claude · Grounded in docs
I know everything about Immerseai. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
ImmerseAI
把书里的人物请出来,和他们聊天。

ImmerseAI 是一款 Local-First 桌面应用。通过 MCP 协议接管本地书库,在设备端完成 RAG 向量化,生成书中角色的人设并进行沉浸式对话。所有书籍与向量索引永远留在本地,唯一出站的只有你主动发起的 LLM 请求。
功能概览
| 功能 | 说明 |
|---|---|
| 本地书架 | 挂载任意本地目录,自动扫描 .md / .txt,支持多层文件夹结构 |
| 宫格 / 列表视图 | 可切换两种书架布局,拖动窗口自适应响应式排版 |
| 端侧 RAG | 自适应分块 + 主进程 embedding(all-MiniLM-L6-v2)+ Orama BM25,混合 RRF 检索 |
| 两阶段索引 | 大书(> 5000 chunks)立即完成词法索引可用,后台异步升级语义 |
| 角色人设 | 用 LLM + RAG 检索自动生成角色描述、性格、台词风格、背景 |
| 沉浸式对话 | 流式输出 + RAG 上下文注入,回应附带原文引用,点击跳回原文 |
| Librarian Agent | 自然语言指挥文件管理:移动书籍、创建/删除文件夹、批量操作 |
| 页面过渡动画 | framer-motion 全局路由过渡 + 阅读器骨架屏,消除白屏体验 |
| 渐进式阅读器 | 大文档先显示最后阅读位置,后台异步加载全文,50MB LRU 缓存加速二次访问 |
| 安全存储 | API Key 通过 Electron safeStorage 加密,不写入任何明文文件 |
技术栈
| 层级 | 技术选型 |
|---|---|
| 运行时 | Electron 28 |
| 前端 | React 18 + TypeScript strict |
| 构建 | Vite 5 + electron-vite |
| UI | TailwindCSS 3 + shadcn/ui + framer-motion |
| 全局状态 | Zustand 4 + persist middleware |
| Agent 协议 | @modelcontextprotocol/sdk(Stdio transport) |
| 端侧 RAG | @huggingface/transformers(主进程 Node.js)+ @orama/orama |
| LLM | OpenAI Compatible API,用户自定义 Base URL / Model |
架构分层:渲染进程(React UI)→ 主进程(RAG + IPC 桥接 + MCP)→ 外部(LLM API)
RAG 向量化在主进程 Node.js 中执行,规避渲染进程 file:// 协议限制;UI 层通过 IPC fire-and-forget 异步获取进度,始终不阻塞界面。
快速开始
npm install
npm run dev # 开发模式(热重载)
npm run build # 类型检查 + 构建
npm run pack # electron-builder 打包为安装包
首次启动后,在设置页填入 API Key、Base URL 和 Model 名称,然后点击书架页的目录按钮选择本地文件夹挂载书架。配置通过 Zustand persist 缓存,重启后自动恢复。
项目结构
immerseai/
├── electron/
│ ├── main/ # ipc-handlers · llm-handler · rag-handler · mcp-manager · safe-storage
│ └── preload/ # contextBridge 安全 API(白名单 channel)
├── src/
│ ├── app/ # 路由(PageTransitionLayout)· Provider
│ ├── features/ # bookshelf · reader · chat · persona · settings
│ └── shared/ # 通用组件 · Store · 类型 · hooks · utils
├── openspec/ # 规格驱动开发文档与归档变更
└── test_book/ # 调试记录(Bug调试记录.md)与测试样本
开发进度
更新:2026-03-31
| Phase | 内容 | 状态 |
|---|---|---|
| 1 基建 | IPC 桥接 / Zustand Store / 路由 / 类型系统 | ✅ |
| 2 书架 | MCP Manager / BookshelfPage / Librarian Agent / 响应式布局 / 宫格+列表视图 | ✅ |
| 3 大脑 | RAG 主进程迁移 / 自适应分块 / 两阶段索引 / 混合 RRF 检索 / 并发去重 | ✅ |
| 4 灵魂 | LLM 流式对话 / Chat UI / 角色人设生成 / 阅读器 / 引用跳转 / 骨架屏 | ✅ |
| 5 质量 | React 最佳实践审查 / 性能优化 / Bug 调试体系 / 打包发布 | ✅ |
工程实践
OpenSpec 规格驱动开发:每个功能变更遵循 proposal → design → specs → tasks → apply → verify → archive 流程,变更文档归档于 openspec/changes/archive/。
测试体系:qoobee-t&f-skill 支持自动化代码审计(AT-01 ~ AT-14)与人工测试报告修复。AT-01 ~ AT-14 全部通过。
Bug 调试记录:每个 Bug 均记录根因分析、代码 diff、知识点与面试问答,维护于 test_book/无分类/Bug调试记录.md(当前 BUG-001 ~ BUG-008)。
Agent Skills:.cursor/skills/ 内置测试修复、Bug 调试记录、Vercel React 最佳实践等能力包,关键词触发,不影响核心运行链路。
