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

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

เครื่องมือทุกตัวประกาศระดับความเสี่ยงระดับใดระดับหนึ่งจากทั้งหมดสี่ระดับ ระดับสูงสุดคือ approval-required และจะไม่ทำงานในการเรียกครั้งแรก แต่ ConfirmationGate จะส่งคืนโทเค็นการท้าทายแบบใช้ครั้งเดียวแทน เอเจนต์ต้องส่งต่อโทเค็นนั้นให้มนุษย์เพื่ออนุญาตการเรียกใช้อีกครั้ง

การติดตั้ง

composer require nextpdf/server

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

โมเดลความเสี่ยงมีสี่ระดับที่เรียงตามลำดับดังนี้:

ระดับ	ค่า	ความหมาย	ผล
ปลอดภัย (safe)	0	อ่านอย่างเดียว ไม่มีผลข้างเคียง	ทำงานอัตโนมัติ
ระมัดระวัง (caution)	1	สร้างหรือแก้ไขสถานะในหน่วยความจำ	ทำงานอัตโนมัติ บันทึกการตรวจสอบ
ตรวจทาน (review)	2	สร้างเอาต์พุตที่อาจถูกนำไปใช้ในทางที่ผิดได้	ทำงานอัตโนมัติ บันทึกการตรวจสอบ
ต้องอนุมัติ (approval_required)	3	ทำลายข้อมูล มีนัยทางกฎหมาย หรือมีความสำคัญเชิงความเป็นส่วนตัว	ต้องได้รับการยืนยันจากมนุษย์

ความเสี่ยงของเครื่องมือมาจากสองแหล่งเท่านั้น: การประกาศของเครื่องมือเอง และการแทนที่การกำหนดค่าที่ผู้ดำเนินการเลือกตั้งค่า ไม่มีแหล่งที่สาม โมเดลนี้มีหมายเลขเวอร์ชันกำกับ การตอบสนอง initialize ของ MCP จะเปิดเผยหมายเลขนั้นเพื่อให้ไคลเอนต์ตรวจพบการเปลี่ยนแปลงที่ไม่เข้ากันได้ การบันทึกการตรวจสอบจะเริ่มตั้งแต่ระดับ caution ขึ้นไป

การชะลอการกระทำอัตโนมัติไว้จนกว่ามนุษย์จะอนุญาต เป็นการวางการควบคุมไว้ ณ จุดที่ระบบอัตโนมัติก่อให้เกิดความเสี่ยง IEC 31010 ระบุว่านี่คือตำแหน่งสำหรับการควบคุมความเสี่ยงที่เกิดขึ้นผ่านการกระทำของมนุษย์ ณ จุดที่ก่อให้เกิดหรือใกล้กับจุดนั้น (IEC 31010:2019)

พื้นผิว API

ConfirmationGate (เกตยืนยัน)

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

{ "allowed": true }

หรือ

{ "allowed": false, "challenge": "<human-readable text>", "token": "confirm_<nonce>" }

ข้อความการท้าทายระบุชื่อการดำเนินการและคำอธิบายของการดำเนินการนั้น อีกทั้งยังเตือนเมื่อไฟล์ปลายทางกำลังจะถูกเขียนทับ ข้อความนี้แจ้งให้ผู้เรียกเรียกใช้เครื่องมือเดิมซ้ำพร้อมพารามิเตอร์ _confirmation_token ที่ตั้งค่าเป็นโทเค็นที่ออกให้ โทเค็นจะหมดอายุภายใน 300 วินาที

การผูกโทเค็นได้รับการออกแบบเช่นนี้โดยจงใจ: โทเค็นผูกกับชื่อเครื่องมือ nonce แบบสุ่ม และ TTL โดย ไม่ ผูกกับอาร์กิวเมนต์ เมื่อมีการลองใหม่ ไคลเอนต์ MCP อาจซีเรียลไลซ์อาร์กิวเมนต์ใหม่ด้วยการเรียงลำดับคีย์หรือการปรับให้อยู่ในรูปแบบมาตรฐานที่แตกต่างกัน ดังนั้นการแฮชอาร์กิวเมนต์จะทำให้การยืนยันที่ถูกต้องล้มเหลว โทเค็นใช้ได้ครั้งเดียว การใช้โทเค็นในการเรียกใช้ซ้ำจะอนุญาตให้เรียกได้เพียงครั้งเดียวเท่านั้น

การแสดงผลในแต่ละทรานสปอร์ต

เกตถูกบังคับใช้กับทุกทรานสปอร์ตที่ใช้ขับเคลื่อนเครื่องมือ:

MCP: การท้าทายจะส่งคืนแบบ in-band เป็นการตอบสนอง JSON-RPC ที่สำเร็จ โดยมีข้อความการท้าทายเป็นเนื้อหา ผู้เรียกจะเรียกใช้ tools/call ซ้ำพร้อมกับ arguments._confirmation_token
REST และ gRPC: เกตเดียวกันนี้จะทำงานในตัวดำเนินการเครื่องมือที่ใช้ร่วมกันก่อนดำเนินการ approval_required การท้าทายจะปรากฏในการตอบสนองของการดำเนินการ ผู้เรียกจะดำเนินการซ้ำพร้อมกับโทเค็น

การป้องกันการลดระดับในตัว

การแทนที่การกำหนดค่าอาจ เพิ่ม ระดับความเสี่ยงของเครื่องมือได้ แต่ตามการออกแบบแล้วจะไม่มีทางลดระดับเครื่องมือที่เป็น approval_required ได้ ตัวโหลดการกำหนดค่าจะบังคับใช้ชุดระดับวิกฤตที่กำหนดไว้ตายตัว และจะโยนข้อผิดพลาดในเวลาโหลดหากการแทนที่พยายามลดระดับ เซิร์ฟเวอร์จะปฏิเสธการบูต แทนที่จะทำงานด้วยเกตที่ถูกทำให้อ่อนลง

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

กระตุ้นการท้าทายด้วยการเขียนไฟล์ผ่าน output_pdf:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"output_pdf","arguments":{"document_id":"<id>","file_path":"/var/lib/nextpdf/tmp/out.pdf"}}}
EOF

การตอบสนองจะเป็นการท้าทาย ไม่ใช่ไฟล์ ให้เรียกใช้ซ้ำด้วยโทเค็นที่ออกให้:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"output_pdf","arguments":{"document_id":"<id>","file_path":"/var/lib/nextpdf/tmp/out.pdf","_confirmation_token":"confirm_<nonce>"}}}

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

สำหรับการปรับใช้ที่ได้รับการเสริมความแข็งแกร่ง ให้เพิ่มระดับเครื่องมือที่ปกติเป็น caution ขึ้นเป็น approval-required:

nextpdf_mcp:
  risk_level_overrides:
    add_image: 3      # require human confirmation for image insertion

การลดระดับจะถูกปฏิเสธในเวลาโหลด และเซิร์ฟเวอร์จะไม่เริ่มทำงาน เช่น การตั้งค่า output_pdf ให้ต่ำกว่า 3 ถือเป็นการลดระดับ

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

output_pdf ในโหมด base64 จะไม่ผ่านเกต การเขียนลงดิสก์เป็น approval-required ส่วนการส่งคืน PDF แบบ base64 (ไม่มี file_path) ถือเป็นความเสี่ยงระดับต่ำกว่าและทำงานได้โดยไม่ต้องยืนยัน
โทเค็นไม่ใช่ข้อมูลรับรอง โทเค็นไม่พิสูจน์ตัวตนของผู้เรียก และไม่แทนที่คีย์ API บนทรานสปอร์ตแบบเครือข่าย โทเค็นเพียงปลดล็อกการเรียกเฉพาะรายการเดียวที่ผ่านเกตได้หนึ่งครั้ง ภายใน 300 วินาที
การท้าทายใหม่ทุกครั้ง การไม่ส่งต่อโทเค็น หรือการปล่อยให้โทเค็นหมดอายุ จะไม่บล็อกเครื่องมือถาวร การเรียกครั้งถัดไปจะออกการท้าทายใหม่ โทเค็นถูกเก็บไว้ในที่จัดเก็บโทเค็นแบบใช้ครั้งเดียว พร้อมการเก็บขยะเป็นระยะ
การบันทึกการตรวจสอบเกิดขึ้นไม่ว่าผลลัพธ์จะเป็นอย่างไร การออกการท้าทาย การดำเนินการที่สำเร็จ และการดำเนินการที่ล้มเหลวที่ระดับ caution ขึ้นไป ทั้งหมดจะถูกบันทึกการตรวจสอบพร้อมชื่อเครื่องมือและระดับความเสี่ยง

ประสิทธิภาพ

เกตจะเพิ่มการค้นหาในที่จัดเก็บโทเค็น และเมื่อออกการท้าทาย จะเพิ่มการสร้างโทเค็นแบบสุ่ม ต้นทุนดังกล่าวน้อยมากเมื่อเทียบกับการดำเนินการที่ผ่านเกต และมีผลเฉพาะกับเครื่องมือ approval_required เท่านั้น

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

เกตเป็นการควบคุมแบบจำกัดขอบเขต ไม่ใช่การควบคุมการพิสูจน์ตัวตน เกตทำให้มั่นใจว่ามนุษย์เป็นผู้อนุญาตการกระทำที่ทำลายข้อมูล มีนัยทางกฎหมาย หรือเกี่ยวข้องกับความเป็นส่วนตัวอย่างมีนัยสำคัญ แม้ในขณะที่เอเจนต์อัตโนมัติเป็นผู้ขับเคลื่อนเครื่องมือ สำหรับการดำเนินการเหล่านี้ เซิร์ฟเวอร์ไม่ได้อ้างว่าทำงานโดยไม่มีการกำกับดูแลของมนุษย์ และการกำหนดค่าไม่สามารถทำให้เกตอ่อนลงได้ ใช้เกตร่วมกับโมเดลคีย์ API บนทรานสปอร์ตแบบเครือข่าย และร่วมกับการกำหนดขอบเขตสิทธิ์ขั้นต่ำของ enabled_tools ดู /connect/security-and-operations/

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

ข้อกล่าวอ้าง	แหล่งที่มา	`reference_id`
ควบคุมความเสี่ยง ณ จุดที่ (มนุษย์) ก่อให้เกิดความเสี่ยง	IEC 31010:2019

การตอบสนอง initialize ของ MCP จะมาพร้อมเวอร์ชันของโมเดลความเสี่ยง เพื่อให้ไคลเอนต์ตรวจพบการเปลี่ยนแปลงที่ไม่เข้ากันได้ รูปแบบสายข้อมูลบันทึกไว้ที่ /transports/mcp/

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

เครื่องมือ Premium ประกาศระดับความเสี่ยงของตนเองตามโมเดลสี่ระดับเดียวกัน การดำเนินการ Premium ที่ทำลายข้อมูล เช่น การปกปิดข้อมูล (redaction) ใช้เกตเดียวกันนี้ เกตเป็นส่วนหนึ่งของเซิร์ฟเวอร์ ไม่ใช่แพ็กเกจ Premium

ดูเพิ่มเติม

/connect/tool-catalog/ — ระดับความเสี่ยงของเครื่องมือหลักที่ผ่านการตรวจสอบแต่ละตัว
/connect/configuration/ — การแทนที่ความเสี่ยงแบบเพิ่มระดับเท่านั้น
/connect/security-and-operations/ — เกตทำงานร่วมกับโมเดลภัยคุกคามอย่างไร
/transports/mcp/ — รูปแบบสายข้อมูลการท้าทายแบบ in-band
/connect/overview/ — เกตอยู่ที่ใดในสถาปัตยกรรม