小笨羊 PDF 阅读

它解决什么问题

在一个 AI 助手的项目里，PDF 往往只以一个路径的形式出现：report.pdf、contract.pdf、paper.pdf。模型自己读不了二进制内容，当你需要提取全文、查找某个关键词在第 37 页的位置、或者只是想知道这份文档的页数和作者时，凭空猜测显然是不可靠的。这个技能的目标就是把这些操作变成一组确定的、可路由的工具调用。

核心能力

技能把能力拆成四个工具函数，每个对应一个明确的用户意图：

• scripts.tools.read_pdf：读取整个 PDF，返回全文内容和元数据
• scripts.tools.read_pdf_page：按页码或页码范围读取，参数包括 page、startPage、endPage
• scripts.tools.get_pdf_metadata：只拿元数据，不触碰正文，适合快速判断文档是否值得深入读
• scripts.tools.search_pdf：在文档内搜索关键词，可选 caseSensitive 控制大小写敏感

输入统一为 path，既接受本地绝对或相对路径，也接受 http:// 或 https:// 的 URL。

工作流程

大模型在这里只扮演路由层，代码负责真正调用 API：

1. 先检查 API 密钥，缺失时用 AskUserQuestion 向用户询问，拿到后通过 scripts.config.set_api_key 保存
2. 根据用户意图从工具列表中选择对应函数
3. 提取参数，不完整时继续追问
4. 以关键字参数调用，例如 scripts.tools.search_pdf(path=..., query=...)
5. 把 result["raw"] 整理后展示给用户

返回结构是固定的 dict，包含 raw（API 原始 JSON）、success（布尔值）和 message（状态消息）。

适用边界与注意点

API 密钥是硬性前置条件。没有 XBY_APIKEY 时，技能禁止自行搜索或编造数据，必须先向用户要。这意味着不能在无密钥环境下做离线降级。另外，工具只做文本层的提取与检索，如果 PDF 是扫描件且没有文本层，提取到的内容可能不完整，需要上游先做 OCR。