扫描PDF转Markdown

概述

scanned-pdf-to-markdown — 扫描版 PDF 图书转 Markdown（Pay Skill）

把"扫描图片型 PDF 图书"变成"高质量 Markdown 文字版"，供 AI 检索、做知识库、生成 skill 使用。

核心思路：MinerU 转换（10%）+ 系统化校对（90%）。转换本身一条命令，真正的质量差异在校对——OCR 错误有高度重复的模式，用规则扫描 + 分章通读可以机械化地修掉绝大多数。

本 Skill 为 Pay Skill：每次转换需先完成微信支付验证，验证通过后按下方规则执行本地脚本。

付费前置检查

调用本 Skill 前，检查当前 Agent 是否已安装 weixinpay 插件：

• 已安装：可继续提供付费服务
• 未安装：向用户提示「当前 Agent 暂不支持微信支付付费能力」，终止流程

付费工作流程（⚠️ 必须先于转换执行）

第一步：请求付费网关

向 Pay Skill 网关发起 POST 请求（invoke_url 见 frontmatter）：

POST https://pay-skill-nat-4198535-1341112664.ap-shanghai.run.tcloudbase.com/api/skill/invoke
Content-Type: application/json

{
  "query": "用户的转换需求（如：把 /path/to/scan.pdf 转成 Markdown）",
  "skill_id": "scanned-pdf-to-markdown",
  "skill_version": "1.0.0",
  "amount_fen": 50
}

第二步：处理 402 响应

若收到 HTTP 402，从响应中提取并保存以下信息（Header 与 Body 均可能出现）：

• WeixinPay-Required：支付码（payment_code）
• X-Out-Trade-No：商户订单号

将 WeixinPay-Required 的值作为 paymentCode，调用 微信支付官方技能skill（weixinpay-pay），若遇系统繁忙等支付失败，调用mcp__weixinpay__weixinpay_retry_pay 把 paymentCode 回传给系统拉起卡片 向用户申请支付授权。

第三步：支付成功后重新请求（⚠️ 必须执行，不可跳过）

支付成功后，必须用与第一步完全一致的 JSON body 重新 POST 同一接口，并在 Header 中携带第二步保存的值：

POST https://pay-skill-nat-4198535-1341112664.ap-shanghai.run.tcloudbase.com/api/skill/invoke
Content-Type: application/json
WeixinPay-Required: <payment_code>
X-Out-Trade-No: <out_trade_no>

{
  "query": "用户的转换需求（与第一步完全一致）",
  "skill_id": "scanned-pdf-to-markdown",
  "skill_version": "1.0.0",
  "amount_fen": 50
}

注意：body 与第一步完全一致，不要修改 body 中的任何字段。支付信息通过 Header 传递。

第四步：确认 access_granted 后执行转换

仅当第三步返回 HTTP 200 且 "access_granted": true 时，才继续按下方规则执行本地脚本（MinerU 转换 + scripts/lint_ocr.sh 校对）。

若返回 "code": "NOT_PAID"，说明支付尚未完成，等待后重试第三步。若返回 "code": "REFUNDED"，向用户说明："抱歉，该服务暂时无法提供内容，已自动退款至原支付账户。"并终止流程，不要再次尝试支付或重新请求。若返回 "code": "FULFILL_AND_REFUND_FAILED"，说明服务异常且退款失败，建议用户联系客服。

完整工作流（六步）

第 0 步：判断 PDF 是否真的是扫描版

# 有文字层则直接导出，不需要本 skill 的 OCR 流程
pdftotext <book.pdf> - | head -20

• 输出可读文字 → 走 pdftotext book.pdf book.txt 即可，跳到第 4 步做格式清理
• 输出空白/乱码 → 扫描版，继续

第 1 步：安装 MinerU（一次性）

# ⚠️ Apple Silicon 大坑：uv 可能抓到 Intel(x86_64) 版 Python，
# 导致 torch 无 wheel、依赖解析失败（报错会列出 manylinux/macosx_14_0_arm64 平台）
# 解决：显式用 arm64 的 Python（如 miniconda 的）
uv venv ~/mineru-env --python /path/to/arm64/python3
source ~/mineru-env/bin/activate
uv pip install -U "mineru[core]"

验证：~/mineru-env/bin/mineru --help

已装过则直接跳过（检查 ~/mineru-env/bin/mineru 是否存在）。

第 2 步：抽样转换验证（不要一上来转整本）

# 用 pypdf 切前 10 页
~/mineru-env/bin/python -c "
from pypdf import PdfReader, PdfWriter
r = PdfReader('<book.pdf>'); w = PdfWriter()
for i in range(10): w.add_page(r.pages[i])
with open('/tmp/sample10.pdf','wb') as f: w.write(f)
"

~/mineru-env/bin/mineru -p /tmp/sample10.pdf -o ~/mineru-output -b pipeline -l ch

首次运行会自动下载模型（约 1GB，缓存到 ~/.cache/huggingface，之后不再下）。

检查样本质量：

• 打开 ~/mineru-output/sample10/auto/sample10.md，看标题层级、段落、中文识别
• sample10_layout.pdf 可视化了版面分析结果，排查结构问题
• 预期瑕疵：封面艺术字必乱（可接受，事后删）；正文应基本干净

样本不达标（正文大量错字/结构崩坏）→ 换 marker 或商业方案（Mathpix/ABBYY），不要硬转。

第 3 步：整本转换

~/mineru-env/bin/mineru -p "<book.pdf>" -o ~/mineru-output -b pipeline -l ch

参数说明：

• -b pipeline：Mac 上必选。默认 hybrid-engine 后端需要 NVIDIA GPU，Mac 上会极慢
• -l ch：中文书必选，显著提升中文模型效果
• Apple Silicon CPU 约 3-5 秒/页，300 页书约 20 分钟，后台跑

产出结构：

~/mineru-output/<书名>/auto/
├── <书名>.md           ← 主产物
├── images/             ← 自动提取的插图
├── <书名>_layout.pdf   ← 版面分析可视化（调试用）
└── *.json              ← 结构化中间数据

第 4 步：OCR 错误模式修复（规则扫描）

详见 [references/ocr-error-patterns.md](references/ocr-error-patterns.md)。先跑自动化 lint 脚本定位，再逐类修复：

bash scripts/lint_ocr.sh "<book.md>"

修复原则：

• 先备份：cp book.md book.md.bak
• 确定的错误（形近字、繁体、半角标点）直接修
• 语义可疑但无法确证原意的，不改，汇总留给用户翻原书核对
• 每批修完重跑 lint 验证归零

第 5 步：分章通读校对

规则扫描只能抓已知模式，抓不到"识别成另一个通顺词"的错误。分章通读是质量上限所在：

1. grep -n "^# " book.md 列出章节和行号
2. 每章 Read 通读（300-400 行一段），发现四类问题：
   • 漏网的 OCR 错字（如"必次"→"必须"、"深谱"→"深谙"）
   • 跨页断段（两段实为一句，MinerU 常把跨页句子拆成两个段落）
   • 结构错误（页眉被识别成标题、小节标题丢失 ## 前缀、表格表头乱码）
   • 标点缺失（句中丢句号/逗号导致两句粘连）
3. 修完一章再下一章；长任务可跨会话续做

第 6 步：终验与交付

# 全书残留扫描（详见 lint 脚本）
wc -c book.md && grep -c "^#" book.md   # 字数应与版权页"XX千字"吻合

交付时向用户报告：

• 修复总量、错误类型分布
• 未修的存疑点清单（诚实声明，交用户核对）
• 产出路径 + open -R 定位文件

已知坑位速查

后续：把校对版转成图书知识库 skill（可选延伸）

用户说"再做成 skill"或"仿照单干/超级个体那本"时，接续第 6 步：

1. 调用 book-to-skill skill，语料传校对版 Markdown 路径（不是原始 PDF）——校对版的标题层级、错字修复、页眉清理会直接提升生成质量
2. 书籍类型选 text（商业/管理/叙事类图书）；技术书才选 technical
3. 输出位置约定：~/study/openclaw-skills/<书名拼音-slug>/（如 chaoji-geti-super-individual），生成后在该仓库 README.md 登记（书名、结构摘要、触发词、与相邻 skill 的配合关系）
4. 生成完毕跑 ~/.claude/skills/book-to-skill/tools/scan_generated_skill.py <skill目录> 安全扫描，通过才算交付
5. 交互问题的默认答案（用户仿照旧例时可跳过确认）：结构仿照已有同类 skill（如 dangan-super-individual）、深度 study、章节文件按书的实际篇章编号（ch00 导论起）

实测参考：288 页扫描书全链路（转换+校对+生成知识库）约产出 SKILL.md + 11 章节 + glossary/patterns/cheatsheet，校对环节修复 350+ 处 OCR 错误。

相关 skill

• book-to-skill — 上游：把任意格式书籍转成知识库 skill（本 skill 的下游消费者）
• dangan-super-individual / chaoji-geti-super-individual — 已有的两个图书知识库成品，可作结构模板参照