xiehuan123/dsh-deepread

📖 DeepRead 证据精读：让 AI 的结论回到原文核对

中文官网 · 真实输出 · English · 中文

把公众号文章、PDF、书籍和文档集整理成可追溯的观点、证据、原文位置与置信度，而不只是一段流畅摘要。

npm version
GitHub release
GitHub stars
Agent Skill
Awesome DSH Plugin
MIT License

DeepRead 证据优先精读流程

DeepRead 同时提供两种兼容形态：

- 便携 Agent Skill：适用于 Codex、Claude Code 及其他兼容 Agent Skills 的工具，零运行时依赖。
- Host 插件包：适用于 DeepSeek Harness Web/headless 与 dsh-TUI，包含 deepread 工具、PDF 抽取、可选持久化/jobs/Web route、批量对比、成本预估和 HTML/XMind 导出；浏览器 client 仅供 Web 宿主按需加载。

它和普通摘要有什么不同

| 普通 AI 摘要 | DeepRead |
| --- | --- |
| 压缩文章主题 | 提取完整观点与论证链 |
| 容易混合原文事实和模型推断 | 区分作者原意、原文事实、合理推断和无法确认 |
| 结论很难回查 | 重要观点配证据，并定位到页码或原文段落 |
| 给完答案就结束 | 继续生成关系图、限制条件和主动回忆问题 |

原文没有支撑某个观点时，DeepRead 会明确写出 「原文未提供证据」，不会替作者补答案。

DeepSeek Harness Web 中的真实精读面板；便携 Agent Skill 不依赖这套运行时界面，但使用同一套证据优先方法。

快速开始

Codex / Claude Code / Agent Skills
npx skills@latest add xiehuan123/dsh-deepread

完整 DSH 插件
dsh plugin --profile web add dsh-deepread

如果 pnpm 报错 ERR_PNPM_ADDING_TO_ROOT，请显式指定 profile workspace 后重试：

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

先看真实输出

以下是由公开文章生成的完整报告，不是手写展示稿：

| 报告 | DeepRead 揭示了什么 |
| --- | --- |
| deep · Claude Code Token 优化 | 还原「可见性→输入压缩→输出压缩→检索路径」工程链路，并区分作者建议与项目方自报 benchmark。 |
| map · 营销文章事实核查 | 找出“90% 转型”“128 万年薪”“日薪 2000”等数字均无来源、样本和基准，逐项标记为无法确认。 |
| deep · vivo Tauri 架构实践 | 将选型结论连接到体积、性能和实现证据，同时保留未验证假设与部署限制。 |

查看全部可复现案例 →

功能

| 能力 | 说明 |
| --- | --- |
| 🎛️ 五种模式 | quick 快速抓要点 · deep 深度精读 · map 知识地图 · feynman 费曼读书法（11 步闭环 + 间隔复习）· book 整本书分部分精读（对比见下方「五种模式对比」） |
| 🗺️ 知识地图模式 | 核心问题 / 核心结论 / 十类内容分类（核心结论、分论点、原因或作用机制、事实、数据、案例、隐含前提、反对意见、限制条件、可执行建议）/ 观点必配证据（无证据标注「原文未提供证据」）/ 关键数据表（数值与单位、时间范围、样本、比较基准、来源、位置）/ 八种关系标注（支持、反驳、导致、解释、取决于、举例、对比、限制）/ 四档置信度（作者原意、原文事实与数据、合理推断、无法确认）/ Mermaid 思维导图 / XMind 大纲 / 5 个主动回忆问题 |
| 📥 三种输入 | 微信公众号链接（mp.weixin.qq.com 稳定链接）· 文件（.txt/.md/.html/.pdf，PDF 内置纯 JS 提取器，含中文 ToUnicode 映射、页码标记与对象流/交叉引用流支持）· 粘贴文本 |
| 📤 可选导出 | 默认只在会话中展示；export 参数可选 md / mm（FreeMind，XMind 可导入）/ html（编辑风网页报告，深浅色自适应）/ all，写入工作区 deepread-output/ |
| 🎨 浏览器 UI | deepread 工具结果卡片（置信度四色图例、折叠分区）+ 输入区左侧 📖 快捷按钮，点击弹出卡片式精读面板（链接/路径/正文 + 模式/导出选择 + 关注重点 + 一键开始） |
| 🔀 批量对比 | batch 一次给 2-10 篇（各带 url/path/text），逐篇速览 + 跨篇对比报告：对比矩阵、冲突点、互补关系与综合结论 |
| 📍 引用溯源 | 报告带页码/段落定位：分论点、金句与专门的引用溯源表把论断定位回原文【第N页】标记 |
| 🧮 预算预检 | estimate: true 不调用模型，先给出各模式的预计 token、调用次数与耗时（中文≈0.6 token/字；速率与延迟默认按当前模型族自动取值，也可显式配置覆盖） |
| 📚 最近读过 | 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分钟)），粘贴文本即时计算，并随真实模型速度自校准；链接/文件路径点面板「🔍 预算预检」按钮，经同源 API（POST /api/deepread/budget）由 Host 直接抓取/读取并估算，面板内即时显示一行结论（约 N 字 · ≈X token · ≈Y 分钟），不跳对话、不渲染表格 |
| ⚡ 采样预检 | estimate 模式对 PDF 只采前 2 页并按页数外推，大 PDF 预算毫秒级返回 |
| 🎯 自校准 | 每次模型调用实测 token/秒，滚动平均持久化——估算随你的真实模型速度收敛；冷启动默认值按模型族给出（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 包暴露 TypeScript Host 入口 lib/types/index.js、dsh-TUI Community Consensus v0.15 清单 dsh-plugin.json，以及可选的 DeepSeek Harness Web client lib/client.js。

宿主兼容矩阵

| 宿主 | Node deepread 工具 | Web client | 打包 skill | 降级行为 |
| --- | --- | --- | --- | --- |
| DeepSeek Harness Web 0.1.2-rc.1 | 支持 | 加载浏览器 Web UI | 可用 | 无 |
| DeepSeek Harness headless 0.1.0-rc.7 | 支持 | 不加载 Web client | 可用 | 不注册预算 HTTP route |
| dsh-TUI 0.8.1 最低版本 / Community Consensus v0.15 | 支持 | 不加载 Web client | 可用 | 无 Web route、无浏览器 UI |
| 缺少 storageDomain 的自定义组合 | 支持 | 取决于 Web 服务 | 可用 | URL 缓存和 Host 校准退化为进程内状态 |

替换 0.5.4 前请先阅读升级与回滚指南，其中说明了浏览器 origin 与 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 runtime 应保留 DeepRead 1.0.0。可用 npm view dsh-deepread dist-tags 查询当前标签。

npm latest 标签
dsh plugin --profile web add dsh-deepread

固定 npm 版本
dsh plugin --profile web add dsh-deepread@1.0.1

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

从 Web profile 卸载 DeepRead：

dsh plugin --profile web remove dsh-deepread

pnpm workspace 根目录兼容

部分 DSH 版本会把每个 profile 创建为 pnpm workspace，却在转发 add 和 remove 时没有显式声明 workspace 根目录。受影响的 pnpm 版本会在任何 DeepRead 代码运行前停止，并报错 ERR_PNPM_ADDING_TO_ROOT。只需为这次失败的操作添加 -w（pnpm 的 --workspace-root 简写）后重试：

安装时报 ERR_PNPM_ADDING_TO_ROOT
dsh plugin --profile web add -w dsh-deepread

卸载时遇到同类 workspace-root 错误
dsh plugin --profile web remove -w dsh-deepread

这是 profile 包管理器兼容问题，可能影响安装到该 profile 的任何 DSH 插件。请勿通过删除 pnpm 缓存或手工修改 node_modules 处理；应继续使用 dsh plugin，让它同步更新 profile 清单和 bundle 列表。

重启 dsh web 后生效。输入区左侧出现 📖 快捷按钮，点击弹出卡片式精读面板。对话中也可直接说「用知识地图模式精读这篇文章：」。

提示：抓取微信公众号链接需要 HTTP provider。安装后若报「网页抓取服务不可用」，请在 profile 的 cordis.patch.yml 中挂载 @deepseek-ai/dsh-web-fetch-http 并为它配置浏览器 User-Agent（微信有反爬验证页）。

dsh-TUI（Host 工具 + skill）

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（skill 形态，零依赖）

安装（三选一）：

claude plugin install xiehuan123/dsh-deepread      # 终端命令（Codex 兼容）
/plugin install xiehuan123/dsh-deepread            # 或会话内斜杠命令
npx skills@latest add xiehuan123/dsh-deepread      # 或 skills.sh

使用说明（Codex / Claude Code 通用）：

1. 触发：直接说一句包含「精读 / 分析 / 知识地图 / 费曼」的话，例如
- 精读一下 docs/architecture.md
- 用知识地图模式分析这篇文章：
- 用费曼读书法读这本书，给我复习计划
- 快速抓一下这篇公众号文章的要点：https://mp.weixin.qq.com/s/xxxx
2. 模式：agent 会按诉求自动选择（默认 deep），五种模式见上表；不确定时它会问你要哪种。
3. 输入：文件路径 / 网页链接（微信公众号可直接抓；知乎/掘金等反爬站点请粘贴正文）/ 直接粘贴文本，PDF 也能处理（agent 会按 SKILL.md 的指引抽取文本，扫描版建议先 OCR）。
4. 输出：默认只在对话里给 Markdown 报告；你说「导出 html / 导图 / md」时，它会把报告写入工作区 deepread-output/（.md 报告、.mm FreeMind 思维导图【XMind 可导入】、.html 网页报告）。
5. 知识地图模式：输出含四档置信度（作者原意/原文事实与数据/合理推断/无法确认），每条观点配证据——原文没有证据会明确标「原文未提供证据」。
6. 费曼模式：完整 11 步（目录→提问→分章→观点数据证据→章节导图→合上书讲解→自检缺口→回原文修正→合并导图→再讲一次→第 1/3/7/14/30 天间隔复习计划）。

提示：Codex 版的 skill 是「方法论」形态——由 agent 用自己的工具执行分析；DSH 版的 deepread 是「工具」形态——由插件直接调用模型跑流水线。两者输出格式一致，可互相迁移（把导出的 .md/.html 交给任一端的 agent 都能继续工作）。

使用示例

请用 deepread 精读这个链接：https://mp.weixin.qq.com/s/xxxx
用知识地图模式精读 book.pdf，导出 html
快速抓一下这篇文章的要点：

参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| 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：同一链接命中缓存直接复用全文，不联网） |
| focus | string | 读者关注角度，如「论证逻辑」「研究方法」 |
| language | enum | zh / en / auto（默认） |

仓库结构

├── package.json            # dsh.bundle + dsh.client + dsh.skills
├── cordis.patch.yml        # insert 挂载自身
├── dsh-plugin.json         # dsh-TUI Community Consensus v0.15 Host-only 清单
├── src/index.ts            # TypeScript Cordis Host 入口
├── src/host//.ts        # Host 管线、可选服务、存储与导出
├── src/client//.ts      # Client 类型模型、存储、store、视图与 slot 入口
├── tsdown.config.ts        # 按官方 lazy-CJS 模块语义生成 lib/client.js
├── lib/types/index.js      # 生成的 Host 运行时包入口
├── lib/client.js           # Client half（生成产物）：__ModuleLoader__.load({ id, factory })
├── docs/                   # 集成、升级/回滚与发布文档
├── test/                   # Host、浏览器、兼容、manifest 与打包契约
├── skills/dsh-deepread/    # Codex / Claude Code 兼容 skill（SKILL.md + references + agents/openai.yaml）
├── .claude-plugin/         # Claude Code 插件清单（plugin.json + marketplace.json）
└── .codex-plugin/          # Codex 插件清单（plugin.json）

@deepseek-ai/ 官方包（cordis / dsh-tools / schemastery / dsh-storage-domain）与 zod、react
由宿主 profile 提供，在 peerDependencies 中声明（ 表示跟随宿主版本）；dsh.client.inject
声明客户端依赖边（dsh-api-session-controller 提供 sessions，dsh-client-ui-conversation 提供 conversation）。

全文缓存

URL 抓取的全文按官方 storageDomain 约定落盘：deepread_url_cache 领域（版本 1，zod schema
校验，记录含 url/text/fetchedAt），存于 $DSH_HOME/storages/，跨进程重启仍然有效。
同一篇文章换模式（deep→map/feynman/book）直接复用缓存、不再联网；抓取失败时自动回退缓存并
在报告中注明。TTL 默认 7 天，条目上限 200（写入时惰性清理过期项）。未挂载
storageDomain 的组合会降级为进程内缓存。webServer 是可选能力：Web-capable profile
会注册预算 route；stock headless profile 仍会激活 Host 工具，但没有该 route 和浏览器 client。

插件配置（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 插件集成参考，其中记录了 profile 装载、Node/Browser 双入口、slot 生命周期、主题规则和排障顺序。

npm run typecheck:host      # Host 严格类型检查
npm run typecheck:browser   # 浏览器严格类型检查
npm run build               # 构建 lib/types 与 lib/client.js
npm test                    # 完整仓库契约测试
npm pack --dry-run --json   # 核对发布文件清单与公共入口

社区与贡献

- 使用问题、阅读工作流和案例分享请到 GitHub Discussions。
- 可复现问题请使用 Bug 表单。
- 聚焦的改进建议请使用 功能建议表单。
- 提交 Pull Request 前请阅读 CONTRIBUTING.md。

关注公众号 Appoint 实验室，获取 AI 工具、效率软件、开源项目和产品实践：

如果可追溯的 AI 精读对你有帮助，可以 Star 这个仓库，让下一位需要核对原文的读者更容易找到它，也方便关注后续版本。

License

MIT