Dizains: lietojuma gadījumi un rīki
Šajā lapā
Nodarbība pārrakstīta 2026. gada 3. novembrī, pamatojoties uz OpenAI dokumentācijas lapām Brainstorm plugin use cases un Define tools. Iepriekšējā nodarbībā tika instalēts neeksistējošs pakotnes nosaukums
@openai/apps-sdkun manifestschatgpt-app.json; patieso rīku (oficiālo MCP SDK) instalēšana notiek 4. nodarbībā. Avoti: Brainstorm plugin use cases · Define tools.
Sāc ar gaidām, nevis API
OpenAI dokumentācija iesaka spraudņa izstrādi sākt, pirms uzrakstīta pirmā koda rinda: sastādi sarakstu ar to, ko lietotāji no tā sagaida. Spraudņa nosaukums, apraksts, prasmes, rīki un produkts, pie kura tas pieslēdzas, veido šīs gaidas; tavai implementācijai tās ir jāattaisno, vai arī jābūt apzinātam iemeslam, kāpēc tās netiek izpildītas.
Iedomājies kādu, kurš ir instalējis tavu spraudni, neizlasot tā dokumentāciju. Ko viņš tam lūgs darīt? Lai to noskaidrotu, izmanto datus par uzdevumiem, kurus tavi lietotāji jau veic tavā produktā, atbalsta biļetes, meklēšanas vaicājumus, funkciju pieprasījumus, viņu lietoto vokabulāru, kā arī pagaidu risinājumus, kas liek tiem kopēt datus no viena rīka uz citu. Atzīmē gan tiešus pieprasījumus, kuros minēts spraudņa nosaukums, gan netiešus pieprasījumus, kuros pausts tikai mērķis: projektu vadības spraudnim vienlīdz jāapstrādā „Parādi Acme palaišanas tāfeli” un „Kas kavē palaišanu?”.
Neierobežo šo inventāru tikai ar to, ko tavs API jau spēj darīt. Vispirms uzskaiti gaidas, tad salīdzini tās ar to, ko vari nodrošināt droši un uzticami.
Lietojuma gadījumu inventārs
Katram lietojuma gadījumam OpenAI iesaka atbildēt uz septiņiem jautājumiem:
| Lauks | Jautājums |
|---|---|
| Mērķis | Ko cilvēks cenšas sasniegt? |
| Piemēra pieprasījumi | Kā viņš to formulētu, tieši vai netieši? |
| Paredzamais rezultāts | Kas padarītu mijiedarbību veiksmīgu? |
| Nepieciešamais konteksts | Kāda informācija, konta piekļuve vai iepriekšējais stāvoklis ir vajadzīgs? |
| Spēja | Vai pietiek ar prasmi, vai ir nepieciešams MCP rīks? |
| Drošības robeža | Vai tas var atklāt datus, mainīt stāvokli, tērēt naudu vai ietekmēt trešo pusi? |
| Lēmums | Pirmā versija, vēlāka realizācija vai apzināta izslēgšana? |
Sagrupē pieprasījumus, kuriem ir kopīgs mērķis: „Uzskaiti manus atvērtos uzdevumus”, „Kas man šodien jādara?” un „Parādi nokavētos darbus” droši vien pieder vienam un tam pašam uzdevumu apskates lietojuma gadījumam, tikai ar dažādiem filtriem.
Tad pārbaudi pārklājumu. Katram atlasītajam lietojuma gadījumam ir jābūt pilnam ceļam no pieprasījuma līdz rezultātam; rakstīšanas operācijām ir jāietver autorizācija un apstiprinājums; spraudnim ir jāprot pateikt, ko tas nedara, vienlaikus piedāvājot noderīgu nākamo soli. Spraudnis, kas ļauj izveidot projektus, bet ne tos uzskaitīt, apskatīt vai rediģēt, sola vairāk, nekā spēj nodrošināt: vai nu pabeidz to, vai sašaurini tā pozicionējumu.
Izslēg un dokumentē to
Tev nav jāimplementē viss, taču katram lielam izslēgumam ir jābūt pamatojumam: nepieņemams drošības vai privātuma risks, API, kas to nevar uzticami atbalstīt, nepārbaudāmas atļaujas, maldinoši rezultāti trūkstošas informācijas dēļ vai pirmās versijas tvērums, kas skaidri norādīts spraudņa sarakstā. Fiksē šos lēmumus: tie informē prasmju robežas, rīku aprakstus, atteikumus, testus un publisko saraksta tekstu.
No lietojuma gadījumiem uz rīkiem
Rīkam ir jākalpo lietotāja mērķim. Vienkārši nenokopē savu iekšējo API tādu, kāds tas ir. Katram atlasītajam lietojuma gadījumam uzraksti paredzamo rezultātu, uzskaiti nepieciešamo informāciju, identificē lasīšanas, rakstīšanas un ārējās darbības, sagrupē to, kas veido vienotu darbību, un atdali to, kas atšķiras pēc atļaujām, riska vai nepieciešamības pēc apstiprinājuma.
OpenAI piemērs projektu spraudnim:
list_projects, lai atrastu projektus;get_project, lai apskatītu vienu no tiem;create_project, lai izveidotu jaunu;update_project, lai modificētu detaļas;archive_project, lai veiktu augstas sekas izraisošu stāvokļa maiņu.
Lasīšanas un rakstīšanas operācijas ir atdalītas, lai modelis un lietotājs varētu atšķirt konsultēšanos no modificēšanas.
Katra rīka līgums
| Lauks | Definīcija |
|---|---|
| Nosaukums | Stabilais, uz darbību orientēts identifikators |
| Virsraksts | Kodolīgs, cilvēkam lasāms darbības apraksts |
| Apraksts | Lietotāja mērķis un nosacījumi, kuriem jāizraisa rīka izmantošana |
| Ievades shēma | Nepieciešamie un neobligātie parametri, tipi, atļautās vērtības, limiti |
| Izvades shēma | Strukturēti lauki, kurus modelis var pārbaudīt un atkārtoti izmantot |
| Autorizācija | Konts, loma vai piekļuve, kas serverim ir jāpārbauda |
| Blakusparādības | Dati vai ārējais stāvoklis, ko rīks var modificēt |
| Kļūmes | Kļūdas, ko modelis var izskaidrot vai no kurām var atgūties |
Šo tabulu papildina trīs noteikumi. Eksplicīta ievade: nepaļaujies uz to, ka modelis uzminēs ID vai konta tvērumu. Atkārtoti izmantojama izvade: atgriez stabilus ID un pietiekami daudz informācijas nākamajam izsaukumam. Tīra izvade: bez noslēpumiem, piekļuves tokeniem, iekšējās diagnostikas vai liekiem personas datiem.
Apraksti, kas rakstīti, lai tos izvēlētos
Modelis izvēlas rīkus, balstoties uz to aprakstiem: apraksti lietotāja nodomu, nevis implementāciju. Labs apraksts norāda, ko rīks dara, kad to lietot, kā tas atšķiras no saviem kaimiņiem un kādas ir tā robežas vai priekšnosacījumi. Izvairies no aprakstiem, kas atkārto rīka nosaukumu vai lieto iekšēju žargonu, ko tavi lietotāji nepazīst.
Drošības anotācijas
Katrs rīks nes anotācijas, kas noteiktas, balstoties uz tā faktisko uzvedību:
readOnlyHintirtruetikai tad, ja rīks nevar modificēt nevienu stāvokli;destructiveHintirtrue, ja rīks var radīt neatgriezenisku vai grūti atceļamu rezultātu;openWorldHintirtrue, ja rīks piekļūst publiskajam internetam vai atvērtām ārējām entītēm, pat ja tas ir tikai lasīšanas režīmā, piemēram, tīmekļa meklēšana. Privāts, ierobežots konts vai darbvietas nav „atvērts”, tikai tāpēc, ka tas ir mitināts citur.
Anotācijas palīdz ChatGPT un Codex izvēlēties pareizo apstiprinājuma līmeni, taču tās neaizstāj servera puses autorizāciju, ievades validāciju vai apstiprinājumu svarīgām darbībām.
Plāns, kas kalpo kā testu plāns
Saglabā inventāru un rīku plānu: tie kļūst par tavu kontrolsarakstu. Pievieno tiešus, netiešus, robežas un ārpus tvēruma esošus pieprasījumus un pārbaudi, vai pabeigtais spraudnis katram no tiem uzvedas paredzētajā veidā. Tāpat meklē rīkus, kas nekalpo nevienam dokumentētam lietojuma gadījumam, trūkstošas lasīšanas operācijas pirms rakstīšanas, kā arī aprakstus, kas ir pārāk līdzīgi viens otram un varētu maldināt modeli.
Galvenās atziņas
- Sāc ar to, ko lietotāji sagaidīs, tad salīdzini ar to, ko vari nodrošināt droši
- Septiņu jautājumu inventārs katram lietojuma gadījumam, ieskaitot apzinātas izslēgšanas
- Viens rīks vienai vienotai darbībai; lasīšana un rakstīšana ir atdalīta
- Viens līgums katram rīkam: nosaukums, virsraksts, apraksts, shēmas, autorizācija, blakusparādības, kļūmes
- Anotācijas (
readOnlyHint,destructiveHint,openWorldHint) seko faktiskajai uzvedībai un neaizstāj autorizāciju