สร้างเอกสารหลายหน้าผ่าน NextPDF Connect

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

สร้างเอกสารหลายหน้าผ่าน NextPDF Connect โดย add_page จะเพิ่มหน้าที่สืบทอดเรขาคณิตเริ่มต้นของเอกสาร หรือกำหนดการวางแนวเฉพาะของหน้านั้นเอง หลังจากเรียก add_page แต่ละครั้ง เคอร์เซอร์จะรีเซ็ตไปยังขอบบนซ้ายของหน้าใหม่ ใช้เครื่องมือ Core สี่รายการ ได้แก่ create_pdf, add_text, add_page และ output_pdf

การติดตั้ง

composer require nextpdf/server

เชื่อมต่อทรานสปอร์ต ได้แก่ Model Context Protocol (MCP) stdio, REST หรือ gRPC โดยไม่จำเป็นต้องใช้ระดับที่ต้องมีสิทธิ์การใช้งาน

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

เอกสารใช้โครงสร้างต้นไม้ของหน้า (page tree) โดยเข้าถึงแต่ละหน้าผ่านโครงสร้างต้นไม้นั้น (ISO 32000-2 §7.7.3) แต่ละหน้ามีแอตทริบิวต์เรขาคณิตของตนเอง รวมถึง media box ที่กำหนดพื้นที่ที่มองเห็นได้ (ISO 32000-2 §7.7.3.3) create_pdf จะสร้างหน้าแรกโดยอัตโนมัติ และ add_page จะเพิ่มหน้าใหม่แต่ละหน้า ละเว้น page_size/orientation เพื่อสืบทอดค่าเริ่มต้นของเอกสาร กำหนด orientation: "landscape" เพื่อให้หน้า A4 มีขนาด 297×210 มม.

พื้นผิว API

เครื่องมือ	บทบาท	ระดับความเสี่ยง
`create_pdf`	เปิดเซสชันและสร้างหน้าแรก	ปลอดภัย
`add_text`	เขียนข้อความที่ตำแหน่งเคอร์เซอร์	ควรระมัดระวัง
`add_page`	เพิ่มหน้า (สืบทอดหรือกำหนดทับ)	ควรระมัดระวัง
`output_pdf`	เรนเดอร์และส่งคืน PDF	ต้องอนุมัติ / ตรวจสอบ (base64)

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

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

อธิบายเป็นลำดับขั้น:

create_pdf (A4 แนวตั้ง ชื่อเรื่อง ผู้เขียน) → document_id
add_text (ชื่อเรื่อง ฟอนต์ขนาดใหญ่ จัดกึ่งกลาง) จากนั้น add_text (ย่อหน้าเกริ่นนำ ฟอนต์เนื้อความ)
add_page โดยมีเฉพาะ document_id → สืบทอด A4 แนวตั้ง ระบบจะส่งคืน page_number ใหม่ และเคอร์เซอร์จะรีเซ็ต
add_text สำหรับหัวข้อส่วนและเนื้อความในหน้า 2
add_page ด้วย orientation: "landscape" → หน้า A4 แบบกว้าง
add_text สำหรับเนื้อหาแบบกว้าง
output_pdf → base64

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

ตรวจสอบความถูกต้องของการตอบกลับแต่ละรายการ หลังจาก add_page เนื้อหาจะเริ่มที่ด้านบนของหน้าใหม่ การรีเซ็ตเคอร์เซอร์เป็นพฤติกรรมที่ตั้งใจไว้ ไม่ใช่ข้อบกพร่อง ติดตาม position.page จากการตอบกลับของ add_text เพื่อตรวจจับเมื่อเนื้อหาไหลไปยังหน้าถัดไป เรียก output_pdf เพียงครั้งเดียวเท่านั้น จากนั้นทิ้ง document_id

กรณีขอบเขตและจุดที่ควรระวัง

การรีเซ็ตเคอร์เซอร์ หลังจาก add_page เคอร์เซอร์จะอยู่ที่ขอบบนซ้ายของหน้าใหม่ ข้อผิดพลาดที่พบบ่อยคือการคาดหวังให้เคอร์เซอร์ทำงานต่อจากหน้าก่อนหน้า
ต้องระบุ document_id เครื่องมือทุกตัวยกเว้น create_pdf ต้องใช้ document_id การละเว้นจะเป็นข้อผิดพลาด
การวางแนวที่ไม่ถูกต้อง ค่าที่ถูกต้องมีเพียง "portrait" และ "landscape" เท่านั้น
การแก้ไขหลังจากเอาต์พุต เนื้อหาที่เพิ่มหลังจาก output_pdf ด้วย destroy: true จะล้มเหลว เนื่องจากเซสชันถูกลบไปแล้ว

ประสิทธิภาพ

เอกสารข้อความหลายหน้าจะอยู่ภายในงบประมาณของหน้า และเอาต์พุตมีขนาดเพียงไม่กี่ KB โปรไฟล์เป็นแบบ structural: ค่า /ID ในเทรลเลอร์และไทม์สแตมป์จะไม่คงที่ในแต่ละครั้งที่รัน

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

โหมด base64 ไม่มีผลข้างเคียง เอาต์พุตเป็นไฟล์มีการควบคุม ดูส่วน human-in-the-loop (HITL) document_id เป็นแฮนเดิลแบบทึบ (opaque handle) อย่าใช้ร่วมกันระหว่างคำขอที่ทำงานพร้อมกัน

ความสอดคล้องตามมาตรฐาน

ข้อความระบุ	ข้อกำหนด	ข้อ	รหัสอ้างอิง (reference_id)
เข้าถึงหน้าแต่ละหน้าผ่านโครงสร้างต้นไม้ของหน้า	ISO 32000-2	§7.7.3
ออบเจ็กต์ของหน้ากำหนดแอตทริบิวต์เรขาคณิตของตนเอง	ISO 32000-2	§7.7.3.3

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

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

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

ทรานสปอร์ต	พร้อมใช้งาน	หมายเหตุ
MCP (stdio)	ใช่	`tools/call` ต่อหนึ่งเครื่องมือ
REST	ใช่	หนึ่งการดำเนินการต่อหนึ่งเครื่องมือ
gRPC	ใช่	แบบ Unary ต่อหนึ่งเครื่องมือ

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

create_pdf เป็น Safe; add_text และ add_page เป็น Caution; output_pdf เป็น Approval Required และลดระดับเป็น Review ในโหมด base64 เอาต์พุตเป็นไฟล์ยังคงเป็น Approval Required ดู output-approval และ HITL risk tiers

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

เอาต์พุต base64 ตรงนี้:

{ "allowed": true }

รูปแบบการท้าทาย (challenge) แสดงอยู่ใน output-approval