Дизайн: Сценарии на употреба и инструменти
На тази страница
Урокът е пренаписан на 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) следват действителното поведение и не заместват оторизацията