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 的特化版本。