dsh-plugin-mineru

38Stars2Forks4Issues0Watchers

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

Categories✨ Creative Content
HuanLinOTOHuanLinOTO
·HuanLinOTO/dsh-plugin-mineru.git
Language
TypeScript
License
NOASSERTION
Branch
master
dsh-plugin

Install

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

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

一句话定位

把 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% 的场景；需要批量或长任务的用户才需要用到三步异步流程。

前置依赖与兼容性

依赖最低版本说明
DeepSeek Harness0.0.1-rc.1+（由 peerDeps 推导）需要宿主提供 tools 与 connection 服务；私有 RPC 通道走 @deepseek-ai/dsh-host-apiproxy（package.json:53-63）
Node.js>=18.0.0package.json engines 字段声明；源码用 node:fs/promises、node:os、node:path 等内置模块（package.json:83-85）
MinerU 服务端v3.4.4，protocol v2插件仅是协议封装，必须自行部署一个 MinerU FastAPI 实例并填到 baseURL（src/client.ts:3-9 / README.md:93）
平台跨平台package.json 未声明 os/cpu 限制；纯 TypeScript + 内置 Node API
原生模块无零原生依赖；不引入 sqlite / pty / canvas 之类需要编译的包

安装方式

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

配置项

配置类型说明默认值
API 地址字符串MinerU 服务地址，例如 http://your-host:18000。必填，否则插件启动失败（src/index.ts:57-59）（首次启动 seed 为 http://localhost:18000，见 cordis.patch.yml:6-10）
API Key 环境变量名字符串鉴权用的环境变量名；插件运行时去读这个变量（也尝试读宿主 credentials 服务）。开源 MinerU 无鉴权可保持默认MINERU_API_KEY
默认解析后端选项pipeline（无 VLM、多语言、CPU 可用）/ vlm-engine（仅 VLM）/ hybrid-engine（VLM+pipeline，需 VLM 模型）/ vlm-http-client / hybrid-http-clientpipeline
默认解析方式选项auto（自动判定）/ txt（纯文本，不 OCR，速度快）/ ocr（强制走 OCR）auto
默认语言字符串仅 pipeline 后端生效；常用值 ch（中文/英文/日文）、ench
轮询间隔（毫秒）数字异步任务每次查询状态的间隔2000
轮询超时（毫秒）数字mineru_parse_document 等待解析完成的最长时间600000（10 分钟）
请求超时（毫秒）数字单次 HTTP 请求超时60000
Markdown 输出字符上限数字超长 markdown 会被截断并写到系统临时目录200000

常见问题

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）
← Back to plugin directory