dsh-markitdown：将非文本文档转为 Markdown 的 DeepSeek Harness 插件

前言¶

DeepSeek Harness 的模型通常只能直接读取文本。当需要处理 PDF、Excel 或 PPT 等非文本文件时，往往需要先编写脚本进行预处理。markitdown 是微软提供的优秀文档转 Markdown 工具，但传统用法需要 Python 环境。dsh-markitdown 作为一个 DeepSeek Harness 插件，旨在让模型在 DSH 环境中直接调用 MarkItDown，而无需假设特定的 Python 环境或安装布局。

插件介绍¶

dsh-markitdown 是 Microsoft MarkItDown 作为 DeepSeek Harness 工具的封装。它将 PDF、Word、Excel、PowerPoint、HTML、CSV、EPUB 或 URL 等多种格式的文档转换为模型可读的 Markdown。

所有者：jiekesu967
类别：模型推理
许可证：MIT

核心功能¶

该插件支持将以下格式转换为 Markdown：
* 文档：PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx), HTML, EPUB
* 数据：CSV, TSV, XML
* 代码与笔记本：JSON, Jupyter (.ipynb)
* 网络：URL

当外部工具缺失时，插件会使用内置转换器作为后备方案。此外，它还支持通过 OCR 识别图像、音频和 YouTube 内容。

安装与启用¶

使用前需确保环境满足以下要求：
* DeepSeek Harness：0.1.5-rc.1 或更新版本（0.1.x 和 0.2.x 均支持）
* Node.js：^22.19.0 或 >=24.0.0

安装步骤¶

执行以下命令安装插件：

    dsh plugin --profile web add github:jiekesu967/dsh-markitdown

安装后重启 dsh web，工具将在下一个会话中生效。
若需使用 PDF、OCR 或完整的 Office 转换功能，建议在本地安装 MarkItDown：

    pip install "markitdown[all]"
    # 或安装 uv 后使用 uvx
    winget install astral-sh.uv

典型用法¶

在 Harness 的工作流中，模型可以直接调用 markitdown 工具。

转换本地文件为 Markdown：

markitdown({ input: "reports/q3.pdf" })

转换并保存到指定路径：

markitdown({ input: "data/forecast.xlsx", output: "notes/forecast.md" })

转换网页内容：

markitdown({ input: "https://example.com/spec.html" })

配置说明¶

配置项均为可选，默认值如下：

- id: markitdown
  name: dsh-markitdown
  config:
    engine: auto              # 自动检测可用引擎
    uvxPackage: "markitdown[all]"   # 指定 uvx 安装时的包名
    command: ""               # 显式指定可执行文件
    timeoutMs: 120000         # 单次转换超时时间
    maxChars: 120000          # 内联结果的最大字符数
    maxBytes: 67108864        # 内置引擎读取文件的最大字节数
    allowUrls: true           # 是否接受 URL 输入
    extraArgs: []             # 传递给外部引擎的额外参数

引擎检测顺序（engine: auto 时）：
1. markitdown CLI（需 pip install "markitdown[all]"）
2. uvx markitdown（无需安装，需安装 uv）
3. python -m markitdown（需 Python 3.10+ 且已安装）
4. 内置转换器（无需额外依赖，但功能有限）

使用注意事项¶

路径解析：相对路径（如 input: "reports/q3.pdf"）是相对于会话的工作区（session workspace）解析的，而非进程当前工作目录。
文件写入：通过 output 参数写入文件时，会经过文件系统接口，受限于沙箱策略和读写规则。
输入校验：若输入文件缺失，插件会在启动子进程前报错，而非在执行过程中失败。
输出截断：当 Markdown 结果超过 maxChars 且未指定输出路径时，结果会被截断，并明确提示截断信息。
安全限制：
- 本地文件超过 maxBytes 会被拒绝读取。
- URL 响应受内容长度限制，超限则不下载。
- 归档文件解压受限于单条目大小（默认 256MiB）。
- Excel 列引用超出 XFD 时会被丢弃。
权限：MarkItDown 在当前进程权限下执行 I/O 操作，请谨慎处理不信任的输入源。

总结¶

dsh-markitdown 解决了 DeepSeek Harness 模型无法直接处理非文本文档的痛点。它通过自动检测和回退机制，提供了在不同环境下的兼容性。对于需要从文档中提取结构化数据的场景，该插件是一个直接、高效的工具。

插件目录：https://www.skillhub.cn/plugins/jiekesu967/dsh-markitdown
源码仓库：https://github.com/jiekesu967/dsh-markitdown