前言¶

在 DSH 里做「读书助手」，常见做法是整本书正文进上下文，再用提示词要求模型不要剧透。进度往往用百分比或字符偏移记录，换字号或窗口一变，锚点就漂。复习环节也常依赖模型现场出题，断网或没配模型时整条链路就空转。

下面介绍的是社区插件 伴读（OtakuP417/dsh-reading-companion）：把 已读章节 当作硬边界，未读内容在检索与工具入口层就被挡在外面；位置用 EPUB CFI 与进度里的 sectionIndex 对齐；讨论默认是苏格拉底式追问；复习卡片由规则生成、用 SM-2 排期，不调用模型也能照常复习。它不替你把书读完，只围绕你已经读过的文字帮你想清楚，并把讨论收成能跳回原文的收获与卡片。

这是什么¶

伴读 是 DeepSeek Harness（DSH）下的 工作流 类插件，维护者为 OtakuP417，许可证 MIT，当前包版本 0.1.0（以仓库 package.json 为准）。

装好后在 GUI 左侧边栏会出现书本图标，点开占满主区的「伴读」页：左侧正文（基于 foliate-js），右侧就着你刚读完的那段聊。数据落在 DSH 数据目录下的 reading-companion/（默认如 ~/.dsh/reading-companion/）。插件本身不依赖在线服务（只有模型对话需要网络/API）。

和「全书摘要 + 自由问答」差在哪里¶

核心功能¶

进度门（CFI + sectionIndex）¶

一本书只有一份可信进度：sectionIndex 表示已读到第几章，只增不减。提示词可读边界、检索范围、摘要生成上限、进度门判断都从这一份进度派生；往回翻不会把已读章节重新藏起来。

硬防剧透¶

读取未读原文的入口（工具、HTTP）先过 gateTarget / requireReadable；检索索引用 filterReadable 构建，未读章节原文不在索引里；另有 tools.guard 在工具执行前按原始参数再拦一次。

三个面板¶

1. 讨论：默认以提问为主；本章可按「本章收口」用你自己的收获复盘，不回头重读原文。
2. 收获：按章分组，可「回到原文」跳到 CFI 对应句子。
3. 复习：正面是问题，背面是讨论摘要与 CFI；不做测验打分，动作是看一眼后决定要不要重读；回忆不起来同样可回到原文。

多格式导入¶

非 EPUB 会先规整成插件生成的 EPUB，再走同一套渲染、索引、CFI 与进度门管线，保证阅读器与索引对「第 N 章」指向同一段文字。

离线检索与复习¶

检索使用 BM25 + 字 n-gram 哈希向量的 HybridIndex（离线、零依赖），不是在线 embedding。收获到卡片由 cards.js 纯规则生成 1～3 张原子卡片；排期封装 vendored 的 supermemo2（MIT）。

安装与启用¶

前置条件：

• DSH 版本满足 engines.dsh：>=0.2.0-rc.1 <0.3.0-0（不满足会在安装前被拦下）；
• 能访问 github.com（dsh plugin 通过 pnpm 拉源码包）；
• 换机安装 不需要 在目标机器上单独装 Node 或跑 npm install / npm run build，仓库内 lib/ 为预构建产物。

桌面 profile 官方安装命令：

dsh plugin --profile desktop add "github:OtakuP417/dsh-reading-companion"

装完后 刷新 GUI：侧栏出现书本图标，点开进入伴读整页。Web 部署时 profile 可能是 web，需与当前环境一致。dsh 不在 PATH 时可用桌面版自带的 dsh.cmd（路径随安装位置而变）。

更新：再执行同一条 add 会拉到最新 main。卸载：

dsh plugin --profile desktop remove dsh-reading-companion

Host 侧 ESM 模块无热重载；更新或改 Host 代码后 重启应用 最稳；仅改客户端产物时刷新页面即可。

GitHub 连不上时，可下载 ZIP 解压后本地路径安装（资料中的离线方式）：

dsh plugin --profile desktop add "D:\解压出来的\dsh-reading-companion-main"

典型用法¶

1. 安装并刷新后，从侧栏进入伴读，导入支持的电子书（EPUB 或可归整格式）。
2. 在阅读器中推进章节；进度随阅读更新，sectionIndex 只增不减。
3. 在讨论区就当前已读内容对话；需要收束时用「本章收口」，收获写入按章分组的数据。
4. 在复习面板按 SM-2 排期看卡片；需要时用「回到原文」跳转到 foliate-js 中的 CFI 位置。
5. 换机器时拷贝数据根目录即可续读（纯 JSON / JSONL）：

macOS / Linux: ~/.dsh/reading-companion/
Windows: %USERPROFILE%\.dsh\reading-companion\

只同步进度时可只拷 progress/ 目录。

适用场景与注意¶

适合：在 DSH 桌面/Web GUI 里边读 EPUB（或可转换格式）边做 constrained 讨论、希望 函数级 而非提示词级防剧透、希望复习 不绑模型 的读者或工作流搭建者。

注意：

• 插件在 当前 DSH 进程权限 下运行；安装前请自行查看 GitHub 仓库 源码与 MIT 许可证。
• 面板内部文案为中文硬编码；PDF、AZW3/KF8 不支持；MOBI 无图；CBZ 无文字可讨论。
• 已知限制与验收范围见仓库 README（含 58 条单测、多种格式导入等说明）。

结尾¶

伴读把 阅读进度 当作唯一坐标，用 CFI 与进度门约束可见原文，用默认追问代替被动摘要，用规则卡片与 SM-2 承担复习。若你在 DSH 里需要「只聊读过的部分」，可以从官方安装命令装起，在侧栏伴读页里试一本 EPUB。

• 社区目录页：https://www.skillhub.cn/plugins/OtakuP417/dsh-reading-companion
• 源码与完整文档：https://github.com/OtakuP417/dsh-reading-companion