前言¶
在 DeepSeek Harness (DSH) 插件生態中，將 Office 文檔或 PDF 轉換爲 Markdown 是一個高頻需求。已有的方案中，外部服務存在隱私風險，本地轉換則往往難以兼顧排版保留與掃描件識別。dsh-md-convert 插件基於 Microsoft 的 MarkItDown 引擎，提供了一套在本地運行的解決方案，支持包含 OCR 在內的多種轉換鏈路。
插件簡介¶
該插件由用戶 yakoylp 維護，開源協議爲 MIT。它旨在將 Office 文檔（.doc/.docx/.xls/.xlsx/.ppt/.pptx）及 PDF（含文字層和掃描件）轉換爲保留結構級排版的 Markdown。插件提供 CLI 命令行與 DSH Agent 工具兩種使用方式。
核心功能¶
插件的核心轉換邏輯根據輸入格式自動路由：
1. 現代格式直轉：.docx, .xlsx, .pptx 及 PDF 文字層直接通過 MarkItDown 引擎處理，保留標題層級、列表、表格和段落順序。
2. 老格式轉換：.doc, .xls, .ppt 需先通過後端（WPS/Office 或 LibreOffice）另存爲新格式，再轉 Markdown。插件會自動探測後端，也可手動指定。
3. 掃描件 OCR：對於無文字層的 PDF 掃描件，插件使用輕量級 CPU 模型路由流水線進行識別。路由流程包括：PP-DocLayout-L 版面分析、RapidOCR 文字識別、SLANet 表格結構提取、FormulaNet 公式識別。
安裝與啓用¶
在 DSH 環境中安裝該插件：
dsh plugin --profile web add github:yakoylp/dsh-md-convert
安裝後，重啓 dsh web 服務，Agent 即可使用 md_convert 工具，CLI 命令 dsh-md-convert 也會在 profile 的 node_modules/.bin 中可用。
命令行使用¶
插件提供 dsh-md-convert 命令，支持批量處理與依賴檢查。
- 批量轉換
dsh-md-convert a.docx b.pdf -o ./md
- 處理老格式
dsh-md-convert old.doc old.xls old.ppt -o ./md
- 強制指定老格式後端
dsh-md-convert old.doc -o ./md --legacy-backend wps
- 處理掃描件
dsh-md-convert scan.pdf -o ./md
- 檢查依賴與模型
dsh-md-convert deps
首次運行掃描件轉換時，插件會自動下載 OCR 模型到 ~/.paddlex/，之後完全離線可用。
Agent 工具使用¶
安裝插件後，Agent 可直接調用 md_convert 工具：
md_convert({ file: "報告.docx", outDir: "./md" })
插件配置文件 cordis.patch.yml 定義了工具的行爲，包括輸出目錄、是否強制 OCR、OCR 縮放比例以及後端選擇等參數。
注意事項¶
- 環境依賴：在 Linux 無頭服務器上運行時，建議安裝中文字體
fonts-noto-cjk。Windows 老格式轉換需要本機安裝 WPS 或 Office；Linux/macOS 需安裝 LibreOffice。 - 依賴自動安裝：默認開啓依賴自動安裝，首次轉換掃描件時會自動安裝
paddlepaddle、paddleocr等依賴。若需手動控制，可使用--no-auto-install-deps。 - PaddlePaddle 版本：PaddlePaddle >= 3.3 版本需禁用 oneDNN 以避免崩潰，插件已自動處理此問題。
- 錯誤碼：CLI 與 Agent 返回穩定的錯誤碼（0/1/2），調用方可據此判斷轉換結果。
- 侷限性：由於 Markdown 本身無法表達字體/字號/顏色，轉換過程會丟失這些視覺細節。此外，複雜版面或超小字號可能存在識別不全的情況。
總結¶
dsh-md-convert 插件通過 MarkItDown 引擎和本地 OCR 路由，爲 DSH 提供了輕量級、可離線的文檔轉 Markdown 能力。適合需要處理大量文檔且注重隱私與結構保留的場景。
- 官方目錄：https://www.skillhub.cn/plugins/yakoylp/dsh-md-convert
- 源碼地址：https://github.com/yakoylp/dsh-md-convert
