/legal-ocr

name: legal-ocr
description: 本技能应在用户需要 OCR、扫描识别、图片文字识别、文档识别，或将 PDF、图片、Office 文档、URL 转换为 Markdown 时使用。检测到法律材料时可进行保守的法律术语与文书结构优化。不要用于法律事实判断、补写缺失内容、语义改写、印章深度识别或图表实体分析。
version: "1.6.0"
license: MIT
author: 杨卫薪律师（微信ywxlaw）
homepage: https://github.com/cat-xierluo/legal-skills

Legal OCR

本技能用于 OCR、扫描识别、图片文字识别、文档识别，以及把 PDF、图片、Office 文档和 URL 转换为可继续编辑、分析和归档的 Markdown。它首先是通用 OCR 入口；当结果被识别为法律材料时，再自动启用保守型法律后处理。默认使用配置优先的自动路由：

• 本地 PDF 默认先探测原生文本层：法院电子送达判决书、电子合同、政府公文等带可靠文本层的 PDF 直读比 OCR 更准、更快、更省额度。质量达标直接抽文字转 Markdown；不达标才落回 OCR。详见「PDF 文本层双路径」。
• 只配置 PaddleOCR：PaddleOCR 支持的 PDF / 图片优先走 PaddleOCR；超出能力边界时再提示或改走 MinerU 支持链路。
• 只配置 MinerU Token：所有 MinerU 支持的输入统一走 MinerU，包含 PDF、图片、Office、远程文档 URL 和网页 URL。
• 同时配置两套 API：本地 PDF / 图片优先 PaddleOCR，Office / 网页 URL 优先 MinerU；首选后端出现额度、频率、鉴权、网络或服务失败时自动尝试候选后端。
• 本机已安装 RapidOCR 时，本地 PDF / 图片把本地 RapidOCR 作为云端失败后的最后一级候选。
• 两套 API 都未配置：本机已装 RapidOCR 时优先本地识别（材料不出本机），MinerU 轻量接口退为兜底；未装 RapidOCR 时使用 MinerU 轻量接口处理小文件，并在超限时提示补充 Token。
• 敏感材料不允许外传时，显式使用 `--backend rapid`（本地 onnx 推理，全程不出本机）。

旧的 `paddle-ocr` 和 `mineru-ocr` 保持可用；本技能是新的统一入口，目标是覆盖两者的常用 OCR/转换场景。

何时使用

在以下场景使用本技能：

• 用户明确需要 OCR、扫描识别、图片文字识别或文档识别。
• 输入可能是 PDF、图片、Office 文档、远程文档 URL 或网页 URL，并希望转成 Markdown。
• 希望保留 archive，便于复核原文件、后端结果、Markdown 和图片资源。
• 需要自动选择 OCR 后端，而不是手动判断该用 PaddleOCR 还是 MinerU。
• 希望非法律材料保持通用 OCR 输出，法律材料再做术语和文书结构优化。

不优先使用本技能的场景：

• 只需要快速读取一小段清晰文本，且不需要 Markdown 文件和归档。
• 需要基于上下文改写事实、补充缺失信息、印章深度标注或图表语义分析；这些能力仍在后续计划中。

依赖

系统依赖

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

Python 包

脚本使用 `uv run` 执行，依赖写在脚本头部；推荐直接使用 `uv run scripts/convert.py`，无需单独维护 `requirements.txt`。

| 包名 | 用途 | 安装命令 | |------|------|----------| | `httpx` | 调用 PaddleOCR 与 MinerU API | `pip install httpx` | | `pypdfium2` | 读取 PDF 页数与拆分页码范围 | `pip install pypdfium2` | | `rapidocr` + `onnxruntime` | 可选：本地 RapidOCR 后端（`--backend rapid`） | `uv run --with rapidocr --with onnxruntime scripts/convert.py ...` 或 `pip install rapidocr` |

如直接用 `python scripts/convert.py` 运行且缺少依赖，脚本会给出安装提示。

本地 RapidOCR 后端能力边界

• 只有文字检测+识别，没有版面分析：段落由统一后处理链重建，单栏文书（判决书、合同扫描件等）可靠，多栏版面可能错序。
• 不提取图片资源：印章、签名、图表不会出现在 Markdown 里。
• Office 文档与 URL 不支持（仍走 MinerU）。
• 渲染 DPI 默认 220，可用 `LEGAL_OCR_RAPID_DPI` 调整；置信度阈值 `LEGAL_OCR_RAPID_MIN_SCORE`（默认 0.5）。

首次配置

复制配置模板：

cd legal-ocr/config
cp .env.example .env
nano .env

可选配置：

• PaddleOCR：填写 `PADDLEOCR_DOC_PARSING_API_URL` 和 `PADDLEOCR_ACCESS_TOKEN`。
• MinerU Token：填写 `MINERU_API_TOKEN`；不填时小文件默认走 MinerU 轻量接口。
• 自动路由：保持 `LEGAL_OCR_BACKEND=auto`。
• 法律术语优化：保持 `LEGAL_OCR_LEGAL_TERMS=auto`，只在检测到法律材料时启用；如需强制启用可设为 `true`，如需关闭可设为 `false`。
• 通用硬换行优化：保持 `LEGAL_OCR_LINE_MERGE=true`；如需加载自定义法律术语，设置 `LEGAL_OCR_CUSTOM_TERMS_PATH`。

本技能也会尝试读取环境变量和 `~/.mineru/config.yaml` 中的 MinerU Token。 PaddleOCR 也兼容 `pdf-processor` 使用的 `PADDLE_OCR_API_ENDPOINT` / `PADDLE_OCR_API_KEY`，并支持 `/api/v2/ocr/jobs` 异步任务接口。

常用命令

在技能根目录运行：

uv run scripts/convert.py "/path/to/file.pdf"
uv run scripts/convert.py "/path/to/file.pdf" --pages "1-20"
uv run scripts/convert.py "/path/to/file.pdf" --backend paddle
uv run scripts/convert.py "/path/to/file.pdf" --backend paddle --paddle-model PaddleOCR-VL-1.5
uv run scripts/convert.py "https://example.com/document.pdf" --backend auto
uv run scripts/convert.py "https://example.com/article" --backend mineru
uv run scripts/convert.py "/path/to/judgment.pdf" --legal-terms always
uv run scripts/convert.py checktoken

敏感材料本地识别（不出本机）：

uv run --with rapidocr --with onnxruntime scripts/convert.py "/path/to/scan.pdf" --backend rapid

兼容 JXA 入口：

/usr/bin/osascript -l JavaScript scripts/convert.js "/path/to/file.pdf"

可选参数：

| 参数 | 说明 | |------|------| | `--backend auto|paddle|mineru|rapid` | 指定后端；默认读取 `LEGAL_OCR_BACKEND`，未配置时为 `auto`。`rapid` 为本地 RapidOCR（onnx 推理，不出本机） | | `--text-layer auto|never|always` | PDF 原生文本层分支；默认 `auto`，达标则直读跳过 OCR；`never` 强制走 OCR；`always` 强制文本层，不可用即失败 | | `--output <path>` | 输出 Markdown 路径或目录 | | `--pages <spec>` | 页码范围，如 `1-20`、`1-5,8,10-12` | | `--archive-name <name>` | 自定义 archive 目录名 | | `--no-archive` | 不写入 archive | | `--no-post-process` | 跳过全部后处理 | | `--no-legal-terms` | 跳过法律术语优化 | | `--legal-terms auto|always|never` | 法律术语优化模式；默认 `auto` | | `--no-line-merge` | 跳过 OCR 硬换行整理 | | `--model pipeline|vlm` | MinerU Token API 模型 | | `--paddle-model PP-OCRv5|PaddleOCR-VL-1.5` | PaddleOCR 异步任务模型 | | `--paddle-api-protocol auto|sync|async` | PaddleOCR API 协议 | | `--paddle-api-extra-json <path>` | 合并额外 PaddleOCR optionalPayload |

PaddleOCR 同步接口会校验后端实际返回页数。若返回页数少于本地 PDF 批次页数，转换会失败并提示降低 `PADDLEOCR_BATCH_PAGES` 或使用 `--pages` 重跑，避免缺页结果被误当作成功。

PDF 文本层双路径

本地 PDF 进入 OCR 后端之前，会先探测是否带可用的原生文本层（v1.5.0+）。这是法律场景里的高频优化：法院电子送达判决书、电子合同、政府公文等 PDF 通常已带可靠文本层，直读比 OCR 更准、更快、不耗 API 额度。

工作流

1. 仅本地 `.pdf` 触发；图片、Office、URL 不参与。 2. 用 `pypdfium2` 逐页抽取文字，计算 4 个指标：文本页覆盖率、平均 CJK / 页、乱码比例（PUA + 替换字符 + 非常见字符）、总字符数。 3. 全部阈值达标 → 直接转 Markdown，复用既有 post-process（法律术语 → 硬换行整理 → 基础清理）。 4. 任一不达标 → 落回原有 OCR 候选（PaddleOCR → MinerU），完全兼容旧工作流。

模式（CLI `--text-layer` 或 env `LEGAL_OCR_TEXT_LAYER`）

| 模式 | 行为 | |------|------| | `auto`（默认） | 探测后达标走文本层，不达标回退 OCR | | `never` | 完全禁用文本层，回到旧版纯 OCR 行为 | | `always` | 强制走文本层；不可用时直接 exit=2 失败，便于排障 |

与 `--backend` 的优先级

• `--backend auto` + `--text-layer auto`：最优路径，先文本层、不达标再 OCR。
• `--backend paddle|mineru`：视为用户显式想要 OCR，跳过文本层分支（除非同时设 `--text-layer always` 强制覆盖）。

阈值（保守默认，理想值待真实卷宗校准）

| env | 默认 | 含义 | |-----|------|------| | `LEGAL_OCR_TEXT_LAYER_MIN_COVERAGE` | `0.8` | 文本页占探测页比例下限 | | `LEGAL_OCR_TEXT_LAYER_MIN_CHARS_PER_PAGE` | `50` | 文本页平均 CJK 字符下限 | | `LEGAL_OCR_TEXT_LAYER_MAX_GARBLE_RATIO` | `0.05` | PUA + 替换字符 + 非常见字符占比上限 | | `LEGAL_OCR_TEXT_LAYER_MIN_TOTAL_CHARS` | `100` | 非空白字符总数下限 |

阈值默认值的理由见 `references/text-layer-detection.md` 与 `DECISIONS.md`。如果你拿到一批真实卷宗发现误判（例如应该走 OCR 的 PDF 走了文本层，或反之），把指标和样本反馈给维护者，再调阈值或加新规则。

archive 记录

无论是否走文本层，PDF 输入都会在 `metadata.json` 留下 `text_layer` 字段：

• 走了文本层：`enabled=true` + `probe` 全量指标（页数、coverage、garbled_ratio、阈值快照）。