Φτιαγμένο για πράκτορες τεχνητής νοημοσύνης, όχι μόνο για προγράμματα περιήγησης
Κάθε εργαλείο καταλόγου είναι σημείο REST στο /api/v1/ και MCP στο /mcp. Ανώνυμες κλήσεις χωρίς κλειδί API· οι αποτυχίες επιστρέφουν RFC 7807 problem+json.
Μια καρτέλα προγράμματος περιήγησης εξακολουθεί να λειτουργεί: διαλέγετε εργαλείο, ανεβάζετε αρχείο, κατεβάζετε το αποτέλεσμα. Οι πράκτορες και τα σενάρια καλούν τις ίδιες λειτουργίες χωρίς να ανοίξουν διεπαφή χρήστη. Και οι δύο διαδρομές καταλήγουν στον ίδιο κατάλογο.
Κάθε σελίδα εργαλείου είναι και σημείο API
Συγχώνευση, διαχωρισμός, συμπίεση, OCR, μετατροπή: κάθε εργαλείο του καταλόγου αντιστοιχεί σε μια διαδρομή /api/v1/…. Ανοίξτε τη σελίδα ενός εργαλείου και κατεβείτε στο Κλήση από κώδικα για ένα παράδειγμα curl χτισμένο από τις πραγματικές παραμέτρους του εργαλείου, όχι από ένα γενικό πρότυπο. Οι ανώνυμες κλήσεις δεν χρειάζονται λογαριασμό ούτε κλειδί API στον δημόσιο ιστότοπο· τα ανώνυμα προθέματα είναι /api/v1/general/, /api/v1/misc/, /api/v1/security/, /api/v1/convert/ και /api/v1/filter/.
Το παράδειγμα συγχώνευσης είναι συγκεκριμένο:
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. Στείλτε Idempotency-Key όταν μια επανάληψη δεν πρέπει να εκτελέσει δύο φορές μια μεταλλακτική εργασία. Οι φιλοξενούμενες απαντήσεις ανακοινώνουν X-RateLimit-Limit, X-RateLimit-Remaining και X-RateLimit-Reset· σε HTTP 429, διαβάστε το Retry-After (ανώνυμος περιορισμός ρυθμού).
Το OCR μέσω του ίδιου καταλόγου επιστρέφει Markdown (text/markdown) από το /api/v1/misc/ocr-pdf, όχι PDF με κρυφό στρώμα κειμένου. Οι πράκτορες που περιμένουν αναζητήσιμο PDF από αυτό το σημείο θα χειριστούν λανθασμένα τη λήψη· η σύμβαση είναι εξαγωγή κειμένου για αγωγούς επεξεργασίας, όχι επανεγγραφή τύπου OCRmyPDF.
MCP για πελάτες που μιλούν τη γλώσσα του
Το MCP (Model Context Protocol) επιτρέπει σε πελάτες πρακτόρων να ανακαλύπτουν και να καλούν εργαλεία ως συναρτήσεις, αντί να συλλέγουν τεκμηρίωση από σελίδες. Αυτός ο ιστότοπος εκθέτει διακομιστή MCP στο /mcp, δίπλα στο REST API, ώστε ένας συμβατός πελάτης να συνδεθεί μία φορά και να πάρει ολόκληρο τον κατάλογο.
MCP και REST μοιράζονται τις ίδιες προσδοκίες πιστοποίησης: ανώνυμη πρόσβαση όπου τα προθέματα των εργαλείων το επιτρέπουν, κλειδιά API για σταθερή αυτοματοποίηση και για αυτο-φιλοξενούμενους διακομιστές με έλεγχο πρόσβασης. Το να στρέφετε έναν πράκτορα στο /mcp δεν είναι διαφορετικό προϊόν από το να στρέφετε το curl στο /api/v1/…. Τεκμηρίωση: MCP για προγραμματιστές.
Τα σφάλματα είναι δομημένα, όχι αόριστο κείμενο
Οι αποτυχίες επιστρέφουν application/problem+json (κατά το RFC 7807), όχι ένα γυμνό 500 ή ένα «κάτι πήγε στραβά». Κάθε φορτίο έχει σταθερό κωδικό (rate_limited, bad_request, invalid_document, missing_dependency και παρόμοιους), μια αναγνώσιμη υπόδειξη και συχνά ένα επόμενο βήμα. Οι άνθρωποι μπορούν να το σαρώσουν· οι πράκτορες μπορούν να αποφασίσουν επανάληψη, αλλαγή αρχείου ή διακοπή χωρίς να χρειαστεί κάποιος να αποκωδικοποιήσει ίχνος στοίβας.
Αυτή η δομή μετράει περισσότερο από μια φιλική σελίδα σφάλματος HTML όταν ο καλών είναι σενάριο. Αναφορά: Σφάλματα για προγραμματιστές.
Το llms.txt είναι για εργαλεία, όχι για κατάταξη
Το /llms.txt είναι ευρετήριο απλού κειμένου με κάθε εργαλείο (όνομα, σύντομη περιγραφή, URL), παραγόμενο από τον ίδιο κατάλογο που τροφοδοτεί τον ιστότοπο. Πράκτορες προγραμματισμού και εργαλεία τεκμηρίωσης μπορούν να το διαβάσουν σαν README. Δεν είναι μοχλός κατάταξης στη Google: η Αναζήτηση αγνοεί το /llms.txt (πηγές: οδηγός της Google για βελτιστοποίηση για AI). Επειδή παράγεται αυτόματα, δεν μπορεί να ξεπεραστεί σιωπηλά όπως ένα χειροκίνητα επεξεργασμένο αρχείο.
CLI και δεξιότητα μοιράζονται τα ίδια σχήματα
Το pdfx μπορεί να τρέξει τοπικό pdf-core ή --cloud απέναντι σε ένα βασικό URL. Η δεξιότητα για πράκτορες προγραμματισμού στο dist/skills/pdf-toolbox/SKILL.md τεκμηριώνει τα σχήματα curl για συγχώνευση και αγωγούς, ώστε οι πράκτορες να μην εφεύρουν δεύτερο συμβόλαιο. Τέσσερις πελάτες, ένας κατάλογος: Ίδια λειτουργία, τέσσερις πελάτες.
Η διαδρομή του προγράμματος περιήγησης δεν αλλάζει
Το να ρίχνετε ένα αρχείο σε μια καρτέλα λειτουργεί ακριβώς το ίδιο. Η επιπλέον επιφάνεια είναι τα ίδια σημεία για έναν πράκτορα, ένα σενάριο ή ένα CI: ίδια επεξεργασία, χωρίς άνθρωπο στη μέση. Η αυτο-φιλοξενία κρατά αυτή την επιφάνεια στο δίκτυό σας (Αυτο-φιλοξενία)· η φιλοξενούμενη υπηρεσία παραμένει η ανώνυμη δοκιμαστική διαδρομή.
Αναφορά API: Swagger. Τα βασικά για οποιαδήποτε διαδρομή: Βοήθεια και Προγραμματιστές.