处理 NextPDF Connect 工作流中的错误

概览

构建具备韧性的 Connect 工作流。验证每一个工具结果，清理失败的会话，并以全新状态重试。失败的工具会返回结构化错误结果；它属于常规响应，而不是传输失败。PSR-18 也采用相同区分：即使状态表示错误，仍会返回一个响应（PSR-18 §3）。

安装

composer require nextpdf/server

绑定传输方式。本示例使用 create_pdf、add_text 与 output_pdf，这三者都属于 Core。

概念概览

失败的工具调用会返回一个错误结果。它包含错误标志和人类可读消息，并在适用时附上代码。成功结果没有错误标志，并包含该工具的常规输出。无论是哪一种情况，传输都已经发送请求并收到响应（PSR-18 §p2）。

防御性的循环很短：发送调用并读取结果。如果是错误，就记录、分类、应用恢复策略，并且不要带着过期状态继续。否则，提取所需字段并继续。

API 接口

工具	角色	风险级别
`create_pdf`	开启会话	安全
`add_text`	写入文本	谨慎
`output_pdf`	渲染并返回 PDF	需要审批/审查（base64）

工具目录是权威记录目录。可用工具取决于已安装的级别。

代码示例 — 快速开始

执行正常路径（create_pdf → add_text → output_pdf）并检查每一个结果。接着刻意在 add_text 上重用一个已被销毁的 document_id，以触发会话错误。通过创建新的会话并重放内容来恢复。

代码示例 — 生产环境

按类别对错误分类，并据此响应：

输入验证 — 具有确定性。修正参数并重试相同的调用。示例：空白文本、无效对齐、非正数大小、未知页面大小、未知字体族。
会话 — 该 document_id 已不存在。创建新的会话并重放所有内容。
系统 — 服务器资源限制，例如会话上限。退避后重试。
审批 — 将 output_pdf 写入文件时，可能会暂停以等待人工审批。这是工作流暂停，而不是失败。转发挑战并等待，然后带着确认令牌重新调用。

切勿假设成功；会话错误后切勿重用 document_id；在每一个内容步骤都成功之前，切勿发送 output_pdf。

边界情况与陷阱

审批并非错误。 HITL 挑战是一种暂停。不要在高频循环中重试。将它转发给人工处理。
服务器重启。 所有内存中的会话都会被清除，且先前的每一个 document_id 都会失效。
部分工作流。 如果 add_text 在文件处理中途失败，会话状态可能不一致。安全的恢复方式是创建全新的会话，而不是做部分修复。

性能

可以忽略。本示例着重于控制流，而不是渲染。对于任何生成的输出，其可复现性配置均为 structural。

安全注意事项

错误消息面向调用方代理和操作人员。不要将原始服务器错误文本逐字返回给不受信任的最终用户。改为显示一条经过分类和清理的消息。

合规性

陈述	规范	条款	reference_id
无论结果如何，传输都会返回一个响应。	PSR-18	§p2
即使状态表示错误，仍会返回一个响应。	PSR-18	§3

商业场景

不适用 — 所有工具均属于 Core。

传输可用性

传输	可用	备注
MCP（stdio）	是	错误会以带有错误标志的工具结果形式返回。
REST	是	非 2xx 状态会带有相同的分类错误响应体。
gRPC	是	一个状态码加上一条错误结果消息。

在每一种传输中，工具级别的错误都是一条需要检查的常规响应，而不是被丢弃的调用（PSR-18 §3）。

HITL 风险级别

create_pdf 为安全，add_text 为谨慎，而 output_pdf 需要审批；在 base64 模式下降级为审查。待处理的文件写入会以审批挑战的形式呈现，错误循环必须将其视为暂停，而不是失败（HITL 风险级别）。

确认关卡 JSON 封装

待处理的审批会返回：

{ "allowed": false, "challenge": "<human-readable challenge text>", "token": "confirm_<single-use-hex>" }

将 _confirmation_token 设为该令牌后，重新调用同一个工具，它便会返回 { "allowed": true }。关于完整流程，请参阅 output-approval。