PDF Evidence Reader

把“PDF 里说了什么”变成可核对的三件事：第几页、哪段原文、字符区间。

这个 Skill 不生成摘要式答案，而是先检索证据，再让 Agent 基于证据回答。适用于论文、财报、合同、说明书等带页码的 PDF。

何时使用

用户问某句话、数字、结论出自 PDF 的哪一页。
用户要求“原文引用”“给出处”“不要编造”。
需要核对一个 claim 是否被 PDF 支持。
需要在长 PDF 中快速定位相关段落，再交给模型阅读。

不适用：

扫描件 OCR（本 Skill 只读取 PDF 可提取文本层）。
需要理解整张图表视觉内容的任务。
没有明确问题的全文摘要（可先用本 Skill 定位，再做摘要）。

输入

pdf：本地 PDF 文件路径。
query：用户的问题或关键词，中英文均可。
可选：--top 返回页数（默认 5）、--context 每段上下文字符数（默认 360）。

工作流

确认依赖：python -c "import pypdf"。若缺失，先 pip install pypdf。
运行检索脚本：

python scripts/pdf_evidence.py <pdf路径> "<query>" --top 5 --json

读取 JSON 中的 pages。每个结果包含：
- page：物理页码，从 1 开始，不是印刷页码。
- snippet：原文片段，未改写。
- start / end：snippet 在原页文本中的半开字符区间。
- terms：命中的查询词。
回答用户时：
- 先给结论，再列证据。
- 每条证据必须带 第 N 页，并引用 snippet 原文。
- 如果证据不足，明确说“检索到的页面不足以支持该结论”，不要补写。
- 用户要求精确核对时，给出 start/end 或完整原句。

输出契约

脚本默认输出人类可读文本；加 --json 输出：

{
  "pdf": "report.pdf",
  "query": "operating margin",
  "pages": [
    {
      "page": 42,
      "score": 12.34,
      "snippet": "…exact text…",
      "start": 120,
      "end": 480,
      "terms": ["operating", "margin"]
    }
  ]
}

pages 按相关度降序；同一页只返回一次；空白页不返回。

关键规则

原文优先：snippet 必须逐字来自 PDF 提取文本，不能翻译、改写或补全。
页码是物理页：从 PDF 第一页开始计数，避免与财报印刷页码混用。
不足就承认：没有命中时返回空数组；不要用常识替代原文。
中文检索：脚本使用 CJK 单字 + 二元组和 BM25，中文问题可直接检索。
大文件：先用 --top 小范围定位；需要读全文时再按页码读取。
加密 PDF：空密码可读的 PDF 会正常解析；需要密码的文件会报错。
隐私：不要把 PDF 内容、路径或查询发送到网络；脚本完全离线运行。

示例

用户：这篇论文有没有提到 positional encoding 的消融实验？

python scripts/pdf_evidence.py paper.pdf "positional encoding ablation" --top 3 --json

Agent 回答：

有。第 7 页的 Table 3 给出了 positional encoding 的消融结果： “We also compare learned positional encodings with sinusoidal encodings…” （第 7 页，字符区间 812–1046）

用户：这份财报的资本开支是多少？

python scripts/pdf_evidence.py 10-K.pdf "capital expenditures" --top 5 --json

先返回现金流表中的原文和页码，再让模型基于该段计算或总结。

失败处理

pypdf 未安装：提示安装命令，不要改用在线服务。
文件不存在/不是 PDF：明确报错。
页面没有可提取文本：跳过该页，并在结果中说明“可能是扫描件”。
需要 OCR：提示用户先做 OCR，再重新运行。

文件

scripts/pdf_evidence.py：离线检索脚本。
references/usage.md：更多示例与集成方式。
tests/：脚本自测。