深度阅读 Madao1210/dsh-deep-reading

dsh-deep-reading

Deep Reading —— DSH（DeepSeek Harness）的深度阅读插件：Token 效率优先的读书流程。
导入拆章 → 单章精读（子代理）→ 带 [n] 定位的章节记忆 → 已读复用 → 逐字导出。

- 像读过书的人在讲：不是摘要，不是搬运目录，而是「我读完了，我来跟你聊这本书」。

- 有 AI 自己的观点：能说「这点我同意 / 这里我觉得作者有问题」，而不是只复述作者。

- 让用户真懂：重点是理解，不是信息量。

它把「读一本书」变成一件可累积、可续读、可导出的事：

- 读过的每一章都留下带段落定位的讲解记忆；换一个阅读目的，可以不重读原文直接复用；
- 读一半关掉，新会话说一声「继续」就原样接上；
- 读完全书，一键导出成逐字不差的 EPUB 或 Markdown。

省 Token 的关键：章节原文只在子代理里读、主会话只收短结果——一本书的正文永远不会灌进主对话，读再厚的书，上下文也不会被撑爆。

读书功能

导入拆章：EPUB / Markdown / 纯文本 / PDF 都能进

- 支持五种来源：EPUB、单个 .md、目录（一个 .md 文件一章）、.txt、.pdf。
- .txt / .pdf 先转成 Markdown 再切章（lib/convert.js），转换全文留在 books/<ID>/source.md。
- 切章规则：Markdown 按 # 一级标题切，标题之前的内容算「前言」，一个标题都没有就当整本一章； EPUB 按书自身的章节结构（spine）逐节收，EPUB 2 会自动升级后导入。
- 导入时给每章正文编好段落号（[1] [2] [3] …）——后面所有的「定位」都建在这个编号上。
- 源文件没变再导入会返回 skipped:true，不重做。
- 导入完只报书名和章数，不转述章节内容。

单章精读：原文只在子代理里读

- 你说「精读第 N 章」，主会话会派生一个章节子代理（reading_chapter 工具）。
- 子代理带着本章原文和阅读目的独自读完，返回一份「讲解 + 状态行」——讲解原样呈现给你，同时落盘为本章记忆。
- 原文不进主会话：一本书读下来，主对话里只有短结果，上下文很轻。
- 超长章节自动分节（默认每节 12000 字节）：中间检查点标 partial + covered "1-3/7"，读完全章才转 complete；中途断了下次从断点续，不从头再来。

章节记忆：每条结论都能指回原文段落

- 记忆写进 memory/NNN.md，每条主张必须带 [n] 段落定位（工具强制校验，缺定位直接拒绝写入）。
- complete 的记忆不可回改：后来理解变了，就在后续章节的记忆里写「修正了第 N 章的某结论」——记忆只追加，像一份可以回放的阅读史。
- 记忆绑定当时的原文哈希：章节文件一旦变了（比如你手工修过 source.md），旧记忆自动判为「过期」，不会被悄悄用错。

已读复用：换个目的，也不用重读原文

- dr_status 给每章判 reusable：记忆 complete + 源哈希一致 + 记忆协议版本一致，三个都满足才算数。
- 遇到 reusable 的章，直接基于记忆讲解（开头注明「（基于已有记忆，未重读原文）」），不派子代理、不重读、也不打断你确认。
- 换视角也行：上次从制度角度读的，这次要「从人物角度再讲一遍第 2 章」——照样复用。

跨会话续读：读一半关掉，下次原样接上

- 新会话里说「继续读书」：dr_status 全书扫一遍，找到第一个还没读完的章（未读 / 读到一半 / 过期）接着读。
- 前文记忆由子代理按需读取，不用你复述读到哪了。

回查原文：段落 / 短语 / 关键词三种定位

dr_read 四种模式，全部只读、绝不写盘：

- index：列全书章节目录（含每章段数、记忆状态）；
- range：按段落区间读原文（带 [n] 锚点，超字节上限自动截断并给 nextFrom）；
- locate：按短语定位段落（附上下文窗口）；
- find：关键词检索全书或指定章。

问「作者那句话原话是怎么说的？」时用得上。

你的想法单独存：和 AI 解释分开放

四类信息严格分开，互不污染：

| 类别 | 存哪 | 规则 |
| 原文事实 | chapters/ | 只由 dr_import 写 |
| AI 解释 | memory/ lecture/ | 每条带 [n] 定位 |
| 你的想法 | user/NNN.md | 只记你的原话，不加 AI 解读 |
| 你的理解状态 | user/state.md | 只记有证据的（引用你的原话） |

另外 reader.md 记你的阅读目的与偏好，精读每章前都会先看它。

导出：逐字拼接，AI 不重写一个字

- Markdown 导出：写一份 manifest（标题行 + @include 行）， @include <相对路径> 会被替换为该文件的逐字内容，其余行原样保留——原文和记忆怎么编排进阅读笔记，你说了算。
- EPUB3 导出：dr_export_epub 把逐章讲解 lecture/.md 拼成电子书，逐字收录，未读章节自然缺席。
- 两种导出都由脚本做拼接，模型不参与改写。

用量账本：每章花了多少 Token，看得见

- 每完成一步（导入 / 精读一章 / 续读 / 导出）记一笔到 usage.jsonl，子代理的 token 也会折进去。
- dr_usage 的 report 模式按章汇总：哪一章读得贵、合计花了多少，一目了然。

一次典型阅读

你：把《置身事内》.epub 导入，ID 用 zhi-shen-shi-nei → 拆成 N 章（只报书名 + 章数）你：精读第 1 章 → 子代理读完，返回带 [n] 定位的讲解（原文没进主会话）你：继续 → 从第 2 章接着读你：以「地方政府」的视角再讲一遍第 1 章 → 复用已有记忆，未重读原文你：把讲解导出成 EPUB → 得到逐字收录的电子书

安装

dsh plugin --profile <profile> add <本目录路径>

桌面版（profile 名 desktop）装完后必须重启 DSH 桌面应用才会加载。

书库位置

默认 $DSH_HOME/deep-reading/books。想把书库放到别处、或多套安装共用同一批书、同一份记忆与用量账本，就在 profile 的 cordis.patch.yml 里改：

- id: dsh-deep-reading
name: dsh-deep-reading
config:
booksRoot: 'D:/deep-reading/books' # 改成你自己的书库路径

注意：这条是整体替换 config，不是一个字段的合并。

工具速查

| 工具 | 作用 |
| dr_import | 导入 EPUB / .md / .txt / .pdf / 含 md 的目录，拆章 + 建索引；txt/pdf 先转成 Markdown，转换全文留 source.md；源未变则 skipped:true |
| dr_read | mode: index / range（带 [n] 锚点、按字节分节）/ locate / find |
| dr_write | 写 memory / lecture / user-note / user-state / reader / export（export 做 @include 逐字拼接） |
| dr_status | 每章状态与 reusable 判定（含源文件 hash 比对） |
| dr_usage | 用量账本记账 / 汇总（含子代理 token 折算） |
| dr_export_epub | 把 lecture/.md 拼成 EPUB3（逐字收录，不重写一个字） |
| reading_chapter | 派生单章精读子代理；目标章 reusable 时直接短路，不 spawn |

技能

- deep-reading：入口流程（模型可调用）；用户说「读这本书 / 继续读书 / 精读第 N 章 / 导出阅读笔记」时进入
- deep-reading-chapter：章节子代理的说明书（模型/用户都不可调用，只作为子代理 persona，由 reading_chapter 注入）

源格式与转换（txt / pdf）

- .txt：BOM / UTF-8 / GB18030 / Big5 自动判定（按高频汉字打分；拿不准会在导入报告里写"不确定"）； "一行一段"还是"硬换行"由正文自己说话（看句末标点比例 + 空行密度）。
- .pdf：需要文字层。中文靠 pdfjs 的 CMap 表，lib/convert.js 里两处不能动： cMapUrl 必须传纯文件路径（Node 的 fetch 不支持 file://），并且要显式换用 pdfjs-dist/legacy/build/pdf.mjs（官方 Node 构建；unpdf 自带的 serverless 构建读不了 CMap 表）。
缺任何一处，中文 PDF 会静默抽出 0 个字（看起来像扫描件）。
- 扫描件（图片版、没有文字层）会被拒绝导入并提示先 OCR；本版不做 OCR。
- 转换全文留在 books/<ID>/source.md（默认可见，切章时排除）。
想手工修标题：改 source.md 给标题行加 # ，再按 .md 导入。

数据目录 books/<ID>/

| 路径 | 内容 | 谁写 |
| book.json index.md chapters/NNN.md .map.json | 元数据与原文事实 | 只由 dr_import 写 |
| source.md | txt/pdf 导入时的转换全文（不参与切章） | 只由 dr_import 写 |
| memory/NNN.md | AI 解释（每条主张带 [n] 定位） | 章节子代理 |
| lecture/NNN.md | 逐章讲解正文（EPUB 的来源） | 章节子代理 |
| user/NNN.md user/state.md reader.md | 用户想法、理解状态、阅读目的 | 主会话 |
| exports/ | 拼接 / EPUB 导出 | dr_write / dr_export_epub |
| usage.jsonl .usage-agents.json | 用量账本 | dr_usage / reading_chapter |

测试

npm run load-check # 插件契约：81 项（context 桩、schema 结构、每个工具实跑、转换依赖）
npm test # 行为门禁：114 条规则（幂等、截断衔接、记忆不可回改、导出越界、txt/pdf 转换…）
npm run host-check # 用桌面应用自带的 cordis/ToolRuntime/SkillRegistry 真跑一遍：74 项
npm run check # 三个一起跑（共 269 项）

host-check 需要本机装有 DSH 桌面版（只读，不改动应用）；非默认安装目录用 DSH_APP_DIR 指定。它会自动用应用自带的 Electron-as-Node 重新启动自己。

许可证

MIT © 2026 Madao