📦 PaddleOCR — 法律PDF转Markdown

v1.1.1

面向法律 PDF 与扫描件的 PaddleOCR 结构化解析技能。默认将本地 PDF 或图片转换为 Markdown，并在技能内部保留可追溯 archive 归档。本技能应在用户需要法律 PDF OCR、卷宗 OCR、病历 OCR、证据扫描件转 Markdown、表格识别、公式识别、版面分析、PDF 转 Markdown、复杂 PDF 解析时使用。

0· 32·0 当前·0 累计

by @cat-xierluo (xierluo)·MIT-0

生产力工具

下载技能包

License

MIT-0

最后更新

2026/4/15

安全扫描

VirusTotal

无害

查看报告

OpenClaw

安全

high confidence

技能代码和指令与其声明的用途匹配（法律文档OCR → Markdown + archive）；主要问题是注册表元数据与所需环境变量的不匹配，以及文档上传到配置的外部PaddleOCR端点的隐私风险。

评估建议

该技能似乎做到了它所声称的功能：将PDF/图像转换为Markdown并保留本地归档，调用必须配置的PaddleOCR布局解析API。在用于敏感文档之前：1) 修复注册表/配置不匹配——SKILL.md和lib.py需要PADDLEOCR_DOC_PARSING_API_URL和PADDLEOCR_ACCESS_TOKEN（在paddle-ocr/config/.env中创建）。2) 验证API URL指向您信任的服务（自托管或可信提供商）。该工具将完整文档（Base64）上传到该端点，并在Authorization头中携带令牌。3) 首先运行smoke_test.py（尝试--skip-api-test检查配置，然后使用非敏感样本确认端点行为）。4) 如果隐私至关重要，优先选择本地/自托管PaddleOCR布局解析端点（或localhost），以确保数据不会离开您的环境。5) 注意'uv'将在运行时通过PyPI安装Python依赖；如果您的环境有严格策略，请检查依赖项。最后，查看repo/homepage和.env.example以确认配置的端点和令牌处理符合您的安全/合规要求。...

详细分析 ▾

ℹ 用途与能力

该技能被宣传为基于PaddleOCR的法律PDF转Markdown转换器，包含的脚本（convert.py、layout_caller.py、lib.py等）实现了这一功能。lib.py中的环境变量和请求/响应处理与其声明的用途一致（PADDLEOCR_DOC_PARSING_API_URL和PADDLEOCR_ACCESS_TOKEN）。然而，注册表元数据声称'Required env vars: none'，而SKILL.md和lib.py明确要求两个PaddleOCR配置变量——这种不一致可能会在安装/配置期间误导用户。

ℹ 指令范围

运行时指令范围包括：读取本地文件或远程URL、调用配置的PaddleOCR布局解析API（发送文件Base64或文件URL）、提取Markdown和图像，以及在技能的archive/文件夹下写入归档。这与其目的一致。重要的隐私/安全含义：脚本会将整个文档（Base64有效载荷）上传到您配置的API URL，因此敏感的法律或医疗文档将被传输到该端点。脚本不会尝试读取无关的系统文件或其他凭据。

✓ 安装机制

没有注册表安装规范（仅指令），仓库提供Python脚本。执行使用'uv run --script'头来声明依赖；SKILL.md要求用户在需要时安装'uv'。注册表未定义任意网络下载或打包安装程序。注意：运行脚本将在运行时通过uv/PyPI安装Python包——这是标准做法，但值得注意。

⚠ 凭证需求

该技能合理地需要两个环境/配置值：PADDLEOCR_DOC_PARSING_API_URL和PADDLEOCR_ACCESS_TOKEN（在SKILL.md中声明并由lib.py强制执行）。这些与功能相称。令人担忧的是与注册表元数据的不匹配，注册表元数据列出了no required env vars——这种遗漏可能导致用户在没有意识到需要配置API端点和令牌的情况下运行技能，从而无意中向意外的端点发送数据。该技能不会请求无关的凭据或广泛的环境访问。

✓ 持久化与权限

该技能不请求'always: true'或其他提升的平台特权。它只写入技能根目录下的归档目录和用户指定的输出路径。它不会修改其他技能或全局代理配置。

安全有层次，运行前请审查代码。

License

MIT-0

可自由使用、修改和再分发，无需署名。

查看条款 ↗

运行时依赖

无特殊依赖

版本

latestv1.1.12026/4/15

面向法律 PDF 与扫描件的 PaddleOCR 结构化解析，支持表格识别、公式识别、版面分析，保留 archive 归档

● 无害

安装命令

点击复制

官方npx clawhub@latest install paddle-ocr

镜像加速npx clawhub@latest install paddle-ocr --registry https://cn.longxiaskill.com镜像同步中

需要定制？告诉我你的需求 →

技能文档

本技能服务于法律材料 OCR。默认目标不是返回一段临时文本，而是：

将本地 PDF / 图片转换为可继续编辑和分析的 Markdown。
在 archive/ 下保留完整归档，便于复核、追溯和二次处理。

何时使用

在以下场景使用本技能：

需要把卷宗、病历、证据材料、法院通知、财报、票据等扫描 PDF 转成 Markdown。
文档包含表格、印章、页眉页脚、多栏排版、公式或复杂版面。
希望保留一个技能内的 archive，沉淀原文件、Markdown、结构化 JSON 和批次结果。
后续还要继续做法律分析、证据摘录、知识入库或 RAG 切片。

在以下场景不要优先使用本技能：

只是快速读取一小段清晰文本，且不需要 Markdown 和归档。
只是截图抄字，速度比结构化质量更重要。
输入不是 PDF / 常见图片格式。

主产出

默认主产出只有两类：

Markdown 文件：保存在源文件同目录，默认与原文件同名、扩展名为 .md
archive 归档目录：保存在 paddle-ocr/archive/时间戳_文件名/

archive 默认包含：

原始输入文件副本
最终 result.md
最终 result.json
批次级 batches/.json

提取出的图片资源

metadata.json

依赖

系统依赖

依赖	安装方式
`python3`	macOS 通常已内置
`uv`	macOS: `brew install uv`

Python 包
脚本使用 uv run 执行，依赖写在脚本头部，无需单独维护 requirements.txt。
首次配置
获取 API 信息
打开 PaddleOCR 官网

进入对应模型的 API 页面

在示例代码中复制：

- API_URL - Access Token
配置方式
优先编辑 config/.env：
cd paddle-ocr/config cp .env.example .env nano .env
必填项：
PADDLEOCR_DOC_PARSING_API_URL

PADDLEOCR_ACCESS_TOKEN
常用命令
主工作流：生成 Markdown + archive
在技能根目录运行：
uv run scripts/convert.py "/path/to/legal-document.pdf"
或继续兼容旧入口：
/usr/bin/osascript -l JavaScript scripts/convert.js "/path/to/legal-document.pdf"
可选参数：
uv run scripts/convert.py "/path/to/legal-document.pdf" --pages "1-20" uv run scripts/convert.py "/path/to/legal-document.pdf" --output "/tmp/output.md" uv run scripts/convert.py "/path/to/legal-document.pdf" --archive-name "某案卷宗-证据一"
底层调试：只调用解析接口，输出结构化 JSON
uv run scripts/layout_caller.py --file-path "/path/to/legal-document.pdf" --pretty uv run scripts/layout_caller.py --file-url "https://example.com/document.pdf" --stdout --pretty
当你只想检查原始接口结果，或后续要自己解析表格/坐标信息时，使用这个底层脚本。
自检
uv run scripts/smoke_test.py --skip-api-test uv run scripts/smoke_test.py
拆分页码
uv run scripts/split_pdf.py input.pdf output.pdf --pages "1-5,8,10-12"
法律 PDF 工作流
按以下顺序工作：
优先使用 scripts/convert.py。

如只需部分页码，先传 --pages，避免整卷上传。

对大体量卷宗，脚本会按配置自动分批请求，再合并为一个 Markdown。

需要复核时，到 archive/ 查看：

- output/result.md - output/result.json - metadata.json - batches/.json

大文件策略

本技能为了法律材料的稳定性，默认采用保守批次策略：

PDF 页数超过 PADDLEOCR_BATCH_PAGES 时自动分批
预估 Base64 大小超过 PADDLEOCR_MAX_BASE64_MB 时自动分批

这意味着它可能比官方上限更早拆分，但通常能降低长卷宗、病历合并件和扫描质量不稳定文档的失败率。

输出说明

Markdown

默认保存到源文件同目录
如果传 --output 且是 .md 文件路径，则保存到指定路径
如果 --output 是目录，则在该目录下生成同名 .md

配置项

编辑 config/.env：

选项	默认值	说明
`PADDLEOCR_DOC_PARSING_API_URL`	空	官方要求的完整 `layout-parsing` 端点
`PADDLEOCR_ACCESS_TOKEN`	空	官方 Access Token
`PADDLEOCR_DOC_ORIENTATION`	`false`	是否启用方向分类
`PADDLEOCR_DOC_UNWARP`	`false`	是否启用去扭曲
`PADDLEOCR_CHART_RECOG`	`false`	是否启用图表识别
`PADDLEOCR_DOC_PARSING_TIMEOUT`	`600`	单次请求超时秒数
`PADDLEOCR_BATCH_PAGES`	`40`	PDF 自动分批页数阈值兼批次大小
`PADDLEOCR_MAX_BASE64_MB`	`20`	触发分批的保守大小阈值
`PADDLEOCR_LOG_LEVEL`	`medium`	`low` / `medium` / `high`

结果结构

如果需要理解底层 JSON 包装格式，读取：

references/output_schema.md

故障排除

问题	解决方式
未配置 API	先补 `config/.env`，再执行 `uv run scripts/smoke_test.py --skip-api-test`
403 / Token 错误	更新 `PADDLEOCR_ACCESS_TOKEN`
请求超时	调大 `PADDLEOCR_DOC_PARSING_TIMEOUT`，或减少页码范围
大 PDF 失败	使用 `--pages` 缩小范围，或让脚本自动分批
Markdown 为空	到 `archive/` 查看 `batches/.json` 和 `metadata.json`，确认是否原文件质量过差
需要看原始坐标和表格结构	使用 `scripts/layout_caller.py`，并读取 `result.result.layoutParsingResults[].prunedResult`

维护建议

修改本技能后，同步更新：

CHANGELOG.md

数据来源：ClawHub ↗ · 中文优化：龙虾技能库