精读笔记生成 PensiveFei/deep-read-summarize

deep-read-summarize

免责声明：这是非官方第三方工具，与 DeepSeek 及 DeepSeek Harness 项目无隶属关系，也未获其认可或赞助。「DeepSeek」和「DeepSeek Harness」是各自所有者的商标。本项目只编排你 DSH 环境里可用的 workflow 工具，不再分发任何 DeepSeek 软件。

⚠️ 最重要：本工具是「辅助精读」工具，不能代替自主学习。 它帮你快速提取、归纳、结构化阅读内容，但真正的理解、思考与批判仍需你自己完成；请始终以原文为准，不要把它当作学习成果本身。

给 DSH（DeepSeek Harness）写的一个精读工作流：输入一本书、一篇论文、一个视频链接或网页，输出一份结构化的标准 Markdown 笔记（YAML frontmatter，可直接放进 Obsidian / Logseq / 静态站点内容目录 / 任意 Markdown 编辑器）。

内容会被拆成若干块，由多个子代理并行精读，再合并成一篇带 YAML frontmatter 的 Markdown。关键结论附原文出处，成稿前有一道质量校验。

使用中遇到问题、或觉得哪里能更好，欢迎随时在 GitHub issue 反馈。

注意：DSH 目前是 developer preview，接口可能变化。本仓库针对特定版本的 workflow 工具语义编写，见下文兼容性。

平台：Windows / macOS / Linux 同等支持（0.3.9 起），详见下文支持平台。

实际效果

（图用 GitHub 绝对地址，npm 页面同样能显示；图片本身不打进 npm 包，只随仓库分发）

| 精读论文 | 视频笔记（元信息） |
| 论文精读笔记 | 视频笔记元信息 |

| 视频笔记（行动要点） | 会话内摘要 |
| 视频笔记行动要点 | 会话内摘要 |

能做什么

- 书籍（PDF/EPUB/MOBI）、论文（arXiv/PDF/HTML）、视频（字幕优先，无字幕自动转写，出品完整逐字稿精读）、网页
- 长内容分块后由并行子代理精读，再合并
- 获取/分块与质量校验的输出受 JSON Schema 约束，结构稳定、下游可解析
- 分块计划与子代理数量受 maxChunks 强制约束（计划失控会顶穿单次调用时限）
- 关键引用必须标注页码/章节/段落，降低编造风险
- 配置错误直接报错终止；某块内容解析失败则跳过并标记缺口
- 输出标准 Markdown + YAML frontmatter：正文是通用 CommonMark（无双链、无 callout），Obsidian（配合 Dataview）、Logseq、Jekyll / Hugo / Astro 的内容目录、任意 Markdown 编辑器都能直接用

结构

输入（链接或文件路径） │ ▼ 解析器注册表 ── book / paper / video / web │ ▼ 波次1 获取内容 → 写入临时文件 → 生成分块计划 │ ▼ 波次2 N 个子代理并行精读各块（Map） │ ▼ 波次3 合并成稿 + 质量校验（Reduce） │ ▼ Markdown 笔记

三个波次，默认约 N+3 次子代理调用（获取、N 块精读、成稿、质量校验）。auto 遇到 PDF、未知网页或文本等模糊输入时，额外进行一次轻量类型识别；显式指定 type 可跳过识别。
auto 会把明确的视频链接、arXiv 论文链接和电子书扩展名直接分发到对应解析器；同站的专栏、频道与帮助页仍先分类，PDF 则根据内容区分书籍与论文。无法识别时返回 stage: "detect"，请显式指定类型。options.tempDir 作为临时根目录，每次调用在其中创建独立的 run-* 子目录，获取、音频和转写文件不与其他任务共用。

分块计划会排序、裁掉重复区间并补齐缺口，超过 maxChunks 时合并相邻块以保留全文。返回的 coverageComplete 表示是否依据有效的 totalLines 覆盖全部行号；缺少总行数时保留已知范围，同时将 qualityPassed 置为 false 并说明覆盖无法确认。

质量检查分两部分：程序按提供的标量/列表 frontmatter 模板检查字段、必要章节和篇幅（汉字按字、其他文字按词，排除 frontmatter、代码块、HTML 注释及链接地址）；独立核验代理读取本次原文文件，逐块检查覆盖，并为第 4 节的逐字引用返回原句和行号。单独的 pass: true 无法通过检查。qualityChecks 返回检查项，qualityEvidence 返回原文路径、分块摘录和引用证据；原文真实性判断仍由读取原文的代理完成，无法核实就报告未通过。修订为空、调用失败或结构退化时保留上一份有效成稿。

直接调用 workflow 的 options 必须类型正确：minWords 为 1–100000 的整数，maxChunks 为正整数（大于 12 仍夹到 12），maxRetries 为 0–3 的整数；非法值和未知键在启动时 FATAL。插件 profile 的 config 则逐项告警并回退默认值，避免阻止宿主启动。

parsers/ 各输入类型的解析器，按类型分发 book.js 书籍：PDF/EPUB/MOBI 文本提取、章节分块 paper.js 论文：arXiv/PDF/HTML 结构识别 video.js 视频：完整逐字稿（字幕优先，无字幕自动转写，走 scripts/transcribe.js） web.js 网页：正文提取 index.js 注册表：解析器发现与回退 schemas/ 输出约束的 JSON Schema（波次1 由 workflow.js 注入脚本，单一真相） scripts/ lint（含换行/空白卫生检查）、安全检查、跨平台转写引导（transcribe.js） lib/ 独立可用的小工具 cache.js 输入指纹与幂等记录（供自己驱动流程的调用方使用；workflow 沙箱没有文件系统，用不到它） workflow-script.txt workflow 脚本正文（普通文本，可直接读改，不需要任何转义） tests/ 测试与验证脚本（不随 npm 包发布，仓库里才有） workflow.js workflow 的 meta 与组装逻辑（解析器内联、schema 注入）

脚本正文单独放 lib/workflow-script.txt：这个文件曾经因为「转义套转义」被改坏过两次，现在它是普通文本，读改都不需要编码步骤。

想换某个输入类型的处理方式，在插件包的 custom-parsers/ 放一个同接口的解析器即可，该目录会随 npm 包分发。也可在插件顶层 config 中指定 customParsersDir，使用自己的解析器目录；它不是 workflow options。相同类型会覆盖内置实现，也可新增 podcast 等类型。程序化注册后重新生成技能会使用最新注册表；各 profile 的专属目录相互隔离。接口为 name、types、buildPrompt(input, opts)。

解析器的 CommonJS 模块会连同字面量相对路径的 .js / .cjs / .json 依赖一起打包，保留模块级常量、helper、方法简写和循环依赖。构建时使用 Acorn 解析 JavaScript；它由 npm 自动安装，不进入 workflow 沙箱。沙箱中的解析器只负责生成提示词，不支持 Node 内置模块、外部包或动态 require / import；这些依赖会在构建时明确报错。程序化注册的函数须自包含，模块闭包请使用文件解析器。

支持平台

Windows / macOS / Linux 同等支持（0.3.9 起）。插件本身只依赖 Node（DSH 自带），各环节需要的额外工具按平台装：

- 书籍 / 论文 PDF → pdftotext（poppler）：macOS brew install poppler、Windows winget install poppler、Debian/Ubuntu apt install poppler-utils
- B站字幕 / 音频 → curl：Windows 10+ 与 macOS / Linux 都自带，零安装
- YouTube 字幕 → yt-dlp：macOS brew install yt-dlp、Windows winget install yt-dlp.yt-dlp、任意平台 pip install -U yt-dlp
- 无字幕转写 → uv（脚本自举：建 Python 3.12 环境 + 装 faster-whisper）：macOS brew install uv、Windows winget install astral-sh.uv，macOS / Linux 也可用官方安装脚本（curl -LsSf https://astral.sh/uv/install.sh 交给 sh）

其余说明：

- 转写是唯一需要额外工具链的环节，三平台共用同一份 Node 脚本、同一条命令：node scripts/transcribe.js --audio <音频> --out <txt>。
- 转写默认走 CPU，Apple Silicon / Intel Mac 与 Linux 都不需要 CUDA；GPU 需自备 CUDA 运行库，options.device: "auto" 会尝试并在失败时自动回退 CPU。
- 缓存目录按平台取：macOS ~/Library/Caches/deep-read-summarize、Linux $XDG_CACHE_HOME/deep-read-summarize、Windows %LOCALAPPDATA%\deep-read-summarize。
- 已在真实 macOS 上跑通一次完整的无字幕转写（0.3.12 起）：uv 自举 Python 3.12 → 装 faster-whisper → 下载模型 → 输出逐字稿，退出码 0；CI 的 macos-latest 作业另外覆盖平台路径解析与整套测试。遇到报错欢迎开 issue 反馈。

安装（DSH 插件）

deep-read-summarize 是 DSH 插件，可通过 npm 或本地安装：

npm 安装（自动安装用于解析器构建的 Acorn）
npm install deep-read-summarize

或本地安装（dsh profile 目录）
pnpm add ./deep-read-summarize-0.3.10.tgz
然后在 dsh 配置的 dsh.profile.bundles 追加:
- deep-read-summarize
重启 dsh web 即可（POST /dsh-market/restart）

安装后自动注册：
- deep_read_summarize 工具（宿主提供 tools / workflowEngine 服务时）；模型只传 input/type/options，插件直接提交已加载的工作流
- deep-read-summarize 工作流定义（meta + script；旧宿主保留通过 workflow 工具调用的方式）
- deep-read-summarize 技能（skills/deep-read-summarize/SKILL.md）
- 四种解析器（parsers/）与 JSON Schema（schemas/）

快速开始（约 5 分钟）

1. 安装

方式 A：npm 直接安装（无需 clone）
npm install deep-read-summarize

方式 B：从源码开发
git clone https://github.com/PensiveFei/deep-read-summarize.git
cd deep-read-summarize
npm ci # 安装锁定依赖

2. 验证安装（离线，不需要任何 API key）

node -e "console.log(require('deep-read-summarize').name)"

看到 deep-read-summarize 即包可正常加载。从源码开发时再运行 npm test 和 npm run test:node；测试不随 npm 包分发。

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）

优先把下面的 JSON 直接传给 deep_read_summarize 工具。旧宿主使用技能提供的 meta + script，通过 workflow 工具执行：

{ "input": "https://arxiv.org/abs/2307.09042", "type": "paper", "options": { "maxChunks": 4, "fastMode": true } }

工作流会返回结构化结果：{ ok, kind, title, filePath, qualityPassed, note }，note 即最终 Markdown 笔记。

⚠️ 笔记由主代理落盘：DSH 的 workflow 契约规定脚本只能协调子代理（沙箱内没有文件系统），所以脚本只返回 note 正文与建议路径 filePath，不会自己写文件。插件自带的 SKILL.md 已明确要求模型在拿到结果后用 write 工具写入 filePath——自己拼 workflow 调用时也要记得这一步，否则笔记只存在于返回值里。

用法

deep_read_summarize 工具只需要以下参数；旧宿主将其作为 workflow 的 args，并使用技能中的 meta + script：

{
"input": "https://arxiv.org/abs/2307.09042", // 链接或文件路径 "type": "auto", // auto | book | paper | video | web
"options": {
"minWords": 2500,
"fastMode": false, // true 时跳过 5-7 节，速度快一些 "maxChunks": 4, // 分块上限，1-12（默认调低，控制子代理数与耗时） "transcribe": true, // 视频：无字幕时自动本地转写（faster-whisper）；false 则跳过转写，见「视频」节 "whisperModel": "small", // 视频转写模型档位：small | base | medium "language": "zh", // 视频转写语言：纯英文视频可设 "en" "device": "cpu", // 转写设备：cpu（默认）| auto | cuda；auto/cuda 需自备 CUDA 运行库，失败自动回退 cpu "maxRetries": 0, // 质量校验重试次数（默认 0 = 不重试，重试会明显变慢） "frontmatter": "obsidian", // frontmatter 键集：obsidian（默认，配 Dataview）| generic（换掉 Hugo 保留键）| minimal "requireCitations": true, // 关键结论是否必须标注出处 "includeTimestamps": false, "outputDir": "./output", // 笔记输出目录（可指向 Obsidian 仓库或静态站点内容目录） "tempDir": "./.tmp" // 临时文件目录 } }
| 类型 | input |
| 论文 | https://arxiv.org/abs/2307.09042 |
| 书籍 | 本地路径，如 ~/books/xxx.pdf |
| 视频 | https://youtube.com/watch?v=xxx |
| 网页 | https://example.com/article |

笔记写到 options.outputDir 指定的目录（默认 ./output，可指向你的 Obsidian 仓库或静态站点内容目录），文件名取自内容标题。

frontmatter 三档（options.frontmatter）

默认 obsidian，键集与历史版本一致，标量和列表值使用安全引号。之所以要分档：type、aliases、url 在 Hugo 里是保留键，语义和 Obsidian 完全不同——直接丢进 Hugo 会改变渲染行为，而不是多几个无害字段。

| 键 | obsidian（默认） | generic | minimal |
| title | ✓ | ✓ | ✓ |
| aliases | ✓ | — | — |
| author / year | ✓ | ✓ | — |
| type | ✓ | — | — |
| docType | — | ✓ | — |
| url | ✓ | — | — |
| sourceUrl | — | ✓ | ✓ |
| tags | ✓ | ✓ | ✓ |
| created | ✓ | — | — |
| date | — | ✓ | ✓ |
| status | ✓ | ✓ | — |

为什么 generic 要换键：

- type 在 Hugo 里决定用哪套 layout（type: video 会让它去找 layouts/video/）
- aliases 在 Hugo 里是一组会重定向到本页的旧 URL
- url 在 Hugo 里会覆盖页面自身的路径——来源链接会变成文章的永久链接
- date 才是 Hugo/Jekyll 都认的时间键；created 只是自定义字段

非法值直接 FATAL 终止（与 type 的失败纪律一致，不静默降级）。

视频：完整逐字稿（字幕优先，无字幕自动转写）

视频取文本是统一流水线（已去掉「三档」）：目标 = 拿到完整逐字稿再精读。

⚠️ 为保证精读质量，处理时间可能略长（刻意取舍，不是卡死）：无字幕视频会先做一次转写（CPU 上约为视频时长的 0.5–2×）再精读，所以这类视频整体会明显比有字幕视频慢；换来的是完整逐字稿 + 真正的精读。有字幕视频仍是秒级。请勿把转写的较慢误判为卡死。

1. 有平台字幕（B站官方 API 的 AI 字幕 / YouTube CC）→ 直接用字幕（=全文，最快、零依赖）。
2. 无公开字幕 → 用插件自带转写 scripts/transcribe.js（faster-whisper small / int8 / VAD / 中文）得到全文。
3. 都不行 → 降级：提示手动提供转写文本，或退回 desc 作背景；绝不阻塞。

options.transcribe：默认 true（无字幕自动转写）；设为 false 则跳过转写（只用字幕/desc 或降级）。

转写工具链：脚本用 uv 创建 Python 3.12 环境，从清华镜像安装 faster-whisper==1.2.1，通过 HF_ENDPOINT=https://hf-mirror.com 下载并缓存模型。健康的缓存环境直接运行，不要求 uv 仍在 PATH，也不再启动单独的 Python 导入探测。实际解释器和依赖版本记录在缓存目录的 runtime.json；Python 补丁版本、uv 和传递依赖未全部锁定，不能据此声称环境逐字一致。PyAV 可直接解码音频，无需单独 ffmpeg。三平台使用同一条命令 node scripts/transcribe.js --audio <音频> --out <txt>，默认 CPU；options.device: "auto" 可尝试自备的 CUDA，失败回退 CPU。缓存目录：Windows %LOCALAPPDATA%\deep-read-summarize、macOS ~/Library/Caches/deep-read-summarize、Linux $XDG_CACHE_HOME/deep-read-summarize（未设置时用 ~/.cache）。创建 Python 环境默认先用镜像，失败再直连 GitHub；DRS_UV_PYTHON_MIRROR 可覆盖镜像，空字符串表示直连。

⚠️ 首次转写会先下载模型（small 约 484MB，走 hf-mirror，非 GitHub），可能需要几分钟，请耐心等待；本机只下这一次，之后所有视频转写用缓存、秒开。只有「无字幕」视频才会触发转写（有字幕的视频直接用字幕，不触发、不下载）。

质量/速度：small + int8 量化 + VAD 静音过滤，中文质量可用且 CPU 友好。有字幕的视频不转写（快）；无字幕视频转写，CPU 上约为视频时长的 0.5–2×。

失败处理：安装/下载失败则明确报错并降级（提示手动提供转写文本），不静默、不长期阻塞。此时可用 options.transcribe: false 跳过转写。

怎么知道本次用了什么来源：来源信息不写进笔记（保证笔记干净），透出在：① 运行日志的 [source] <值> -> <标签> 行；② 返回结果里的 textSource 字段（subtitle / transcription / desc / manual）。

差异与影响因素（时长与内容为何可能不同）

输出时长与内容会因「模型」和「输入」不同而有明显差异，属正常现象，请知悉：

模型

- ASR 模型档位：small（默认，中文可用）→ base（更快、质量略降）→ medium（更好、更慢）。可用 options.whisperModel 调整；下载量与速度随模型变大而增长。
- 语言/口音：中/英/混合语言、方言、口音、重音 → 转写准确度与耗时不同；纯英文视频可设 language: "en"。
- 精读 LLM：用宿主 DSH 的模型，不同上下文/推理模型 → 输出质量、篇幅、速度不同。
- 非确定性：LLM 与 ASR 均带随机性，同一输入重复跑可能得到略有差异的结果（内容/篇幅）。

输入

- 视频：
- 有无公开字幕是最大差异点——有公开字幕 = 秒级；只有登录态 AI 字幕/无字幕 = 触发转写，明显变慢。
- 时长：越长转写越久（CPU 约 0.5–2× 视频时长）。
- 音质/噪杂/低音量/纯 BGM/无人声：转写易错或结果空，此时请手动提供转写文本。
- 论文/书籍/网页：
- 格式：PDF/EPUB/MOBI/HTML/arXiv；扫描版 OCR、坏 PDF、公式/图表密集 → 提取质量与耗时不同。
- 术语密度/篇幅 → 分块数与精读深度不同。
- 分块结构：不同类型分块方式不同（章节/主题/段落），影响输出结构与覆盖。

硬件

- GPU vs CPU：GPU 转写可比 CPU 快一个数量级（device='auto' 自动选）。CPU 上无字幕视频约 0.5–2× 时长。

其他

- 首次 vs 复用：首次要下模型（约 484MB），之后缓存复用。
- Token/成本：分块数/篇幅/引证决定 token 消耗；fastMode/maxChunks 可省。
- 引用/编造：转写或 OCR 的错词可能被当作「原文」引用，关键引用请复核。
- 边界：纯 BGM、失真音频 → 转写空/差；无字幕且转写不可用 → 降级提示人工提供转写文本。

失败怎么处理

分两类：

- 配置错误（缺 input、type 非法、options 格式错）：直接抛异常终止，不产出半成品。
- 内容问题（抓取失败、某块精读失败）：返回 { ok: false, stage, fatal: false }，由调用方决定。某一块失败时跳过它、在成稿里标注缺口，不整体中断。

保持质量的提速

- 支持的新宿主优先使用 deep_read_summarize，模型只提交参数，省去复制整份工作流脚本。旧宿主自动保留原入口。
- 精读仍完整覆盖已知原文，最多三个任务并发；空闲槽位立即领取下一块。按行数均衡工作量，避免一个超大块拖住整批。
- QC 继续独立读取原文；不再在每轮上下文中重复塞入全部 Map 笔记。缺总行数、精读失败或只有视频简介等问题不能靠改写笔记解决，不再浪费全文修订轮次。
- 视频 textSource: "desc" 明确为降级来源，不能取得完整精读的质量通过状态。B站多 P 链接按 p 选择对应 CID、分 P 标题和时长。
- 返回 timings 提供各阶段毫秒耗时，用同一资料、模型、篇幅和质量门槛比较；调度测试不能当成真实 LLM 加速比例。

本次未改小模型档位、减少字数门槛或抽样跳过原文。常驻 ASR 模型、逐字稿缓存和分层 QC 仍需单独做质量与性能基准。

成本

Token 用量取决于原文长度、分块数和成稿篇幅。原文核验会再次读取资料，每轮修订还会增加一次修订和一次核验调用。fastMode 减少输出章节；调低 maxChunks 限制代理数，同时保留全文覆盖。

使用 lib/cache 的程序化调用方请注意：URL 尾斜杠、空 query 与 fragment 可能选择不同资料，现在会保留；新版指纹自动与旧版缓存隔离，升级后可能需要重新处理一次。该工具不负责证明远程内容未更新，复用前仍须由调用方确认来源与配置。

安全与版权

- 抓取视频/网页会发起外部请求，由子代理在 DSH 的沙箱和审批策略下执行；不要让模型无人值守地跑任意脚本。
- 子代理写文件需要相应权限；如果权限不够，workflow 会把内容返回，由主代理负责落盘。
- 本地转写：视频转写（faster-whisper）在本机运行，音频/字幕不出本地；抓取视频元数据/字幕/音频时才会向对应平台发起网络请求。
- 这个仓库只有流程本身：workflow 定义、解析器代码、提示词模板、schema。不含任何受版权保护内容的提取结果。 测试用的 fixture 是自写的公共领域寓言。用本工作流处理有版权的材料时，产出物的使用责任在你。

开发

npm install
npm run lint # node --check 全部 JS
npm test # fixture 测试（35 项，全部离线）
npm run validate # 发布前验证（含安全检查）

npm publish 会自动先跑 prepublishOnly（测试 + lint + 安全检查），任何一项失败都不会发布。

改动说明见 CHANGELOG.md，贡献规范见 CONTRIBUTING.md。

兼容性

已验证的宿主：DSH 0.2.0-rc.2（Node 24）。本仓库的依赖面只有两处：

| 依赖面 | 现行契约 | 本仓库的用法 |
| workflow 脚本钩子 | agent() / pipeline() / parallel() / phase() / log() / args | 只用了 agent/parallel/phase/log/args；agent() 选项只用 label/phase/schema（引擎只接受 label/phase/schema/provider/model，其它选项会被判为 fatal） |
| JSON Schema 子集 | type / properties / required / additionalProperties / items / enum / const / oneOf + 注解键 | 两个 agent() schema 已用宿主真实的 assertObjectJsonSchema 实测通过 |

两点容易踩的契约细节：

- 脚本沙箱没有文件系统/网络/定时器/require——只能协调子代理；笔记落盘由主代理完成（见上文 ⚠️）。
- 违反上述子集不是降级而是终止：引擎抛 UNSUPPORTED_SCHEMA，整条 workflow 直接失败。仓库的 npm test 里有对应回归（含反向断言，确保校验器不是空放行）。

升级 DSH 后先跑 npm test + npm run test:node；坏了对照 CHANGELOG.md 排查。

License

MIT，见 LICENSE。