Suunnittelu: Käyttötapaukset ja työkalut
Tällä sivulla
Oppitunti kirjoitettu uudelleen 3. marraskuuta 2026 OpenAI:n Brainstorm plugin use cases - ja Define tools -dokumentaation perusteella. Edellinen oppitunti asensi olematonta
@openai/apps-sdk-pakettia jachatgpt-app.json-manifestia; varsinaisten työkalujen (viralliset MCP SDK:t) asennus tapahtuu oppitunnilla 4. Lähteet: Brainstorm plugin use cases · Define tools.
Aloita odotuksista, älä rajapinnasta
OpenAI:n dokumentaatio kehottaa aloittamaan liitännäisen rakentamisen ennen kuin kirjoitat ainuttakaan koodiriviä: listaamalla, mitä ihmiset odottavat siltä. Liitännäisen nimi, kuvaus, taidot, työkalut ja tuote, johon se kiinnittyy, luovat kaikki odotuksia; toteutuksesi on täytettävä ne, tai sinulla on oltava harkittu syy olla tekemättä niin.
Kuvittele henkilö, joka on asentanut liitännäisesi lukematta sen dokumentaatiota. Mitä hän pyytää sitä tekemään? Saadaksesi selville, amenna tehtävistä, joita käyttäjäsi jo suorittavat tuotteessasi, tukipyyntöjen, hakukyselyiden, ominaisuuspyyntöjen, heidän käyttämänsä sanaston sekä kiertoteiden, jotka pakottavat heidät kopioimaan dataa työkalusta toiseen. Huomioi suorat pyynnöt, joissa mainitaan liitännäisen nimi, ja epäsuorat pyynnöt, joissa ilmoitetaan vain tavoite: projektinhallintaliitännäisen on käsiteltävä ”Näytä Acmen julkaisutaulu” samalla tavalla kuin ”Mikä estää julkaisun?”.
Älä rajoita tätä inventaariota siihen, mitä rajapintasi jo tekee. Listaa odotukset ensin ja vertaa niitä sitten siihen, mitä voit tarjota turvallisesti ja luotettavasti.
Käyttötapausinventaario
Jokaista käyttö tapausta varten OpenAI suosittelee vastaamaan seitsemään kysymykseen:
| Kenttä | Kysymys |
|---|---|
| Tavoite | Mitä henkilö yrittää saavuttaa? |
| Esimerkkipyynnöt | Miten hän muotoilisi sen, suoraan tai epäsuorasti? |
| Odotettu lopputulos | Mikä tekisi vuorovaikutuksesta onnistuneen? |
| Vaadittu konteksti | Mitä tietoja, tilikäyttöoikeuksia tai aiempaa tilaa tarvitaan? |
| Kyky | Riittääkö taito, vai tarvitaanko MCP-työkalu? |
| Turvaraja | Voisiko se paljastaa dataa, muuttaa tilaa, kuluttaa rahaa tai vaikuttaa kolmanteen osapuoleen? |
| Päätös | Ensimmäinen versio, myöhemmin vai tarkoituksellinen poisjättäminen? |
Ryhmittele pyynnöt, joilla on sama tavoite: ”Listaa avoimet tehtäväni”, ”Mitä minun pitää tehdä tänään?” ja ”Näytä myöhässä olevat työt” kuuluvat todennäköisesti samaan tehtävien katselmuskäyttötapaukseen eri suodattimilla.
Varmista sitten kattavuus. Jokaisella valitulla käyttötapauksella on oltava täydellinen polku pyynnöstä tulokseen; kirjoitusoperaatioiden on sisällettävä valtuutus ja vahvistus; ja liitännäisen on osattava kertoa, mitä se ei tee, tarjoten samalla hyödyllisen seuraavan askeleen. Liitännäinen, jonka avulla voit luoda projekteja mutta et listata, tarkastella tai muokata niitä, lupaa enemmän kuin mitä se toimittaa: joko viimeistele se tai rajaa sen kohdistusta.
Jätä pois ja dokumentoi se
Sinun ei tarvitse toteuttaa kaikkea, mutta jokainen merkittävä poisjättäminen ansaitsee syyn: hyväksymätön turvallisuus- tai tietosuojariski, rajapinta, joka ei tue sitä luotettavasti, varmennettavat käyttöoikeudet puuttuvat, harhaanjohtavat tulokset puuttuvien tietojen vuoksi tai ensimmäisen version laajuus, joka on ilmoitettu selkeästi liitännäisen listauksessa. Kirjaa nämä päätökset: ne ohjaavat taitorajoituksia, työkalukuvauksia, kieltäytymisiä, testejä ja julkista listaus tekstiä.
Käyttötapauksista työkaluihin
Työkalun on palveltava käyttäjän tavoitetta. Älä vain kopioi sisäistä rajapintaasi sellaisenaan. Jokaista valittua käyttö tapausta varten kirjoita odotettu lopputulos, listaa vaaditut tiedot, tunnista luku-, kirjoitus- ja ulkoiset toiminnot, ryhmittele ne, jotka muodostavat yhtenäisen toiminnon – ja erota ne, jotka eroavat käyttöoikeuksien, riskin tai vahvistustarpeen perusteella.
OpenAI:n esimerkki projektiliitännäiselle:
list_projectsprojektien löytämiseen;get_projectyhden tarkasteluun;create_projectuuden luomiseen;update_projectyksityiskohtien muokkaamiseen;archive_projectsuurivaikutteiseen tilanmuutokseen.
Luku- ja kirjoitusoperaatiot on erotettu, jotta malli ja käyttäjä voivat erottaa kuulemisen muokkaamisesta.
Jokaisen työkalun sopimus
| Kenttä | Määritä |
|---|---|
| Nimi | Vakaa, toimintasuuntautunut tunniste |
| Otsikko | Tiivis, ihmiselle luettava toiminto |
| Kuvaus | Käyttäjän tavoite ja ehdot, jotka pitäisi laukaista työkalu |
| Syöteskeema | Vaaditut ja valinnaiset parametrit, tyypit, sallitut arvot, rajat |
| Tulosteskeema | Jäsennellyt kentät, joita malli voi tarkastella ja käyttää uudelleen |
| Valtuutus | Tili, rooli tai pääsy, joka palvelimen on varmistettava |
| Sivuvaikutukset | Data tai ulkoinen tila, jonka työkalu voi muuttaa |
| Virheet | Virheet, joita malli voi selittää tai joista se voi palautua |
Kolme sääntöä täydentää tätä taulukkoa. Eksplisiittiset syötteet: älä luota malliin arvatakseen tunnisteita tai tilin laajuutta. Uudelleenkäytettävät tulosteet: palauta vakaita tunnisteita ja tarpeeksi tietoa seuraavaa kutsua varten. Siistit tulosteet: ei salaisuuksia, käyttöoikeustokeneja, sisäisiä diagnostiikkatietoja tai tarpeetonta henkilökohtaista dataa.
Kuvaukset kirjoitettu valittavaksi
Malli valitsee työkalut niiden kuvauksen perusteella: kuvaile käyttäjän aikomusta, älä toteutusta. Hyvä kuvaus kertoo, mitä työkalu tekee, milloin sitä käytetään, miten se eroaa naapureistaan ja mitkä ovat sen rajat tai edellytykset. Vältä kuvauksia, jotka toistavat työkalun nimen tai käyttävät sisäistä jargonia, jota käyttäjäsi eivät tunne.
Turvallisuusmerkinnät
Jokainen työkalu sisältää merkintöjä, jotka asetetaan sen todellisen käyttäytymisen perusteella:
readOnlyHintontruevain, jos työkalu ei voi muuttaa mitään tilaa;destructiveHintontrue, jos työkalu voi tuottaa peruuttamattoman tai vaikeasti peruttavan tuloksen;openWorldHintontrue, jos työkalu käyttää julkista internetiä tai avoimia ulkoisia entiteettejä, vaikka se olisi vain lukuoperaatio kuten verkkohaku. Yksityinen, rajattu tili tai työtila ei ole “avoin” vain siksi, että se on isännoitu muualla.
Merkinnät auttavat ChatGPT:tä ja Codexia valitsemaan oikean vahvistustason, mutta ne eivät korvaa palvelinpuolen valtuutusta, syötteen validointia tai vahvistusta tärkeissä toiminnoissa.
Suunnitelma, joka toimii testisuunnitelmana
Pidä inventaario ja työkalusuunnitelma tallessa: niistä tulee tarkistuslistasi. Lisää suoria, epäsuoria, reunatapauksiin liittyviä ja aihealueen ulkopuolisia pyyntöjä, ja varmista, että valmis liitännäinen käyttäytyy odotetusti jokaisessa tapauksessa. Etsi myös työkaluja, jotka eivät palvele mitään dokumentoitua käyttö tapausta, puuttuvia lukuoperaatioita ennen kirjoitusoperaatioita sekä kuvauksia, jotka ovat liian lähellä toisiaan ja saattavat sekoittaa mallia.
Keskeiset asiat
- Aloita siitä, mitä käyttäjät odottavat, ja vertaa sitten siihen, mitä voit tarjota turvallisesti
- Seitsemän kysymyksen inventaario kutakin käyttö tapausta kohden, mukaan lukien tarkoitukselliset poisjättämiset
- Yksi työkalu kutakin yhtenäistä toimintoa kohden; luku- ja kirjoitusoperaatiot erotettu
- Yksi sopimus työkalua kohden: nimi, otsikko, kuvaus, skeemat, valtuutus, sivuvaikutukset, virheet
- Merkinnät (
readOnlyHint,destructiveHint,openWorldHint) seuraavat todellista käyttäytymistä eivätkä korvaa valtuutusta