前言¶
在 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
