Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Id-Disinn: Każijiet ta' Użu u Għodod

Lezzjoni 3 / 14 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Ibda mill-aspettattivi, mhux mill-API
  2. L-inventarju tal-każijiet ta’ użu
  3. Eskludi, u ddokumentaha
  4. Mill-każijiet ta’ użu għall-għodod
  5. Il-kuntratt ta’ kull għodda
  6. Deskrizzjonijiet miktuba biex jintgħażlu
  7. Annotazzjonijiet tas-sigurtà
  8. Pjan li jservi bħala pjan ta’ test
  9. Punti Ewlenin

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-sdk li ma jeżistix u manifest chatgpt-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:

QasamMistoqsija
GħanX’inhu qed jipprova jikseb il-persuna?
Talbiet ta’ eżempjuKif kienu jifformulawha, direttament jew indirettament?
Riżultat mistenniX’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żjoniL-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_projects biex issib proġetti;
  • get_project biex teħtieġ wieħed;
  • create_project biex toħloq wieħed;
  • update_project biex timmodifika d-dettalji;
  • archive_project għ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

QasamIddefinixxi
IsemIdentifikatur stabbli, orjentat lejn l-azzjoni
TitoluAzzjoni konċiża, li tinftiehem mill-bniedem
DeskrizzjoniL-għan tal-utent u l-kundizzjonijiet li għandhom jattivaw l-għodda
Skema tal-inputParametri meħtieġa u fakultattivi, tipi, valuri permessi, limiti
Skema tal-outputOqsma strutturati li l-mudell jista’ jispezzjona u jerġa’ juża
AwtorizzazzjoniIl-kont, ir-rwol, jew l-aċċess li s-server irid jivverifika
Effetti sekondarjiData 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:

  • readOnlyHint hija true biss jekk l-għodda ma tistax timmodifika l-ebda stat;
  • destructiveHint hija true jekk l-għodda tista’ tipproduċi riżultat irreversibbli jew diffiċli biex jinqaleb lura;
  • openWorldHint hija true jekk 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