同一操作，四種用戶端：瀏覽器、curl、MCP、pdfx
同一份 PDF123 合併有四種呼叫方式：瀏覽器表單、curl 打 REST、/mcp 上的 MCP，以及本機或 --cloud 的 pdfx，共用同一個 op 與同一套契約。
四種用戶端看起來像四套產品，其實共用同一份目錄。拿 合併 PDF 這個具體工作來說：依上傳順序把 PDF 合起來，不把頁面光柵化成影像。目錄裡其他工具（壓縮、OCR、轉換等）都是同一個模式：一個 op id，四種呼叫方式。
瀏覽器
打開 /zh-tw/merge，依你想要的順序加入檔案，按下處理，下載。目錄工具不需要帳號。頁面上的 「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
匿名呼叫目錄工具不需要金鑰。來自 開發者 的金鑰，給自動化一個穩定的身分，也給自架伺服器一道閘門。OpenAPI 在 /v1/openapi.json。
多步驟工作用 POST /api/v1/pipeline，在 steps 欄位裡接受有序的 op，例如先合併、再浮水印、再壓縮。重試不能重複執行同一份工作時，請發送 Idempotency-Key；成功的重放會帶回 Idempotency-Replayed。失敗使用 application/problem+json，錯誤碼是穩定的，例如 rate_limited、bad_request（開發者錯誤）。
代管回應也會標示 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset，HTTP 429 另含 Retry-After。請把這些標頭當成現場額度，不要背誦部落格裡的那個數字（匿名速率限制）。
MCP
會說 Model Context Protocol 的 Agent 連上 /mcp，把 merge 發現成一個工具，並用與 REST 相同的 API Key 身分呼叫。文件見 開發者 MCP。
MCP 不是第二份目錄。它是疊在 OpenAPI 已列出的同一批操作之上的探索與呼叫協定。某個 op 在 MCP 裡缺席，那是伺服器缺陷，不是另有一條產品路線圖。想在用戶端連線前先拿一份散文式的工具索引，可以把 MCP 和 /llms.txt 搭配使用。
pdfx CLI
本機 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
本機模式從不上傳；雲端模式用與 curl 相同的 multipart 形狀，打到你的 base URL。dist/skills/pdf-toolbox/SKILL.md 下的編碼 Agent skill 記錄了同一套 merge 與 pipeline 形狀，免得 Agent 再造一份 OpenAPI。
經上面任一用戶端做 OCR，回傳的仍是 /api/v1/misc/ocr-pdf 的 Markdown，不是隱藏文字層。這屬於共享契約的一部分：只在某個用戶端改掉回傳型別，就會破壞「同一 op」的承諾。壓縮仍由 /api/v1/misc/compress-pdf 做串流重壓縮，它和合併是不同的 op，但同樣有這四種到達方式。
為什麼一致性重要
如果瀏覽器合併與 API 合併哪天分了叉，自動化會悄悄退步，而演示頁看起來仍然正常。一個 op、四種把手，正是重點。入口網站是便利的用戶端，不是合併、壓縮或 OCR 的第二套實作。
這也是不做桌面分叉的原因：第五棵 UI 樹換個二進位名字，又會把同一種漂移問題複製一份。更完整的框架見 為 AI Agent 而建，不只為瀏覽器；桌面這個決定的來龍去脈見 為什麼我們不做桌面應用；要把 API 立到自己的網路上，見 自架。