# 📖 DeepRead 证据精读：让 AI 的结论回到原文核对
[中文官网](https://xiehuan123.github.io/dsh-deepread/) · [真实输出](examples/README.md) · [English](README.md) · 中文
> 把公众号文章、PDF、书籍和文档集整理成可追溯的观点、证据、原文位置与置信度，而不只是一段流畅摘要。
[](https://www.npmjs.com/package/dsh-deepread)
[](https://github.com/xiehuan123/dsh-deepread/releases/latest)
[](https://github.com/xiehuan123/dsh-deepread/stargazers)
[](./skills/dsh-deepread/SKILL.md)
[](https://beancookie.github.io/awesome-dsh-plugin)
[](LICENSE)
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 不依赖这套运行时界面，但使用同一套证据优先方法。
## 快速开始
```sh
# 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 后重试：
```sh
dsh plugin --profile web add -w dsh-deepread
```
## 先看真实输出
以下是由公开文章生成的完整报告，不是手写展示稿：
| 报告 | DeepRead 揭示了什么 |
| --- | --- |
| [`deep` · Claude Code Token 优化](examples/claude-code-token-optimization.md) | 还原「可见性→输入压缩→输出压缩→检索路径」工程链路，并区分作者建议与项目方自报 benchmark。 |
| [`map` · 营销文章事实核查](examples/ad-fact-check-knowledge-map.md) | 找出“90% 转型”“128 万年薪”“日薪 2000”等数字均无来源、样本和基准，逐项标记为无法确认。 |
| [`deep` · vivo Tauri 架构实践](examples/vivo-tauri-architecture.md) | 将选型结论连接到体积、性能和实现证据，同时保留未验证假设与部署限制。 |
[查看全部可复现案例 →](examples/README.md)
## 功能
| 能力 | 说明 |
| --- | --- |
| 🎛️ 五种模式 | `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` 前请先阅读[升级与回滚指南](docs/upgrade-and-rollback.md)，其中说明了浏览器 origin 与 `DSH_HOME` 的数据保留条件；[正式版说明](docs/releases/1.0.1.md)记录兼容范围与入口变化。
### DeepSeek Harness（工具 + Web UI，完整功能）
需要本机已安装 **pnpm**（`dsh plugin` 命令底层调用 pnpm 安装插件）。
`1.0.1` 发布后，不指定版本的命令会安装 npm 正式版；需要精确部署版本时固定为 `1.0.1`。
```sh
# npm 正式版（1.0.1 发布后）
dsh plugin --profile web add dsh-deepread
# 固定 npm 版本（1.0.1 发布后）
dsh plugin --profile web add dsh-deepread@1.0.1
# 固定 GitHub tag（v1.0.1 创建后）
dsh plugin --profile web add "github:xiehuan123/dsh-deepread#v1.0.1"
```
从 Web profile 卸载 DeepRead：
```sh
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` 简写）后重试：
```sh
# 安装时报 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 形态，零依赖）
安装（三选一）：
```bash
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 行配置中覆盖，例如：
```yaml
- insert:
- id: deepread
name: dsh-deepread
config:
timeoutMs: 600000
cacheTtlHours: 24
```
## 开发
维护宿主集成前先阅读 [DeepSeek Harness 插件集成参考](docs/deepseek-harness-integration.md)，其中记录了 profile 装载、Node/Browser 双入口、slot 生命周期、主题规则和排障顺序。
```sh
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](https://github.com/xiehuan123/dsh-deepread/discussions)。
- 可复现问题请使用 [Bug 表单](https://github.com/xiehuan123/dsh-deepread/issues/new?template=bug_report.yml)。
- 聚焦的改进建议请使用 [功能建议表单](https://github.com/xiehuan123/dsh-deepread/issues/new?template=feature_request.yml)。
- 提交 Pull Request 前请阅读 [CONTRIBUTING.md](https://github.com/xiehuan123/dsh-deepread/blob/main/CONTRIBUTING.md)。
关注公众号 **Appoint 实验室**，获取 AI 工具、效率软件、开源项目和产品实践：
如果可追溯的 AI 精读对你有帮助，可以 [Star 这个仓库](https://github.com/xiehuan123/dsh-deepread)，让下一位需要核对原文的读者更容易找到它，也方便关注后续版本。
## License
MIT
