NextPDF Connect API 参考文档

概览

本页是 NextPDF Connect 服务器（nextpdf/server）的符号级参考。它按已注册的工具名称和实现类列出每个工具，并记录 gRPC 服务 NextPDFConnect 及其远程过程调用（RPC）方法和请求与响应消息。本页还说明所有传输方式共享的认证、错误和速率限制契约。

服务器通过三种传输方式公开同一个工具注册表：基于标准输入和输出的 Model Context Protocol（模型上下文协议，MCP）、表述性状态转移（REST）应用程序接口（API），以及 gRPC。每种传输方式的线路细节位于各自页面：参见 MCP 传输、REST 传输，以及 gRPC 传输。本页是这些传输方式所承载符号的目录。

下列工具名称、类和风险层级读取自 src/Tools/。一次部署实际暴露的工具数量属于运行时属性；参见工具目录。层级解析见启动与发现。

传输可用性

工具可通过一次部署中运行的任一传输方式访问。这些传输方式是相互独立的进程；启动其中一个不会启动其他进程。

传输方式	入口点	线路格式	认证
MCP	`bin/nextpdf-mcp`	基于 stdio 的 JavaScript 对象表示法远程过程调用（JSON-RPC）2.0	操作系统进程边界（无 API 密钥）
REST	`bin/nextpdf-server`	HTTP，OpenAPI 3.1	在 `Authorization` 标头中提供的 Bearer API 密钥
gRPC	`bin/nextpdf-grpc`	Protocol Buffers，包 `nextpdf.connect.v1`	在 `authorization` 调用元数据中提供的 Bearer 令牌

在 MCP 中，工具通过 tools/call 并使用已注册的工具名称调用。在 REST 和 gRPC 中，可通过渲染、操作和能力接口访问相同的引擎能力；参见 REST 传输路由表和 gRPC 传输 RPC 表。

认证与风险层级

API 密钥认证

除无需认证的健康探测外，REST 和 gRPC 传输方式要求每个请求都携带 Bearer API 密钥。密钥格式为 npk_live_{kid}_{secret}：其中 kid 是用于查找记录的八字符标识符，密文部分承载熵。服务器只存储密钥的 SHA-256 摘要，并通过恒定时间比较核对提交的令牌，因此错误密钥不会通过时序泄露信息。REST 从 Authorization: Bearer … 标头读取令牌；gRPC 从 authorization 调用元数据读取同一令牌。MCP stdio 传输没有 API 密钥，因为它是一个由启动它的客户端信任的本地子进程。认证模型见安全与运维。

四个风险层级

每个工具都会声明四个有序风险级别之一，该枚举由 src/Config/RiskLevel.php 中的 RiskLevel 定义。

层级	枚举项	值	作用
Safe（安全）	`RiskLevel::Safe`	0	只读，无副作用。自动执行。
Caution（谨慎）	`RiskLevel::Caution`	1	创建或修改内存中的状态。自动执行，记入审计日志。
Review（审查）	`RiskLevel::Review`	2	生成可能被滥用的输出。自动执行，记入审计日志。
ApprovalRequired（需审批）	`RiskLevel::ApprovalRequired`	3	具有破坏性、涉及法律，或对隐私至关重要。需要人工确认。

工具的有效风险仅来自两处：工具自身的 riskLevel() 声明，以及可选的运维配置覆盖。该覆盖只能提升风险，绝不能降低 ApprovalRequired 工具的风险。参见 HITL 风险层级和配置。

审批令牌如何流转

当一个 ApprovalRequired 工具在没有有效令牌的情况下被调用时，ConfirmationGate（src/Mcp/ConfirmationGate.php）会返回一个一次性质询令牌，而不是运行该工具。AI Agent（代理）将质询转交给人类，然后在 _confirmation_token 参数中携带所签发的令牌，重新调用同一工具。该令牌绑定工具名称、一个随机 nonce 以及一个 300 秒的存活时间（TTL）。它不绑定参数，也不是认证凭据。在 REST 中，Bearer API 密钥仍负责对请求进行认证，同一门控会在受门控操作之前于共享的工具执行器中运行。在 gRPC 中，同一门控会在分派操作之前运行。质询与令牌机制在各传输方式间完全一致。

工具与端点

下表按已注册的工具名称（“符号”列）记录每个工具，并标明其实现类。工具按层级和类别分组。所有 AST 和变更类都位于 src/Tools/Ast 和 src/Tools/Ast/Mutation 下；提取类位于 src/Tools/Extraction 下；其余类位于 src/Tools/Core。

核心文档工具

符号	参数	默认行为	返回值	抛出或失败于	备注
`create_pdf`	`page_size`（默认 `A4`）、`orientation`（`portrait`/`landscape`）、`title`、`author`；均为可选。	创建内存中的文档和一个页面；如提供元数据，则设置元数据。	包含 `document_id`、`page_count`、`page_size`、`orientation`。	失败时返回携带引擎消息的错误结果。	类 `CreatePdfTool`。风险 `RiskLevel::Caution`。层级 core。返回的 `document_id` 会供给后续的每次操作。
`add_page`	`document_id`（必填），可选的页面尺寸和方向。	向文档追加一个页面。	包含新页数的 JSON。	当 `document_id` 未知时返回错误结果。	类 `AddPageTool`。风险 `RiskLevel::Caution`。层级 core。
`add_text`	`document_id`（必填），`text`（必填），可选的位置和样式。	向文档添加文本。	JSON 文档状态摘要。	当 `document_id` 未知时返回错误结果。	类 `AddTextTool`。风险 `RiskLevel::Caution`。层级 core。
`add_image`	`document_id`（必填），`source`（必填：文件路径或 base64），可选的放置位置。	从路径或 base64 数据添加图像。	JSON 文档状态摘要。	当源不可读或 `document_id` 未知时返回错误结果。	类 `AddImageTool`。风险 `RiskLevel::Caution`。层级 core。
`add_table`	`document_id`（必填），`html`（必填）。	将 HTML 表格标记渲染到文档中。	JSON 文档状态摘要。	当标记无效或 `document_id` 未知时返回错误结果。	类 `AddTableTool`。风险 `RiskLevel::Caution`。层级 core。
`set_font`	`document_id`（必填），`family`（必填），可选的尺寸和样式。	为后续文本操作设置字体。	确认当前字体的 JSON。	当字体未知或 `document_id` 未知时返回错误结果。	类 `SetFontTool`。风险 `RiskLevel::Caution`。层级 core。
`output_pdf`	`document_id`（必填），`file_path`（可选），`destroy`（默认 `true`）。	完成文档生成；提供 `file_path` 时写入该路径，省略时返回 base64；默认销毁该文档。	包含 `file_path` 和 `file_size`，或 `base64` 和 `file_size`。	当 `document_id` 未知时返回错误结果；写入基目录之外时发生路径包含校验失败。	类 `OutputPdfTool`。风险 `RiskLevel::ApprovalRequired`。层级 core。写入文件会经过确认门控；base64 模式则不会。
`preview_layout`	`document_id`（必填）。	返回布局摘要，而不渲染最终 PDF。	JSON 布局摘要。	当 `document_id` 未知时返回错误结果。	类 `PreviewLayoutTool`。风险 `RiskLevel::Safe`。层级 core。
`parse_pdf`	`document_id`（必填）。	检查结构性元数据：页数、字体、图像、加密和信息字典。	JSON 结构性元数据。	当文档格式错误时返回错误结果。	类 `ParsePdfTool`。风险 `RiskLevel::Safe`。层级 core。仅当 `NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED` 为 `true` 或 `1` 时启用。

核心诊断工具

符号	参数	默认行为	返回值	抛出或失败于	备注
`diagnostic.doctor`	无。	运行健康检查并返回结构化环境诊断信息。	JSON 环境报告。	当内部检查失败时返回错误结果。	类 `DiagnosticDoctorTool`。风险 `RiskLevel::Safe`。层级 core。无需文档，也无需确认。
`diagnostic.capabilities`	无。	列出能力及其层级和状态信息。	JSON 能力列表。	当内部失败时返回错误结果。	类 `DiagnosticCapabilitiesTool`。风险 `RiskLevel::Safe`。层级 core。
`diagnostic.inspect`	`document_id`（必填）。	检查 PDF 并返回结构性元数据。	JSON 结构性元数据。	当 `document_id` 未知时返回错误结果。	类 `DiagnosticInspectTool`。风险 `RiskLevel::Safe`。层级 core。
`diagnostic.verify`	`document_id`（必填），可选的 PDF/A 或 PDF/UA 配置文件。	验证结构完整性；可选地启动 VeraPDF 子进程来验证 PDF/A 或 PDF/UA。	JSON 验证报告。	当子进程失败、超时或输入过大时返回错误结果。	类 `DiagnosticVerifyTool`。风险 `RiskLevel::Caution`。层级 core。输入上限为 50 兆字节（MiB）。

核心条码工具

符号	参数	默认行为	返回值	抛出或失败于	备注
`generate_barcode`	`payload`（必填），`format`（例如 QR Code、DataMatrix）。	为载荷生成二维条码模块矩阵。	JSON 模块矩阵。	当 `format` 不受支持或载荷无效时返回错误结果。	类 `BarcodeTool`。风险 `RiskLevel::Caution`。层级 core。只有在已安装的 `BarcodeTool` 中存在核心 `barcode` 编码器注册表时，`nextpdf/core` 才会注册该工具；注册后的工具名称为 `generate_barcode`。

企业版隐私工具

这些工具封装了企业版隐私类，只有这些类可自动加载时，才会注册到企业版层级下。它们作用于纯文本内容。

符号	参数	默认行为	返回值	抛出或失败于	备注
`redact_pdf`	`content`（必填），可选的检测选项。	使用企业版涂黑引擎，对纯文本内容中的个人可识别信息（PII）执行破坏性涂黑。	包含涂黑后内容和 SHA-256 哈希的 JSON。	当企业版类缺失或检测失败时返回错误结果。	类 `RedactPdfTool`。风险 `RiskLevel::Review`。层级 enterprise。
`deidentify_pdf`	`content`（必填），`strategy`（涂黑或抑制）。	使用企业版去标识器，对纯文本内容应用系统化去标识策略。	包含去标识后内容的 JSON。	当企业版类缺失时返回错误结果。	类 `DeIdentifyPdfTool`。风险 `RiskLevel::Review`。层级 enterprise。
`zone_redact_pdf`	`content`（必填），`zones`（页面和归一化矩形列表）。	使用企业版涂黑引擎，应用基于坐标的区域涂黑。	包含涂黑后内容的 JSON。	当区域无效或企业版类缺失时返回错误结果。	类 `ZoneRedactionTool`。风险 `RiskLevel::Review`。层级 enterprise。

抽象语法树 (AST) 读取工具

这些工具随服务器一同提供，注册到 Pro 层级下，并受 NEXTPDF_AST_TOOLS_ENABLED 门控（默认启用）。它们是只读的。

符号	参数	默认行为	返回值	抛出或失败于	备注
`get_document_ast`	`pdf_data`（必填）。	构建语义 AST：生成一棵完整节点树，并为每个结构元素附带引用锚点。	JSON 节点树，以及一个用于并发控制的 ETag。	当文档格式错误时返回错误结果。	类 `GetDocumentAstTool`。风险 `RiskLevel::Safe`。层级 pro。
`get_ast_node`	`pdf_data`（必填），`node_id`（必填）。	检索单个 AST 节点及其所有子节点。	包含子节点的 JSON 节点。	当 `node_id` 未知时返回错误结果。	类 `GetAstNodeTool`。风险 `RiskLevel::Safe`。层级 pro。
`get_ast_diff`	`original_pdf_data`（必填），`modified_pdf_data`（必填）。	比较两个文档的语义 AST，并生成结构化差异。	包含新增、删除和更改节点的 JSON。	当输入文档格式错误时返回错误结果。	类 `GetAstDiffTool`。风险 `RiskLevel::Safe`。层级 pro。
`search_ast_nodes`	`pdf_data`（必填），可选的类型、页面索引和文本过滤器。	按类型、页面索引或文本内容搜索 AST 节点。	包含匹配节点（带浅层子节点）的扁平 JSON 列表。	当文档格式错误时返回错误结果。	类 `SearchAstNodesTool`。风险 `RiskLevel::Safe`。层级 pro。
`extract_cited_text`	`pdf_data`（必填），可选的 `headings_only`。	提取带引用锚点（页面、边界框、置信度）的文本块。	JSON 引用文本块。	当文档格式错误时返回错误结果。	类 `ExtractCitedTextTool`。风险 `RiskLevel::Safe`。层级 pro。类别 `ast`。
`extract_cited_tables`	`pdf_data`（必填）。	提取带引用锚点的表格块；为每个 Table 节点返回行优先的单元格矩阵。	带锚点的 JSON 表格矩阵。	当文档格式错误时返回错误结果。	类 `ExtractCitedTablesTool`。风险 `RiskLevel::Safe`。层级 pro。类别 `extraction`。

AST 变更工具

这些工具随服务器一同提供，注册到 Pro 层级下，并受 NEXTPDF_MUTATION_TOOLS_ENABLED 门控（默认启用）。这四个工具都是 ApprovalRequired，并通过 ETag 使用乐观并发控制（OCC）。

符号	参数	默认行为	返回值	抛出或失败于	备注
`apply_ast_mutations`	`pdf_data`、`etag`、`idempotency_key`、`mutations`（均为必填）。	以原子方式应用一批变更；对重复的 `idempotency_key` 做去重处理。	包含变更后的 PDF 和一个新 ETag 的 JSON。	当 ETag 过期时发生 OCC 冲突；当变更格式错误时发生校验错误。	类 `ApplyAstMutationsTool`。风险 `RiskLevel::ApprovalRequired`。层级 pro。
`delete_ast_node`	`pdf_data`、`node_id`、`etag`（均为必填）。	以覆盖模式移除节点（原始内容被遮盖，而非物理删除）。	包含修改后的 PDF 和一个新 ETag 的 JSON。	当 ETag 过期时发生 OCC 冲突；当 `node_id` 未知时返回错误结果。	类 `DeleteAstNodeTool`。风险 `RiskLevel::ApprovalRequired`。层级 pro。
`insert_ast_node`	`pdf_data`、`parent_node_id`、`position`、`etag`、`node`（均为必填）。	在指定位置插入一个新节点，作为父节点的子节点。	包含修改后的 PDF 和一个新 ETag 的 JSON。	当 ETag 过期时发生 OCC 冲突；当节点格式错误时发生校验错误。	类 `InsertAstNodeTool`。风险 `RiskLevel::ApprovalRequired`。层级 pro。
`update_ast_node`	`pdf_data`、`node_id`、`etag`、`updates`（均为必填）。	更新节点的文本内容。	包含修改后的 PDF 和一个新 ETag 的 JSON。	当 ETag 过期时发生 OCC 冲突；当 `node_id` 未知时返回错误结果。	类 `UpdateAstNodeTool`。风险 `RiskLevel::ApprovalRequired`。层级 pro。

请求与响应模式

gRPC 传输的定义位于 Protocol Buffers 包 nextpdf.connect.v1 中，文件位于 proto/nextpdf/connect/v1/*.proto。该服务及其消息是规范的模式符号。

服务 `NextPDFConnect`

服务 NextPDFConnect 公开一元 RPC 和服务器流式 RPC。模式符号就是 RPC 方法名称及其承载的请求与响应消息。

RPC	请求消息	响应消息	形态
`Render`	`RenderRequest`	`RenderResponse`	一元。同步无状态渲染。
`RenderStream`	`RenderRequest`	`RenderChunk`（流）	服务器流式。以有序分块形式交付渲染结果。
`SubmitJob`	`SubmitJobRequest`	`JobResponse`	一元。提交一个异步渲染作业。
`GetJobStatus`	`GetJobStatusRequest`	`JobResponse`	一元。轮询作业状态。
`GetJobResult`	`GetJobResultRequest`	`RenderResponse`	一元。下载已完成的结果。
`GetJobResultStream`	`GetJobResultRequest`	`RenderChunk`（流）	服务器流式。以分块形式下载已完成的结果。
`CancelJob`	`CancelJobRequest`	`JobResponse`	一元。取消或删除作业。
`CreateSession`	`CreateSessionRequest`	`SessionResponse`	一元。创建一个文档构建会话。
`GetSession`	`GetSessionRequest`	`SessionResponse`	一元。获取会话元数据。
`DestroySession`	`DestroySessionRequest`	`DestroySessionResponse`	一元。销毁一个会话及其文档。
`SessionOperation`	`SessionOperationRequest`	`SessionResponse`	一元。在会话文档上执行一个操作。
`SessionRender`	`SessionRenderRequest`	`RenderResponse`	一元。将会话文档渲染为 PDF。
`SessionRenderStream`	`SessionRenderRequest`	`RenderChunk`（流）	服务器流式。以分块形式渲染会话文档。
`ExecuteCapability`	`CapabilityRequest`	`CapabilityResponse`	一元。执行一个受层级门控的能力操作。
`GetCapabilities`	`GetCapabilitiesRequest`	`GetCapabilitiesResponse`	一元。列出已认证客户端可用的能力。
`HealthCheck`	`HealthCheckRequest`	`HealthCheckResponse`	一元。存活探测。
`ReadinessCheck`	`ReadinessCheckRequest`	`ReadinessCheckResponse`	一元。就绪探测。

消息符号

请求与响应消息是该模式的结构性符号。渲染消息——RenderRequest、RenderResponse，以及流式的 RenderChunk——承载页面尺寸、方向、有序操作以及生成的 PDF 字节。作业消息——SubmitJobRequest、GetJobStatusRequest、GetJobResultRequest、CancelJobRequest，以及 JobResponse——对异步作业生命周期建模，作业元数据保存在 JobData 消息中。会话消息——CreateSessionRequest、SessionResponse、GetSessionRequest、DestroySessionRequest、DestroySessionResponse、SessionOperationRequest，以及 SessionRenderRequest——对有状态会话生命周期建模，会话元数据保存在 SessionData 消息中。能力消息——CapabilityRequest、CapabilityResponse、GetCapabilitiesRequest，以及 GetCapabilitiesResponse——承载受层级门控的操作派发和自省。系统消息——HealthCheckRequest、HealthCheckResponse、ReadinessCheckRequest，以及 ReadinessCheckResponse——承载存活和就绪状态。

随附的 .proto 文件构成已记录的线路契约；gRPC 传输参考位于 gRPC 传输。

错误模型

服务器使用各传输方式的原生错误机制报告故障。各传输方式保持相同的逻辑条件；只有编码方式不同。

MCP

MCP 错误是 JSON-RPC 2.0 错误对象。未知方法返回 method-not-found（-32601）；无效的 JSON-RPC 消息返回 invalid-request（-32600）；无法解析的输入返回 parse-error（-32700）。失败的工具会返回一个成功的 JSON-RPC 响应，并在内容中标记错误，而不是返回传输层错误，以便代理可以读取该消息。针对 ApprovalRequired 工具的确认质询同样是一个成功响应，而非错误。

REST

REST 使用超文本传输协议（HTTP）状态码，其语义由 RFC 9110 定义。200 携带结果；400 在请求字段未通过格式校验时返回；401 在未提供有效 API 密钥时返回，并携带一个 WWW-Authenticate: Bearer 质询标头；403 在有效密钥的层级无权执行该操作时返回；404 在受层级门控的路由因其包缺失而未注册时返回。机器可读错误体是符合 RFC 9457 的 Problem Details 文档，以 application/problem+json 媒体类型提供，并为每种条件附带一个稳定的 type 统一资源标识符（URI）。字段级校验失败会在错误体中列出。作为路径遍历加固措施，document_id 若不匹配模式 doc_[a-f0-9]{24}，会在工具运行之前以 400 被拒绝。REST 中间件管线和路由表记录于 REST 传输。

gRPC

gRPC 使用标准的 gRPC 状态码。缺失、格式错误、未知、已禁用或已过期的令牌会使调用以 UNAUTHENTICATED 失败，而非返回 HTTP 状态。丰富错误细节会镜像 REST 的 Problem Details 形态，并承载在 gRPC 状态细节中，因此错误 type URI 在各传输方式间保持一致。

另见：RFC 9110（HTTP Semantics）了解状态码语义，以及 RFC 9457（Problem Details for HTTP APIs）了解错误体格式。

RFC 9110（状态码语义规范）：https://www.rfc-editor.org/rfc/rfc9110
RFC 9457（问题详情错误体格式）：https://www.rfc-editor.org/rfc/rfc9457

速率限制与配额

REST 传输在其中间件管线中按互联网协议地址（IP）和按客户端施加速率限制，并叠加请求体大小限制、层级载荷限制以及单请求超时。相关上限是配置值，而非硬编码常量：

各层级的载荷上限（corePayloadLimit、proPayloadLimit、enterprisePayloadLimit）及相应超时，会根据已认证密钥的层级在 REST 上生效。参见配置。
内存中的文档存储受 max_documents（默认 50）和 document_ttl（默认 1800 秒）的约束。
速率限制和幂等性状态按工作进程保存，除非配置了 NEXTPDF_REDIS_HOST 来使用共享存储。参见部署。

当速率限制和幂等性存储被共享时，重复的相同异步作业提交会根据 idempotency_key 去重。MCP 传输通过管道一次处理一个请求，并使用一个 64 项缓冲区对重复的请求 id 去重，而不施加网络速率限制。

开发注意事项

从 src/Tools/ 下的源代码读取工具名称、类和风险层级；不要假设总数固定。请向正在运行的服务器查询权威数量，如工具目录。
从随附的 proto/nextpdf/connect/v1/*.proto 文件重新生成 gRPC 客户端存根；包和命名空间为 nextpdf.connect.v1。不要手工编辑生成的消息类。
一个 ApprovalRequired 工具在首次调用时会返回确认质询。在你交付任何使用 _confirmation_token 或任何变更工具的集成之前，请先构建重试路径：转交质询，然后携带 output_pdf 重新调用。
未安装的受层级门控路由或能力并非认证失败：对于缺失的路由，REST 返回 404，而 gRPC ExecuteCapability 会将该操作报告为不可用。应将缺失的 Pro 或企业版层级视为预期运作，而非故障。
切勿将 API 密钥纳入源代码管理；应从一个密文文件挂载它们，并优先使用支持热重载的文件密钥库，使轮换无需重启。参见安全与运维。

另见

开发者指南 — 架构、生命周期、扩展点以及测试清单
工具目录 — 经过验证的核心工具集和运行时数量
HITL 风险层级 — 风险模型和确认质询
MCP 传输 · REST 传输 · gRPC 传输 — 各传输方式的线路细节
安全与运维 — 认证、传输安全以及威胁模型