PensiveFei/deep-read-summarize
> Disclaimer: This is an unofficial third-party tool. It is not affiliated with, endorsed by, or sponsored by DeepSeek or the DeepSeek Harness project. "DeepSeek" and "DeepSeek Harness" are trademarks of their respective owners. This project only orchestrates the workflow tool available in your DSH environment; it does not redistribute any DeepSeek software.
catalog 简介 / catalog descriptioncatalog description:Deep reading & summarization workflow for books/papers/videos/web — plugin parsers, MapReduce deep-read, JSON Schema output, Obsidian-ready (DSH)
编辑导读Editor's Brief
## 核心特性
- 支持将书籍、论文、视频链接和网页作为输入,并生成带有 YAML frontmatter 的结构化 Markdown 笔记,便于 Obsidian 和 Dataview 使用。
- 将长内容拆分为多个块,并分配给并行子代理,最后将结果合并为单个文档。
- 使用 JSON Schema 约束子任务输出,并对未通过校验的输出进行重试。
- 要求关键结论附带页码、章节或段落引用,并在最终输出前执行质量检查。
- 对于缺失输入或类型无效等配置错误,会直接终止且不输出部分内容;内容解析失败则可跳过并标记为缺口。
## 使用场景
- 将来自 arXiv、PDF 或 HTML 的学术论文总结为带引用的研究笔记。
- 将 PDF、EPUB 或 MOBI 格式书籍转换为可识别章节的 Obsidian 条目。
- 通过字幕或转录文本处理 YouTube 或 Bilibili 视频,生成结构化笔记。
- 提取并总结网页文章内容,用于个人知识库或研究资料库。
## 技术细节
- 该工作流通过 workflow.js 以 JavaScript 实现,并使用针对书籍、论文、视频和网页输入的 parser 模块。
- 它依赖 DSH 工作流原语,例如 agent()、parallel()、phase()、log() 和 args,以及用于子任务校验的受支持 JSON Schema 子集。
- 自定义 parsers 可通过在 custom-parsers/ 中提供 name、types 和 buildPrompt(input, opts) 来覆盖内置类型。
- 安装后会将一个 workflow、一个 skill 文件、四个 parsers 和 JSON schemas 注册到 DSH profile bundle 中。
## 注意事项
- 视频处理需要本机安装 yt-dlp;若缺少字幕,则需要手动提供转录文本。
- DSH 处于 developer preview 阶段,workflow 工具接口可能变化;仓库建议在升级后运行 npm test。
- 外部抓取和文件写入受 DSH sandbox、审批和权限设置限制。
## Core Features
- Accepts books, papers, video links, and web pages as input and produces a structured Markdown note with YAML frontmatter for Obsidian and Dataview.
- Splits long content into chunks and assigns them to parallel subagents before merging the results into a single document.
- Constrains subtask outputs with JSON Schema and retries outputs that fail validation.
- Requires key conclusions to carry page, chapter, or paragraph citations and runs a quality check before final output.
- Reports configuration errors such as missing input or invalid type by terminating without partial output, while content parsing failures can be skipped and marked as gaps.
## Use Cases
- Summarizing academic papers from arXiv, PDF, or HTML sources into citation-backed research notes.
- Converting books in PDF, EPUB, or MOBI format into chapter-aware Obsidian entries.
- Processing YouTube or Bilibili videos through subtitles or transcripts into structured notes.
- Extracting and summarizing web article content for a personal knowledge base or research library.
## Technical Details
- The workflow is implemented in JavaScript through workflow.js and uses parser modules for book, paper, video, and web inputs.
- It depends on DSH workflow primitives such as agent(), parallel(), phase(), log(), and args, plus a supported JSON Schema subset used for subtask validation.
- Custom parsers can override built-in types by providing name, types, and buildPrompt(input, opts) in custom-parsers/.
- Installation registers a workflow, a skill file, four parsers, and JSON schemas into a DSH profile bundle.
## Notes
- Video processing requires yt-dlp on the local machine, and missing subtitles require manually supplied transcript text.
- DSH is in developer preview, so workflow tool interfaces may change, and the repository recommends running npm test after upgrades.
- External fetching and file writing are subject to DSH sandbox, approval, and permission settings.
安装Install
dsh plugin --profile web add github:PensiveFei/deep-read-summarize
把 PensiveFei/deep-read-summarize 加入你的 DSH 配置(web profile)即可启用。
READMEREADME
deep-read-summarize
Disclaimer: This is an unofficial third-party tool. It is not affiliated with, endorsed by, or sponsored by DeepSeek or the DeepSeek Harness project. "DeepSeek" and "DeepSeek Harness" are trademarks of their respective owners. This project only orchestrates the workflow tool available in your DSH environment; it does not redistribute any DeepSeek software.
给 DSH(DeepSeek Harness)写的一个精读工作流:输入一本书、一篇论文、一个视频链接或网页,输出一份结构化的 Obsidian 笔记。
内容会被拆成若干块,由多个子代理并行精读,再合并成一篇带 YAML frontmatter 的 Markdown。关键结论附原文出处,成稿前有一道质量校验。
注意:DSH 目前是 developer preview,接口可能变化。本仓库针对特定版本的 workflow 工具语义编写,见下文兼容性。
能做什么
- 书籍(PDF/EPUB/MOBI)、论文(arXiv/PDF/HTML)、视频(YouTube/B 站字幕)、网页
- 长内容分块后由并行子代理精读,再合并
- 各子任务的输出用 JSON Schema 约束,不合格自动重试
- 关键引用必须标注页码/章节/段落,降低编造风险
- 配置错误直接报错终止;某块内容解析失败则跳过并标记缺口
- 输出可直接放进 Obsidian,配合 Dataview 使用
结构
输入(链接或文件路径)
│
▼
解析器注册表 ── book / paper / video / web
│
▼
波次1 获取内容 → 写入临时文件 → 生成分块计划
│
▼
波次2 N 个子代理并行精读各块(Map)
│
▼
波次3 合并成稿 + 质量校验(Reduce)
│
▼
Obsidian 笔记
三个波次,子代理总数约 N+2 个,N 是分块数。
parsers/ 各输入类型的解析器,按类型分发
book.js 书籍:PDF/EPUB/MOBI 文本提取、章节分块
paper.js 论文:arXiv/PDF/HTML 结构识别
video.js 视频:yt-dlp 抓字幕、转写清洗
web.js 网页:正文提取
index.js 注册表:解析器发现与回退
schemas/ 子任务输出的 JSON Schema
scripts/ lint、安全检查
tests/ fixture 测试与验证脚本
workflow.js workflow 脚本本体(meta + script)
想换某个输入类型的处理方式,在 custom-parsers/ 放一个同接口的解析器即可,同名类型会覆盖内置实现。接口只有三个字段:name、types、buildPrompt(input, opts)。
dsh.so 生态
本仓库带 dsh-plugin topic 和 package.json 的 dsh 字段,可被 dsh.so 注册表索引。
dsh.so 收录要求:公开仓库、dsh-plugin topic(或 dsh 字段)、README 安装说明、SPDX 许可证(MIT)。
提交后标记为 Declared�在官方 Discussions 报告结果,这是唯一升 Verified 的途径。
安装(DSH 插件)
deep-read-summarize 是 DSH 插件,可通过 dsh.so 生态或本地安装:
# 本地安装(dsh profile 目录)
pnpm add ./deep-read-summarize-0.1.0.tgz
# 然后在 dsh 配置的 dsh.profile.bundles 追加:
# - deep-read-summarize
# 重启 dsh web 即可(POST /dsh-market/restart)
安装后自动注册:
deep-read-summarizeworkflow(meta + script)deep-read-summarize技能(skills/deep-read-summarize/SKILL.md)- 四种解析器(
parsers/)与 JSON Schema(schemas/)
快速开始(约 5 分钟)
1. 安装
git clone https://github.com/<your-org>/deep-read-summarize.git
cd deep-read-summarize
npm install # 无第三方依赖,仅初始化
2. 验证环境(离线,不需要任何 API key)
npm test # 17 项 fixture 测试,全部离线跑通
看到 TOTAL: 17 passed, 0 failed 即环境就绪。
3. 一行命令喂入 demo 文件
node -e "const wf = require('./workflow.js'); console.log('meta:', wf.meta.name); console.log('parsers:', wf.parsers.list().map(p => p.name).join(', '));"
输出类似:
meta: deep-read-summarize
parsers: book, paper, video, web
4. 真实运行(需要 DSH workflow 工具)
把下面的 JSON 传给 DSH 的 workflow 工具(见下节「用法」):
{ "input": "https://arxiv.org/abs/2307.09042", "type": "paper", "options": { "maxChunks": 4, "fastMode": true } }
工作流会返回结构化结果:{ ok, kind, title, filePath, qualityPassed, note },note 即最终 Markdown 笔记。
用法
把下面这段 JSON 传给 DSH 的 workflow 工具:
{
"input": "https://arxiv.org/abs/2307.09042", // 链接或文件路径
"type": "auto", // auto | book | paper | video | web
"options": {
"minWords": 2500,
"fastMode": false, // true 时跳过 5-7 节,速度快一些
"maxChunks": 6, // 分块上限,1-12
"requireCitations": true, // 关键结论是否必须标注出处
"includeTimestamps": false,
"outputDir": "./output", // 笔记输出目录(可指向 Obsidian 仓库)
"tempDir": "./.tmp" // 临时文件目录
}
}
示例:
| 类型 | input |
|---|---|
| 论文 | https://arxiv.org/abs/2307.09042 |
| 书籍 | D:/books/xxx.pdf |
| 视频 | https://youtube.com/watch?v=xxx |
| 网页 | https://example.com/article |
输出写到 D:/Obsidian 仓库/PensiveFei/精读笔记/<标题>.md,路径在 workflow.js 里可以改。
视频字幕需要本机装 yt-dlp(winget install yt-dlp.yt-dlp)。没装也不影响其他类型;抓不到字幕时工作流会提示你手动提供转写文本。
失败怎么处理
分两类:
- 配置错误(缺 input、type 非法、options 格式错):直接抛异常终止,不产出半成品。
- 内容问题(抓取失败、某块精读失败):返回
{ ok: false, stage, fatal: false },由调用方决定。某一块失败时跳过它、在成稿里标注缺口,不整体中断。
成本
一篇论文、6 块、完整模式,大约 15-25k token。用 fastMode 并调低 maxChunks 能省四成左右。
安全与版权
- 抓取视频/网页会发起外部请求,由子代理在 DSH 的沙箱和审批策略下执行;不要让模型无人值守地跑任意脚本。
- 子代理写文件需要相应权限;如果权限不够,workflow 会把内容返回,由主代理负责落盘。
- 这个仓库只有流程本身:workflow 定义、解析器代码、提示词模板、schema。不含任何受版权保护内容的提取结果。 测试用的 fixture 是自写的公共领域寓言。用本工作流处理有版权的材料时,产出物的使用责任在你。
开发
npm install
npm run lint # node --check 全部 JS
npm test # fixture 测试
npm run validate # 发布前验证(含安全检查)
改动说明见 CHANGELOG.md,贡献规范见 CONTRIBUTING.md。
兼容性
DSH 还在快速迭代,有过破坏性变更。本仓库的依赖面是:
- workflow 工具的
agent()、parallel()、phase()、log()、args - JSON Schema 子集:
type / properties / required / additionalProperties / items / enum / const / oneOf
升级 DSH 后先跑一遍 npm test。如果坏了,对照 CHANGELOG.md 里的版本记录排查。
License
MIT,见 LICENSE。
amruthpillai/reactive-resume
tt-a1i/archify
strukto-ai/mirage
liustack/modlens
omdsh-dev/DSH-better-sidebar
dsh-market/dsh-market
agentrq/agentrq