Disain: Kasutusjuhtumid ja tööriistad
Sellel lehel
Õppetund kirjutati ümber 3. novembril 2026, tuginedes OpenAI dokumentatsiooni lehtedele Brainstorm plugin use cases ja Define tools. Eelmine õppetund paigaldas olematut
@openai/apps-sdkpaketti jachatgpt-app.jsonmanifesti; tegelike tööriistade (ametlikud MCP SDK-d) paigaldus toimub 4. õppetunnis. Allikad: Brainstorm plugin use cases · Define tools.
Alusta ootustest, mitte API-st
OpenAI dokumentatsioon soovitab enne esimese koodirea kirjutamist koostada pistikprogrammi arendusplaan, loetledes, mida kasutajad sellelt ootavad. Pistikprogrammi nimi, kirjeldus, oskused, tööriistad ja toode, millega see seostub, loovad kõik kindlad ootused; sinu teostus peab need täitma või olema tahtlik põhjus, miks seda ei tehta.
Kujuta ette kedagi, kes on sinu pistikprogrammi installinud, lugemata selle dokumentatsiooni. Mida ta sellelt küsida võiks? Selle väljaselgitamiseks tugine ülesannetele, mida sinu kasutajad juba sinu tootes täidavad, tugipiletitele, otsingupäringutele, funktsioonisoovidele, nende kasutatavale sõnavarale ning ajutistele lahendustele, mis sunnivad neid andmeid ühest tööriistast teise kopeerima. Pane kirja nii otsesed päringud, mis nimetavad pistikprogrammi, kui ka kaudsed päringud, mis väljendavad vaid eesmärki: projektihalduse pistikprogramm peab käsitlema „Näita Acme’i käivitustahvlit“ sama moodi kui „Mis takistab käivitamist?“.
Ära piira seda nimekirja sellega, mida sinu API juba teeb. Loetle esmalt ootused ja võrdle seejärel neid sellega, mida saad turvaliselt ja usaldusväärselt pakkuda.
Kasutusjuhtumite inventuur
Iga kasutusjuhtumi kohta soovitab OpenAI vastata seitsmele küsimusele:
| Väli | Küsimus |
|---|---|
| Eesmärk | Mida inimene püüab saavutada? |
| Näidispäringud | Kuidas ta seda sõnastaks, otseselt või kaudselt? |
| Oodatav tulemus | Mis teeks suhtluse edukaks? |
| Vajalik kontekst | Millist teavet, konto juurdepääsu või eelnevat olekut on vaja? |
| Võimekus | Kas oskusest piisab või on vaja MCP tööriista? |
| Turvapiirang | Kas see võib paljastada andmeid, muuta olekut, kulutada raha või mõjutada kolmandat osapoolt? |
| Otsus | Esimene versioon, hilisem versioon või tahtlik väljajätmine? |
Grupeeri päringud, millel on sama eesmärk: „Loetle mu lahtised ülesanded“, „Mis mul täna teha on?“ ja „Näita просроченud töid“ kuuluvad tõenäoliselt samasse ülesannete ülevaatuse kasutusjuhtumisse, kuid erinevate filtritega.
Seejärel kontrolli katvust. Igal valitud kasutusjuhtumil peab olema täielik tee päringust tulemuseni; kirjutamistoimingud peavad sisaldama volitamist ja kinnitust; ning pistikprogramm peab oskama öelda, mida ta ei tee, pakkudes samas kasulikku järgmist sammu. Pistikprogramm, mis lubab luua projekte, kuid mitte neid loetleda, vaadata ega muuta, lubab rohkem kui suudab täita: kas vii see lõpule või kitsenda selle positsioneerimist.
Jäta välja ja dokumenteeri seda
Sa ei pea kõike rakendama, kuid iga suurem väljajätmine vajab põhjendust: vastuvõetamatu turva- või privaatsusrisk, API, mis ei suuda seda usaldusväärselt toetada, kontrollimatud õigused, eksitavad tulemused puuduva teabe tõttu või esimese versiooni ulatus, mis on selgelt määratletud pistikprogrammi kirjelduses. Salvesta need otsused: need annavad teavet oskuste piirangute, tööriistade kirjelduste, keeldumiste, testide ja avaliku kirjelduse teksti jaoks.
Kasutusjuhtumitest tööriistadeni
Tööriist peab teenima kasutaja eesmärki. Ära lihtsalt kopeeri oma sisemist API-t muutumatul kujul. Iga valitud kasutusjuhtumi jaoks kirjuta üles oodatav tulemus, loetle vajalik teave, tuvasta lugemis-, kirjutamis- ja välised toimingud, grupeeri see, mis moodustab tervikliku tegevuse – ja eralda see, mis erineb õiguste, riski või kinnituse vajaduse poolest.
OpenAI näide projektide pistikprogrammi jaoks:
list_projectsprojektide leidmiseks;get_projectühe projekti uurimiseks;create_projectuue projekti loomiseks;update_projectüksikasjade muutmiseks;archive_projectsuure mõjuga olekumuudatuse jaoks.
Lugemine ja kirjutamine on eraldatud, et mudel ja kasutaja saaksid eristada konsulteerimist muutmisest.
Iga tööriista leping
| Väli | Määratlus |
|---|---|
| Nimi | Stabiilne, tegevusele orienteeritud identifikaator |
| Pealkiri | Lühike, inimloetav tegevus |
| Kirjeldus | Kasutaja eesmärk ja tingimused, mis peaksid tööriista käivitama |
| Sisendskeem | Nõutavad ja valikulised parameetrid, tüübid, lubatud väärtused, piirangud |
| Väljundskeem | Struktureeritud väljad, mida mudel saab kontrollida ja uuesti kasutada |
| Volitus | Konto, roll või juurdepääs, mida server peab kontrollima |
| Kõrvalmõjud | Andmed või väline olek, mida tööriist võib muuta |
| Tõrked | Vead, mida mudel saab selgitada või millest taastuda |
Selle tabeli täiendavad kolm reeglit. Sõnaselged sisendid: ära tugine mudeli arvamusel ID-de või konto ulatuse äraarvamisele. Uuesti kasutatavad väljundid: tagasta stabiilsed ID-d ja piisavalt teavet järgmise väljakutse jaoks. Puhtad väljundid: mingeid saladusi, juurdepääsutokeneid, sisemisi diagnostikaandmeid ega ebavajalikke isikuandmeid.
Kirjeldused, mis on mõeldud valimiseks
Mudel valib tööriistu nende kirjelduse põhjal: kirjelda kasutaja kavatsust, mitte teostust. Hea kirjeldus ütleb, mida tööriist teeb, millal seda kasutada, kuidas see erineb naabritest ja millised on selle piirangud või eeltingimused. Välti kirjeldusi, mis kordavad tööriista nime või kasutavad sisemist žargooni, mida sinu kasutajad ei tunne.
Turvamärgised
Iga tööriist kannab endas märgiseid, mis on seatud vastavalt selle tegelikule käitumisele:
readOnlyHintontrueainult siis, kui tööriist ei saa muuta ühtegi olekut;destructiveHintontrue, kui tööriist võib tekitada pöördumatu või raskesti tagasipööratava tulemuse;openWorldHintontrue, kui tööriist pääseb ligi avalikule internetile või avatud välistele üksustele, isegi kui see on ainult lugemisrežiimis, nagu veebiotsing. Privaatne, piiratud konto või tööruum ei ole „avatud“ ainult seetõttu, et seda majutatakse mujal.
Märgised aitavad ChatGPT-l ja Codexil valida õiget kinnitustaset, kuid need ei asenda serveripoolset volitamist, sisendi valideerimist ega kinnitust oluliste toimingute jaoks.
Plaan, mis toimib testiplaanina
Hoia alles inventuuri ja tööriistade plaani: neist saab sinu kontrollnimekiri. Lisa otsesed, kaudsed, äärmuslikud ja väljaspool ulatust olevad päringud ning veendu, et valmis pistikprogramm käitub igaühe puhul ootuspäraselt. Otsi ka tööriistu, mis ei teeni ühtegi dokumenteeritud kasutusjuhtumit, puuduvaid lugemistoiminguid enne kirjutamist ja kirjeldusi, mis on liiga sarnased ja võivad mudelit segadusse ajada.
Peamised punktid
- Alusta sellest, mida kasutajad ootavad, ja võrdle seda sellega, mida saad turvaliselt pakkuda
- Seitsme küsimusega inventuur iga kasutusjuhtumi kohta, kaasa arvatud tahtlikud väljajätmised
- Üks tööriist ühe tervikliku tegevuse kohta; lugemine ja kirjutamine on eraldatud
- Üks leping tööriista kohta: nimi, pealkiri, kirjeldus, skeemid, volitus, kõrvalmõjud, tõrked
- Märgised (
readOnlyHint,destructiveHint,openWorldHint) järgivad tegelikku käitumist ja ei asenda volitamist