ocr-run

OCR 执行 — 历史文献专用双引擎

Task

把清理过的 PDF 交给 OCR API，拿回 Markdown + 附件 + 对照预览 HTML。

为什么支持两个引擎：

• MinerU（上海 AI Lab）：对繁体、竖排、古籍版式、公式、表格识别更强，默认推荐。
• 百度 OCR：稳定、额度大、响应快，适合大批量现代简体论文。

~/.env 里的 OCR_ENGINE=mineru 或 OCR_ENGINE=baidu 决定默认引擎。命令行 --engine=xxx 可临时覆盖。

输出结构（权威规范见插件 references/workspace-layout.md）：

<pdf-basename>.ocr/
├── README.md                    自动生成的目录地图（workspace_readme.py）
├── source.pdf                   被 OCR 的 PDF（prep-scan 的 cleaned.pdf 副本，或用户直接传入）
├── raw.md                       OCR 原始 Markdown（含 <!-- page N --> 标记）
├── meta.json                    引擎、耗时、页数、low_confidence_pages
├── assets/                      OCR 抽出的图片附件（古籍插图、论文图表）
├── previews/
│   └── ocr-preview.html         原图 + OCR 文本并排。人工协作模式下可点击右栏编辑
├── _internal/                   Pipeline 簿记（MinerU 原生 full.md、导入 provenance）
└── ...                          其他 skill 会继续填充 review/ prep/ output/

raw.md / meta.json / assets/ 在根目录，下游（proofread / diff-review / to-docx）读相对路径 assets/xxx.png 不需修改；过程产物（HTML 预览、簿记文件）全部收进子目录。

Process

Step 0：决定走哪条路径（默认本地 mineru CLI）

Agent 默认走 run_mineru.py（本地 mineru[pipeline]），不再按 OCR_ENGINE 环境变量选云 API：

which mineru   # 检查 mineru CLI 是否在 PATH

判断：

条件	路径
mineru 在 PATH	路径 A：run_mineru.py 本地跑
mineru 没装	路径 B：提示 pip install 'mineru[pipeline]' 或跑 /collate:setup
离线 / 环境装不上 / PDF 有可用文字层且用户急	路径 D：extract_text_layer.py 兜底（质量会打折）

具体四条路径的决策语义与失败兜底全文见 agents/ocr-pipeline-operator.md——ocr-run skill 只负责调脚本，不重复 决策逻辑。

旧的 OCR_ENGINE=baidu|mineru 环境变量仍然被 mineru_client.py / baidu_client.py 读，但新工作流不走这两个——它们是兼容分支。

Step 1（已合并到 Step 0）

Step 2：建输出目录

支持两种输入形态（任选其一，脚本自动适配）：

• 形态 A：<workspace>/source.pdf（prep-scan 已跑过，工作区已存在）
• 形态 B：任意 PDF 路径（用户跳过 prep-scan 直接 OCR，没有预处理痕迹）

PDF="<input-pdf-path>"
DIR=$(dirname "$PDF")

# 如果传入的是 .ocr/source.pdf，OUT 就是它的上级目录（工作区已存在）
# 否则按 basename 建新的 .ocr/ 工作区
if [[ "$DIR" == *.ocr ]]; then
    OUT="$DIR"
else
    BASE=$(basename "$PDF" .pdf)
    OUT="$DIR/$BASE.ocr"
fi
mkdir -p "$OUT/assets" "$OUT/previews" "$OUT/_internal"
# 确保 source.pdf 在根目录（外部传入时复制一份）
[ -f "$OUT/source.pdf" ] || cp "$PDF" "$OUT/source.pdf"