puremapping/dsh-plugin-reading-pipeline

📚 dsh-plugin-reading-pipeline

把一整本书「读完并真正吸收」的 DeepSeek Harness 阅读管线插件
分章读 + 每章笔记落盘 + 读新章前回填上一章笔记 —— 让理解长成你自己的东西。

version
license
DSH
node
topic

⚠️ 非官方社区项目 — 与 DeepSeek AI 无关, 是第三方为 deepseek-ai/deepseek-harness 开发的插件。
协议文档源自社区技能 agent-reading-pipeline (MIT), 由「小霁」原创并发布到 BotLearn。

🧠 它解决什么问题

上下文窗口装不下一整本书。这个插件把读书变成一条 管线：

选书 → epub 转换 → 分章阅读 → 每章笔记落盘 → 读新章前回填上一章 → 读后沉淀 → 跨书概念图

- 机械操作固化为工具 —— 转换、原子写、续读注入、跨书检索, 不需要 agent 每次照着文档手工做
- 协议由配套 preset 承载 —— 六步阅读 / 重读机制 / 反框架批注 / goal-driven 提问 / 笔记验收标准, 全在 SKILL.md 里
- 上下文有预算 —— 注入包 ≤500 tokens, 位置感知排列 (反框架批注放在注意力最强的末尾)

🛠 工具

| 工具 | 作用 | 固化的协议点 |
|---|---|---|
| reading_prep_book | epub → 分章 markdown + 自动验收 (章节数 / 残留 / .tmp) | 新书流程 4-5 步 |
| reading_note_write | 原子写笔记: tmp+rename + 跨进程写锁, append 句子级即时追加 | 写盘策略三改 |
| reading_status | 续读定位 + ≤500 token 注入包 (位置感知: 反框架批注在末尾) | 回填 / 位置感知 / token 预算 / 冷启动 |
| reading_backlink_search | 本地跨书检索 (段落级 AND + 大小写不敏感, 数据不出本机) | 跨书概念图检索层 |

✨ 特性

- 冷启动续读 — 每次会话独立, 靠 reading.md + 磁盘笔记接上"我上次在想什么"
- 句子级即时追加 — 读到被击中的话立刻落盘, 不丢失任何一句
- 原子写盘 — tmp+rename + 跨进程写锁, 写一半断电也不留半截文件
- 位置感知注入 — summary 开头 (primacy) / 证据指针中间 / 反框架批注末尾 (recency)
- 跨书概念图 — 同一主题跨书 ≥2 次自动沉淀 knowledge 概念节点, 冲突不抹平
- 零依赖 — 不 import 任何 @deepseek-ai/* 内部包, 与 DSH 内部解析链解耦, 安装最稳

🚀 快速开始

1. 安装插件 (每个 profile 都要装)

发布版 (GitHub):
dsh plugin --profile web add github:puremapping/dsh-plugin-reading-pipeline#v0.1.1
dsh plugin --profile headless add github:puremapping/dsh-plugin-reading-pipeline#v0.1.1

本地开发版:
dsh plugin --profile web add /path/to/dsh-plugin-reading-pipeline

⚠️ 插件从 profile 目录解析。装进 dsh 安装目录会让所有 profile 崩溃。

2. 安装配套 preset

复制 reading-pipeline-preset/ 到 $DSH_HOME/.agent-presets/reading-pipeline/
新会话里选 "Reading Pipeline" preset

3. 配置

agent.cordis.yml 挂载行 (preset 已内置, 只需改 projectRoot):

- id: reading-pipeline
name: 'dsh-plugin-reading-pipeline'
config:
projectRoot: D:/reading                 # 必填: 读书项目根 (工具只允许读写其内路径)
pythonBin:                              # 可选: python 可执行 (默认探测 python / py -3)
pandocBin:                          # 可选: pandoc 可执行 (默认取 PANDOC_BIN 或 PATH)
backlinkLimit: 10                   # 可选: 跨书检索默认最大命中数

4. 开始读书

「读《被讨厌的勇气》第一章」→ agent 自动: reading_status 定位 → 读章 →
reading_note_write 写笔记 → 更新 reading.md → git commit
「继续」→ 回填上一章笔记 → 读下一章 → …

📖 依赖

| 依赖 | 版本 | 用途 |
|---|---|---|
| Node | ^22.19.0 \|\| >=24.0.0 | DSH 同款要求 |
| python | 3.9+ | epub 转换（Windows 下 python 可能是 Store alias，建议显式配 pythonBin） |
| pandoc | 任意 | epub → markdown（用 PANDOC_BIN 或 pandocBin 指定） |
| @deepseek-ai/cordis | ^4 (peer) | 由 DSH 提供 |

插件自身 零运行时依赖。

🗂 目录结构

dsh-plugin-reading-pipeline/
├── lib/
│   ├── index.js              # name/inject/apply (cordis 插件出口)
│   ├── tools/                # 4 个工具
│   └── util/                 # 原子写 / 路径校验
├── scripts/book-prep.py      # 转换脚本 (与 preset 版同源, preset 为源)
└── README.md

✅ 实测验证 (2026-08-15)

headless 真实工具链 + 四子代理两轮跑书评估 (test-project: 《被讨厌的勇气》06/56 章 + 《动物农场》5 章 + 5 个跨书概念节点):

| 维度 | 评分 | 证据 |
|---|---|---|
| 技术 | 4/5 → 修复后达标 | 原子写全程 0 .tmp/.lock 残留; 检索段落级 AND 实测通过; 注入包初读轮从章节笔记提取 summary (372-701 字符) |
| 阅读体验 | 4/5 | 六步协议被真实执行; 回填注入帮助续读 (后续章引用前章存疑作检验起点) |
| 理解深度 | 5/5 | 笔记均回答章节核心矛盾, 真笔记无缩水/表演式假笔记 (含反框架批注) |
| 内化 | 5/5 | 成长痕迹到行为层面; 跨书主题 ≥2 次正确建 knowledge 概念节点并回链 |

两轮实测共修复 8 项 bug: schema 格式 / 可空字段 / reading.md 表头解析 / readProgress 按 bookName 定位行 / 注入包正则兼容序号标题 / render 输出 summary 预览 / nextChapter 排除作者页 / 检索大小写 + 段落级 AND。

🔗 与 BotLearn 发布版的关系

- 协议版本线 (agent-reading-pipeline v0.3.0, skillhunt): 协议内容变更走 BotLearn CLI 发布。
- 插件版本线 (本包 0.1.1): 代码层能力, 独立 bump; 协议变更时同步更新内置引用。
- scripts/book-prep.py 以 reading-pipeline-preset 为源, 插件打包时复制 (勿直接改插件内副本)。

⚠️ 已知限制

- 检索无英文词形归一 (freedom 匹配不到 free, 需分别检索或用词根)
- 中英关键词不要并列 (AND 语义, 一次查一种语言)
- 笔记协议 (六步/重读/goal-driven) 需要配套 preset 的 SKILL.md 才能完整执行

📄 License

MIT — 协议文档源自 agent-reading-pipeline (MIT)。