使用与此文件相邻的 pdfread.py 工具来读取 PDF 文件。可以通过以下两种方式运行：

使用 uv 0.11+（推荐）：直接调用 pdfread.py —— shebang 会通过 uv run 运行它，首次调用会下载依赖项，可能需要一分钟。
不使用 uv：在已安装 pymupdf4llm>=0.0.17（pip install pymupdf4llm）的任何 Python 3.10+ 环境中，运行 python3 pdfread.py …。

search 命令需要支持 FTS5 的 SQLite；由 uv 管理的 Python 以及几乎所有现代系统 Python 都包含它，如果缺少，脚本会清楚地报错。

运行 pdfread.py --help 获取完整用法。简要说明：

pdfread.py info FILE —— 页数、元数据、大纲/目录。从这里开始。
pdfread.py search FILE "terms" —— 查找提及关键词的页面，按 BM25 排序并附带每个匹配项的片段。首次搜索会构建缓存索引（耗时数秒）；后续搜索即时完成。条件之间是 AND 关系，term* 可匹配前缀，--raw 参数可解锁完整的 FTS5 语法（"精确短语"、OR、NEAR）。仅限文本层——扫描页面对搜索不可见。
pdfread.py text FILE --pages 10-25 —— 获取指定页面范围（基于 1）的 Markdown 文本。图片会显示为 [image: p12-img2 640x480px] 占位符。
pdfread.py image FILE p12-img2 —— 将该图片导出为 PNG 并打印其路径；可使用文件读取工具查看。
pdfread.py images FILE --pages 12 —— 列出指定页面上的图片 ID。
pdfread.py render FILE 7 —— 将整个页面渲染为 PNG（或使用 --rect x0,y0,x1,y1 裁剪区域）；用于扫描页面和文本层缺失内容的备选方案。

保留大 PDF 的上下文

对于精确问题（例如“合同在哪里提到了解约费？”），先运行 search，然后仅使用 text --pages 读取命中页面——无需子代理扩展。索引缓存是共享的，因此子代理也可以使用 search 而无需重新构建。

对于广泛综合，不要将整个文档转储到主对话中。相反：

运行 info 获取页数和目录，并将文档划分为合理的范围（按章节，或大约 15–25 页）。
为每个范围生成一个子代理，并附带如下指令：“运行 <path>/pdfread.py text <file> --pages 10-25，然后回答<用户的问题> / 用最多 N 字总结。如果 [image: ...] 占位符看起来相关，请使用 image 命令提取并查看。”
仅将摘要/答案保留在主对话中，并据此进行综合。仅在摘要表明答案位于特定页面时，才自行重新定位那些页面。

注意事项

没有 OCR：没有文本层的页面将仅返回其全页 [image: ...] 占位符（或“无可提取文本”的提示）——提取或 render 它并以可视化方式读取图像。
提取是确定性的：图片 ID 在不同运行之间保持稳定，因此子代理报告的 ID 可以在后续从主对话中提取。