鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

dsh-md-convert

将 Office 文档与 PDF（含扫描件）转换为保留结构的 Markdown，采用 CPU 优先的路由 OCR 流水线（RapidOCR/SLANet/FormulaNet）。

工作流
访问 GitHub
文档README

dsh-md-convert

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

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

支持格式与转换链路

输入链路说明
.docx / .xlsx / .pptxMarkItDown 直转标题/列表/表格/段落保留为 Markdown
.pdf(含文字层)MarkItDown 直转文字层为空时自动回退路由 OCR
.pdf(扫描件)路由 OCR(PP-DocLayout-L 版面 + RapidOCR 文字 / SLANet 表格 / FormulaNet 公式)标题/正文/表格/公式/印章,纯 CPU、轻量模型
.doc / .xls / .pptWPS/Office COM(Windows)或 LibreOffice(其余平台)另存为新格式 → MarkItDown后端自动探测,可配置
.html/.csv/.json/.xml/.ipynb/.md/.txt/...MarkItDown / 直接读取MarkItDown 支持的全部格式

"结构级排版" = 标题层级(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 关闭,或手动预装:

▼
sh
复制代码
pip install paddlepaddle paddleocr "paddlex[ocr]" pypdfium2 rapidocr onnxruntime

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

安装

作为 DSH 插件

▼
sh
复制代码
dsh plugin --profile web add github:yakoylp/dsh-md-convert

安装后重启 dsh web,agent 获得 md_convert 工具。CLI 命令 dsh-md-convert 随 profile 的 node_modules/.bin 暴露。

独立命令行(不装进 DSH)

▼
sh
复制代码
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 <输出目录>

命令行用法

▼
sh
复制代码
# 基本:批量转换
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 / 二次开发)可据此分类处理:

错误码含义处理
E_FILE_NOT_FOUND源文件不存在检查路径
E_UNSUPPORTED_FORMAT扩展名不受支持更换格式
E_MARKITDOWNMarkItDown 转换失败多为文件损坏/加密,可重试
E_LEGACY_CONVERT老格式另存失败(COM/LibreOffice)Windows 需 WPS/Office、其余平台需 LibreOffice;已内置自动重试
E_OCR_DEPS缺 OCR 依赖(自动安装失败/已禁用)执行 dsh-md-convert deps
E_OCR_RUN路由 OCR 执行失败重试或降低 --ocr-scale
E_OCR_EMPTY扫描件未识别出内容检查扫描质量
E_OUTPUT输出写入失败检查 outDir 权限/磁盘
E_UNKNOWN其他错误查看 error 消息

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

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

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

Agent 工具

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

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

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

▼
yaml
复制代码
- 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)

老格式转换后端

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

平台auto 后端实现
WindowsWPS → MS OfficeCOM(PowerShell 脚本);WPS/Office 正在运行时自动重试(不会杀用户进程)
Linux / macOSLibreOfficesoffice --headless --convert-to,需安装 LibreOffice(自动探测 soffice/libreoffice)

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

临时文件清理

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

测试

▼
sh
复制代码
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),无需手动处理。
  • 扫描件 OCR 质量取决于版面清晰度;复杂版面/超小字号页面可适当提高 --ocr-scale(如 3)换取精度,耗时相应增加。

限制

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

许可证

MIT © 2026 yakoylp

工作流

快捷安装

复制到终端去安装插件

dshplugin--profilewebaddgithub:yakoylp/dsh-md-convert

温馨提示

装插件等于在本机跑第三方代码，权限与你相同，能读文件、用凭据、访问网络，工具审批管不到。请只装可信来源，并尽量锁定 commit。

站长：程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长：程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
零感AI零感AI
墨得问题墨得问题
dsh 插件推荐
DSH-Feedback-Bridge
将 DSH 对话整理为可审阅的社区反馈，并在确认后提交到 DeepSeek Harness 官方 Discussions。
dsh-itranslation#bundle
DeepSeek Harness 整本书翻译生产线：确定性章节识别与分段、子代理逐章翻译、术语表控制、全书审查、定向修订，以及可审计的 meta.json 证据链。
dsh-subagent-pool
为 DeepSeek Harness 维护可复用的命名子代理配置，并按配置的模型、推理强度和 Agent 预设运行子代理。
dsh-plugins#dsh-wx-push
DSH 会话任务结束后自动把结果原文推送到微信（iLink 直发，真实校验送达，失败如实报错）。需配置 wechat-acp 守护进程——一个需要另外安装并扫码登录微信的独立进程。
dsh-tasks
定时任务：用 cron 表达式定时执行提示词，到点自动开一个新 agent 会话替你干活，支持绑定工作区、手动立即执行与会话自动命名。