# dify-doc2md

**Repository Path**: lyDevelop/dify-doc2md

## Basic Information

- **Project Name**: dify-doc2md
- **Description**: 用于 dify 的文本解析插件
支持将常见文本转换成 markdown 文本
.doc .docx .wps .xlsx .xls .txt .pdf .ofd .csv .png .jpeg .jpg
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-18
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: dify

## README

# Dify 文档提取器

将文档、表格、PDF、OFD 和图片提取为 Markdown，供 Dify 工作流中的 LLM 使用。支持批量解析、OCR、超时控制和完整 Markdown 文件输出。

支持 `.md`、`.doc`、`.docx`、`.wps`、`.xlsx`、`.xls`、`.txt`、`.pdf`、`.ofd`、`.csv`、`.png`、`.jpeg`、`.jpg`。其他扩展名一律返回 `unsupported`，不自动按 ZIP 或文本处理。

DOCX、XLSX、OFD 和 ZIP 容器形式的 WPS 在交给解析器前只检查 ZIP 中央目录：成员数、单成员展开大小、总展开大小、压缩比及危险成员名；插件不支持普通 ZIP，也不递归解压。解析在可终止子进程中进行，`file_timeout_seconds` 是单文件硬超时，`total_timeout_seconds` 覆盖整次请求。超时会终止并回收子进程。批量文件可通过 `max_workers` 设置 1–4 个并行解析子进程；单个文件仍按页面顺序处理，资源受限或大文件场景建议保持为 1。

OFD 优先读取安全 XML 文本层；只有原生文本为空时才用 easyofd 转 PDF 并调用 OCR，避免渲染器丢失文字时生成空表格。保留文件大小、PDF 页数、图片像素、输出长度和 OCR 请求超时限制。OCR 提供者可选：

- `paddle`：自部署 PaddleOCR，使用既有 `/layout-parsing` JSON Base64 协议。
- `aistudio`：PaddleOCR AI Studio 网络 API。填写 API Token，默认使用 `PaddleOCR-VL-1.6`；插件以 multipart 上传文件，轮询 Job，并只读取结果 JSONL 中的 Markdown。

AI Studio 可选填写 `ocr_endpoint` 覆盖默认 Job 地址 `https://paddleocr.aistudio-app.com/api/v2/ocr/jobs`。网络 OCR 的全部上传和轮询仍受单文件硬超时及 OCR 请求超时约束。

## 在工作流中向 LLM 提供完整内容

工具节点的 `text` 是用于界面预览的输出，受 `max_output_chars` 限制；完整结果始终会作为 `.md` 文件附件返回，同时写入工具节点的 `full_markdown` 输出变量。将下游 LLM 节点提示词中的输入变量设为“文档提取器 / full_markdown”，即可使用未被该参数截断的 Markdown。

`full_markdown` 不受本插件的可见文本上限影响，但仍会受到所选模型的上下文窗口和 Dify 运行环境的请求上限约束。超出模型上下文时，请按工作表或行区间拆分后分别调用 LLM。

安全边界：ZIP 预检依赖容器中央目录元数据，解析器本身仍是第三方代码，因而始终运行在可终止子进程；OCR 服务是外部信任边界，必须部署在受控网络中。

## 运行要求与包选择

- Dify **1.10.1 或更高版本**，插件使用 **Python 3.12 runner**。
- 目标运行环境为 **Linux amd64（x86_64）或 arm64（aarch64）**。
- 离线包内的原生依赖要求 **glibc 2.28 或更高版本**，不适用于 Alpine/musl 环境。

`amd64` 是 Intel/AMD 通用的 64 位 x86 架构名称，不代表只支持 AMD 处理器；不支持 32 位 x86（i386/i686）。

| 使用场景 | 包文件 | 支持的目标架构 |
| --- | --- | --- |
| Dify 能联网安装 Python 依赖 | `document_extractor-online.difypkg` | amd64、arm64 共用 |
| Intel/AMD 64 位服务器，离线安装依赖 | `document_extractor-offline-amd64.difypkg` | amd64 / x86_64 |
| ARM 64 位服务器，离线安装依赖 | `document_extractor-offline-arm64.difypkg` | arm64 / aarch64 |

在**目标 Dify 服务器**上执行 `uname -m` 判断架构：`x86_64` 选 amd64，`aarch64` / `arm64` 选 arm64。以实际运行插件的 Linux 容器或服务器架构为准。

离线包携带对应架构的 Python wheel，包内 `manifest.yaml` 只声明该架构；在线包由目标环境安装依赖，声明支持两种架构。离线打包不会修改仓库中的 `manifest.yaml`。

## 打包

在本仓库根目录执行以下命令。构建机需要 Python 3 和 pip；离线打包还需要 `rsync`。首次运行会通过 `curl` 从 GitHub 下载与构建机匹配的官方 Dify CLI，缓存到 `.dify-cli/`；下载依赖需要访问 PyPI 或所配置的镜像源。

构建机可为 macOS 或 Linux 的 amd64 / arm64 系统，**可以跨架构打包**，例如在 Apple Silicon Mac 上生成 Linux amd64 离线包。

### 在线包

```bash
./scripts/package_online.sh

# 可选：指定输出路径（父目录需已存在）
./scripts/package_online.sh /path/to/document_extractor-online.difypkg
```

在线包不携带 wheel；Dify 导入时需要能从其配置的 Python 软件源安装依赖。

### amd64（x86_64）离线包

```bash
./scripts/package_offline_amd64.sh

# 可选：指定输出路径
./scripts/package_offline_amd64.sh /path/to/document_extractor-offline-amd64.difypkg
```

默认生成仓库根目录下的 `document_extractor-offline-amd64.difypkg`。

### ARM64 离线包

```bash
./scripts/package_offline_arm64.sh

# 可选：指定输出路径
./scripts/package_offline_arm64.sh /path/to/document_extractor-offline-arm64.difypkg
```

默认生成仓库根目录下的 `document_extractor-offline-arm64.difypkg`。

两个离线入口共用 `scripts/package_offline.sh`，也可以直接指定目标架构：

```bash
./scripts/package_offline.sh amd64
./scripts/package_offline.sh arm64 /path/to/document_extractor-offline-arm64.difypkg
```

离线脚本会复制源码，下载目标 Linux 架构 / CPython 3.12 的二进制 wheel，再使用 `--no-index` 校验本地 wheel 能否完成依赖解析。随后写入 `--no-index --find-links=./wheels`、限定包内架构声明，最后生成 `.difypkg` 并输出 SHA256。下载目标同时包含 `manylinux_2_28` 和 `manylinux2014` 标签，以覆盖不同依赖提供的 wheel。

### 构建参数

| 环境变量 | 适用脚本 | 说明 | 默认值 |
| --- | --- | --- | --- |
| `PYTHON_BIN` | 全部 | Python 解释器；离线打包需带 pip | `python3` |
| `MAX_SIZE_MB` | 全部 | 传给 Dify CLI 的包大小上限，单位 MB | `5120` |
| `PIP_INDEX_URL` | 离线 | 构建时下载依赖的软件源，不写入离线包 | pip 默认配置 |
| `PIP_TRUSTED_HOST` | 离线 | 与所用镜像源配套的 pip 主机配置 | 不额外设置 |
| `DIFY_CLI` | 在线 | 指定已有 Dify CLI 的命令或路径 | `.dify-cli/dify` |

```bash
PYTHON_BIN=python3.12 ./scripts/package_offline_amd64.sh
```

## 导入 Dify

1. 根据目标服务器架构选择包，在 Dify 插件管理中通过本地文件导入 `.difypkg`。
2. 若 Dify 开启插件签名验证，请先按部署环境要求签名。
3. 在工作流中添加“文档提取器”工具节点，配置输入文件；需要 OCR 时配置对应服务。
4. 将下游 LLM 的输入连接到工具节点的 `full_markdown` 输出变量。

离线包解决的是 Python 依赖安装；调用 OCR 仍需目标环境能访问所配置的 OCR 服务。

### 查看与检查包

```bash
ls -lh document_extractor-*.difypkg

# macOS 校验和；Linux 可使用 sha256sum
shasum -a 256 document_extractor-offline-amd64.difypkg

# 查看包内架构声明、离线参数及依赖文件
unzip -p document_extractor-offline-amd64.difypkg manifest.yaml
unzip -p document_extractor-offline-amd64.difypkg requirements.txt
unzip -l document_extractor-offline-amd64.difypkg
```

打包时的依赖解析检查不等同于目标 Linux 环境的运行验证，导入后应使用实际文档确认提取和 OCR 结果。

## 本地开发

```bash
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -m unittest discover -s tests -v
```