前言¶
DeepSeek Harness（簡稱 dsh）把模型、工具、會話和界面都做成可插拔插件。智能體寫代碼、改配置時很順手，但一遇到掃描版 PDF、帶公式的論文、PPT 講義和 Excel 表格，純文本循環就卡住了：模型看不見版面，普通抽取又容易把多欄、頁眉頁腳和表格拆亂。
OpenDataLab 的 MinerU 專門做這件事：把 PDF、圖片、DOCX、PPTX、XLSX 轉成適合大模型繼續處理的 Markdown / JSON。它本身是獨立的解析引擎，帶 CLI、WebUI 和 FastAPI，並不會自動出現在 dsh 的工具列表裏。
dsh-plugin-mineru 補的是這一段：在 Harness 裏註冊一組面向模型的工具，把已經跑起來的 MinerU HTTP 服務接到智能體循環中。本文按社區目錄頁、GitHub 倉庫 README / 源碼、npm 包說明，以及 MinerU、DeepSeek Harness 官方資料覈對後整理。
這是什麼¶
dsh-plugin-mineru 是一款 工具與能力 類 DeepSeek Harness 插件，由 HuanLinOTO 維護，倉庫在 HuanLinOTO/dsh-plugin-mineru。插件內部名稱是 dsh-mineru，npm 包名爲 @huanlin/dsh-plugin-mineru，當前發佈版本是 0.2.2（2026-08-14），主要語言是 TypeScript，要求 Node.js 18 及以上。截至 2026-08-17，GitHub 顯示 30 星；社區目錄頁收錄時顯示 18 星，以倉庫頁面爲準。
它解決的問題很具體：讓 dsh 裏的模型能調用 MinerU，把本地文檔解析成結構化 Markdown，完整 JSON 結果另存文件，而不是讓模型自己猜 PDF 裏的字。
需要分清三層關係：
- DeepSeek Harness 是 DeepSeek 開源的智能體運行時，官方口號是「Everything is a Plugin」，倉庫在 deepseek-ai/deepseek-harness。
- MinerU 是 OpenDataLab 的文檔解析引擎，倉庫在 opendatalab/MinerU。官方說明支持 PDF、圖片、DOCX、PPTX、XLSX，輸出 Markdown / JSON，公式轉 LaTeX、表格轉 HTML，並提供
mineru-apiFastAPI。 - 本插件 是社區項目，用
fetch調用 MinerU 的/health、/tasks、/tasks/{id}、/tasks/{id}/result。它不內置解析模型，也不替你部署 MinerU。
社區插件目錄 deepseek-harness-plugin.com 是獨立站點，和 DeepSeek / 幻方沒有官方從屬關係，不要把它當成官方應用商店。目錄頁寫明本插件已同時收錄於 dshfind 插件超市。
許可證以倉庫爲準：package.json 和 LICENSE 標明 AGPL-3.0（版權頁寫 Copyright (C) 2026 Huanlin）。GitHub 許可證探測和目錄頁顯示爲 NOASSERTION，屬於探測未識別，不是第二種許可證。
核心功能¶
插件以 bundle 形式掛載：cordis.patch.yml 插入一行 dsh-mineru，package.json 聲明 dsh.bundle.patch。宿主側註冊 5 個工具，瀏覽器側帶 Web UI 設置頁（dsh.client.platform 爲 web）。配置改動走 RPC，不必重新註冊工具。
對接已部署的 MinerU API¶
客戶端註釋寫明：對接 MinerU FastAPI（開發時針對 v3.4.4、協議 v2）。鑑權是可選的——開源 MinerU 服務默認沒有內置認證；若憑據庫或環境變量裏解析到密鑰，請求會帶 Authorization: Bearer，並且拒絕跟隨重定向。
支持的本地文件，以工具參數和客戶端 MIME 映射爲準：PDF、DOCX、PPTX、XLSX，以及 png / jpg / jpeg / gif / bmp / tiff / webp 等圖片。必須是本機文件系統路徑；如果只有 URL，要先下載到本地再解析。
五個面向模型的工具¶
README 把日常用法收成下面這組工具。
mineru_parse_document（推薦）
高層封裝：提交文件 → 按間隔輪詢 → 返回 Markdown。大多數單次解析用這個即可。可覆蓋後端、解析方法、語言、公式/表格開關、頁碼範圍，以及最長等待時間（默認 10 分鐘）。源碼裏這個工具的執行超時是 900000 毫秒。
mineru_submit_parse_job
異步提交，立刻返回 task_id。適合大文檔，或要並行丟多份文件。工具說明建議：一頁 PDF 大約 1–2 秒，大文檔可能要數分鐘。
mineru_get_parse_status
查詢任務狀態，返回 pending / processing / completed / failed。排隊時可能帶 queued_ahead。
mineru_get_parse_result
取已完成任務的結果。Markdown 內聯返回，超過 maxMdOutputChars（默認 20 萬字符）會截斷，全文寫到臨時文件；完整結構化 JSON 始終寫到 raw_result_path，可用讀文件工具繼續看。
mineru_health
無參數。檢查服務是否健康，以及版本、隊列深度和最大併發，適合批量任務前做一次預檢。
可配置的解析默認值¶
在 DSH GUI 設置頁或 cordis.patch.yml 裏配置，字段以倉庫 README 爲準：
| 字段 | 類型 | 默認值 | 說明 |
|---|---|---|---|
baseURL |
string | 必填 | MinerU API 地址 |
apiKeyEnv |
credential-ref | MINERU_API_KEY |
API key 的環境變量名 / 憑據引用；測試實例可不鑑權 |
defaultBackend |
enum | pipeline |
pipeline / vlm-engine / hybrid-engine / vlm-http-client / hybrid-http-client |
defaultParseMethod |
enum | auto |
auto / txt / ocr |
defaultLang |
string | ch |
pipeline 後端語言代碼 |
pollIntervalMs |
number | 2000 |
異步狀態輪詢間隔 |
pollTimeoutMs |
number | 600000 |
mineru_parse_document 最長輪詢（10 分鐘） |
requestTimeoutMs |
number | 60000 |
單次 HTTP 請求超時 |
maxMdOutputChars |
number | 200000 |
內聯 Markdown 上限，超出則落臨時文件 |
cordis.patch.yml 的首次啓動種子是：
- insert:
- id: dsh-mineru
name: '@huanlin/dsh-plugin-mineru'
config:
baseURL: 'http://localhost:18000'
這只是插件自己的種子值。MinerU 官方文檔裏 mineru-api 的示例端口是 8000（mineru-api --host 0.0.0.0 --port 8000），Docker Compose 的 api profile 也映射 8000。裝完插件後，必須在 GUI 裏把 baseURL 改成你實際部署的地址，不要默認假設 18000 就是 MinerU 在聽的端口。
安裝與啓用¶
目錄頁給出的安裝命令如下，在 DeepSeek Harness 終端運行即可：
dsh plugin add github:HuanLinOTO/dsh-plugin-mineru
需要可復現安裝時，目錄頁寫法是固定 commit 哈希：
dsh plugin add github:HuanLinOTO/dsh-plugin-mineru#commit
把 #commit 換成具體哈希。倉庫 README 當前另外推薦從 npm 安裝，並指定 web profile（設置頁走 Web UI）：
dsh plugin --profile web add @huanlin/dsh-plugin-mineru
npm 上 0.2.2 的 README 仍寫從 git 安裝；GitHub master 在 2026-08-15 有過推送，比 npm 發佈時間更晚，以倉庫 README 和目錄頁爲準即可。
若用 git 安裝且 pnpm ≥ 10，README 要求在對應 profile 的 pnpm-workspace.yaml 裏允許構建：
allowBuilds:
'@huanlin/dsh-plugin-mineru': true
本地開發安裝示例（路徑按你的 checkout 修改）：
dsh plugin --profile web add link:D:\Projects\deepseek-harness\dsh-mineru
目錄頁提醒：插件以當前 dsh 進程的權限運行，安裝時可能執行代碼。安裝前應檢查源碼倉庫和許可證。
啓用前還要有一臺可訪問的 MinerU。官方快速用法是：
mineru-api --host 0.0.0.0 --port 8000
瀏覽器打開 http://127.0.0.1:8000/docs 可看接口文檔。插件不會幫你拉模型、裝 GPU 驅動或選 backend，這些都在 MinerU 一側完成。
典型用法¶
下面按官方工具說明串一條可復現路徑，不額外編對話記錄。
1. 改 baseURL
MinerU 起來之後，在 DSH GUI 的 MinerU 設置裏覆蓋 baseURL。若服務聽在官方示例端口，應類似：
http://127.0.0.1:8000
測試實例通常不用填 API key。若你的網關要鑑權，把密鑰放到 MINERU_API_KEY 對應的環境變量或憑據引用裏。
2. 先探活
讓模型調用 mineru_health。正常時應返回 healthy，以及版本、排隊/處理中任務數和最大併發。批量丟文件前先看容量，避免把隊列打滿。
3. 日常：一條命令走完解析
把本地路徑交給智能體，例如工作區裏的 docs/paper.pdf。模型應調用 mineru_parse_document，必填參數是 file_path。常用可選參數：
backend：默認pipeline（工具說明寫 hallucination-free、多語言）。hybrid-engine需要 VLM；CPU-only 服務應繼續用pipeline。parse_method：auto/txt/ocr（pipeline / hybrid 有效）。lang_list：僅 pipeline 有效，默認['ch']；VLM / hybrid 後端會忽略。formula_enable/table_enable：默認都是 true。start_page_id/end_page_id：PDF 頁碼，從 0 起算；end_page_id默認 99999（表示儘量到末頁），不是「最後一頁」這個語義值。poll_timeout_ms：等不及默認 10 分鐘時再改。
返回值裏的 md_content 就是給模型繼續總結、摘錄、對照代碼的 Markdown。公式、表格的還原質量取決於 MinerU 後端，不取決於這層 HTTP 封裝。
4. 大文件或批量：拆成提交 / 輪詢 / 取結果
流程在 README 和工具描述裏寫得很清楚：
mineru_submit_parse_job提交，拿到task_idmineru_get_parse_status等到completed或failedmineru_get_parse_result取 Markdown；完整 JSON 在raw_result_path
任務在服務端保留約 24 小時，不要把很久以前的 task_id 跨會話反覆用。結果文件名是去掉擴展名後的 stem，提交響應裏的 file_names 纔是可靠的對照。
5. 輸出過大時看臨時文件
內聯 Markdown 默認上限 20 萬字符。超出後工具會把全文寫到臨時目錄（文件名形如 mineru-{taskId}.md），並在返回值裏給出路徑。需要版面中間結果或圖片時，提交階段打開 return_middle_json / return_content_list / return_images；return_images 可能帶出很大的 base64，插件開發說明建議圖片多的文檔優先考慮 zip 響應，而不是把圖全部內聯進上下文。
適用場景與注意事項¶
比較適合這些情況：
- 在 DeepSeek Harness 裏做 RAG、論文閱讀、需求/設計文檔對照，原始材料是 PDF 或 Office 文件
- 掃描件、多欄排版、含公式或表格的文檔，需要先結構化再讓模型處理
- 已經（或準備）自建 MinerU，希望智能體直接調解析，而不是自己寫 curl 輪詢
使用前注意下面幾條，都來自目錄頁、倉庫說明或 MinerU 文檔，不是額外發揮。
- 插件不等於 MinerU。 沒把
mineru-api（或等價 HTTP 入口）跑起來，工具調用會失敗。GPU、模型文件、backend 選擇都在 MinerU 部署側。 baseURL必須對上真實端口。 插件種子是http://localhost:18000，MinerU 官方示例是 8000。改錯地址時，mineru_health會立刻暴露問題。- 只接受本地路徑。 遠程 URL 要先下載。插件以當前 dsh 進程權限讀這些文件，等於進程能讀到的本地內容都可能被送去 MinerU。
- backend 和機器要匹配。
pipeline適合無 VLM 的環境；hybrid-engine需要 VLM。lang_list只對 pipeline 有意義。 - 結果會進模型上下文。 超長 Markdown 雖有截斷，完整 JSON 仍落在臨時文件上。不要把含密鑰、合同原件的目錄隨手丟給解析服務，尤其是
baseURL指向非本機時。 - 許可證是 AGPL-3.0。 修改後通過網絡提供服務時，條款比常見 MIT 插件更嚴，安裝前應自己讀
LICENSE。 - 安全邊界。 目錄頁寫明：插件以當前 dsh 進程權限運行，安裝時可能執行代碼。源碼在 GitHub，安裝前應過一遍。
小結¶
dsh-plugin-mineru 不重新實現一套 PDF 解析，而是把 MinerU 的 FastAPI 接到 DeepSeek Harness 的工具層：日常用 mineru_parse_document，大批量用提交/輪詢/取結果，並用設置頁管理 API 地址。對已經在用 dsh、又需要把文檔變成可被模型消化的 Markdown / JSON 的人來說，缺的往往不是「再寫一段提示詞」，而是這一層穩定的 HTTP 工具。
目錄頁與倉庫：
- 社區目錄：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-plugin-mineru/
- GitHub：https://github.com/HuanLinOTO/dsh-plugin-mineru
- npm：https://www.npmjs.com/package/@huanlin/dsh-plugin-mineru
- MinerU：https://github.com/opendatalab/MinerU
- DeepSeek Harness：https://github.com/deepseek-ai/deepseek-harness
