# 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**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-18
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: dify

## README

# Dify 文档提取器

支持 `.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。

```bash
python -m pip install -r requirements.txt
python -m unittest discover -s tests -v
```

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

## 打包与部署

### 在线打包（推荐用于可联网的 Dify 环境）

在线包只包含插件源码和 `requirements.txt`；导入到 Dify 后，由目标环境从其配置的软件源安装与自身架构匹配的依赖。

```bash
# 在插件根目录执行；首次运行会下载官方 Dify CLI 到 .dify-cli/
./scripts/package_online.sh

# 指定输出包路径
./scripts/package_online.sh /path/to/output.difypkg
```

可用环境变量：`DIFY_CLI`（指定已有 CLI 路径）、`PYTHON_BIN`（默认 `python3`）和 `MAX_SIZE_MB`（默认 `5120`）。

### 离线打包（ARM64 平台）

在可联网的构建机上执行离线打包脚本；生成的包可带到不能联网的 Dify 环境导入。脚本以插件根目录为工作目录，不再需要指定旧的 `python_dify/` 子目录。

```bash
# 在插件根目录执行
cd /Users/liuyang/Desktop/dify-doc2md

# 首次执行会下载 Dify 官方 GitHub Release 中与当前系统匹配的 CLI；构建机需要能访问 GitHub 与 PyPI
./scripts/package_offline_arm64.sh

# 指定输出包路径
./scripts/package_offline_arm64.sh /path/to/output.difypkg
```

**脚本参数说明：**

| 参数         | 说明       | 默认值                                       |
| ------------ | ---------- | -------------------------------------------- |
| `output_pkg` | 输出包路径 | `./document_extractor-offline-arm64.difypkg` |

**环境变量：**

| 变量            | 说明                                 | 默认值    |
| --------------- | ------------------------------------ | --------- |
| `PYTHON_BIN`    | Python 解释器路径                    | `python3` |
| `PIP_INDEX_URL` | 可选的 PyPI 镜像地址（仅构建时使用） | -         |
| `MAX_SIZE_MB`   | 包大小上限（MB）                     | `5120`    |

**脚本会自动：**

1. 下载 Dify 官方 GitHub Release 的 CLI 到 `.dify-cli/`（仅首次需要；macOS 会验证代码签名）
2. 复制插件源码（自动排除虚拟环境、缓存和历史构建物）
3. 下载 Linux ARM64 / Python 3.12 的二进制 wheel
4. 验证依赖可以从本地 wheel 安装
5. 写入离线安装参数（`--no-index --find-links=./wheels`）
6. 生成 `.difypkg` 包并计算 SHA256 校验

**生成的离线包可直接在 Dify 控制台导入，无需额外操作。**

### 架构兼容性

`package_online.sh` 生成的在线包不携带架构相关的 wheel，`manifest.yaml` 已声明支持 `amd64` 和 `arm64`。因此，只要目标是满足插件最低版本要求的 Linux Dify 环境、使用 Python 3.12 runner，并且能从其 Python 软件源安装依赖，同一个在线包可用于这两种架构。

它并非对所有环境通用：离线包仍固定为 ARM64；不满足 Dify、Linux runner、Python 版本或依赖软件源要求的环境不能保证可用。

### 验证打包结果

```bash
# 查看包大小
ls -lh *.difypkg

# 验证校验和（脚本输出中包含）
shasum -a 256 *.difypkg

# 解压查看包内容（可选）
unzip -l document_extractor.difypkg
```

### 注意事项

1. **平台兼容性**：离线包默认针对 `manylinux_2_28_aarch64` + `manylinux2014_aarch64` 平台，确保目标服务器为 ARM64 架构
2. **Python 版本**：离线包使用 Python 3.12，目标服务器需要安装相同版本
3. **包大小限制**：默认上限 5120MB，可通过 `MAX_SIZE_MB` 环境变量调整
4. **签名验证**：如果 Dify 开启签名验证，离线包需要重新签名