用途:当用户附上 PDF、论文、报告等文档,且答案需要跨多处内容(如总结方法、对比第 3 节与第 5 节、列出全文所有数据集/引用/图表/基准)时,逐页通读整篇文档代价高昂。该技能先将 PDF 一次性解析为持久文本,再按需缩小范围,只读取真正需要的页面并由模型自行推理。
主要能力(均由 kernel.py 提供,需先加载后直接调用,无需 import):
- pdf_pages(path, pages=[...], mode="text"):同时取多页/多节文本,返回 [{page, text, n_chars}]。
- pdf_outline(path):读取 PDF 内嵌目录,返回 [{page, heading, level}],无目录时返回 []。
- pdf_scan(path, query, top_k):按词法重合度为查询排出候选页,返回 {hits, n_scanned},属廉价预筛而非相关性判断。
- pdf_grep(path, pattern):对解析文本做穷尽式正则扫描(DOI、登录号、"Table N"、邮箱等),返回 [{page, matches, lines?}]。
- pdf_pages(mode="image", dpi=200):把页面渲染为 PNG,用图像工具读取图中数值、坐标轴标签或图例。
- pdf_resolve(path):规范化路径。
安装与加载:依赖 pip install pypdfium2 pillow(pillow 用于 image 模式的 PNG 编码)。每会话在 Python 单元中执行一次:exec(open("<skills>/pdf-explore/kernel.py").read()),路径按实际安装位置调整;在 Claude Science 之外不会自动加载。若提示 helper 未定义,说明尚未 exec kernel.py。默认后端为 pypdfium2(Apache-2.0/BSD-3-Clause);如已安装 PyMuPDF 会作为回退,但其为 AGPL-3.0,若嵌入网络可访问服务需遵循 AGPL 的源码共享条款。
推荐用法:合成多页答案时,用一次调用取出所需页并写入文件,再读取该文件作答;先用 pdf_outline 找页码,再按主题用 pdf_scan 取候选页,或对可拼写的术语用 pdf_grep 交叉核对;读取图表细节时按 dpi=200 渲染后裁切再看。文本约每页 800 token,远低于图像的约 4000 token。
限制:pdf_scan 为词法排序,查询未使用的同义词不会得分;pdf_scan 与 pdf_grep 依赖已有文本层,纯图像扫描件无文本层,需以 mode="image" 渲染后自行阅读。mode="auto" 为默认,当页均可提取字符平均低于 80 时按图像重新解析。极长文档可用 pages=range(1, n, 3) 抽样,但可能漏掉窄相关片段,建议优先用大纲定位。仅 1–4 页的即时查阅或单一关键字搜索,用代理自带的读取工具即可。缓存键为 (abs_path, mtime, mode, dpi),传 cache=False 可强制重新解析,渲染结果位于 ./.cache/pdf-explore/{sha8}-{mtime}/dpi{N}/p{NNN}.png。