前言¶
DeepSeek Harness（DSH）通過插件機制擴展了智能體的工具箱。在構建智能體時，處理非文本文件（如 Word、PPT、Excel、PDF）是一個常見需求。這些文件中通常包含嵌入式圖片，而純文本模型無法直接理解這些視覺內容。
dsh-anydoc-markdown 旨在解決這一痛點。它將文檔轉換爲純 Markdown，並利用視覺語言模型（VLM）對文檔中的圖片進行描述，從而讓文本模型能夠基於圖片內容進行推理。
插件介紹¶
dsh-anydoc-markdown 是一個 DeepSeek Harness 插件，由 SeerableOfficial 維護，採用 MIT 許可證。
該插件基於 Rust 的 firecrawl-anydoc 庫實現文檔解析，並配套一個 Python 包裝器來處理圖像的批量描述。它不直接注入轉換後的 Markdown，而是將源文件路徑提供給智能體，由智能體主動調用轉換工具，保證了工具調用的規範性。
核心功能¶
- 多格式文檔轉換：支持 Word (.docx)、PowerPoint (.pptx)、Excel (.xlsx)、OpenDocument (.odt)、RTF、EPUB、CSV、PDF 等格式，統一輸出爲 GitHub 風格的 Markdown。
- 圖像視覺描述：利用 VLM 描述文檔中的嵌入式圖片，並將圖片替換爲描述性文本佔位符（如
）。 - 批量請求機制：爲了防止性能下降，插件默認將圖片按每批最多 10 張進行分組請求，而不是一次性發送所有圖片。
- 智能體工具集成：提供一個
convert_document工具，智能體可按需調用，將文檔轉換爲 Markdown。 - 原生拖拽支持：在 Harness 的編輯器中支持直接拖拽文檔文件進行上傳和轉換，無需額外的附件按鈕。
- 離線優先模式：當未配置 VLM 端點時，插件仍可工作，僅使用離線元數據描述圖片，無需網絡調用和 API 密鑰。
- 文件提取與保存：配置輸出目錄後，插件會自動提取圖片並保存爲 PNG 文件，生成的 Markdown 文件與圖片同目錄存儲。
安裝與啓用¶
安裝前請確保已安裝 Python 環境及必要的依賴庫。
- 安裝依賴包（包含
firecrawl-anydoc、pdfplumber和Pillow）：
pip install -r converter/requirements.txt
- 在 Harness 中添加插件：
dsh plugin --profile web add dsh-anydoc-markdown
- 重啓 DSH Web 服務：
# restart dsh web
典型用法¶
1. 智能體主動調用¶
智能體接收源文件路徑後，調用 convert_document 工具。
# 智能體調用示例
markdown_content = convert_document(file_path: "report.pptx")
2. 界面拖拽上傳¶
在 Harness 的 Web 界面中，支持原生拖拽操作。
- 將文檔（.docx, .pdf, .pptx 等）拖拽到頁面。
- 文件會出現在編輯器上方的附件條帶中，顯示文件名和大小。
- 提交消息後，文件已保存至本地，智能體在下一輪對話中會收到文件路徑，並調用轉換工具。
注意事項¶
- 版本兼容性：該插件僅針對 DeepSeek Harness 版本
v0.1.1-rc.2進行過測試，可能與最新版本不兼容。 - 依賴庫要求：要描述 PDF 中的圖片，必須安裝
pdfplumber和Pillow。如果未安裝，PDF 僅能轉換文本內容，不影響其他功能。 - 文件路徑機制：文檔在轉換前以源文件路徑形式存儲。智能體必須調用
convert_document工具來觸發轉換。 - 輸出模式：
- 如果未配置
markdownOutputDir，轉換結果將以 Markdown 文本形式內聯返回。 - 如果配置了
markdownOutputDir，轉換結果將保存爲文件，並返回文件路徑。
- 如果未配置
總結¶
dsh-anydoc-markdown 通過結合 Rust 本地解析能力與 VLM 的視覺理解能力，爲 DeepSeek Harness 提供了一套完整的文檔處理方案。它支持批量請求以優化性能，並提供了離線模式，適合需要在 Agent 流程中處理複雜文檔結構的場景。
