Σχεδιασμός: Περιπτώσεις Χρήσης και Εργαλεία
Σε αυτήν τη σελίδα
Μάθημα αναθεωρήθηκε στις 3 Νοεμβρίου 2026 με βάση τις σελίδες τεκμηρίωσης της OpenAI Brainstorm plugin use cases και Define tools. Το προηγούμενο μάθημα εγκαθιστούσε ένα ανύπαρκτο πακέτο
@openai/apps-sdkκαι ένα αρχείο manifestchatgpt-app.json· η εγκατάσταση των πραγματικών εργαλείων (επίσημα MCP SDKs) πραγματοποιείται στο Μάθημα 4. Πηγές: Brainstorm plugin use cases · Define tools.
Ξεκινήστε με τις προσδοκίες, όχι με το API
Η τεκμηρίωση της OpenAI συμβουλεύει να ξεκινήσετε την ανάπτυξη ενός πρόσθετου πριν γράψετε καν μία γραμμή κώδικα: καταγράφοντας τι θα περιμένουν οι χρήστες από αυτό. Το όνομα του πρόσθετου, η περιγραφή, οι δεξιότητες, τα εργαλεία και το προϊόν στο οποίο συνδέεται δημιουργούν όλες προσδοκίες· η υλοποίησή σας πρέπει να τις καλύπτει, ή να έχει έναν σκόπιμο λόγο για να μην το κάνει.
Φανταστείτε κάποιον που έχει εγκαταστήσει το πρόσθετό σας χωρίς να διαβάσει την τεκμηρίωσή του. Τι θα του ζητήσει να κάνει; Για να το ανακαλύψετε, αντλήστε από εργασίες που οι χρήστες σας ήδη ολοκληρώνουν στο προϊόν σας, από αιτήματα υποστήριξης, ερωτήματα αναζήτησης, αιτήματα λειτουργιών, το λεξιλόγιο που χρησιμοποιούν και από προσωρινές λύσεις που τους αναγκάζουν να αντιγράφουν δεδομένα από ένα εργαλείο σε άλλο. Σημειώστε άμεσα αιτήματα που ονομάζουν το πρόσθετο, και έμμεσα αιτήματα που δηλώνουν μόνο τον στόχο: ένα πρόσθετο διαχείρισης έργων πρέπει να χειρίζεται το «Εμφάνισε τον πίνακα εκκίνησης της Acme» με τον ίδιο τρόπο όπως το «Τι εμποδίζει την εκκίνηση;».
Μην περιορίζετε αυτή την απογραφή σε ό,τι κάνει ήδη το API σας. Καταγράψτε πρώτα τις προσδοκίες και μετά συγκρίνετέ τες με ό,τι μπορείτε να παρέχετε με ασφάλεια και αξιοπιστία.
Η απογραφή περιπτώσεων χρήσης
Για κάθε περίπτωση χρήσης, η OpenAI συνιστά να απαντάτε σε επτά ερωτήσεις:
| Πεδίο | Ερώτηση |
|---|---|
| Στόχος | Τι προσπαθεί να επιτύχει το άτομο; |
| Παραδείγματα αιτημάτων | Πώς θα το διατύπωνε, άμεσα ή έμμεσα; |
| Αναμενόμενο αποτέλεσμα | Τι θα καθιστούσε επιτυχημένη την αλληλεπίδραση; |
| Απαιτούμενο πλαίσιο | Ποιες πληροφορίες, πρόσβαση λογαριασμού ή προηγούμενη κατάσταση απαιτούνται; |
| Δυνατότητα | Αρκεί μια δεξιότητα ή απαιτείται ένα εργαλείο MCP; |
| Όριο ασφαλείας | Θα μπορούσε να εκθέσει δεδομένα, να τροποποιήσει κατάσταση, να ξοδέψει χρήματα ή να επηρεάσει τρίτο μέρος; |
| Απόφαση | Πρώτη έκδοση, αργότερα, ή σκόπιμος αποκλεισμός; |
Ομαδοποιήστε αιτήματα που μοιράζονται έναν στόχο: τα «Εμφάνισε τις ανοιχτές εργασίες μου», «Τι πρέπει να κάνω σήμερα;» και «Δείξε τις εκπρόθεσμες εργασίες» πιθανότατα ανήκουν στην ίδια περίπτωση χρήσης αναθεώρησης εργασιών, με διαφορετικά φίλτρα.
Στη συνέχεια, επαληθεύστε την κάλυψη. Κάθε επιλεγμένη περίπτωση χρήσης πρέπει να έχει μια πλήρη διαδρομή από το αίτημα στο αποτέλεσμα· οι εγγραφές πρέπει να περιλαμβάνουν εξουσιοδότηση και επιβεβαίωση· και το πρόσθετο πρέπει να γνωρίζει πώς να δηλώνει τι δεν κάνει, προσφέροντας ταυτόχρονα ένα χρήσιμο επόμενο βήμα. Ένα πρόσθετο που σας επιτρέπει να δημιουργείτε έργα αλλά όχι να τααπαριθμείτε, να τα προβάλλετε ή να τα επεξεργάζεστε, υπόσχεται περισσότερα από όσα προσφέρει: είτε ολοκληρώστε το είτε περιορίστε τον προσανατολισμό του.
Αποκλείστε και τεκμηριώστε το
Δεν χρειάζεται να υλοποιήσετε τα πάντα, αλλά κάθε μεγάλος αποκλεισμός αξίζει έναν λόγο: μη αποδεκτός κίνδυνος ασφαλείας ή απορρήτου, ένα API που δεν μπορεί να το υποστηρίξει αξιόπιστα, μη επαληθεύσιμες άδειες, παραπλανητικά αποτελέσματα λόγω ελλειπουσών πληροφοριών, ή ένα εύρος πρώτης έκδοσης που δηλώνεται σαφώς στη λίστα του πρόσθετου. Καταγράψτε αυτές τις αποφάσεις: ενημερώνουν τα όρια των δεξιοτήτων, τις περιγραφές των εργαλείων, τις αρνήσεις, τις δοκιμές και το κείμενο της δημόσιας λίστας.
Από τις περιπτώσεις χρήσης στα εργαλεία
Ένα εργαλείο πρέπει να εξυπηρετεί έναν στόχο χρήστη. Μην αντιγράφετε απλώς το εσωτερικό σας API ως έχει. Για κάθε επιλεγμένη περίπτωση χρήσης, γράψτε το αναμενόμενο αποτέλεσμα, καταγράψτε τις απαιτούμενες πληροφορίες, εντοπίστε αναγνώσεις, εγγραφές και εξωτερικές ενέργειες, ομαδοποιήστε ό,τι σχηματίζει μια συνεκτική ενέργεια—και διαχωρίστε ό,τι διαφέρει ως προς τις άδειες, τον κίνδυνο ή την ανάγκη επιβεβαίωσης.
Παράδειγμα της OpenAI για ένα πρόσθετο έργων:
list_projectsγια την εύρεση έργων·get_projectγια την εξέταση ενός·create_projectγια τη δημιουργία ενός·update_projectγια την τροποποίηση λεπτομερειών·archive_projectγια μια αλλαγή κατάστασης υψηλών συνεπειών.
Οι αναγνώσεις και οι εγγραφές διαχωρίζονται ώστε το μοντέλο και ο χρήστης να μπορούν να διακρίνουν τη διαβούλευση από την τροποποίηση.
Η σύμβαση κάθε εργαλείου
| Πεδίο | Ορισμός |
|---|---|
| Όνομα | Ένας σταθερός, προσανατολισμένος στη δράση αναγνωριστικός κωδικός |
| Τίτλος | Μια συνοπτική, ευανάγνωστη από τον άνθρωπο δράση |
| Περιγραφή | Ο στόχος του χρήστη και οι συνθήκες που πρέπει να ενεργοποιήσουν το εργαλείο |
| Σχήμα εισόδου | Απαραίτητες και προαιρετικές παράμετροι, τύποι, επιτρεπόμενες τιμές, όρια |
| Σχήμα εξόδου | Δομημένα πεδία που το μοντέλο μπορεί να επιθεωρήσει και να επαναχρησιμοποιήσει |
| Εξουσιοδότηση | Ο λογαριασμός, ο ρόλος ή η πρόσβαση που πρέπει να επαληθεύσει ο διακομιστής |
| Παρενέργειες | Δεδομένα ή εξωτερική κατάσταση που το εργαλείο ενδέχεται να τροποποιήσει |
| Αποτυχίες | Σφάλματα που το μοντέλο μπορεί να εξηγήσει ή από τα οποία μπορεί να ανακάμψει |
Τρεις κανόνες ολοκληρώνουν αυτόν τον πίνακα. Ρητές είσοδοι: μην βασίζεστε στο μοντέλο για να μαντέψει ένα ID ή το εύρος ενός λογαριασμού. Επαναχρησιμοποιήσιμες έξοδοι: επιστρέψτε σταθερά IDs και αρκετές πληροφορίες για την επόμενη κλήση. Καθαρές έξοδοι: χωρίς μυστικά, διακριτικά πρόσβασης, εσωτερικά διαγνωστικά ή περιττά προσωπικά δεδομένα.
Περιγραφές γραμμένες για να επιλέγονται
Το μοντέλο επιλέγει εργαλεία με βάση την περιγραφή τους: περιγράψτε την πρόθεση του χρήστη, όχι την υλοποίηση. Μια καλή περιγραφή λέει τι κάνει το εργαλείο, πότε να το χρησιμοποιήσετε, πώς διαφέρει από τα γειτονικά του και ποια είναι τα όρια ή οι προϋποθέσεις του. Αποφύγετε εκείνες που επαναλαμβάνουν το όνομα του εργαλείου ή χρησιμοποιούν εσωτερική ορολογία που οι χρήστες σας δεν γνωρίζουν.
Σημειώσεις ασφαλείας
Κάθε εργαλείο φέρει σημειώσεις (annotations), οι οποίες ορίζονται με βάση την πραγματική του συμπεριφορά:
- Το
readOnlyHintείναιtrueμόνο εάν το εργαλείο δεν μπορεί να τροποποιήσει καμία κατάσταση· - Το
destructiveHintείναιtrueεάν το εργαλείο μπορεί να παράγει ένα μη αναστρέψιμο ή δύσκολο στην αναίρεση αποτέλεσμα· - Το
openWorldHintείναιtrueεάν το εργαλείο αποκτά πρόσβαση στο δημόσιο διαδίκτυο ή σε ανοιχτές εξωτερικές οντότητες, ακόμη και μόνο για ανάγνωση, όπως μια αναζήτηση στον ιστό. Ένας ιδιωτικός, περιορισμένος λογαριασμός ή χώρος εργασίας δεν είναι «ανοιχτός» απλώς και μόνο επειδή φιλοξενείται αλλού.
Οι σημειώσεις βοηθούν το ChatGPT και το Codex να επιλέξουν το κατάλληλο επίπεδο επιβεβαίωσης, αλλά δεν αντικαθιστούν την εξουσιοδότηση στην πλευρά του διακομιστή, την επικύρωση εισόδου ή την επιβεβαίωση για σημαντικές ενέργειες.
Ένα σχέδιο που λειτουργεί ως σχέδιο δοκιμών
Διατηρήστε την απογραφή και το σχέδιο εργαλείων: γίνονται η λίστα ελέγχου σας. Προσθέστε άμεσα, έμμεσα, οριακά και εκτός εύρους αιτήματα, και επαληθεύστε ότι το ολοκληρωμένο πρόσθετο συμπεριφέρεται όπως αναμένεται για το καθένα. Επίσης, αναζητήστε εργαλεία που δεν εξυπηρετούν καμία τεκμηριωμένη περίπτωση χρήσης, ελλείπουσες αναγνώσεις πριν από εγγραφές, και περιγραφές πολύ κοντά μεταξύ τους που θα μπορούσαν να μπερδέψουν το μοντέλο.
Βασικά σημεία
- Ξεκινήστε με το τι θα περιμένουν οι χρήστες και μετά συγκρίνετέ το με ό,τι μπορείτε να παρέχετε με ασφάλεια
- Μια απογραφή επτά ερωτήσεων ανά περίπτωση χρήσης, συμπεριλαμβανομένων των σκόπιμων αποκλεισμών
- Ένα εργαλείο ανά συνεκτική ενέργεια· διαχωρισμός αναγνώσεων και εγγραφών
- Μία σύμβαση ανά εργαλείο: όνομα, τίτλος, περιγραφή, σχήματα, εξουσιοδότηση, παρενέργειες, αποτυχίες
- Οι σημειώσεις (
readOnlyHint,destructiveHint,openWorldHint) ακολουθούν την πραγματική συμπεριφορά και δεν αντικαθιστούν την εξουσιοδότηση