yakoylp/dsh-md-convert

dsh-md-convert

将 Office 文档与 PDF(含扫描件)转换为保留结构级排版的 Markdown,基于 MarkItDown 引擎。提供 CLI 命令行与 dsh agent 工具(md_convert)双入口。

• AI Agent 使用规范:README.agent.md(错误码处理/批量规范/调用约定)
• English: README.en.md

支持格式与转换链路

"结构级排版" = 标题层级(H1–H6)、列表、表格(管道表格)、段落顺序均保留。 Markdown 本身无法表达字体/字号/颜色/缩进等视觉细节,任何转换器都不会保留它们——这是格式本质。

环境依赖

• Node.js ≥ 18
• 老格式转换(.doc/.xls/.ppt):Windows 需本机装有 WPS Office 或 Microsoft Office(COM 自动探测);Linux/macOS 需 LibreOffice(apt install libreoffice,自动探测 soffice)
• 扫描件 OCR 以 CPU 为主、轻量模型优先、性价比优先:模块化路由流水线——PP-DocLayout-L 版面分析(轻量)按区域路由,文字走 RapidOCR(PP-OCRv6 ONNX,最快),表格走 SLANet+RT-DETR,公式走 FormulaNet-Plus-S(轻量);标题层级由版面模型识别。质量有基本保证,但为效率做了取舍(如复杂版面/超小字号可能识别不全)
• Linux 无头服务器建议安装中文字体 fonts-noto-cjk
• 模型本地化:OCR 模型首次经 dsh-md-convert deps 联网下载到本地缓存(~/.paddlex/official_models/,约数百 MB);之后运行完全离线,不做任何网络检查,断网可正常 OCR

依赖自动安装(默认开启):首次转换扫描件时,插件自动检测 Python 与 OCR 依赖 (paddlepaddle paddleocr paddlex[ocr] pypdfium2 rapidocr onnxruntime), 有则直接使用,缺则自动 pip install,无需手动操作。可用 --no-auto-install-deps 关闭,或手动预装:

pip install paddlepaddle paddleocr "paddlex[ocr]" pypdfium2 rapidocr onnxruntime

路由 OCR = PP-DocLayout-L 版面分析(阈值 0.3)+ 区域路由:文字→RapidOCR、 表格→SLANet 结构+RT-DETR 单元格+OCR 填格、公式→FormulaNet-S、印章→注释。

安装

作为 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)

git clone https://github.com/yakoylp/dsh-md-convert.git
cd dsh-md-convert
npm install
npm link          # 全局获得 dsh-md-convert 命令
# 或直接调用
node lib/cli.js <文件...> -o <输出目录>

命令行用法

# 基本:批量转换
dsh-md-convert a.docx b.pdf -o ./md

# 老格式(自动探测:Windows 用 WPS→Office,Linux/macOS 用 LibreOffice)
dsh-md-convert old.doc old.xls old.ppt -o ./md

# 强制指定老格式后端
dsh-md-convert old.doc -o ./md --legacy-backend wps

# 扫描件:自动走路由 OCR(无需任何 OCR 参数;缺依赖自动安装)
dsh-md-convert scan.pdf -o ./md

# 指定 Python 解释器(多 Python 环境时)
dsh-md-convert scan.pdf -o ./md --ocr-python "C:\path\to\python.exe"

# 检查 / 安装 OCR 依赖与模型
dsh-md-convert check        # 只检查状态,不安装
dsh-md-convert deps         # 安装缺失依赖并预下载 OCR 模型到本地(需联网一次,之后离线可用)

完整选项见 dsh-md-convert --help。

错误码与退出码

失败时必定携带稳定错误码,调用方(CLI / agent / 二次开发)可据此分类处理:

CLI 输出格式(批量时每行可定位到具体文件):

✓ markitdown  → ./md/a.md
✗ [E_OCR_EMPTY] 扫描件未识别出任何内容  C:\docs\扫描件.pdf
✗ [E_FILE_NOT_FOUND] 文件不存在:...  C:\docs\缺失.docx

退出码:0 全部成功 / 1 存在失败(失败行含 [错误码] 与源文件路径)/ 2 参数错误。

Agent 工具

安装插件后,agent 可用 md_convert 工具:

md_convert({ file: "报告.docx", outDir: "./md" })
→ { ok: true, output: "./md/报告.md", chain: "markitdown", warnings: [] }

插件配置(cordis.patch.yml):

- insert:
    - id: dsh-md-convert
      name: dsh-md-convert
      config:
        outDir: ""            # 输出目录;空则用会话工作区
        forceOcr: false       # 强制 PDF 走 OCR
        ocrScale: 2           # PDF 渲染倍率
        autoInstallDeps: true # 缺 OCR 依赖时自动 pip 安装
        ocr:
          python: ""          # Python 解释器(运行 OCR 流水线;空则自动探测)
        legacy:
          backend: "auto"     # auto | wps | office | libreoffice(auto:Windows 用 COM,其余平台用 LibreOffice)
        markitdown:
          mode: "worker"      # worker(默认,子进程执行)| in-process(仅诊断;DSH 宿主内会失败)
          node: ""            # 运行 worker 的解释器;空则自动探测
          timeoutMs: 0        # worker 超时毫秒;0 = 不超时

markitdown 执行方式(默认子进程)

.docx/.xlsx/.pptx 与 PDF 文字层由 MarkItDown 直转,这一步默认在子进程中执行:

• 子进程用 process.execPath 启动;在 Electron 宿主(官方桌面版)里自动追加 ELECTRON_RUN_AS_NODE=1,让同一二进制以纯 Node 方式运行 worker
• 可用 markitdown.node 或环境变量 DSH_MD_CONVERT_NODE 指定解释器
• worker 把结果写入临时 JSON 文件再由父进程读取,因此 markitdown/jsdom 的偶发 stdout 输出不会污染结果;失败统一映射为 E_MARKITDOWN(消息内带退出码与 stderr 尾部)

为什么默认子进程:DSH 宿主会给 profile 内模块安装「插件依赖路由层」,它把 pkg/ 形式的模块请求剥成包名后调用 require.resolve.paths(包名);若剥出的名字正好是 Node 内置模块名,该调用返回 null,随后的 for...of 抛 TypeError。MarkItDown 顶层依赖 jsdom,而 jsdom → whatwg-url → tr46 链上有一句 require("punycode/")(为取 npm 版 punycode,而非已废弃的内置模块),正好命中该缺陷,导致在宿主进程内加载 MarkItDown 必然失败。 独立子进程没有这层路由,按 Node 原生规则解析。副作用是好的:jsdom/sharp 等重依赖的加载 与内存开销不再留在长驻宿主进程里。

mode: "in-process" 保留作诊断与「无法 spawn 子进程」的环境的逃生口;在 DSH 0.2.0-rc.2 宿主内它仍会失败,不要用来规避上述缺陷。

老格式转换后端

.doc/.xls/.ppt 先另存为现代格式再交给 MarkItDown。后端自动按平台选择:

可用 --legacy-backend wps | office | libreoffice 显式指定(如 Windows 无 WPS/Office 但装了 LibreOffice,可强制 --legacy-backend libreoffice)。

临时文件清理

• 每次转换使用独立临时目录(%TEMP%/dsh-md-convert-*),结束即删除
• 进程异常退出时,exit/信号钩子兜底清理,下次运行自动清扫历史残留
• OCR 无中间文件(Python 侧内存完成);调试可用 --keep-temp 保留

测试

npm test                       # 单元测试(后端分流、LibreOffice mock)
node test/run-smoke.mjs        # 7 格式冒烟(Windows 需 WPS/Office;Linux 需 LibreOffice)
node test/run-smoke.mjs --all --reference   # 全量 8 格式(含扫描件 OCR),并把参考输出写入 test/fixtures/final-out/

已知问题

• paddlepaddle ≥3.3 的 oneDNN 与 PIR 静态图不兼容会导致推理崩溃,插件已自动禁用 (FLAGS_use_mkldnn=0 + enable_mkldnn=False),无需手动处理。
• DSH 宿主插件依赖路由层缺陷(影响 dsh 0.2.0-rc.2):宿主解析 profile 内模块的 pkg/ 请求时会剥成包名再调 require.resolve.paths(),剥出的名字若是 Node 内置模块名 (如 require("punycode/") → punycode)则返回 null 并抛 TypeError。插件已通过 「markitdown 走子进程」规避(见上文);同源缺陷会影响任何依赖树里含 jsdom (→ whatwg-url → tr46)的插件,值得向 DSH 侧反馈。
• 扫描件 OCR 质量取决于版面清晰度;复杂版面/超小字号页面可适当提高 --ocr-scale(如 3)换取精度,耗时相应增加。

限制

• 加密/损坏文件、部分复杂版面可能转换失败(会给出明确错误)
• MarkItDown 不支持的格式(如 .pages/.key 等)会明确报"不支持"
• 效率优先的取舍:路由 OCR 选用轻量模型(版面 PP-DocLayout-L、文字 RapidOCR、公式 FormulaNet-S),速度优先, 质量有基本保证;复杂表格(多层合并/斜线表头)、复杂多栏版面、超小字号可能存在识别不完整
• OCR 模型首次需联网预下载(约数百 MB 到 ~/.paddlex/),之后完全离线、秒级加载

许可证

MIT © 2026 yakoylp