证据精读 xiehuan123/dsh-deepread

📖 DeepRead — 让 AI 阅读可溯源

官网 · 真实输出 · English ·

把文章、书籍、PDF 和文档集拆成一条条主张，每条都能追溯到证据和原文位置。

Awesome DSH Plugin

DeepRead evidence-first reading workflow

DeepRead 有两种互相兼容的形态：

- 可移植 Agent Skill，适用于 Codex、Claude Code 以及其他兼容 Agent Skills 的工具。零运行时依赖；智能体用自己的文件和网页工具，按证据优先的阅读工作流执行。
- 宿主插件包，适用于 DeepSeek Harness Web/headless 和 dsh-TUI，提供 deepread 工具、PDF 提取、可选的持久化/任务/Web 路由、批量对比、成本预览，以及 HTML/XMind 兼容导出。它的浏览器客户端是可选入口，只在 Web 端使用。

它有什么不同

| 常见的摘要 | DeepRead |
| 压缩主题 | 提取完整主张，以及主张背后的推理 |
| 把原文事实和模型推断混在一起 | 区分作者意图、原文事实、推理推断和未经验证的内容 |
| 结论难以核对 | 重要主张都配上证据和页码/段落位置 |
| 给出答案就结束 | 补充知识地图、冲突、局限和主动回忆问题 |

如果原文不支持某条主张，DeepRead 会直接说 「原文未提供证据」，而不是把空缺补上。

真实的 DeepSeek Harness Web 阅读面板。可移植 Agent Skill 使用同一套证据优先工作流，但没有这套运行时 UI。

快速开始

可移植 Agent Skill

npx skills@latest add xiehuan123/dsh-deepread

然后对你的智能体说：

以知识地图模式精读 docs/architecture.pdf。
每条重要论断都要给出支撑证据和来源位置。

完整版 DeepSeek Harness 插件

dsh plugin --profile web add dsh-deepread

如果 pnpm 报 ERR_PNPM_ADDING_TO_ROOT，把 profile 工作区显式写出来再试一次：

dsh plugin --profile web add -w dsh-deepread

重启 dsh web，然后用 📖 阅读面板，或在聊天里调用 deepread 工具。

看真实输出

下面这些报告都由公开文章生成，不是手写的示例：

| 报告 | DeepRead 让什么变得可见 |
| deep · Claude Code token 优化 | 重建了从可见性到输入、输出、检索路径压缩的工程链路；把建议和项目自带的基准测试分开。 |
| map · 营销话术事实核查 | 发现文章里的「90%」「月薪 128 万」「每天 2000 元」这些说法没有来源、样本或基线；逐条标为未验证。 |
| deep · vivo Tauri 架构 | 把架构选择与文中给出的体积/性能证据连起来，同时保留文章里未经检验的假设和部署限制。 |

浏览全部可复现示例 →

功能

| 能力 | 说明 |
| 🎛️ 五种模式 | quick 要点速览 · deep 深度阅读 · map 知识地图 · feynman 费曼技巧（11 步循环 + 间隔重复） · book 整本书阅读（见下方对比） |
| 🗺️ 知识地图模式 | 核心问题 / 核心结论 / 十类内容（结论、子论断、机制、事实、数据、案例、隐藏前提、反驳、局限、可执行建议） / 每条论断都配上证据（无法验证的论断标注「原文未提供证据」） / 关键数据表（数值与单位、时间范围、样本、基线、来源、位置） / 八种关系标签（支持、反驳、导致、解释、依赖、例证、对比、限制） / 四级置信度（作者意图、原文事实与数据、合理推断、无法验证） / Mermaid 思维导图 / XMind 大纲 / 5 个主动回忆问题 |
| 📥 三种输入 | 微信公众号文章 URL（mp.weixin.qq.com 稳定链接） · 文件（.txt/.md/.html/.pdf，PDF 走内置纯 JS 提取器，支持中文 ToUnicode 映射、页码标记、object-stream/xref-stream） · 粘贴文本 |
| 📤 可选导出 | 默认在会话内展示；export 接受 md / mm（FreeMind，可导入 XMind） / html（编辑器风格的网页报告，带浅色/深色主题） / all，写入工作区里的 deepread-output/ |
| 🎨 浏览器 UI | deepread 工具结果卡片（四色置信度图例、可折叠分区）+ 输入区旁边的 📖 快捷按钮，点开是卡片式阅读面板（链接/路径/文本 + 模式/导出选择 + 阅读焦点 + 一键开始） |
| 🔀 批量对比 | 通过 batch 传入 2-10 篇文档（每篇可为 url/path/text），得到逐篇摘要加一份跨文档报告：对比矩阵、冲突、互补、综合 |
| 📍 引用溯源 | 报告带页码/段落出处：论点、引文，以及一张专门的引用表，把每条主张定位回原文里的 【第N页】 标记 |
| 🧮 成本预览 | estimate: true 预览 token 消耗、模型调用次数、各模式预计耗时，不调用模型（CJK≈0.6 tok/字 的估算规则；速率/延迟默认值按模型系列选取，可显式覆盖） |
| 📚 最近阅读 | Web 面板在本地保留最近阅读记录，一键重读（localStorage，不走服务器往返） |
| ⏳ 进度透明 | 长文阅读 / 大 PDF / 批量任务都变成正式的后台任务：标签写明分段数和预算；进度流逐行推送「精读第 3/20 段…」；job_output 轮询进度和最终报告，job_kill 取消 |
| 🔍 解析进度 | 完整 PDF 提取移入后台任务，并逐页流式推送——「解析 PDF 中… 42%（10/24 页）」——先做一次快速采样预检判断篇幅（不再有后台任务出现前的静默等待）；批量任务逐篇推送——「解析第 2/5 篇… / 精读第 2/5 篇… / 完成第 2/5 篇」，外加「跨篇对比汇总中…」 |
| 🧮 面板预算 | Web 面板在模式选项上方显示各模式的 token + 时间提示（例如 深度精读 (≈38k token · ≈8分钟)），粘贴文本时即时显示；按真实模型速度校准；链接/文件路径由 Host 通过同源 API（POST /api/deepread/budget）抓取并估算，面板的 🔍 预算预检按钮直接在面板内显示一行结果（≈N 字 · ≈X token · ≈Y 分钟）——不走对话往返，不出表格 |
| ⚡ 快速预检 | estimate 模式采样 PDF 前 2 页，再按页数外推，大 PDF 的预算几毫秒就能返回 |
| 🎯 自校准 | 每次模型调用都实测 token/s，汇入滚动平均值并持久化到存储——估算会收敛到你实际服务商的速度；冷启动默认值按模型系列设定（DeepSeek/Kimi/Qwen ≈100-110 tok/s，Claude ≈70，GPT ≈90） |

五种模式对比

| 模式 | 最适合 | 关键输出 | 成本 |
| quick | 「这篇文章讲什么？」一眼看个大概 | 一句话摘要、核心主张、论证结构、引文、关键概念、批判性问题 | 单次调用，最快 |
| deep（默认） | 仔细读一篇文章 | 概览、核心主张、论证结构（主张 + 证据 + 原文引文）、论证脉络、分段亮点、引文、关键概念、批判性思考 | 长文自动拆分，逐段分析 + 汇总 |
| map | 引用前做研究、事实核查 | 核心问题与结论、十类内容、主张与证据配对、关键数据表（五要素）、八种关系、四级置信度、Mermaid 思维导图、XMind 大纲、主动回忆问题 | 结构化流水线，多次调用 |
| feynman | 真正学会并讲给别人听 | 11 步循环：目录 → 提问 → 逐章 → 主张/数据/证据 → 章节思维导图 → 合上书讲解 → 自查漏洞 → 对照原文纠正 → 合并思维导图 → 再讲一遍 → 第 1/3/7/14/30 天间隔复习 | 输出最长，调用最多 |
| book | 整本书 / 超长文本 | 目录、章节脉络、由各部分深读汇总而成的全书摘要 | 逐部分处理 |

一句话选型：赶时间用 quick；想读透一篇文章用 deep；要引用和事实核查用 map；想学会并记住用 feynman；整本书用 book。

安装

DeepRead 1.0.1 要求 Node.js 22.19 或 24 及以上（^22.19 || >=24）。同一个 npm 包在 lib/types/index.js 暴露 TypeScript Host 入口，在 dsh-plugin.json 提供 dsh-TUI Community Consensus v0.15 清单，并在 lib/client.js 提供可选的 DeepSeek Harness Web 客户端。

Host 兼容性

| Host | Node deepread 工具 | Web 客户端 | 打包技能 | 降级行为 |
| DeepSeek Harness Web 0.1.2-rc.1 | 支持 | 加载 Web UI | 可用 | 无 |
| DeepSeek Harness headless 0.1.0-rc.7 | 支持 | 不加载 Web 客户端 | 可用 | 无预算 HTTP 路由 |
| dsh-TUI 0.8.1 最低 / Community Consensus v0.15 | 支持 | 不加载 Web 客户端 | 可用 | 无 Web 路由或浏览器 UI |
| 不带 storageDomain 的自定义组合 | 支持 | 取决于 Web 服务 | 可用 | URL 缓存与 Host 校准使用进程内状态 |

替换 0.5.4 之前，请先读升级与回滚指南，其中包含浏览器来源与 DSH_HOME 保留条件。发布说明介绍了兼容性与入口点的变化。

DeepSeek Harness（工具 + Web UI，全功能）

机器上需要 pnpm（dsh plugin 底层通过 pnpm 安装插件）。

不固定版本的命令跟随 npm latest 标签。若要对齐已验证的 Harness Web 0.1.2-rc.1 基线，请固定 DeepRead 1.0.1；在较旧的 0.1.0-rc.7 Web 运行时上继续用 DeepRead 1.0.0。用 npm view dsh-deepread dist-tags 查看当前标签。

npm latest tag
dsh plugin --profile web add dsh-deepread

Exact npm version
dsh plugin --profile web add dsh-deepread@1.0.1

Exact GitHub tag
dsh plugin --profile web add "github:xiehuan123/dsh-deepread#v1.0.1"

从 Web 配置档移除 DeepRead：

dsh plugin --profile web remove dsh-deepread

pnpm workspace-root 兼容性

有些 DSH 版本会把每个配置档建成 pnpm workspace，但转发 add 和 remove 时没有显式标记 workspace 根目录。碰上受影响的 pnpm 版本，命令还没跑到任何 DeepRead 代码就停了，报 ERR_PNPM_ADDING_TO_ROOT。只重试那一步失败的操作，加上 -w（pnpm 里 --workspace-root 的简写）：

Install after ERR_PNPM_ADDING_TO_ROOT
dsh plugin --profile web add -w dsh-deepread

Remove after the same workspace-root error
dsh plugin --profile web remove -w dsh-deepread

这是配置档包管理器兼容性问题，装进该配置档的任何 DSH 插件都可能中招。别删 pnpm 缓存，也别手动改 node_modules；让 dsh plugin 去更新配置档清单和 bundle 列表。

重启 dsh web 才会生效。输入区旁边会出现 📖 快捷按钮，点它打开卡片式阅读面板。你也可以直接说：「用知识图谱模式读这篇文章：<内容>」。

提示：抓取微信公众号文章 URL 需要 HTTP 服务商。安装后如果看到「web fetch service unavailable」，就在配置档的 cordis.patch.yml 里挂载 @deepseek-ai/dsh-web-fetch-http，并给它一个浏览器 User-Agent（微信会返回反爬验证页）。

dsh-TUI（宿主工具 + 技能）

dsh-TUI 0.8.1 或更新版本可以通过宿主的插件安装器安装 dsh-deepread@1.0.1。安装器读取打包好的 dsh-plugin.json v0.15 清单，加载 lib/types/index.js；它不加载 lib/client.js。

Codex / Claude Code（技能形式，零依赖）

安装（任选一种）：

claude plugin install xiehuan123/dsh-deepread # terminal command (Codex compatible)
/plugin install xiehuan123/dsh-deepread # or the in-session slash command
npx skills@latest add xiehuan123/dsh-deepread # or skills.sh

用法（Codex / Claude Code）：

1. 触发：说一句包含「deep-read / analyze / knowledge map / Feynman」的话，比如
- Deep-read docs/architecture.md
- Analyze this article in knowledge-map mode: <paste text>
- Read this book with the Feynman technique and give me a review plan
- Quickly summarize this WeChat article: https://mp.weixin.qq.com/s/xxxx
2. 模式：智能体自动挑模式（默认 deep）；拿不准时会问你。
3. 输入：文件路径 / 网页链接（微信公众号文章直接抓；知乎、掘金这类反爬站点，把正文粘过来）/ 粘贴的文本。PDF 也行（智能体按 SKILL.md 提取文本；纯扫描版 PDF 先做 OCR）。
4. 输出：默认在对话里给一份 Markdown 报告；说「export html / mindmap / md」，它就写到工作区的 deepread-output/（.md 报告、.mm FreeMind 思维导图 [XMind 可导入]、.html 网页报告）。
5. 知识地图模式：输出带四级置信度（作者意图 / 原文事实与数据 / 合理推断 / 无法验证），每条论断都配上证据 —— 原文没有证据的，明确标注「原文未提供证据」。
6. 费曼模式：完整 11 步（目录 → 提问 → 逐章 → 论断/数据/证据 → 章节思维导图 → 合上书讲解 → 自查漏洞 → 对照原文纠正 → 合并思维导图 → 再讲一遍 → 第 1/3/7/14/30 天间隔复习）。

注意：Codex/Claude 技能是「方法论」形态 —— 智能体用自己的工具做分析；DSH deepread 是「工具」形态 —— 插件直接调用模型跑完整流程。两者输出格式一致，可以互换（导出的 .md/.html 交给任一宿主上的智能体都能继续用）。

示例

Please deep-read this link: https://mp.weixin.qq.com/s/xxxx
Read book.pdf in knowledge-map mode and export html
Quickly summarize this article: <paste text>

参数

| 参数 | 类型 | 说明 |
| url | string | 稳定的微信公众号文章链接（仅限 mp.weixin.qq.com；遇到反爬站点，请粘贴正文） |
| path | string | 工作区文件路径（.txt/.md/.markdown/.html/.pdf） |
| text | string | 粘贴的文本 |
| depth | enum | quick / deep（默认）/ map / feynman / book |
| export | enum | none（默认，仅会话内）/ md / mm / html / all |
| refresh | boolean | true 强制重新抓取并刷新缓存（默认 false：命中缓存的 URL 直接复用已存的全文，不走网络） |
| focus | string | 读者关注的角度，例如「论证逻辑」「研究方法」 |
| language | enum | zh / en / auto（默认） |

仓库结构

├── package.json # dsh.bundle + dsh.client + dsh.skills
├── cordis.patch.yml # inserts itself into the composition
├── dsh-plugin.json # dsh-TUI Community Consensus v0.15 Host-only manifest
├── src/index.ts # TypeScript Cordis Host entry
├── src/host//.ts # Typed Host pipeline, optional services, storage, and exports
├── src/client//.ts # Typed client models, storage, store, views, and slot entry
├── tsdown.config.ts # official lazy-CJS module build semantics for lib/client.js
├── lib/types/index.js # generated Host runtime package entry
├── lib/client.js # Client half (generated): __ModuleLoader__.load({ id, factory })
├── docs/ # integration, upgrade/rollback, and release documentation
├── test/ # Host, browser, compatibility, manifest, and package contracts
├── assets/ # README and showcase visuals
├── skills/dsh-deepread/ # Codex / Claude Code compatible skill (SKILL.md + references + agents/openai.yaml)
├── plugin.json # Agent Plugins-compatible root manifest
├── .claude-plugin/ # Claude Code 插件清单（plugin.json + marketplace.json） └── .codex-plugin/ # Codex 插件清单（plugin.json）

@deepseek-ai/ 系列宿主包（cordis / dsh-tools / schemastery / dsh-storage-domain）以及 zod 和 react，都由宿主配置档提供，并在 peerDependencies 中声明（ 表示「跟随宿主版本」）；dsh.client.inject 声明客户端依赖边（dsh-api-session-controller 提供会话，dsh-client-ui-conversation 提供对话）。

全文缓存

抓取到的文章全文按官方 storageDomain 约定持久化：deepread_url_cache 域（版本 1，经 zod schema 校验，记录保存 url/text/fetchedAt），存放在 $DSH_HOME/storages/ 下，进程重启后依然存在。用不同模式（deep→map/feynman/book）重读同一篇文章时，直接复用缓存，不再访问网络；抓取失败时改用缓存兜底，报告里也会说明。默认 TTL 为 7 天，上限 200 条（过期条目在写入时惰性清理）。组合中省略 storageDomain 时，降级为进程内缓存。webServer 可选：支持 Web 的配置档会注册 budget 路由，而自带的 headless 配置档只激活 Host 工具，不带该路由和浏览器客户端。

插件配置（Config）

timeoutMs（默认 900000）、chunkChars（默认 6000）、maxParts（默认 20）、maxInputChars（默认 400000）、cacheEnabled（默认 true）、cacheTtlHours（默认 168，0 表示禁用缓存），都可以在 cordis 行里覆盖，例如：

- insert:
- id: deepread
name: dsh-deepread
config:
timeoutMs: 600000
cacheTtlHours: 24

开发

维护宿主集成之前，先读 DeepSeek Harness 插件集成参考。里面记录了配置档加载、Node/浏览器入口、插槽生命周期、主题规则和排查顺序。

npm run typecheck:host # strict Host typecheck
npm run typecheck:browser # strict browser typecheck
npm run build # build lib/types and lib/client.js
npm test # full repository contract suite
npm pack --dry-run --json # inspect the publishable file list and public entries

社区

- 在 GitHub Discussions 里提问用法，或分享你的阅读工作流。
- 用 bug 表单 报告可复现的问题。
- 用 feature 表单 提出聚焦的改进建议。
- 提 pull request 之前，先读 CONTRIBUTING.md。
想获取 AI 工具、开源项目与实用工作流的中文笔记，欢迎关注微信公众号 Appoint 实验室：

如果可溯源 AI 阅读对你有用，欢迎 给仓库点个 star，让下一位读者更容易找到它，也方便跟进后续版本。

License

MIT