📚 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.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
「继续」→ 回填上一章笔记 → 读下一章 → …

📖 依赖

插件自身 零运行时依赖。

🗂 目录结构

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 个跨书概念节点):

两轮实测共修复 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)。