前言¶

在 DeepSeek Harness（DSH）里做智能体时，模型往往只能直接读纯文本或 Markdown。PDF、Office、网页、图片、音频等格式需要先转成 Markdown，会话里才好检索、摘要和追问。自己写脚本调转换库、再挂 MCP 或打包二进制，维护成本不低。

下面介绍社区插件 dsh-markitdown（维护者 AlbertZJ）：它把 Microsoft 的 markitdown 接到 DSH 的模型工具面上，通过你配置的 Python 解释器执行 python -m markitdown，不依赖 MCP，也不在插件里捆绑 MarkItDown 本体。

这是什么¶

dsh-markitdown 是 DSH 的 MarkItDown 集成插件。它在 harness 里注册转换与自检工具，并附带一条 markitdown skill（环境检查 → 转换 → 说明格式限制）。MarkItDown 需自行安装到 Python 环境；插件当前版本为 0.6.0（见仓库 package.json），许可证 MIT；MarkItDown 本身为 Microsoft MIT 授权，未随插件打包。

核心功能¶

工具¶

1. markitdown_check：探测配置的 Python 解释器，报告已安装的 MarkItDown 版本（若配置了 LLM 辅助还会报告就绪情况）；缺依赖时给出具体安装指引。
2. markitdown_convert：将单个或多个源转为 Markdown，主要参数包括：
   - path：单个绝对本地路径，或 http(s) URL（例如安装 [all] extra 后可处理 YouTube 链接）；
   - paths：最多 16 个路径或 URL 的批量转换，单个失败不影响其余；
   - stdinBase64：经 MarkItDown stdin 传入的 canonical base64 字节（需配合 extensionHint / mimeHint）；
   - 提示项对应 CLI：extensionHint（-x）、mimeHint（-m）、charsetHint（-c）、keepDataUris；
   - URL 源会先下载再转换，并对出站连接做固定地址校验（防 DNS 重绑定）；默认拒绝解析到 loopback、私网、链路本地地址，除非开启 allowPrivateUrls；
   - output 将单源结果写入文件；outputDir 为每个源写 <name>.md；否则 Markdown 以内联形式返回。

DOCX 内嵌图与可选描述¶

Word 内嵌图片会导出为文件，Markdown 里用文件链接替代 data-URI，便于会话里用 read_image 打开原图继续提问。使用 output 时图片落在同级 <name>.media/；outputDir 时每个 Markdown 旁各有 <name>.media/；inline 转换使用临时目录（绝对路径引用），需要持久化时应指定 output / outputDir。

在 DSH Settings → MarkItDown（不在插件清单页内）可开关「用模型为每张导出图写描述」，并按 OpenAI、DeepSeek 或自定义端点各配一张卡片（模型与 API key）；密钥写入 dsh 凭据存储，不写进 profile 明文配置。该能力需要 pip install openai，并使用仓库内的 python/llm_convert.py 辅助；对 DOCX，插件会按文档顺序解包 word/media、导出（及可选描述）并替换占位符。描述在 temperature=0 下运行，要求逐字转写、不可读处标注而非猜测。

Skill 与格式范围¶

内置 markitdown skill 覆盖常见工作流，并说明各格式预期与已知限制。

本地支持的输入类型包括：PDF，DOCX/DOC，PPTX/PPT，XLSX/XLS，CSV，JSON，XML，HTML/HTM，EPUB，MD，Outlook MSG，ZIP（内含文件就地转换），JPG/JPEG/PNG/GIF/TIFF/BMP（EXIF、可用时 OCR），WAV/MP3（转写，需 [all] extra）。

安装与启用¶

前提：在将要使用的 Python 环境中安装 MarkItDown（含可选的全部 extra）：

python -m pip install 'markitdown[all]'

安装插件：在任意 profile 的 Plugins 页选择从源码安装，或使用等价的 CLI，安装源为：

github:AlbertZJ/dsh-markitdown

仓库要求 Node.js >= 22.19.0，dsh 版本 >=0.2.1-rc.2 且 <0.3.0。插件不会替你安装 Python 包；安装后应让模型调用 markitdown_check 并按提示补齐环境。

配置要点¶

profile 中插件块名称为 dsh-markitdown，字段均可选；默认在 PATH 上的 python 已装好 markitdown 即可工作：

- name: 'dsh-markitdown'
  config:
    command: python
    timeoutMs: 60000
    maxInputBytes: 52428800
    maxOutputBytes: 8388608
    # allowedRoot: D:/work/documents
    # llmProvider / llmProviders / describeImages 等见 README
    # allowPrivateUrls: false
    # allowPlugins: false

Windows 若只有 launcher，可将 command 设为 py 或 Python 可执行文件的绝对路径。可选 allowedRoot 将读写限制在单一工作区根目录内（解析路径时跟随符号链接）。LLM 图片描述、活动 provider、llmAllowUrls 等以 Settings → MarkItDown 与 README 中的 YAML 注释为准。

典型用法¶

1. 启用插件并完成 markitdown_check，确认 MarkItDown 版本与依赖就绪。
2. 对本地绝对路径调用 markitdown_convert，需要保留 DOCX 导出图时使用 output 或 outputDir。
3. 需要从 URL 拉取文档时传入 path 为 https 链接；内网或 localhost 仅在明确风险可控时考虑 allowPrivateUrls。
4. 需要 skill 引导的完整流程时，使用 bundled markitdown skill。

转换在 dsh 宿主进程中以子进程方式运行，不经过 harness 的 Bash 审批流；插件会在调用前校验路径（绝对、存在、扩展名允许列表、大小上限）。

适用场景与注意¶

适合：已在 DSH 中开发文档类智能体、希望统一用 MarkItDown 把 Office/PDF/多媒体转为 Markdown、并可选把 Word 内图导出供 read_image 追问的场景。

注意：

• 无文字层的扫描 PDF 可能几乎无文本输出；复杂版式会压平为线性 Markdown。
• inline 转换的临时媒体目录可能被系统清理；设 allowedRoot 时 inline 可能保留 data URI 而不写出工作区外。
• 图片描述是一次性的，措辞要求精确时应打开导出原图而非仅信描述。
• 插件以当前 dsh 进程权限 运行子进程与读文件；安装前请阅读 GitHub 源码 与 MIT 许可证，自行评估 URL 下载与 LLM 外发（llmAllowUrls 默认关闭）是否符合安全策略。

DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区索引，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-markitdown 把 MarkItDown 接到 DSH 工具面，提供自检、单批转换、DOCX 出图与可选 LLM 描述，以及配套 skill，适合在 harness 内做文档流水线。详情与 issue 见 GitHub 仓库，目录入口见 SkillHub。