dsh-mineru

dsh-mineru

Repository: · npm: dsh-mineru · Changelog

English | 简体中文

dsh-mineru is a MinerU-powered multimodal document parsing plugin for DeepSeek Harness (dsh): turn PDF, Word, PPT, Excel, HTML, and images into structured Markdown. Configure a MinerU token to use the 🎯 Precision API, or leave it blank and use the ⚡ Agent API (tokenless, IP rate-limited).

⚠️ Data leaves this machine: every parse uploads your file to MinerU's remote service — there is no fully offline mode. Do not use it for confidential / case material that must stay on-premises. See Security model.

Contents

• Overview · Quick start · Two API modes · Tools · Results & artifacts · Configuration · Usage tips · Web UI · Rate limits & reliability · Error code reference · Security model · FAQ · Development & publishing · Contributing · License

Overview

What is this?

dsh-mineru plugs MinerU (OpenDataLab's high-precision document parsing engine) into the DeepSeek Harness agent ecosystem, letting text-only models "read" documents: the model receives structured Markdown (tables, formulas, and images preserved) instead of binary files it cannot open.

Typical use cases:

• Read papers / contracts / reports: parse a PDF, then ask the agent to summarize or extract data;
• Batch-processing documents: parse dozens of files in one call, each producing Markdown;
• OCR for images / screenshots: scanned pages and web screenshots become searchable text;
• Formulas & tables: math formulas in papers and Excel tables survive with full structure.

Supported file formats

Format · Precision API (token required) · Agent API (tokenless) PDF · ✅ · ✅ Word (.doc / .docx) · ✅ · ✅ (.docx only) PPT (.ppt / .pptx) · ✅ · ✅ (.pptx only) Excel (.xls / .xlsx) · ✅ · ✅ (.xlsx only) HTML (.html / .htm) · ✅ (forces MinerU-HTML model) · ❌ Images (.png .jpg .jpeg .jp2 .webp .gif .bmp) · ✅ · ✅

Note: the Agent API does not support .doc / .ppt / .xls (legacy Office formats) or HTML — use the Precision API (token required) for those.

Highlights

• DSH 0.2.0-rc.2 compatibility — tested with the real Loader, settings service and tool runtime; the 0.1.5-rc.x peer range and legacy settings path are retained;
• Dual API modes, auto-selected — chooses Precision or Agent parsing based on whether a token is configured; can be overridden per call;
• Progressive tool exposure — only the tiny mineru_activate bootstrap is visible until the agent activates the full toolset, saving context;
• Drag-and-drop uploads — drop a file into the chat; its path lands in the composer draft so text-only models can process documents;
• Auto-chunked batch parsing — submit hundreds of files/URLs at once; batching respects official limits automatically;
• Rate-limit aware — built-in token buckets, daily caps, 429 backoff, and actionable messages for every error code;
• Artifact-backed results — parsed output lands in the workspace as files with signed preview links in the Web UI.

Quick start

Step 1: Install

Note: Requires DeepSeek Harness 0.2.0-rc.1 or newer on the 0.2.0 line, or a compatible 0.1.5-rc.x installation, with the dsh CLI available. On the 0.2.0 line, use plugin 0.1.15 or later: 0.1.14 covers only 0.2.0-rc.2+, 0.1.13 only the older host range. If npm still serves 0.1.13, install a source-built tarball below.

From npm (recommended)

dsh plugin --profile web add dsh-mineru        # Web profile
dsh plugin --profile headless add dsh-mineru   # Headless profile

Build from source (development / preview latest changes)

git clone git@github.com:Lee-Hilex/dsh-mineru.git
cd dsh-mineru
npm ci             # development: Node.js 24 recommended; no build step
npm test           # includes real DSH 0.2.0-rc.2 integration tests
npm pack           # produces dsh-mineru-<version>.tgz
dsh plugin --profile web add ./dsh-mineru-<version>.tgz

Run npm pack again and re-install after changing the source. Local installs must use the tarball (pnpm link: installs resolve @deepseek-ai peers outside the profile).

For the desktop profile, use dsh plugin --profile desktop add ./dsh-mineru-0.1.14.tgz. Compatible package metadata passes the runtime gate without an allow-version exemption. npm run test:compat runs only the real-runtime compatibility checks; MinerU responses are simulated, so the tests upload no documents and consume no API quota.

Step 2: Verify the install

dsh --profile web --dump-config | grep -A 2 "id: mineru"

Expected output (a # == comment line plus your plugin row):

# == dsh-mineru
  - id: mineru
    name: dsh-mineru

Then restart a running Web profile (dsh web) and open Settings → Plugins → MinerU 解析.

Step 3: Configure (optional)

No token needed to get started — the plugin automatically falls back to the tokenless Agent API. Add a token to unlock the full feature set (Precision API, batch parsing, HTML, more formats):

• Web UI: Settings → Plugins → MinerU 解析 → paste the token into the write-only field (blank keeps the existing value);
• Headless / CLI: put MINERU_API_TOKEN: in $DSH_HOME/.credentials.yaml, or export the MINERU_API_TOKEN environment variable.

The token is resolved once per operation — rotations take effect on the very next call without a restart. Get a token by registering at (API management page).

Step 4: Use it

Web UI (drag-and-drop friendly):

1. Drag a PDF/Word/image into the chat — the file is saved to the session workspace and its path is filled into the composer draft (never auto-sent);
2. Add your request, e.g. "Parse this PDF to Markdown and summarize the key points";
3. Send. The agent activates the toolset and calls mineru_parse; results come back as files you can preview.

URL parsing: just tell the agent "parse this document: https://example.com/paper.pdf".

Headless smoke test: one-off tasks run on the headless profile:

dsh --profile headless "Parse C:/docs/sample.pdf to Markdown and summarize the first 3 paragraphs"

Headless and Web share the same tool semantics; you can also type /mineru-tools in a conversation to load the usage skill.

Two API modes

· 🎯 Precision API (token required) · ⚡ Agent API (tokenless) Endpoints · /api/v4/extract/task, /api/v4/file-urls/batch, /api/v4/extract/task/batch · /api/v1/agent/parse/url, /api/v1/agent/parse/file Models · pipeline / vlm (default) / MinerU-HTML · fixed lightweight pipeline Size limit · ≤ 200 MB · ≤ 10 MB Page limit · ≤ 200 pages per request (workspace PDFs over it are split automatically) · ≤ 20 pages (never split) Batch parsing · ✅ (URLs ≤ 200/batch, local uploads ≤ 50/batch, auto-batched) · ❌ single file only Output · Zip: full.md + content_list.json + layout.json + images (+ optional docx/html/latex) · Markdown only Best for · Long docs, scans, formulas/tables, batch jobs, HTML · Quick reads, small files, temporary use

Mode selection (mode parameter or config):

• auto (default) — Precision when a token is configured, Agent otherwise;
• precision — force Precision; errors loudly when no token is configured;
• agent — force Agent.

To see which API the current session is actually using: call mineru_activate once — the api field in its result tells you (precision or agent).

Tools

By default the toolset is progressively exposed: only the mineru_activate bootstrap is registered at first. One call unlocks the other three tools, and mineru_activate then hides itself for that session.

mineru_activate — activation bootstrap

Item · Description Purpose · Unlocks mineru_parse / mineru_batch_parse / mineru_task and loads the mineru-tools skill Parameters · none Returns · A status summary: effective API mode, token configured or not, per-API limits

mineru_parse — parse a single document

Parses a workspace file path or http(s) URL into structured Markdown.

Parameter · Required · Description source · ✅ · Workspace file path, or full http(s) URL mode · · auto (default) / precision / agent modelVersion · · Precision model: pipeline / vlm (default, recommended) / MinerU-HTML (forced automatically for HTML sources) language · · Document language pack, default ch — see Configuration enableTable · · Table recognition, default true enableFormula · · Formula recognition, default true isOcr · · Force OCR for scans, default false pageRanges · · Precision page ranges, comma-separated: "2,4-6"; negative pages supported: "2--2" (2nd from last). Omit for the whole document; a workspace PDF over the 200-page cap is split automatically pageRange · · Agent page range, from-to or single page: "1-10" extraFormats · · Extra export formats (Precision only): docx / html / latex dataId · · Business data ID (optional, ≤ 128 chars) timeoutMs · · Whole-operation timeout incl. polling; defaults to plugin config (10 min) output · · Result directory base name; defaults to the source file name anchor · · Also write document.md, a page-anchored copy of the result (one ` per block); default false` — see Page-anchored Markdown

Result highlights: ok, the api/modelVersion used, taskId, duration, runDir, a truncated Markdown preview, the artifact list (with signed preview links on Web), and — with anchor: true — an anchor summary naming the document.md that was written.

Page-anchored Markdown (anchor)

full.md is prose: nothing in it says which page a sentence came from, so a claim drawn from a scan cannot be cited back to a page. anchor: true adds a document.md that carries that information as an HTML comment per block:

君子务本，本立而道生。


![image](images/1efeb151….jpg)


**表一 孔门弟子年表**
<table><tr><td>姓名</td><td>字</td><td>生年</td></tr>…</table>

• pN is the physical page position in this file (1-based, cover and front

matter included) — not the page number printed on the page. The cloud renumbers the pages you asked for, so with pageRanges: "2,4-6" the anchors are p2, p4, p5, p6 — the mapping is requestedPages[page_idx], not a fixed offset;

• bK is the K-th block of that page in content_list.json order. Page

headers, footers and page numbers stay out of the body but still occupy their number, so bK can have gaps (e.g. b1, b2, b4) — that is deliberate: bK always names the same record in content_list.json;

• text blocks render their text, a cloud heading level becomes the matching

Markdown heading, tables render as their caption plus table_body, images as ``;

• a block the cloud marked [Unreadable] keeps its anchor and shows

[Unreadable]; a block with empty text keeps its anchor too;

• the precision API is the only mode that returns content_list.json, so

anchor: true under the Agent API returns a warning and no document.md instead of failing.

The number printed on a page is a *printed* page number, and it need not match the physical order: front matter numbered with Roman numerals, or a document that keeps the page numbers of the journal it came from, shifts every later page. When the result carries readable page_number blocks the renderer compares them with the physical order on a best-effort basis, records each page's printed − physical difference in the pageNumbers field of the anchor summary ({ detected, total, offsets }, offsets sorted and de-duplicated), and reports a single constant non-zero difference as one warning line (messages are Chinese, like the rest of the renderer's warnings):

anchor.pageNumbers = { "detected": 4, "total": 4, "offsets": [3] }
anchor.warnings    = ["印刷页码与物理页序整体相差 +3（前言用罗马数字，或用析出文献保留原刊页码，都会造成整体偏移）；锚点仍用物理页序，可用页码映射声明两者的对应关系"]

Several different differences are reported as such and need checking page by page. Nothing is reported when the two agree (every offset 0) or when no printed number could be read. The check only reads the blocks: the anchors are never changed by it.

Without pageRanges the pages are numbered from 1 in request order. With a negative range ("2--2") the cloud does not tell us the document length, so the anchors fall back to the first page you asked for and the result carries a warning telling you to check them.

Long PDFs — automatic chunking: when one precision request would ask for more than 200 pages (a workspace PDF larger than that, or a pageRanges selection over 200 pages), the plugin splits it into sequential page_ranges chunks itself, submits and polls them one by one, and merges the outcome into the layout a single request produces. No extra parameter, and no local PDF rewrite: the file is uploaded once, only the requested range changes per request.

• full.md — concatenated in page order, with one `` line before each chunk;
• content_list.json — merged, with page_idx mapped back to the original document (the API renumbers it from 0 for every requested subset);
• images/ — the union of all chunks (names are content hashes, so they cannot collide);
• layout.json / _model.json — kept per chunk under chunks/chunk-/, because they are page-indexed arrays that a merge would break;
• run.json — per-chunk page range, batchId, state and duration; the tool result carries the same list as chunkCount / chunks.

Boundaries: splitting needs the page count locally, so it covers workspace PDFs in precision mode only. URL sources, non-PDF formats (the host cannot read docx/pptx page counts) and the tokenless Agent API keep their previous behaviour, and their page-limit error names the reason no split happened. The Agent API is deliberately never split: it is rate-limited per caller IP, so fanning one call out into a dozen requests would exhaust the caller's quota — use Precision, or segment it yourself. timeoutMs applies to each chunk. Only a merged multi-chunk result renumbers pages; a single request (including one with an explicit pageRanges) keeps the cloud's own page_idx, exactly as before.

mineru_batch_parse — batch parsing (Precision only)

Parses many documents in one call; local paths and URLs can be mixed, submissions are auto-chunked within official limits, and per-item success/failure is reported.

Parameter · Required · Description sources · ✅ · Mixed list of file paths / URLs outputPrefix · · Result directory base name, default batch dataIdPrefix · · Business data ID prefix; a sequence number is appended per item (optional) anchor · · Same as mineru_parse: write a document.md per document (default false) others · · Same shared options as mineru_parse (except mode — this tool is Precision-only)

Chunking rules: local files ≤ 50 per batch, URLs ≤ 200 per batch, ≤ 1000 total per call; exceeding these errors with a hint to split the call.

Result highlights: success/failure counts, batchIds, per-item results (each success includes its full.md directory), and error messages for failures.