Design: Cazuri de utilizare și instrumente
Pe această pagină
Lecție rescrisă la 3 noiembrie 2026 pe baza documentației OpenAI privind Cazurile de utilizare pentru plugin-uri de tip Brainstorm și Definirea instrumentelor. Lecția anterioară instala un pachet inexistent
@openai/apps-sdkși un manifestchatgpt-app.json; instalarea instrumentelor reale (SDK-urile MCP oficiale) are loc în Lecția 4. Surse: Cazurile de utilizare pentru plugin-uri de tip Brainstorm · Definirea instrumentelor.
Începeți cu așteptările, nu cu API-ul
Documentația OpenAI recomandă să începeți construirea unui plugin înainte de a scrie o singură linie de cod: prin enumerarea a ceea ce utilizatorii se așteaptă de la acesta. Numele plugin-ului, descrierea, abilitățile, instrumentele și produsul la care se atașează creează toate anumite așteptări; implementarea dumneavoastră trebuie să le îndeplinească sau să aveți un motiv deliberat pentru care nu o faceți.
Imaginați-vă cineva care v-a instalat plugin-ul fără să-i citească documentația. Ce îi va cere să facă? Pentru a afla acest lucru, inspirați-vă din sarcinile pe care utilizatorii dumneavoastră le îndeplinesc deja în produsul dvs., din tichetele de suport, interogările de căutare, cererile de funcționalități, vocabularul pe care îl folosesc și soluțiile temporare care îi obligă să copieze date de la un instrument la altul. Notați cererile directe care numesc plugin-ul și cererile indirecte care enunță doar obiectivul: un plugin de gestionare a proiectelor trebuie să gestioneze „Afișează panoul de lansare Acme“ la fel ca „Ce blochează lansarea?“.
Nu limitați acest inventar la ceea ce face deja API-ul dumneavoastră. Enumerați mai întâi așteptările, apoi comparați-le cu ceea ce puteți oferi în siguranță și fiabil.
Inventarul cazurilor de utilizare
Pentru fiecare caz de utilizare, OpenAI recomandă răspunsul la șapte întrebări:
| Câmp | Întrebare |
|---|---|
| Obiectiv | Ce încearcă persoana să realizeze? |
| Exemple de cereri | Cum ar formula acestea, direct sau indirect? |
| Rezultat așteptat | Ce ar face interacțiunea reușită? |
| Context necesar | Ce informații, acces la cont sau stare anterioară sunt necesare? |
| Capacitate | Este suficientă o abilitate sau este necesar un instrument MCP? |
| Limită de siguranță | Ar putea expune date, modifica starea, cheltui bani sau afecta o terță parte? |
| Decizie | Prima versiune, mai târziu sau excludere intenționată? |
Grupați cererile care partajează un obiectiv comun: „Listează sarcinile mele deschise“, „Ce am de făcut astăzi?“ și „Afișează lucrările întârziate“ aparțin probabil aceluiași caz de utilizare de revizuire a sarcinilor, dar cu filtre diferite.
Apoi, verificați acoperirea. Fiecare caz de utilizare selectat trebuie să aibă o cale completă de la cerere la rezultat; operațiile de scriere trebuie să includă autorizare și confirmare; iar plugin-ul trebuie să știe cum să spună ceea ce nu face, oferind în același timp un pas următor util. Un plugin care vă permite să creați proiecte, dar nu să le listați, vizualizați sau editați, promite mai mult decât livrează: fie îl finalizați, fie îi restrângeți poziționarea.
Excludeți și documentați
Nu trebuie să implementați totul, dar fiecare excludere majoră merită un motiv: risc inacceptabil de securitate sau confidențialitate, un API care nu o poate susține în mod fiabil, permisiuni neverificabile, rezultate înșelătoare din cauza lipsei de informații sau un domeniu de aplicare pentru prima versiune declarat clar în lista plugin-ului. Înregistrați aceste decizii: ele informează limitele abilităților, descrierile instrumentelor, refuzurile, testele și textul listării publice.
De la cazuri de utilizare la instrumente
Un instrument trebuie să servească unui obiectiv al utilizatorului. Nu copiați doar API-ul intern așa cum este. Pentru fiecare caz de utilizare selectat, scrieți rezultatul așteptat, listați informațiile necesare, identificați citirile, scrierile și acțiunile externe, grupați ceea ce formează o acțiune coerentă – și separați ceea ce diferă prin permisiuni, risc sau nevoia de confirmare.
Exemplul OpenAI pentru un plugin de proiecte:
list_projectspentru a găsi proiecte;get_projectpentru a examina unul;create_projectpentru a crea unul;update_projectpentru a modifica detalii;archive_projectpentru o schimbare de stare cu consecințe majore.
Citirile și scrierile sunt separate astfel încât modelul și utilizatorul să poată distinge consultarea de modificare.
Contractul fiecărui instrument
| Câmp | Definiție |
|---|---|
| Nume | Un identificator stabil, orientat spre acțiune |
| Titlu | O acțiune concisă, lizibilă pentru om |
| Descriere | Obiectivul utilizatorului și condițiile care ar trebui să declanșeze instrumentul |
| Schema de intrare | Parametri obligatorii și opționali, tipuri, valori permise, limite |
| Schema de ieșire | Câmpuri structurate pe care modelul le poate inspecta și reutiliza |
| Autorizare | Contul, rolul sau accesul pe care serverul trebuie să le verifice |
| Efecte secundare | Date sau stare externă pe care instrumentul le poate modifica |
| Eșecuri | Erori pe care modelul le poate explica sau din care se poate recupera |
Trei reguli completează acest tabel. Intrări explicite: nu vă bazați pe model pentru a ghici un ID sau un domeniu de cont. Ieșiri reutilizabile: returnați ID-uri stabile și suficiente informații pentru următorul apel. Ieșiri curate: fără secrete, token-uri de acces, diagnostice interne sau date personale inutile.
Descrieri scrise pentru a fi alese
Modelul selectează instrumentele pe baza descrierii lor: descrieți intenția utilizatorului, nu implementarea. O descriere bună spune ce face instrumentul, când să îl utilizați, cum diferă de cele vecine și care sunt limitele sau prerechizitele sale. Evitați descrierile care repetă numele instrumentului sau folosesc jargon intern pe care utilizatorii dumneavoastră nu îl cunosc.
Anotări de siguranță
Fiecare instrument poartă anotări, stabilite pe baza comportamentului său real:
readOnlyHintestetruedoar dacă instrumentul nu poate modifica nicio stare;destructiveHintestetruedacă instrumentul poate produce un rezultat ireversibil sau greu de anulat;openWorldHintestetruedacă instrumentul accesează internetul public sau entități externe deschise, chiar și doar în citire, cum ar fi o căutare pe web. Un cont sau spațiu de lucru privat și delimitat nu este „deschis“ doar pentru că este găzduit în altă parte.
Anotările ajută ChatGPT și Codex să aleagă nivelul corect de confirmare, dar nu înlocuiesc autorizarea lato sensu, validarea intrărilor sau confirmarea pentru acțiuni importante.
Un plan care servește drept plan de testare
Păstrați inventarul și planul instrumentelor: acestea devin lista dumneavoastră de verificare. Adăugați cereri directe, indirecte, la limită și în afara domeniului de aplicare și verificați dacă plugin-ul finalizat se comportă așa cum este de așteptat pentru fiecare. Căutați, de asemenea, instrumente care nu deservesc niciun caz de utilizare documentat, citiri lipsă înainte de scrieri și descrieri prea apropiate care ar putea confunda modelul.
Puncte cheie
- Începeți cu ceea ce se așteaptă utilizatorii, apoi comparați cu ceea ce puteți oferi în siguranță
- Un inventar de șapte întrebări per caz de utilizare, inclusiv excluderile intenționate
- Un instrument per acțiune coerentă; citirile și scrierile sunt separate
- Un contract per instrument: nume, titlu, descriere, scheme, autorizare, efecte secundare, eșecuri
- Anotările (
readOnlyHint,destructiveHint,openWorldHint) urmează comportamentul real și nu înlocuiesc autorizarea