Local AI Reading Companion · AI 伴读
让阅读速度提升 5 倍，而理解深度提升 10 倍。
macOS 14+ · Windows 10/11（P0） · Polyform Noncommercial · Latest Release
功能特性 · 界面预览 · 最近更新 · 下载安装 · 开发者
--- ## 功能特性 - **本地优先** — 默认 Ollama 本机跑通导入 → 摘要 → 深聊，书与笔记数据不出机 - **多格式书库** — 电子书 PDF / EPUB / MOBI / AZW / AZW3 / FB2，办公文档 DOCX / ODT / RTF，网页 HTML，以及 Markdown / TXT；也可粘贴公开网址（分号批量）抓成离线书 - **语义分段** — 识别序言/章节角色，不从句中切断；可手动调界或整书重新分段 - **扫描 PDF OCR** — 默认本机 RapidOCR；可在设置中配置 OpenAI 兼容视觉 API，配置完整时云端优先 - **书架详览** — 智能集合（最近 / 摘要进度 / 分段中 / 导入失败 / 阅读进度 / 分类 / 收藏）+ 网格或列表 - **沉浸式阅读** — 顶栏管书、底栏管段列表 / 笔记 / 深聊 / 显示，摘要 ↔ 原文一键切换 - **听文本** — 听总结 / 听详细 / 听原文，迷你条连播；使用系统离线神经语音 - **书内查找** — **⌘F**（Windows：Ctrl+F）搜该书原文，命中后跳段并高亮 - **深度理解** — 古文、外文自动翻译；段级 citation 可溯源；可选联网增强 - **读书记忆** — 跨书笔记 + **⌘K** 全局搜索，随时找回读过的内容 - **资讯** — RSS 同步、结构化简报与精读深聊 - **永不卡住** — 导入、分段、摘要在后台进行；长书导入时仍可开其他书、资讯与设置 - **可扩展** — 可选 OpenAI / OpenRouter / Cursor 兼容 API；整书摘要导出 Markdown - **两档摘要** — 每个 API 资源可分别配置正常/高级模型；点「开始摘要」即正常档，点箭头可选高级（需确认）；高级未配置时自动回退正常模型 --- ## 界面预览 macOS 主界面（Windows 功能对等，交互为 WinUI 惯用导航）。 | 书库 | 阅读器 | |:---:|:---:| |
| 
|
| 智能集合 + 网格书架 | 摘要阅读 · 听 · 深聊 |
| 资讯 | 设置 |
|:---:|:---:|
| 
| 
|
| RSS 简报与精读 | 引擎、听书与 API 资源 |
---
## 最近更新
### v1.5.1 — 粘贴文本导入
相对 v1.5.0 的主要变化：
- **书库**：可以把全文粘贴成一本纯文本，再走现有分段与摘要。书名取第一行（超过 80 字截断）；重复正文沿用覆盖 / 跳过询问；空白或超过 15MB 不导入
- **阅读**：已在最后一段时再按段头右箭头或 `→`，阅读区短暂提示「书籍已读完」
- **听**：连播自然走到全书末尾后，再朗读一句「书籍已播完」
- **网址导入**：安装包带上 justext 停用词表，避免抽正文时找不到文件
- **工程治理**：版本同步至 1.5.1
### v1.5.0 — 从网址导入
相对 v1.4.8 的主要变化：
- **书库**：粘贴公开 `http`/`https` 网址导入为离线书；英文分号可一次多条；重复网址沿用覆盖 / 跳过询问
- **正文**：只保存页面可读正文，不登录、不执行脚本、不收下直链文件
- **稳定性**：缺少 trafilatura 配置或 TLS 中途断开时会补齐配置并重试，不再把整次导入标成失败
- **工程治理**：版本同步至 1.5.0
### v1.4.8 — 非中文按词计字
相对 v1.4.7 的主要变化：
- **字数**：英文等空格分词语言按词计 1，汉字、假名、谚文仍逐字；空格和标点不计。分段预算与「约 N 字」不再把英文按字母拆碎。切点仍是 Unicode 码位
- **模型候选**：正常/高级模型可用分号写多个，按顺序尝试后再换下一个资源
- **书架**：智能集合去掉「收藏」；收藏动作和「收藏优先」排序仍在
- **资讯**：每天本地时间 09:00 后台同步 RSS
- **工程治理**：切分算法号 17；版本同步至 1.4.8
### v1.4.7 — 原文搜索命中列表与独立索引
相对 v1.4.6 的主要变化：
- **原文搜索**：macOS 先展示命中列表再点选定位；底栏可返回结果 / 上一条 / 下一条；搜完不自动跳第一条
- **检索性能**：独立原文索引后台回填；索引就绪后大书首屏检索更快；启动回填正确注入 DB 连接
- **正式发布仅 macOS**：Windows 安装包与 Release CI 停用（源码仍在 `apps/windows`）
- **工程治理**：版本同步至 1.4.7；badcase catalog 同步
### v1.4.1 — 阅读体验首次流畅版本（重要里程碑）
相对 v1.4.0 的主要变化：
- **阅读交互**：段头左右箭头翻段；`↑`/`↓`/`PgUp`/`PgDn` 连续滚动；键盘与触控板路径统一，输入框/弹层避让
- **可配置快捷键（macOS）**：设置可改键、冲突检测、恢复默认；摘要/分段菜单快捷键只打开 popover
- **段顶栏信息**：左上 `章名 · 段 N/总 · 标题`；「原文 · 约 N 字」；总结句墙文质量门
- **工程治理**：版本同步至 1.4.1；badcase catalog 同步
### v1.4 — 性能全方位优化
相对 v1.3 的主要变化：
- **阅读器回退简单路径**：macOS 开书一次拉全量 slim catalog + 主区全书 `ForEach`，去掉有界窗口/滞后锚点带来的视口抖动与骨架死锁风险
- **开书与进度**：Windows 开书先恢复本地进度再 around 拉窗，避免夹到最近段写脏进度；开书贴段顶；慢开书 / 慢段列表打耗时告警
- **Cursor 官方 SDK**：按需下载到用户数据目录，不进 sidecar；设置可装 SDK 并探测连通性
- **摘要质量**：加强总结句冗余/混语碎片门禁；UI 分区「主要内容」仅改可见文案
- **工程治理**：badcase catalog 与 never-freeze-ui / summary-ui-label-only 规则同步；版本同步至 1.4.0
### v1.1 — 阅读进度门闩、摘要衔接与打开方式
相对 v1.0.2 的主要变化：
- **阅读进度门闩**：搜索 / 段列表 / citation / 笔记 / ⌘K 跳转不写进度；非阻塞条可返回上次进度或留在此处；不操作则再连续经过 3 个不同段后落库
- **摘要衔接与字数门**：总结句承接最近前文（不串事实）；总结合计约 50–200 字，明显偏离自动重生
- **macOS 打开方式**：Finder「打开方式」/ 双击导入支持格式；不支持格式立即提示；已运行时再开文件有响应（ad-hoc 签名便于设为默认）
- **图片型 EPUB OCR**：扫描页 EPUB 按 spine 逐图 OCR，不再只导入目录后误报成功
- **分段硬地板**：不足 200 字的空壳/短段可向后合并；目标段长打包仍不得跨章硬凑
- **永不卡住**：摘要续跑与段摘要预取不得饿死 `/health`；大库 catalog 走缓存路径
### v1.0.2 — 启动不卡死、原文契约与顶栏书名
相对 v1.0.1 的主要变化：
- **启动不卡死**：大书库开机时 `recover_on_startup` 不再阻塞 lifespan；`/health` 可先响应，避免客户端超时杀进程后连环 `database is locked`
- **段详情契约**：`GET .../segments/{idx}` 的 `bullet_labels` 始终为 JSON 数组（不再把库内 TEXT 原样返回），修复切换原文时「原文加载失败」
- **阅读顶栏书名**：中间显示当前书名（长名单行省略）；点击返回书架，与左侧书架入口并存（v1.0 仅 macOS）
- **手动调界**：点击只预览新分界，底栏「保存」才落库并重新摘要这两段
### v1.0.1 — 引导、段列表结构树与分段更稳
相对 v1.0 的主要变化：
- **首次引导**：在真实界面上逐项高亮（可跳过），结束后给出使用指南；设置「关于」与 macOS Help 可再打开，不重跑 spotlight
- **段列表结构树**：按原文标题层级嵌套（不限层数）；分组后段行不再重复章名；无结构则平铺
- **手动调界**：点相邻两段拼接原文中的某一处预览新分界（吸附句末），点「保存」才落库；取消不保存；不再拖动滑块
- **分段**：同一章内每段不少于 200 字，章标题并入本章正文；导入超时按页数/文件体积计算，硬顶 8 小时
- **书架排序**：字段旁可选升序/降序（标题默认 A→Z，其余默认新→旧）
- **听摘要**：单击扬声器听简要；听完整必须点始终可见的下拉箭头，不再依赖长按
### v1.0 — 正式版：听读、查找与永不卡住
首个正式版本。相对 v0.10 的主要变化：
- **听文本**：阅读器顶栏听总结 / 听详细 / 听原文，迷你条连播与倍速；音色用系统已安装的神经语音（设置里可打开系统下载页），不走云端 TTS
- **书内原文搜索**：顶栏 / ⌘F 只搜该书原文，命中后切到原文模式并高亮；与 ⌘K 跨书搜索分开
- **阅读顶底栏**：点空白同步显隐顶栏（书架、摘要/原文、听、搜索、摘要、分段、导出、导入）与底栏（段列表、深聊、笔记、显示）；正文不位移。五档字号 + 四色纸只涂阅读面
- **永不卡住**：大 TXT / 扫描件的分段放到 sidecar 子进程；导入显示字数或页进度，超时会失败并写明原因；一本分段中仍能打开其他已就绪的书
- **结构分段**：章界硬切、未超限的自然段不劈开；装饰线粘连的章名也能切开；导入可选正常/高级分段
- **摘要更稳**：原文自称「我」时摘要保留第一人称；输出跟目标语言，不串假名/西里尔/英语整句；点「开始摘要」即正常档，点旁边箭头才展开高级
- **书架**：摘要维增加「分段中」「导入失败」；支持无 DRM 的 AZW / AZW3；卡片封面与阅读进度排序
- **引擎**：退出应用会关掉 `lumina-core`；设置始终可查看状态并停止 / 重启
### v0.10 — 阅读进度、摘要队列与操作更稳
- **阅读进度**：退出或切书后停在离开时那一段的开头；书架显示「在读 · n/m 段」；两本进度互不串味
- **阅读操作**：点翻段 / 复制 / 重新摘要不再误开关工具栏；翻段按钮钉在最右侧；工具栏「段列表」会钉住侧栏
- **摘要队列**：全书索引不再抢段摘要槽位；阅读面也能看到进行中 / 排队，不再出现「0 进行中 · n 排队」
- **书架**：右键即可整书重新分段；打开书不再弹出笔记 cancelled；周期性按钮 tooltip 已去掉
- v0.10.1：release 固定 CPython 3.11；修复 Windows 设置页缺分号
- v0.10.2：Lumina.app 体积上限与 sidecar 对齐（520MB）；修复 WinUI 阅读器编译（翻段快捷键 / 调界滑块）
### v0.9 — 语义分段、书架与阅读更稳
- **语义结构分段**：序言与正文分开，短序不再并进第一章；在句末切开，不从句子中间截断
- **书架详览**：智能集合 + 网格/列表；阅读中侧栏只保留最近打开，整理与沉浸阅读分开
- **手动调界 / 重新分段**：拖动相邻段分界只重摘要这两段；整书可按 200–8000 字重新分段
- **两档摘要 + 分层索引**：正常/高级模型；摘要质检避免把原文「我」写成阅读助手；深聊用分层 rollup
- **更多格式与编码**：FB2 / DOCX / ODT / RTF / HTML / Markdown；GB18030 TXT；Identity-H CID PDF 正确抽中文
- **阅读进度**：跨段即时保存，退出不丢；按视口恢复；未读完不标已读完；布局抖动不跳回首页
- **引擎身份**：升级后自动换掉旧 sidecar，不再因切分版本相同而复用旧进程；OCR / 联网搜索设置重启后保留
### v0.8 — Windows 与 macOS 功能对等
- Windows 补齐资讯、Ctrl+K、笔记、Markdown 导出、完整设置与任务管理
- 阅读器结构化摘要、笔记抽屉、选区提问、深聊 token / 耗时 / TPS
- WinUI 惯用 NavigationView / 工具栏 / 抽屉，不复刻 Mac 顶底浮栏
- v0.8.1：修复 EPUB spine 解析
### v0.7 — Windows P0 与阅读器滚动修复
- WinUI 自包含发布（ZIP）与跨平台 `lumina-core` 适配
- 修复 macOS 阅读器跳转在滚动抑制期间丢失
### v0.6 — 更高可用的伴读体验
- **SQLite 跨线程串行化**，导入写入与 API 读不再竞态报错
- 摘要 **默认不自动开始**（设置可开），导入只分段，后台更可控
- 阅读器 **命中区域收窄**、书库侧栏可见性策略，误触更少
- 深聊 **token / 耗时 / TPS** 归因展示，云端与本地调用更可观测
- 可配置 Prompt、书库批量摘要启停（承接 v0.5 后的管控能力）
### v0.5 — 云端摘要、多书并发与阅读体验升级
- **OpenRouter / OpenAI 兼容**云端摘要，设置热更新与 JSON 解析更鲁棒
- **多书并发槽位等待**，Ollama 满负载时排队而非误切云端；摘要进度 Banner 实时展示
- 段列表**瘦 API + 按需 hydrate**，大书 reopen 更快；选区**发送到深聊**
- 书库**分类筛选**、导出重构（系统保存面板 + 中文文件名）；OCR 发布校验增强
---
## 普通用户 · 下载即用
> 你**不需要**安装 Python、uv、Xcode 或任何命令行工具。下载安装包，拖进「应用程序」即可。
### 下载
| 平台 | 要求 | 下载 |
|------|------|------|
| macOS 14+（Apple Silicon / Intel） | 约 250 MB 安装包（安装后约 500 MB）+ 首次 AI 模型 ~3 GB | **[GitHub Releases 下载 DMG](https://github.com/hezhenghui7338/Lumina/releases/latest)** |
Release 页提供 **Lumina-*-macOS.dmg** / **Lumina-*-macOS.zip**（GitHub Actions 构建）。Windows 安装包当前不发布（源码仍在 `apps/windows`，发布链路已停用）。
### 安装（两步）
1. 打开下载的 **`.dmg`**，将 **Lumina** 拖入 **Applications（应用程序）** 文件夹
2. 从启动台或应用程序文件夹打开 **Lumina**
### 首次打开：「无法验证 / 可能危害 Mac」
这是 **正常现象**。当前 Release 由 GitHub Actions 自动构建，尚未经过 Apple 付费开发者签名与公证，macOS 会对**任何**未公证的本机应用显示此提示，**不代表有病毒**。
任选一种方式即可打开（只需操作一次）：
**方法 1（推荐）**
1. 在「应用程序」里找到 **Lumina**
2. **按住 Control 键点击**（或右键）→ 选 **「打开」**
3. 弹窗中再点 **「打开」**
**方法 2**
1. 先双击 Lumina（会被拦截）
2. 打开 **系统设置 → 隐私与安全性**
3. 向下滚动，找到 **「已阻止使用 Lumina」** 或类似提示
4. 点 **「仍要打开」**
**方法 3（熟悉终端时）**
```bash
xattr -cr /Applications/Lumina.app
```
然后照常双击打开。
> 后续版本若加入 Apple 开发者签名与公证，此提示将不再出现。
### 首次使用
打开 App 后按屏幕引导操作即可：
1. **Lumina 引擎** — 自动启动，无需配置
2. **本地 AI（Ollama）** — 一键打开 [ollama.com/download](https://ollama.com/download) 安装；安装后在 Ollama 里搜索并下载 **qwen3.5:4b**（约 3.4 GB，仅首次）
3. **导入书籍** — 点「导入」，选择文件即可
当前支持的导入格式：
| 类型 | 扩展名 |
|------|--------|
| 电子书 | `.pdf` `.epub` `.mobi` `.azw` `.azw3` `.fb2` |
| 办公文档 | `.docx` `.odt` `.rtf` |
| 网页 | `.html` `.htm` `.xhtml` |
| 文本 | `.txt` `.text` `.md` `.markdown` `.mdown` `.mkd` `.log` |
> **说明**：Ollama 是免费的本机 AI 运行时（类似本地版 ChatGPT 引擎）。Lumina 已内置阅读引擎，Ollama 仅负责 AI 摘要与对话，数据不出本机。
>
> 扫描 PDF 默认使用本地 OCR。若在「设置 → 文档识别」同时填写 OpenAI 兼容 Base URL、视觉模型和 API Key，Lumina 会优先逐页上传到该服务识别；云端不可用时改用本机 RapidOCR，导入不会因此中断。
### 日常使用
| 操作 | 方法 |
|------|------|
| 导入书 | 书库 → **导入**（亦可拖入书架） |
| 浏览书架 | 左侧智能集合 + 右侧网格/列表；点书进入阅读 |
| 阅读 / 深聊 | 打开书后点空白显隐顶栏与底栏；底栏打开段列表 / 笔记 / 深聊 / 显示（字号与纸色） |
| 听总结 / 听原文 | 阅读器顶栏 **听**；播放中用迷你条暂停、倍速、上下段 |
| 书内原文搜索 | 阅读器顶栏搜索或 **⌘F**（Windows：**Ctrl+F**） |
| 跨书笔记 | 书库 → **全部笔记** |
| 跨书搜索 | **⌘K** |
| 资讯 | 顶部 **资讯** Tab → **同步 RSS** |
| 导出摘要 | 阅读器 → **导出** |
| 任务管理 | **设置** Tab → 查看 / 取消进行中的导入与摘要 |
| 设置 | **设置** Tab（引擎启停、听书音色、语言、联网 provider、深色模式） |
> **说明**：**Cursor** 预设资源走 OpenAI 兼容 HTTP 路径（`POST /v1/chat/completions`），需在设置中配置代理 Base URL 与 API Key（Cursor 官方暂无原生 chat/completions endpoint）。默认亦支持 Ollama、OpenAI、OpenRouter 等。
### 数据在哪
全部在本机：
```
macOS: ~/Library/Application Support/Lumina/
```
### 常见问题
**提示「Apple 无法验证 Lumina…」？**
见上方 [首次打开](#首次打开无法验证--可能危害-mac) 三种方法；推荐右键 → **打开**。
**打不开 / 提示损坏？**
系统设置 → 隐私与安全性 → 仍要打开；或右键 Lumina → 打开。
**导入失败？**
确认 Ollama 已安装且在运行（菜单栏有 Llama 图标），并已下载 `qwen3.5:4b` 模型。
**内存较小？**
在 Ollama 中改用 `qwen3.5:2b` 或 `qwen3.5:0.8b`，并在 Lumina **设置** 中调整（若已配置模型）。
**升级后云端 API Key 失效？**
旧版曾把密钥存在 macOS 钥匙串；新版改由本机 `~/Library/Application Support/Lumina/secrets.json` 保存。若升级后联网或云端模型不可用，请在 **设置** 中重新输入 API Key 并保存一次。
**第一段摘要较慢？**
首次把模型载入内存需 30 秒～2 分钟，属正常现象。
**想加快整书摘要？**
在 **设置 → API 资源** 中编辑 Ollama 资源，将「并发」调到 2–3（默认 2）。同时为本机 Ollama 设置 `OLLAMA_NUM_PARALLEL`（建议与并发一致），例如 Homebrew：
```bash
# ~/Library/LaunchAgents/homebrew.mxcl.ollama.plist 的 EnvironmentVariables 中加入
# OLLAMA_NUM_PARALLEL=2
# 然后重启 ollama serve
```
内存吃紧或单段延迟变差时调回 1。
---
## 开发者
面向贡献者与从源码构建的同学。普通用户请只看上一节。
### 环境
- macOS 14+（SwiftUI）或 Windows 10/11（WinUI 3）
- macOS：[Xcode 15+](https://developer.apple.com/xcode/)
- Windows：[.NET 8 SDK](https://dotnet.microsoft.com/download) + Visual Studio 2022（Windows 应用开发工作负载）
- [uv](https://docs.astral.sh/uv/)（Python **3.11+**）
- [Ollama](https://ollama.com) + `qwen3.5:4b`
### 本地开发
```bash
git clone