Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Návrh: Prípady použitia a nástroje

Lekcia 3 z 14 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Začni očakávaniami, nie API
  2. Inventár prípadov použitia
  3. Vylúčenie a jeho zdokumentovanie
  4. Od prípadov použitia k nástrojom
  5. Zmluva každého nástroja
  6. Popisy písané tak, aby boli vybrané
  7. Anotácie bezpečnosti
  8. Plán, ktorý slúži ako testovací plán
  9. Kľúčové poznatky

Lekcia prepísaná 3. novembra 2026 na základe dokumentácie OpenAI o prípadoch použitia pluginu Brainstorm a definícii nástrojov. Predchádzajúca lekcia inštalovala neexistujúci balík @openai/apps-sdk a manifest chatgpt-app.json; inštalácia skutočných nástrojov (oficiálne MCP SDK) prebieha v lekcii 4. Zdroje: Prípady použitia pluginu Brainstorm · Definícia nástrojov.

Začni očakávaniami, nie API

Dokumentácia OpenAI hovorí, aby si začal stavať plugin ešte pred napísaním jediného riadku kódu: zostavením zoznamu toho, čo od neho ľudia budú očakávať. Názov pluginu, popis, zručnosti, nástroje a produkt, ku ktorému sa pripája, vytvárajú očakávania; tvoja implementácia ich musí splniť, alebo mať úmyselný dôvod, prečo nie.

Predstav si niekoho, kto si nainštaloval tvoj plugin bez prečítania dokumentácie. O čo ho požiada? Aby si to zistil, čerpaj z úloh, ktoré tvoji používatelia už vo svojom produkte vykonávajú, z ticketov podpory, vyhľadávacích dopytov, žiadostí o funkcie, slovnej zásoby, ktorú používajú, a obchádzaní problémov, ktoré ich nútia kopírovať údaje z jedného nástroja do druhého. Všimni si priame žiadosti, ktoré menujú plugin, aj nepriame žiadosti, ktoré uvádzajú iba cieľ: plugin na riadenie projektov musí spracovať „Zobraziť spúšťaciu tabuľu Acme“ rovnako ako „Čo brzdí spustenie?“.

Neobmedzuj tento inventár len na to, čo tvoje API už robí. Najprv vypíš očakávania a potom ich porovnaj s tým, čo môžeš poskytnúť bezpečne a spoľahlivo.

Inventár prípadov použitia

Pre každý prípad použitia OpenAI odporúča odpovedať na sedem otázok:

PoleOtázka
CieľČo sa osoba snaží dosiahnuť?
Príkladové žiadostiAko by to sformulovali, priamo alebo nepriamo?
Očakávaný výsledokČo by urobilo interakciu úspešnou?
Potrebný kontextAké informácie, prístup k účtu alebo predchádzajúci stav sú potrebné?
SchopnosťStačí zručnosť, alebo je potrebný nástroj MCP?
Hranica bezpečnostiMohlo by to odhaliť údaje, zmeniť stav, minúť peniaze alebo ovplyvniť tretiu stranu?
RozhodnutiePrvá verzia, neskoršia verzia alebo úmyselné vylúčenie?

Zoskup žiadosti, ktoré zdieľajú cieľ: „Vypíš moje otvorené úlohy“, „Čo musím dnes urobiť?“ a „Ukáž oneskorenú prácu“ pravdepodobne patria do rovnakého prípadu použitia revízie úloh, len s rôznymi filtrami.

Potom over pokrytie. Každý vybraný prípad použitia musí mať úplnú cestu od žiadosti po výsledok; zápisy musia zahŕňať autorizáciu a potvrdenie; a plugin musí vedieť povedať, čo nerobí, pričom ponúkne užitočný ďalší krok. Plugin, ktorý ti umožňuje vytvárať projekty, ale nie ich vypisovať, zobrazovať alebo upravovať, sľubuje viac, než dodáva: buď ho dokonči, alebo zúž jeho pozíciu na trhu.

Vylúčenie a jeho zdokumentovanie

Nemusíš implementovať všetko, ale každé veľké vylúčenie si vyžaduje dôvod: neprijateľné riziko bezpečnosti alebo súkromia, API, ktoré to nedokáže spoľahlivo podporiť, neoveriteľné povolenia, zavádzajúce výsledky kvôli chýbajúcim informáciám alebo rozsah prvej verzie jasne uvedený v zozname pluginov. Zaznamenaj tieto rozhodnutia: informujú o limitoch zručností, popisoch nástrojov, odmietnutiach, testoch a texte verejného zoznamu.

Od prípadov použitia k nástrojom

Nástroj musí slúžiť cieľu používateľa. Nekopíruj svoje interné API tak, ako je. Pre každý vybraný prípad použitia napíš očakávaný výsledok, vypíš potrebné informácie, identifikuj čítania, zápisy a externé akcie, zoskup to, čo tvorí súdržnú akciu – a oddel to, čo sa líši podľa povolení, rizika alebo potreby potvrdenia.

Príklad OpenAI pre plugin na projekty:

  • list_projects na nájdenie projektov;
  • get_project na preskúmanie jedného projektu;
  • create_project na vytvorenie projektu;
  • update_project na úpravu detailov;
  • archive_project pre zmenu stavu s vysokými dôsledkami.

Čítania a zápisy sú oddelené, aby model a používateľ mohli rozlíšiť konzultáciu od úpravy.

Zmluva každého nástroja

PoleDefinícia
NázovStabilný identifikátor orientovaný na akciu
TitulokStručná, čitateľná akcia pre človeka
PopisCieľ používateľa a podmienky, ktoré by mali spustiť nástroj
Schéma vstupuPovinné a voliteľné parametre, typy, povolené hodnoty, limity
Schéma výstupuŠtruktúrované polia, ktoré môže model skontrolovať a znovu použiť
AutorizáciaÚčet, rola alebo prístup, ktorý musí server overiť
Vedľajšie účinkyÚdaje alebo externý stav, ktorý môže nástroj zmeniť
ZlyhaniaChyby, ktoré môže model vysvetliť alebo z ktorých sa môže zotaviť

Túto tabuľku dopĺňajú tri pravidlá. Explicitné vstupy: nespoliehaj sa na to, že model uhádne ID alebo rozsah účtu. Opätovne použiteľné výstupy: vráť stabilné ID a dostatok informácií pre ďalšie volanie. Čisté výstupy: žiadne tajomstvá, prístupové tokeny, interná diagnostika ani zbytočné osobné údaje.

Popisy písané tak, aby boli vybrané

Model vyberá nástroje na základe ich popisu: opíš zámer používateľa, nie implementáciu. Dobrý popis hovorí, čo nástroj robí, kedy ho použiť, ako sa líši od svojich susedov a aké sú jeho limity alebo predpoklady. Vyhnite sa tým, ktoré opakujú názov nástroja alebo používajú interný žargón, ktorý tvoji používatelia nepoznajú.

Anotácie bezpečnosti

Každý nástroj nesie anotácie nastavené na základe jeho skutočného správania:

  • readOnlyHint je true iba vtedy, ak nástroj nemôže zmeniť žiadny stav;
  • destructiveHint je true, ak môže nástroj spôsobiť nezvratný alebo ťažko vratný výsledok;
  • openWorldHint je true, ak nástroj pristupuje k verejnému internetu alebo otvoreným externým entitám, dokonca aj pri čítaní, ako je webové vyhľadávanie. Súkromný, ohraničený účet alebo pracovný priestor nie je „otvorený“ len preto, že je hostený inde.

Anotácie pomáhajú ChatGPT a Codex vybrať správnu úroveň potvrdenia, ale nenahrádzajú autorizáciu na strane servera, validáciu vstupu ani potvrdenie pre dôležité akcie.

Plán, ktorý slúži ako testovací plán

Udržuj inventár a plán nástrojov: stanú sa tvojím kontrolným zoznamom. Pridaj priame, nepriame, hraničné a mimo-rozsahové žiadosti a over, či sa dokončený plugin správa podľa očakávaní pre každú z nich. Hľadaj aj nástroje, ktoré neslúžia žiadnemu zdokumentovanému prípadu použitia, chýbajúce čítania pred zápismi a popisy, ktoré sú príliš podobné a mohli by model zmiasť.

Kľúčové poznatky

  • Začni tým, čo používatelia očakávajú, a potom to porovnaj s tým, čo môžeš bezpečne poskytnúť
  • Sedemotázkový inventár pre každý prípad použitia vrátane úmyselných vylúčení
  • Jeden nástroj na jednu súdržnú akciu; čítania a zápisy oddelené
  • Jedna zmluva na nástroj: názov, titulok, popis, schémy, autorizácia, vedľajšie účinky, zlyhania
  • Anotácie (readOnlyHint, destructiveHint, openWorldHint) nasledujú skutočné správanie a nenahrádzajú autorizáciu