Przejdź do głównej treści
Polski— Wybierz język
Menu

Projektowanie: Przypadki użycia i narzędzia

Lekcja 3 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Zacznij od oczekiwań, a nie od API
  2. Inwentaryzacja przypadków użycia
  3. Wykluczaj i dokumentuj to
  4. Od przypadków użycia do narzędzi
  5. Kontrakt każdego narzędzia
  6. Opisy pisane tak, by były wybierane
  7. Adnotacje bezpieczeństwa
  8. Plan, który służy jako plan testów
  9. Kluczowe wnioski

Lekcja przepisana 3 listopada 2026 r. na podstawie dokumentacji OpenAI dotyczącej Przypadków użycia wtyczek typu Brainstorm oraz Definiowania narzędzi. Poprzednia lekcja instalowała nieistniejący pakiet @openai/apps-sdk i manifest chatgpt-app.json; instalacja właściwych narzędzi (oficjalne SDK MCP) następuje w Lekcji 4. Źródła: Brainstorm plugin use cases · Define tools.

Zacznij od oczekiwań, a nie od API

Dokumentacja OpenAI zaleca, aby przed napisaniem pierwszej linii kodu zająć się planowaniem wtyczki: wypisz to, czego ludzie będą się po niej spodziewać. Nazwa wtyczki, opis, umiejętności, narzędzia oraz produkt, do którego jest podpięta – wszystko to buduje oczekiwania. Twoja implementacja musi im sprostać lub mieć świadomy powód, by tego nie robić.

Wyobraź sobie kogoś, kto zainstalował Twoją wtyczkę, nie czytając dokumentacji. O co ją poprosi? Aby to ustalić, czerp z zadań, które użytkownicy już wykonują w Twoim produkcie, zgłoszeń do wsparcia, haseł wyszukiwania, próśb o nowe funkcje, słownictwa, którego używają, oraz obejść, które zmuszają ich do kopiowania danych z jednego narzędzia do drugiego. Zwróć uwagę na bezpośrednie prośby wymieniające nazwę wtyczki oraz pośrednie, które określają tylko cel: wtyczka do zarządzania projektami musi obsłużyć zarówno polecenie „Pokaż tablicę startową Acme“, jak i pytanie „Co blokuje start?“.

Nie ograniczaj tej inwentaryzacji do tego, co Twoje API już potrafi. Najpierw spisz oczekiwania, a następnie porównaj je z tym, co możesz dostarczyć bezpiecznie i niezawodnie.

Inwentaryzacja przypadków użycia

Dla każdego przypadku użycia OpenAI rekomenduje odpowiedź na siedem pytań:

PolePytanie
CelCo użytkownik próbuje osiągnąć?
Przykładowe prośbyJak by to sformułował, bezpośrednio lub pośrednio?
Oczekiwany wynikCo sprawi, że interakcja będzie udana?
Wymagany kontekstJakie informacje, dostęp do konta lub stan wcześniejszy są potrzebne?
MożliwościCzy wystarczy umiejętność (skill), czy konieczne jest narzędzie MCP?
Granica bezpieczeństwaCzy może to ujawnić dane, zmodyfikować stan, wydać pieniądze lub wpłynąć na stronę trzecią?
DecyzjaWersja pierwsza, późniejsza czy celowe wykluczenie?

Grupuj prośby o wspólnym celu: „Wymień moje otwarte zadania“, „Co mam do zrobienia dzisiaj?“ i „Pokaż zaległe prace“ prawdopodobnie należą do tego samego przypadku użycia – przeglądu zadań – z różnymi filtrami.

Następnie zweryfikuj pokrycie. Każdy wybrany przypadek użycia musi mieć kompletną ścieżkę od prośby do wyniku. Operacje zapisu muszą zawierać autoryzację i potwierdzenie, a wtyczka musi wiedzieć, jak zakomunikować, czego nie robi, oferując jednocześnie użyteczny kolejny krok. Wtyczka, która pozwala tworzyć projekty, ale nie umożliwia ich listowania, przeglądania ani edycji, obiecuje więcej, niż dostarcza: albo ją dokończ, albo zawęź jej pozycjonowanie.

Wykluczaj i dokumentuj to

Nie musisz implementować wszystkiego, ale każde główne wykluczenie zasługuje na uzasadnienie: nieakceptowalne ryzyko bezpieczeństwa lub prywatności, API, które nie może tego obsłużyć niezawodnie, nieweryfikowalne uprawnienia, mylące wyniki spowodowane brakiem informacji lub jasno określony zakres pierwszej wersji w opisie wtyczki. Zanotuj te decyzje: informują one o limitach umiejętności, opisach narzędzi, odmowach, testach i tekście publicznego opisu.

Od przypadków użycia do narzędzi

Narzędzie musi służyć celowi użytkownika. Nie kopiuj po prostu swojego wewnętrznego API jeden do jednego. Dla każdego wybranego przypadku użycia zapisz oczekiwany wynik, wymień wymagane informacje, zidentyfikuj operacje odczytu, zapisu i działania zewnętrzne, zgrupuj to, co tworzy spójną akcję – i oddziel to, co różni się uprawnieniami, ryzykiem lub koniecznością potwierdzenia.

Przykład OpenAI dla wtyczki do projektów:

  • list_projects do znajdowania projektów;
  • get_project do badania konkretnego projektu;
  • create_project do tworzenia projektu;
  • update_project do modyfikowania szczegółów;
  • archive_project dla zmiany stanu o wysokich konsekwencjach.

Odczyty i zapisy są rozdzielone, aby model i użytkownik mogli odróżnić konsultację od modyfikacji.

Kontrakt każdego narzędzia

PoleDefinicja
NazwaStabilny identyfikator zorientowany na akcję
TytułZwięzła, czytelna dla człowieka nazwa akcji
OpisCel użytkownika i warunki, które powinny uruchomić narzędzie
Schemat wejściaWymagane i opcjonalne parametry, typy, dozwolone wartości, limity
Schemat wyjściaStrukturalne pola, które model może inspektować i ponownie wykorzystać
AutoryzacjaKonto, rola lub dostęp, które serwer musi zweryfikować
Efekty uboczneDane lub stan zewnętrzny, które narzędzie może zmodyfikować
BłędyBłędy, które model może wyjaśnić lub z których może się odzyskać

Trzy zasady uzupełniają tę tabelę. Jawne dane wejściowe: nie polegaj na modelu, aby zgadywał ID lub zakres konta. Wielokrotnego użytku dane wyjściowe: zwracaj stabilne ID i wystarczającą ilość informacji do kolejnego wywołania. Czyste dane wyjściowe: żadnych sekretów, tokenów dostępu, wewnętrznej diagnostyki ani niepotrzebnych danych osobowych.

Opisy pisane tak, by były wybierane

Model wybiera narzędzia na podstawie ich opisu: opisuj intencję użytkownika, a nie implementację. Dobry opis mówi, co narzędzie robi, kiedy go użyć, czym różni się od sąsiednich narzędzi oraz jakie są jego limity lub warunki wstępne. Unikaj opisów, które powtarzają nazwę narzędzia lub używają wewnętrznego żargonu nieznanego użytkownikom.

Adnotacje bezpieczeństwa

Każde narzędzie posiada adnotacje ustawiane na podstawie jego rzeczywistego zachowania:

  • readOnlyHint wynosi true tylko wtedy, gdy narzędzie nie może modyfikować żadnego stanu;
  • destructiveHint wynosi true, jeśli narzędzie może wywołać nieodwracalny lub trudny do cofnięcia rezultat;
  • openWorldHint wynosi true, jeśli narzędzie uzyskuje dostęp do publicznego internetu lub otwartych podmiotów zewnętrznych, nawet tylko do odczytu, jak wyszukiwarka internetowa. Prywatne, ograniczone konto lub przestrzeń robocza nie jest „otwarta“ tylko dlatego, że jest hostowana gdzie indziej.

Adnotacje pomagają ChatGPT i Codex wybrać odpowiedni poziom potwierdzenia, ale nie zastępują autoryzacji po stronie serwera, walidacji danych wejściowych ani potwierdzenia dla ważnych akcji.

Plan, który służy jako plan testów

Zachowaj inwentaryzację i plan narzędzi: staną się one Twoją listą kontrolną. Dodaj prośby bezpośrednie, pośrednie, brzegowe i te wykraczające poza zakres, a następnie zweryfikuj, czy gotowa wtyczka zachowuje się zgodnie z oczekiwaniami dla każdej z nich. Szukaj również narzędzi, które nie obsługują żadnego udokumentowanego przypadku użycia, brakujących odczytów przed zapisami oraz opisów zbyt podobnych do siebie, które mogą zmylić model.

Kluczowe wnioski

  • Zacznij od tego, czego użytkownicy będą oczekiwać, a następnie porównaj to z tym, co możesz dostarczyć bezpiecznie
  • Inwentaryzacja siedmiu pytań dla każdego przypadku użycia, łącznie z celowymi wykluczeniami
  • Jedno narzędzie na spójną akcję; odczyty i zapisy rozdzielone
  • Jeden kontrakt na narzędzie: nazwa, tytuł, opis, schematy, autoryzacja, efekty uboczne, błędy
  • Adnotacje (readOnlyHint, destructiveHint, openWorldHint) wynikają z rzeczywistego zachowania i nie zastępują autoryzacji