เรียกใช้การวินิจฉัยสภาพแวดล้อมใน NextPDF Connect

ภาพรวมโดยย่อ

ยืนยันว่าเซิร์ฟเวอร์ NextPDF Connect อยู่ในสถานะปกติและมีความสามารถที่เวิร์กโฟลว์ต้องใช้ก่อนใช้งานจริง ใช้ขั้นตอนนี้เป็นขั้นตอนแรกของไปป์ไลน์แบบ agentic ทุกแบบ เครื่องมือที่ตรวจสอบกับรีจิสทรีเครื่องมือของเซิร์ฟเวอร์แล้วคือ diagnostic.doctor diagnostic.capabilities และ diagnostic.verify รีจิสทรีเปิดเผยเครื่องมือเหล่านี้ภายใต้ชื่อโปรโตคอลแบบมีจุดคั่น และยังมีเครื่องมือที่เกี่ยวข้องคือ diagnostic.inspect เครื่องมือทั้งหมดเป็น Core

การติดตั้ง

composer require nextpdf/server

ผูกทรานสปอร์ต คุณต้องใช้ veraPDF เฉพาะในขั้นตอนการตรวจสอบความสอดคล้องที่ไม่บังคับเท่านั้น การตรวจสอบเชิงโครงสร้างไม่ต้องใช้เครื่องมือภายนอก

ภาพรวมเชิงแนวคิด

diagnostic.doctor คืนค่ารายงานสถานะพื้นฐาน ได้แก่ เวอร์ชัน PHP ส่วนขยายที่โหลด เวอร์ชันเซิร์ฟเวอร์ ระดับที่ใช้งานอยู่ และคำเตือนต่างๆ ใช้ status เป็นเกณฑ์ตัดสิน ดำเนินการต่อเมื่อค่าเป็น ok อ่าน warnings เมื่อค่าเป็น warning และหยุดเมื่อค่าเป็น error
diagnostic.capabilities แสดงรายการความสามารถที่ลงทะเบียนไว้พร้อมระดับและสถานะรันไทม์ (available, unavailable, degraded) จำนวนความสามารถขึ้นอยู่กับรันไทม์และระดับ จึงไม่ควรกำหนดยอดรวมแบบตายตัวในโค้ด ตรวจสอบความสามารถแต่ละรายการที่เวิร์กโฟลว์ต้องการ
diagnostic.verify ตรวจสอบความสมบูรณ์เชิงโครงสร้าง ได้แก่ ส่วนหัว PDF เครื่องหมาย EOF และตารางอ้างอิงไขว้ นี่คือโครงสร้างเอกสารที่เข้าถึงผ่านโครงสร้างต้นไม้ของหน้า (ISO 32000-2 §7.5) เมื่อใช้ compliance_flavour ระบบจะเรียกใช้ veraPDF ด้วย

ผลการวินิจฉัยเป็นการตอบกลับปกติในทุกทรานสปอร์ต (PHP Standard Recommendation 18, PSR-18 §p2)

ขอบเขต API

เครื่องมือ	บทบาท	ระดับความเสี่ยง
`diagnostic.doctor`	รายงานสถานะสภาพแวดล้อม	Safe
`diagnostic.capabilities`	รายการความสามารถพร้อมสถานะ	Safe
`diagnostic.verify`	ตรวจสอบเชิงโครงสร้าง / ความสอดคล้อง	Safe
`create_pdf`, `add_text`, `output_pdf`	ทดสอบเอกสารแบบ smoke-test	ตามที่ระบุไว้ในที่อื่น

ชื่อเหล่านี้คือชื่อโปรโตคอลในรีจิสทรี แค็ตตาล็อกเครื่องมือ คือแค็ตตาล็อกอ้างอิงอย่างเป็นทางการ ระดับที่ติดตั้งจะกำหนดว่ามีเครื่องมือและความสามารถใดบ้าง จึงห้ามยืนยันจำนวนเครื่องมือหรือความสามารถแบบตายตัวโดยเด็ดขาด

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

diagnostic.doctor (ไม่มีอาร์กิวเมนต์) → อ่าน status
diagnostic.capabilities (ไม่มีอาร์กิวเมนต์) → ยืนยันว่าความสามารถที่ต้องการแต่ละรายการเป็น available
create_pdf จากนั้น add_text → เอกสารสำหรับ smoke-test ขนาดเล็กที่สุด
diagnostic.verify พร้อม document_id → การตรวจสอบเชิงโครงสร้าง
หากต้องการ ให้ใช้ diagnostic.verify พร้อม compliance_flavour: "4" → veraPDF
output_pdf (base64) → ทำลายเซสชัน smoke

ตัวอย่างโค้ด — การใช้งานจริง

กำหนดเกณฑ์ผ่านของไปป์ไลน์ตาม diagnostic.doctorstatus จับคู่การพึ่งพาแต่ละรายการของเวิร์กโฟลว์กับ capability id ที่เจาะจง และยืนยันว่าเป็น available ก่อนเรียกใช้ขั้นตอนที่พึ่งพาความสามารถนั้น ถือว่า degraded เป็นความเสี่ยงด้านคุณภาพที่ต้องตรวจสอบแบบสุ่ม เรียกใช้ diagnostic.verify เชิงโครงสร้างเสมอ เรียกใช้รูปแบบการตรวจสอบความสอดคล้องเฉพาะเมื่อความสอดคล้องมีความสำคัญเท่านั้น หากไม่มี veraPDF ระบบจะคืนผลลัพธ์ว่าไม่พบอย่างชัดเจน แทนที่จะรายงานเป็นข้อบกพร่องของเซิร์ฟเวอร์

กรณีขอบและข้อควรระวัง

ไม่มี veraPDF การเรียกตรวจสอบความสอดคล้องจะคืนผลลัพธ์ว่าไม่พบอย่างชัดเจน การตรวจสอบเชิงโครงสร้างยังทำงานได้ หากคุณต้องการตรวจสอบความสอดคล้อง ให้ติดตั้ง veraPDF และวางไว้ใน PATH ของโพรเซสเซิร์ฟเวอร์
veraPDF หมดเวลา เอกสารขนาดใหญ่อาจทำให้การตรวจสอบหมดเวลาได้ ลดขนาดเอกสาร หรือเพิ่มค่าหมดเวลาในการตั้งค่าเซิร์ฟเวอร์
ความสามารถ degraded การพึ่งพาพร้อมใช้งานเพียงบางส่วน คุณภาพของผลลัพธ์จึงอาจลดลง ตรวจสอบบันทึกของเซิร์ฟเวอร์เพื่อดูตัวเลือกสำรองที่กำลังใช้งาน
Doctor error มีข้อกำหนดสำคัญบางอย่างที่ไม่ได้รับการตอบสนอง อย่าดำเนินการต่อ

ประสิทธิภาพ

การตรวจสอบเชิงโครงสร้างทำงานได้รวดเร็ว ส่วนเส้นทางการตรวจสอบความสอดคล้องจะสร้างโพรเซส veraPDF และทำงานภายในค่าหมดเวลาของการตรวจสอบ งบประมาณที่กว้างสะท้อนถึงโพรเซสย่อยดังกล่าว

หมายเหตุด้านความปลอดภัย

เอาต์พุตการวินิจฉัยเปิดเผยรายละเอียดสภาพแวดล้อม ได้แก่ เวอร์ชัน PHP ส่วนขยาย และระดับ ให้ถือว่าเป็นข้อมูลสำหรับผู้ดำเนินการเท่านั้น และอย่าแสดงต่อผู้เรียกที่ไม่น่าเชื่อถือ

ความสอดคล้อง

ข้อความ	ข้อกำหนด	ข้อ	รหัสอ้างอิง (reference_id)
ผลการวินิจฉัยเป็นการตอบกลับของทรานสปอร์ตตามปกติ	PSR-18	§p2
ความสมบูรณ์เชิงโครงสร้างมุ่งตรวจโครงสร้างที่ยึดกับโครงสร้างต้นไม้ของหน้า	ISO 32000-2	§7.5

รูปแบบการตรวจสอบความสอดคล้องจะเรียกใช้ veraPDF และรายงานผลการตัดสิน NextPDF ไม่ได้ยืนยันความสอดคล้องด้วยตนเอง ตัวตรวจสอบความถูกต้องเป็นผู้ตัดสินผล

บริบทเชิงพาณิชย์

ไม่เกี่ยวข้อง — เครื่องมือวินิจฉัยทั้งหมดเป็น Core

ความพร้อมใช้งานของทรานสปอร์ต

ทรานสปอร์ต	พร้อมใช้งาน	หมายเหตุ
MCP (stdio)	ได้	ผลการวินิจฉัยเป็นผลลัพธ์ของเครื่องมือ
REST	ได้	เอนด์พอยต์สถานะถูกแมปกับเครื่องมือเหล่านี้
gRPC	ได้	แบบยูนารี ผลลัพธ์มีฟิลด์สถานะชุดเดียวกัน

ระดับความเสี่ยง HITL

เครื่องมือวินิจฉัยทั้งสามรายการเป็น Safe คืออ่านอย่างเดียวและไม่มีผลข้างเคียง เครื่องมือเหล่านี้ไม่กระตุ้นเกตการยืนยันใดๆ output_pdf สำหรับ smoke-test เป็นโหมด base64 (Review ไม่มีเกต)

ซองข้อมูล JSON ของเกตการยืนยัน

การวินิจฉัยไม่ก่อให้เกิดเกตใดๆ

{ "allowed": true }