การดำเนินการเดียวกัน สี่ไคลเอนต์: เบราว์เซอร์, curl, MCP, pdfx

ไคลเอนต์สี่ตัวดูเหมือนสี่ผลิตภัณฑ์ แต่แชร์แคตตาล็อกเดียวกัน ลองดู Merge เป็นตัวอย่างงานที่จับต้องได้: รวม PDF ตามลำดับอัปโหลดโดยไม่แปลงหน้าเป็นภาพ แพตเทิร์นเดียวกันใช้กับเครื่องมืออื่นในแคตตาล็อกทั้งหมด บีบอัด OCR แปลงไฟล์ และที่เหลือ: op เดียว สี่วิธีเรียก

เบราว์เซอร์

เปิด /merge เพิ่มไฟล์ตามลำดับที่ต้องการ กด Process แล้วดาวน์โหลด เครื่องมือในแคตตาล็อกไม่ต้องมีบัญชี บล็อก “Call this from code” บนหน้าสร้าง curl จากฟิลด์ชุดเดียวกับฟอร์มส่ง UI กับสัญญา HTTP จึงสอดคล้องกัน

บล็อกนั้นไม่ใช่ข้อความโฆษณา มันสร้างจากนิยามเครื่องมือที่พอร์ทัลใช้กับฟอร์มอยู่แล้ว เมื่อพารามิเตอร์ถูกเปลี่ยนชื่อ ทั้งสองที่จึงเปลี่ยนพร้อมกัน ถ้าฟอร์มรับ sortType=byFileName ตัวอย่าง curl ก็พกฟิลด์เดียวกันได้

curl / REST

curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
  -F "[email protected]" \
  -F "[email protected]" \
  -o merged.pdf

การเรียกแคตตาล็อกแบบไม่ระบุตัวตนไม่ต้องใช้คีย์ ส่วนคีย์จาก Developers ให้งานอัตโนมัติมีตัวตนคงที่ และให้เซิร์ฟเวอร์ที่โฮสต์เองมีประตูป้องกัน OpenAPI อยู่ที่ /v1/openapi.json

งานหลายขั้นใช้ POST /api/v1/pipeline รับ op เรียงลำดับในฟิลด์ steps เช่น รวม แล้วประทับลายน้ำ แล้วบีบอัด ส่ง Idempotency-Key เมื่อการลองใหม่ต้องไม่รันงานซ้ำ การเล่นซ้ำที่สำเร็จอาจคืนพร้อมเฮดเดอร์ Idempotency-Replayed ส่วนความล้มเหลวใช้ application/problem+json พร้อมรหัสคงที่อย่าง rate_limited และ bad_request (Developers errors)

การตอบกลับแบบโฮสต์ยังประกาศ X-RateLimit-Limit, X-RateLimit-Remaining และ X-RateLimit-Reset และ HTTP 429 มี Retry-After ให้ถือเฮดเดอร์เหล่านั้นเป็นงบสด ไม่ใช่ตัวเลขจากบทความ (การจำกัดอัตราแบบไม่ระบุตัวตน)

MCP

เอเจนต์ที่พูด Model Context Protocol เชื่อมต่อ /mcp ค้นพบการรวมไฟล์เป็นเครื่องมือหนึ่ง และเรียกด้วยเรื่องคีย์ API ชุดเดียวกับ REST เอกสาร: Developers MCP

MCP ไม่ใช่แคตตาล็อกที่สอง แต่เป็นโปรโตคอลค้นพบและเรียกใช้บนการดำเนินการชุดเดียวกับที่ OpenAPI ระบุ ถ้า op ใดหายไปจาก MCP นั่นคือบั๊กของเซิร์ฟเวอร์ ไม่ใช่แผนผลิตภัณฑ์แยก จับคู่ MCP กับ /llms.txt เมื่อต้องการดัชนีร้อยแก้วของเครื่องมือก่อนไคลเอนต์เชื่อมต่อ

CLI pdfx

pdf-core ในเครื่อง:

pdfx merge a.pdf b.pdf -o merged.pdf

หรือใช้เซิร์ฟเวอร์ตัวเดียวกับที่พอร์ทัลใช้:

pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf

โหมดในเครื่องไม่อัปโหลดอะไร ส่วนโหมดคลาวด์ยิง base URL ของคุณด้วยรูป multipart ชุดเดียวกับ curl สกิลสำหรับเอเจนต์ที่ dist/skills/pdf-toolbox/SKILL.md บันทึกรูปการรวมและ pipeline ชุดเดียวกัน เอเจนต์จึงไม่ต้องประดิษฐ์ OpenAPI อีกชุด

OCR ผ่านไคลเอนต์ใดก็ตามยังคืน Markdown จาก /api/v1/misc/ocr-pdf ไม่ใช่เลเยอร์ข้อความที่ซ่อนอยู่ ข้อเท็จจริงนี้เป็นส่วนหนึ่งของสัญญาที่แชร์กัน ถ้าเปลี่ยนชนิดข้อมูลที่คืนในไคลเอนต์เดียวโดยไม่แก้ตัวอื่น ก็เท่ากับผิดคำสัญญา “op เดียวกัน” ส่วน Compress ยังอยู่ที่ /api/v1/misc/compress-pdf สำหรับบีบอัดสตรีมใหม่ เป็น op คนละอันกับการรวม และเข้าถึงได้สี่ทางเดียวกัน

ทำไมความเหมือนจึงสำคัญ

ถ้าการรวมบนเบราว์เซอร์กับการรวมผ่าน API แยกทางกัน งานอัตโนมัติจะถอยหลังเงียบ ๆ ขณะที่หน้าเดโม่ยังดูปกติ หนึ่ง op สี่ทางจับคือประเด็นทั้งหมด พอร์ทัลเป็นไคลเอนต์ที่ช่วยให้สะดวก ไม่ใช่การทำงานชุดที่สองของการรวม บีบอัด หรือ OCR

นั่นเป็นเหตุผลเดียวกับที่ไม่มีเดสก์ท็อปฟอร์ก เพราะต้นไม้ UI ต้นที่ห้าจะสร้างปัญหาเดิมขึ้นใหม่ภายใต้ชื่อไบนารีอื่น ภาพรวมที่กว้างกว่า: สร้างมาเพื่อเอเจนต์ AI ไม่ใช่แค่เบราว์เซอร์ เหตุผลที่ข้ามแอปเดสก์ท็อป: ทำไมเราจึงไม่ทำแอปเดสก์ท็อป การตั้ง API บนเครือข่ายของคุณ: Self-host