面向法律 PDF 与扫描件的 PaddleOCR 结构化解析技能。默认将本地 PDF 或图片转换为 Markdown，并在技能内部保留可追溯 archive 归档。适用于卷宗、病历、证据材料、发票、财报、复杂扫描件、表格密集文档、公式与多栏版面。触发词包括：法律 PDF OCR、卷宗 OCR、病历 OCR、证据扫描件转 Markdown、PaddleOCR、表格识别、公式识别、版面分析、PDF 转 Markdown、复杂 PDF 解析。
本技能服务于法律材料 OCR。默认目标不是返回一段临时文本，而是：
archive/ 下保留完整归档，便于复核、追溯和二次处理。在以下场景使用本技能：
在以下场景不要优先使用本技能：
默认主产出只有两类：
.mdpaddle-ocr/archive/时间戳_文件名/archive 默认包含：
result.mdresult.jsonbatches/*.jsonmetadata.json| 依赖 | 安装方式 |
|---|---|
python3 | macOS 通常已内置 |
uv | macOS: brew install uv |
脚本使用 uv run 执行，依赖写在脚本头部，无需单独维护 requirements.txt。
API_URLAccess Token优先编辑 config/.env：
cd paddle-ocr/config
cp .env.example .env
nano .env
必填项：
PADDLEOCR_DOC_PARSING_API_URLPADDLEOCR_ACCESS_TOKEN在技能根目录运行：
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 "某案卷宗-证据一"
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"
按以下顺序工作：
scripts/convert.py。--pages，避免整卷上传。archive/ 查看：
output/result.mdoutput/result.jsonmetadata.jsonbatches/*.json本技能为了法律材料的稳定性，默认采用保守批次策略：
PADDLEOCR_BATCH_PAGES 时自动分批PADDLEOCR_MAX_BASE64_MB 时自动分批这意味着它可能比官方上限更早拆分，但通常能降低长卷宗、病历合并件和扫描质量不稳定文档的失败率。
--output 且是 .md 文件路径，则保存到指定路径--output 是目录，则在该目录下生成同名 .md默认归档目录结构：
archive/
└── 20260405_153000_文件名/
├── input/
│ └── 原文件.pdf
├── output/
│ ├── result.md
│ ├── result.json
│ └── images/
├── batches/
│ ├── batch_001_1-40.json
│ └── batch_002_41-67.json
└── metadata.json
编辑 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 |
修改本技能后，同步更新：
TASKS.mdDECISIONS.mdCHANGELOG.md