使用方法

本页展示常见命令模式。对于未知 PDF，先做结构化第一遍，检查页面 overview，再只在证据需要的地方添加布局、渲染、OCR、搜索或视觉区域。

推荐第一遍

pdfvision document.pdf --json

用它回答：

• 哪些页面有可用的原生文本？
• 哪些页面偏视觉、像扫描件或字形损坏？
• 哪些页面有警告？
• 哪些页面需要布局重建、OCR 或渲染裁剪？

本地 PDF

pdfvision document.pdf

远程 PDF

pdfvision --remote https://example.com/document.pdf --format json

远程下载会被缓存，并在提取前验证是否为 PDF。如果 .pdf URL 返回 HTML、登录页或挑战页，pdfvision 会在缓存前失败。

--remote 的初始 URL 仅支持 HTTP(S)，并会跟随重定向。如果响应正文开头附近没有 PDF header，pdfvision 会拒绝该响应。默认限制为 100 MB 的正文上限，以及涵盖等待响应头和传输正文的 60 秒截止时间。

只对用户独立授权的目标使用 --remote。它验证响应，但不验证网络目标，也不会阻止私有地址或重定向目标。不要直接传入不可信 URL；应使用下载组件通过允许列表验证每个解析 IP 和重定向节点、固定连接目标，再把本地文件传给 pdfvision，或者把 pdfvision 的下载过程隔离在网络控制之后。详见安全与隐私。

远程缓存按 URL 建立。如果一个稳定 URL 的内容会被原地更新，可用 --no-cache 做一次新鲜获取，或用 --clear-cache 删除缓存副本：

pdfvision --remote https://example.com/document.pdf --no-cache --format json

页码范围

pdfvision document.pdf --pages 1-3
pdfvision document.pdf --pages 1,3,5 --format json

页码范围使用从 1 开始的物理页码。逗号组合多个选择器，范围包含两端，重复页会合并到排序后的输出中。

有效示例：

• 1
• 1-5
• 1,3,5
• 2-4,7

空片段、0、负数、5-3 这样的降序范围和格式错误的范围都会直接报错，而不是猜测用户意图。如果选择器包含超出文档末尾的页，但至少选中了一个真实页，pdfvision 会提取真实页，并为被跳过的页发出警告。

渲染页面

pdfvision document.pdf --render --render-output ./images --format json

使用 --render-scale 控制图像细节：

pdfvision document.pdf --render --render-scale 3

提取布局和视觉结构

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

这会添加布局块、图像框、矢量框、视觉区域和布局警告。

适用于双栏论文、幻灯片、财务报告、表格、表单、图表、图示，以及任何视觉位置会改变含义的页面。

只渲染重要区域

pdfvision document.pdf --render-visual-regions --render-output ./regions --format json

当不想渲染整页，但需要查看图、表、表单或图表区域时使用。

搜索并放大

pdfvision report.pdf --search "revenue" --format json
pdfvision report.pdf --pages 3 --render --render-region 120,180,360,140 --render-output ./crops --format json

当 pdfvision 能定位证据时，搜索结果会包含 bbox。把该 bbox 传给 --render-region，即可生成用于视觉验证的小裁剪图。

当答案必须绑定到可审计的 PDF 证据时，这个模式很有用：先搜索术语，选择匹配页和 bbox，再渲染最小可用裁剪。

扫描页 OCR

pdfvision scan.pdf --ocr --ocr-lang eng --format json
pdfvision japanese-scan.pdf --ocr --ocr-lang jpn+eng --format json

OCR 结果包含文本、置信度、语言和单词框。

OCR 会附在原生文本旁边，不会替换 pages[].text。智能体可以先比较原生提取与 OCR，再决定信任哪个证据。

表单、链接与注释

pdfvision form.pdf --layout --form-fields --annotations --links --format json

当 PDF 包含 widget 值、复选框、单选组、可见评论、链接，或含义依赖页面位置的表单标签时使用。

目录、页码标签与文档功能

pdfvision document.pdf -p 1 --page-labels --outline --viewer --layers --format json

当 PDF viewer 体验有意义时，使用此命令进行探测，例如检查不同于物理页码的页码标签、书签、open action、optional content layer 或 viewer preferences。这里的 -p 1 只限制页面提取和输出，并不保证只加载或解析第一页，也不限制整个文档的运行时间。若不指定它，文档功能选项仍会提取所有页面。文档级字段仍会返回。页面级 JavaScript actions 只针对选中的页面返回；如需检查，请用相关页范围重新运行 --viewer。

加密 PDF

pdfvision encrypted.pdf --password your-password --format json
printf "your-password\n" | pdfvision encrypted.pdf --password-stdin --format json

当密码不应出现在 shell 历史或进程参数中时，优先使用 --password-stdin。

缓存控制

pdfvision document.pdf --no-cache --json
pdfvision --clear-cache

pdfvision 会缓存提取结果、渲染图像、远程下载和 OCR 数据，让智能体重复读取同一 PDF 时更快。如果不希望缓存提取结果和远程 PDF 字节，请使用 --no-cache；用 --clear-cache 删除缓存数据。

当应用需要把缓存放在已知位置时，请将 PDFVISION_CACHE_DIR 设为指向专用目录的非空绝对路径。相对路径、~、文件系统根目录、主目录、工作目录和共享临时目录都会被拒绝：

PDFVISION_CACHE_DIR=/secure/pdfvision-cache pdfvision document.pdf --json

经过所有者检查的 .pdfvision-cache-root 标记用于授权递归清理。--clear-cache 绝不会采用未标记的自定义根目录；未设置 PDFVISION_CACHE_DIR override 时，只能在权限加固前后确认旧版形状后采用当前历史默认根目录。正常使用时，所有未标记根目录都要经过相同扫描。在 POSIX 上，带有 group/other 写权限的未标记根目录会被拒绝；每个祖先还必须可读/open、由当前用户或 root 拥有，并且不可写或有安全的 sticky 保护。移入 quarantine 后，POSIX 清理会比较 st_dev，若不一致则拒绝递归删除；原路径此时已经移动，且同一 device 的 bind mount 无法检测。身份检查仅在传统 POSIX uid/mode/sticky semantics 下增强替换防护；不会检查 ACL 或网络文件系统权限，也无法排除最终检查后由 root 或同一 UID 发起的替换。Windows 只能提供 best-effort 防护。清理不与正在运行的 OCR 协调；请重试被中断的 OCR。

--no-cache 会跳过提取缓存和远程 PDF 缓存，但未指定 --render-output 的渲染 PNG 会使用单独的操作系统临时路径，显式渲染输出仍会写入指定位置。--ocr 仍会在经过验证的缓存根目录下持久保存 traineddata 和 worker support files。因此，即使设置了 --no-cache，无效的 PDFVISION_CACHE_DIR 仍会导致 OCR 运行失败。

对远程 PDF，--no-cache 也会跳过远程 PDF 缓存，并把新下载的字节直接送入提取流程。对于私有或限时 URL，这可以避免保留下载的 PDF 字节；当同一 URL 的内容可能发生变化时，也会强制重新获取。但它不会让原本未经授权的网络目标变得安全。