ข้อกำหนดสำหรับสูตร Connect

สูตรทั้งหมดในคุกบุ๊ก Connect ใช้สัญญาเดียวกัน หน้านี้บันทึกสัญญาดังกล่าวเพื่อให้ผู้อ่านทราบว่าควรคาดหวังอะไร และผู้เขียนทราบว่าสูตรหนึ่งต้องเป็นไปตามเงื่อนไขใดบ้าง หน้านี้เป็นเอกสารเชิงพรรณนา กล่าวคือบันทึกข้อกำหนดไว้เท่านั้น การบังคับใช้เกิดขึ้นในเครื่องมือของรีโพซิทอรี nextpdf/server และในชีตการแทนที่สไตล์ของเอกสาร ไม่ใช่ในหน้านี้

ผู้เขียนสร้างสูตร Connect ในรีโพซิทอรี nextpdf/server ภายใต้ docs/public/ จากนั้นตัวรวบรวมจะดึงสูตรเหล่านั้นเข้ามายังไซต์นี้ ข้อกำหนดด้านล่างนี้ใช้กับทุกตำแหน่งที่มีสูตร Connect

1. การเรียกใช้เครื่องมือไม่ขึ้นกับ transport

สูตร Connect ใช้รูปแบบการเรียกใช้เครื่องมือเดียวกันในทุก transport

สูตรแสดงการเรียกใช้เครื่องมือเพียงครั้งเดียว และการเรียกใช้เดียวกันนี้ใช้ขับเคลื่อนเครื่องมือผ่าน Model Context Protocol (tools/call) เอนด์พอยต์เครื่องมือแบบ Representational State Transfer (REST) และบริการ gRPC เพราะทั้งสามแบบใช้ตัวรันเครื่องมือเดียวกันร่วมกัน
สคีมาอาร์กิวเมนต์ที่ถือเป็นทางการสำหรับเครื่องมือหนึ่งคือสคีมาที่ดีพลอยเมนต์ที่กำลังทำงานส่งกลับมาจาก tools/list (MCP) หรือตัวพรรณนาบริการ (gRPC) อาร์กิวเมนต์ตัวอย่างในสูตรแสดงรูปแบบการเรียกใช้ ไม่ใช่สคีมาที่ตรึงไว้เพื่อให้สูตรนิยามใหม่
สูตรไม่เคยยืนยันจำนวนรวมของเครื่องมือแบบตายตัว แค็ตตาล็อกที่ถือเป็นทางการคือแค็ตตาล็อกเครื่องมือของเซิร์ฟเวอร์เอง ซึ่งสูตรเชื่อมโยงถึง

2. ต้องระบุเครื่องมือที่ขึ้นกับ tier ไม่ใช่สันนิษฐานเอาเอง

รีจิสทรีเครื่องมือของเซิร์ฟเวอร์จะลงทะเบียนเครื่องมือ core เสมอ จากนั้นตรวจหาผู้ให้บริการ Pro และ Enterprise ด้วย class_exists() แล้วลงทะเบียนเครื่องมือของผู้ให้บริการเหล่านั้นเฉพาะเมื่อมีการติดตั้ง nextpdf/premium ควบคู่กับเซิร์ฟเวอร์

สูตรที่ขึ้นอยู่กับเครื่องมือ Pro หรือ Enterprise จะระบุการพึ่งพา tier นั้นไว้อย่างชัดเจน และบอกวิธียืนยันว่าเครื่องมือดังกล่าวมีอยู่บนดีพลอยเมนต์ของคุณด้วยการเรียก tools/list เพียงครั้งเดียว
บนดีพลอยเมนต์ที่ไม่สามารถรีโซลฟ์เครื่องมือได้ การเรียกใช้จะส่งกลับข้อผิดพลาด unknown-tool สูตรนำเสนอผลลัพธ์นั้นว่าเป็นขอบเขต tier ตามที่ตั้งใจไว้ ไม่ใช่การลดทอนคุณภาพ และไม่เคยสื่อว่าเครื่องมือที่ถูกกั้นตาม tier พร้อมใช้งานเสมอ

3. โมเดลความเสี่ยงและเกตการยืนยัน

เครื่องมือทุกตัวประกาศระดับความเสี่ยงหนึ่งในสี่ระดับ ระดับสูงสุดคือ approval_required ซึ่งจะไม่ทำงานในการเรียกใช้ครั้งแรก

สูตรที่เครื่องมืออาจเป็น approval_required (โดยการออกแบบหรือโดยการแทนที่ของผู้ปฏิบัติงาน) จะมีเอกสารกำกับ ConfirmationGate เกตนี้จะส่งกลับโทเค็นชาเลนจ์แบบใช้ครั้งเดียวที่ผูกกับชื่อเครื่องมือ nonce และเวลาคงอยู่ (TTL) 300 วินาที แต่ไม่ผูกกับอาร์กิวเมนต์ ผู้เรียกใช้จะเรียกใช้เครื่องมือเดิมซ้ำพร้อมด้วย arguments._confirmation_token ได้เพียงครั้งเดียว
สูตรระบุว่าการแทนที่ค่าคอนฟิกทำได้เพียง เพิ่ม ระดับความเสี่ยงของเครื่องมือเท่านั้น และไม่สามารถลดระดับเครื่องมือที่เป็น approval_required โดยการออกแบบได้เลย เกตทำงานเหมือนกันในทุก transport

4. การจัดการข้อผิดพลาดแยก transport ออกจากสถานะ

สำหรับสูตรที่เข้าถึงบริการระยะไกลผ่าน Hypertext Transfer Protocol (HTTP) ความล้มเหลวของ transport และสถานะ HTTP ที่ไม่สำเร็จเป็นคนละกรณีกัน ไคลเอนต์ PSR-18 จะยกข้อยกเว้นไคลเอนต์แบบมีชนิดเฉพาะเมื่อไม่สามารถส่งคำขอได้เลยเท่านั้น — PSR-18 §4 ส่วนการตอบสนอง 4xx หรือ 5xx เป็นค่าที่ส่งกลับตามปกติซึ่งสูตรต้องตรวจสอบ ไม่ใช่ข้อยกเว้นที่สูตรดักจับ สูตร Connect ที่พร้อมใช้งานจริงจะแยกจัดการทั้งสองกรณีอย่างชัดเจน และไม่มีบล็อก catch ที่ว่างเปล่า

5. ขอบเขตของความสอดคล้องและการรับรอง

สูตร Connect ถือว่าการรองรับมาตรฐานเป็นเพียงการรองรับ ไม่ใช่การกล่าวอ้างความสอดคล้องหรือการรับรอง

เอนจินสร้างเอาต์พุตที่ ตั้งใจให้สอดคล้อง กับมาตรฐาน (PDF/UA-2, PDF/A-4, ระดับ PAdES) ความสอดคล้องนั้นต้องพิจารณาตามข้อกำหนดของมาตรฐานโดยตัวตรวจสอบความถูกต้องที่เป็นอิสระ ไม่ใช่ยืนยันโดยซอฟต์แวร์ที่ผลิต — PDF/A-4 §6.7.3
การประเมินความพร้อมเป็นเพียงสัญญาณบ่งชี้ความพร้อม ไม่ใช่การรับรอง การตรวจสอบความถูกต้องไม่ใช่การรับประกันทางกฎหมาย ข้อมูลการตรวจสอบความถูกต้องระยะยาวที่มีอยู่ในเอกสารเป็นความสามารถที่เอกสารพกพาไว้ ไม่ใช่การรับประกันว่าลายเซ็นจะใช้ได้อย่างไม่มีกำหนด นี่เป็นความสามารถเฉพาะ Enterprise เท่านั้น ซึ่งแตกต่างจากระดับ PAdES ที่ต่ำกว่า
สูตรจะไม่ใช้คำที่บ่งชี้ความสอดคล้องแบบเด็ดขาดเป็นการกล่าวอ้างของเอนจิน บัญชีรายการคำต้องห้ามที่สูตรถูกตรวจสอบเทียบแบบตรงตัวอักษรประกอบด้วยโทเค็น “certified” ตามด้วย “guaranteed” ตามด้วยวลีสองคำ “fully” + “compliant” ตามด้วย “tamper-proof” และตามด้วย “legally valid” โดยไม่มีคำใดที่อาจใช้เป็นคุณสมบัติที่ยืนยันแล้วของเอาต์พุต NextPDF ได้ เพราะความสอดคล้องถูกตัดสินโดยตัวตรวจสอบความถูกต้องที่เป็นอิสระเทียบกับข้อกำหนดของมาตรฐาน ไม่ใช่โดยซอฟต์แวร์ที่ผลิต — PDF/A-4 §6.7.3 สูตรที่ลดทอนความหนักแน่นของการกล่าวอ้างต้นทางจะบันทึกการลดทอนนั้นไว้ในไฟล์ไซด์คาร์ downgraded-claims ที่อยู่ร่วมตำแหน่งกัน

6. เกตการเผยแพร่

สูตร Connect ทุกสูตรจะมี publish: false จนกว่าจะผ่าน Writing Gate ค่าเริ่มต้นคือปฏิเสธ การรวมหน้าหนึ่งเข้ามาไม่ได้เท่ากับเผยแพร่หน้านั้น การเผยแพร่เกิดขึ้นได้เฉพาะจากการตัดสินใจของเกตที่ชัดเจนและบันทึกไว้ใน front-matter เท่านั้น สูตรที่ไม่สามารถปักหมุดการอ้างอิงเชิงบรรทัดฐานได้เนื่องจากการขัดข้องจริงของ compliance-engine จะมีตัวบ่งชี้ unresolved-citation ด้วย และคงสถานะ publish: false ไว้จนกว่าจะปักหมุดการอ้างอิงใหม่ โปรโตคอลสำรองกรณีโครงสร้างพื้นฐานของ Retrieval-Augmented Generation (RAG) ขัดข้องในรีโพซิทอรีเป็นผู้กำกับตัวบ่งชี้นั้น ผู้เขียนต้องปฏิบัติตามโปรโตคอลนี้แทนที่จะแต่งการอ้างอิงขึ้นมาเองหรือตัดการกล่าวอ้างทิ้ง

7. ตัวรวบรวมเป็นผู้เขียนฟิลด์ provenance

ผู้เขียนสูตร Connect ไม่ได้เขียนฟิลด์ source-provenance ทั้งสี่ที่ตัวรวบรวมเป็นเจ้าของด้วยมือ ได้แก่ source_repo, source_ref, source_hash และ manifest_hash ตัวรวบรวมจะเติมค่าฟิลด์เหล่านั้นเมื่อดึงสูตรมาจาก nextpdf/server เพื่อให้หน้าที่เผยแพร่บันทึกรีวิชันที่สร้างหน้านั้นขึ้นมาได้อย่างแม่นยำ ดัชนีนี้และหน้าข้อกำหนดนี้เป็น docs-native ดังนั้นฟิลด์ provenance ของหน้าเหล่านี้จึงถูกเติมด้วยศูนย์ตามการออกแบบ และตัวรวบรวมจะไม่เขียนทับ

สรุป

สูตร Connect มีการเรียกใช้เครื่องมือที่ไม่ขึ้นกับ transport การพึ่งพา tier ที่ระบุไว้อย่างชัดเจน โมเดลความเสี่ยงและเกตการยืนยันที่มีเอกสารกำกับ การจัดการข้อผิดพลาดที่แยก transport ออกจากสถานะ ขอบเขตความสอดคล้องที่ตรงไปตรงมา และค่าเริ่มต้น publish: false จนกว่าจะผ่าน Writing Gate หน้าที่เป็นไปตามครบทั้งหกข้อคือสูตร ส่วนหน้าที่เป็นไปตามน้อยกว่านั้นคือฉบับร่าง

ดูเพิ่มเติม

คุกบุ๊ก Connect — แผนผัง slug ของสูตร รวมถึงขอบเขตของ tier และ transport
ข้อกำหนดของสูตรในคุกบุ๊ก Integration — สัญญาระดับทั่วทั้งระบบนิเวศของสูตร ซึ่งสัญญานี้นำมากำหนดเฉพาะสำหรับ Connect