Dizainas: naudojimo atvejai ir įrankiai
Šiame puslapyje
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-sdkpaketas irchatgpt-app.jsonmanifestas; 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:
| Laukas | Klausimas |
|---|---|
| Tikslas | Ko asmuo siekia pasiekti? |
| Pavyzdinės užklausos | Kaip jis tai suformuluotų, tiesiogiai ar netiesiogiai? |
| Laukiamas rezultatas | Kas padarytų sąveiką sėkminga? |
| Reikalingas kontekstas | Kokios informacijos, paskyros prieigos ar ankstesnės būsenos reikia? |
| Galimybė | Ar pakanka įgūdžio, ar būtinas MCP įrankis? |
| Saugumo ribos | Ar tai gali atskleisti duomenis, pakeisti būseną, išleisti pinigų ar paveikti trečiąją šalį? |
| Sprendimas | Pirmoji 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_projectsprojektams rasti;get_projectvienam projektui išnagrinėti;create_projectprojektui sukurti;update_projectdetalėms modifikuoti;archive_projectdidelės įtakos būsenos pakeitimui.
Skaitymo ir rašymo operacijos atskirtos, kad modelis ir naudotojas galėtų atskirti konsultaciją nuo modifikavimo.
Kiekvieno įrankio sutartis
| Laukas | Apibrėžimas |
|---|---|
| Pavadinimas | Stabilus, veiksmu orientuotas identifikatorius |
| Antraštė | Glaustas, žmonėms suprantamas veiksmas |
| Aprašymas | Naudotojo tikslas ir sąlygos, kurios turėtų suaktyvinti įrankį |
| Įvesties schema | Privalomi ir neprivalomi parametrai, tipai, leistinos reikšmės, ribos |
| Išvesties schema | Struktūrizuoti laukai, kuriuos modelis gali tikrinti ir pakartotinai naudoti |
| Autorizacija | Paskyra, vaidmuo arba prieiga, kurią serveris turi patikrinti |
| Šalutiniai poveikiai | Duomenys arba išorinė būsena, kurią įrankis gali pakeisti |
| Gedimai | Klaidos, 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į:
readOnlyHintyratruetik tada, kai įrankis negali modifikuoti jokios būsenos;destructiveHintyratrue, jei įrankis gali sukelti negrįžtamą arba sunkiai atšaukiamą rezultatą;openWorldHintyratrue, 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