| 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) URL
corpus_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 九项修复)。