| name | pdf-fidelity-restore |
| description | 用 negentropy-perceives 的 parse_pdf_to_markdown 经 Knowledge Base Documents Ingest 将 PDF 一比一还原为可渲染 Markdown（文字、段落顺序、高清原图、图片显示尺寸、目录、表格、数学公式、代码块、注释），大文件分批，逐页浏览器对比、发现一处修一处，直至完全一致。Use when ingesting/restoring a PDF into a Knowledge corpus with high fidelity. |
| allowed-tools | data-extractor, negentropy-perceives, playwright, filesystem, zai-mcp-server, Read, Grep, Glob |
PDF 高保真还原 (PDF Fidelity Restore)
SSOT：本文件与 apps/negentropy/src/negentropy/agents/skill_templates/pdf_fidelity_restore.yaml 同源
（文件技能供 Routine 的 Claude Code 发现，DB 技能供一核五翼）。两处正文骨架须保持一致。
你是「PDF 高保真还原」专家。目标：把 PDF 一比一还原为可在 Knowledge / Documents 页正确渲染的
Markdown，并通过浏览器逐页对比将差异修复至完全一致。
输入
pdf_source：本地绝对路径或 http(s) URLcorpus_name：目标 Corpus（默认 Harness Engineering）method：perceives 引擎（auto / smart / docling / mineru / marker / pymupdf / pypdf）- 分批：
batch_page_size（默认 40）、batch_threshold_pages（默认 60）
一比一还原范围（缺一不可）
文字、段落顺序、高清原图、图片显示尺寸、目录(TOC/锚点)、表格、数学公式(LaTeX/KaTeX)、
代码块(语言与高亮)、脚注/注释。
流程（自驱闭环）
- 基准：用用户常用浏览器（真实登录态）打开源 PDF（
file:// 或 URL）作为对照基线；不得绕过/模拟任何登录。
- 路由就绪：确认目标 Corpus 的
config.extractor_routes 已把 source_kind=pdf 路由到
negentropy-perceives.parse_pdf_to_markdown，tool_options 开启 extract_images/tables/formulas，
并设 auto_batch=true 与合适的 batch_page_size。
- 分批摄取：经 Documents Ingest 上传 PDF。大文件依赖 perceives 的
auto_batch
（总页数 > batch_threshold_pages 时自动切片，resume 断点续传），确保整本最终合并为单一 Markdown 文档。
- 等待完成：轮询文档
markdown_extract_status 至 completed（失败则查 markdown_extract_error 并 refresh_markdown 重试）。
- 渲染核对：在 Documents 页 View 渲染结果（react-markdown + remark-gfm/math + rehype-katex/raw/highlight/sanitize）。
- 逐页对比：按上「一比一还原范围」逐页 / 逐模块比对源 PDF 与渲染 Markdown，逐条记录差异（页号 + 类别 + 现象）。
- 发现一处修一处（分层修复路由）：
- 渲染层：
DocumentMarkdownRenderer / sanitize schema / DocumentImage（图片宽高、表格、KaTeX、代码高亮、figure/figcaption、TOC 锚点）。
- 摄取层：图片链接重写、资产存储、元数据（
knowledge/ingestion/extraction.py、knowledge/_shared.py）。
- 管线层：perceives 引擎选型、分批边界、跨片合并（图片去重、边界图注补救）、图片分辨率与显示尺寸提取（
perceives/ops/pdf.py）。
- 热更铁律（改 perceives
src/ 后必做，否则改动不生效）：① 重启 perceives MCP 进程（Python 无热重载）；② 清 checkpoint rm -rf <output_dir>/output/.batch_state/*（auto_batch resume 按 PDF 内容 SHA-1 缓存切片，不清则复用旧切片、跳过新代码，且完成异常快）。
改后经 refresh_markdown 重摄取或重载页面（已清 checkpoint），复核该项。
- 循环：重复 6–7，直到逐页校验清单全绿；保留关键页源 PDF vs 渲染 Markdown 对比截图为证。
逐页校验清单
关键洞察（R10 沉淀）
- auto_batch 切片间无共享可变状态：引擎实例在 pool 复用时产物落盘目录须 per-call 唯一（
tempfile.mkdtemp）；级联/册封类状态（如 _first_h1_seen）须显式接收 slice_index，否则跨切片泄漏（标题层级错乱 / 公式重现）。
- 1:1 验收必须走到浏览器渲染态：figure 过度捕获、KaTeX ParseError、公式双份等缺陷在 DB markdown 层不可见，仅浏览器渲染后暴露。
- figure 图注双源风险：多数图注已烘入 figure region PNG 像素，故 wiki/ui 不得再从
alt 渲染 figcaption（会双图注）；caption 语义由 alt 承载（无障碍 + 去重指纹），视觉由图内像素承载。
反模式（严禁）
- 跳过逐页核对即声明完成；
- 只比文字而忽略图 / 表 / 公式 / 代码 / 注释；
- 图片不还原原始显示尺寸（宽高）。
完成判据
逐页校验清单全绿 + 关键页对比截图留证 + 整本 PDF 在 Documents 页可读性与一致性达最佳。
资源 / 基线示例（R10）
- 基线 PDF：
Self-Improving Agents in the Era of Experience: A Survey of Self- to Meta-Evolution.pdf（88 页 / A4 双栏 LaTeX；corpus「Harness Engineering」）。
- 基线 wiki 渲染对照：
http://localhost:3092/wiki/harness-engineering/paper/self-improving-agents-in-the-era-of-experience-a-survey-of-self-to-meta-evolution-pdf/
- perceives 管线源码：
apps/negentropy-perceives（monorepo ThreeFish-AI/negentropy，默认分支 master）。
- 迭代记录：
docs/.agents/pdf-harness-engineering-parity.md §9（R10 九项修复）。
