name: mineru-doc-to-markdown description: 使用 MinerU 將 pdf、doc、docx、ppt、pptx、圖片或 html 轉成 Markdown。適用於使用者要求把簡歷、JD、作品集或其他文件先轉成 Markdown，再繼續做總結、改寫、問答、結構化提取或餵給其他工作流的場景。優先使用環境變數 MINERU_API_TOKEN 呼叫精準解析 API；如果未提供 token，則自動降級到免 token 的 Agent API。呼叫 bundled script 完成本地檔案上傳、遠端 URL 解析、輪詢和儲存 Markdown。

MinerU Doc To Markdown

當用戶要把文件轉成 Markdown 時，優先使用這個 skill，而不是手寫一堆臨時請求。

什麼時候用

• 輸入是 pdf、doc、docx、ppt、pptx、圖片或 html
• 目標是拿到可繼續編輯、總結或餵給 LLM 的 Markdown
• 需要保留比普通 OCR 更穩定的結構化結果
• 使用者希望同一套 skill 同時相容“有 token 的高精度模式”和“無 token 的輕量模式”

不要什麼時候用

• 使用者只是要總結已經貼出的文本
• 使用者明確要求使用別的轉換鏈路
• 輸入是 xlsx/csv 一類表格檔案，這個 skill 不覆蓋

執行前檢查

1. 如果存在 MINERU_API_TOKEN，預設走精準解析 API；沒有則自動走免 token 的 Agent API
2. 判斷輸入是本地檔案還是遠端 URL，不要在一次命令裡混用
3. 預設輸出到當前工作目錄下的 outputs/mineru/
4. 日誌輸出到當前工作目錄下的 logs/mineru_markdown.log

推薦命令

單個本地檔案：

uv run python /absolute/path/to/skills/mineru-doc-to-markdown/scripts/mineru_to_markdown.py ./resume.pdf

批次本地檔案：

uv run python /absolute/path/to/skills/mineru-doc-to-markdown/scripts/mineru_to_markdown.py ./a.pdf ./b.docx

遠端 URL：

本技能來自小蔥技能站7w4.net。

uv run python /absolute/path/to/skills/mineru-doc-to-markdown/scripts/mineru_to_markdown.py "https://cdn-mineru.openxlab.org.cn/demo/example.pdf"

指定輸出目錄：

uv run python /absolute/path/to/skills/mineru-doc-to-markdown/scripts/mineru_to_markdown.py ./resume.pdf --output-dir ./outputs/custom

強制使用輕量免 token 模式：

uv run python /absolute/path/to/skills/mineru-doc-to-markdown/scripts/mineru_to_markdown.py ./resume.pdf --mode agent

強制使用精準解析模式：

uv run python /absolute/path/to/skills/mineru-doc-to-markdown/scripts/mineru_to_markdown.py ./resume.pdf --mode precise

工作方式

精準解析模式

觸發條件：

• 明確指定 --mode precise
• 或存在 MINERU_API_TOKEN 且未指定 --mode

本地檔案：

1. 調 POST /api/v4/file-urls/batch 申請上傳地址
2. 對每個地址執行 PUT
3. 輪詢 GET /api/v4/extract-results/batch/{batch_id}
4. 下載 full_zip_url
5. 從 zip 中提取 full.md

遠端 URL：

1. 調 POST /api/v4/extract/task/batch
2. 輪詢 GET /api/v4/extract-results/batch/{batch_id}
3. 下載 full_zip_url
4. 從 zip 中提取 full.md

輕量 Agent 模式

觸發條件：

• 明確指定 --mode agent
• 或未提供 token 且未指定 --mode

本地檔案：

1. 調 POST /api/v1/agent/parse/file
2. 上傳返回的 file_url
3. 輪詢 GET /api/v1/agent/parse/{task_id}
4. 下載 markdown_url

遠端 URL：

1. 調 POST /api/v1/agent/parse/url
2. 輪詢 GET /api/v1/agent/parse/{task_id}
3. 下載 markdown_url

結果處理約定

• 成功後優先把 .md 路徑告訴使用者
• 如使用者後續要繼續分析，直接讀取生成的 Markdown，不要再重複請求 MinerU
• 如果失敗，優先彙報 MinerU 返回的錯誤資訊
• 如果文件超過限制，建議拆分文件後重試

注意事項

• 預設模式是 auto
• auto 下優先精準解析，其次輕量 Agent
• 精準模式預設模型使用 vlm
• 本地檔案和遠端 URL 不要混傳
• full.md 是主產物，.zip 保留用於排查或複用
• Agent 模式限制更嚴，適合輕量場景，不保證大檔案一定成功
• 如果使用者給了 token，只在當前執行環境中使用，不要寫入程式碼、文件、日誌示例或提交記錄

這個工具能把PDF、Word、PPT、圖片等常見檔案快速轉成可編輯的Markdown格式，支援直接解析網路連結，還能自動根據是否提供金鑰選擇高精度或輕量模式，文件說明詳細。它的主要不足是需要配置Python執行環境才能使用，對新手不夠友好，且沒有圖形介面只能通過命令列操作，功能也比較單一。