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