DeepSeek HarnessHub
提交插件

Yurzi/dsh-pdf-mineru ↗★ 12

dsh-pdf-mineru

基于 MinerU 的文档解析与后台任务管理插件 适合需要通过MinerU官方云或自建服务解析PDF等文档，并在DSH中管理解析任务的用户。

视觉工具
包名
dsh-pdf-mineru
兼容性
待验证
Harness 依赖范围
^0.2.0-rc.2
Cordis 依赖范围
~4.0.4
版本
0.2.0
许可证
MIT
最近更新
2026年10月4日

安装

$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:Yurzi/dsh-pdf-mineru

说明文档

阅读完整 README ↗

2. 配置与连接

打开 DSH 界面中的 Plugins / 插件 → dsh-pdf-mineru，根据您的使用场景选择 Provider。配置页位于插件 bundle 详情中，不再单独出现在全局 Settings 导航。设置页按卡片分组，高级配置按需展开；修改后点击 Save Configuration / 保存配置 生效。连接测试使用当前草稿，缓存清理仍需先预览再确认。

配置由 DSH Loader 的 Config 与 profile patch 管理；可热更新字段使用 Volatile.get()，保存后影响后续调用。插件关闭原生自动生成表单，保留显式草稿保存。Provider-based v1 配置在内存中规范化，启动不写回配置；旧 settings.yaml 的导入由 DSH 负责。

设置页包含 Provider、解析默认值、存储与缓存、轮询、重试、输出限制、安全上限和存储维护八张卡片。支持全部展开／折叠，折叠不会丢失表单草稿；启动时固定的安全上限只读展示，需修改宿主配置并重启。界面沿用 DSH 深浅色主题，并支持键盘导航和紧凑布局。

MinerU 配置卡片预览（旧版导航，当前入口为 Plugins → dsh-pdf-mineru）

上图展示配置卡片；旧版 Settings 导航仅供参考，当前请从 Plugins / 插件 → dsh-pdf-mineru 打开。

方案 A：使用 MinerU 官方云（推荐，免部署）
  1. 前往 MinerU 官网 注册并获取 API Token。
  2. 在终端配置环境变量（或通过 DSH 凭据服务管理）： 
    export MINERU_API_KEY="your-token-here"
  3. 在设置中选择 Official v4，保持 API Key Env Var 为 MINERU_API_KEY，点击 Test Active Provider 即可完成验证。
方案 B：使用本地 / 私有化自建服务
  1. 启动 MinerU 服务：4.x 请选择 Self-Hosted MinerU (V1 API)（常见地址 http://localhost:8000）；3.x 请选择 Self-Hosted MinerU (Legacy v2)（常见地址 http://localhost:18000）。API 代际不等于软件大版本，也不要填入 VLM 推理服务地址。
  2. V1 配置档位 tier 和独立的 OCR 模式 ocrMode: auto/txt/ocr；legacy-v2 配置 backend 映射及共享解析默认值。两种协议显式选择，不自动降级或映射 backend 为 tier。
  3. 本地 HTTP 需勾选 Allow Insecure HTTP。点击 Test Active Provider 验证：V1 显示部署声明的档位、产物和来源，真实解析前也检查 ZIP、file_id 与选定档位是否可用。验证不等于解析效果保证。
  4. 配置修改只更新草稿，点击 Save Configuration 才保存。切换协议、折叠卡片不清空各 profile 的草稿。

3. 开始使用

配置完成后，无需记忆复杂指令，直接在聊天框中用自然语言对 Agent 下达需求即可！

🛠️ 设置与配置参考

推荐直接在 DSH Web GUI (Plugins / 插件 → dsh-pdf-mineru) 中进行可视化调整。若需要直接编辑配置文件（cordis.patch.yml），可参考以下常用配置：

📋 点击展开：YAML 配置示例

1. 官方云 (Official v4) 推荐配置

schemaVersion: 3
activeProvider: mp_official
providers:
  - id: mp_official
    type: official-v4
    baseURL: https://mineru.net/api/v4
    apiKeyEnv: MINERU_API_KEY
    models: [pipeline, vlm]
defaults:
  model: vlm
  ocr: false
  formula: true
  table: true

2. 本地私有化 (Self-hosted legacy v2) 推荐配置

schemaVersion: 3
activeProvider: mp_self_hosted
providers:
  - id: mp_self_hosted
    type: self-hosted-legacy-v2
    baseURL: http://localhost:18000
    allowInsecureHttp: true
    modelMap:                 # legacy-v2 的 backend 名称
      pipeline: pipeline
      vlm: vlm-engine
defaults:
  model: pipeline
  ocr: false
  formula: true
  table: true

3. MinerU 4.x 自托管（V1 API）配置

schemaVersion: 3
activeProvider: mp_self_hosted_v1
providers:
  - id: mp_self_hosted_v1
    type: self-hosted-v1
    baseURL: http://localhost:8000
    allowInsecureHttp: true
    apiKeyEnv: MINERU_API_KEY
    tier: standard          # 可省略，让服务端选择；不是具体模型名
    ocrMode: auto           # auto / txt / ocr；按 V1 profile 独立保存
    configuredVersion: '4.0.10' # 原地升级服务或模型后更新缓存版本

V1 不暴露上游已移除的请求级语言／公式／表格参数。隐藏这些共享默认值不会把它们清空，但它们不影响 V1 请求或缓存；内部占位值不表示服务端关闭相关能力。OCR 的 txt 与 auto 保持不同语义，txt 不保证完全不运行视觉模型。档位切换和 OCR 模式变化会隔离缓存；standard/advanced 可以使用同一模型、不同计算量。

**配置版本与自动迁移：**当前插件配置为 schemaVersion: 3，独立于 MinerU 软件/API 版本及缓存、游标版本。读取旧配置时只在内存中按 1 → 2 → 3 转换；未声明版本的 Provider-based 配置按版本 2 处理。启动、配置读取均不自动改写磁盘；用户点击保存后，才通过宿主事务持久化版本 3 的完整迁移结果，后续普通保存仍沿用原生 Settings。

  • 1 → 2 移除旧批量/产物默认字段；2 → 3 将 self-hosted-v2 转为 self-hosted-legacy-v2，保留有效 ID、活动选择、地址、凭据引用、backend 映射及其他有效设置，移除 legacy 不支持的 tier。
  • 旧版本缺失或不支持的字段值使用对应默认值修复；重复/无效 ID 采用不冲突的默认 ID。迁移记录只含版本、字段路径和 Provider ID，不记录原始值或密钥。不会因迁移自动开启未经明确授权的 HTTP；缺少授权的 HTTP 默认端点改用 HTTPS，无效凭据引用不会被传给 Provider。
  • 最新版本编辑继续严格校验；未知未来版本和未知结构字段拒绝，防止误降级或吞掉配置。宿主组合基础层中残留的两个已废弃字段仅在内存清除；不恢复旧 flat config。
  • 首次显式保存迁移配置时，完整快照同时保存修复后的非表单字段，避免更新版本号后残留坏值；运行中的 storageRoot/limits 仍不允许改变。保存失败不会提前更新运行时配置。

**接口选择与缓存：**迁移不根据 URL/backend/tier 猜测接口。此前依赖 V1 自动识别的部署需主动选择 self-hosted-v1。原自托管缓存不会被新 Provider 身份复用，配置迁移也不改写解析产物；连接失败不会降级到另一个协议。

**V1 功能边界：**使用本地路径或会话附件，经上传去重、任务轮询及 ZIP 下载后发布到插件自身缓存。已处理 partial/canceled 状态、逐文件错误和素材实际路径；不把服务器资源 ID 当作重启后可恢复的持久化记录。工具仍是单文件；不暴露 URL/inline 来源、callback/Webhook、服务端 DELETE 取消、HTML/DOCX 产物选择或 Doclib。job_kill 只取消本次等待，不中止共享上游任务。read_pdf.pages 是已解析内容的物理页投影，不是完整上游 page_range 语法；原页 view 仅支持 PDF。当前输入白名单仍限于 PDF、常见图片及 doc/docx/ppt/pptx/xls/xlsx；HTML/MHTML、OpenDocument、RTF、EPUB、OFD、CSV/TSV 等上游新增格式尚未开放，HTML 已验证在上传前明确拒绝。不能将四档×所有文件类型视作均已覆盖或验证。

4. 存储与限制自定义（可选）

storage:
  storageRoot: /absolute/path/to/dsh/cache/pdf-mineru  # 默认在 $DSH_HOME/cache/pdf-mineru
  cacheEnabled: true
output:
  maxInlineChars: 12000   # 单次响应预算；正文每块另限 8000 UTF-16 单元
  maxInlineImages: 6      # 单次 read_pdf 响应最多内联图片数（0–100）
limits:
  maxFileBytes: 209715200  # 200 MB

多进程共享存储与升级

多个进程可以共享同一 storageRoot，前提是同一主机、同一 PID 可见命名空间及支持 hard link 的一致本地文件系统。不支持 NFS、跨主机或互不可见 PID 的容器共享这一锁协议。

升级时请先停止所有使用该目录的 MinerU 进程，再统一更新并重启。新协议的 .process.lock 是持久版本隔离标记，实际互斥与使用记录位于 .lock/；它不是应当在退出时删除的“残留锁”。遇到旧锁或损坏记录，请先确认所有相关进程已停止，再按错误提示人工恢复，切勿在活跃进程运行时删除协调文件。

storageRoot 与 limits.* 在启动时固定。运行中的配置保存会拒绝这些值的变更；应修改宿主配置并重启插件，不能依赖一次被拒绝的保存自动生效。

1. 官方云 (Official v4) 推荐配置

schemaVersion: 3
activeProvider: mp_official
providers:
  - id: mp_official
    type: official-v4
    baseURL: https://mineru.net/api/v4
    apiKeyEnv: MINERU_API_KEY
    models: [pipeline, vlm]
defaults:
  model: vlm
  ocr: false
  formula: true
  table: true

2. 本地私有化 (Self-hosted legacy v2) 推荐配置

schemaVersion: 3
activeProvider: mp_self_hosted
providers:
  - id: mp_self_hosted
    type: self-hosted-legacy-v2
    baseURL: http://localhost:18000
    allowInsecureHttp: true
    modelMap:                 # legacy-v2 的 backend 名称
      pipeline: pipeline
      vlm: vlm-engine
defaults:
  model: pipeline
  ocr: false
  formula: true
  table: true

3. MinerU 4.x 自托管（V1 API）配置

schemaVersion: 3
activeProvider: mp_self_hosted_v1
providers:
  - id: mp_self_hosted_v1
    type: self-hosted-v1
    baseURL: http://localhost:8000
    allowInsecureHttp: true
    apiKeyEnv: MINERU_API_KEY
    tier: standard          # 可省略，让服务端选择；不是具体模型名
    ocrMode: auto           # auto / txt / ocr；按 V1 profile 独立保存
    configuredVersion: '4.0.10' # 原地升级服务或模型后更新缓存版本

V1 不暴露上游已移除的请求级语言／公式／表格参数。隐藏这些共享默认值不会把它们清空，但它们不影响 V1 请求或缓存；内部占位值不表示服务端关闭相关能力。OCR 的 txt 与 auto 保持不同语义，txt 不保证完全不运行视觉模型。档位切换和 OCR 模式变化会隔离缓存；standard/advanced 可以使用同一模型、不同计算量。

**配置版本与自动迁移：**当前插件配置为 schemaVersion: 3，独立于 MinerU 软件/API 版本及缓存、游标版本。读取旧配置时只在内存中按 1 → 2 → 3 转换；未声明版本的 Provider-based 配置按版本 2 处理。启动、配置读取均不自动改写磁盘；用户点击保存后，才通过宿主事务持久化版本 3 的完整迁移结果，后续普通保存仍沿用原生 Settings。

  • 1 → 2 移除旧批量/产物默认字段；2 → 3 将 self-hosted-v2 转为 self-hosted-legacy-v2，保留有效 ID、活动选择、地址、凭据引用、backend 映射及其他有效设置，移除 legacy 不支持的 tier。
  • 旧版本缺失或不支持的字段值使用对应默认值修复；重复/无效 ID 采用不冲突的默认 ID。迁移记录只含版本、字段路径和 Provider ID，不记录原始值或密钥。不会因迁移自动开启未经明确授权的 HTTP；缺少授权的 HTTP 默认端点改用 HTTPS，无效凭据引用不会被传给 Provider。
  • 最新版本编辑继续严格校验；未知未来版本和未知结构字段拒绝，防止误降级或吞掉配置。宿主组合基础层中残留的两个已废弃字段仅在内存清除；不恢复旧 flat config。
  • 首次显式保存迁移配置时，完整快照同时保存修复后的非表单字段，避免更新版本号后残留坏值；运行中的 storageRoot/limits 仍不允许改变。保存失败不会提前更新运行时配置。

**接口选择与缓存：**迁移不根据 URL/backend/tier 猜测接口。此前依赖 V1 自动识别的部署需主动选择 self-hosted-v1。原自托管缓存不会被新 Provider 身份复用，配置迁移也不改写解析产物；连接失败不会降级到另一个协议。

**V1 功能边界：**使用本地路径或会话附件，经上传去重、任务轮询及 ZIP 下载后发布到插件自身缓存。已处理 partial/canceled 状态、逐文件错误和素材实际路径；不把服务器资源 ID 当作重启后可恢复的持久化记录。工具仍是单文件；不暴露 URL/inline 来源、callback/Webhook、服务端 DELETE 取消、HTML/DOCX 产物选择或 Doclib。job_kill 只取消本次等待，不中止共享上游任务。read_pdf.pages 是已解析内容的物理页投影，不是完整上游 page_range 语法；原页 view 仅支持 PDF。当前输入白名单仍限于 PDF、常见图片及 doc/docx/ppt/pptx/xls/xlsx；HTML/MHTML、OpenDocument、RTF、EPUB、OFD、CSV/TSV 等上游新增格式尚未开放，HTML 已验证在上传前明确拒绝。不能将四档×所有文件类型视作均已覆盖或验证。

若无关插件阻止 Web shell 启动，可显式限定浏览器 fixture 的排除列表（不修改宿主配置）：

6. （显式选择）使用真实 Token 运行在线解析，会上传文档

MINERU_API_KEY= pnpm run smoke:official-v4 -- /path/to/sample.pdf


GUI 验证在现有 Web 地址中注入当前构建，使用浏览器内的配置／凭据／插件清单 fixture，并隔离该测试浏览器的 HMR graph；不修改真实配置、凭据或缓存，也不代表已更新宿主安装的插件。

> 文档入口：[PDF阅读指南](https://github.com/Yurzi/dsh-pdf-mineru/blob/6ab9784f5e5f9389104f4df5ddd014adb1adf7bf/docs/model-reading.md) · [版本记录](https://github.com/Yurzi/dsh-pdf-mineru/blob/6ab9784f5e5f9389104f4df5ddd014adb1adf7bf/CHANGELOG.md)。已完成的阶段性开发报告不作为当前使用契约维护，历史信息可从Git记录查阅。

> 想要深入了解插件的架构设计、数据模型、并发请求合并、安全解包与存储隔离机制？请查阅 **[ARCHITECTURE.md](https://github.com/Yurzi/dsh-pdf-mineru/blob/6ab9784f5e5f9389104f4df5ddd014adb1adf7bf/ARCHITECTURE.md)**。

---

## 📜 许可证与致谢

- 本项目基于 [MIT License](https://github.com/Yurzi/dsh-pdf-mineru/blob/6ab9784f5e5f9389104f4df5ddd014adb1adf7bf/LICENSE) 开源。
- 感谢 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 提供的卓越插件体系。
- 感谢 [OpenDataLab MinerU](https://github.com/opendatalab/MinerU) 提供的文档解析能力。
- 感谢 [Huanlin/dsh-plugin-mineru](https://github.com/HuanLinOTO/dsh-plugin-mineru) 带来的早期设计灵感。
- 本插件已被 [Awesome DeepSeek Harness Plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 社区精选列表收录（[收录详情页](https://awesome-dsh-plugin.com/p/Yurzi/dsh-pdf-mineru)）。
- Banner 图像中的 DeepSeek 鲸鱼娘形象由上善无形原创角色与 ZipZipPipe 二创设计衍生，遵循 [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.zh-hans) 许可。