前言¶

在 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