Salt la conținutul principal
Română— Alege o limbă
Meniu

Design: Cazuri de utilizare și instrumente

Lecția 3 din 14 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Începeți cu așteptările, nu cu API-ul
  2. Inventarul cazurilor de utilizare
  3. Excludeți și documentați
  4. De la cazuri de utilizare la instrumente
  5. Contractul fiecărui instrument
  6. Descrieri scrise pentru a fi alese
  7. Anotări de siguranță
  8. Un plan care servește drept plan de testare
  9. Puncte cheie

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 manifest chatgpt-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
ObiectivCe încearcă persoana să realizeze?
Exemple de cereriCum ar formula acestea, direct sau indirect?
Rezultat așteptatCe ar face interacțiunea reușită?
Context necesarCe informații, acces la cont sau stare anterioară sunt necesare?
CapacitateEste 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?
DeciziePrima 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_projects pentru a găsi proiecte;
  • get_project pentru a examina unul;
  • create_project pentru a crea unul;
  • update_project pentru a modifica detalii;
  • archive_project pentru 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âmpDefiniție
NumeUn identificator stabil, orientat spre acțiune
TitluO acțiune concisă, lizibilă pentru om
DescriereObiectivul utilizatorului și condițiile care ar trebui să declanșeze instrumentul
Schema de intrareParametri obligatorii și opționali, tipuri, valori permise, limite
Schema de ieșireCâmpuri structurate pe care modelul le poate inspecta și reutiliza
AutorizareContul, rolul sau accesul pe care serverul trebuie să le verifice
Efecte secundareDate sau stare externă pe care instrumentul le poate modifica
EșecuriErori 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:

  • readOnlyHint este true doar dacă instrumentul nu poate modifica nicio stare;
  • destructiveHint este true dacă instrumentul poate produce un rezultat ireversibil sau greu de anulat;
  • openWorldHint este true dacă 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