# dsh-plugin-mineru

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

## Metadata

- Author: [@HuanLinOTO](https://github.com/HuanLinOTO)
- Repo: <https://github.com/HuanLinOTO/dsh-plugin-mineru.git>
- GitHub: [HuanLinOTO/dsh-plugin-mineru](https://github.com/HuanLinOTO/dsh-plugin-mineru)
- Stars: 38
- Language: TypeScript
- License: [NOASSERTION](https://spdx.org/licenses/NOASSERTION.html)
- Topics: `dsh-plugin`
- Forks: 2
- Open Issues: 4
- Last push: 2026-08-15T05:06:34.000Z
- Added: 2026-08-13T00:00:00.000Z

## Install

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

## Wiki

## 一句话定位
把 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 Harness | 0.0.1-rc.1+（由 peerDeps 推导） | 需要宿主提供 `tools` 与 `connection` 服务；私有 RPC 通道走 `@deepseek-ai/dsh-host-apiproxy`（package.json:53-63） |
| Node.js | >=18.0.0 | package.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 之类需要编译的包 |

## 安装方式
```bash
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-client | `pipeline` |
| 默认解析方式 | 选项 | auto（自动判定）/ txt（纯文本，不 OCR，速度快）/ ocr（强制走 OCR） | `auto` |
| 默认语言 | 字符串 | 仅 pipeline 后端生效；常用值 `ch`（中文/英文/日文）、`en` | `ch` |
| 轮询间隔（毫秒） | 数字 | 异步任务每次查询状态的间隔 | `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）

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-plugin-mineru](https://deepseek-plugin.org/plugins/HuanLinOTO/dsh-plugin-mineru)
Wiki generated by AI (model: `MiniMax-M3`)