Скрипт приложений: напишите 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 с расширениями.
• Создайте надстройку для Gmail, которая будет обращаться к внешнему API.
• Измените дополнение таким образом, чтобы оно вызывало API Vertex AI для генерации изображений.
• Разверните тестовую версию надстройки Google Workspace из пользовательского интерфейса Apps Script.

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

Перед началом лабораторной работы

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

⚠️Внимание : В этой лабораторной работе используются платные облачные ресурсы. Чтобы избежать постоянных расходов , выполните действия по очистке в конце лабораторной работы. Новые пользователи могут воспользоваться бесплатной пробной версией стоимостью 300 долларов США .

4. Создайте новый проект или выберите вариант повторного использования существующего проекта.

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

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

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

4. Настройте свою среду Google Cloud.

1. Нажмите на значок «Активировать Cloud Shell». В правом верхнем углу заголовка консоли щелкните значок терминала, на который при наведении курсора отображается надпись «Активировать Cloud Shell» .
2. Авторизовать .
3. Дождитесь инициализации: в новом окне внизу консоли откроется сессия Cloud Shell. Инициализация сессии займет несколько минут, пока будет создана временная виртуальная машина (ВМ) на базе Debian.
4. После инициализации сессии вы увидите приглашение командной строки ( user@cloudshell:~ $ ).
5. Вы можете расширить окно Cloud Shell, нажав на кнопку расширения, чтобы увеличить его размер.
6. Проверьте свой проект: выполните команду:

gcloud config list project

7. Измените свой проект (при необходимости):

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

3. Разрешите Clasp доступ к вашей учетной записи, введя следующую команду и следуя инструкциям ниже:

clasp login --no-localhost

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

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

4. Установите расширения clasp Gemini CLI .

gemini extensions install https://github.com/google/clasp --consent

5. Установите расширения gcloud Gemini CLI .

gemini extensions install https://github.com/gemini-cli-extensions/gcloud --consent

6. Установите расширения Gemini CLI для разработчиков Google Workspace .

gemini extensions install https://github.com/googleworkspace/developer-tools --consent

7. Создайте пустую директорию проекта:

mkdir genai-cat-add-on

8. Перейдите в каталог только что созданного проекта:

cd genai-cat-add-on

9. Настройте файл контекста 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

10. Включите API Google Apps Script в своей учетной записи в студенческой лаборатории, затем щелкните по API Google Apps Script и переключите его из положения «Выкл .» в положение « Вкл.» .

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

1. Запустите Gemini в каталоге вашего проекта.

gemini

⭐ Совет : Если у вас возникнут проблемы при использовании Gemini CLI, вы всегда можете обратиться к советам по устранению неполадок, чтобы запустить конкретную версию Gemini CLI.

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

3. Убедитесь, что файл GEMINI.md был загружен, и отобразите, что именно он загружает в контексте командной строки Gemini:

/memory show

4. Убедитесь, что серверы MCP настроены правильно. Инициализация сервера gcloud MCP может занять некоторое время, поэтому не пугайтесь, если он отображается как отключенный. Подождите несколько минут и попробуйте снова.

/mcp list

ℹ️Примечание : В процессе выполнения следующих шагов Gemini CLI запросит разрешение на использование определенных инструментов, необходимых для работы в лаборатории. Вам следует разрешить запуск всех инструментов.

7. Создайте надстройку для Gmail.

5. Обратитесь к 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.

❗Важно : Gemini CLI запросит у вас разрешение на выполнение любых инструментов или расширений MCP, и вы можете продолжить, разрешив ему всегда запрашивать разрешение на использование инструментов с сервера/расширения, о котором он спрашивает.

6. После того, как Gemini ответит на ваш запрос, нажмите на предоставленную ссылку или перейдите на главную страницу Apps Script и щелкните проект genai-cat-add-on .
7. Нажмите на значок «Настройки проекта» (значок шестеренки). в левой части страницы.

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

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.

2. Обновите главную страницу Gmail и снова откройте дополнение. При необходимости предоставьте все необходимые разрешения.
3. Теперь должно отобразиться сгенерированное ИИ изображение кошки. Если изображение не отображается, выполните диагностику с помощью Gemini CLI, отправив сообщение об ошибке и следуя его инструкциям.
4. Откройте электронное письмо и обратите внимание, как изображение меняется, отображая облачко с именем отправителя. Устраните любые проблемы с 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.

2. Чтобы обновить дополнение, нажмите на три вертикальные точки и выберите «Обновить», либо обновите главную страницу Gmail и снова откройте дополнение.
3. Проверьте новые функции, выбрав другое изображение животного. Если возникнут ошибки, например, интерфейс пользователя не обновится или появится сообщение об ошибке, выполните диагностику с помощью Gemini CLI, отправив сообщение об ошибке и следуя его инструкциям.

11. Уборка

Выход из Gemini CLI

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

/quit

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

⚠️Внимание : Удаление этого проекта Google Cloud приведет к безвозвратному уничтожению всех его ресурсов, включая любую работу, не связанную с этим практическим заданием. Кроме того, вы не сможете повторно использовать этот пользовательский идентификатор проекта в будущем. Чтобы сохранить идентификатор, удаляйте только конкретные ресурсы, созданные в ходе этого задания, а не весь проект целиком.

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

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Проект Delete Apps Script

⚠️Внимание : Удаление этого проекта Apps Script приведет к безвозвратному удалению всех содержащихся в нем файлов и уничтожению всех активных развертываний. Если вы использовали существующий проект для этого практического занятия, это действие также удалит вашу предыдущую работу. Чтобы сохранить ваши развертывания для будущего использования, мы рекомендуем вручную удалять отдельные ресурсы внутри проекта, а не удалять проект полностью.

Нажмите на значок информации в левой панели навигации, а затем на Значок корзины в правой части экрана позволяет удалить проект 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 с помощью vibe-code.

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

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

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