扫描教材 → 知识库（scan-to-kb）
把本地扫描整本书（纯图片 PDF，无文字层）转成可检索、可溯源的 Markdown 知识库。
实测来源：山东春考数媒专业《网页制作》备考，样本《DW 网页设计.pdf》（107 页扫描件）。
何时用本 Skill
- 用户手上有扫描版 PDF（每页是整页位图、无文字层），想 OCR 建库
- 目标是从书里生成教案、习题，且要求答案能回溯到具体页码
- 关键词命中：扫描件 / 教材 OCR / 建知识库 / 解析整本书 / MinerU / 转成可检索文本
不适用：带文字层的原生 PDF（可直接 PyMuPDF 抽文本，不必 OCR）；非教材类的通用文档问答。
核心结论（已实测，直接采信，不要重新验证）
- 引擎用 MinerU，档位用
basic。 这是本机（i7-6700K + GTX 970 4GB + 16GB 内存）唯一可行档位。
-standard/advanced档位跑不动：1.2B VLM 在纯 CPU/4GB 显存下failed to encode mtmd batch崩溃。
- 不要用 RapidOCR / Tesseract：中文扫描教材效果差，会整行吞掉代码填空线、圈号。 - 调用方式只有一条路能走通（MinerU 4.x on Windows）：
mineru-kit.exe parse <输入.pdf> -o <输出.md> -f markdown -p all --tier basic
- 不要用mineru.exe parse（要求起 doclib 服务，服务起来即崩，报 sqlite readonly）
- 不要用mineru.exe server start（后台守护进程被沙箱回收）
- 不要用--remote（需 mineru.net API key） - 实测性能：约 3.8 秒/页。107 页约 7 分钟；251 页整本 15m36s 一次跑通（MinerU 4.0.10 自动按 64 页窗口分批，无需手动切页）。
标准流程
① 整本解析 mineru-kit 直接整本跑（251 页实测一次跑通，自动按 64 页窗口分批）；超大/易崩才用 PyMuPDF 切页
② MinerU 解析 mineru-kit parse --tier basic → 输出 Markdown（带标题层级）
③ 合并全本 把多页 Markdown 合并成一个文件（页眉自动检测依赖全书行频统计）
④ 清洗 clean_mineru.py（自动剥页眉/页脚、修破折号/引号/圈号叠印）
⑤ OCR 校验 ocr_verify.py 自动扫描误识别（LaTeX 代码/错字/噪声行/序号/引号），输出待复核清单
⑥ 抽检+校对 对照校验清单逐题人工还原代码（重点看代码题、表格页、图示页）
⑦ 切片 按 Markdown 标题层级(##/###)切，不要按固定字数切
⑧ 入库 导入 ima / 向量库，L1 原子知识点带页码可溯源
关键细节（踩坑记录）
MinerU 残留的字符级问题（可用正则修复，性质是"形近误识"非"内容丢失"）
- 代码内破折号：
http-equiv→http— equiv、Content-Type→Content—Type - 全角/弯引号：
height=“150"左右不匹配 - 圈号叠印：
② V应为②>；/>被拆成1>（第①空实为>） - 页脚页码
— 11 —未剥离（页眉剥离了，页脚没有）
图片处理（重要，别丢图）
- MinerU 输出 markdown 时，图片是 base64 内联（
），不是独立文件。 - 清洗/切片前先提取图片（用
scripts/extract_images.py）：解码 base64 存成 jpg，按图题（图 X-X）命名，无图题的按img_XXX兜底。 - 切片时把占位符替换成图片引用
，别只留[插图]占位符——否则图丢了。 - 偏移不对齐坑：图片索引里记录的字符偏移基于「含 base64 的原始 markdown」，与「删掉 base64 后的清洗版」偏移完全不同，不可混用。
正确做法：全书图片列表按出现顺序排序，用「封面/目录部分的占位符数」作偏移跳过（正文图片 = 图片列表[封面占位数:]）。 - header 避坑：切片文件的自述 header 里不要出现占位符字样（如
[插图]），否则re.sub会把 header 里的字样也误替换，造成图片错位。
代码题 OCR 质量（需人工校对）
- HTML/CSS 代码段会被 MinerU 识别成 LaTeX 公式（
$<img \; src = ...$、$\text{...}$），这是 basic 档位对代码的固有误识。 - 代码类题目（网页制作/DW 模块最多）必须逐题人工校对还原，按 HTML/CSS 规范 + 题目语义重写选项。
- 同时伴随题目序号误识（
II.→11.）、文字误识（插人→插入）、噪声行（严重乱码）——一并清理。
检测卷类文件：卷尾常有真题
- 教辅「同步检测卷」末尾往往附有历年真题（如「山东省普通高校招生(春季)考试…试题」），切片时单独切出，价值高。
切片原则（重要）
- 用 MinerU 输出的标题层级作为切片边界，检索质量远好于固定字数切。
pdfkit-py的chunk_pdf是固定字数/段落策略，会把一个知识点切碎，不推荐。
三层知识库结构（上层方法论）
- L1 原子层：单个知识点（标签/属性/选择器…），一段话，带页码
- L2 考点层：考纲条目 → 关联 L1 知识点列表（人工构建，核心资产）
- L3 题目层：教材例题/习题 + 自编题（单题粒度，供生成习题的语料）
校验闸门（质量底线）
- 每道 AI 生成的题，答案必须能回溯到具体页码原文；回溯不了的判废。
环境（自动发现，勿硬编码）
本 Skill 不写死任何本机路径，执行时按下列优先级自动定位：
- Python：优先用当前环境可用的
python/python3；WorkBuddy 托管环境则用
~/.workbuddy/binaries/python/envs/default/Scripts/python.exe（Windows）或
~/.workbuddy/binaries/python/envs/default/bin/python（macOS/Linux）。 - MinerU：优先用
mineru-kit.exe（Windows）/mineru-kit（Unix，在 PATH 中）；
否则到~/.mineru/下定位。模型位于~/.mineru/models/（basic 用MinerU-4_models_onnx）。 - 配置：
~/.mineru/config.yaml。直接用 mineru-kit 可绕过 doclib 服务，通常无需改。
> ~ 指用户主目录（Windows 为 C:\Users\<用户名>）。换机器后按各自 HOME 自动解析，
> 无需修改本 Skill。
前置依赖（对方机器首次使用需准备一次）
# 1) 安装 MinerU（进入 WorkBuddy 隔离 venv 或系统 Python）
pip install "mineru[core]"
# 2) 下载 basic 档位模型
mineru-kit models download --tier basic
装好后即可跑通；模型只需下载一次。
脚本
scripts/clean_mineru.py：清洗 MinerU 输出（剥页脚/修破折号/引号/圈号叠印）- 页眉自动检测：对整本书做行频统计，自动识别高频短行页眉，换书无需任何配置
scripts/headers.txt：仅高级用户强制指定页眉时用（默认auto，可忽略）scripts/extract_images.py：从 MinerU 原始 markdown 提取 base64 内联图片为独立 jpg，按图题命名 + 生成_图片索引.txt- 用法：
python extract_images.py <原始.md> <输出图片目录> scripts/ocr_verify.py：OCR 校验，自动定位 LaTeX 代码误识别 / 错字 / 噪声行 / 罗马数字序号 / 引号不配对，输出 Markdown 待复核清单- 用法：
python ocr_verify.py <清洗后的.md> [报告.md] - 参考：
references/ocr-benchmark.md（RapidOCR vs MinerU 实测数据）
输出规范
- 解析结果：Markdown，保留
##/###标题层级 - 清洗后文件名后缀
_final.md或_cleaned.md - 交付时附抽检结论与字符级错误统计（残留破折号数、圈号数、代码块数）
