Connect recipe 惯例
Connect recipe 惯例
标题为“Connect recipe 惯例”的章节Connect cookbook 中的每一个 recipe（示例）都遵循同一份契约。本页把这份契约写清楚，让读者知道可以预期什么，也让作者了解一则 recipe 必须满足哪些条件。本页是描述性说明：它记录这项惯例。真正落实这项惯例的地方，是 nextpdf/server 存储库中的工具与文档风格覆盖表，而不是这里。
Connect recipe 撰写在 nextpdf/server 存储库的 docs/public/ 之下，再由执行 aggregate（聚合）流程的 aggregator（文档聚合器）拉入本网站。无论 Connect recipe 放在哪里，以下惯例都一体适用。
1. 工具调用与传输无关
标题为“1. 工具调用与传输无关”的章节一个 Connect recipe 的工具调用在每一种传输上的行为都相同。
- recipe 只示范一次工具调用。同一个调用可以在 Model Context Protocol（
tools/call）、REST 工具 endpoint，以及 gRPC 服务上驱动同一个工具，因为这三者共用同一个工具执行器。 - 一个工具的权威参数结构，是运行中部署从
tools/list（MCP）返回的那一份，或服务描述符（gRPC）。recipe 里的示例参数只是用来说明调用的形状，并不是 recipe 重新定义的一份冻结结构。 - recipe 绝不会断言固定的工具总数。作为依据的目录是服务器自己的工具目录，由 recipe 链接过去。
2. 分级条件式工具是明说的，不是假设的
标题为“2. 分级条件式工具是明说的，不是假设的”的章节服务器的工具注册表会无条件注册核心工具，接着用 class_exists() 探测 Pro 与 Enterprise 提供者，并且只有在 nextpdf/premium 与服务器一同安装时，才会注册它们的工具。
- 若一则 recipe 依赖 Pro 或 Enterprise 工具，就要明说这项分级依赖，并告诉读者如何确认该工具存在于自己的部署中（调用一次
tools/list）。 - 在工具无法 resolve（解析）的部署上，这个调用会返回一个未知工具错误。recipe 会把这作为预期中的分级边界呈现，而不是一种降级，并且绝不暗示分级把关的工具总是可用。
3. 风险模型与确认 gate
标题为“3. 风险模型与确认 gate”的章节每个工具都声明四种风险等级之一；最高的 approval_required 不会在第一次呼叫就执行。
- 若一则 recipe 的工具可能是
approval_required（出于设计，或出于操作者覆盖），就要把 ConfirmationGate 写清楚：这个 gate 返回一个一次性挑战令牌，绑定于工具名称、一个 nonce，以及 300 秒的 TTL，而不是绑定于参数。调用端带着arguments._confirmation_token再次调用同一个工具一次。 - recipe 要说明：配置覆盖只能 提高 一个工具的风险等级；它绝不能调低一个出于设计就是
approval_required的工具。这个 gate 在各种传输上的行为完全一致。
4. 错误处理把传输和状态分开
标题为“4. 错误处理把传输和状态分开”的章节对于通过 HTTP 连接远端服务的 recipe 来说，传输失败与非成功的 HTTP 状态是两个不同的情况。PSR-18 客户端只有在完全无法送出请求时，才会抛出类型化客户端异常——PSR-18 §4；而 4xx 或 5xx 响应是 recipe 需要检查的正常返回值，不是它要捕捉的异常。一则可用于生产环境的 Connect recipe 会把这两种情况分开处理，而且没有空的 catch 块。
5. conformance 与 certification 边界
标题为“5. conformance 与 certification 边界”的章节Connect recipe 会把对某个标准的支持仅表述为支持，绝不表述为 conformance（符合）或 certification（认证）。
- 引擎产生的是 意在符合 某个标准的输出（PDF/UA-2、PDF/A-4、某个 PAdES 级别）；符合与否由独立验证器依该标准的要求判定，而不是由产生它的软件自我断言——PDF/A-4 §6.7.3。
- 就绪评估只是一个就绪信号，不是 certification。证明（attestation）不是法律保证。文档中包含的长期验证（long-term-validation）素材，表示这份文档携带这项能力，而不是对签名无限期有效的保证。它是仅限 Enterprise 的能力，与较低的 PAdES 级别有所区别。
- 绝对化的符合性表述不会被当成引擎的宣称。recipe 检查的词汇黑名单，逐字就是这些 token：先是 “certified”，接着 “guaranteed”，再来是两个字的词组 “fully” + “compliant”，然后 “tamper-proof”，最后 “legally valid”：这些都不得作为 NextPDF 输出的属性来断言，因为符合与否是由独立验证器依该标准的要求判定，而不是由产生它的软件判定——PDF/A-4 §6.7.3。若一则 recipe 弱化了上游的某个宣称，就要把这次弱化记录在就近放置的 downgraded-claims sidecar 中。
6. 发布 gate（Writing Gate）
标题为“6. 发布 gate（Writing Gate）”的章节每一则 Connect recipe 在通过 Writing Gate 之前，都带着 publish: false。默认是拒绝：合并一个页面并不会发布它；只有在 front-matter 中记录了明确的 gate 决定，才会发布。若一则 recipe 因为 compliance engine 确实发生中断而无法固定规范性引用，就会额外带着一个未解析引用标记，并保持 publish: false，直到引用重新固定为止。存储库的 RAG 基础设施中断后备协议负责管理这个标记；作者要遵循它，而不是自己编一个引用或把宣称丢掉。
7. aggregator 写入 provenance 字段
标题为“7. aggregator 写入 provenance 字段”的章节Connect recipe 作者不会手写那四个由 aggregator 拥有的来源 provenance（来源信息）字段：source_repo、source_ref、source_hash，以及 manifest_hash。aggregator 在从 nextpdf/server 拉取 recipe 时把它们填好，因此发布出来的页面会精确记录是哪个修订版本产生了它。这份 Index（索引）与这份惯例页面都是 docs-native，因此它们的 provenance 字段按设计以零填入，aggregator 不会覆盖它们。
一则 Connect recipe 是：与传输无关的工具调用、明说的分级依赖、写清楚的风险模型与确认 gate、把传输与状态分开的错误处理、诚实的 conformance 边界，以及在通过 Writing Gate 之前都维持 publish: false 的默认状态。满足全部六项的页面是一则 recipe；满足较少的则是草稿。
另请参阅
标题为“另请参阅”的章节- Connect cookbook — recipe slug 对照表，以及 tier/transport 边界。
- Integration cookbook recipe conventions — 全生态通用的 recipe 契约，本页是它针对 Connect 的特化版本。