dsh-anydoc-markdown：DeepSeek Harness 文档转 Markdown 与图像描述插件

前言¶

DeepSeek Harness（DSH）通过插件机制扩展了智能体的工具箱。在构建智能体时，处理非文本文件（如 Word、PPT、Excel、PDF）是一个常见需求。这些文件中通常包含嵌入式图片，而纯文本模型无法直接理解这些视觉内容。

dsh-anydoc-markdown 旨在解决这一痛点。它将文档转换为纯 Markdown，并利用视觉语言模型（VLM）对文档中的图片进行描述，从而让文本模型能够基于图片内容进行推理。

插件介绍¶

dsh-anydoc-markdown 是一个 DeepSeek Harness 插件，由 SeerableOfficial 维护，采用 MIT 许可证。

该插件基于 Rust 的 firecrawl-anydoc 库实现文档解析，并配套一个 Python 包装器来处理图像的批量描述。它不直接注入转换后的 Markdown，而是将源文件路径提供给智能体，由智能体主动调用转换工具，保证了工具调用的规范性。

核心功能¶

1. 多格式文档转换：支持 Word (.docx)、PowerPoint (.pptx)、Excel (.xlsx)、OpenDocument (.odt)、RTF、EPUB、CSV、PDF 等格式，统一输出为 GitHub 风格的 Markdown。
2. 图像视觉描述：利用 VLM 描述文档中的嵌入式图片，并将图片替换为描述性文本占位符（如 ![<description>](asset://<id>)）。
3. 批量请求机制：为了防止性能下降，插件默认将图片按每批最多 10 张进行分组请求，而不是一次性发送所有图片。
4. 智能体工具集成：提供一个 convert_document 工具，智能体可按需调用，将文档转换为 Markdown。
5. 原生拖拽支持：在 Harness 的编辑器中支持直接拖拽文档文件进行上传和转换，无需额外的附件按钮。
6. 离线优先模式：当未配置 VLM 端点时，插件仍可工作，仅使用离线元数据描述图片，无需网络调用和 API 密钥。
7. 文件提取与保存：配置输出目录后，插件会自动提取图片并保存为 PNG 文件，生成的 Markdown 文件与图片同目录存储。

安装与启用¶

安装前请确保已安装 Python 环境及必要的依赖库。

1. 安装依赖包（包含 firecrawl-anydoc、pdfplumber 和 Pillow）：

    pip install -r converter/requirements.txt

2. 在 Harness 中添加插件：

    dsh plugin --profile web add dsh-anydoc-markdown

3. 重启 DSH Web 服务：

    # restart dsh web

典型用法¶

1. 智能体主动调用¶

智能体接收源文件路径后，调用 convert_document 工具。

# 智能体调用示例
markdown_content = convert_document(file_path: "report.pptx")

2. 界面拖拽上传¶

在 Harness 的 Web 界面中，支持原生拖拽操作。

1. 将文档（.docx, .pdf, .pptx 等）拖拽到页面。
2. 文件会出现在编辑器上方的附件条带中，显示文件名和大小。
3. 提交消息后，文件已保存至本地，智能体在下一轮对话中会收到文件路径，并调用转换工具。

注意事项¶

1. 版本兼容性：该插件仅针对 DeepSeek Harness 版本 v0.1.1-rc.2 进行过测试，可能与最新版本不兼容。
2. 依赖库要求：要描述 PDF 中的图片，必须安装 pdfplumber 和 Pillow。如果未安装，PDF 仅能转换文本内容，不影响其他功能。
3. 文件路径机制：文档在转换前以源文件路径形式存储。智能体必须调用 convert_document 工具来触发转换。
4. 输出模式：
   • 如果未配置 markdownOutputDir，转换结果将以 Markdown 文本形式内联返回。
   • 如果配置了 markdownOutputDir，转换结果将保存为文件，并返回文件路径。

总结¶

dsh-anydoc-markdown 通过结合 Rust 本地解析能力与 VLM 的视觉理解能力，为 DeepSeek Harness 提供了一套完整的文档处理方案。它支持批量请求以优化性能，并提供了离线模式，适合需要在 Agent 流程中处理复杂文档结构的场景。

插件目录 | GitHub 仓库