书架阅读器 0avatar0/dsh-ai-book-shelf

AI 书架 / AI Book Shelf

一个常驻的 DSH Web UI 插件：在侧边栏加入全页多格式阅读器，为选中文字提供 AI 讲解栏，还带论文库（支持翻译与双语对照）和档案库（支持文件搜索与 AI 摘要）。

亮点

- 支持多种格式 — EPUB、PDF、TXT、Markdown、HTML、FB2 和 DOCX。
- 不用离开页面就能提问 — 选中文字，右侧栏给出背景、上下文、讲解和追问。
- 搜索整个书架 — 全书 Ctrl+F、在线搜书（Project Gutenberg、Standard Ebooks、中文维基媒体来源）以及自定义 OPDS 来源。
- 论文模式 — 段落/整篇翻译、双语对照、AI 讲解和追问。
- 档案模式 — 文件夹、Ctrl+A 批量导入、关键词搜索、对搜索结果生成 AI 摘要，以及按文件夹配置技能。

安装

1. 从最新发布下载 dsh-ai-book-shelf-2.6.11.tgz，或用 dsh-ai-book-shelf@2.6.11 从 npm 安装。
2. 在 DSH 中打开 Plugins → Add plugin，选择下载好的 tgz，或粘贴 npm 包标识。
3. 重新加载插件，在侧边栏打开 AI 书架 / AI Book Shelf。

中文分步指南：INSTALL-zh.md。发布与 npm 说明：PUBLISHING.md。

功能说明

- 书架 — 扫描归档书架（默认是第一个注册的工作区，本部署中为 D:\BookLib），以及额外的 libraryDirs，找出支持的书籍文件。
- 复制外部书籍 — 从归档书架之外打开或导入的书，会先复制进 archiveDir。内容相同的文件直接复用；重名时加 (2) 后缀，不会覆盖任何文件。
- 档案模式 — 独立的档案库，支持文件夹、多选导入（在文件选择器中按 Ctrl/Cmd 或 Ctrl+A）、按文件夹范围全文搜索、流式 AI 摘要和文件夹技能。新建文件夹会附带一个空技能供你填写；导入的 SKILL.md 可以替换它，AI 摘要会遵循它。
- 公有领域搜索 — Search books 标签页会查询 Project Gutenberg（Gutendex，失败时回退到 Gutenberg 网站搜索）、仅中文的 Project Gutenberg 目录（lang=zh）、中文维基文库、中文维基教科书和 Standard Ebooks，然后把选中的书（EPUB，维基媒体来源则为 HTML 书）保存到归档书架。对中文目录，简体中文查询还会用繁体中文再试一次。结果流式一次向页面送入一个来源；较慢的来源继续搜索，而首批结果已经可用。搜索存储位于 Library 组件之外，因此打开书或切换 Harness 页面不会中断流；返回时恢复查询和结果，Host 会让结果 id 保持可下载 30 分钟。只使用公有领域 / 开放许可的目录；不支持 DRM 和未授权的书籍来源。用 Choose sources 选择要查询哪些目录；选中的来源主页会以小链接形式显示。可以添加自定义 OPDS 搜索 URL，但只接受声明了 open-access EPUB 获取链接的条目。用 + 按钮可以添加多个自定义 OPDS 来源。内置中文目录涵盖繁体中文 Gutenberg 书目和 Wikisource；其他目录大多是英文。
- Reader — 把书解析成章节，清理 HTML，渲染出舒适的衬线阅读页面，并按书记录进度。EPUB 保留其 OPF spine、标题、列表、表格、图片和 TOC；PDF/Text/Markdown/HTML/FB2/DOCX 会被规范化为可读章节。
- Ask while selecting — 浮动选择栏在 解释 左侧包含一个提问输入框。输入具体问题后按 Enter 或 解释，留空则直接解释。问题会连同书、章节、选中内容和附近上下文一起发送；右侧栏打开并流式输出答案。
- Follow-ups — 在面板中保留整个问答线程，并把之前的轮次发送给模型，让代词和早先的细节保持在上下文中。你可以停止流、复制答案，或使用快捷提问（翻译 / 示例 / 背景）。
- Per-book annotations — 每条完成的解释及其后续问答都保存在 Host 的 archive 目录下。打开书会打开右侧注释栏，显示该书保存的记录；点击记录可重新打开其问答线程并继续提问。记录在浏览器刷新和重启后仍然存在。
- Paper mode — 单独的论文库，用于英文 PDF，支持虚拟文件夹（创建、拖入论文、重命名）、把段落级翻译写入 JSON 翻译文件、手动修正、重新翻译、把整篇论文翻译保存为新中文论文，以及双语对照视图。论文阅读复用阅读器的 AI 解释和全书搜索；对照视图有和书籍相同的右侧 AI 栏、选择提问栏、后续问答、保存的注释历史和逐答案折叠，并且对英文原文和中文译文都有效。注释历史和线程可以删除整个线程或单条后续问答对，记录右上角有 X，二次点击确认。论文库支持右键菜单新建文件夹、导入到文件夹和重命名；新建文件夹控件是右侧一个图标。在书卡右键菜单里，可以隐藏/取消隐藏或删除书籍（移到 .epub-reader/trash）。论文可以从卡片右键菜单删除（两步确认）；删除源论文时，还会一并删除它的中文翻译论文，并把 PDF/翻译文件移到论文回收站。论文副本存放在 .epub-reader/papers，与书架分开。对比开关位于论文阅读器页眉，可以再次隐藏；每个翻译框都能从底边调整大小，首次打开时自动适配文本，记住高度/折叠状态，可以单独折叠，也可以一键全部折叠。翻译文本支持 AI 解释。
- 缩放 — Ctrl/Cmd + 鼠标滚轮调整书籍和论文的阅读字号；论文对比视图也会缩放源文/译文文本。
- AI 面板 — 解释默认展开，可以单独折叠，也可以用「全部折叠」一键收起。
- 在书中查找 — Ctrl/Cmd+F 打开全书搜索，覆盖每一章，包括 PDF/HTML/DOCX 书籍。结果显示章节、出现位置和文本片段；点击结果会跳到对应章节并高亮所有匹配项。阅读器工具栏在搜索按钮旁显示快捷键。简体中文查询也能匹配繁体文本（陈文龙 能找到 陳文龍）。
- 键盘 — Ctrl/Cmd+Shift+E 解释当前选中内容，Alt+← / Alt+→ 在章节间移动，Esc 关闭搜索/侧栏。

支持的格式

| 格式 | 支持情况 |
| .epub | 完整 spine、章节、目录、图片、封面 |
| .pdf | 提取文本层，每章 8 页；扫描版 PDF 需先做 OCR |
| .txt / .text | 纯文本，自动分块 |
| .md / .markdown | 标题、段落、列表、引用、代码块 |
| .html / .htm / .xhtml | 净化后的 HTML 正文 |
| .fb2 | FictionBook XML |
| .docx | Word 段落和 Heading 1–3 章节 |
| .mobi / .azw3 / .azw | 先转成 EPUB 或 PDF（例如用 Calibre） |

PDF 提取使用 vendor/pdfjs/ 下的内置 PDF.js 运行时；包本身没有针对它的 npm 运行时依赖。

配置

在配置档补丁里编辑已安装行的配置（或在安装前编辑插件的 cordis.patch.yml）：

- id: epub-reader
name: '@local/dsh-epub-reader'
config:
Where outside books are copied and what the shelf scans by default.
Empty = the first registered workspace (D:\BookLib here), then cwd.
archiveDir: D:\BookLib
Extra folders to scan, if any. Absolute paths are allowed.
libraryDirs:
- D:\Books
Optional; otherwise the Host's default model is used.
Example: explainProvider: deepseek-account
explainModel: deepseek-flash
explainProvider: deepseek-account
explainModel: deepseek-flash
Off by default: the API answers only loopback browser requests.
allowRemote: false
Host 路由挂载在 /api/epub-reader 下。这些路由只接受同源浏览器请求，只暴露配置的 shelf 根目录下的 .epub 文件，解析前先把外部文件复制进归档目录，并通过 SSE 流式返回解读内容。

说明

- 图书以只读方式打开；阅读进度保存在浏览器的 localStorage 里。
- 不支持带 DRM 保护的图书。
- PDF 支持以文本优先：扫描版或纯图片 PDF 会返回 PDF_NO_TEXT，而不是显示空白页。请先做 OCR，或先转成文本版 PDF。
- MOBI/AZW3 不直接解析；导入前请先转成 EPUB/PDF。
- 插件使用官方 llm Host 服务；插件本身不读取任何 API key。
- 内存中只保留最近打开的 5 本书；再次打开会重新解析文件。
- 标注历史存放在 <archiveDir>/.epub-reader/annotations.json，以 EPUB 内容指纹为键，所以同一本书换个路径也能保留记录。如果希望标注随书架一起迁移到另一台机器，请把该文件夹和 EPUB 一起复制过去。
- 搜索结果缓存 30 分钟，方便下载结果；过期的 id 会返回 SEARCH_EXPIRED，界面会提示你重新搜索。
- 清空搜索框（浏览器的 X）或点击 Stop searching，会中止进行中的请求，不会让加载动画一直转下去。
- 自定义 OPDS 源必须是合法、开放获取的目录。Host 只接受标记为 open-access 的 EPUB 获取链接；它不是通用下载器。
- 下载上限为 120 MB，且只从允许列表中的 gutenberg.org / standardebooks.org 主机拉取。大文件可能要等一会儿。
- 搜索功能需要 DSH Host 进程具备出站网络访问能力。

许可证

插件代码以 MIT License 发布。内置的 PDF.js 运行时保留自己的 Apache-2.0 许可证，见 vendor/pdfjs/LICENSE；内置字体保留 vendor/pdfjs/standard_fonts/ 下的许可证。