文档转Markdown Gorkaseto/dsh-markdownize

dsh-markdownize

一个 DeepSeek Harness（dsh）插件，把文档转成 Markdown，让 LLM 能读懂。

模型对纯文本的处理效果最好。PDF、Word 文件或电子表格按原始字节读进去，对模型来说就是噪声。Markdown 保留结构（标题、列表、表格、幻灯片、页面），同时紧凑易读。这个插件给智能体提供一个 convert_to_markdown 工具，在本地完成转换。你也可以在内容发给模型之前，自己先预览转换结果。

功能

- convert_to_markdown 工具。 模型传入本地文件路径调用它，拿回 Markdown 格式的文档，按 max_chars 截断（默认 100,000）。
- 两种转换引擎。 在插件页面上二选一：
- 自带引擎，纯 JavaScript 移植 MarkItDown 的离线转换器，随插件打包，始终可用；
- Microsoft MarkItDown（Python），安装后使用。
- DOCX 和 PPTX 中的图片。 内嵌图片变成 [Image N: alt text] 标记。当前模型接受图片时，每张图片紧跟其标记之后发送。
- 调试模式。 在网页输入框里预览文件转出的 Markdown（Ctrl+Shift+M）。不会向模型发送任何内容。

支持的格式

| 格式 | 自带引擎（JS） | Microsoft MarkItDown |
| PDF | 支持（逐页文本） | 支持 |
| Word .docx | 支持 | 支持 |
| PowerPoint .pptx | 支持（逐页文本和备注） | 支持 |
| Excel .xlsx | 支持（每个工作表一张表） | 支持 |
| HTML / HTM | 支持 | 支持 |
| CSV / TSV | 支持（转成表格） | 支持 |
| JSON / XML | 支持（代码围栏块） | 支持 |
| TXT / MD | 支持（原样） | 支持 |
| ZIP | 支持（逐个处理内部支持的文件） | 支持 |
| Excel 97 .xls、EPUB、Jupyter .ipynb、Outlook .msg | 不支持 | 支持 |

转换引擎

自带引擎（JavaScript）

convert.js 用 Node 库复刻 MarkItDown 的离线转换器：

- DOCX 用 mammoth；
- XLSX 用 exceljs；
- PDF 用 unpdf（pdf.js）；
- HTML 用 turndown，支持 GFM 表格；
- PPTX 和 ZIP 用 jszip 和 fast-xml-parser。

不需要 Python，不需要网络，也不起子进程。这些库已预打包在 vendor/ 里，所以插件没有运行时 npm 依赖。这一点很关键：dsh 以 link: 依赖的方式安装本地插件，而 pnpm 从不安装链接包的依赖。

Microsoft MarkItDown

MarkItDown 是微软的 Python 工具，做同一件事。它给出参考输出，还能多读几种格式。安装：

pip install "markitdown[all]"

插件会在 PATH 上按 markitdown、py -m markitdown、python -m markitdown 或 python3 -m markitdown 查找它。如果它装在别处，比如某个 virtualenv 的 markitdown.exe，在插件页面上设置它的命令。路径含空格时用双引号括起来。

选择引擎

打开 Plugins → dsh-markdownize。页面会显示找到了哪些引擎。
两者都可用时，按下面的规则选择：

- 自动（默认）：找到 MarkItDown 就用它，否则用 JavaScript 引擎。
- 始终使用 MarkItDown：找不到它时转换失败。
- 始终使用 JavaScript。

选择结果和自定义命令保存在 <dshHome>/storages/dsh-markdownize/settings.json，与图片设置放在一起。它们对工具和调试模式都生效。每次 Host 启动时检测一次 MarkItDown；安装后按 Search again 重新搜索。

文档中的图片

JavaScript 引擎会提取 DOCX 和 PPTX 文件中嵌入的图片（包括 ZIP 内的图片）。每张图片在原位置留下一个标记：DOCX 留在文本中，PPTX 留在幻灯片文本之后。

[Image 1: Sales by quarter]
[Image 2]
[Image 3: Company logo — same as image 1] [Image 4: Vector logo — format not supported]

插件页面决定接下来怎么处理：

- 模型接受图片时发送给它（默认）。工具会检查当前模型声明的输入模态，做法与 harness 的 read_image 相同。模型支持图片时，每张图片存为附件，紧跟其标记之后发送。模型只支持文本时（例如 DeepSeek 的模型），只发送标记，并附一条说明原因的提示。
- 仅发送文本标记。 图片从不发送。

每次转换的图片上限（1–50，默认 10）限制单次调用发送的图片数量，且不超过 harness 自身的单条消息图片上限。超出上限的图片保留标记，并附一条说明。模型也可以传 include_images: false 只获取标记；它无法覆盖这些设置。

重复的图片（每张幻灯片上都有的 logo）只发送一次。两边都小于 32 px 且没有 alt 文本的图标会跳过。PNG、JPEG、GIF 和 WebP 会发送；EMF、WMF 和 TIFF 只保留标记。调试模式始终显示标记。

MarkItDown 不提取图片，所以它作为引擎时这些设置不起作用。

安装

插件不需要构建步骤，也不需要 Python。对于 web 配置档：

dsh plugin --profile web add ./dsh-markdownize

dsh --profile web --dump-config

导出的配置里应出现 # == dsh-markdownize 层。然后启动客户端：

dsh web

在 desktop 配置档上，从应用的插件管理器里以本地文件夹方式添加。

调试模式（web 客户端）

1. 在输入框附加兼容的文件，或用 @ 提及一个文件。
2. 按 Ctrl+Shift+M。

每个兼容的附件和 @file 引用都会在 Host 上转换。@file 路径按会话的工作区解析。完整输出（不截断）写入 <os tmpdir>/dsh-markdownize-debug/，并在右侧边栏预览中打开。输入框会显示一条通知，报告其大小、路径和所用引擎。

不会向模型发送任何内容，草稿保持原样。图片和不支持的格式会跳过。

限制与安全

- 仅限本地文件：URL 会被拒绝（这类场景请使用 web 工具）。
- 读取文件时使用 dsh 进程的权限。
- 文件大小上限为 50 MB。
- ZIP 上限为 200 个条目、解压后 50 MB，最多嵌套一层。
- 工具输出默认截断到 100,000 个字符。

未覆盖： 扫描件 OCR、PDF 中的图片、纯文本模型的图片描述、音频转写、YouTube、Azure Document Intelligence，以及旧版 .doc 和 .ppt 格式。

结构

- index.js —— Host 部分。它注册 convert_to_markdown 工具和 markdownize 服务（convert、convertPath、status、configure、configureImages、redetect），通过 Gateway 的 SRC 回退提供。
- engine.js —— 引擎选择、MarkItDown 检测与调用，以及保存的设置。
- convert.js —— JavaScript 引擎。
- images.js —— 内嵌图片：标记、模型交接，以及工具的输出 schema。
- client.js —— Client 部分：Plugins 下的引擎页面、调试模式快捷键，以及 en / es / zh 界面文案。
- locale/ —— 插件的本地化标题和描述。
- cordis.patch.yml —— 插入 dsh-markdownize 插件行。
- vendor/ —— 打包的转换器库（生成后提交）。
- build-vendor.mjs —— 重新构建 vendor/。

重新构建 vendor/

在 devDependencies 中修改转换器版本后：

npm install && npm run build

提交重新生成的 vendor/ 文件：插件在运行时加载它们。

许可证

Copyright 2026 gorkaseto. 依据 Apache License, Version 2.0 授权；打包的第三方库及其许可证见 NOTICE。