📚 dsh-plugin-reading-pipeline

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

⚠️ 非官方社区项目 — 与 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)。