dsh-deepread

📖 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.
• Host plugin package for DeepSeek Harness Web/headless and dsh-TUI, with a deepread tool, PDF extraction, optional persistence/jobs/Web route, batch comparison, cost preview, and HTML/XMind-compatible export. Its browser client is an optional Web-only entry.

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:

• deep mode: Claude Code token optimization — claims, evidence, argument flow, concepts, and critical questions.
• map mode: fact-check knowledge map — confidence levels, evidence pairing, data table, relation labels, Mermaid map, and recall questions.
• deep mode: 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

Five modes compared

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

DeepRead 1.0.0 requires Node.js 22.19 or 24 and higher (^22.19 || >=24). The same npm package exposes the TypeScript Host entry at lib/types/index.js, the dsh-TUI Community Consensus v0.15 manifest at dsh-plugin.json, and an optional DeepSeek Harness Web client at lib/client.js.

Host compatibility

Before replacing 0.5.4, read the Upgrade and rollback guide, including the browser-origin and DSH_HOME retention conditions. The Release notes describe the compatibility and entry-point changes.

DeepSeek Harness (tool + Web UI, full functionality)

Requires pnpm on the machine (dsh plugin runs pnpm underneath to install plugins).

After 1.0.0 is published, the unpinned command installs the stable npm release. Pin 1.0.0 when an exact deployment version is required.

# Stable npm release (after 1.0.0 is published)
dsh plugin --profile web add dsh-deepread

# Exact npm version (after 1.0.0 is published)
dsh plugin --profile web add dsh-deepread@1.0.0

# Exact GitHub tag (after v1.0.0 is created)
dsh plugin --profile web add "github:xiehuan123/dsh-deepread#v1.0.0"

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-http in the profile's cordis.patch.yml and give it a browser User-Agent (WeChat serves an anti-bot verification page).

dsh-TUI (Host tool + skill)

dsh-TUI 0.8.1 or newer can install dsh-deepread@1.0.0 through the host's plugin installer. The installer reads the packaged dsh-plugin.json v0.15 manifest and loads lib/types/index.js; it does not load lib/client.js.

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):

1. Trigger: say something containing "deep-read / analyze / knowledge map / Feynman", e.g.
   • 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. Mode: the agent picks a mode automatically (default deep); it asks when unsure.
3. 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).
4. Output: a Markdown report in the conversation by default; say "export html / mindmap / md" and it writes to deepread-output/ in the workspace (.md report, .mm FreeMind mindmap [importable by XMind], .html web report).
5. 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".
6. 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 deepread is the "tool" form — the plugin runs the pipeline by calling the model directly. Output formats are identical and interchangeable (an exported .md/.html keeps 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

Repository layout

├── 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 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). A composition that omits storageDomain degrades to an in-process cache. webServer is optional: Web-capable profiles register the budget route, while the stock headless profile activates the Host tool without that route or the browser client.

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

Before maintaining the host integration, read the DeepSeek Harness plugin integration reference. It records profile loading, the Node/browser entry points, slot lifecycle, theme rules, and the diagnostic order.

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

License

MIT