布局与警告

PDF 的含义常常存在于位置关系中：分栏、标题、表单标签、表格、脚注、图、链接、注释、重复页眉或页脚都会影响阅读方式。--layout 保留这些信号，而不是把页面压平成一个文本流。

对于 AI 智能体，这一点很重要，因为看似合理的文本流仍然可能是错的。双栏论文可能被跨栏读取，财务表可能丢失行边界，表单值可能离开标签，页脚可能被误当正文。pdfvision 暴露布局和 warning 信号，让智能体能发现这些情况。

布局重建

pdfvision document.pdf --layout --format json

布局输出包括：

• pages[].layout.blocks[].lines: 带几何信息的重建文本行。
• pages[].layout.blocks: 按阅读顺序排列的块、角色和 bbox。
• pages[].layout.tables: 原生文本可能压平行列关系时的数字表格提示。
• 竖排 CJK 文本恢复。

当原生文本流与视觉阅读顺序不同，Markdown 输出可以使用恢复后的 layout order。

需要 layout 的场景：

• 页面有分栏、侧栏、图题或脚注。
• 任务依赖标题或章节层级。
• 表单标签必须与值关联。
• 表格行列很重要。
• 重复的页面 chrome 不应被当作正文。
• 搜索结果或提取字段需要视觉坐标进行验证。

layout.blocks 不是为了隐藏原生文本。它给智能体提供带 geometry 和 role hints 的另一种 reading-order view，同时 pages[].text 仍可用于比较。

几何信息

pdfvision document.pdf --geometry --format json

--geometry 为每个保留的定位 pdf.js 文本项在 pages[].spans 中输出一个 span。文本项可能是一个字符、单词或更长字符串；相邻项保持分离。bbox 是整个文本项的舍入轴对齐包围框，而不是字形轮廓。每个 span 还包含近似字号 fontSize，可用于标题检测等场景。

视觉框和区域

pdfvision document.pdf --layout --image-boxes --vector-boxes --visual-regions --format json

重要字段：

• pages[].imageBoxes: 栅格图像。
• pages[].vectorBoxes: 图表路径、表格线、表单框、幻灯片形状等矢量绘制。
• pages[].visualRegions: 图、图表、表格、表单和示意图的可裁剪区域。

当智能体只需要检查这些区域时，使用 --render-visual-regions。

这是“把一切抽成文本”和“查看 PDF”之间的关键差异。幻灯片图表、签名框、标注图或表格网格可能没有多少有用原生文本，但其 image/vector geometry 会告诉智能体应该看哪里。

visual regions 可以作为到多模态模型的桥梁：

1. 用 --visual-regions 发现候选区域。
2. 选择 kind、page、bbox 和关联文本合适的区域。
3. 重新运行 --render-region，或使用 --render-visual-regions。
4. 让视觉模型只检查该证据区域。

页面警告

pages[].warnings 描述在信任原生文本前应该检查的异常。

常见警告包括：

• 文本重叠或文本框超出页面。
• 正文挤到重复页眉或页脚附近。
• 被压平的数字表格。
• 原生文本顺序与视觉阅读顺序不一致。
• 字形乱码、PUA 字符串或局部 mojibake。
• 全页扫描上的 OCR 文本层。
• 扫描页上的低置信度 OCR。
• 内部标签可能需要视觉模型读取的大型栅格区域。
• 表单、图表或示意图这样的密集矢量页面。

Hidden Native Text

A PDF can contain successfully extracted and searchable native text that is not visible on the rendered page. These checks run by default—no geometry or vector flag is required—and they leave the original extracted text unchanged. Inspect pages[].warnings separately from quality.nativeTextStatus, which can still be ok.

Code	What it means
invisible_text	Text was shown while PDF text rendering mode Tr 3 was active, so it remains in native extraction but is not painted for a viewer.
text_under_opaque_fill	A later opaque dark rectangular fill covers extracted text. This can reveal a specific visual-only redaction failure, but it is not a general redaction detector.

To avoid expected scan/OCR layers, invisible_text is suppressed when a full-page raster backs the page, while text_under_opaque_fill is suppressed when raster_backed_text_layer applies. Inspect the affected page as rendered:

pdfvision document.pdf -p 3 --render --format json

A render establishes only what the page visibly shows. Neither a warning nor its absence validates whether redaction succeeded, and absence does not certify visibility, correctness, or safety. These detectors do not find arbitrary hidden text or prompt injection. See pdfvision docs warnings for full warning details, and Security and Privacy before acting on or sharing PDF-derived content.

警告不是最终判断，而是告诉智能体下一步应检查哪里。

智能体应如何使用警告

把 warning 当作 routing signal：

• 如果原生文本字形损坏，在摘要前先与 render 或 OCR 比较。
• 如果阅读顺序分歧，叙事顺序优先使用 layout blocks，而不是 raw page text。
• 如果出现 table warning，保留行列证据；当数值重要时裁剪表格。
• 如果出现 large raster 或 dense vector warning，在验证前假设标签可能是 visual-only。
• 如果涉及 repeated chrome，避免混合页眉、页脚、页码和正文。

重要习惯不是让整个提取失败，而是让智能体选择下一步观察。pdfvision 会返回足够的证据来支持这个选择。