前言¶
DeepSeek Harness（简称 dsh）把模型、工具、会话和界面都做成可插拔插件。智能体写代码、改配置时很顺手，但一遇到扫描版 PDF、带公式的论文、PPT 讲义和 Excel 表格，纯文本循环就卡住了：模型看不见版面，普通抽取又容易把多栏、页眉页脚和表格拆乱。
OpenDataLab 的 MinerU 专门做这件事：把 PDF、图片、DOCX、PPTX、XLSX 转成适合大模型继续处理的 Markdown / JSON。它本身是独立的解析引擎，带 CLI、WebUI 和 FastAPI，并不会自动出现在 dsh 的工具列表里。
dsh-plugin-mineru 补的是这一段：在 Harness 里注册一组面向模型的工具，把已经跑起来的 MinerU HTTP 服务接到智能体循环中。本文按社区目录页、GitHub 仓库 README / 源码、npm 包说明，以及 MinerU、DeepSeek Harness 官方资料核对后整理。
这是什么¶
dsh-plugin-mineru 是一款 工具与能力 类 DeepSeek Harness 插件，由 HuanLinOTO 维护，仓库在 HuanLinOTO/dsh-plugin-mineru。插件内部名称是 dsh-mineru，npm 包名为 @huanlin/dsh-plugin-mineru，当前发布版本是 0.2.2（2026-08-14），主要语言是 TypeScript，要求 Node.js 18 及以上。截至 2026-08-17，GitHub 显示 30 星；社区目录页收录时显示 18 星，以仓库页面为准。
它解决的问题很具体：让 dsh 里的模型能调用 MinerU，把本地文档解析成结构化 Markdown，完整 JSON 结果另存文件，而不是让模型自己猜 PDF 里的字。
需要分清三层关系：
- DeepSeek Harness 是 DeepSeek 开源的智能体运行时，官方口号是「Everything is a Plugin」，仓库在 deepseek-ai/deepseek-harness。
- MinerU 是 OpenDataLab 的文档解析引擎，仓库在 opendatalab/MinerU。官方说明支持 PDF、图片、DOCX、PPTX、XLSX，输出 Markdown / JSON，公式转 LaTeX、表格转 HTML，并提供
mineru-apiFastAPI。 - 本插件 是社区项目，用
fetch调用 MinerU 的/health、/tasks、/tasks/{id}、/tasks/{id}/result。它不内置解析模型，也不替你部署 MinerU。
社区插件目录 deepseek-harness-plugin.com 是独立站点，和 DeepSeek / 幻方没有官方从属关系，不要把它当成官方应用商店。目录页写明本插件已同时收录于 dshfind 插件超市。
许可证以仓库为准：package.json 和 LICENSE 标明 AGPL-3.0（版权页写 Copyright (C) 2026 Huanlin）。GitHub 许可证探测和目录页显示为 NOASSERTION，属于探测未识别，不是第二种许可证。
核心功能¶
插件以 bundle 形式挂载：cordis.patch.yml 插入一行 dsh-mineru，package.json 声明 dsh.bundle.patch。宿主侧注册 5 个工具，浏览器侧带 Web UI 设置页（dsh.client.platform 为 web）。配置改动走 RPC，不必重新注册工具。
对接已部署的 MinerU API¶
客户端注释写明：对接 MinerU FastAPI（开发时针对 v3.4.4、协议 v2）。鉴权是可选的——开源 MinerU 服务默认没有内置认证；若凭据库或环境变量里解析到密钥，请求会带 Authorization: Bearer，并且拒绝跟随重定向。
支持的本地文件，以工具参数和客户端 MIME 映射为准：PDF、DOCX、PPTX、XLSX，以及 png / jpg / jpeg / gif / bmp / tiff / webp 等图片。必须是本机文件系统路径；如果只有 URL，要先下载到本地再解析。
五个面向模型的工具¶
README 把日常用法收成下面这组工具。
mineru_parse_document（推荐）
高层封装：提交文件 → 按间隔轮询 → 返回 Markdown。大多数单次解析用这个即可。可覆盖后端、解析方法、语言、公式/表格开关、页码范围，以及最长等待时间（默认 10 分钟）。源码里这个工具的执行超时是 900000 毫秒。
mineru_submit_parse_job
异步提交，立刻返回 task_id。适合大文档，或要并行丢多份文件。工具说明建议：一页 PDF 大约 1–2 秒，大文档可能要数分钟。
mineru_get_parse_status
查询任务状态，返回 pending / processing / completed / failed。排队时可能带 queued_ahead。
mineru_get_parse_result
取已完成任务的结果。Markdown 内联返回，超过 maxMdOutputChars（默认 20 万字符）会截断，全文写到临时文件；完整结构化 JSON 始终写到 raw_result_path，可用读文件工具继续看。
mineru_health
无参数。检查服务是否健康，以及版本、队列深度和最大并发，适合批量任务前做一次预检。
可配置的解析默认值¶
在 DSH GUI 设置页或 cordis.patch.yml 里配置，字段以仓库 README 为准：
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
baseURL |
string | 必填 | MinerU API 地址 |
apiKeyEnv |
credential-ref | MINERU_API_KEY |
API key 的环境变量名 / 凭据引用；测试实例可不鉴权 |
defaultBackend |
enum | pipeline |
pipeline / vlm-engine / hybrid-engine / vlm-http-client / hybrid-http-client |
defaultParseMethod |
enum | auto |
auto / txt / ocr |
defaultLang |
string | ch |
pipeline 后端语言代码 |
pollIntervalMs |
number | 2000 |
异步状态轮询间隔 |
pollTimeoutMs |
number | 600000 |
mineru_parse_document 最长轮询（10 分钟） |
requestTimeoutMs |
number | 60000 |
单次 HTTP 请求超时 |
maxMdOutputChars |
number | 200000 |
内联 Markdown 上限，超出则落临时文件 |
cordis.patch.yml 的首次启动种子是：
- insert:
- id: dsh-mineru
name: '@huanlin/dsh-plugin-mineru'
config:
baseURL: 'http://localhost:18000'
这只是插件自己的种子值。MinerU 官方文档里 mineru-api 的示例端口是 8000（mineru-api --host 0.0.0.0 --port 8000），Docker Compose 的 api profile 也映射 8000。装完插件后，必须在 GUI 里把 baseURL 改成你实际部署的地址，不要默认假设 18000 就是 MinerU 在听的端口。
安装与启用¶
目录页给出的安装命令如下，在 DeepSeek Harness 终端运行即可：
dsh plugin add github:HuanLinOTO/dsh-plugin-mineru
需要可复现安装时，目录页写法是固定 commit 哈希：
dsh plugin add github:HuanLinOTO/dsh-plugin-mineru#commit
把 #commit 换成具体哈希。仓库 README 当前另外推荐从 npm 安装，并指定 web profile（设置页走 Web UI）：
dsh plugin --profile web add @huanlin/dsh-plugin-mineru
npm 上 0.2.2 的 README 仍写从 git 安装；GitHub master 在 2026-08-15 有过推送，比 npm 发布时间更晚，以仓库 README 和目录页为准即可。
若用 git 安装且 pnpm ≥ 10，README 要求在对应 profile 的 pnpm-workspace.yaml 里允许构建：
allowBuilds:
'@huanlin/dsh-plugin-mineru': true
本地开发安装示例（路径按你的 checkout 修改）：
dsh plugin --profile web add link:D:\Projects\deepseek-harness\dsh-mineru
目录页提醒：插件以当前 dsh 进程的权限运行，安装时可能执行代码。安装前应检查源码仓库和许可证。
启用前还要有一台可访问的 MinerU。官方快速用法是：
mineru-api --host 0.0.0.0 --port 8000
浏览器打开 http://127.0.0.1:8000/docs 可看接口文档。插件不会帮你拉模型、装 GPU 驱动或选 backend，这些都在 MinerU 一侧完成。
典型用法¶
下面按官方工具说明串一条可复现路径，不额外编对话记录。
1. 改 baseURL
MinerU 起来之后，在 DSH GUI 的 MinerU 设置里覆盖 baseURL。若服务听在官方示例端口，应类似：
http://127.0.0.1:8000
测试实例通常不用填 API key。若你的网关要鉴权，把密钥放到 MINERU_API_KEY 对应的环境变量或凭据引用里。
2. 先探活
让模型调用 mineru_health。正常时应返回 healthy，以及版本、排队/处理中任务数和最大并发。批量丢文件前先看容量，避免把队列打满。
3. 日常：一条命令走完解析
把本地路径交给智能体，例如工作区里的 docs/paper.pdf。模型应调用 mineru_parse_document，必填参数是 file_path。常用可选参数：
backend：默认pipeline（工具说明写 hallucination-free、多语言）。hybrid-engine需要 VLM；CPU-only 服务应继续用pipeline。parse_method：auto/txt/ocr（pipeline / hybrid 有效）。lang_list：仅 pipeline 有效，默认['ch']；VLM / hybrid 后端会忽略。formula_enable/table_enable：默认都是 true。start_page_id/end_page_id：PDF 页码，从 0 起算；end_page_id默认 99999（表示尽量到末页），不是「最后一页」这个语义值。poll_timeout_ms：等不及默认 10 分钟时再改。
返回值里的 md_content 就是给模型继续总结、摘录、对照代码的 Markdown。公式、表格的还原质量取决于 MinerU 后端，不取决于这层 HTTP 封装。
4. 大文件或批量：拆成提交 / 轮询 / 取结果
流程在 README 和工具描述里写得很清楚：
mineru_submit_parse_job提交，拿到task_idmineru_get_parse_status等到completed或failedmineru_get_parse_result取 Markdown；完整 JSON 在raw_result_path
任务在服务端保留约 24 小时，不要把很久以前的 task_id 跨会话反复用。结果文件名是去掉扩展名后的 stem，提交响应里的 file_names 才是可靠的对照。
5. 输出过大时看临时文件
内联 Markdown 默认上限 20 万字符。超出后工具会把全文写到临时目录（文件名形如 mineru-{taskId}.md），并在返回值里给出路径。需要版面中间结果或图片时，提交阶段打开 return_middle_json / return_content_list / return_images；return_images 可能带出很大的 base64，插件开发说明建议图片多的文档优先考虑 zip 响应，而不是把图全部内联进上下文。
适用场景与注意事项¶
比较适合这些情况：
- 在 DeepSeek Harness 里做 RAG、论文阅读、需求/设计文档对照，原始材料是 PDF 或 Office 文件
- 扫描件、多栏排版、含公式或表格的文档，需要先结构化再让模型处理
- 已经（或准备）自建 MinerU，希望智能体直接调解析，而不是自己写 curl 轮询
使用前注意下面几条，都来自目录页、仓库说明或 MinerU 文档，不是额外发挥。
- 插件不等于 MinerU。 没把
mineru-api（或等价 HTTP 入口）跑起来，工具调用会失败。GPU、模型文件、backend 选择都在 MinerU 部署侧。 baseURL必须对上真实端口。 插件种子是http://localhost:18000，MinerU 官方示例是 8000。改错地址时，mineru_health会立刻暴露问题。- 只接受本地路径。 远程 URL 要先下载。插件以当前 dsh 进程权限读这些文件，等于进程能读到的本地内容都可能被送去 MinerU。
- backend 和机器要匹配。
pipeline适合无 VLM 的环境；hybrid-engine需要 VLM。lang_list只对 pipeline 有意义。 - 结果会进模型上下文。 超长 Markdown 虽有截断，完整 JSON 仍落在临时文件上。不要把含密钥、合同原件的目录随手丢给解析服务，尤其是
baseURL指向非本机时。 - 许可证是 AGPL-3.0。 修改后通过网络提供服务时，条款比常见 MIT 插件更严，安装前应自己读
LICENSE。 - 安全边界。 目录页写明：插件以当前 dsh 进程权限运行，安装时可能执行代码。源码在 GitHub，安装前应过一遍。
小结¶
dsh-plugin-mineru 不重新实现一套 PDF 解析，而是把 MinerU 的 FastAPI 接到 DeepSeek Harness 的工具层：日常用 mineru_parse_document，大批量用提交/轮询/取结果，并用设置页管理 API 地址。对已经在用 dsh、又需要把文档变成可被模型消化的 Markdown / JSON 的人来说，缺的往往不是「再写一段提示词」，而是这一层稳定的 HTTP 工具。
目录页与仓库：
- 社区目录：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-plugin-mineru/
- GitHub：https://github.com/HuanLinOTO/dsh-plugin-mineru
- npm：https://www.npmjs.com/package/@huanlin/dsh-plugin-mineru
- MinerU：https://github.com/opendatalab/MinerU
- DeepSeek Harness：https://github.com/deepseek-ai/deepseek-harness
