使用 NextPDF Connect（Pro）提取文本内容

概览

从现有 PDF 中提取文本，用于索引、分析或后续处理。此工具名为 extract_text。它会重新验证 Pro 工具提供方；该提供方会以协议名称 extract_text 注册 new ExtractTextTool()。extract_text 是 Pro 级工具。 服务器会在启动时通过 class_exists() 探测它，并且仅在安装 Pro 包时才会注册。它支持纯文本输出、页码范围，以及按页分段的结构化输出。

安装

composer require nextpdf/server
composer require nextpdf/pro

绑定一个传输层。在依赖此工具之前，请先通过 diagnostic.capabilities 确认它可用。

概念总览

提取会按流顺序读取内容流中的文本显示运算符（ISO 32000-2 §9.4）。输出反映的是编码后的阅读顺序（ISO 32000-2 §9.10）。没有文本层的扫描型 PDF 只会产生极少文本，甚至完全没有文本。这是来源本身的性质，并非工具缺陷。format: "plain" 会返回单个字符串。format: "structured" 会返回每页的对象，并包含字符计数。page_range 会限制处理的页面。

API 接口

工具	级别	角色	风险等级
`extract_text`	Pro	提取文字（纯文本/结构化/范围）	安全
`parse_pdf`	Core（受环境变量管控）	低层结构（页数、元数据）	安全

工具名称就是注册表中的协议名称。工具目录是权威目录。可用工具取决于已安装的级别。

代码示例 — 快速上手

extract_text，搭配 source（服务器可读取的路径）与 format: "plain"。
extract_text，搭配 page_range: "1-3" 以获取子集。
extract_text，搭配 format: "structured" 以获取按页分段的输出。

代码示例 — 生产环境

在请求页面范围之前，请先通过 parse_pdf（或先前一次未设限的 extract_text）取得页数。若用于 RAG/索引，建议采用 format: "structured"，以便逐页分块。若来源已加密，请提供密码参数。字符计数采用 UTF-8 码点计数，而非字节。

边界情况与陷阱

来源遗失。 错误的路径会返回找不到文件的错误。请使用服务器可读取的绝对路径。
扫描型 PDF。 没有文本层意味着文本为空或近乎为空。请先对来源进行 OCR。
页码超出范围。 超出文档的范围会被拒绝，并返回实际页数。
来源已加密。 请提供密码参数。
未安装 Pro。 仅有 Core 时，extract_text 并不会注册。请通过 diagnostic.capabilities 探测。

效能

提取规模会随文档大小增长，且预算允许大型输入。对于任何生成的产物，其配置文件均为 structural，因为此工具返回的是文本，而非 PDF。

安全须知

提取出的文本可能包含敏感内容。请将结果视为机密，并且仅通过可信通道返回。此工具不会写入文件系统。它只会以服务器权限读取来源路径，因此请限制调用方可传入的路径。

符合性

陈述	规范	条款	reference_id
文本由文本运算符按流顺序显示。	ISO 32000-2	§9.4
提取反映的是编码后的阅读顺序。	ISO 32000-2	§9.10

本示例并不断言：对于未加标签的文档，提取出的文本就是忠实的逻辑阅读顺序。其顺序是编码后的顺序。

商业语境

extract_text 是 Pro 级工具，仅在服务器启动时 Pro 包得以解析时才会注册。

传输层支持度

传输层	是否支持	备注
MCP（stdio）	是（Pro）	大量文本会使 stdio 帧膨胀。
REST	是（Pro）	在支持的情况下，请通过流式方式返回大型结果。
gRPC	是（Pro）	大量文本会受消息大小上限的限制。

HITL 风险等级

extract_text 属于安全（只读、无副作用），且永远不会设下确认关卡。

确认关卡 JSON 封套

只读提取永远不会设下确认关卡：

{ "allowed": true }