One-Line Positioning

Package the MinerU document parsing service as a DSH model tool, enabling AI to directly read PDFs, images, Word, PPT, Excel files and convert their content into usable Markdown.

Core Capabilities

• One-click local document parsing: Pass in PDF / image / DOCX / PPTX / XLSX paths, get structured Markdown content from the model
• Async step-by-step interface: For large documents, you can just submit the task and get a task_id, let the model work on other things, then poll for results
• Server health and capacity probe: Returns MinerU version, queue depth, and concurrent limit, convenient for judging server load before batch tasks
• Large output auto-save to disk: When Markdown exceeds the character limit, it's automatically written to the system temp directory; complete structured results (including images, table JSON) are always saved to disk
• Web-side visual configuration: DSH settings page lets you directly edit server address, default backend, polling and timeout parameters, save for hot-reload

Technical Implementation

• Language: TypeScript (NodeNext, ESM-only, relative imports with .js suffix)
• Key Dependencies: cordis (^4.0.0-rc.7, host-injected plugin runtime), @deepseek-ai/dsh-tools (^0.0.1-rc.1, defineTool / ContentBlock types), schemastery (^3.18.0, Config Schema validation), @deepseek-ai/dsh-host-apiproxy (^0.0.1-rc.1, private RPC channel /mineru-api)
• Architecture Pattern: Standard DSH bundle dual-sided plugin — host process (src/index.ts) injects a dsh-mineru line via cordis.patch.yml, injects tools + connection services; registers 5 model tools via ctx.tools.register(defineTool(...)), exposes config read/write + health probing to browser side via ctx.connection.rpc.handle('/mineru-api', ...); client (src/client/index.ts) registers settings.section slot as Cordis client, provides Chinese/English bilingual settings page
• Entry Files: host entry src/index.ts (exports name, inject, Config, apply), browser entry src/client/index.ts (exports apply to register React settings page), build outputs lib/index.js + lib/client.js

Use Cases

Users who want the model to read and understand non-plain-text资料: Convert scanned PDFs, contract photos, Excel reports into Markdown before putting them into the conversation for the model to digest directly; or use mineru_health to check if the MinerU queue can still handle it before batch tasks, then decide whether to wait. Ordinary users can solve 90% of scenarios with just the mineru_parse_document tool; users needing batch or long-running tasks will use the three-step async flow.

Prerequisites & Compatibility

Installation

dsh plugin --profile web add github:HuanLinOTO/dsh-plugin-mineru

Configuration Options

FAQ

Q: Can it parse documents right after installation?

A: No. The plugin only forwards requests to your own MinerU service. You need to deploy a MinerU FastAPI instance first (open source version available from MinerU GitHub repo), then change baseURL to your service address in DSH GUI's MinerU settings page, save and it's effective (README.md:93).

Q: Do I need an API Key?

A: Open source MinerU service has no built-in auth, leave empty to make requests; if you deployed a commercial version with auth, fill in apiKeyEnv in settings page (default reads MINERU_API_KEY env variable), plugin will send it as Bearer token.

Q: What if parsing results get truncated?

A: Markdown over 200000 characters gets truncated and you get prompted that full content was written to mineru-<task_id>.md in system temp; complete structured results (including middle_json, content_list, images, etc.) are always written to mineru-result-<task_id>.json, model can use file read tools to access them.

Q: How to choose parsing backend?

A: Default pipeline, no VLM model needed, runs on CPU, sufficient for most scenarios; to use MinerU's recommended engine you need VLM model installed on server first then switch to hybrid-engine; vlm-* series splits VLM to remote HTTP service, more flexible deployment.

Q: Can I parse multiple documents simultaneously?

A: Yes, but use the async three-step flow: mineru_submit_parse_job gets multiple task_ids at once, poll separately and get results separately, let model work on other things; before batch, use mineru_health to check max_concurrent_requests to see if server can handle it.

Q: Do I need to restart after changing settings?

A: No. After saving in settings page, plugin recreates MinerU client instance, 5 tools read latest config via getter, next call uses new value, process is transparent to model.

Q: How to uninstall?

A: dsh plugin --profile web rm dsh-mineru, then clean up the - insert block this plugin added in ~/.dsh/cordis.patch.yml, temp files won't be actively deleted by plugin.

Getting Started Difficulty

Beginner — After installation, just fill in one MinerU service address in GUI settings page, model can call mineru_parse_document directly; if running local CPU-only MinerU, no API Key needed either.

Known Issues & Limitations

• end_page_id defaults to 99999, not "to PDF end"; MinerU will ignore if exceeding actual page count, but if you need precise slicing pass specific integer (src/tools.ts:79 / AGENTS.md:47)
• lang_list only works with pipeline backend, VLM/hybrid backends silently ignore this parameter (AGENTS.md:44)
• return_images=true makes base64 images in response very large, recommend using response_format_zip=true for image-intensive documents (AGENTS.md:45)
• MinerU server only retains tasks for 24 hours, caching task_id in long sessions may get already-cleaned responses, recommend using and discarding (AGENTS.md:46)
• hybrid-engine / vlm-engine backend requires VLM model loaded on server, will error directly if VLM not loaded (AGENTS.md:43 / README.md:9)
• When apiKeyResolver gets a key, HTTP client sets redirect: 'error', auth requests don't follow 3xx redirects, preventing token leakage to unexpected domains (src/client.ts:233)
• Config file must be saved after modification for hot-reload to take effect, editing without clicking save button won't take effect (src/client/SettingsPage.tsx:116)

📌 本插件已收录于 dshfind 插件超市，点击上方徽章直达主页。

dsh-mineru

DSH 插件：向模型暴露 MinerU 文档解析工具。MinerU 可将 PDF、图片、DOCX、PPTX、XLSX 等文件转换为结构化的 Markdown / JSON。

安装

# 从 npm 安装（推荐）：
dsh plugin --profile web add @huanlin/dsh-plugin-mineru

# 从本地 checkout 开发安装：
dsh plugin --profile web add link:D:\Projects\deepseek-harness\dsh-mineru

若从 git 安装（pnpm ≥10），需在 profile 的 pnpm-workspace.yaml 中允许构建：

allowBuilds:
  '@huanlin/dsh-plugin-mineru': true

配置

在 DSH GUI 设置页或 cordis.patch.yml 中配置：

工具

mineru_parse_document（推荐）

解析本地文档并返回提取出的 markdown。内部自动完成：提交文件 → 轮询至完成 → 返回 markdown。大多数解析任务用这个即可。

mineru_submit_parse_job

异步提交解析任务，立即返回 task_id。适合大文档或并行批量提交。

mineru_get_parse_status

轮询异步任务状态，返回 pending / processing / completed / failed。

mineru_get_parse_result

获取已完成任务的结果。内联返回 markdown（过大则截断），并将完整结构化 JSON 存到 raw_result_path。

mineru_health

检查服务器健康状态、版本、队列深度与并发容量。

开发

pnpm install          # 安装开发依赖（schemastery、typescript、vitest）
pnpm run typecheck    # tsc --noEmit 类型检查
pnpm test             # vitest run 单元测试
pnpm run build        # tsdown 构建 → lib/

目录结构

dsh-mineru/
├── src/
│   ├── index.ts        # 入口：name、inject、Config（Schemastery）、apply
│   ├── client.ts       # MinerUClient（基于 fetch 的 HTTP 客户端 + 类型）
│   ├── tools.ts        # 5 个 defineTool 定义 + 辅助函数 + registerTools
│   └── types.d.ts      # @deepseek-ai/dsh-tools + cordis 的环境类型声明
├── tests/
│   └── tools.spec.ts   # 单元测试（mock fetch，无需真实服务器）
├── cordis.patch.yml    # bundle 层：插入 dsh-mineru 插件行
├── package.json        # dsh.bundle.patch 声明 + peerDeps
└── tsconfig.json       # NodeNext、ES2022、strict

测试 API

请自己部署 MinerU 实例。cordis.patch.yml 默认指向 http://localhost:18000，请在 DSH GUI 中覆盖 baseURL 改为你的 MinerU 服务器地址。