MinerU PDF 知识库
核心锚点是“派生链”：原始 PDF 只读，MinerU 解析结果、精简 Markdown、必要图片、章节文件和检索地图都是可重建的派生物。
触发门禁
满足任一条件时执行本 Skill：
- 多份 PDF 要形成一个可长期问答、可持续追加的资料库；
- 单份大部头需要按真实章节拆分，避免 Agent 一次读入整本；
- 资料包含扫描页、复杂排版、表格、公式或混合质量，普通文本提取不足以稳定建库；
- 用户明确要求目录、检索地图、失败记录和回源验收。
只有一份短 PDF、少量普通文字型 PDF 或一次性阅读/摘要时，改用通用 PDF 工具；不启动本建库流程。完成标准：先判断用户要的是“读文件”还是“建可重复使用的知识库”，再开始安装和解析。
固定输出合同
output/
├── source-manifest.csv
├── content/
├── assets/
├── chapters/
├── page-maps/
├── index.md
├── retrieval-map.md
├── retrieval-eval.md
├── failures.md
└── run-log.md
字段、状态和各层职责见 output-contract.md。最终知识库只保留 Markdown、必要图片和追踪清单，不把 MinerU 调试 PDF、模型 JSON 或原始 PDF 复制进输出。
派生链步骤
1. 确认范围与验收问题
确认只读来源目录、独立输出目录、隐私范围和 3–8 个真实检索问题。问题至少覆盖正常命中、跨文档整合和资料中没有答案。
完成标准：输出目录不在原件目录内；用户要的是大部头或多资料建库；验收问题已记录。
2. 建立独立 MinerU 环境
读取 platform-notes.md，按当前平台创建项目内 .venv-mineru。macOS 与 Windows 都使用官方 mineru[all] 包；Windows 优先 Python 3.12，macOS 使用 Python 3.10–3.13。安装前先说明约 20 GB 磁盘、16 GB 内存和首次下载模型的成本，再获得用户同意。
安装后用同一环境执行：
python scripts/doctor.py --json --branch mineru-kb
mineru --version
检测器只检查，不自行安装。完成标准：mineru-kb 分支为 ready，且记录实际平台与 MinerU 版本；Windows 说明是兼容路径还是已在真实 Windows 设备验证。
3. 先跑代表样本
从资料中选 1–3 份获准样本，覆盖文字型、复杂排版或扫描型页面。默认使用跨平台 CPU 路径：
mineru -p /path/to/sample.pdf -o /path/to/sample-output -b pipeline -m auto
有符合官方要求的 Apple Silicon 或 GPU，并且样本对比证明质量更好时，才切换 hybrid-engine。抽查标题层级、阅读顺序、表格、图片和 OCR；解析不适合时先调整样本参数，不直接跑全库。
完成标准：至少一个样本产生可读 Markdown；关键页面完成原 PDF 对照；选定正式后端和 OCR 方法。
4. 批量建立 Markdown 知识库
在安装并激活 MinerU 的环境中运行：
python scripts/build_pdf_knowledge_base.py \
--source-dir /path/to/read-only-pdfs \
--output-dir /path/to/output \
--backend pipeline \
--method auto \
--question "第一个真实检索问题" \
--question "需要跨资料回答的问题"
Windows 不激活环境时，通过 --mineru-command .venv-mineru\Scripts\mineru.exe 指定命令。脚本逐份调用 MinerU，保留相对来源路径和 SHA-256，收集主 Markdown 与实际引用图片，生成页码线索，并在 Markdown 足够长且存在重复 H1/H2 时按大章节拆分。失败文件独立记录，不中断其他来源。
输出已存在时默认停止；确认来源与参数未变后使用 --resume。完成标准：清单中的每份 PDF 都是 complete 或 failed，没有静默遗漏，原文件哈希在解析前后保持一致。
5. 校准章节与检索地图
以一个“大章节”为默认检索单元；只有单章仍明显过长时再继续拆分。检查 retrieval-map.md 是否把主题、资料和章节连到正确 Markdown。一个问题需要多份资料时保留多来源路径，不强迫只命中一个文件。
自动拆分依赖 Markdown 标题结构；标题不可靠时人工校准章节边界。完成标准：大部头不再依赖整本加载；每个章节链接存在；检索入口优先指向最合适的章节或资料。
6. 做真实检索验收
依次回答 retrieval-eval.md 中的问题，记录命中文件、章节、page-maps/ 页码线索和原 PDF 抽查结果。页码线索缺失时明确写“仅定位到 Markdown，需人工回原 PDF”，不能冒充按页验证。
完成标准：正常问题命中正确来源；跨文档问题能合并证据；无答案问题诚实返回缺口；至少一个扫描或复杂页面完成原图抽查。
停止条件
来源无权处理、输出可能覆盖原件、来源哈希变化、磁盘或内存不足、MinerU 样本质量不适合、模型无法合法获取、加密 PDF 无法读取，或页码线索不足以支持用户要求的精度时，停止对应文件并写入 failures.md。保留其他独立文件的成功结果。
