Načrtovanje: primeri uporabe in orodja
Na tej strani
Lekcija je bila ponovno napisana 3. novembra 2026 na podlagi dokumentacije OpenAI o primerih uporabe vtičnikov za nevihto možganov (Brainstorm) in definiranju orodij. Prejšnja lekcija je nameščala neobstoječ paket
@openai/apps-sdkin manifestchatgpt-app.json; namestitev dejanskih orodij (uradni SDK-ji MCP) poteka v 4. lekciji. Viri: Primeri uporabe vtičnikov za nevihto možganov · Definiranje orodij.
Začni s pričakovanji, ne z API-jem
Dokumentacija OpenAI svetuje, da začneš graditi vtičnik, preden napišeš prvo vrstico kode: tako, da našteješ, kaj bodo ljudje od njega pričakovali. Ime vtičnika, opis, veščine, orodja in izdelek, na katerega se navezuje, vsi ustvarjajo pričakovanja; tvoja implementacija jih mora izpolniti ali pa imeti nameren razlog, zakaj jih ne.
Predstavljaj si nekoga, ki je namestil tvoj vtičnik, ne da bi prebral dokumentacijo. Kaj ga bo prosil? Da to ugotoviš, črpaj iz nalog, ki jih tvoji uporabniki že opravljajo v tvojem izdelku, iz zahtevkov za podporo, iskalnih poizvedb, predlogov za funkcije, besedišča, ki ga uporabljajo, in začasnih rešitev, ki jih silijo k kopiranju podatkov iz enega orodja v drugo. Zabeleži neposredne zahteve, ki imenujejo vtičnik, in posredne zahteve, ki navajajo le cilj: vtičnik za upravljanje projektov mora enako obravnavati „Prikaži nadzorno ploščo za zagon Acme” kot „Kaj zavira zagon?”.
Tega popisa ne omeji le na tisto, kar tvoj API že počne. Najprej naštej pričakovanja, nato pa jih primerjaj s tem, kar lahko zagotoviš varno in zanesljivo.
Inventar primerov uporabe
Za vsak primer uporabe OpenAI priporoča odgovor na sedem vprašanj:
| Polje | Vprašanje |
|---|---|
| Cilj | Kaj oseba poskuša doseči? |
| Primeri zahtevkov | Kako bi to formulirali, neposredno ali posredno? |
| Pričakovani izid | Kaj bi naredilo interakcijo uspešno? |
| Zahtevan kontekst | Katere informacije, dostop do računa ali predhodno stanje so potrebni? |
| Zmožnost | Ali je dovolj veščina ali je potrebno orodje MCP? |
| Varnostna meja | Ali bi lahko razkrilo podatke, spremenilo stanje, porabilo denar ali vplivalo na tretjo stran? |
| Odločitev | Prva različica, kasneje ali namerna izključitev? |
Združi zahteve, ki si delijo cilj: „Naštej moje odprte naloge”, „Kaj moram danes narediti?” in „Prikaži zapoznela dela” verjetno spadajo k istemu primeru uporabe pregleda nalog, le z različnimi filtri.
Nato preveri pokritost. Vsak izbran primer uporabe mora imeti popolno pot od zahteve do rezultata; pisanje mora vključevati avtorizacijo in potrditev; vtičnik pa mora vedeti, kako povedati, česa ne počne, hkrati pa ponuditi uporaben naslednji korak. Vtičnik, ki ti omogoča ustvarjanje projektov, ne pa tudi njihovega naštevanja, ogleda ali urejanja, obljublja več, kot lahko izpolni: ali ga dokončaj ali pa zoži njegovo pozicioniranje.
Izključi in to dokumentiraj
Vsega ni treba implementirati, vendar si vsaka večja izključitev zasluži razlog: nesprejemljivo tveganje za varnost ali zasebnost, API, ki tega ne more zanesljivo podpreti, preverljiva dovoljenja, zavajajoči rezultati zaradi manjkajočih informacij ali obseg prve različice, ki je jasno naveden v seznamu vtičnikov. Zabeleži te odločitve: informirajo omejitve veščin, opise orodij, zavrnitve, teste in besedilo javnega seznama.
Od primerov uporabe do orodij
Orodje mora služiti uporabnikovemu cilju. Ne kopiraj svojega notranjega API-ja takšnega, kot je. Za vsak izbran primer uporabe zapiši pričakovani izid, naštej potrebne informacije, identificiraj branja, pisanja in zunanja dejanja, združi tisto, kar tvori koherentno dejanje – in loči tisto, kar se razlikuje glede na dovoljenja, tveganje ali potrebo po potrditvi.
Primer OpenAI za vtičnik projekte:
list_projectsza iskanje projektov;get_projectza pregled enega;create_projectza ustvarjanje enega;update_projectza spreminjanje podrobnosti;archive_projectza spremembo stanja z visokimi posledicami.
Branja in pisanja so ločena, da lahko model in uporabnik razlikujeta med posvetovanjem in spreminjanjem.
Pogodba vsakega orodja
| Polje | Definiraj |
|---|---|
| Ime | Stabilen identifikator, usmerjen v dejanje |
| Naslov | Jedrnat, človeku berljiv opis dejanja |
| Opis | Uporabnikov cilj in pogoji, ki naj sprožijo orodje |
| Shema vnosa | Zahtevani in izbirni parametri, tipi, dovoljene vrednosti, omejitve |
| Shema izhoda | Strukturirana polja, ki jih model lahko pregleda in ponovno uporabi |
| Avtorizacija | Račun, vloga ali dostop, ki ga mora strežnik preveriti |
| Stranski učinki | Podatki ali zunanje stanje, ki ga orodje lahko spremeni |
| Napake | Napake, ki jih model lahko razloži ali odpravi |
Tri pravila dopolnjujejo to tabelo. Eksplicitni vnosi: ne zanašaj se na model, da bi ugibal ID ali obseg računa. Ponovno uporabni izhodi: vrni stabilne ID-je in dovolj informacij za naslednji klic. Čisti izhodi: brez skrivnosti, žetonov za dostop, notranje diagnostike ali nepotrebnih osebnih podatkov.
Opisi, napisani tako, da jih izberejo
Model izbere orodja na podlagi njihovega opisa: opiši uporabnikov namen, ne implementacije. Dober opis pove, kaj orodje počne, kdaj ga uporabiti, kako se razlikuje od sosednjih in kakšne so njegove omejitve ali predpogoji. Izogibaj se tistim, ki ponavljajo ime orodja ali uporabljajo notranji žargon, ki ga tvoji uporabniki ne poznajo.
Varnostne opombe
Vsako orodje nosi opombe, nastavljene glede na njegovo dejansko obnašanje:
readOnlyHintjetruele, če orodje ne more spremeniti nobenega stanja;destructiveHintjetrue, če lahko orodje povzroči nepovraten ali težko razveljavljiv rezultat;openWorldHintjetrue, če orodje dostopa do javnega interneta ali odprtih zunanjih entitet, celo samo za branje, kot je spletno iskanje. Zasebni, omejeni račun ali delovni prostor ni „odprt” samo zato, ker je gostovan drugje.
Opombe pomagajo ChatGPT in Codex izbrati ustrezno raven potrditve, vendar ne nadomeščajo avtorizacije na strani strežnika, validacije vnosa ali potrditve za pomembna dejanja.
Načrt, ki služi kot načrt testiranja
Obdrži inventar in načrt orodij: postaneta tvoj kontrolni seznam. Dodaj neposredne, posredne, robne in izven-obsega zahteve ter preveri, ali se končani vtičnik obnaša pričakovano za vsako od njih. Poišči tudi orodja, ki ne služijo nobenemu dokumentiranemu primeru uporabe, manjkajoča branja pred pisanji in opise, ki so si preveč podobni in bi lahko zmedli model.
Ključne ugotovitve
- Začni s tem, kaj bodo uporabniki pričakovali, nato primerjaj s tem, kar lahko zagotoviš varno
- Inventar sedmih vprašanj na primer uporabe, vključno z namernimi izključitvami
- Eno orodje na koherentno dejanje; branja in pisanja ločena
- Ena pogodba na orodje: ime, naslov, opis, sheme, avtorizacija, stranski učinki, napake
- Opombe (
readOnlyHint,destructiveHint,openWorldHint) sledijo dejanskemu obnašanju in ne nadomeščajo avtorizacije