一句话定位

把 MinerU 文档解析服务包成 DSH 模型工具，让 AI 直接读取 PDF、图片、Word、PPT、Excel 等文件，把里面内容转成可用的 Markdown。

核心能力

• 一键解析本地文档：传入 PDF / 图片 / DOCX / PPTX / XLSX 路径，模型拿到结构化的 Markdown 内容
• 异步分步接口：大文档可只提交任务拿到 task_id，模型穿插别的工作后再轮询、取结果
• 服务端健康与容量探针：返回 MinerU 版本、队列深度、并发上限，方便批量任务前判断忙闲
• 大输出自动落盘：Markdown 超过字符上限自动写入系统临时目录；完整结构化结果（含图片、表格 JSON）始终落盘
• Web 端可视化配置：DSH 设置页直接编辑服务器地址、默认后端、轮询与超时参数，保存即热生效

技术实现

• 语言: TypeScript（NodeNext、ESM-only、相对导入带 .js 后缀）
• 关键依赖: cordis（^4.0.0-rc.7，宿主注入插件运行时）、@deepseek-ai/dsh-tools（^0.0.1-rc.1，defineTool / ContentBlock 类型）、schemastery（^3.18.0，Config Schema 校验）、@deepseek-ai/dsh-host-apiproxy（^0.0.1-rc.1，私有 RPC 通道 /mineru-api）
• 架构模式: 标准 DSH bundle 双面插件 — host 进程（src/index.ts）通过 cordis.patch.yml 注入一条 dsh-mineru 行，注入 tools + connection 服务；通过 ctx.tools.register(defineTool(...)) 注册 5 个模型工具，通过 ctx.connection.rpc.handle('/mineru-api', ...) 给浏览器侧暴露配置读写 + 健康探测；客户端（src/client/index.ts）以 Cordis client 形式注册 settings.section 槽位，提供中文/英文双语设置页
• 入口文件: host 入口 src/index.ts（导出 name、inject、Config、apply），browser 入口 src/client/index.ts（导出 apply 注册 React 设置页），构建产物 lib/index.js + lib/client.js

适用场景

想让模型读取并理解非纯文本资料的用户：把扫描版 PDF、合同照片、Excel 报表塞进对话前先转成 Markdown 让模型直接消化；或者用 mineru_health 在批量任务前看一眼 MinerU 队列还扛不扛得住，再决定要不要等。普通用户只用 mineru_parse_document 一个工具就能解决 90% 的场景；需要批量或长任务的用户才需要用到三步异步流程。

前置依赖与兼容性

安装方式

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

配置项

常见问题

Q：装上就能解析文档吗？

A：不能。插件只负责把请求转发给你自己的 MinerU 服务，需要先部署一个 MinerU FastAPI 实例（开源版可从 MinerU GitHub 仓库获取），然后在 DSH GUI 的 MinerU 设置页把 baseURL 改成你的服务地址，保存即生效（README.md:93）。

Q：需要 API Key 吗？

A：开源 MinerU 服务本身没有内建鉴权，留空即可发起请求；如果部署的是带鉴权的商业版，在设置页填好 apiKeyEnv（默认读 MINERU_API_KEY 环境变量），插件会作为 Bearer token 发出去。

Q：解析结果被截断了怎么办？

A：Markdown 超过 200000 字符会被截断并提示完整内容写到了系统临时目录下的 mineru-<task_id>.md；完整结构化结果（含 middle_json、content_list、图片等）始终写到 mineru-result-<task_id>.json，模型可以再用文件读取工具去访问。

Q：怎么选解析后端？

A：默认 pipeline，无需 VLM 模型、CPU 也能跑，绝大多数场景够用；想用 MinerU 官方推荐的引擎得服务端先装好 VLM 模型再切到 hybrid-engine；vlm-* 系列是把 VLM 拆到远端 HTTP 服务，部署更灵活。

Q：能同时解析多个文档吗？

A：可以，但用异步三步流程：mineru_submit_parse_job 一次性拿多个 task_id，分别轮询再分别取结果，让模型穿插别的工作；想批量前先 mineru_health 看 max_concurrent_requests 判断服务端能不能扛住。

Q：改了设置要重启吗？

A：不需要。设置页保存后插件会重建 MinerU 客户端实例，5 个工具通过 getter 读最新配置，下一次调用就用新值，过程对模型透明。

Q：怎么卸载？

A：dsh plugin --profile web rm dsh-mineru，再清理 ~/.dsh/cordis.patch.yml 中由本插件插入的 - insert 块即可，临时文件不会被插件主动删除。

上手难度

入门 — 装好后只需在 GUI 设置页填一个 MinerU 服务地址，模型即可调用 mineru_parse_document 一把梭；如果只跑本地 CPU 版 MinerU，连 API Key 都不用配。

已知问题与限制

• end_page_id 默认 99999，不是"到 PDF 末页"；超过实际页数 MinerU 端会忽略，但若想精确切片需自己传具体整数（src/tools.ts:79 / AGENTS.md:47）
• lang_list 仅 pipeline 后端生效，VLM/hybrid 后端会静默忽略该参数（AGENTS.md:44）
• return_images=true 会让返回体里的 base64 图片特别大，建议图片密集型文档改用 response_format_zip=true（AGENTS.md:45）
• MinerU 服务端只保留任务 24 小时，长会话里把 task_id 缓存下来可能拿到已清理的响应，建议用完即弃（AGENTS.md:46）
• hybrid-engine / vlm-engine 后端要求服务端已加载 VLM 模型，未加载 VLM 会直接报错（AGENTS.md:43 / README.md:9）
• 当 apiKeyResolver 拿到 key 时，HTTP 客户端把 redirect: 'error'，鉴权请求不允许跟随 3xx 跳转，避免 token 泄露到非预期域名（src/client.ts:233）
• 配置文件必须在修改后保存才会热生效，编辑而不点保存按钮不会生效（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 服务器地址。