pdf 是一个在本地解析 PDF 的 worker，不需要凭据，也不把数据发往任何地方。它不把 PDF 当作文本处理：用文件读取函数读取 PDF 只会得到二进制噪声并浪费上下文，因此所有 PDF 操作都应走 pdf::* 系列函数。
用途
该 worker 的核心用途有两个。一是路由判断：pdf::classify 采样文档内容流，判断页面中是真实字符还是页面图像，并给出哪些具体页面必须借助视觉模型才能读取及原因。这一结论决定后续处理是否值得进行，也能区分“文档为空”和“文档是扫描件”。二是读取：文本型文档可转换为 Markdown，通过字号和页面几何信息恢复标题、列表和表格，而不仅依赖文件本身声明的结构；底层还会提供字符位置信息，供需要知道文本位置而非仅内容的调用方使用。
主要能力
- pdf::classify：路由调用，返回文档类型、置信度、页数、从 1 开始计数的需要 OCR 的页码，以及每页的机器可读原因。
- pdf::to-markdown：输出 Markdown，恢复标题、列表、链接和表格；支持可选页码过滤、按页输出，以及 fidelity 或 compact 配置。
- pdf::extract-text：输出纯文本，不做结构恢复；当结果用于搜索或嵌入时比 Markdown 更省。
- pdf::extract-items：返回每个定位字符片段及其边界框、字体、字号，并恢复粗体、斜体、下划线和删除线。
- pdf::extract-regions：返回指定页面指定边界框内的文本或 Markdown 表格。
使用方式
该 worker 按需调用，不注册 harness 钩子，也不向任何提示词注入内容，因此不涉及文档的对话不会产生额外开销。当对话中出现 PDF 路径或收到 PDF 时，应先调用 pdf::classify 再做其他处理；读取文档时用 pdf::to-markdown，文档较长时用 pages 缩小范围；若只是搜索或嵌入而非阅读，用 pdf::extract-text；判断是否值得发送给视觉模型以及发送哪些页面时，调用 pdf::classify 后查看 pages_needing_ocr 和 ocr_reasons；视觉模型定位了某个区域、需要真实字符而非其转录时，用 pdf::extract-regions；需要分析布局、按字号判断标题或某个值在页面中的位置时，用 pdf::extract-items。
适用场景
适合在本地快速判断 PDF 类型并决定是否需要 OCR 路由；适合将文本型 PDF 转为结构化 Markdown 供阅读或后续处理；适合对 PDF 做搜索、嵌入或按页提取；也适合在视觉模型已定位区域后回取原文。
限制
该 worker 不做页面栅格化，因此不能执行 OCR，扫描件和图像型文档只会被分类和路由，不会被读取；图像内容以占位符形式报告，只提供真实边界框而没有像素。需要 OCR 的页面可交给 document::ocr，由视觉模型逐页读取，但会产生按页计费的成本。ocr_reasons 中的 suspected_garbled_text 表示文本层解码为乱码，此时无论 document_type 如何都不应信任提取结果。响应有长度上限，truncated: true 且 total_chars 远大于当前结果时，说明只拿到片段，不能据此作答，应通过 pages 缩小范围而非提高上限；max_chars: 0 会解除上限，适合将文档移入存储的流水线，而不适合结果进入对话的调用。加密文档仅在 pdf::classify 和 pdf::to-markdown 上接受密码，其余三个函数无法解密。所有页码均从 1 开始计数。坐标因函数而异：pdf::extract-items 报告以左下角为原点的 PDF 点坐标，pdf::extract-regions 接受以左上角为原点的 PDF 点坐标，每个响应都会说明所用坐标系，假设错误会返回页面另一端的内容且不报错。