Премини към основното съдържание
Български— Изберете език
Меню

Дизайн: Сценарии на употреба и инструменти

Урок 3 от 14 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Започнете с очакванията, а не с API
  2. Инвентар на сценариите на употреба
  3. Изключете и го документирайте
  4. От сценарии на употреба към инструменти
  5. Договорът на всеки инструмент
  6. Описания, написани така, че да бъдат избрани
  7. Анотации за безопасност
  8. План, който служи като план за тестване
  9. Ключови изводи

Урокът е пренаписан на 3 ноември 2026 г. въз основа на документацията на OpenAI за Сценарии на употреба на плъгини за мозъчна атака (Brainstorm plugin use cases) и Дефиниране на инструменти (Define tools). Предишният урок инсталира несъществуващия пакет @openai/apps-sdk и манифеста chatgpt-app.json; инсталирането на действителните инструменти (официалните MCP SDK) се извършва в Урок 4. Източници: Brainstorm plugin use cases · Define tools.

Започнете с очакванията, а не с API

Документацията на OpenAI препоръчва да започнете изграждането на плъгин, преди да напишете и ред код: като изброите какво ще очакват хората от него. Името на плъгина, описанието, уменията, инструментите и продуктът, към който се прикрепя, всички те създават очаквания; Вашата реализация трябва да ги удовлетвори или да има умишлена причина да не го прави.

Представете си някой, който е инсталирал Вашия плъгин, без да чете документацията му. Какво ще го помоли да направи? За да разберете, черпете от задачите, които Вашите потребители вече изпълняват във Вашия продукт, от билетите за поддръжка, търсенията, исканията за функции, речника, който използват, и заобикалящите решения, които ги принуждават да копират данни от един инструмент в друг. Отбележете директни искания, които назовават плъгина, и косвени искания, които посочват само целта: един плъгин за управление на проекти трябва да обработва „Покажи таблото за стартиране на Acme“ по същия начин като „Какво блокира стартирането?“.

Не ограничавайте този инвентар до това, което Вашето API вече прави. Първо избройте очакванията, след което ги сравнете с това, което можете да предоставите безопасно и надеждно.

Инвентар на сценариите на употреба

За всеки сценарий на употреба OpenAI препоръчва да отговорите на седем въпроса:

ПолеВъпрос
ЦелКакво се опитва да постигне човекът?
Примерни исканияКак биха го формулирали, директно или косвено?
Очакван резултатКакво би направило взаимодействието успешно?
Необходим контекстКаква информация, достъп до акаунт или предишно състояние са необходими?
ВъзможностДали едно умение е достатъчно, или е необходим MCP инструмент?
Граница на безопасностМоже ли да разкрие данни, да промени състояние, да похарчи пари или да засегне трета страна?
РешениеПърва версия, по-късна версия или умишлено изключване?

Групирайте исканията, които споделят една и съща цел: „Изброй моите отворени задачи“, „Какво трябва да направя днес?“ и „Покажи просрочената работа“ вероятно принадлежат към един и същи сценарий за преглед на задачи, но с различни филтри.

След това проверете покритието. Всеки избран сценарий на употреба трябва да има пълен път от искането до резултата; операциите за запис трябва да включват оторизация и потвърждение; а плъгинът трябва да знае как да каже какво не прави, като същевременно предлага полезна следваща стъпка. Плъгин, който Ви позволява да създавате проекти, но не и да ги изброявате, преглеждате или редактирате, обещава повече, отколкото доставя: или го довършете, или стеснете неговото позициониране.

Изключете и го документирайте

Не е необходимо да внедрявате всичко, но всяко основно изключване заслужава причина: неприемлив риск за сигурността или поверителността, API, което не може да го поддържа надеждно, непроверими разрешения, подвеждащи резултати поради липсваща информация или обхват на първата версия, ясно посочен в списъка с плъгини. Запишете тези решения: те информират ограниченията на уменията, описанията на инструментите, отказите, тестовете и текста на публичния списък.

От сценарии на употреба към инструменти

Един инструмент трябва да служи на потребителска цел. Не копирайте просто вътрешното си API такова, каквото е. За всеки избран сценарий на употреба напишете очаквания резултат, избройте необходимата информация, идентифицирайте четенията, записите и външните действия, групирайте това, което формира последователно действие – и отделете това, което се различава по разрешения, риск или нужда от потвърждение.

Примерът на OpenAI за плъгин за проекти:

  • list_projects за намиране на проекти;
  • get_project за преглед на един проект;
  • create_project за създаване на проект;
  • update_project за модифициране на детайли;
  • archive_project за промяна на състоянието с високи последствия.

Четенията и записите са разделени, така че моделът и потребителят да могат да разграничат консултацията от модификацията.

Договорът на всеки инструмент

ПолеДефиниция
ИмеСтабилен идентификатор, ориентиран към действието
ЗаглавиеКратко, четимо от човек действие
ОписаниеЦелта на потребителя и условията, които трябва да задействат инструмента
Схема на входаЗадължителни и незадължителни параметри, типове, позволени стойности, лимити
Схема на изходаСтруктурирани полета, които моделът може да инспектира и използва повторно
ОторизацияАкаунтът, ролята или достъпът, които сървърът трябва да провери
Странични ефектиДанни или външно състояние, които инструментът може да модифицира
ГрешкиГрешки, които моделът може да обясни или от които да се възстанови

Три правила допълват тази таблица. Изрични входове: не разчитайте на модела да познае ID или обхват на акаунт. Използваеми изходи: връщайте стабилни ID и достатъчно информация за следващото извикване. Чисти изходи: без тайни, токени за достъп, вътрешна диагностика или ненужни лични данни.

Описания, написани така, че да бъдат избрани

Моделът избира инструменти въз основа на тяхното описание: опишете намерението на потребителя, а не реализацията. Едно добро описание казва какво прави инструментът, кога да се използва, как се различава от съседните си и какви са неговите лимити или предпоставки. Избягвайте такива, които повтарят името на инструмента или използват вътрешен жаргон, непознат на Вашите потребители.

Анотации за безопасност

Всеки инструмент носи анотации, зададени въз основа на действителното му поведение:

  • readOnlyHint е true само ако инструментът не може да модифицира никакво състояние;
  • destructiveHint е true, ако инструментът може да произведе необратим или труден за отмяна резултат;
  • openWorldHint е true, ако инструментът достига до публичния интернет или отворени външни субекти, дори само за четене, като уеб търсене. Частен, ограничен акаунт или работно пространство не е „отворен“ само защото е хостван другаде.

Анотациите помагат на ChatGPT и Codex да изберат правилното ниво на потвърждение, но те не заместват оторизацията от страна на сървъра, валидирането на входа или потвърждението за важни действия.

План, който служи като план за тестване

Запазете инвентара и плана за инструментите: те се превръщат във Вашия контролен списък. Добавете директни, косвени, гранични и извън обхвата искания и проверете дали завършеният плъгин се държи според очакванията за всеки от тях. Също така търсете инструменти, които не обслужват документиран сценарий на употреба, липсващи четения преди записи и описания, които са твърде близки едно до друго и могат да объркат модела.

Ключови изводи

  • Започнете с това, което потребителите ще очакват, след което сравнете с това, което можете да предоставите безопасно
  • Инвентар от седем въпроса за всеки сценарий на употреба, включително умишлените изключвания
  • Един инструмент за едно последователно действие; четенията и записите са разделени
  • Един договор за инструмент: име, заглавие, описание, схеми, оторизация, странични ефекти, грешки
  • Анотациите (readOnlyHint, destructiveHint, openWorldHint) следват действителното поведение и не заместват оторизацията