Quy ước cho công thức Connect

Mọi công thức trong sách dạy nấu ăn Connect đều tuân theo cùng một hợp đồng. Trang này ghi lại hợp đồng đó để với tư cách người đọc, bạn biết nên kỳ vọng điều gì, và với tư cách người viết, bạn biết một công thức phải đáp ứng những gì. Trang này chỉ mang tính mô tả: ghi lại quy ước. Phần thực thi nằm trong bộ công cụ của kho lưu trữ nextpdf/server và bảng ghi đè kiểu trình bày tài liệu, không nằm ở đây.

Người viết soạn công thức Connect trong kho lưu trữ nextpdf/server, dưới thư mục docs/public/, rồi bộ tổng hợp kéo chúng vào trang này. Các quy ước dưới đây áp dụng ở mọi nơi có công thức Connect.

1. Lệnh gọi công cụ độc lập với phương thức truyền tải

Một công thức Connect dùng cùng một cách gọi công cụ cho mọi phương thức truyền tải.

Công thức chỉ trình bày lệnh gọi công cụ một lần. Chính lệnh gọi đó điều khiển công cụ qua Model Context Protocol (tools/call), endpoint công cụ Representational State Transfer (REST), và dịch vụ gRPC, vì cả ba dùng chung một bộ thực thi công cụ.
Schema đối số có thẩm quyền của một công cụ là schema do bản triển khai đang chạy trả về từ tools/list (MCP) hoặc từ bộ mô tả dịch vụ (gRPC). Các đối số mẫu trong công thức cho thấy hình dạng lệnh gọi; chúng không phải là schema cố định do công thức định nghĩa lại.
Một công thức không bao giờ khẳng định tổng số công cụ cố định. Danh mục chính thức là danh mục công cụ riêng của máy chủ mà công thức liên kết tới.

2. Công cụ phụ thuộc theo cấp được nêu rõ, không mặc định

Sổ đăng ký công cụ của máy chủ luôn đăng ký các công cụ cốt lõi. Sau đó, nó dò các nhà cung cấp Pro và Enterprise bằng class_exists() và chỉ đăng ký công cụ của các nhà cung cấp đó khi nextpdf/premium được cài đặt cùng máy chủ.

Một công thức phụ thuộc vào công cụ Pro hoặc Enterprise sẽ nêu rõ phụ thuộc theo cấp đó và hướng dẫn bạn xác nhận công cụ có hiện diện trong bản triển khai của mình hay không bằng một lệnh gọi tools/list.
Trên bản triển khai nơi công cụ không phân giải được, lệnh gọi trả về lỗi công cụ không xác định. Công thức trình bày kết quả đó như ranh giới cấp dự định, không phải là sự suy giảm, và không bao giờ ngụ ý rằng công cụ bị giới hạn theo cấp luôn sẵn có.

3. Mô hình rủi ro và cổng xác nhận

Mỗi công cụ khai báo một trong bốn mức rủi ro. Mức cao nhất, approval_required, sẽ không chạy ngay ở lệnh gọi đầu tiên.

Một công thức có công cụ có thể là approval_required (theo thiết kế hoặc do người vận hành ghi đè) sẽ ghi lại ConfirmationGate: cổng trả về một token thử thách dùng một lần, gắn với tên công cụ, một nonce, và thời gian tồn tại (TTL) 300 giây, chứ không gắn với các đối số. Bên gọi gọi lại đúng công cụ đó một lần với arguments._confirmation_token.
Công thức nêu rõ rằng việc ghi đè cấu hình chỉ có thể nâng mức rủi ro của một công cụ; nó không bao giờ có thể hạ mức một công cụ vốn là approval_required theo thiết kế. Cổng hoạt động giống hệt nhau trên mọi phương thức truyền tải.

4. Xử lý lỗi tách phương thức truyền tải khỏi trạng thái

Đối với công thức truy cập dịch vụ từ xa qua Hypertext Transfer Protocol (HTTP), lỗi truyền tải và trạng thái HTTP không thành công là hai trường hợp riêng biệt. Client PSR-18 chỉ ném một ngoại lệ client có kiểu khi hoàn toàn không thể gửi yêu cầu — PSR-18 §4; phản hồi 4xx hoặc 5xx là một giá trị trả về bình thường để công thức kiểm tra, không phải ngoại lệ để bắt. Một công thức Connect sẵn sàng cho môi trường production xử lý riêng hai trường hợp này, không có khối catch rỗng.

5. Ranh giới tuân thủ và chứng nhận

Một công thức Connect coi việc hỗ trợ một tiêu chuẩn chỉ là hỗ trợ, không bao giờ coi đó là tuân thủ hay chứng nhận.

Engine tạo đầu ra nhằm tuân thủ một tiêu chuẩn (PDF/UA-2, PDF/A-4, một mức PAdES); sự tuân thủ do một bộ kiểm định độc lập xác định dựa trên các yêu cầu của tiêu chuẩn, chứ không phải do phần mềm tạo ra đầu ra đó tự khẳng định — PDF/A-4 §6.7.3.
Một đánh giá mức độ sẵn sàng là tín hiệu về mức độ sẵn sàng, không phải chứng nhận. Một bản chứng thực không phải là bảo đảm pháp lý. Dữ liệu xác thực dài hạn có trong tài liệu là khả năng mà tài liệu mang theo, không phải bảo đảm rằng chữ ký có hiệu lực vô thời hạn. Đây là khả năng chỉ có ở bản Enterprise, khác với các mức PAdES thấp hơn.
Không được dùng các từ ngữ tuân thủ tuyệt đối làm tuyên bố về engine. Danh sách chặn từ vựng mà công thức được kiểm tra đối chiếu, giữ nguyên từng chữ, gồm “certified”, rồi “guaranteed”, rồi cụm hai từ “fully” + “compliant”, rồi “tamper-proof”, rồi “legally valid”: không từ nào được xuất hiện như một thuộc tính được khẳng định của đầu ra NextPDF, vì sự tuân thủ do một bộ kiểm định độc lập quyết định dựa trên các yêu cầu của tiêu chuẩn, chứ không phải do phần mềm tạo ra đầu ra đó — PDF/A-4 §6.7.3. Công thức làm nhẹ một tuyên bố từ nguồn trên sẽ ghi lại việc làm nhẹ đó trong tệp sidecar về các tuyên bố đã hạ cấp đặt cùng vị trí.

6. Cổng xuất bản

Mọi công thức Connect đều mang publish: false cho đến khi vượt qua Writing Gate. Mặc định là từ chối: merge một trang không khiến trang đó được xuất bản; chỉ một quyết định cổng rõ ràng được ghi trong front-matter mới làm điều đó. Công thức có các trích dẫn quy phạm không thể ghim do một sự cố thực sự của compliance-engine cũng sẽ mang dấu hiệu trích dẫn chưa giải quyết và giữ publish: false cho đến khi trích dẫn được ghim lại. Giao thức dự phòng khi hạ tầng Retrieval-Augmented Generation (RAG) của kho lưu trữ ngừng hoạt động chi phối dấu hiệu đó; người viết tuân theo giao thức này thay vì bịa ra trích dẫn hoặc bỏ tuyên bố.

7. Bộ tổng hợp ghi các trường nguồn gốc

Người viết công thức Connect không tự tay ghi bốn trường nguồn gốc do bộ tổng hợp sở hữu: source_repo, source_ref, source_hash, và manifest_hash. Bộ tổng hợp điền các trường này khi kéo công thức từ nextpdf/server, để trang đã xuất bản ghi lại đúng bản sửa đổi đã tạo ra trang đó. Trang chỉ mục này và trang quy ước này là docs-native, nên các trường nguồn gốc của chúng được điền số 0 theo thiết kế, và bộ tổng hợp không ghi đè các trường đó.

Tóm tắt

Một công thức Connect có lệnh gọi công cụ độc lập với phương thức truyền tải, phụ thuộc theo cấp được nêu rõ ràng, mô hình rủi ro và cổng xác nhận được ghi lại, cách xử lý lỗi tách phương thức truyền tải khỏi trạng thái, ranh giới tuân thủ trung thực, và mặc định publish: false cho đến Writing Gate. Trang đáp ứng cả sáu điều là công thức; trang đáp ứng ít hơn là bản nháp.

Xem thêm

Sách dạy nấu ăn Connect — bản đồ các slug công thức cùng ranh giới cấp và phương thức truyền tải.
Quy ước công thức của sách dạy nấu ăn Integration — hợp đồng công thức cho toàn hệ sinh thái, được trang này chuyên biệt hóa cho Connect.