คู่มือนักพัฒนา NextPDF Connect

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

NextPDF Connect (nextpdf/server) ครอบเอนจิน NextPDF PDF 2.0 ที่ไม่ผูกกับเฟรมเวิร์กให้เป็นบริการ โดยไม่สร้างกระบวนการสร้าง PDF ขึ้นใหม่ เอนจินเปิดเผยความสามารถแต่ละอย่างเป็นเครื่องมือที่มีชื่อและสคีมา แล้วให้บริการแคตตาล็อกนั้นผ่านทรานสปอร์ตสามแบบ ได้แก่ Model Context Protocol (MCP) บนอินพุตและเอาต์พุตมาตรฐาน Representational State Transfer (REST) Application Programming Interface (API) และ gRPC ใช้คู่มือนี้เมื่อพัฒนาบนเซิร์ฟเวอร์ ขยายชุดเครื่องมือของเซิร์ฟเวอร์ หรือใช้งานในระบบโปรดักชัน

แนวคิดสามอย่างกำหนดการออกแบบนี้ ได้แก่ ทูลรีจิสทรี ทรานสปอร์ตอิสระสามแบบ และเกตยืนยันแบบมีมนุษย์ร่วมตัดสินใจ (human-in-the-loop, HITL) หน้านี้อธิบายว่าแนวคิดเหล่านี้ทำงานร่วมกันอย่างไร และควรใช้งานอย่างไรโดยไม่ทำให้แบบจำลองความปลอดภัยอ่อนแอลง สำหรับสัญลักษณ์ของเครื่องมือ การเรียกโพรซีเยอร์ระยะไกล (remote procedure call, RPC) และข้อความที่แม่นยำ โปรดดู API reference เพิ่มเติม

ข้อกำหนดเบื้องต้นคือ PHP 8.4, Composer 2 และ — สำหรับทรานสปอร์ตแบบเครือข่าย — ไบนารี RoadRunner กับ API key อย่างน้อยหนึ่งคีย์ ติดตั้งได้โดยรันคำสั่ง composer require nextpdf/server

ขอบเขตทางสถาปัตยกรรม

รักษาความรับผิดชอบแต่ละอย่างให้อยู่ฝั่งที่ถูกต้องของขอบเขตนั้น เครื่องมือเป็นตัวห่อหุ้มบาง ๆ รอบการเรียกเอนจิน ต้องไม่มีการตีความเค้าโครง ความหมายของเอกสาร หรือตรรกะการแปลงรูปอยู่ภายใน

เลเยอร์	เป็นเจ้าของโดย	ความรับผิดชอบ	อย่าใส่ไว้ที่นี่
ไคลเอนต์หรือเอเจนต์	การผสานรวมของคุณ	เลือกเครื่องมือที่จะเรียก ส่งต่อคำท้าทายการยืนยันไปยังมนุษย์	ตรรกะของเอนจินหรือการตรวจหาระดับชั้น
ทรานสปอร์ต	`nextpdf/server`	จัดรูปคำขอเป็น JSON-RPC, HTTP หรือ Protocol Buffers ยืนยันตัวตน และกำหนดเส้นทางไปยังตัวดำเนินการเครื่องมือ	ความหมายของเอกสาร
ทูลรีจิสทรี	`nextpdf/server`	ค้นพบระดับชั้น ลงทะเบียนเครื่องมือภายใต้รายการอนุญาตด้านความปลอดภัย ค้นหาเครื่องมือตามชื่อ	การสร้าง PDF
เครื่องมือ	`nextpdf/server`	ตรวจสอบความถูกต้องของอาร์กิวเมนต์กับสคีมาอินพุตและเรียกเอนจิน	การตีความเค้าโครงหรือการประสานงานหลายขั้นตอน
เกตยืนยัน	`nextpdf/server`	พักการดำเนินการ `ApprovalRequired` ไว้จนกว่ามนุษย์จะอนุมัติ	การยืนยันตัวตนของผู้เรียก
เอนจิน	`nextpdf/core` (และ `nextpdf/premium`)	สร้าง ตรวจสอบ และแปลงเนื้อหา PDF	ประเด็นเรื่องทรานสปอร์ตหรือการยืนยันตัวตน

วงจรชีวิตขณะรันไทม์

ทรานสปอร์ตแต่ละแบบมีจุดเริ่มต้นและแฟกทอรีสำหรับบูตของตนเอง และสร้างกราฟอ็อบเจกต์ของตนอย่างชัดเจน ไม่มีคอนเทนเนอร์สำหรับฉีดพึ่งพา (dependency injection) ให้ลงทะเบียน

โหลดการกำหนดค่า เซิร์ฟเวอร์ MCP แปลค่าการกำหนดค่าจากตัวแปรสภาพแวดล้อม (NEXTPDF_MCP_*) ตามด้วยส่วน nextpdf_mcp ของไฟล์ YAML แล้วจึงใช้ค่าเริ่มต้นในตัว และให้ผลลัพธ์เป็น readonlyMcpConfig เซิร์ฟเวอร์ REST และ gRPC อ่าน HttpConfig จากตัวแปรสภาพแวดล้อม NEXTPDF_* โปรดดู Configuration เพิ่มเติม
สร้างนโยบายความปลอดภัย ระบบสร้างรายการอนุญาต enabled_tools ก่อนรีจิสทรี จึงจำกัดการค้นพบตั้งแต่การลงทะเบียนครั้งแรก
สร้างรีจิสทรีและค้นพบเครื่องมือ ToolRegistry::registerDefaults() ลงทะเบียนระดับชั้น core ก่อน จากนั้นลงทะเบียนผู้ให้บริการ Pro และ Enterprise เมื่อแปลค่าคลาสของผู้ให้บริการเหล่านั้นได้ แล้วจึงลงทะเบียนผู้ให้บริการ AST และ mutation ที่มาในชุดภายใต้เกตสภาพแวดล้อมของแต่ละตัว
สร้างที่เก็บข้อมูลร่วมและเกต ระบบสร้างที่เก็บเอกสารในหน่วยความจำจาก TTL และความจุที่กำหนดไว้ ส่วน ConfirmationGate จะประกอบขึ้นพร้อมที่เก็บโทเค็นแบบใช้ครั้งเดียว
ผูกทรานสปอร์ต MCP เข้าสู่ลูปอ่าน-จัดการ-เขียนบน stdio จนถึงจุดสิ้นสุดไฟล์ REST และ gRPC สร้างตารางเส้นทางหรือบริการของตนจากระดับชั้นที่ตรวจพบ จากนั้นส่งมอบลูปคำขอให้ RoadRunner

จากนั้นคำขอจะไหลตามเส้นทางนี้: ยืนยันตัวตน (REST และ gRPC) แปลค่าเครื่องมือหรือการดำเนินการ รันเกตยืนยันสำหรับงาน ApprovalRequired ดำเนินการกับเอนจิน และส่งผลลัพธ์กลับ โปรดดู Boot and discovery เพิ่มเติม

แบบจำลองทรานสปอร์ต

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

ทรานสปอร์ต	จุดเริ่มต้น	เมื่อใดควรเลือก
MCP	`bin/nextpdf-mcp`	ไคลเอนต์ปัญญาประดิษฐ์ (artificial intelligence, AI) ภายในเครื่องที่เริ่มเซิร์ฟเวอร์เป็นกระบวนการย่อยที่เชื่อถือได้
REST	`bin/nextpdf-server`	ไคลเอนต์ HTTP แบบเครือข่าย อธิบายด้วยเอกสาร OpenAPI 3.1
gRPC	`bin/nextpdf-grpc`	ไคลเอนต์แบบมีชนิดและสตรีมมิง ใช้บริการ `nextpdf.connect.v1.NextPDFConnect` เป็นบริการหลัก

เลือกทรานสปอร์ตตามโปรไฟล์ RoadRunner ที่รันอยู่: .rr.yaml (REST เท่านั้น) .rr.grpc.yaml (gRPC เท่านั้น) หรือ .rr.full.yaml (ทั้งสอง) ทรานสปอร์ต MCP เป็นกระบวนการย่อยปกติและไม่ต้องใช้ตัวควบคุมดูแล สำหรับรายละเอียดระดับสายสื่อสาร โปรดดู MCP transport REST transport และ gRPC transport เพิ่มเติม

โครงสร้างการนำไปใช้งานที่แนะนำ

รันทรานสปอร์ตแบบเครือข่ายภายใต้ RoadRunner พร้อมที่เก็บข้อมูลร่วมและคีย์ที่เมานต์จาก secret โปรไฟล์รวมช่วยให้ REST และ gRPC ใช้ตัวควบคุมดูแลเดียวกัน

เส้นทางหรือการตั้งค่า	วัตถุประสงค์
`.rr.full.yaml`	โปรไฟล์รวม REST และ gRPC ภายใต้ตัวควบคุมดูแลตัวเดียว
`NEXTPDF_API_KEYS_FILE`	เส้นทางไปยังไฟล์ API key ที่เมานต์จาก secret และโหลดซ้ำแบบฮอตรีโหลด
`NEXTPDF_REDIS_HOST`	เปิดใช้ที่เก็บอัตราจำกัด ที่เก็บ idempotency และที่เก็บเอกสารที่อิง Redis สำหรับพูลแบบหลายเวิร์กเกอร์
`NEXTPDF_WORKER_COUNT` / `NEXTPDF_GRPC_WORKER_COUNT`	การกำหนดขนาดพูลเวิร์กเกอร์สำหรับพูล HTTP และ gRPC
ไดเรกทอรีฐานสำหรับเอาต์พุต	วอลุมเฉพาะที่มีสิทธิ์ระบบไฟล์แบบสิทธิ์น้อยที่สุดสำหรับเครื่องมือที่ส่งออกเป็นไฟล์

ตัวอย่างเชลล์ต่อไปนี้บูตโปรไฟล์รวมพร้อมคีย์ที่เมานต์จาก secret และที่เก็บ Redis ร่วม ตัวอย่างนี้ไม่มี secret ใด ๆ คีย์ในตัวอย่างถูกเมานต์ไว้ที่ /run/secrets/api-keys

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
export NEXTPDF_WORKER_COUNT=8
export NEXTPDF_GRPC_WORKER_COUNT=4
export NEXTPDF_REDIS_HOST=redis
./vendor/bin/rr serve -c .rr.full.yaml

สำหรับพูลแบบหลายเวิร์กเกอร์ ให้กำหนดค่า Redis และยืนยันว่ามี ext-redis อยู่ในอิมเมจที่กำลังรัน หากไม่มี ที่เก็บอัตราจำกัด ที่เก็บ idempotency และที่เก็บเอกสารจะแยกตามเวิร์กเกอร์ โปรดดู Deployment เพิ่มเติม

ทูลรีจิสทรีและการแปลค่าระดับชั้น

NextPDF\Server\ToolRegistry (src/ToolRegistry.php) สร้างแคตตาล็อกขณะบูต ระดับชั้นเป็นค่าคงที่เชิงประกาศ: เครื่องมือแต่ละตัวคืนค่า tier() และ riskLevel() ของตนเอง รีจิสทรีไม่เคยอนุมานระดับชั้นจากเนมสเปซหรือการจัดแพ็กเกจ

ระดับชั้น core ลงทะเบียนโดยไม่มีเงื่อนไข: เครื่องมือเอกสารและเครื่องมือวินิจฉัย รวมถึง generate_barcode เมื่อมีรีจิสทรีตัวเข้ารหัสบาร์โค้ดของ core อยู่ และ parse_pdf เฉพาะเมื่อ NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED เป็น true หรือ 1
ผู้ให้บริการ Pro และ Enterprise ลงทะเบียนเมื่อแปลค่าคลาสผู้ให้บริการได้ โดยตรวจสอบด้วย class_exists() ระดับชั้นที่ไม่มีอยู่จะถูกข้ามไปอย่างเงียบ ๆ
ผู้ให้บริการ AST และ mutation ที่มาในชุด ลงทะเบียนภายใต้ระดับชั้น Pro โดยควบคุมด้วย NEXTPDF_AST_TOOLS_ENABLED และ NEXTPDF_MUTATION_TOOLS_ENABLED (เปิดใช้ทั้งคู่โดยค่าเริ่มต้น)
ตัวกรองนโยบายความปลอดภัย นำการลงทะเบียนทุกครั้งมาตัดกับรายการอนุญาต enabled_tools รายการอนุญาตทำหน้าที่ลบออก ไม่เคยเพิ่มเข้า ตัวนับต่อระดับชั้นนับเฉพาะเครื่องมือที่นโยบายยอมรับ

การตอบกลับ initialize ของ MCP และเอนด์พอยต์ GET /api/v1/capabilities ของ REST รายงานจำนวนต่อระดับชั้นและจำนวนรวมที่ได้ ให้ถือว่าจำนวนรวมที่ระบุตายตัวในข้อความบรรยายนั้นล้าสมัยเสมอ และให้สอบถามเซิร์ฟเวอร์ที่กำลังรัน โปรดดู Tool catalog เพิ่มเติม

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

เครื่องมือทุกตัวประกาศหนึ่งในสี่ระดับความเสี่ยงจาก enum RiskLevel (src/Config/RiskLevel.php): Safe (0), Caution (1), Review (2) และ ApprovalRequired (3) การบันทึกการตรวจสอบเริ่มมีผลตั้งแต่ระดับ Caution ขึ้นไป การลบล้างการกำหนดค่าอาจยกระดับความเสี่ยงของเครื่องมือได้ แต่ตามการออกแบบแล้ว ไม่อาจลดระดับเครื่องมือที่เป็น ApprovalRequired ได้ ตัวโหลดการกำหนดค่าจะโยนข้อยกเว้นในขณะโหลด และเซิร์ฟเวอร์จะปฏิเสธการบูตแทนที่จะรันด้วยเกตที่อ่อนแอลง

เมื่อเครื่องมือ ApprovalRequired ถูกเรียกโดยไม่มีโทเค็นที่ถูกต้อง ConfirmationGate (src/Mcp/ConfirmationGate.php) จะคืนค่าโทเค็นคำท้าทายแบบใช้ครั้งเดียว โทเค็นผูกกับชื่อเครื่องมือ นอนซ์แบบสุ่ม และอายุการใช้งาน (time-to-live, TTL) 300 วินาที แต่ไม่ผูกกับอาร์กิวเมนต์ เพราะไคลเอนต์อาจซีเรียลไลซ์อาร์กิวเมนต์ใหม่ด้วยลำดับคีย์ที่ต่างกันเมื่อลองใหม่ เอเจนต์ส่งต่อคำท้าทายไปยังมนุษย์และเรียกเครื่องมือเดิมอีกครั้งโดยใส่โทเค็นในอาร์กิวเมนต์ _confirmation_token โทเค็นถูกใช้หมดเมื่อนำมาใช้ และปลดล็อกการเรียกที่ผ่านเกตได้เพียงหนึ่งครั้งพอดี

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

<?php

declare(strict_types=1);

namespace App\Connect;

use JsonException;

/**
 * Drives one tool call and resolves an ApprovalRequired confirmation
 * challenge through a human approver before retrying.
 */
final readonly class ConfirmingToolCaller
{
    public function __construct(
        private McpClientInterface $client,
        private HumanApproverInterface $approver,
    ) {}

    /**
     * @param non-empty-string     $toolName
     * @param array<string, mixed> $arguments
     *
     * @return array<string, mixed> The tool result content
     *
     * @throws JsonException         When a response cannot be decoded
     * @throws ApprovalDeniedException When the human declines the challenge
     */
    public function call(string $toolName, array $arguments): array
    {
        $response = $this->client->callTool($toolName, $arguments);

        if (!isset($response['challenge'], $response['token'])) {
            return $response;
        }

        $challenge = (string) $response['challenge'];
        $token = (string) $response['token'];

        if (!$this->approver->approve($toolName, $challenge)) {
            throw new ApprovalDeniedException($toolName);
        }

        $arguments['_confirmation_token'] = $token;

        return $this->client->callTool($toolName, $arguments);
    }
}

เชื่อมต่อ McpClientInterface, HumanApproverInterface และ ApprovalDeniedException เข้ากับทรานสปอร์ตและช่องทางอนุมัติของคุณเอง การลองใหม่ใช้อาร์กิวเมนต์เดิมพร้อมโทเค็นที่ออกให้ อย่าอนุมัติคำท้าทายโดยอัตโนมัติโดยไม่มีการตัดสินใจของมนุษย์ โปรดดู HITL risk tiers เพิ่มเติม

จุดขยาย

ขยายเซิร์ฟเวอร์โดยเพิ่มเครื่องมือและจัดเตรียมผู้ให้บริการ ไม่ใช่โดยการแก้ไขรีจิสทรี

จุดขยาย	ใช้สำหรับ	ข้อจำกัด
คลาสที่อิมพลีเมนต์ `ToolInterface`	ความสามารถใหม่ของเอนจินที่เปิดเผยเป็นเครื่องมือ	ประกาศ `tier()`, `riskLevel()`, `category()` และ `inputSchema()` ที่เป็น JSON Schema ให้คลาสคงบทบาทเป็นตัวห่อหุ้มเอนจินบาง ๆ
ผู้ให้บริการ `ToolProviderInterface` หนึ่งตัว	การลงทะเบียนชุดเครื่องมือสำหรับระดับชั้นหนึ่ง	ผู้ให้บริการ Pro และ Enterprise ถูกค้นพบด้วย `class_exists()` อย่ากำหนดให้เซิร์ฟเวอร์ต้องการแพ็กเกจกรรมสิทธิ์
`enabled_tools` รายการอนุญาต	การกำหนดขอบเขตแคตตาล็อกที่เปิดเผยตามหลักสิทธิ์น้อยที่สุด	รายการอนุญาตทำหน้าที่ลบออกเท่านั้น ไม่อาจลงทะเบียนเครื่องมือที่ไม่มีอยู่ได้
`risk_level_overrides`	การเสริมความแข็งแกร่งของการนำไปใช้งานโดยยกระดับความเสี่ยงของเครื่องมือ	ยกระดับได้อย่างเดียว การลดระดับเครื่องมือ `ApprovalRequired` จะทำให้บูตล้มเหลว
รอยต่อสำหรับฉีดทรานสปอร์ตและเวิร์กเกอร์	การทดสอบเซิร์ฟเวอร์แบบแยกเดี่ยว	ขอบเขตเหล่านี้มีไว้สำหรับการทดสอบ ไม่ใช่สำหรับการเชื่อมต่อในแอปพลิเคชันจริง

ขั้นตอนการดำเนินงาน

เลือกโปรไฟล์ รัน .rr.yaml, .rr.grpc.yaml หรือ .rr.full.yaml สำหรับทรานสปอร์ตที่เปิดเผย
เมานต์คีย์จาก secret ชี้ NEXTPDF_API_KEYS_FILE ไปยังไฟล์ secret เลือกใช้ที่เก็บคีย์แบบไฟล์ที่ฮอตรีโหลดได้ เพื่อให้การหมุนเวียนไม่ต้องรีสตาร์ต
กำหนดค่าที่เก็บข้อมูลร่วม ตั้งค่า NEXTPDF_REDIS_HOST และยืนยัน ext-redis สำหรับพูลใด ๆ ที่ใหญ่กว่าหนึ่งเวิร์กเกอร์ วางที่เก็บงาน SQLite ไว้บนวอลุมที่เวิร์กเกอร์ทุกตัวเขียนได้
ยุติ TLS รัน REST หลังตัวยุติ Transport Layer Security (TLS) รัน gRPC ด้วย mutual TLS บนเครือข่ายที่ไม่เชื่อถือทุกเครือข่าย โดยจัดหาคีย์เซิร์ฟเวอร์ ใบรับรองเซิร์ฟเวอร์ และผู้ออกใบรับรองไคลเอนต์เป็น secret สำหรับการนำไปใช้งาน
ตรวจสอบสถานะ ใช้เอนด์พอยต์นิรนาม /healthz และ /readyz (REST) หรือ RPC HealthCheck และ ReadinessCheck (gRPC) สำหรับการตรวจสอบของออร์เคสเตรเตอร์
กำหนดขอบเขตแคตตาล็อก จำกัด enabled_tools ให้เหลือชุดขั้นต่ำที่การผสานรวมต้องใช้

ตรวจสอบสถานะของ Redis แทนการสันนิษฐาน เซิร์ฟเวอร์ REST จะถอยกลับไปใช้ที่เก็บในหน่วยความจำเมื่อการเชื่อมต่อ Redis ที่กำหนดไว้ล้มเหลว โปรดดู Deployment และ Security and operations เพิ่มเติม

การจัดการความล้มเหลว

ความล้มเหลว	ปรากฏที่ใด	การตอบสนองที่แนะนำ
ไม่รู้จัก `document_id`	การดำเนินการเครื่องมือ	คืนค่าข้อผิดพลาดที่กำหนดไว้ให้ผู้เรียก และสั่งให้เรียก `create_pdf` ก่อน
ETag ที่ล้าสมัยในการกลายพันธุ์	เครื่องมือกลายพันธุ์ AST	อ่านเอกสารใหม่ด้วย `get_document_ast` และลองใหม่ด้วย ETag ที่เป็นปัจจุบัน
API key หายไปหรือไม่ถูกต้อง (REST)	มิดเดิลแวร์ยืนยันตัวตน	คืนค่า `401` พร้อมคำท้าทาย `WWW-Authenticate: Bearer` อย่าเปิดเผยว่าส่วนใดผิด
ระดับชั้นไม่มีสิทธิ์ (REST)	การอนุญาต	คืนค่า `403` ระดับชั้นของคีย์ต่ำกว่าระดับชั้นของการดำเนินการ
เส้นทางระดับชั้นไม่มีอยู่ (REST)	เราเตอร์	คืนค่า `404` แพ็กเกจไม่ได้ติดตั้งไว้ นี่เป็นพฤติกรรมที่คาดหมายได้ ไม่ใช่ข้อผิดพลาด
โทเค็นไม่ถูกต้อง (gRPC)	ตัวยืนยันตัวตน gRPC	ทำให้การเรียกล้มเหลวด้วยสถานะ `UNAUTHENTICATED` ที่ส่งกลับ
เข้าถึง Redis ไม่ได้	ขณะบูตหรือรันไทม์	ลดระดับไปใช้ที่เก็บในหน่วยความจำ แจ้งเตือนผู้ปฏิบัติงานและตรวจสอบสถานะของ Redis
เส้นทางเอาต์พุตอยู่นอกไดเรกทอรีฐาน	เครื่องมือที่ส่งออกเป็นไฟล์	ล้มเหลวแบบปิด เส้นทางถูกแปลงเป็นรูปแบบบัญญัติและการเดินทะลุไดเรกทอรีถูกปฏิเสธ

แสดงความล้มเหลวของเอนจินเป็นอ็อบเจกต์ข้อผิดพลาดที่กำหนดไว้ ไม่ใช่ความสำเร็จแบบเงียบ ๆ API reference ให้รายละเอียดแบบจำลองข้อผิดพลาดสำหรับแต่ละทรานสปอร์ต

ค่าเริ่มต้นที่ปลอดภัย

ประเด็น	ค่าเริ่มต้น	เมื่อใดควรลบล้าง
`parse_pdf`	ปิดใช้งาน (เลือกเปิดใช้ผ่าน `NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`)	เปิดใช้เฉพาะเมื่อการผสานรวมต้องการการตรวจสอบเชิงโครงสร้าง
`enabled_tools`	ว่าง (อนุญาตเครื่องมือที่ค้นพบทั้งหมด)	ตั้งรายการอนุญาตที่ชัดเจนสำหรับการนำไปใช้งานตามหลักสิทธิ์น้อยที่สุด
การลบล้างความเสี่ยง	ไม่มี	ยกระดับความเสี่ยงสำหรับการนำไปใช้งานที่เสริมความแข็งแกร่ง อย่าพยายามลดระดับ
`document_ttl` / `max_documents`	1800 วินาที / 50 เอกสาร	ลดลงสำหรับการนำไปใช้งานที่ไวต่อถิ่นที่อยู่ของข้อมูลหรือมีหน่วยความจำจำกัด
`allow_file_output`	เปิดใช้งาน	ตั้งเป็น `false` สำหรับการนำไปใช้งานแบบไร้สถานะที่ไวต่อถิ่นที่อยู่ของข้อมูล
จำนวนเวิร์กเกอร์	สี่ (HTTP), สอง (gRPC)	กำหนดขนาดเทียบกับเวลาแฝงที่สังเกตได้และคอร์ที่มีอยู่
ตัวรับฟัง REST	HTTP แบบข้อความธรรมดาหลังตัวยุติ TLS	ยุติ TLS ที่ขอบเครือข่ายเสมอ อย่าเปิดเผยข้อความธรรมดาบนเครือข่ายที่ไม่เชื่อถือ
gRPC บนเครือข่ายที่ไม่เชื่อถือ	mutual TLS	จำเป็น อย่ารันตัวรับฟัง gRPC แบบข้อความธรรมดาบนเครือข่ายที่ไม่เชื่อถือ

รายการตรวจสอบการทดสอบ

การทดสอบรีจิสทรียืนยันว่าระดับชั้น Pro หรือ Enterprise ที่ไม่มีอยู่ถูกข้ามไปอย่างเงียบ ๆ และแคตตาล็อก core ยังคงลงทะเบียนได้
การทดสอบรายการอนุญาตยืนยันว่า enabled_tools ลบออกและไม่เคยเพิ่มเครื่องมือที่รีจิสทรีไม่ได้ค้นพบ
การทดสอบเกตยืนยันยืนยันว่าเครื่องมือ ApprovalRequired คืนค่าคำท้าทายในการเรียกครั้งแรก รันหนึ่งครั้งด้วยโทเค็นแบบใช้ครั้งเดียวที่ถูกต้อง และทำให้โทเค็นหมดอายุหลังจาก TTL
การทดสอบการลดระดับยืนยันว่ารายการ risk_level_overrides ที่ทำให้เครื่องมือ ApprovalRequired อ่อนแอลงนั้นทำให้บูตล้มเหลว
การทดสอบการยืนยันตัวตนครอบคลุมคีย์ที่หายไป รูปแบบผิด ถูกปิดใช้งาน และหมดอายุบน REST (401 พร้อม WWW-Authenticate) และ gRPC (UNAUTHENTICATED) รวมถึงการปฏิเสธสิทธิ์ระดับชั้น (403)
การทดสอบการทำงานพร้อมกันยืนยันว่า ETag ที่ล้าสมัยทำให้การกลายพันธุ์ล้มเหลว และ idempotency_key ที่ซ้ำกันจะเล่นซ้ำผลลัพธ์ที่แคชไว้
การทดสอบการจำกัดขอบเขตเส้นทางยืนยันว่าเส้นทางเอาต์พุตที่แปลค่าไปอยู่นอกไดเรกทอรีฐานถูกปฏิเสธ
รักษาฟิกซ์เจอร์ให้เล็กและไม่มีข้อมูลอ่อนไหว อย่าคอมมิต API key จริงหรือเนื้อหาเอกสาร

ดูเพิ่มเติม

API reference — สัญลักษณ์ของเครื่องมือ, RPC และข้อความที่แม่นยำ
Tool catalog — ชุด core ที่ตรวจสอบแล้วและจำนวนขณะรันไทม์
HITL risk tiers — แบบจำลองความเสี่ยงและซองการยืนยัน
Configuration — ลำดับการแปลค่าและการลบล้างแบบยกระดับได้อย่างเดียว
Deployment — โปรไฟล์ RoadRunner, Redis และ mutual TLS
Security and operations — การยืนยันตัวตน ความปลอดภัยของทรานสปอร์ต และแบบจำลองภัยคุกคาม