{"id":"2df7d894-7bda-4f74-a395-1c6e81fe4560","slug":"dsh-deepread","kind":"skill","name":"dsh-deepread","summary":"Evidence-first reading for AI agents — turn articles, books and PDFs into traceable claims, evidence, source locations and knowledge maps.","owner":"xiehuan123","repoUrl":"https://github.com/xiehuan123/dsh-deepread","license":"MIT","licenseTier":"permissive","trust":"community","stars":59,"match":null,"fewStars":false,"format":"skill","createdAt":"2026-08-15T08:34:51.000Z","addedAt":"2026-10-14T06:05:17.746Z","logoUrl":"https://avatars.githubusercontent.com/u/82025141?u=152e210fc9db0ee09fd4870920abf40821aa07f3&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["files-documents","memory-knowledge","developer-tools"],"tags":["deepseek-harness","dsh-plugin","analysis","deep-read","deep-reading","feynman","knowledge-map","mindmap"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-17T06:43:33.642Z","sample":false,"url":"https://conduits.dev/tools/dsh-deepread","language":"JavaScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# 📖 DeepRead — Make AI reading traceable\n\n[Website](https://xiehuan123.github.io/dsh-deepread/) · [Real outputs](examples/README.md) · English · [中文](README.zh.md)\n\n> Turn articles, books, PDFs, and document sets into claims you can trace back to evidence and source locations.\n\n[![npm version](https://img.shields.io/npm/v/dsh-deepread)](https://www.npmjs.com/package/dsh-deepread)\n[![GitHub release](https://img.shields.io/github/v/release/xiehuan123/dsh-deepread?display_name=tag)](https://github.com/xiehuan123/dsh-deepread/releases/latest)\n[![GitHub stars](https://img.shields.io/github/stars/xiehuan123/dsh-deepread?style=flat&label=stars)](https://github.com/xiehuan123/dsh-deepread/stargazers)\n[![Agent Skill](https://img.shields.io/badge/Agent%20Skill-Codex%20%7C%20Claude%20Code-6366f1)](./skills/dsh-deepread/SKILL.md)\n[![Awesome DSH Plugin](https://beancookie.github.io/awesome-dsh-plugin/badge.svg)](https://beancookie.github.io/awesome-dsh-plugin)\n[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\n![DeepRead evidence-first reading workflow](assets/deepread-demo.svg)\n\nDeepRead is available in two compatible forms:\n\n- **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.\n- **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.\n\n## Why it is different\n\n| A typical summary | DeepRead |\n| --- | --- |\n| Compresses the topic | Extracts complete claims and the reasoning behind them |\n| Blends source facts with model inference | Labels author intent, source facts, reasoned inference, and unverified content |\n| Makes conclusions hard to check | Pairs important claims with evidence and page/paragraph locations |\n| Stops at an answer | Adds knowledge maps, conflicts, limitations, and active-recall questions |\n\nIf the source does not support a claim, DeepRead says **“source does not provide evidence”** instead of filling the gap.\n\n

\n \n \n \"DeepRead\n \n
\n The real DeepSeek Harness Web reading panel. The portable Agent Skill uses the same evidence-first workflow without this runtime UI.\n

\n\n## Quick start\n\n### Portable Agent Skill\n\n```sh\nnpx skills@latest add xiehuan123/dsh-deepread\n```\n\nThen ask your agent:\n\n```text\nDeep-read docs/architecture.pdf in knowledge-map mode.\nFor every important claim, show the supporting evidence and source location.\n```\n\n### Full DeepSeek Harness plugin\n\n```sh\ndsh plugin --profile web add dsh-deepread\n```\n\nIf pnpm reports `ERR_PNPM_ADDING_TO_ROOT`, retry with the profile workspace made explicit:\n\n```sh\ndsh plugin --profile web add -w dsh-deepread\n```\n\nRestart `dsh web`, then use the 📖 reading panel or call the `deepread` tool in chat.\n\n## See real outputs\n\nThese are complete reports generated from public articles, not hand-written mockups:\n\n| Report | What DeepRead made visible |\n| --- | --- |\n| [`deep` · Claude Code token optimization](examples/claude-code-token-optimization.md) | Reconstructed the engineering chain from visibility to input, output, and retrieval-path compression; separated recommendations from project-authored benchmarks. |\n| [`map` · Marketing-claim fact check](examples/ad-fact-check-knowledge-map.md) | Found that the article's “90%”, “¥1.28M salary”, and “¥2,000/day” claims had no source, sample, or baseline; marked each one unverified. |\n| [`deep` · vivo Tauri architecture](examples/vivo-tauri-architecture.md) | Connected architecture choices to reported size/performance evidence while preserving the article's untested assumptions and deployment limits. |\n\n[Browse all reproducible examples →](examples/README.md)\n\n## Features\n\n| Capability | Details |\n| --- | --- |\n| 🎛️ 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) |\n| 🗺️ 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 |\n| 📥 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 |\n| 📤 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 |\n| 🎨 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) |\n| 🔀 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 |\n| 📍 Citations | Reports carry page/paragraph provenance: arguments, quotes, and a dedicated citation table locate claims back to `【第N页】` markers in the source |\n| 🧮 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) |\n| 📚 Recently read | The Web panel keeps a local history of recent reads with one-click re-read (localStorage, no server round-trip) |\n| ⏳ 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 |\n| 🔍 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 「跨篇对比汇总中…」 |\n| 🧮 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 |\n| ⚡ Fast preflight | estimate mode samples the first 2 PDF pages and extrapolates by page count, so big PDF budgets come back in milliseconds |\n| 🎯 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) |\n\n## Five modes compared\n\n| Mode | Best for | Key output | Cost |\n| --- | --- | --- | --- |\n| `quick` | \"What is this article about?\" at a glance | One-line summary, core claim, argument structure, quotes, key concepts, critical questions | Single call, fastest |\n| `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 |\n| `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 |\n| `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 |\n| `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 |\n\nOne-line picker: in a hurry, `quick`; read one article thoroughly, `deep`; cite and fact-check, `map`; learn and remember, `feynman`; a whole book, `book`.\n\n## Installation\n\nDeepRead `1.0.1` 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`.\n\n### Host compatibility\n\n| Host | Node `deepread` tool | Web client | Packaged skill | Degraded behavior |\n| --- | --- | --- | --- | --- |\n| DeepSeek Harness Web `0.1.2-rc.1` | Supported | Web UI loaded | Available | None |\n| DeepSeek Harness headless `0.1.0-rc.7` | Supported | Web client not loaded | Available | No budget HTTP route |\n| dsh-TUI `0.8.1` minimum / Community Consensus `v0.15` | Supported | Web client not loaded | Available | No Web route or browser UI |\n| Custom composition without `storageDomain` | Supported | Depends on Web services | Available | URL cache and Host calibration use in-process state |\n\nBefore replacing `0.5.4`, read the [Upgrade and rollback guide](docs/upgrade-and-rollback.md), including the browser-origin and `DSH_HOME` retention conditions. The [Release notes](docs/releases/1.0.1.md) describe the compatibility and entry-point changes.\n\n### DeepSeek Harness (tool + Web UI, full functionality)\n\nRequires **pnpm** on the machine (`dsh plugin` runs pnpm underneath to install plugins).\n\nThe unpinned command follows the npm `latest` tag. For the validated Harness Web `0.1.2-rc.1` baseline, pin DeepRead `1.0.1`; keep DeepRead `1.0.0` on the older `0.1.0-rc.7` Web runtime. Check the current tags with `npm view dsh-deepread dist-tags`.\n\n```sh\n# npm latest tag\ndsh plugin --profile web add dsh-deepread\n\n# Exact npm version\ndsh plugin --profile web add dsh-deepread@1.0.1\n\n# Exact GitHub tag\ndsh plugin --profile web add \"github:xiehuan123/dsh-deepread#v1.0.1\"\n```\n\nTo remove DeepRead from the Web profile:\n\n```sh\ndsh plugin --profile web remove dsh-deepread\n```\n\n#### pnpm workspace-root compatibility\n\nSome DSH releases create each profile as a pnpm workspace but forward `add` and `remove` without marking the workspace root explicitly. With affected pnpm versions, the command stops before any DeepRead code runs and reports `ERR_PNPM_ADDING_TO_ROOT`. Retry only that failed operation with `-w` (the pnpm shorthand for `--workspace-root`):\n\n```sh\n# Install after ERR_PNPM_ADDING_TO_ROOT\ndsh plugin --profile web add -w dsh-deepread\n\n# Remove after the same workspace-root error\ndsh plugin --profile web remove -w dsh-deepread\n```\n\nThis is a profile package-manager compatibility issue and can affect any DSH plugin installed into that profile. Do not delete pnpm caches or edit `node_modules` by hand; let `dsh plugin` update the profile manifest and bundle list.\n\nRestart `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: \".\n\n> 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).\n\n### dsh-TUI (Host tool + skill)\n\ndsh-TUI `0.8.1` or newer can install `dsh-deepread@1.0.1` 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`.\n\n### Codex / Claude Code (skill form, zero dependencies)\n\nInstall (pick one):\n\n```bash\nclaude plugin install xiehuan123/dsh-deepread # terminal command (Codex compatible)\n/plugin install xiehuan123/dsh-deepread # or the in-session slash command\nnpx skills@latest add xiehuan123/dsh-deepread # or skills.sh\n```\n\n**Usage** (Codex / Claude Code):\n\n1. **Trigger**: say something containing \"deep-read / analyze / knowledge map / Feynman\", e.g.\n - `Deep-read docs/architecture.md`\n - `Analyze this article in knowledge-map mode: `\n - `Read this book with the Feynman technique and give me a review plan`\n - `Quickly summarize this WeChat article: https://mp.weixin.qq.com/s/xxxx`\n2. **Mode**: the agent picks a mode automatically (default `deep`); it asks when unsure.\n3. **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).\n4. **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).\n5. **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\".\n6. **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).\n\n> 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).\n\n## Examples\n\n```\nPlease deep-read this link: https://mp.weixin.qq.com/s/xxxx\nRead book.pdf in knowledge-map mode and export html\nQuickly summarize this article: \n```\n\n## Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `url` | string | Stable WeChat article link (`mp.weixin.qq.com` only; for anti-bot sites, paste the text) |\n| `path` | string | Workspace file path (`.txt/.md/.markdown/.html/.pdf`) |\n| `text` | string | Pasted text |\n| `depth` | enum | `quick` / `deep` (default) / `map` / `feynman` / `book` |\n| `export` | enum | `none` (default, in-session only) / `md` / `mm` / `html` / `all` |\n| `refresh` | boolean | `true` forces a re-fetch and cache refresh (default `false`: a cached URL reuses the stored full text without network access) |\n| `focus` | string | Reader's angle of interest, e.g. \"argumentation logic\", \"research methodology\" |\n| `language` | enum | `zh` / `en` / `auto` (default) |\n\n## Repository layout\n\n```\n├── package.json # dsh.bundle + dsh.client + dsh.skills\n├── cordis.patch.yml # inserts itself into the composition\n├── dsh-plugin.json # dsh-TUI Community Consensus v0.15 Host-only manifest\n├── src/index.ts # TypeScript Cordis Host entry\n├── src/host/**/*.ts # Typed Host pipeline, optional services, storage, and exports\n├── src/client/**/*.ts # Typed client models, storage, store, views, and slot entry\n├── tsdown.config.ts # official lazy-CJS module build semantics for lib/client.js\n├── lib/types/index.js # generated Host runtime package entry\n├── lib/client.js # Client half (generated): __ModuleLoader__.load({ id, factory })\n├── docs/ # integration, upgrade/rollback, and release documentation\n├── test/ # Host, browser, compatibility, manifest, and package contracts\n├── assets/ # README and showcase visuals\n├── skills/dsh-deepread/ # Codex / Claude Code compatible skill (SKILL.md + references + agents/openai.yaml)\n├── plugin.json # Agent Plugins-compatible root manifest\n├── .claude-plugin/ # Claude Code plugin manifests (plugin.json + marketplace.json)\n└── .codex-plugin/ # Codex plugin manifest (plugin.json)\n```\n\nThe `@deepseek-ai/*` host packages (cordis / dsh-tools / schemastery / dsh-storage-domain) plus `zod` and `react`\nare provided by the host profile and declared in `peerDependencies` (`*` means \"follow the host version\");\n`dsh.client.inject` declares the client-side dependency edges (dsh-api-session-controller provides sessions,\ndsh-client-ui-conversation provides conversation).\n\n## Full-text cache\n\nFetched article full texts are persisted following the official storageDomain convention: the\n`deepread_url_cache` domain (version 1, zod-schema validated, records hold `url`/`text`/`fetchedAt`),\nstored under `$DSH_HOME/storages/` and surviving process restarts. Re-reading the same article in a\ndifferent mode (deep→map/feynman/book) reuses the cache without network access; when a fetch fails the\ncache is used as a fallback and the report says so. Default TTL is 7 days with a cap of 200 entries\n(expired entries are lazily removed on write). A composition that omits `storageDomain` degrades to\nan in-process cache. `webServer` is optional: Web-capable profiles register the budget route, while\nthe stock `headless` profile activates the Host tool without that route or the browser client.\n\n## Plugin configuration (Config)\n\n`timeoutMs` (default 900000), `chunkChars` (default 6000), `maxParts` (default 20),\n`maxInputChars` (default 400000), `cacheEnabled` (default true), `cacheTtlHours` (default 168,\n0 disables caching) can all be overridden in the cordis row, for example:\n\n```yaml\n- insert:\n - id: deepread\n name: dsh-deepread\n config:\n timeoutMs: 600000\n cacheTtlHours: 24\n```\n\n## Development\n\nBefore maintaining the host integration, read the [DeepSeek Harness plugin integration reference](docs/deepseek-harness-integration.md). It records profile loading, the Node/browser entry points, slot lifecycle, theme rules, and the diagnostic order.\n\n```sh\nnpm run typecheck:host # strict Host typecheck\nnpm run typecheck:browser # strict browser typecheck\nnpm run build # build lib/types and lib/client.js\nnpm test # full repository contract suite\nnpm pack --dry-run --json # inspect the publishable file list and public entries\n```\n\n## Community\n\n- Ask usage questions or share a reading workflow in [GitHub Discussions](https://github.com/xiehuan123/dsh-deepread/discussions).\n- Report a reproducible problem with the [bug form](https://github.com/xiehuan123/dsh-deepread/issues/new?template=bug_report.yml).\n- Propose a focused improvement with the [feature form](https://github.com/xiehuan123/dsh-deepread/issues/new?template=feature_request.yml).\n- Read [CONTRIBUTING.md](https://github.com/xiehuan123/dsh-deepread/blob/main/CONTRIBUTING.md) before opening a pull request.\n\nFor Chinese-language notes about AI tools, open-source projects, and practical workflows, follow **Appoint 实验室** on WeChat:\n\n\"Appoint\n\nIf traceable AI reading is useful to you, [star the repository](https://github.com/xiehuan123/dsh-deepread) to make it easier for the next reader to find and to follow future releases.\n\n## License\n\nMIT\n"}