英语精读器 colsonSung/dsh-reader

DeepSeek Harness 阅读器

导入一本电子书，然后逐句精读——听朗读、跟着同步语音打字，或者朗读后与原文比对。书留在你自己的机器上，桌面应用和每个浏览器共用同一个书库。

插件在 DeepSeek Harness 左侧边栏加一个 Reader 面板。学习者用到的功能全在页面里跑：文件导入、解析、匹配界面、语音识别。

中文说明：导入 EPUB / TXT / Markdown / HTML / PDF 后逐句精读——听朗读、跟着同步语音打字、或朗读后与原文比对。书库由宿主托管并落盘，桌面应用与浏览器共用同一批书，文件不出本机。完整的中文技术文档见 plugin/README.md。

演示

下面这段录屏是真实插件，跑在 Harness 网页界面里，对着真实书架：书库、打开的书、点词弹出的词卡、生词表。

Reader，从书库到词卡

GIF 时长 40 秒。同样的走查也有 demo.mp4（1384×900，775 KB）。

下面的录屏和截图都取自运行中的应用，不是预览环境，所以展示的就是插件实际的样子。应用自己的侧边栏收成了图标栏：那里列的是阅读器自己的会话，跟别人无关。

功能一览

| 导入 | 拖入 EPUB、TXT、Markdown、HTML 或 PDF；PDF 走懒加载分块，首屏依然很快 |
| 书库 | 书架带封面缩略图（或列表）、搜索，还有三项阅读统计：阅读时长、播放时长、阅读速度 |
| 每本书 | 直接从封面开始听——播放按钮就在封面上，一直都在，不用悬停——外加词频、书籍详情、重命名、删除，书没有封面时用 AI 画一张 |
| 听 | 朗读当前练习单元，逐词高亮；速度可调（0.5x–2x）、可选音色、支持循环。音色列表跟随书的语言：英文书给英文音色，中文书给中文音色 |
| 打字 | 就地在段落里打字——当前词高亮，打错标红，上方显示准确率和速度，语音跟着你打的字走 |
| 朗读 | 语音识别转成文字后与原文逐词对齐，标出你跳过、读错、多读的地方；识别不了就退回录音，自己打分 |
| 中文书 | 能读。中文句子在 。！？ 处断句，每个字算一个词，标点留在页面上不消失，音色和识别器都跟随书的语言 |
| 点词 | 词卡给出音标、词性、释义、例句——还有这个词在这一句里怎么读，实时生成 |
| 生词 | 给词标星就收进生词本：抽屉里有进度环（已掌握 / 学习中 / 待学习）、今日新增、搜索和筛选 |
| 间隔复习 | 收藏的单词立即进入复习队列，按 1 / 2 / 4 / 7 / 15 / 30 天的间隔排期 |
| 在线书库 | 搜索 Project Gutenberg，不用离开应用就能导入公版书 |
| 笔记 | 每句一条笔记，和书一起放在 Host 的书架上 |

书架

书架：封面、三项阅读统计、搜索，以及每本书的菜单。

library

阅读器

打开一本书。段落就是练习场：当前句子高亮，其余部分是上下文，你之前收藏的单词保留自己的颜色。

reader

生词表

vocabulary

安装

git clone https://github.com/colsonSung/dsh-reader.git
cd dsh-reader
./install.sh # installs into the profile of the running Harness

install.sh 可以带一个可选的配置档名（./install.sh web），并且是幂等的。它把包安装进配置档，再把 bundle 行加到 <profile>/cordis.patch.yml。装完要重启 Harness —— 插件的 host 半边在启动时加载。

手动等价操作：

dsh plugin --profile web add ./plugin

<profile>/cordis.patch.yml
- insert:
- id: reader
name: 'dsh-reader'

重启后，左侧边栏的 Global 面板里会出现一个 Reader 图标。

可选：AI 通道

上面这些功能完全不需要 key。浏览器自带的 Web Speech API 提供语音，Harness 自己的模型回答单词卡。

如果你想要云端语音、语音识别和 AI 绘制的封面，就给 Host 半边配一个 MiniMax key。它从环境变量读取，或从工作区之外的私有文件读取：

export MINIMAX_API_KEY=... # 1. the environment
mkdir -p ~/.dsh/reader && echo -n '...' \
~/.dsh/reader/minimax.key && chmod 600 \
~/.dsh/reader/minimax.key # 2. a private file

key 不会进入 bundle，也不会到达浏览器。没有 key 时插件安静降级：单词卡回退到 Harness 模型，云端语音回退到浏览器语音。

可选：在线书库

书库里的 🌐 按钮打开 Project Gutenberg。目录由 Host 拉取一次（约 21 MB，所以不适合放进 bundle），缓存在 ~/.dsh/reader/ 下，保留七天。

工作原理

插件分两半。

客户端半边是面板：它在页面里解析文件，通过 Host 读写书架，渲染书架和阅读器，驱动 Web Speech API。它注册一个侧边栏面板图标和一个主页面。

Host 半边负责页面做不安全的三件事：保管 API key，与服务商通信，管理磁盘上的书库。它通过 Connection 服务的 Fetch 注册表注册一个路由 /api/reader，调用方用同一个浏览器会话完成认证应用其余部分使用：

| 方法 | 作用 |
| word / translate / breakdown | AI 辅助给出的答案，以 Harness 模型作为兜底 |
| tts | 朗读语音，由服务商合成 |
| asr | 转写你自己的朗读 |
| cover | 生成书籍封面 |
| voices | 可用的语音 |
| status | 哪些通道可用 |
| source | Gutenberg 目录的搜索与下载 |
| shelf | 书库本身：书籍、词汇、笔记和播客 |

书库的位置

书架归 Host 所有，写入配置档下的磁盘：

<profileDir>/reader/
├── books/<bookId>.json one file per book, the whole record
├── vocabulary.json
├── notes.json
└── podcasts.json

它以前放在浏览器的 IndexedDB 里，那是个坑：IndexedDB 按源隔离，所以桌面应用（dsh-app://app）、浏览器标签页（http://127.0.0.1:<port>）和下一次运行的应用（不同的端口）各自有一份互不相干的书库。书从没丢过——它们在另一个源的存储里。现在由 Host 持有：每个窗口看到同一个书架，跨浏览器、跨端口、跨重启都一样。

写入是原子的（先写 .tmp，再重命名），损坏的文件会被跳过而不是导致致命错误，记录按原样存储——Host 从不丢弃它不认识的字段。写入阅读位置以进度补丁的形式传输，所以每读一句只有几个字节过网，而不是整本书。

还存着书的浏览器会在插件首次加载时把它们交出来：Host 只在自己没有某个集合时才接收它，所以你删掉的书不会回来。浏览器自己的 IndexedDB 保留为兜底，供尚未重启的 Host 使用。

完整协议见 plugin/docs/CONTRACT-SHELF.md。

预览 harness

书架和阅读器无需运行 Harness 也能渲染。预览用模拟的客户端上下文和预置书架挂载真实的页面组件：

cd plugin
node tools/preview/build.mjs # → tools/preview/preview.bundle.js
cd tools/preview
python3 -m http.server 8080
then open http://localhost:8080/ (add ?view=reader for the reading page)

预览里没有 Host，所以演示书架会预置到浏览器的 IndexedDB——正是阅读器在 Host 还没有书架时用的兜底。IndexedDB 需要真实的源，所以预览必须通过 http 提供。

构建与测试

cd plugin
pnpm install
node build.mjs # → client.js and client.pdf.js
node --test tests/.test.mjs # 310 passing

client.js 和 client.pdf.js 是随包发布的浏览器 bundle，已提交到仓库，所以克隆后无需构建步骤即可安装。只有编辑 plugin/src/ 之后才需要构建。

构建会把当前时间戳打进 bundle，页面会显示它，所以仍持有旧 bundle 的窗口一眼就能认出来。这也意味着 client.js 在多次构建之间不是字节级可复现的。

仓库结构

plugin/ the DeepSeek Harness bundle
index.js the Host half: the /api/reader route
src/client-entry.js the client half: panel icon, page, dictionaries
src/host/ the Host services: the shelf on disk, AI, MiniMax, Gutenberg
src/lib/ parsers, the reading engine, the shelf client and its fallback
src/ui/ the shelf, the reader, the word card, the vocabulary
tests/ 310 tests over the parsers, the engine, the shelf and the UI
tools/preview/ a standalone harness that renders the reader
docs/ the screenshots and the demo recording
install.sh installs the bundle into a profile

已知限制

扫描版 PDF 没有文字层可供提取。插件会明确提示，并请你改用 EPUB 或 TXT。
* 语音识别依赖浏览器的 Web Speech API。Chrome 和 Safari 可用；部分 Electron 运行时没有识别服务，插件会退化为「录下来自己打分」。
* 不派发 boundary 事件的浏览器（Safari、Firefox）在词级高亮上退化为估算。
* 不支持 MOBI / AZW3 / FB2：没有可靠的纯前端解析器，导入会被拒绝并给出明确提示。
* 只有一章的书按段落列出，而不是按章节。
* Host 部分需要重启。 书架由 Host 提供，所以改动 plugin/index.js 或 plugin/src/host/ 后，要重启 Harness 才生效。在此之前，客户端回退到浏览器自带的 IndexedDB——阅读器照常工作，只是书架还没共享。
* shelf 会列出整本书。 书架视图需要正文来统计词数和词频，所以 books.list 会完整返回每本书。书少时没问题，书库一大就变慢；写入阅读位置以进度补丁的形式传输，不受影响。
* 中文按一字一词计数。 没有中文分词器，词汇表和词频都以单字为单位，而不是词。因此中文书的百分比会比以前小——一本 2,305 字的书是 2,305 词，不是 514 词。阅读记录本身不受影响。
* … 一律视为句末。 英文书里 "Wait… what" 会被切成两段。演示用的书里有四处这样的省略号；如果一本书里全是省略号，这条规则就得收紧。
* 本地只有一个中文语音。 macOS 自带一个普通话语音（Ting-Ting）；另外 64 个中文语音来自 MiniMax 通道，需要 key。

许可证

MIT © 2026 Ethan Song