SeerableOfficial/dsh-anydoc-markdown

dsh-anydoc-markdown

适用于 DeepSeek Harness（dsh）的文档 → Markdown + 视觉图像描述插件。

注意：此插件仅在 Deepseek harness 版本 v0.1.1-rc.2 上测试过。它可能无法在最新版本上运行。如果它与你的版本不兼容，请让 agent 修改该插件。

使用 Rust 的
firecrawl-anydoc crate 将文档（Word、PowerPoint、Excel、OpenDocument、RTF、EPUB、CSV、PDF）
转换为干净的 GitHub 风格 Markdown，并使用视觉模型描述
每一张嵌入图像，以便纯文本模型能够推理
文档中的图像内容。

设计目标。 anydoc 是一个纯本地、无依赖的 Rust 转换器：其
核心没有网络调用，也没有 llm_client 参数。但它暴露了
anydoc.to_document()，该方法返回完整的文档模型以及
Document.assets 上的嵌入二进制资源（图像、MIME 类型和 alt 文本标记）。此插件为 anydoc 复刻了 MarkItDown 的 llm_client +
llm_model 模式：拦截图像资源，将它们传递给
VLM（OpenAI 的 gpt-4o 或本地 OpenAI 兼容模型），并替换
输出 Markdown 中的图像占位符。

功能特性

- 所有格式共用同一份 Markdown 输出 — anydoc 将每种格式
都汇入同一个文档模型和 GFM 序列化器，因此标题、表格、列表、
公式、链接、脚注和演讲者备注都能一致地输出。
- 嵌入图像描述（视觉流水线） — 图像由
VLM 描述，并作为  替换到 Markdown 中。
转换器丢弃的图像（空 alt 文本）会作为带描述的列表追加。
- 批量视觉请求（重要部分） — 图像绝不会全部放在
一个 API 请求中发送。它们会被拆分为 maxImagesPerRequest
（默认 10）大小的批次，每个批次都是一个单独的请求，因此视觉性能
不会因巨大的多图像提示而下降。可配置。
- 面向 agent 的 convert_document 工具 — agent 可按需将任意文档转换为
Markdown（无 offset/limit；返回完整 Markdown，有上限）。
- Composer 文档附加（原生拖放 + 停靠条） — 文档通过
harness 原生用于图像的同一整页拖放方式附加
（没有 composer 工具行回形针按钮，也没有相互竞争的拖放覆盖层，
后者此前会冻结 harness 自身的拖放覆盖层）。拖放的文档会显示为
composer 输入停靠区中一条细条内的附件卡片，位于
composer 卡片上方。文档会被存储，并将源文件
路径交给 agent；图像则保留 harness 内置的图像路径。
- 提取的图像保存为 PNG — 当设置了 markdownOutputDir 时，
convert_document 会在该目录下创建一个以 Markdown 文件命名的子文件夹
（例如 report/），并将 .md 文件以及每张提取出的嵌入
图像都保存为其中的 PNG。Markdown 通过以下方式引用这些磁盘上的 PNG：
相对文件名，因此 .md 及其图片可以一起便携移动。
- 代理驱动转换 —— 插件从不注入转换后的 Markdown。
它将保存的源文件路径交给模型，让代理对每个文件调用
convert_document。转换器将 Markdown（及其图片）保存到
markdownOutputDir，并返回 .md 文件路径。
- 离线优先 —— 当未配置 VLM 端点/模型时，转换器
仍会生成 Markdown 并仍会分批处理，对每张图片使用诚实的离线元数据
描述。无需网络调用，无需 API 密钥。
- 自包含 —— 宿主端没有 @deepseek-ai/ 导入（始终
加载），客户端则依托标准的 __ModuleLoader__ 插槽/RPC
接缝。

安装

pip install -r converter/requirements.txt   # firecrawl-anydoc + pdfplumber + Pillow
dsh plugin --profile web add dsh-anydoc-markdown
restart dsh web

pdfplumber + Pillow 仅在描述嵌入 PDF 中的图片时才需要。
如果它们不可用，PDF 仍可转换（仅文本），视觉
管线的其余部分不受影响。

用法

1. 代理使用文档路径调用 convert_document 工具：
convert_document(file_path: "report.pptx")。
2. 插件针对 anydoc 运行捆绑的 Python 包装器（converter/anydoc_vlm.py），
然后通过 VLM 分批描述每张嵌入的图片。
3. 该工具将 Markdown（已替换图片描述）返回给
模型。

Composer 文档附加（原生拖放 / 多文件）

文档通过与测试框架用于图片的相同整页拖放方式附加：
将任意数量的文档（.docx .pdf .pptx .xlsx .odt .rtf .epub
.csv .txt .md .html）拖到页面上并释放。测试框架自带的拖放覆盖层
（即显示“将图片和文档拖到此处以添加它们”的那个）会提示
拖放，插件会将附加的文档显示为 composer
输入停靠条中的卡片（composer 卡片上方的一行）。同时拖放的图片
继续使用测试框架内置的图片附加功能。

1. 将文档拖到页面上（或放下它们）→ 它们会流式传输到宿主的
attach.upload RPC 通道（默认为 /dsh-anydoc）。每个上传的
文档都会写入 attachmentsDir，并在停靠条中显示为卡片（名称 + 大小 +
移除）。在你提交消息后，卡片会自动清除 —— 文档已保存到磁盘，因此代理仍会在下一步
获取它们的路径。
2. 在下一步代理操作中，插件将保存的源文件
路径作为模型可见的步骤前消息交给模型（“对下面每个
路径使用 convert_document”）。它从不注入转换后的 Markdown。
3. 代理对每个文件调用 convert_document(file_path: "")。该
工具转换文档，将 Markdown 保存到 markdownOutputDir，并
返回 .md 文件路径（savedPath）以及 Markdown。
4. 失败/超大/不支持的文件会单独报告，绝不会破坏
批次中的其余部分。

配置

所有字段都有合理的默认值——安装后无需改动任何字段即可使用。只调整
你需要的部分。每个可调项都是经过验证的 cordis.patch.yml 字段；没有
任何一项是硬编码的。

| 字段 | 默认值 | 描述 |
| --- | --- | --- |
| converterPython | python | 用于运行捆绑包装器的 Python 解释器。 |
| converterPath | converter/anydoc_vlm.py | 捆绑包装器的路径（位于此目录中）。 |
| maxImagesPerRequest | 10 | 每次视觉请求的最大图像数。安装要求——绝不要把所有图像塞进一个请求。 |
| maxChars | 60000 | 返回给模型的 Markdown 截断上限。 |
| timeoutMs | 120000 | 协作式工具调用超时预算。 |
| visionEndpoint | '' | 兼容 OpenAI 的视觉端点；为空 = 离线元数据描述。 |
| visionModel | '' | 视觉模型 id（例如 gpt-4o）；为空 = 离线元数据描述。 |
| visionApiKeyEnv | OPENAI_API_KEY | 提供视觉 API 密钥的环境变量。 |
| attachmentChannel | /dsh-anydoc | 编辑器用于附加文档的通用 RPC 通道。 |
| attachmentsDir | /attachments | 上传的源文档写入的目录；代理会获得这些路径。 |
| markdownOutputDir | '' | convert_document 创建以 Markdown 文件命名的子文件夹（例如 report/）并在其中保存 .md 文件以及每个提取出的嵌入图像（作为 PNG）的目录，返回 .md 文件路径（savedPath）以及 imageDir/savedImages。为空 = 内联返回 Markdown 且不保存任何内容。 |
| maxFileBytes | 26214400（25 MiB） | 文档附件的单次上传字节上限（解码后大小）。 |
| allowedAttachExtensions | ['.docx','.doc','.pdf','.pptx','.ppt','.xlsx','.xls','.odt','.rtf','.epub','.csv','.txt','.md','.html','.htm'] | 编辑器接受的文档扩展名。 |

- id: dsh-anydoc-markdown
config:
maxImagesPerRequest: 10
visionEndpoint: https://api.openai.com/v1
visionModel: gpt-4o

图像如何处理

| 检测到的图像 | 处理方式 |
| --- | --- |
| 嵌入资源（Document.assets 中的字节） | 由 VLM 描述并替换为 。当设置了 markdownOutputDir 时，它还会被重新编码为 PNG 并保存到每个文档的子文件夹中，引用会指向该文件。 |
| 嵌入、空 alt（anydoc 会丢弃它） | 作为带描述的引用列表追加到末尾。当设置了 markdownOutputDir 时，也会持久化为 PNG。 |
| PDF 嵌入光栅图 | PDF 没有 anydoc 文档模型，因此每个光栅图都会用 pdfplumber 从 PDF 字节中恢复、重新编码，并作为带描述的引用列表追加。当设置了 markdownOutputDir 时，也会持久化为 PNG。 |
| 外部 URL 图像 | 保留为普通的 Markdown 图像。 |
VLM 调用与 OpenAI 兼容；将 visionEndpoint/visionModel 指向任何
使用 chat-completions 通信格式的端点（OpenAI、本地
Ollama VL 模型、OpenAI 兼容代理等）。当
visionEndpoint: ''（默认值）时，包装器使用离线元数据描述。

视觉流水线（转换器细节）

Python 包装器 converter/anydoc_vlm.py 是
转换 + 图像描述发生的地方（完整说明见
converter/README.md）：

- 批量请求（硬性要求）。 图像绝不会全部放在一个
API 请求中发送——那会降低视觉性能。describe_many() 将它们
按 maxImagesPerRequest（默认 10）切成组，并为每组发出一个
chat-completions 请求，因此 23 张图像会跨 3 个请求产生 [10, 10, 3]，
而不是一个巨大的多图像提示。
- 重试 + 宽容解析（失败关闭）。 每个批次在 HTTP 错误、超时，或响应
不是恰好包含 N 个描述的 JSON 数组时，最多重试 3
次（带退避）。包裹在散文或围栏 JSON 块中的数组响应
仍会被解析。只有当每次重试都失败时，该批次才会
降级为离线元数据描述——并且注释会说明原因*
（vision request failed after retries / vision unavailable after retries），
而不是声称模型未配置。
- PDF 支持。 PDF 不携带 anydoc 文档模型，因此其内嵌的栅格
图像会使用 pdfplumber 从 PDF 字节中恢复，并以相同方式描述。
需要 pdfplumber + Pillow；如果缺少它们，则失败关闭为纯文本 Markdown。
扫描页面需要 --ocr hosted（Firecrawl Parse）。
- 离线优先，诚实的元数据。 在未配置端点/模型时，
包装器仍会生成 Markdown 并且仍会分批，对每张图像使用诚实的离线
元数据描述（[Offline metadata description - no vision
model was configured.]）。无需网络调用，无需密钥。

转换器 CLI

python converter/anydoc_vlm.py  \
[--format NAME] [--ocr reject|hosted] [--max-images N] \
[--vision-endpoint URL] [--vision-model MODEL] [--api-key KEY] \
[--save-images-dir DIR] [--mock-vision] [--json] [--out FILE]

| 选项 | 默认值 | 描述 |
| --- | --- | --- |
| --format | auto | 显式格式名称（仅对 CSV 等无签名格式需要）。 |
| --ocr | reject | hosted 将扫描的 PDF 页面路由到 Firecrawl Parse。 |
| --max-images | 10 | 每个视觉请求的最大图像数。 |
| --vision-endpoint | 环境变量 ANYDOC_VISION_ENDPOINT | OpenAI 兼容的视觉端点。 |
| --vision-model | 环境变量 ANYDOC_VISION_MODEL | 视觉模型 id（例如 gpt-4o）。 |
| --api-key | 环境变量 OPENAI_API_KEY | 视觉 API 密钥。 |
| --save-images-dir | 未设置 | 将每个提取出的内嵌图像保存为该目录中的 PNG，并重写 Markdown 图像引用以指向它。 |
| --mock-vision | 关闭 | 强制使用离线描述（用于测试）。 |
| --json | 关闭 | 输出 {"markdown", "meta"} 而非纯 Markdown。 |
| --out | stdout | 将 Markdown 写入文件。 |

使用捆绑的测试文档验证批处理（23 张图片，最多 10 张）：

python converter/anydoc_vlm.py tests/multi.docx --mock-vision --max-images 10 --json
vision_batch_sizes: [10, 10, 3], vision_requests: 3

架构

dsh-anydoc-markdown/
├── index.js                 # 宿主插件：convert_document 工具 + attach.upload RPC 通道
├── lib/client.js            # Web 客户端：文档拖放 + dock-strip 卡片（无工具行按钮/覆盖层）
├── cordis.patch.yml         # 捆绑配置（所有可调项）
├── package.json             # dsh.bundle.patch + dsh.client, files
├── converter/
│   ├── anydoc_vlm.py        # anydoc + 批处理视觉引擎（即 "llm_client" 接缝）
│   ├── requirements.txt     # firecrawl-anydoc + pdfplumber + Pillow（PDF 图片）
│   └── README.md            # 包装器文档 + 批处理工作原理
└── README.md

Python 包装器是真正工作发生的地方（参见
converter/README.md）：anydoc.to_document() 产出
嵌入的资源，VisionClient.describe_many() 对它们进行批处理（每次请求 ≤ 10 个），
然后 substitute() 将图像占位符替换为描述。

开发

python converter/anydoc_vlm.py tests/multi.docx --mock-vision --max-images 10 --json
node --check index.js
python -m py_compile converter/anydoc_vlm.py

安全与注意事项

- anydoc 在本地运行转换；只有选择启用
--ocr hosted 的扫描 PDF 页面会离开本机（Firecrawl Parse）。视觉调用本身仅
发送到配置的 visionEndpoint。
- 该插件故障关闭：如果解释器缺失、anydoc 未安装，或转换出错，该调用会
大声失败，而测试框架会按照 dsh-file-upload 的设计方式继续工作。
- 上传的文档会写入 attachmentsDir（持久化），转换后的 Markdown（及其提取的
图像 PNG）会写入 markdownOutputDir 内按文档划分的子文件夹；两者均可配置，
且仅在你配置时才会写入。文件名会被清理（无路径遍历），
不在允许列表中的扩展名会被拒绝，文件大小受
maxFileBytes 限制。

许可证

MIT