Konwencje przepisów Connect

Każdy przepis w książce kucharskiej Connect podlega temu samemu kontraktowi. Ta strona opisuje ten kontrakt, aby było jasne, czego może oczekiwać czytelnik i jakie warunki musi spełnić autor przepisu. Ma charakter opisowy: dokumentuje konwencję. Egzekwowanie odbywa się w narzędziach repozytorium nextpdf/server oraz w arkuszu nadpisań stylu dokumentacji, nie tutaj.

Autorzy przygotowują przepisy Connect w repozytorium nextpdf/server, w katalogu docs/public/, a agregator pobiera je do tej witryny. Poniższe konwencje obowiązują wszędzie tam, gdzie znajduje się przepis Connect.

1. Wywołania narzędzi są niezależne od transportu

Przepis Connect używa tego samego wywołania narzędzia w każdym transporcie.

Przepis pokazuje wywołanie narzędzia tylko raz. To samo wywołanie steruje narzędziem za pośrednictwem protokołu Model Context Protocol (tools/call), punktu końcowego narzędzia Representational State Transfer (REST) oraz usługi gRPC, ponieważ wszystkie trzy korzystają z jednego egzekutora narzędzi.
Miarodajny schemat argumentów narzędzia to ten, który działające wdrożenie zwraca z tools/list (MCP) lub z deskryptora usługi (gRPC). Przykładowe argumenty w przepisie pokazują kształt wywołania; nie są zamrożonym schematem redefiniowanym przez przepis.
Przepis nigdy nie podaje stałej łącznej liczby narzędzi. Miarodajnym katalogiem jest własny katalog narzędzi serwera, do którego przepis odsyła.

2. Narzędzia warunkowane poziomem są wyraźnie wskazywane, a nie zakładane

Rejestr narzędzi serwera zawsze rejestruje narzędzia podstawowe. Następnie za pomocą class_exists() sprawdza obecność dostawców Pro i Enterprise oraz rejestruje ich narzędzia tylko wtedy, gdy nextpdf/premium jest zainstalowany obok serwera.

Przepis, który zależy od narzędzia Pro lub Enterprise, wyraźnie wskazuje tę zależność od poziomu i wyjaśnia, jak potwierdzić obecność narzędzia w danym wdrożeniu za pomocą wywołania tools/list.
We wdrożeniu, w którym narzędzie nie jest rozpoznawane, wywołanie zwraca błąd nieznanego narzędzia. Przepis przedstawia ten wynik jako zamierzoną granicę poziomu, a nie jako degradację, i nigdy nie sugeruje, że narzędzie ograniczone poziomem jest zawsze dostępne.

3. Model ryzyka i bramka potwierdzenia

Każde narzędzie deklaruje jeden z czterech poziomów ryzyka. Najwyższy poziom, approval_required, nie jest uruchamiany przy pierwszym wywołaniu.

Przepis, którego narzędzie może mieć poziom approval_required (z założenia lub na skutek nadpisania przez operatora), dokumentuje ConfirmationGate: bramka zwraca jednorazowy token wyzwania powiązany z nazwą narzędzia, wartością nonce oraz 300-sekundowym czasem życia (TTL), a nie z argumentami. Wywołujący ponownie, jeden raz, wywołuje to samo narzędzie z arguments._confirmation_token.
Przepis wskazuje, że nadpisanie konfiguracji może wyłącznie podnieść poziom ryzyka narzędzia; nigdy nie może obniżyć poziomu narzędzia, które z założenia ma poziom approval_required. Bramka zachowuje się identycznie we wszystkich transportach.

4. Obsługa błędów oddziela transport od statusu

W przypadku przepisu, który łączy się z usługą zdalną przez Hypertext Transfer Protocol (HTTP), awaria transportu i niepomyślny status HTTP to dwa odrębne przypadki. Klient PSR-18 zgłasza typowany wyjątek klienta tylko wtedy, gdy w ogóle nie może wysłać żądania — PSR-18 §4; odpowiedź 4xx lub 5xx jest normalną wartością zwracaną, którą przepis analizuje, a nie wyjątkiem do przechwycenia. Gotowy do produkcji przepis Connect obsługuje oba przypadki oddzielnie, bez pustego bloku catch.

5. Granica zgodności i certyfikacji

Przepis Connect traktuje obsługę standardu wyłącznie jako obsługę, nigdy jako zgodność ani certyfikację.

Silnik tworzy dane wyjściowe mające na celu zgodność ze standardem (PDF/UA-2, PDF/A-4, poziom PAdES); zgodność jest ustalana względem wymagań standardu przez niezależny walidator, a nie deklarowana przez oprogramowanie wytwarzające — PDF/A-4 §6.7.3.
Ocena gotowości jest sygnałem gotowości, a nie certyfikacją. Poświadczenie nie jest gwarancją prawną. Materiał walidacji długoterminowej obecny w dokumencie to możliwość, którą dokument zawiera, a nie gwarancja bezterminowej ważności podpisu. Jest to możliwość dostępna wyłącznie w edycji Enterprise, odrębna od niższych poziomów PAdES.
Kategorycznych sformułowań dotyczących zgodności nie używa się jako deklaracji silnika. Leksykalna lista zablokowanych słów, względem której sprawdzany jest przepis, obejmuje dosłownie tokeny „certified”, następnie „guaranteed”, następnie dwuwyrazowe wyrażenie „fully” + „compliant”, następnie „tamper-proof”, a następnie „legally valid”: żaden z nich nie może występować jako deklarowana właściwość danych wyjściowych NextPDF, ponieważ o zgodności decyduje niezależny walidator względem wymagań standardu, a nie oprogramowanie wytwarzające — PDF/A-4 §6.7.3. Przepis, który łagodzi deklarację pochodzącą z wyższego źródła, zapisuje to złagodzenie we współzlokalizowanym pliku pobocznym ze złagodzonymi deklaracjami.

6. Bramka publikacji

Każdy przepis Connect ma ustawione publish: false, dopóki nie przejdzie przez Writing Gate. Domyślnie obowiązuje odmowa: scalenie strony nie powoduje jej publikacji; powoduje ją wyłącznie wyraźna decyzja bramki zapisana w front-matter. Przepis, którego cytatów normatywnych nie udało się zakotwiczyć z powodu rzeczywistej awarii silnika zgodności, ma także znacznik nierozwiązanego cytatu i pozostaje z ustawieniem publish: false, dopóki cytat nie zostanie ponownie zakotwiczony. Tym znacznikiem zarządza obowiązujący w repozytorium protokół awaryjny na wypadek awarii infrastruktury Retrieval-Augmented Generation (RAG); autor stosuje się do niego, zamiast wymyślać cytat lub porzucać deklarację.

7. Agregator wpisuje pola proweniencji

Autor przepisu Connect nie wpisuje ręcznie czterech pól proweniencji źródła, które należą do agregatora: source_repo, source_ref, source_hash oraz manifest_hash. Agregator wypełnia je, gdy pobiera przepis z nextpdf/server, dzięki czemu opublikowana strona zapisuje dokładną rewizję, z której powstała. Ten indeks i ta strona konwencji są natywne dla dokumentacji, więc ich pola proweniencji są z założenia wypełnione zerami, a agregator ich nie nadpisuje.

Podsumowanie

Przepis Connect ma niezależne od transportu wywołania narzędzi, wyraźnie wskazaną zależność od poziomu, udokumentowany model ryzyka i bramkę potwierdzenia, obsługę błędów oddzielającą transport od statusu, rzetelną granicę zgodności oraz domyślne ustawienie publish: false do czasu przejścia przez Writing Gate. Strona, która spełnia wszystkie sześć warunków, jest przepisem; strona, która spełnia ich mniej, jest wersją roboczą.

Zobacz także

Książka kucharska Connect — mapa slugów przepisów oraz granica poziomu i transportu.
Konwencje przepisów w książce kucharskiej integracji — kontrakt przepisów obejmujący cały ekosystem, który ta strona uszczegóławia dla Connect.