📖 DeepRead — Evidence-first reading for AI agents
English | 中文
Turn long articles, books, PDFs, and document sets into traceable claims, evidence, confidence levels, knowledge maps, and review questions.
DeepRead is available in two compatible forms:
- Portable Agent Skill for Codex, Claude Code, and other Agent Skills-compatible tools. Zero runtime dependencies; the agent follows the evidence-first reading workflow with its own file and web tools.
- Full DeepSeek Harness plugin with a
deepreadtool, browser UI, PDF extraction, background jobs, progress updates, batch comparison, cost preview, and HTML/XMind-compatible export.
Quick start
Portable Agent Skill
npx skills@latest add xiehuan123/dsh-deepread
Then ask your agent:
Deep-read docs/architecture.pdf in knowledge-map mode.
For every important claim, show the supporting evidence and source location.
Full DeepSeek Harness plugin
dsh plugin --profile web add dsh-deepread
Restart dsh web, then use the 📖 reading panel or call the deepread tool in chat.
See it in action
The repository includes real, reproducible output rather than placeholder screenshots:
deepmode: Claude Code token optimization — claims, evidence, argument flow, concepts, and critical questions.mapmode: fact-check knowledge map — confidence levels, evidence pairing, data table, relation labels, Mermaid map, and recall questions.deepmode: vivo Tauri architecture — architecture decisions, supporting data, and limitations.
DeepRead never silently upgrades a theme into a claim or fills missing support with invented evidence. If the source does not support a claim, the report says so.
Features
| Capability | Details |
|---|---|
| 🎛️ Five modes | quick key takeaways · deep in-depth reading · map knowledge map · feynman Feynman technique (11-step loop + spaced repetition) · book whole-book reading (see the comparison below) |
| 🗺️ Knowledge-map mode | Core question / core conclusion / ten content categories (conclusion, sub-claim, mechanism, fact, data, case, hidden premise, objection, limitation, actionable advice) / every claim paired with evidence (unverifiable claims marked "no evidence provided in the original text") / key data table (value & unit, time range, sample, baseline, source, location) / eight relation labels (supports, refutes, causes, explains, depends on, exemplifies, contrasts, limits) / four confidence levels (author intent, original facts & data, reasonable inference, unverifiable) / Mermaid mindmap / XMind outline / 5 active-recall questions |
| 📥 Three inputs | WeChat article URLs (mp.weixin.qq.com stable links) · files (.txt/.md/.html/.pdf, PDF via a built-in pure-JS extractor with Chinese ToUnicode mapping, page markers, and object-stream/xref-stream support) · pasted text |
| 📤 Optional export | Displayed in-session by default; export accepts md / mm (FreeMind, importable by XMind) / html (editor-style web report with light/dark theme) / all, written to deepread-output/ in the workspace |
| 🎨 Browser UI | deepread tool result card (four-color confidence legend, collapsible sections) + a 📖 shortcut button next to the input area that opens a card-style reading panel (link/path/text + mode/export selection + reading focus + one-click start) |
| 🔀 Batch compare | Pass 2-10 documents via batch (url/path/text each) to get per-document summaries plus a cross-document report: comparison matrix, conflicts, complementarity, and synthesis |
| 📍 Citations | Reports carry page/paragraph provenance: arguments, quotes, and a dedicated citation table locate claims back to 【第N页】 markers in the source |
| 🧮 Cost preview | estimate: true previews token spend, model-call count, and expected time per mode without calling the model (CJK≈0.6 tok/char heuristic; rate/latency defaults are picked per model family and can be overridden explicitly) |
| 📚 Recently read | The Web panel keeps a local history of recent reads with one-click re-read (localStorage, no server round-trip) |
| ⏳ Progress transparency | Long reads / big PDFs / batches become official background jobs: the label states segment count and budget; the progress stream pushes 「精读第 3/20 段…」 line by line; job_output polls progress and the final report, job_kill cancels |
| 🔍 Parse progress | Full PDF extraction moves inside the background job and streams per page — 「解析 PDF 中… 42%（10/24 页）」 — after a fast sampling preflight decides length (no more silent wait before the background job appears); batches stream per document — 「解析第 2/5 篇… / 精读第 2/5 篇… / 完成第 2/5 篇」 plus 「跨篇对比汇总中…」 |
| 🧮 Panel budget | The Web panel shows per-mode token + time hints above the mode chips (e.g. 深度精读 (≈38k token · ≈8分钟)), instantly for pasted text; calibrated by real model speed; links/file paths are fetched and estimated by the Host through a same-origin API (POST /api/deepread/budget) and the panel's 🔍 budget-preflight button shows a one-line result (≈N chars · ≈X token · ≈Y min) right inside the panel — no chat round-trip, no table |
| ⚡ Fast preflight | estimate mode samples the first 2 PDF pages and extrapolates by page count, so big PDF budgets come back in milliseconds |
| 🎯 Self-calibration | Real token/s measured from every model call feeds a rolling average persisted in storage — estimates converge to your actual provider speed; cold-start defaults are per model family (DeepSeek/Kimi/Qwen ≈100-110 tok/s, Claude ≈70, GPT ≈90) |
Five modes compared
| Mode | Best for | Key output | Cost |
|---|---|---|---|
quick |
"What is this article about?" at a glance | One-line summary, core claim, argument structure, quotes, key concepts, critical questions | Single call, fastest |
deep (default) |
Reading one article carefully | Overview, core claim, argument structure (claim + evidence + verbatim quotes), argument flow, section highlights, quotes, key concepts, critical thinking | Long articles are auto-split, section-by-section + summary |
map |
Research, fact-checking before citing | Core question & conclusion, ten content categories, claim-evidence pairing, key data table (five elements), eight relations, four confidence levels, Mermaid mindmap, XMind outline, active-recall questions | Structured pipeline, multiple calls |
feynman |
Truly learning it and teaching it to others | 11-step loop: TOC → questions → per-chapter → claims/data/evidence → chapter mindmap → explain with the book closed → self-check gaps → correct against the source → merged mindmap → explain again → spaced review on days 1/3/7/14/30 | Longest output, most calls |
book |
Whole books / very long texts | Table of contents, chapter flow, a full-book summary assembled from per-part deep reads | Processed part by part |
One-line picker: in a hurry, quick; read one article thoroughly, deep; cite and fact-check, map; learn and remember, feynman; a whole book, book.
Installation
DeepSeek Harness (tool + Web UI, full functionality)
Requires pnpm on the machine (dsh plugin runs pnpm underneath to install plugins) and Node.js ≥ 22.
# From npm (prebuilt, no build authorization needed)
dsh plugin --profile web add dsh-deepread
# Pin a version
dsh plugin --profile web add dsh-deepread@^0.5.4
# From GitHub (source; build artifacts are committed)
dsh plugin --profile web add "github:xiehuan123/dsh-deepread#v0.5.4"
Restart dsh web for it to take effect. A 📖 shortcut button appears next to the input area; click it to open the card-style reading panel. You can also just say: "Read this article in knowledge-map mode: ".
Tip: fetching WeChat article URLs needs an HTTP provider. If you see "web fetch service unavailable" after install, mount
@deepseek-ai/dsh-web-fetch-httpin the profile'scordis.patch.ymland give it a browser User-Agent (WeChat serves an anti-bot verification page).
Codex / Claude Code (skill form, zero dependencies)
Install (pick one):
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
Usage (Codex / Claude Code):
- Trigger: say something containing "deep-read / analyze / knowledge map / Feynman", e.g.
Deep-read docs/architecture.mdAnalyze this article in knowledge-map mode: <paste text>Read this book with the Feynman technique and give me a review planQuickly summarize this WeChat article: https://mp.weixin.qq.com/s/xxxx
- Mode: the agent picks a mode automatically (default
deep); it asks when unsure. - Input: file path / web link (WeChat articles are fetched directly; for anti-bot sites like Zhihu/Juejin, paste the text) / pasted text. PDFs work too (the agent extracts text per
SKILL.md; scan-only PDFs should be OCR'd first). - Output: a Markdown report in the conversation by default; say "export html / mindmap / md" and it writes to
deepread-output/in the workspace (.mdreport,.mmFreeMind mindmap [importable by XMind],.htmlweb report). - Knowledge-map mode: output carries four confidence levels (author intent / original facts & data / reasonable inference / unverifiable), and every claim is paired with evidence — the original text lacking evidence is explicitly marked "no evidence provided in the original text".
- Feynman mode: the full 11 steps (TOC → questions → per-chapter → claims/data/evidence → chapter mindmap → explain with the book closed → self-check gaps → correct against the source → merged mindmap → explain again → spaced review on days 1/3/7/14/30).
Note: the Codex/Claude skill is the "methodology" form — the agent performs the analysis with its own tools; the DSH
deepreadis the "tool" form — the plugin runs the pipeline by calling the model directly. Output formats are identical and interchangeable (an exported.md/.htmlkeeps working when handed to an agent on either host).
Examples
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>
Parameters
| Parameter | Type | Description |
|---|---|---|
url |
string | Stable WeChat article link (mp.weixin.qq.com only; for anti-bot sites, paste the text) |
path |
string | Workspace file path (.txt/.md/.markdown/.html/.pdf) |
text |
string | Pasted text |
depth |
enum | quick / deep (default) / map / feynman / book |
export |
enum | none (default, in-session only) / md / mm / html / all |
refresh |
boolean | true forces a re-fetch and cache refresh (default false: a cached URL reuses the stored full text without network access) |
focus |
string | Reader's angle of interest, e.g. "argumentation logic", "research methodology" |
language |
enum | zh / en / auto (default) |
Repository layout
├── package.json # dsh.bundle + dsh.client + dsh.skills
├── cordis.patch.yml # inserts itself into the composition
├── index.mjs # Node half: Cordis entry (deepread tool + PDF/HTML parsing + three export formats)
├── src/client/index.js # Client source: result card + reading bar + reading panel (factory bundle)
├── scripts/build-client.mjs# bundles client source into the C6 factory artifact lib/client.js (do not edit by hand)
├── lib/client.js # Client half (generated): __ModuleLoader__.load({ id, factory })
├── test/ # smoke tests: Node tool pipeline + client factory-bundle contract
├── 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 manifests (plugin.json + marketplace.json)
└── .codex-plugin/ # Codex plugin manifest (plugin.json)
The @deepseek-ai/* host packages (cordis / dsh-tools / schemastery / dsh-storage-domain) plus zod and react
are provided by the host profile and declared in peerDependencies (* means "follow the host version");
dsh.client.inject declares the client-side dependency edges (dsh-client-runtime provides slots/sessions,
dsh-client-ui-conversation provides conversation).
Full-text cache
Fetched article full texts are persisted following the official storageDomain convention: the
deepread_url_cache domain (version 1, zod-schema validated, records hold url/text/fetchedAt),
stored under $DSH_HOME/storages/ and surviving process restarts. Re-reading the same article in a
different mode (deep→map/feynman/book) reuses the cache without network access; when a fetch fails the
cache is used as a fallback and the report says so. Default TTL is 7 days with a cap of 200 entries
(expired entries are lazily removed on write). Profiles without storage mounted (e.g. a headless
composition without the web bundle) automatically degrade to an in-process cache.
Plugin configuration (Config)
timeoutMs (default 900000), chunkChars (default 6000), maxParts (default 20),
maxInputChars (default 400000), cacheEnabled (default true), cacheTtlHours (default 168,
0 disables caching) can all be overridden in the cordis row, for example:
- insert:
- id: deepread
name: dsh-deepread
config:
timeoutMs: 600000
cacheTtlHours: 24
Development
npm run build:client # regenerate lib/client.js from src/client/index.js
npm test # Node tool pipeline smoke + client factory-bundle contract tests
License
MIT
No comments yet. Be the first to write one.