Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Dizainas: naudojimo atvejai ir įrankiai

Paskaita 3 iš 14 Atnaujinta 2026 m. lapkričio 3 d. Kūrėjas
Šiame puslapyje
  1. Pradėk nuo lūkesčių, o ne nuo API
  2. Naudojimo atvejų inventorizacija
  3. Neįtrauk ir tai dokumentuok
  4. Nuo naudojimo atvejų prie įrankių
  5. Kiekvieno įrankio sutartis
  6. Aprašymai, rašomi tam, kad būtų pasirinkti
  7. Saugumo anotacijos
  8. Planas, kuris tampa testų planu
  9. Svarbiausi punktai

Pamoka perrašyta 2026 m. lapkričio 3 d. remiantis OpenAI dokumentacijos puslapiais Brainstorm plugin use cases ir Define tools. Ankstesnėje pamokoje buvo diegiamas neegzistuojantis @openai/apps-sdk paketas ir chatgpt-app.json manifestas; tikrųjų įrankių (oficialių MCP SDK) diegimas vyksta 4 pamokoje. Šaltiniai: Brainstorm plugin use cases · Define tools.

Pradėk nuo lūkesčių, o ne nuo API

OpenAI dokumentacija rekomenduoja pradėti kurti įskiepį dar prieš parašant vieną kodo eilutę: sudaryk sąrašą to, ko žmonės iš jo tikėsis. Įskiepio pavadinimas, aprašymas, įgūdžiai, įrankiai ir produktas, prie kurio jis jungiamas, formuoja lūkesčius; tavo implementacija turi juos pateisinti arba turėti pagrįstą priežastį, kodėl taip nėra.

Įsivaizduok žmogų, kuris įdiegė tavo įskiepį neperskaitęs dokumentacijos. Ko jis jo prašys? Norėdamas tai išsiaiškinti, remkis užduotimis, kurias naudotojai jau atlieka tavo produkte, palaikymo bilietais, paieškos užklausomis, funkcijų pageidavimais, jų vartojama terminija bei apylankiais būdais, verčiančiais kopijuoti duomenis iš vieno įrankio į kitą. Fiksuok tiek tiesioginius prašymus, kuriuose minimas įskiepis, tiek netiesioginius, nurodančius tik tikslą: projektų valdymo įskiepis turi vienodai gerai apdoroti „Rodyk Acme paleidimo lentą“ ir „Kas stabdo paleidimą?“.

Neapsiribok tuo, ką tavo API jau gali daryti. Pirmiausia surašyk lūkesčius, o tada palygink juos su tuo, ką gali suteikti saugiai ir patikimai.

Naudojimo atvejų inventorizacija

Kiekvienam naudojimui atvejui OpenAI rekomenduoja atsakyti į septynis klausimus:

LaukasKlausimas
TikslasKo asmuo siekia pasiekti?
Pavyzdinės užklausosKaip jis tai suformuluotų, tiesiogiai ar netiesiogiai?
Laukiamas rezultatasKas padarytų sąveiką sėkminga?
Reikalingas kontekstasKokios informacijos, paskyros prieigos ar ankstesnės būsenos reikia?
GalimybėAr pakanka įgūdžio, ar būtinas MCP įrankis?
Saugumo ribosAr tai gali atskleisti duomenis, pakeisti būseną, išleisti pinigų ar paveikti trečiąją šalį?
SprendimasPirmoji versija, vėlesnis etapas ar tyčinis neįtraukimas?

Sugrupuok prašymus, turinčius tą patį tikslą: „Išvardink mano atviras užduotis“, „Ką turiu nuveikti šiandien?“ ir „Rodyk vėluojančius darbus“ greičiausiai priklauso tam pačiam užduočių peržiūros naudojimui atvejui, tik su skirtingais filtrais.

Tada patikrink aprėptį. Kiekvienas pasirinktas naudojimo atvejis turi turėti pilną kelią nuo užklausos iki rezultato; rašymo operacijos turi apimti autorizaciją ir patvirtinimą; o įskiepis turi mokėti paaiškinti, ko jis nedaro, kartu pasiūlydamas naudingą kitą žingsnį. Įskiepis, leidžiantis kurti projektus, bet neleidžiantis jų išvardinti, peržiūrėti ar redaguoti, žada daugiau, nei gali įvykdyti: arba užbaik jį, arba susiaurink jo pozicionavimą.

Neįtrauk ir tai dokumentuok

Nebūtina implementuoti visko, tačiau kiekviena didelė išimtis turi turėti priežastį: nepriimtina saugumo ar privatumo rizika, API, negalintis to patikimai palaikyti, nepatikrinami leidimai, klaidinantys rezultatas dėl trūkstamos informacijos arba aiškiai įskiepio sąraše nurodyta pirmosios versijos apimtis. Įrašyk šiuos sprendimus: jie informuoja apie įgūdžių ribas, įrankių aprašymus, atsisakymus, testus ir viešąjį sąrašo tekstą.

Nuo naudojimo atvejų prie įrankių

Įrankis turi tarnauti naudotojo tikslui. Tiesiog nekopyjuok savo vidinio API tokio, koks jis yra. Kiekvienam pasirinktam naudojimui atvejui aprašyk laukiamą rezultatą, išvardink reikalingą informaciją, identifikuok skaitymo, rašymo ir išorinius veiksmus, sugrupuok tai, kas sudaro darnų veiksmą, ir atskirk tai, kas skiriasi leidimais, rizika ar patvirtinimo poreikiu.

OpenAI pavyzdys projektų įskiepiui:

  • list_projects projektams rasti;
  • get_project vienam projektui išnagrinėti;
  • create_project projektui sukurti;
  • update_project detalėms modifikuoti;
  • archive_project didelės įtakos būsenos pakeitimui.

Skaitymo ir rašymo operacijos atskirtos, kad modelis ir naudotojas galėtų atskirti konsultaciją nuo modifikavimo.

Kiekvieno įrankio sutartis

LaukasApibrėžimas
PavadinimasStabilus, veiksmu orientuotas identifikatorius
AntraštėGlaustas, žmonėms suprantamas veiksmas
AprašymasNaudotojo tikslas ir sąlygos, kurios turėtų suaktyvinti įrankį
Įvesties schemaPrivalomi ir neprivalomi parametrai, tipai, leistinos reikšmės, ribos
Išvesties schemaStruktūrizuoti laukai, kuriuos modelis gali tikrinti ir pakartotinai naudoti
AutorizacijaPaskyra, vaidmuo arba prieiga, kurią serveris turi patikrinti
Šalutiniai poveikiaiDuomenys arba išorinė būsena, kurią įrankis gali pakeisti
GedimaiKlaidos, kurias modelis gali paaiškinti arba ištaisyti

Šią lentelę papildo trys taisyklės. Aiški įvestis: nesikliauk, kad modelis atspės ID arba paskyros apimtį. Pakartotinai naudojama išvestis: grąžink stabilius ID ir pakankamai informacijos kitam kvietimui. Švari išvestis: jokių paslapčių, prieigos raktų, vidinės diagnostikos ar nereikalingų asmens duomenų.

Aprašymai, rašomi tam, kad būtų pasirinkti

Modelis pasirenka įrankius pagal jų aprašymą: aprašyk naudotojo ketinimą, o ne implementaciją. Geras aprašymas nurodo, ką įrankis daro, kada jį naudoti, kuo jis skiriasi nuo kaimyninių įrankių ir kokios jo ribos ar priešsąlygos. Venk tų, kurie kartojasi su įrankio pavadinimu arba naudoja vidinį žargoną, kurio tavo naudotojai nežino.

Saugumo anotacijos

Kiekvienas įrankis turi anotacijas, nustatomas pagal jo faktinį elgesį:

  • readOnlyHint yra true tik tada, kai įrankis negali modifikuoti jokios būsenos;
  • destructiveHint yra true, jei įrankis gali sukelti negrįžtamą arba sunkiai atšaukiamą rezultatą;
  • openWorldHint yra true, jei įrankis pasiekia viešąjį internetą arba atvirus išorinius subjektus, net jei tai tik skaitymas, kaip interneto paieška. privati, apribota paskyra ar darbo sritis nėra „atvira“ vien todėl, kad talpinama kitur.

Anotacijos padeda ChatGPT ir Codex pasirinkti tinkamą patvirtinimo lygį, tačiau jos nepakeičia serverio pusės autorizacijos, įvesties validavimo ar patvirtinimo svarbiems veiksmams.

Planas, kuris tampa testų planu

Išlaikyk inventorizaciją ir įrankių planą: jie tampa tavo kontroliniu sąrašu. Pridėk tiesioginių, netiesioginių, ribinių ir už apimties esančių užklausų bei patikrink, ar baigtas įskiepis elgiasi taip, kaip tikėtasi kiekvienu atveju. Taip pat ieškok įrankių, kurie netarnauja jokiems dokumentuotiems naudojimo atvejams, trūkstamų skaitymo operacijų prieš rašymą ir per daug panašių aprašymų, kurie gali suklaidinti modelį.

Svarbiausi punktai

  • Pradėk nuo to, ko naudotojai tikėsis, tada palygink su tuo, ką gali suteikti saugiai
  • Septynių klausimų inventorizacija kiekvienam naudojimui atvejui, įskaitant tyčinius neįtraukimus
  • Vienas įrankis vienam darniam veiksmui; skaitymas ir rašymas atskirti
  • Viena sutartis vienam įrankiui: pavadinimas, antraštė, aprašymas, schemos, autorizacija, šalutiniai poveikiai, gedimai
  • Anotacijos (readOnlyHint, destructiveHint, openWorldHint) atitinka faktinį elgesį ir nepakeičia autorizacijos