文档解析器 Lee-Hilex/dsh-mineru

dsh-mineru

仓库: <https://github.com/Lee-Hilex/dsh-mineru> · npm: dsh-mineru · 更新日志

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

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

目录

- 简介 · 快速开始 · 两种 API 模式 · 工具详解 · 解析结果与 Artifacts · 配置参考 · 使用技巧 · Web 界面 · 限流与可靠性 · 错误码速查 · 安全模型 · 常见问题 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（HTML 源自动强制） |
| language | | 文档语言包，默认 ch（中英），见 language 取值 |
| enableTable | | 表格识别，默认 true |
| enableFormula | | 公式识别，默认 true |
| isOcr | | 强制 OCR（扫描件），默认 false |
| pageRanges | | 精准解析页码范围，逗号分隔，如 "2,4-6"；支持倒数页 "2--2"（倒数第 2 页）。不传表示整份文档；工作区 PDF 超过 200 页上限时自动分片 |
| pageRange | | Agent 解析页码范围，仅 from-to 或单页，如 "1-10" |
| extraFormats | | 额外导出格式（仅精准解析）：docx / html / latex |
| dataId | | 业务数据 ID（可选，≤128 字符） |
| timeoutMs | | 整个操作（含轮询）超时，默认取插件配置（10 分钟） |
| output | | 结果目录基名，默认取源文件名 |
| anchor | | 额外产出一份带页级块锚点的 document.md（每块一行 ），默认 false；详见 页级块锚点产物 |

返回要点：ok、所用 api/modelVersion、taskId、耗时、runDir 结果目录、截断的 Markdown 预览、Artifact 列表（Web 含签名预览链接）；带 anchor: true 时另附 anchor 摘要，指明写出的 document.md。

页级块锚点产物（anchor）

full.md 是连续正文，正文里没有任何信息能说明某句话来自哪一页，扫描件的结论因此无法回溯到页码。anchor: true 额外写一份 document.md，用每块前的一行 HTML 注释带上这个信息：

君子务本，本立而道生。

image

表一 孔门弟子年表姓名字生年…

- pN 是这份文件的物理页序（1 基，含封面与前言），不是书本或期刊页面上印的印刷页码。云端对请求的页会重新编号，所以 pageRanges: "2,4-6" 下锚点就是 p2, p4, p5, p6——映射口径是 requestedPages[page_idx]，不是固定偏移；
- bK 是该块在本页内按 content_list.json 顺序的序号。页眉、页脚、页码不进正文但仍占号，所以 bK 可能不连续（如 b1, b2, b4）——这是有意的：bK 始终指向 content_list.json 里同一条记录；
- 文本块渲染正文；云端给了标题层级时映射成对应的 Markdown 标题；表格渲染为标题 + table_body；图片渲染为 ；
- 云端标为 [Unreadable] 的块保留锚点并显示 [Unreadable]；正文为空的块同样保留锚点；
- 只有精准解析 API 的结果含 content_list.json，因此在 Agent 轻量解析下传 anchor: true 会返回一条提示而不产出 document.md，不会让整次解析失败。

页面上印的是印刷页码，它和物理页序未必一致：前言用罗马数字编号，或析出文献保留原刊页码，都会让正文页码整体偏移。结果包里带可识别的 page_number 块时，渲染会拿它做一次尽力而为的自检，把每页的「印刷页码 − 物理页序」记进锚点摘要的 pageNumbers 字段（{ detected, total, offsets }，offsets 去重后升序），偏移恒为一套非零值时给出一行提示：

anchor.pageNumbers = { "detected": 4, "total": 4, "offsets": [3] }
anchor.warnings = ["印刷页码与物理页序整体相差 +3（前言用罗马数字，或用析出文献保留原刊页码，都会造成整体偏移）；锚点仍用物理页序，可用页码映射声明两者的对应关系"]

偏移不止一套时提示「多套偏移」，需要逐页核对。两者一致（偏移全为 0）或一页都没识别到时不提示；自检只读不写，锚点本身不受影响。

不带 pageRanges 时按请求顺序从第 1 页起编号。使用倒数页码范围（如 "2--2"）时云端不会给出文档总页数，锚点会退化为「按你请求的第一个页码起算」，并在结果里明确提示需要人工核对。

长 PDF 自动分片：当一次精准解析请求会要超过 200 页时（整份工作区 PDF 超过 200 页，或 pageRanges 选出的页数超过 200 页），插件自动按顺序切成若干 page_ranges 分片，逐片提交与轮询，最后合并成与单次请求一致的产物布局。不需要新参数，也不在本地拆 PDF：同一份文件只上传一次，每次只改请求的页码范围。

- full.md：按页序拼接，每片前有一行 注释；
- content_list.json：合并结果，page_idx 已映射回原文档页码（云端对每次请求的子集都会从 0 重新编号）；
- images/：所有分片图片的并集（按内容哈希命名，不会冲突）；
- layout.json / <uuid>_model.json：按页数组组织，合并会破坏结构，按片保留在 chunks/chunk-<n>/ 下；
- run.json：分片记录（每片的页码范围、batchId、状态、耗时）；工具返回值里的 chunkCount / chunks 是同一份清单。

边界：分片需要本地知道页数，所以只对精准解析模式下的工作区 PDF 生效。URL 源、非 PDF 格式（本地读不出 docx/pptx 的页数）与免 Token 的 Agent 轻量解析 API 保持原有行为——它们撞到页数上限时，错误信息会说明为什么没有自动分片。Agent 轻量解析 API 按 IP 限流，故意不做自动分片：一次调用被拆成十几片会把额度打爆，请改用精准解析或自行分段。timeoutMs 对每片分别生效。只有多片合并的结果才归一页码；单次请求（含显式传 pageRanges）保持云端原样，与既有行为一致。

mineru_batch_parse —— 批量解析（仅精准解析）

一次解析多个文档，本地文件路径与 URL 可混用，自动分批提交（官方限额内），逐项报告成功/失败。

| 参数 | 必填 | 说明 |
| sources | ✅ | 文件路径 / URL 混合列表 |
| outputPrefix | | 结果目录基名，默认 batch |
| dataIdPrefix | | 业务数据 ID 前缀，每项自动追加序号（可选） |
| anchor | | 同 mineru_parse：为每个文档各写一份 document.md（默认 false） |
| 其余 | | 同 mineru_parse 的公共选项（mode 除外——本工具强制精准解析） |

分批规则：本地文件每批 ≤ 50 个、URL 每批 ≤ 200 个、单次调用总共 ≤ 1000 个；超出会报错并提示拆分调用。

返回要点：成功/失败计数、各 batchId、逐项结果（每个成功项包含其 full.md 所在目录），失败项附错误信息。

mineru_task —— 任务查询与结果收集

解析超时后不丢任务：凭 mineru_parse 返回的 taskId + api 继续查询进度、收集结果，无需重新提交。

| 参数 | 必填 | 说明 |
| taskId | ✅ | 提交任务时返回的 task_id |
| api | ✅ | 任务所属：precision 或 agent |
| wait | | 是否轮询等待任务完成，默认 false（只查一次） |
| collect | | 任务完成时是否下载结果落地为 Artifact，默认 true |
| output | | 收集结果目录基名，默认 task |
| anchor | | 收集结果时是否额外写一份 document.md（默认 false） |
| timeoutMs | | wait 模式下的超时 |

典型场景：解析大 PDF 时 mineru_parse 超时了 → 告诉 Agent「用 mineru_task 继续收集 taskId=xxx 的结果」。

mineru-tools 技能

插件自带同名技能：会话中输入 /mineru-tools 或让 Agent 调用 skill 工具加载，即可获得工具清单、双 API 对比、使用要点与官方限制的完整说明（Agent 视角的使用手册）。

解析结果与 Artifacts

所有解析结果写入 <workspace>/.dsh-mineru/artifacts/<run>/（<workspace> 为当前会话工作区，<run> 为每次解析的独立目录）：

.dsh-mineru/artifacts/<run>/
├── full.md # 结构化 Markdown 主结果（两模式都有） ├── run.json # 本次解析元数据（来源、API、模型、耗时等） ├── document.md # 页级块锚点 Markdown（仅精准解析 + anchor: true） ├── _content_list.json # 内容结构化清单（仅精准解析） ├── layout.json # 版面布局数据（仅精准解析） ├── _model.json # 模型原始输出（仅精准解析） ├── _origin.pdf # 服务端转换的原始文件（仅精准解析） ├── images/ # 文档内嵌图片（仅精准解析） └── result.zip # 服务端原始结果包（仅精准解析）

- 工具结果里附限长 Markdown 预览（默认前 12 KB），完整内容请用 read 工具读取 full.md；
- document.md 是可选增量（anchor: true 才产出）：full.md、content_list.json、layout.json 的形态与现在完全一致，不用 anchor 的用户感知不到任何变化；
- Web 界面：Artifact 带 HMAC 签名预览链接（默认有效期 24 小时），点开即可看/下载；工具结果卡片可直接打开文件；
- Headless：直接使用返回的绝对路径。

批量解析时每个文档在独立子目录：<run>/<文件名>/full.md。

配置参考

配置分三层解析：schema 默认值 ← 组合层（profile patch 中的 mineru 行 config）← 用户设置（Web 设置卡片写入），后一层覆盖前一层。

组合层配置示例（cordis.patch.yml 或 profile patch）
- id: mineru
config:
mode: auto # auto | precision | agent
modelVersion: vlm # pipeline | vlm | MinerU-HTML
language: ch # 文档语言包 enableTable: true # 表格识别 enableFormula: true # 公式识别 isOcr: false # 强制 OCR
extraFormats: [] # docx | html | latex（仅精准解析）
exposeMode: progressive # progressive: 引导激活; always: 全局注册全部工具 timeoutMs: 600000 # 整体超时（毫秒） pollIntervalMs: 3000 # 结果轮询间隔（毫秒） inlineMarkdownBytes: 12000 # 工具结果内联预览字节数 submitRatePerMin: 40 # 提交限速（次/分钟） pollRatePerMin: 900 # 查询限速（次/分钟） dailySubmitLimit: 5000 # 每日提交限额 artifactRootName: .dsh-mineru # Artifact 根目录名

完整配置项

| 配置项 | 默认值 | 说明 |
| mode | auto | API 模式：auto（按 Token 自动）/ precision / agent |
| modelVersion | vlm | 精准解析模型：pipeline / vlm / MinerU-HTML（HTML 源自动强制） |
| language | ch | 文档语言包（见下表） |
| enableTable | true | 表格识别开关 |
| enableFormula | true | 公式识别开关 |
| isOcr | false | 强制 OCR（扫描件） |
| extraFormats | [] | 额外导出格式（仅精准解析）：docx / html / latex |
| exposeMode | progressive | progressive：引导激活；always：全局注册全部工具 |
| timeoutMs | 600000 | 整个操作（含轮询）超时，范围 10 s ~ 1 h |
| pollIntervalMs | 3000 | 结果轮询间隔，范围 500 ~ 60000 ms |
| pollJitterMs | 500 | 轮询随机抖动，避免请求整齐划一 |
| maxFileBytes | 0 | 本地文件大小上限；0 = 按 API 模式限额（200 MB / 10 MB） |
| inlineMarkdownBytes | 12000 | 工具结果内联的 Markdown 预览字节数 |
| artifactUrlTtlSec | 86400 | 签名预览链接有效期（秒），范围 60 s ~ 30 天 |
| submitRatePerMin | 40 | 提交限速（官方上限 50/分钟） |
| pollRatePerMin | 900 | 查询限速（官方上限 1000/分钟） |
| dailySubmitLimit | 5000 | 每日提交限额（官方上限 5000/天） |
| tokenCredential | MINERU_API_TOKEN | DSH 凭据引用名（只存引用，不存密钥） |
| apiBaseUrl | https://mineru.net | MinerU API 地址 |
| artifactRootName | .dsh-mineru | Artifact 根目录名（单层目录名） |
| userAgent | dsh-mineru/<版本> | 请求 User-Agent |

Token 与凭据

配置中只保存凭据引用名（默认 MINERU_API_TOKEN），Token 值存放在 dsh 凭据层，三种方式任选：

1. Web 设置卡片：Token 输入框只写不读——留空保留现有值，点「清除」删除；
2. Headless / 命令行：$DSH_HOME/.credentials.yaml 写入 MINERU_API_TOKEN: <token>；
3. 环境变量：设置 MINERU_API_TOKEN。

Token 每次操作实时解析——轮换后下一次调用立即生效，无需重启。日志、错误与设置响应永不携带密钥。

language 取值

| 值 | 说明 | 值 | 说明 |
| ch | 中英（默认） | ch_server | 中文（服务端） |
| en | 英文 | japan | 日文 |
| korean | 韩文 | chinese_cht | 繁体中文 |
| latin | 拉丁语系 | arabic | 阿拉伯语 |
| cyrillic | 西里尔语系 | east_slavic | 东斯拉夫语系 |
| devanagari | 天城文 | th | 泰文 |
| ta | 泰米尔文 | te | 泰卢固文 |
| ka | 格鲁吉亚文 | el | 希腊文 |

使用技巧

- 拖拽上传：把文件拖进聊天窗口即可——文件自动保存到会话工作区，路径填入输入框草稿（不自动发送），你补一句需求再发送。这绕开了纯文本模型不支持的图片附件通道；
- URL 注意：MinerU 服务端会去抓取该 URL——无法访问被墙站点（如 github.com、aws 等）。这类文档请先下载到本地再传路径；
- 页码范围：精准解析用 pageRanges（"2,4-6"，"2--2" 表示倒数第 2 页）；Agent 用 pageRange（"1-10"）。工作区 PDF 单次请求超过 200 页时会自动分片；
- 长文档：精准解析模式下工作区 PDF 超过 200 页会自动分片并合并，不必手工分段；也可以传 pageRanges 只解析一部分。vlm 模型对公式/复杂版面效果最好；
- 超时恢复：解析超时不等于失败——任务还在服务端跑，用 mineru_task + taskId 继续收集；
- HTML 文档：仅精准解析支持，且自动强制 MinerU-HTML 模型（无需手动指定）；
- HTML 文件每日限额：官方对 HTML 提交有单独限制（最多 100 个/天）。

Web 界面

- 设置 → 插件 → MinerU 解析：Token（只写）、模式、模型、语言、表格/公式/OCR 开关、额外导出格式，以及可折叠的高级设置（超时/轮询/限速/限额、API 地址、凭据引用名、Artifact 根目录名）。每个操作都有即时反馈（忙碌状态与结果消息）；保存带修订冲突检测（409 冲突 → 重新加载后重试）；
- 测试按钮：「测试 Token」提交官方一页示例 PDF 验证密钥（约消耗 1 页额度）；「测试 Agent API」验证免登录通道（受 IP 限频）；
- 工具卡片：三个解析工具的结果以专属卡片呈现——模式徽章、耗时、任务 ID、Artifact 列表（点击打开 / 链接预览）、限长预览、逐项批量结果。

限流与可靠性

MinerU 官方限流（插件已内置本地限速与退避，超限的请求会被服务端以 HTTP 429 拒绝）：

| 维度 | 官方限额 | 插件本地默认 |
| 提交 | 50 个文件/分钟 | 40 个/分钟 |
| 每日提交 | 5000 个文件/天/用户（HTML 最多 100 个/天） | 5000（本地提前报错） |
| 结果查询 | 1000 次/分钟 | 900 次/分钟 |

插件行为：

- 内置令牌桶限速（提交/查询分开），超限的本地请求排队而不是打爆 API；
- 命中 HTTP 429 时按 Retry-After 退避自动重试；
- 轮询带随机抖动（pollJitterMs），避免请求整齐划一触发风控；
- 整体超时（timeoutMs）后任务不丢——用 mineru_task 凭 taskId 继续收集。

错误码速查

| 错误码 | 含义 | 处理方式 |
| A0202 / A0211 | Token 错误 / 过期 | 在设置中更新 MinerU Token |
| -60005 / -30001 | 文件超限（200 MB / 10 MB） | 压缩或拆分文件 |
| -60006 / -30003 | 页数超限（200 页 / 20 页） | 工作区 PDF 会自动分片；其它来源的错误信息会说明未自动分片的原因——用 pageRanges / pageRange 手动分段 |
| -60018 | 当日配额已满 | 明天再试，或检查 dailySubmitLimit |
| 429 | 请求过于频繁 | 稍后重试或降低并发 |
| MINERU_TOKEN_REQUIRED | 需要 Token 的操作未配 Token | 配置 Token 或改用 Agent 模式 |
| MINERU_UNSUPPORTED_TYPE | 该格式不被当前 API 支持 | 换格式或换 API 模式 |
| MINERU_BATCH_TOO_LARGE | 单次批量超过 1000 个 | 拆分后多次调用 |

所有错误都会映射为可操作的中文提示，而不是原始错误码。

安全模型

数据流向（内容去了哪里）

本插件不是离线工具。 两种 API 模式都会把完整源文件发送到 MinerU 远端服务，再把解析结果下载回本机——本地不做任何解析。

| 操作 | 是否出网 | 端点 | Token |
| 精准解析 / 批量 / task 收集 | 是——上传文件、下载结果 zip | https://mineru.net（结果 CDN：https://cdn-mineru.openxlab.org.cn） | 必需 |
| Agent 轻量解析 | 是——上传文件、下载 Markdown | MinerU Agent API | 无需（IP 限频） |
| 激活 / 设置 / 本地预览 | 文件内容不出网（仅 Token 自检会发起一次已认证 API 调用） | — | — |

不存在"仅本地"模式：MinerU 在服务端运行。不得出网的材料请使用完全本地的处理链（本地转 PDF + 离线 OCR + 本地模板渲染）。

- 路径隔离：输入路径以会话工作区为根解析，不能读取工作区外文件；
- ZIP 解包防护：拒绝绝对路径、.. 穿越、加密条目与 ZIP64，带条目数量/体积上限，每个解出的条目都校验 CRC32；
- Artifact 边界：只写入 <workspace>/.dsh-mineru；预览 URL 为 HMAC 签名 + 过期时间，每次读取重新校验；
- Web 路由：仅接受同源请求；HTML/SVG 等 Artifact 以附件方式下发（nosniff）；
- 可取消：所有网络请求响应工具取消信号——会话取消/超时会立即停止上传、轮询与下载；
- 密钥不出库：Token 只存在于凭据层，日志/错误/设置响应永不携带。

常见问题 FAQ

Q：不配 Token 能用吗？ 能。自动走 Agent 轻量解析 API（≤10 MB、≤20 页、仅 Markdown、免登录），适合快速粗读。

Q：为什么工具列表里只有 mineru_activate？ 这是渐进式曝光设计。调用一次 mineru_activate，其余三个工具立即解锁；或者把配置项 exposeMode 改为 always 全局注册。

Q：解析超时了，文件会不会丢？ 不会。任务在 MinerU 服务端继续执行，用 mineru_task（taskId + api）随时查询进度并收集结果，无需重新提交。

Q：拖拽文件后为什么没有自动解析？ 拖拽只把文件路径填入输入框草稿（防误发送），需要你补充需求后手动发送，Agent 才会开始解析。

Q：报错 A0202 / A0211 怎么办？ Token 无效或过期。在「设置 → 插件 → MinerU 解析」重新填写 Token（留空再点保存不会覆盖旧值）。

Q：HTML 网页能解析吗？ 能，但仅精准解析 API 支持（需 Token），且自动使用 MinerU-HTML 模型。注意服务端抓不到被墙的 URL。

Q：怎么批量解析？ 用 mineru_batch_parse，把文件路径/URL 列成列表即可，自动分批（本地 ≤50/批、URL ≤200/批、单次 ≤1000）。

Q：Agent 轻量解析和精准解析结果有什么差别？ 轻量解析只出 Markdown；精准解析额外产出 content_list.json、layout.json、model.json、内嵌图片，还可加导出 docx/html/latex，且支持表格/公式识别参数。

开发与发布

本包无构建步骤：lib/ 为可直接加载的 ESM，lib/client.js 为打包形态的浏览器 bundle。

node --check lib/.js # 语法检查
npm pack # 打包本地 tgz

新版本发布请严格按 RELEASE.md 清单执行（升版本号 → 更新 CHANGELOG 与双语 README → 打包验证 → 打 tag 推送 → npm publish），完整开发循环见 CONTRIBUTING.md。

贡献

欢迎 Issue 与 PR，见 CONTRIBUTING.md。报告问题时请勿粘贴 MinerU Token。

许可

MIT。MinerU 由 OpenDataLab 提供，其官方文档（API 文档、限流策略）为权威依据。