Id-Disinn: Każijiet ta' Użu u Għodod
F'din il-paġna
Lezzjon miktuba mill-ġdid fit-3 ta’ Novembru 2026 ibbażata fuq il-paġni tad-dokumentazzjoni ta’ OpenAI Brainstorm plugin use cases u Define tools. Il-lezzjoni preċedenti installat pakkett
@openai/apps-sdkli ma jeżistix u manifestchatgpt-app.json; l-installazzjoni tal-għodod attwali (l-SDKs uffiċjali tal-MCP) issir fil-Lezzjoni 4. Sorsi: Brainstorm plugin use cases · Define tools.
Ibda mill-aspettattivi, mhux mill-API
Id-dokumentazzjoni ta’ OpenAI tgħidlek tibni plugin qabel ma tikteb linja waħda ta’ kodiċi: billi telenka x’jistennew in-nies minnu. L-isem tal-plugin, id-deskrizzjoni, il-ħiliet, l-għodod, u l-prodott li jinhemeż miegħu joħolqu aspettattivi kollha; l-implimentazzjoni tiegħek trid tilħaqhom, jew ikollok raġuni deliberata biex ma tagħmilx hekk.
Immaġina xi ħadd li installa l-plugin tiegħek mingħajr ma qara d-dokumentazzjoni tiegħu. X’se jistaqsih biex jagħmel? Biex issib dan, ibbaża ruħek fuq il-kompiti li l-utenti tiegħek diġà jwettqu fil-prodott tiegħek, it-tikketti tas-support, il-mistoqsijiet fit-tiftix, it-talbiet għal karatteristiċi ġodda, il-vokabolarju li jużaw, u s-soluzzjonijiet temporanji li jfurzawhom jikkopjaw data minn għodda għal oħra. Innota t-talbiet diretti li jsemmu l-plugin, u t-talbiet indiretti li jiddikjaraw biss l-għan: plugin tal-ġestjoni tal-proġetti għandu jittratta “Uri l-bord tat-tnedija ta’ Acme” bl-istess mod bħal “X’qed jimblokaw it-tnedija?”.
Tillimitax din il-lista għal dak li l-API tiegħek diġà tagħmel. Elenska l-aspettattivi l-ewwel, imbagħad qabbelhom ma’ dak li tista’ tipprovdi b’mod sikur u affidabbli.
L-inventarju tal-każijiet ta’ użu
Għal kull każ ta’ użu, OpenAI tirrakkomanda li twieġeb seba’ mistoqsijiet:
| Qasam | Mistoqsija |
|---|---|
| Għan | X’inhu qed jipprova jikseb il-persuna? |
| Talbiet ta’ eżempju | Kif kienu jifformulawha, direttament jew indirettament? |
| Riżultat mistenni | X’ikun jagħmel l-interazzjoni suċċess? |
| Kuntest meħtieġ | Liema informazzjoni, aċċess għall-kont, jew stat preċedenti huwa meħtieġ? |
| Kapaċità | Ħila hija biżżejjed, jew għodda MCP hija meħtieġa? |
| Limitu tas-sigurtà | Tista’ tesponi data, timmodifika stat, tonfoq flus, jew taffettwa parti terza? |
| Deċiżjoni | L-ewwel verżjoni, iktar tard, jew esklużjoni intenzjonata? |
Iggroupja t-talbiet li jaqsmu l-istess għan: “Elenska l-kompiti miftuħa tiegħi”, “X’għandi nagħmel illum?” u “Uri x-xogħol skadut” x’aktarx jappartjenu għall-istess każ ta’ użu ta’ reviżjoni tal-kompiti, b’filtri differenti.
Imbagħad ivverifika l-kopertura. Kull każ ta’ użu magħżul irid ikollu mogħdija sħiħa mit-talba għar-riżultat; il-kitbiet (writes) iridu jinkludu awtorizzazzjoni u konferma; u l-plugin irid ikun jaf kif jgħid dak li ma jagħmilx waqt li joffri pass li jmiss utli. Plugin li jħallik toħloq proġetti iżda mhux telista, tara, jew teditjahom, iwiegħed aktar milli jwassal: jew ikmilih jew iddejjaq il-pożizzjonament tiegħu.
Eskludi, u ddokumentaha
M’għandekx timplimenta kollox, iżda kull esklużjoni maġġuri teħtieġ raġuni: riskju inaċċettabbli għas-sigurtà jew il-privatezza, API li ma tistax tappoġġjah b’mod affidabbli, permessi li ma jistgħux jiġu vverifikati, riżultati qarrieqa minħabba nuqqas ta’ informazzjoni, jew ambitu tal-ewwel verżjoni ddikjarat b’mod ċar fil-lista tal-plugin. Irreġistra dawn id-deċiżjonijiet: dawn jinfurmaw il-limiti tal-ħiliet, id-deskrizzjonijiet tal-għodod, ir-rifjuti, it-testijiet, u t-test tal-lista pubblika.
Mill-każijiet ta’ użu għall-għodod
Għodda trid isservi għan tal-utent. Tikkopjax sempliċiment l-API interna tiegħek kif inhi. Għal kull każ ta’ użu magħżul, ikteb ir-riżultat mistenni, elenka l-informazzjoni meħtieġa, identifika l-qari (reads), il-kitbiet (writes), u l-azzjonijiet esterni, iggroupja dak li jifforma azzjoni koerenti—u seppara dak li jvarja skont il-permessi, ir-riskju, jew il-bżonn ta’ konferma.
L-eżempju ta’ OpenAI għal plugin tal-proġetti:
list_projectsbiex issib proġetti;get_projectbiex teħtieġ wieħed;create_projectbiex toħloq wieħed;update_projectbiex timmodifika d-dettalji;archive_projectgħal bidla fl-istat b’konsegwenzi għoljin.
Il-qari u l-kitbiet huma separati biex il-mudell u l-utent ikunu jistgħu jiddistingwu bejn il-konsultazzjoni u l-modifika.
Il-kuntratt ta’ kull għodda
| Qasam | Iddefinixxi |
|---|---|
| Isem | Identifikatur stabbli, orjentat lejn l-azzjoni |
| Titolu | Azzjoni konċiża, li tinftiehem mill-bniedem |
| Deskrizzjoni | L-għan tal-utent u l-kundizzjonijiet li għandhom jattivaw l-għodda |
| Skema tal-input | Parametri meħtieġa u fakultattivi, tipi, valuri permessi, limiti |
| Skema tal-output | Oqsma strutturati li l-mudell jista’ jispezzjona u jerġa’ juża |
| Awtorizzazzjoni | Il-kont, ir-rwol, jew l-aċċess li s-server irid jivverifika |
| Effetti sekondarji | Data jew stat estern li l-għodda tista’ timmodifika |
| Fallimenti | Żbalji li l-mudell jista’ jispjega jew jirkupra minnhom |
Tliet regoli jikmlew din it-tabella. Inputs espliċiti: ma tiddependix fuq il-mudell biex jindovina ID jew ambitu tal-kont. Outputs li jistgħu jerġgħu jintużaw: irritorna IDs stabbli u biżżejjed informazzjoni għas-sejħa li jmiss. Outputs nodfa: l-ebda sigriet, tokens tal-aċċess, dijanjostika interna, jew data personali mhux meħtieġa.
Deskrizzjonijiet miktuba biex jintgħażlu
Il-mudell jagħżel l-għodod ibbażat fuq id-deskrizzjoni tagħhom: iddeskrivi l-intenzjoni tal-utent, mhux l-implimentazzjoni. Deskrizzjoni tajba tgħid x’tagħmel l-għodda, meta għandha tintuża, kif tvarja mill-ġirien tagħha, u x’inhuma l-limiti jew il-prerekwiżiti tagħha. Evita dawk li jirrepetu l-isem tal-għodda jew jużaw ġargon intern li l-utenti tiegħek ma jafuhx.
Annotazzjonijiet tas-sigurtà
Kull għodda ġġorr annotazzjonijiet, stabbiliti abbażi tal-imġiba attwali tagħha:
readOnlyHinthijatruebiss jekk l-għodda ma tistax timmodifika l-ebda stat;destructiveHinthijatruejekk l-għodda tista’ tipproduċi riżultat irreversibbli jew diffiċli biex jinqaleb lura;openWorldHinthijatruejekk l-għodda taċċessa l-internet pubbliku jew entitajiet esterni miftuħa, anke jekk huma biss għall-qari bħal tfittxija fuq il-web. Kont privat u limitat jew spazju tax-xogħol mhuwiex “miftuħ” sempliċiment għax huwa ospitat f’post ieħor.
L-annotazzjonijiet jgħinu lil ChatGPT u Codex jagħżlu l-livell tajjeb ta’ konferma, iżda ma jissostitwixxux l-awtorizzazzjoni fuq is-server, il-validazzjoni tal-input, jew il-konferma għal azzjonijiet importanti.
Pjan li jservi bħala pjan ta’ test
Żomm l-inventarju u l-pjan tal-għodod: dawn isiru ċ-checklist tiegħek. Żid talbiet diretti, indiretti, tal-fruntiera (edge), u barra mill-ambitu, u vverifika li l-plugin lest jaġixxi kif mistenni għal kull wieħed. Fittex ukoll għodod li ma jservu l-ebda każ ta’ użu ddokumentat, qari nieqes qabel il-kitbiet, u deskrizzjonijiet viċini wisq li jistgħu jħawdu lill-mudell.
Punti Ewlenin
- Ibda minn dak li l-utenti se jistennew, imbagħad qabbel ma’ dak li tista’ tipprovdi b’mod sikur
- Inventarju ta’ seba’ mistoqsijiet għal kull każ ta’ użu, inklużi esklużjonijiet intenzjonati
- Għodda waħda għal kull azzjoni koerenti; il-qari u l-kitbiet separati
- Kuntratt wieħed għal kull għodda: isem, titolu, deskrizzjoni, skemi, awtorizzazzjoni, effetti sekondarji, fallimenti
- L-annotazzjonijiet (
readOnlyHint,destructiveHint,openWorldHint) isegwu l-imġiba attwali u ma jissostitwixxux l-awtorizzazzjoni