# DSH 书架 2.4.4 — 安装说明

这是一个 DSH Web UI 持久化插件：在侧边栏增加「书架」，支持阅读 EPUB、PDF、TXT、Markdown、HTML、FB2、DOCX，并在选中文字后让 AI 结合上下文解释。

从书架目录之外打开或导入的书籍会自动复制到书架目录（默认是第一个工作区，本机为 `D:\BookLib`）；同名同内容复用已有副本，同名不同内容使用 ` (2)` 后缀，不覆盖原文件。

## 运行要求

- DSH 0.2.1-rc.2 或更新版本（插件清单已声明 `dsh.engines.dsh >= 0.2.1-rc.2`）。
- 目标电脑已经配置好可用的默认模型。插件不保存 API Key，使用 DSH 当前默认模型。
- 不需要 npm 账号；本包没有运行时依赖，安装不需要联网。

## 安装到另一台电脑

1. 把 `dsh-epub-reader-2.4.4.tgz` 复制到目标电脑的任意目录。
   - 建议放在 `Downloads` 这类简单路径下。
   - **不要解压** tgz。
2. 打开 DSH Web GUI。
3. 左侧点击 **Plugins / 插件**。
4. 点击 **Add plugin / 添加插件**，选择 **Install a third-party plugin / 安装第三方插件**。
5. 在包输入框中粘贴 tgz 的**绝对路径**（不是目录），例如：
   - Windows：`C:\Users\你的用户名\Downloads\dsh-epub-reader-2.4.4.tgz`
   - macOS / Linux：`/Users/你的用户名/Downloads/dsh-epub-reader-2.4.4.tgz`
6. 点击 **Install / 安装**，等待安装完成。新 bundle 默认启用。
7. 刷新页面。左侧应出现 **书架** 图标。
8. 如果没出现，回到 **Plugins** 页面，确认 `@local/dsh-epub-reader` 处于 **On** 状态。

> 也可以把整个 `epub-reader-plugin` 文件夹复制到目标电脑，在同一个安装框里填该文件夹的绝对路径。tgz 方式更适合传输，文件夹方式更适合继续修改源码。

## 支持格式

- **EPUB**：完整章节、目录、图片和封面
- **PDF**：提取文字层，每 8 页一组；扫描版 PDF 需要先用 OCR 处理
- **TXT / Markdown / HTML / FB2 / DOCX**：自动转换为分章阅读
- **MOBI / AZW3 / AZW**：需要先用 Calibre 等工具转换为 EPUB 或 PDF

PDF 解析使用插件内置的 PDF.js，不需要额外安装 npm 依赖。

## 使用

1. 把书籍文件放进书架目录（本机 `D:\BookLib`），或直接点书架里的 **打开书籍** / 拖入文件。
2. 外部文件会先复制到书架目录，再打开副本；界面会提示副本路径。
3. 选中正文文字，浮动栏会立即出现：左边是提问输入框，右边是 **解释** 按钮；下方还有 **翻译 / 举例 / 背景 / 解释** 四个快捷按钮。
4. 在输入框里写问题，点 **解释** 或按回车；留空点 **解释** 就是直接解释。也可以按 `Ctrl+Shift+E` 直接解释当前选中内容。
5. AI 会结合书籍、章节、原文和你的问题流式回答。之后支持 **翻译 / 举例 / 背景 / 继续追问**。
6. 追问会保留在面板里，并把之前的问答一起发给模型；当前回答生成完成前输入框会暂时锁定。
7. `Alt+←` / `Alt+→` 切换章节，`Esc` 关闭搜索/AI 面板。
8. 按 `Ctrl+F`（macOS 为 `⌘F`）或点右上角 **全书搜索**，可跨全部章节查找文字；结果会显示章节、序号和上下文，点击后跳到对应章节并高亮全部匹配。简体查询也会匹配繁体正文，例如 `陈文龙` 能找到 `陳文龍`。
9. 阅读进度自动保存在浏览器 `localStorage`。

## 论文模式

1. 在“书架 / 在线搜书”标签右侧点 **论文模式**，进入独立论文库。
2. **导入 PDF** 英文论文；左侧“全部论文”右侧的文件夹图标可新建文件夹。右键论文库空白处也可新建文件夹/导入论文；右键文件夹可导入论文到该文件夹或重命名；右键论文卡片可阅读或重命名。论文卡片也可以直接拖到文件夹。
3. 论文卡片点 **阅读**（复用 AI 解释和 `Ctrl+F` 全书搜索）；进入阅读界面后，点右上角 **中英对照** 显示中文翻译，再点 **隐藏中文翻译** 回到纯阅读。
4. 对照界面左侧英文段落，右侧中文译文：
   - **翻译本段**：翻译单个段落，结果追加写入翻译文件；
   - **整篇翻译**：逐段翻译并生成一篇新的中文论文；
   - 可直接编辑译文，点 **保存校正**；人工校正的段落会保留，重新翻译默认不覆盖；
   - **重新翻译** 可重做单段或整篇。
   - 翻译框首次打开会自动撑到可阅读全文；拖动底部边缘可调整高度，高度和收起状态会记住；可单独收起或 **收起全部**。
   - 选中英文原文或中文译文，会弹出和书籍阅读一致的“提问 + 解释”浮动栏；右侧 AI 栏支持继续追问、保存问询和注释记录。
   - 论文 AI 栏默认展开；注释记录里的每条提问和追问默认全部展开，可点记录底部 **继续追问** 恢复线程。
5. 书籍和论文阅读都支持 `Ctrl/Cmd + 鼠标滚轮` 缩放字体；论文对照界面也会同步缩放原文和译文。
6. AI 解释默认展开；可在单条解释上点 **收起**，或点 **收起全部**。
7. 翻译文件保存在 `.epub-reader/papers/translations/`，论文库元数据在同目录的 `library.json`。
8. 目前论文模式只接受有文字层的 PDF；扫描版需要先 OCR。

## 注释记录

- 每次 AI 解释完成、每次提问/追问完成后，都会自动保存这本书的注释和问答记录。
- 注释按书籍内容指纹关联，EPUB/PDF/DOCX 等格式都适用。
- 每次打开一本书，右侧注释栏会自动打开并显示该书的历史记录。
- 点一条记录可以重新打开当时的解释和追问，并继续追问。
- 注释记录默认展开所有提问和追问；记录右上角的 **X** 可删除整条提问，追问旁的 **删除追问** 可删除该追问及其回答。两者都需要再点一次 **确认删除？**。
- 书架右键书籍：**隐藏书籍** / **取消隐藏** / **删除书籍**。删除会移动到 `.epub-reader/trash`，不直接永久删除文件。
- 有隐藏书籍时，书架顶部会出现 **显示隐藏** 按钮。
- 右键论文卡片可 **删除论文**，需要再点一次 **确认删除？**；删除原论文时会同时移除对应的中文论文，并把 PDF/翻译文件移到 `.epub-reader/papers/trash`。
- 论文副本保存在 `.epub-reader/papers/files`，书籍保持在书架目录；两者分开存放。
- 记录保存在书架目录下的 `.epub-reader/annotations.json`；换电脑时把这个目录一起复制，记录也会跟着走。
- 如果只复制书籍文件而不复制 `.epub-reader`，新电脑上不会显示旧注释。

## 在线搜书

1. 在书架顶部切换到 **在线搜书**。
2. 输入书名、作者或关键词，点击 **搜索**。
3. 在结果里点 **下载并打开**。下载完成后会自动保存到书架目录并打开阅读。
4. 只索引 **Project Gutenberg**、**Project Gutenberg 中文**、**中文维基文库**、**中文维基教科书** 和 **Standard Ebooks** 的公版/开放内容；不接入 Z-Library 等未授权书源。
5. 搜索需要 DSH Host 能访问外网；搜索结果缓存 30 分钟，过期后重新搜索即可。
6. Gutendex 不可用时会自动回退到 Project Gutenberg 网页搜索。
7. 中文搜索会自动尝试简体/繁体两种写法，`道德经` 和 `道德經` 都能找到 `道德經`。
8. 中文维基文库 / 中文维基教科书的结果会保存为 HTML 书籍（保留正文和来源标注）；其他内置源下载 EPUB，单本上限 120 MB。
9. 搜索结果是流式返回的：哪个书源先完成，就先显示它的结果；其余书源继续搜索，页面下方会显示“正在继续搜索其他书源…”。
10. 搜索状态在插件内持久保存：切到阅读页、书架或其他 Harness 页面再回来，搜索会继续并恢复查询词和结果；关闭或刷新整个 DSH 页面才会停止。

## 选择书源 / 自定义 OPDS

- 搜索框下方的书源名称是小字链接，点击可直接打开对应网站。
- 点 **选择书源** 可以勾选或取消 Project Gutenberg / **Project Gutenberg 中文** / **中文维基文库** / **中文维基教科书** / Standard Ebooks，选择结果会自动保存；两个 Wikimedia 中文源默认关闭，需要时手动勾选。
- 自定义书源区域点 **+ 添加书源** 可以增加一行，最多 8 个；每一行都可以单独启用、填写名称和 **OPDS 搜索地址**。
- OPDS 地址格式为 `网址/opds?q={query}`；如果书源网址是 `https://example.org`，要填入 `https://example.org/opds?q={query}`。
- 搜索框下方会增加醒目提示：简体中文书源较少，建议手动输入书源网址，或改用繁体中文搜索。
- 自定义书源只接受带 `open-access` 获取链接的 EPUB 条目，用于公版或开放获取的合法目录；不用于未授权书源。
- 多个自定义书源会一起参与搜索，结果按书源分别标注；下载时同样先保存到书架目录，单本上限 120 MB。
- 搜索进行中可以点 **停止搜索**，或点搜索框自带的 X 清空关键词并中止当前请求。

## 自定义

插件配置在包内的 `cordis.patch.yml`：

```yaml
- insert:
    - id: epub-reader
      name: '@local/dsh-epub-reader'
      config:
        # 外部书籍复制到这里；留空 = 第一个工作区（本机 D:\BookLib）
        archiveDir: D:\BookLib
        libraryDirs:
          - D:\Books
        explainProvider: deepseek-account
        explainModel: deepseek-flash
        allowRemote: false
```

- `archiveDir`：外部书籍的副本目录，也是书架默认扫描目录；留空时使用第一个 DSH 工作区。
- `libraryDirs`：额外扫描的目录；留空时只扫描 `archiveDir`。
- `explainProvider` / `explainModel`：固定讲解模型；留空使用该电脑的 DSH 默认模型。
- `allowRemote`：默认 `false`，API 只接受本机请求。

修改配置后重载插件或重启 DSH。通过 tgz 安装时，配置修改后建议重新打包并重装。

## 卸载 / 升级

- 卸载：Plugins → `@local/dsh-epub-reader` → Remove。
- 升级：先卸载旧版，再安装新 tgz。阅读进度按书籍路径保存在浏览器里，通常会保留。
- 安装后不要移动 tgz 或源码目录；移动后需要重新安装。

## 已知限制

- 不支持 DRM 加密的书籍。
- 不支持 ZIP64 压缩的 EPUB（极少数超大书籍）。
- 扫描版 / 纯图片 PDF 没有文字层，需要先 OCR；否则会提示 `PDF_NO_TEXT`。
- MOBI / AZW3 / AZW 需要先转换为 EPUB 或 PDF。
- AI 解释使用当前默认模型；如果模型未配置或额度不足，面板会显示错误。
- 已做代码语法、接口和 React 渲染冒烟测试，但没有在目标电脑上做最终视觉验收；不同 DSH 版本 / 主题下仍建议实际点一遍确认。

## 校验

`SHA256SUMS.txt` 中有 tgz 的 SHA-256。Windows 可用：

```powershell
Get-FileHash .\dsh-epub-reader-2.4.4.tgz -Algorithm SHA256
```

macOS / Linux：

```bash
sha256sum dsh-epub-reader-2.4.4.tgz
```

## 如果要发布到 npm

当前包名是 `@local/dsh-epub-reader` 且带 `"private": true`，适合离线 tgz 分发。若要发布到公共 npm 市场，需要：

1. 注册/登录 npm，并确定你拥有的 scope（例如 `@yourname`）。
2. 把 `package.json` 的 `name` 改成 `@yourname/dsh-epub-reader`，移除 `"private": true`。
3. 执行 `pnpm publish --access public`。
4. 其他电脑在 Plugins → Add plugin 中直接填 `@yourname/dsh-epub-reader`。

发布前请确认你拥有该 scope，并接受 npm 的公开可见性。