# OpenClaw技能：将文档转换为Markdown文本

**Repository Path**: low-code-dev-lab/openclaw-skill-convert-document-to-markdown

## Basic Information

- **Project Name**: OpenClaw技能：将文档转换为Markdown文本
- **Description**: 提供知识库建设所需的基本功能，全CPU实现。

功能特性：
- 文件转文本：PDF、Word、Excel、PowerPoint、图片、HTML 等格式（图片识别模式： OCR、VL）
- 文本切块：BERT Chunker Chinese 2
- 文本嵌入：multilingual-e5-small
- 文本排序：gte-multilingual-reranker-base
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-03-27
- **Last Updated**: 2026-03-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文档转 Markdown CLI

将本地 PDF、Office 文档、图片和文本文件转换为 Markdown。当前仅支持通过 Docker 运行，不支持直接在宿主机上以本地 Python 方式作为正式运行路径。

## 功能

- 支持的文档格式为：`.pdf`、`.docx`、`.pptx`、`.xlsx`、`.jpg`、`.jpeg`、`.png`、`.gif`、`.bmp`、`.txt`、`.json`、`.xml`、`.md`
- 图片识别模式按文件类型区分支持范围：PDF 支持 `ocr` / `vl` / `vl-page` / `none`；Office 与图片文件不支持 `vl-page`
- 默认以 JSON 输出转换结果，便于被 OpenClaw skill 或其他自动化流程消费
- 仅处理本地文件路径，不再提供 URL、health、version 子命令
- 仅通过 Docker 镜像运行；运行脚本会按宿主机架构选择 `convert-document-to-markdown-arm64:0.0.1` 或 `convert-document-to-markdown-x64:0.0.1`

## 快速开始

### 1. 直接使用阿里云 CR 镜像

```bash
docker pull crpi-4auaoyyj6r36p6lb.cn-hangzhou.personal.cr.aliyuncs.com/huozige_lab/convert-document-to-markdown-x64:0.0.1
```

脚本默认使用以下阿里云 CR 前缀：

`crpi-4auaoyyj6r36p6lb.cn-hangzhou.personal.cr.aliyuncs.com/huozige_lab`

并根据宿主机架构自动选择镜像名：

- `arm64` 主机：`convert-document-to-markdown-arm64:0.0.1`
- `x64` 主机：`convert-document-to-markdown-x64:0.0.1`

对应的手工拉取命令示例：

```bash
docker pull crpi-4auaoyyj6r36p6lb.cn-hangzhou.personal.cr.aliyuncs.com/huozige_lab/convert-document-to-markdown-x64:0.0.1
docker pull crpi-4auaoyyj6r36p6lb.cn-hangzhou.personal.cr.aliyuncs.com/huozige_lab/convert-document-to-markdown-arm64:0.0.1
```

如果你需要覆盖默认地址，也可以直接设置 `IMAGE_REGISTRY` 或 `IMAGE_NAME`。

### 2. 一次性配置 VL 变量

如果你需要 `vl` 或 `vl-page`，先复制 `.env.example` 为 `.env`，填入以下三个值：

```bash
cp .env.example .env
```

需要配置的核心变量：

- `VL_BASE_URL`
- `VL_API_KEY`
- `VL_MODEL`

之后推荐通过仓库脚本执行。脚本会自动读取仓库根目录的 `.env`，把当前 shell 里的同名环境变量透传进容器，并在本机缺少镜像时自动 `docker pull` 对应架构的固定版本镜像。

### 3. 处理本地文件

Linux / macOS:

```bash
scripts/run_docker_cli.sh file ./example.pdf --image-process-model ocr
```

Windows:

```bat
scripts\run_docker_cli.bat file .\example.pdf --image-process-model ocr
```

## CLI 用法

### `file`

Linux / macOS:

```bash
scripts/run_docker_cli.sh file ./example.pdf \
  --image-process-model ocr \
  --format json
```

Windows:

```bat
scripts\run_docker_cli.bat file .\example.pdf --image-process-model ocr --format json
```

## 输出格式

默认输出 JSON：

```json
{
  "success": true,
  "source_type": "file",
  "source": "/work/example.pdf",
  "name": "example.pdf",
  "image_process_model": "ocr",
  "markdown": "# 文档内容",
  "logs": [
    "========== 开始处理请求 ==========",
    "--- 步骤2: 转换为Markdown ---"
  ],
  "meta": {
    "elapsed_ms": 1234,
    "file_type": ".pdf",
    "output_path": "/work/example.md",
    "log_file": "/work/example.log"
  },
  "error": null
}
```

如果需要直接输出 Markdown：

```bash
scripts/run_docker_cli.sh file ./example.pdf --format markdown
```

如果你需要把 Markdown 或日志落到宿主机文件，直接使用 `docker run` 并显式挂载可写目录，例如：

```bash
docker run --rm \
  --env-file .env \
  -v "$PWD:/work" \
  crpi-4auaoyyj6r36p6lb.cn-hangzhou.personal.cr.aliyuncs.com/huozige_lab/convert-document-to-markdown-x64:0.0.1 \
  file /work/example.pdf \
  --output /work/example.md \
  --log-file /work/example.log
```

## 支持格式

| 格式 | 扩展名 | 图片识别 |
|---|---|---|
| PDF | `.pdf` | `ocr` / `vl` / `vl-page` / `none` |
| Word | `.docx` | `ocr` / `vl` / `none` |
| PowerPoint | `.pptx` | `ocr` / `vl` / `none` |
| Excel | `.xlsx` | `ocr` / `vl` / `none` |
| 图片 | `.jpg`, `.png`, `.jpeg`, `.gif`, `.bmp` | `ocr` / `vl` / `none` |
| 文本 | `.txt`, `.json`, `.xml`, `.md` | 不涉及 |

### 图片支持说明

- 纯图片文件仅支持 `.jpg`、`.jpeg`、`.png`、`.gif`、`.bmp`
- `ocr` 模式依赖 `tesseract`；Docker 镜像内已安装，本地运行需自行安装并确保命令在 `PATH` 中
- `vl` 模式依赖 `VL_API_KEY`、`VL_BASE_URL`、`VL_MODEL`；未配置时会回退到 OCR
- 图片文件不支持 `vl-page`；如果传入该模式，会自动回退到 `vl`
- 对于纯图片文件，如果 OCR 或 VL 调用失败，CLI 会返回失败结果，而不是把错误文本当作 Markdown 正文

### 不在当前支持范围内的格式

- 旧版 Office 二进制格式 `.doc`、`.ppt`、`.xls` 不支持
- 音频格式 `.wav`、`.mp3`、`.m4a`、`.mp4` 目前不应视为稳定支持范围的一部分
- `webp`、`tiff`、`svg`、`heic` 等图片格式未接入当前 CLI 的显式分发逻辑
- `latest` 不是受支持的镜像标签；请固定使用 `0.0.1`

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `IMAGE_REGISTRY` | `crpi-4auaoyyj6r36p6lb.cn-hangzhou.personal.cr.aliyuncs.com/huozige_lab` | 阿里云 CR 仓库前缀。脚本会自动拼出按架构区分的镜像地址 |
| `IMAGE_NAME` | 空 | 完整 Docker 镜像地址。设置后优先级高于 `IMAGE_REGISTRY` |
| `IMAGE_VERSION` | `0.0.1` | 运行脚本使用的固定镜像版本 |
| `IMAGE_ARCH` | 自动检测 | 运行脚本使用的镜像架构，支持 `arm64` / `x64` |
| `VL_BASE_URL` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | Vision API 地址 |
| `VL_API_KEY` | 空 | Vision API 密钥 |
| `VL_MODEL` | `qwen-vl-plus` | Vision 模型名称 |
| `VL_API_TIMEOUT` | `300` | Vision API 请求超时，单位秒 |
| `VL_PAGE_TARGET_WIDTH` | `2400` | PDF 页面截图目标宽度 |
| `VL_PAGE_MIN_ZOOM` | `1.2` | PDF 页面截图最小缩放比例 |
| `VL_PAGE_MAX_ZOOM` | `5.0` | PDF 页面截图最大缩放比例 |

## 镜像构建

正式运行不支持本地 Python 直接执行；如需维护镜像，可使用 Docker 构建脚本。

Linux / macOS:

```bash
make build
make example
```

或直接执行：

```bash
scripts/build_image.sh
```

Windows:

```bat
dev.bat build
dev.bat example
```

## OpenClaw / ClawHub 配置

如果这个仓库作为 OpenClaw skill 使用，推荐把配置写到 `~/.openclaw/openclaw.json` 的 `skills.entries.convert_document_to_markdown` 下。OpenClaw 官方文档说明了两点：

- `skills.entries.<skillKey>.env` 可为 skill 注入环境变量
- `skills.entries.<skillKey>.apiKey` 可配合 skill 的 `primaryEnv` 一次性保存主密钥

可参考如下结构：

```json
{
  "skills": {
    "entries": {
      "convert_document_to_markdown": {
        "enabled": true,
        "apiKey": "sk-xxx",
        "env": {
          "VL_BASE_URL": "https://api.openai.com/v1",
          "VL_MODEL": "gpt-4.1-mini"
        }
      }
    }
  }
}
```

在当前 skill 里：

- `apiKey` 会映射到 `VL_API_KEY`
- `env` 里的 `VL_BASE_URL` 和 `VL_MODEL` 会通过包装脚本自动透传到容器