Скрипт приложений: напишите Vibe-код дополнения к Gmail с помощью Gemini CLI и серверов MCP

1. Обзор

В этой лабораторной работе вы освоите современный рабочий процесс на основе искусственного интеллекта для создания динамического дополнения Gmail с нуля. Вы будете использовать Gemini CLI для организации мощной локальной среды разработки, используя серверы MCP (Model Context Protocol) и расширения Gemini CLI для интеграции таких инструментов, как gcloud и clasp .

Созданное вами дополнение будет генерировать и отображать уникальное изображение кошки по запросу, вызывая модель изображения на платформе Vertex AI от Google Cloud.

В результате у вас будет полностью функциональное дополнение для Gmail, которое вызывает API Vertex AI для генерации уникальных изображений непосредственно в интерфейсе Gmail, и все это будет управляться из локальной командной строки.

2. Чему вы научитесь

Выполнив эту лабораторную работу, вы научитесь:

  • Настройка и использование Gemini CLI с расширениями
  • Создайте дополнение Gmail, которое вызывает внешний API
  • Измените дополнение так, чтобы оно вызывало API Vertex AI для генерации изображений.
  • Разверните тестовую версию надстройки Google Workspace из пользовательского интерфейса Apps Script.

3. Настройка и требования

Прежде чем начать лабораторную работу

  1. Если у вас ещё нет учётной записи Google, необходимо её создать. Используйте личную учётную запись вместо рабочей или учебной. Рабочие и учебные учётные записи могут иметь ограничения, которые не позволят вам включить API, необходимые для этой лабораторной работы.
  2. Войдите в Google Cloud Console .
  3. Включите выставление счетов в Cloud Console.
  1. Создайте новый проект или выберите повторное использование существующего проекта.

Требования к лаборатории

Чтобы получить максимальную пользу от этой лабораторной работы, вам понадобится:

  • Веб-браузер: стандартный веб-браузер, например Chrome (рекомендуется).
  • Выделенное время: выделите достаточно времени, чтобы сосредоточиться на лабораторных занятиях.

4. Настройте свою облачную среду Google

  1. Нажмите значок «Активировать Cloud Shell». 7a0d8a88ebea95af.png : В правом верхнем углу заголовка консоли щелкните значок терминала, на котором при наведении курсора отображается надпись «Активировать Cloud Shell» .
  2. Разрешить .
  3. Дождитесь инициализации: сеанс Cloud Shell откроется в новом фрейме в нижней части окна консоли. Инициализация сеанса займёт несколько минут, так как он подготавливает для вас временную виртуальную машину на базе Debian.
  4. После инициализации сеанса вы увидите приглашение командной строки ( user@cloudshell:~ $ ).
  5. Вы можете развернуть окно Cloud Shell, нажав кнопку «Развернуть», чтобы увеличить размер окна.
  6. Проверьте свой проект: выполните команду: 
gcloud config list project
  1. Измените свой проект (при необходимости): 
gcloud config set project [YOUR_PROJECT_ID]

Все готово к началу лабораторных работ!

5. Настройте локальную среду разработки

В этом задании вы настроите Gemini CLI и его расширения для управления вашими облачными проектами и проектами Apps Script с вашего терминала.

  1. Gemini CLI уже установлен как часть среды Cloud Shell, поэтому нет необходимости его устанавливать.
  2. clasp также уже установлен как часть среды Cloud Shell, однако мы позаботимся о том, чтобы в этой лабораторной работе использовалась последняя версия. 
npm install -g @google/clasp@latest
  1. Разрешите clasp доступ к вашей учетной записи, введя следующую команду и следуя инструкциям ниже: 
clasp login --no-localhost

Нажмите на сгенерированный URL-адрес в терминале, чтобы авторизовать clasp . Используйте учётную запись студенческой лаборатории для входа в систему, и при запросе разрешений выберите «Выбрать все» и нажмите «Продолжить» . После этого должно появиться сообщение об ошибке, подобное приведенному ниже.

db77651c2ce19d7f.png

Скопируйте URL-адрес из окна браузера (который начинается с http://localhost:8888/?code=xxx ), вставьте его в открытый сеанс Cloud Shell и нажмите Enter. clasp продолжит процесс авторизации, и если вход в систему выполнен успешно, вы увидите подтверждение, похожее на You are logged in as user@gmail.com .

  1. Установите застежку расширения Gemini CLI . 
gemini extensions install https://github.com/google/clasp --consent
  1. Установите расширения gcloud Gemini CLI . 
gemini extensions install https://github.com/gemini-cli-extensions/gcloud --consent
  1. Установите расширения Gemini CLI для разработчиков Google Workspace . 
gemini extensions install https://github.com/googleworkspace/developer-tools --consent
  1. Создайте пустой каталог проекта: 
mkdir genai-cat-add-on
  1. Перейдите в каталог только что созданного проекта: 
cd genai-cat-add-on
  1. Настройте файл контекста Gemini CLI для этого проекта: 
cat << 'END_OF_FILE' > GEMINI.md
## **Gemini CLI Instructions for Gmail Add-on Development**

You are a methodical **Google Workspace extensibility and integration expert**. Your goal is to build a Gmail Add-on for the `genai-cat-add-on` project by writing Apps Script code and using command-line tools.

---

## **Tools Available**

*   **`clasp`**: Use this tool for all Apps Script project operations like pushing files.
*   **`gcloud`**: Use this tool for Google Cloud operations, such as enabling APIs or managing IAM permissions.
*   **`workspace-developer`**: Use this tool to search the official Google Workspace documentation for correct syntax, manifest properties, and required OAuth scopes.

---

## **Development Workflow and Validation**

You MUST follow the workflow below when building the add-on:

1.  **Mandatory Documentation Check**: Before creating, committing, or modifying any code (especially manifest files or Apps Script functions), you **MUST** first utilize the **`workspace-developer` tool** and use **search_workspace_docs** to search and validate the necessary Apps Script syntax, OAuth scopes, Apps Script services such as GmailApp, and best practices. Always refer to the official Google Workspace developer documentation via this tool for authoritative information.
2.  **Security and Scopes**: For every code commit or structural change, you must first **verify the manifest file (`appsscript.json`) includes the necessary OAuth scopes** for Gmail access and external API calls, ensuring you use the **minimal required scopes** and nothing more to adhere to the principle of least privilege.
3.  **Versioning/Persistence**: After any successful file creation, update, or deletion, you must ensure the changes are persistently saved and pushed using the appropriate `clasp` tool command.
4.  **Error Handling**: Include appropriate debugging and robust error handling code in all Apps Script functions.

---

## **Project and API Specifications**

* **Project Focus:** All work is centered on the **`genai-cat-add-on`** Apps Script project.
* **Vertex AI Details:** If asked to generate images, you must use the **`gemini-2.5-flash-image`** model on **Vertex AI**. Do NOT use imagen. All Vertex AI operations must use the currently logged-in user's credentials and the current Google Cloud project.
END_OF_FILE
  1. Включите API Google Apps Script в учетной записи вашей студенческой лаборатории, нажмите на API Google Apps Script и переключите его с Выкл . на Вкл .

41eb25a89e13e1ff.gif

6. Запустите и проверьте настройку Gemini CLI.

  1. Запустите Gemini в каталоге вашего проекта. 
gemini
  1. По умолчанию Gemini CLI предлагает вам проверить и принять изменения в файлах. Для этой лабораторной работы мы рекомендуем отключить эту функцию, нажав Shift + Tab, чтобы автоматически принимать изменения и завершить её вовремя. Теперь эта опция на экране должна быть выделена красным цветом.

31a7326896719d73.png

  1. Убедитесь, что файл GEMINI.md был загружен, и покажите, что он загружен в контексте Gemini CLI: 
/memory show
  1. Убедитесь, что серверы MCP настроены правильно. Инициализация сервера MCP gcloud может занять некоторое время, поэтому не беспокойтесь, если он отображается как отключенный. Подождите несколько минут и повторите попытку. 
/mcp list

7. Создайте дополнение Gmail

  1. Попросите Gemini создать нашу первую версию дополнения для Gmail: 
Use Apps Script to create a new Google Workspace add-on that displays a random cat image using the Cat-as-a-Service API upon opening the add-on in Gmail. Make sure you update the code and manifest files, use the correct scopes, and use the API documentation at https://cataas.com/doc.html.

Once done, provide a link to view the project.
  1. Как только Gemini закончит отвечать на ваши запросы, нажмите на предоставленную ссылку или перейдите на домашнюю страницу Apps Script и нажмите на проект genai-cat-add-on .
  2. Нажмите значок «Настройки проекта» (значок шестеренки). 9485fddc5bf46369.png на левой стороне страницы.

2bc043bb3c3a216d.png

  1. Выберите опцию « Показать файл манифеста 'appsscript.json' в редакторе ».

e74dca570d64e540.png 9. Переключитесь на экран редактора и проверьте сгенерированный код в Code.gs и файл манифеста, который настраивает проект в appsscript.json

8. Установите и протестируйте дополнение.

  1. Вернитесь на страницу проекта Apps Script.
  2. Найдите кнопку «Развернуть» вверху.
  3. Нажмите на стрелку рядом с пунктом Развернуть и выберите Тестовые развертывания .
  4. В открывшемся диалоговом окне «Тестовые развертывания» вы увидите опцию установки неопубликованного дополнения.
  5. Нажмите кнопку «Установить» .
  6. Появится сообщение с подтверждением. Нажмите «Готово» внизу, чтобы закрыть диалоговое окно развёртывания.
  7. Откройте и обновите домашнюю страницу Gmail .
  8. Теперь дополнение должно быть доступно. Оно появится на правой боковой панели.
  9. При первом использовании надстройки вам будет предложено предоставить ей доступ к необходимым данным или разрешениям. Следуйте инструкциям на экране, чтобы предоставить разрешения.
  10. Вы должны увидеть изображение кота. Если его нет, устраните неполадку с помощью Gemini CLI, отправив сообщение об ошибке.

9. Реализуйте логику генерации изображений на основе ИИ.

  1. Попросите Gemini теперь добавить логику для создания изображения: 
Now update the add-on to display an AI-generated image using the samples in https://docs.cloud.google.com/vertex-ai/generative-ai/docs/multimodal/image-generation#use-image-generation. 

The image should show a cute cat if I open my inbox, and should add a speech bubble saying "<email sender name> rocks!" with the actual sender name when I open an email.
  1. Обновите домашнюю страницу Gmail и снова откройте дополнение. При необходимости примите любые новые разрешения.
  2. Должно появиться изображение кошки, сгенерированное искусственным интеллектом. Если изображение не отображается, выполните поиск и устранение неполадок с помощью Gemini CLI, отправив сообщение об ошибке и следуя инструкциям.
  3. Откройте электронное письмо и обратите внимание, как изображение изменится, и появится речевой пузырь с именем отправителя. Устраните любые неполадки в Gemini CLI, как описано в предыдущем шаге.

10. [Необязательно] Добавьте раскрывающийся список типов животных.

  1. Попросите Gemini добавить возможность генерации других животных в дополнение к изображению кошки. 
Add a dropdown menu that lets the user choose the type of animal image it wants. Choose 2 random animals to add to the list in addition to the cat image.
  1. Обновите дополнение, нажав на три вертикальные точки и нажав «Обновить», или обновив домашнюю страницу Gmail и снова открыв дополнение.
  2. Протестируйте новую функциональность, выбрав другое изображение животного. Если возникнут ошибки, например, интерфейс не обновится или появится сообщение об ошибке, устраните их с помощью Gemini CLI, отправив сообщение об ошибке и следуя инструкциям.

11. Уборка

Выход из Gemini CLI

Выйдите из Gemini CLI и просмотрите статистику использования, выполнив следующую команду: 

/quit

Удалить проект Google Cloud

Чтобы избежать списания средств с вашего аккаунта Google Cloud за ресурсы, используемые в этой лабораторной работе, мы рекомендуем вам удалить проект Google Cloud. 

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Удалить проект скрипта приложений

Нажмите на dc2524b2c9878567.png значок информации на левой навигационной панели, а затем на 4ad389ddfeda5d7f.png значок корзины на правой стороне экрана, чтобы удалить проект Apps Script.

12. Советы по устранению неполадок

  • Если у вас возникли проблемы с Gemini CLI и расширениями, вы можете использовать следующую команду для запуска определенной рабочей версии Gemini CLI: 
npx https://github.com/google-gemini/gemini-cli#v0.12.0
  • Если вы столкнетесь с какими-либо ошибками, попросите Gemini исправить их и поделитесь ошибками и контекстом (где они происходят).
  • Если Gemini реализует ведение журнала ошибок и просит вас сообщить о любых ошибках, повторно выполните шаги, которые вызвали ошибку, а затем поделитесь результатами с Gemini.
  • Вы можете попробовать ввести следующую подсказку: 
You have my permission to fix any errors. Please go ahead and make it work.
  • Если вы застряли и хотите помочь Близнецам, вы можете воспользоваться следующей подсказкой: 
Use the following Github repo as a reference implementation to make my add-on work: https://github.com/googleworkspace/add-ons-samples/tree/main/apps-script/generative-ai/cat-add-on

13. Поздравляем!

Вы успешно завершили лабораторную работу и использовали Gemini CLI для написания кода дополнения Gmail.

В этой лабораторной работе вы узнали, как:

  • Используйте Gemini CLI.
  • Установите инструменты и расширьте Gemini CLI с помощью серверов MCP (Model Context Protocol).
  • Создайте, разверните и установите дополнение Gmail.

Теперь вы готовы перейти к нашей следующей лабораторной работе.