Connect tarif kuralları

Connect cookbook’undaki her tarif aynı sözleşmeye uyar. Bu sayfa, okuyucu olarak ne bekleyeceğinizi ve yazar olarak bir tarifin hangi koşulları karşılaması gerektiğini bilmeniz için söz konusu sözleşmeyi kayıt altına alır. Açıklayıcı niteliktedir: kuralları belgeler. Zorunlu kılma burada değil; nextpdf/server deposundaki araçlarda ve belge stili geçersiz kılma sayfasında gerçekleşir.

Yazarlar, Connect tariflerini nextpdf/server deposunda docs/public/ altında yazar; toplayıcı da bunları bu siteye çeker. Aşağıdaki kurallar, bir Connect tarifi nerede bulunursa bulunsun geçerlidir.

1. Araç çağrıları taşımadan bağımsızdır

Bir Connect tarifi, her taşımada aynı araç çağrısını kullanır.

Tarif, araç çağrısını bir kez gösterir. Aynı çağrı, aracı Model Context Protocol (tools/call) üzerinden, Representational State Transfer (REST) araç uç noktası üzerinden ve gRPC hizmeti üzerinden çalıştırır; çünkü her üçü de tek bir araç yürütücüsünü paylaşır.
Bir araç için yetkili argüman şeması, çalışan dağıtımın tools/list (MCP) çağrısının veya hizmet tanımlayıcısının (gRPC) döndürdüğü şemadır. Bir tarifin örnek argümanları çağrının biçimini gösterir; bunlar, tarifin yeniden tanımladığı dondurulmuş bir şema değildir.
Bir tarif asla sabit bir toplam araç sayısı öne sürmez. Esas alınan katalog, tarifin bağlantı verdiği sunucunun kendi araç kataloğudur.

2. Katmana bağlı araçlar varsayılmaz, açıkça belirtilir

Sunucunun araç kaydı, çekirdek araçları her zaman kayda alır. Ardından Pro ve Enterprise sağlayıcılarını class_exists() ile denetler ve bunların araçlarını yalnızca nextpdf/premium sunucuyla birlikte kurulduğunda kaydeder.

Bir Pro veya Enterprise aracına dayanan bir tarif, bu katman bağımlılığını açıkça belirtir ve aracın dağıtımınızda mevcut olduğunu bir tools/list çağrısıyla nasıl doğrulayabileceğinizi anlatır.
Aracın çözümlenmediği bir dağıtımda çağrı bir bilinmeyen araç hatası döndürür. Bir tarif, bu sonucu bir bozulma olarak değil, amaçlanan katman sınırı olarak sunar ve katmanla sınırlandırılmış bir aracın her zaman kullanılabilir olduğunu asla ima etmez.

3. Risk modeli ve onay kapısı

Her araç, dört risk düzeyinden birini bildirir. En yüksek düzey olan approval_required, ilk çağrıda yürütülmez.

Aracı (tasarım gereği veya bir operatör geçersiz kılması yoluyla) approval_required olabilen bir tarif, ConfirmationGate’i belgeler: kapı, argümanlara değil, araç adına, bir nonce’a ve 300 saniyelik bir yaşam süresine (TTL) bağlı tek kullanımlık bir doğrulama belirteci döndürür. Çağıran taraf, aynı aracı arguments._confirmation_token ile bir kez daha çağırır.
Bir tarif, bir yapılandırma geçersiz kılmasının bir aracın risk düzeyini yalnızca yükseltebileceğini; tasarım gereği approval_required olan bir aracı asla düşüremeyeceğini belirtir. Kapı, tüm taşımalarda aynı biçimde davranır.

4. Hata işleme, taşımayı durumdan ayırır

Uzak bir hizmete Hypertext Transfer Protocol (HTTP) üzerinden ulaşan bir tarif için, taşıma hatası ile başarısız HTTP durumu birbirinden ayrı durumlardır. Bir PSR-18 istemcisi, yalnızca isteği hiç gönderemediğinde tipli bir istemci istisnası fırlatır — PSR-18 §4; bir 4xx veya 5xx yanıtı, tarifin yakaladığı bir istisna değil, incelediği normal bir dönüş değeridir. Üretime hazır bir Connect tarifi, her iki durumu da ayrı ayrı ele alır ve boş bir catch bloğu içermez.

5. Uyumluluk ve sertifikasyon sınırı

Bir Connect tarifi, bir standart için sunulan desteği yalnızca destek olarak ele alır; asla uyumluluk veya sertifikasyon olarak sunmaz.

Motor, bir standarda (PDF/UA-2, PDF/A-4, bir PAdES düzeyi) uymayı amaçlayan çıktı üretir; uyumluluk, üreten yazılım tarafından öne sürülmez, bağımsız bir doğrulayıcı tarafından standardın gereksinimlerine göre belirlenir — PDF/A-4 §6.7.3.
Bir hazırlık değerlendirmesi sertifikasyon değil, hazırlık göstergesidir. Tasdik, yasal güvence değildir. Bir belgede bulunan uzun vadeli doğrulama materyali, belgenin taşıdığı bir yetenektir; imzanın süresiz geçerli kalacağına dair güvence değildir. Bu yetenek, alt PAdES düzeylerinden ayrıdır ve yalnızca Enterprise’a özgüdür.
Mutlak uyumluluk ifade eden sözcükler, motora ilişkin iddialar olarak kullanılmaz. Bir tarifin denetlendiği sözcüksel engelleme listesi, kelimesi kelimesine şu belirteçlerden oluşur: “certified”, ardından “guaranteed”, ardından iki sözcüklü “fully” + “compliant” ifadesi, ardından “tamper-proof”, ardından “legally valid”: bunların hiçbiri NextPDF çıktısının iddia edilen bir özelliği olarak yer alamaz; çünkü uyumluluk, üreten yazılım tarafından değil, bağımsız bir doğrulayıcı tarafından standardın gereksinimlerine göre karara bağlanır — PDF/A-4 §6.7.3. Yukarı akıştaki bir iddiayı yumuşatan bir tarif, bu yumuşatmayı aynı konumdaki düşürülmüş iddialar yan dosyasına kaydeder.

6. Yayımlama kapısı

Her Connect tarifi, Yazım Kapısı’nı geçene kadar publish: false taşır. Varsayılan davranış reddetmektir: bir sayfayı birleştirmek onu yayımlamaz; yayımlama ancak ön bilgide kayıt altına alınmış açık bir kapı kararıyla gerçekleşir. Gerçek bir uyumluluk motoru kesintisi nedeniyle normatif alıntıları sabitlenemeyen bir tarif de çözülmemiş alıntı işaretçisi taşır ve alıntı yeniden sabitlenene kadar publish: false kalır. Bu işaretçiyi, deponun Retrieval-Augmented Generation (RAG) altyapı kesintisi yedek protokolü yönetir; yazar, bir alıntı uydurmak veya iddiayı düşürmek yerine bu protokolü izler.

7. Köken alanlarını toplayıcı yazar

Bir Connect tarifi yazarı, toplayıcıya ait dört kaynak köken alanını elle yazmaz: source_repo, source_ref, source_hash ve manifest_hash. Toplayıcı, tarifi nextpdf/server deposundan çektiğinde bu alanları doldurur; böylece yayımlanan sayfa, kendisini üreten tam revizyonu kayıt altına alır. Bu dizin ve bu kurallar sayfası belgelere özgüdür; bu nedenle köken alanları tasarım gereği sıfırla doldurulur ve toplayıcı bunların üzerine yazmaz.

Özet

Bir Connect tarifi; taşımadan bağımsız araç çağrılarına, açıkça belirtilmiş bir katman bağımlılığına, belgelenmiş risk modeli ve onay kapısına, taşımayı durumdan ayıran hata işlemeye, dürüst bir uyumluluk sınırına ve Yazım Kapısı’ndan geçene kadar geçerli bir publish: false varsayılanına sahiptir. Altısını da karşılayan bir sayfa bir tariftir; daha azını karşılayan bir sayfa ise taslaktır.

Ayrıca bkz.

Connect cookbook — tarif slug eşlemesiyle katman ve taşıma sınırı.
Integration cookbook recipe conventions — bu sayfanın Connect için özelleştirdiği, ekosistem genelindeki tarif sözleşmesi.