CLI pdfx: Setempat Dahulu, Awan Apabila Diperlukan
pdfx memproses PDF pada mesin anda secara lalai. Pilih mod awan dengan asas API dan kunci apabila anda perlukan laluan REST PDF123 yang dihoskan atau self-host.
PDF123 ialah nama produk. pdfx ialah CLI ringkas yang bercakap kepada operasi yang sama. Laluan lalainya ialah setempat: baca fail, jalankan operasi melalui pdf-core, tulis keluaran. Tiada akaun, tiada kunci API, tiada muat naik.
Setempat dahulu bermakna fail tidak pernah keluar
Panggilan biasa kelihatan seperti pdfx merge a.pdf b.pdf -o merged.pdf atau pdfx compress input.pdf. Pemprosesan berjalan di tempat binari itu berjalan. Itu sesuai untuk tugasan CI pada runner peribadi, skrip di sebelah kelompok invois, dan apa-apa kes yang memuat naik kepada pihak ketiga merupakan jawapan yang salah.
Mod setempat bukan pembungkus nipis yang secara senyap menghantar bait data ke tempat lain. CLI berkongsi daftar operasi yang sama dengan pelayan (pdf_core::ops::run). Jika anda mahukan laluan rangkaian, anda memilihnya secara nyata dengan --cloud.
Subarahan terbina dalam merangkumi operasi biasa: merge, split, compress, rotate, extract, OCR, convert, protect, unlock, watermark, dan kerja yang berkaitan. Keluaran setempat secara lalai ditulis ke fail melalui -o / --output; - menulis ke stdout.
--cloud ialah katalog yang sama melalui HTTP
Apabila anda memerlukan API yang dihoskan (atau pdfx-server anda sendiri), gunakan --cloud bersama --api-base dan --api-key (atau PDFX_API_KEY). Mod awan memerlukan curl di sebalik tabir dan gagal jika tiada kunci API ditetapkan. Contoh daripada skill yang diterbitkan:
pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
--api-base lalai kepada https://pdf123.xyz, iaitu API yang dihoskan. Untuk stack Docker Compose setempat, halakan ke http://127.0.0.1:8080. CLI menjadi klien kepada permukaan REST yang didokumentasikan di Pembangun; nama operasinya sejajar dengan alat portal dan OpenAPI (/v1/openapi.json).
Mod awan tidak mengubah erti sesuatu operasi. Operasi mampat masih pemampatan aliran qpdf; OCR masih memulangkan teks Markdown daripada laluan Rust, bukan lapisan PDF yang boleh dicari. Bendera CLI yang tertinggal dan dipetakan kepada parameter OCR era Java yang diabaikan (contohnya medan languages) tidak mengubah kontrak itu.
Mengapa wujud dua mod
Mod setempat menampung kepercayaan luar talian dan kos pusingan pergi balik yang sifar. Mod awan menampung had kadar yang dikongsi, menjalankan operasi pada mesin yang hanya mempunyai CLI dan curl, serta pasukan yang sudah mempunyai kunci API. Ejen juga boleh memanggil asas yang sama melalui MCP di /mcp atau skill di dist/skills/pdf-toolbox/SKILL.md. Indeks penemuan seperti /llms.txt membantu ejen pengekodan menemui laluan; ia bukan isyarat kedudukan Google.
Untuk cubaan semula yang selamat bagi POST yang mengubah keadaan terhadap API, hantar Idempotency-Key (lihat Idempotency-Key: Cubaan Semula Selamat untuk Tugasan PDF). Laluan awan CLI masih menghantar satu permintaan HTTP bagi setiap seruan; gunakan pengepala itu apabila pembalut anda membuat cubaan semula.
Memilih mod dalam amalan
Gunakan mod setempat apabila fail mesti kekal pada runner, apabila anda sudah mempunyai binari pdfx dan kebergantungan asli pada mesin itu, dan apabila kependaman lebih didominasi oleh operasi berbanding muat naik. Gunakan mod awan apabila kebergantungan berat hanya wujud pada pelayan, apabila anda mahukan had kadar dan pemeteran yang sama seperti klien API lain, atau apabila ejen sudah memegang kunci API untuk https://pdf123.xyz atau asas self-host anda.
Jangan campurkan jangkaan: OCR setempat masih mengikuti kontrak keluaran Markdown daripada misc/ocr-pdf; compress awan masih aliran qpdf, bukan subset fon. Suis mod mengubah tempat operasi berjalan, bukan semantik katalog.
Apa yang bukan CLI ini
pdfx bukan GUI desktop dan bukan pustaka OCR yang boleh dibenamkan ke dalam aplikasi lain. Ia ialah klien baris perintah untuk operasi PDF: setempat secara lalai, HTTP apabila anda memintanya. Kerja sekali melalui pelayar masih kekal di portal (Mampatkan PDF, OCR, dan selebihnya dalam katalog). Automasi yang lebih memilih binari boleh kekal menggunakan pdfx.
Perbandingan operasi yang sama merentas pelayar, curl, MCP, dan CLI diringkaskan di Operasi sama, empat klien. Mulakan dengan Pembangun untuk kunci dan OpenAPI, atau Self-host jika asas API sepatutnya menjadi stack Docker Compose anda sendiri.