dsh-mineru

dsh plugin --profile web add dsh-mineru

dsh-mineru





仓库: <https://github.com/Lee-Hilex/dsh-mineru> · npm: dsh-mineru · [更新日志](CHANGELOG.md)

[English](README.md) | 简体中文

dsh-mineru 是 DeepSeek Harness（简称 dsh）的 MinerU 多模态文档解析插件：把 PDF、Word、PPT、Excel、HTML 和图片一键转成结构化 Markdown。配置了 MinerU Token 走 🎯 精准解析 API；不配 Token 也能用 ⚡ Agent 轻量解析 API（免登录，IP 限频）。

⚠️ 内容会出网：每次解析都会把文件上传到 MinerU 远端服务，无完全离线模式；涉密 / 涉案 / 不得出网的材料请勿使用。详见 [安全模型](#安全模型)。

目录

• [简介](#简介) · [快速开始](#快速开始) · [两种 API 模式](#两种-api-模式) · [工具详解](#工具详解) · [解析结果与 Artifacts](#解析结果与-artifacts) · [配置参考](#配置参考) · [使用技巧](#使用技巧) · [Web 界面](#web-界面) · [限流与可靠性](#限流与可靠性) · [错误码速查](#错误码速查) · [安全模型](#安全模型) · [常见问题 FAQ](#常见问题-faq) · [开发与发布](#开发与发布) · [贡献](#贡献) · [许可](#许可)

简介

这是什么？

dsh-mineru 把 MinerU（OpenDataLab 出品的高精度文档解析引擎）接入 DeepSeek Harness 的 Agent 生态，让纯文本模型也能"看懂"文档：模型拿到的是结构化 Markdown（含表格、公式、图片），而不是打不开的二进制文件。

典型场景：

• 读论文 / 合同 / 报告：让 Agent 解析 PDF 后总结要点、提取数据；
• 批量整理资料：一次解析几十份文档，逐项产出 Markdown；
• 图片 / 截图转文字：OCR 扫描件、网页截图转可检索文本；
• 公式与表格还原：论文中的数学公式、Excel 表格结构完整保留。

支持的文件格式

格式 · 精准解析 API（需 Token） · Agent 轻量 API（免 Token）

PDF · ✅ · ✅

Word（.doc / .docx） · ✅ · ✅（仅 .docx）

PPT（.ppt / .pptx） · ✅ · ✅（仅 .pptx）

Excel（.xls / .xlsx） · ✅ · ✅（仅 .xlsx）

HTML（.html / .htm） · ✅（自动强制 MinerU-HTML 模型） · ❌

图片（.png .jpg .jpeg .jp2 .webp .gif .bmp） · ✅ · ✅

注：Agent 轻量 API 不支持 .doc / .ppt / .xls（旧版 Office 格式）与 HTML，遇到这类文件请改用精准解析（需 Token）。

核心能力

• 适配 DSH 0.2.0-rc.2 — 使用真实 Loader、设置服务和工具运行时验证，同时保留 0.1.5-rc.x 的 peer 范围与旧设置接口；
• 双 API 自动切换 — 按是否配置 Token 自动选择精准解析或轻量解析，也可手动指定；
• 渐进式工具曝光 — 平时只挂一个极小的 mineru_activate 引导工具，激活后才挂载完整工具集，省上下文；
• 拖拽上传 — 文件直接拖进聊天窗口，路径自动填入输入框，纯文本模型也能处理文档；
• 自动分批批量解析 — 一次提交上百个文件/URL，自动按官方限额分批；
• 限流感知 — 内置令牌桶、每日限额、429 退避重试，错误码全部翻译成可操作提示；
• 结果落地为 Artifact — 解析结果写入工作区文件，Web 界面可预览/打开，带签名链接。

快速开始

第 1 步：安装

Note: 需要已安装 DeepSeek Harness 0.2.0-rc.1 或更新（0.2.0 线），或兼容的 0.1.5-rc.x，且 dsh 命令可用。0.2.0 线请使用插件 0.1.15 或更高版本；0.1.14 仅覆盖 0.2.0-rc.2+，0.1.13 仅声明旧宿主版本范围。若 npm 仍提供 0.1.13，请按下文从源码打包安装。

从 npm 安装（推荐）

dsh plugin --profile web add dsh-mineru        # Web 界面使用
dsh plugin --profile headless add dsh-mineru   # 无头（Headless）模式使用

从源码构建（开发 / 预览最新改动）

git clone git@github.com:Lee-Hilex/dsh-mineru.git
cd dsh-mineru
npm ci             # 开发测试推荐 Node.js 24；本包无需 build
npm test           # 包含真实 DSH 0.2.0-rc.2 集成测试
npm pack           # 产出 dsh-mineru-<version>.tgz
dsh plugin --profile web add ./dsh-mineru-<version>.tgz

修改源码后重新 npm pack 并重装即可。注意本地安装请用 tgz（pnpm link: 安装会使 @deepseek-ai 依赖解析脱离 profile）。

桌面端 profile 使用 dsh plugin --profile desktop add ./dsh-mineru-0.1.14.tgz。兼容声明可直接通过宿主版本检查，无需 allow-version 豁免。npm run test:compat 仅运行真实宿主兼容测试；MinerU 响应采用模拟服务，测试不会上传文档或消耗 API 额度。

第 2 步：验证安装

dsh --profile web --dump-config | grep -A 2 "id: mineru"

期望输出（# == 注释行 + 你的插件行）：

# == dsh-mineru
  - id: mineru
    name: dsh-mineru

然后重启 Web profile（dsh web），在 设置 → 插件 → MinerU 解析 中即可看到本插件。

第 3 步：配置（可选）

不配 Token 也能用（自动走 Agent 轻量解析）。配 Token 可以解锁完整能力（精准解析 + 批量 + HTML + 更多格式）：

• Web 界面：设置 → 插件 → MinerU 解析 → 在 Token 输入框粘贴 Token（只写不读，留空保留现有值）；
• Headless / 命令行：在 $DSH_HOME/.credentials.yaml 写入 MINERU_API_TOKEN: <你的Token>，或设置环境变量 MINERU_API_TOKEN。

Token 每次调用时实时解析，轮换后无需重启立即生效。Token 去哪领：<https://mineru.net> 注册后到 API 管理页面获取。

第 4 步：开始使用

Web 界面（推荐方式，支持拖拽）：

1. 把 PDF/Word/图片直接拖进聊天窗口 —— 文件会自动保存到会话工作区，路径填入输入框（不会自动发送）；

2. 在输入框补一句需求，比如「把这份 PDF 解析成 Markdown，然后总结一下重点」；

3. 发送。Agent 会自动激活工具并调用 mineru_parse，解析结果以文件形式返回，可点击预览。

URL 解析：直接告诉 Agent「解析这个网页/文档：https://example.com/paper.pdf」即可。

Headless 快速验证（冒烟测试）：一次性任务走 headless profile：

dsh --profile headless "把 C:/docs/sample.pdf 解析成 Markdown，并总结前 3 段"

Headless 与 Web 共用同一套工具语义；也可以在会话中输入 /mineru-tools 加载使用说明技能。

两种 API 模式

维度 · 🎯 精准解析 API（需 Token） · ⚡ Agent 轻量解析 API（免 Token）

接口 · /api/v4/extract/task、/api/v4/file-urls/batch、/api/v4/extract/task/batch · /api/v1/agent/parse/url、/api/v1/agent/parse/file

模型 · pipeline / vlm（默认）/ MinerU-HTML · 固定轻量 pipeline 模型

大小限制 · ≤ 200 MB · ≤ 10 MB

页数限制 · 单次请求 ≤ 200 页（工作区 PDF 超出时自动分片） · ≤ 20 页（不自动分片）

批量解析 · ✅（URL 每批 ≤200，本地上传每批 ≤50，自动分批） · ❌ 仅单文件

输出 · Zip：full.md + content_list.json + layout.json + 图片（可加 docx/html/latex） · 仅 Markdown

适用场景 · 长文档、扫描件、公式表格、批量、HTML · 快速粗读、小文件、临时使用

模式选择（mode 参数或配置项）：

• auto（默认）— 有 Token 走精准解析，没 Token 走 Agent 轻量；
• precision — 强制精准解析，没配 Token 会直接报错提示；
• agent — 强制 Agent 轻量解析。

想知道当前会话实际走的哪个 API：调用一次 mineru_activate，返回结果里的 api 字段会明确告诉你（precision 或 agent）。

工具详解

安装后，工具集默认渐进式曝光：一开始只有 mineru_activate 一个引导工具，调用一次即解锁其余三个工具，随后 mineru_activate 对本会话自动隐藏。

mineru_activate —— 激活引导

项 · 说明

用途 · 解锁 mineru_parse / mineru_batch_parse / mineru_task 并加载 mineru-tools 技能

参数 · 无

返回 · 当前生效的 API 模式、是否已配 Token、各 API 限制等现状摘要

mineru_parse —— 解析单个文档

将工作区文件路径或 http(s) URL 解析为结构化 Markdown。

参数 · 必填 · 说明

source · ✅ · 工作区文件路径，或完整 http(s) URL

mode · · auto（默认）/ precision / agent

modelVersion · · 精准解析模型：pipeline / vlm（默认，推荐）/ MinerU-HTML（

…(truncated)