Apps Script: Napisz w Vibe-code dodatek do Gmaila z interfejsem wiersza poleceń Gemini i serwerami MCP

1. Przegląd

W tym module nauczysz się nowoczesnego, opartego na AI przepływu pracy, który pozwoli Ci od podstaw stworzyć dynamiczny dodatek do Gmaila. Do koordynowania zaawansowanego lokalnego środowiska programistycznego będziesz używać interfejsu wiersza poleceń Gemini. Będziesz korzystać z serwerów MCP (Model Context Protocol) i rozszerzeń interfejsu wiersza poleceń Gemini, aby zintegrować narzędzia takie jak gcloud i clasp.

Utworzony dodatek będzie generować i wyświetlać na żądanie unikalny obraz kota, wywołując model obrazu na platformie Vertex AI w Google Cloud.

Na koniec będziesz mieć w pełni funkcjonalny dodatek do Gmaila, który wywołuje interfejs Vertex AI API, aby generować unikalne obrazy bezpośrednio w interfejsie Gmaila. Wszystko to będzie zarządzane z lokalnej linii poleceń.

2. Czego się nauczysz

Po ukończeniu tego modułu nauczysz się:

• Konfigurowanie i korzystanie z interfejsu wiersza poleceń Gemini z rozszerzeniami
• Tworzenie dodatku do Gmaila, który wywołuje zewnętrzny interfejs API
• Zmodyfikuj dodatek, aby wywoływał interfejs Vertex AI API w celu generowania obrazów.
• Wdrażanie wersji testowej dodatku do Google Workspace z interfejsu Apps Script

3. Konfiguracja i wymagania

Zanim rozpoczniesz moduł

1. Jeśli nie masz jeszcze konta Google, musisz je utworzyć. Używaj konta osobistego zamiast konta służbowego lub szkolnego. Konta służbowe i szkolne mogą mieć ograniczenia, które uniemożliwiają włączenie interfejsów API potrzebnych w tym module.
2. Zaloguj się w konsoli Google Cloud.
3. Włącz płatności w konsoli Google Cloud.

⚠️ Uwaga: ten moduł korzysta z płatnych zasobów chmurowych. Aby uniknąć bieżących opłat, wykonaj czynności opisane na końcu modułu. Nowi użytkownicy mogą skorzystać z bezpłatnego okresu próbnego, w którym mają do dyspozycji środki w wysokości 300 USD.

4. Utwórz nowy projekt lub użyj już istniejącego.

Wymagania dotyczące modułu

Aby w pełni wykorzystać możliwości tego modułu, musisz mieć:

• Przeglądarka: standardowa przeglądarka, np. Chrome (zalecana).
• Wyznaczony czas: zarezerwuj wystarczająco dużo czasu, aby skupić się na ćwiczeniach w laboratorium.

4. Konfigurowanie środowiska Google Cloud

1. Kliknij ikonę Aktywuj Cloud Shell : w prawym górnym rogu nagłówka konsoli kliknij ikonę terminala, która po najechaniu na nią kursorem wyświetla napis „Aktywuj Cloud Shell”.
2. Autoryzuj.
3. Poczekaj na inicjowanie: sesja Cloud Shell otworzy się w nowej ramce u dołu okna konsoli. Inicjowanie sesji może potrwać kilka minut, ponieważ udostępniana jest tymczasowa maszyna wirtualna oparta na Debianie.
4. Gdy sesja zostanie zainicjowana, zobaczysz znak zachęty wiersza poleceń (user@cloudshell:~ $).
5. Możesz powiększyć okno Cloud Shell, klikając przycisk rozwijania.
6. Sprawdź projekt: uruchom polecenie:

gcloud config list project

7. Zmień projekt (w razie potrzeby):

gcloud config set project [YOUR_PROJECT_ID]

Możesz już rozpocząć ćwiczenia w module.

5. Konfigurowanie lokalnego środowiska programistycznego

W tym zadaniu skonfigurujesz interfejs wiersza poleceń Gemini i jego rozszerzenia, aby zarządzać projektami w chmurze i Apps Script z terminala.

1. Interfejs wiersza poleceń Gemini jest już zainstalowany w środowisku Cloud Shell, więc nie musisz go instalować.
2. clasp jest już zainstalowany w środowisku Cloud Shell, ale w tym module sprawdzimy, czy używamy najnowszej wersji.

npm install -g @google/clasp@latest

3. Aby autoryzować dostęp clasp do Twojego konta, wpisz to polecenie i postępuj zgodnie z instrukcjami poniżej:

clasp login --no-localhost

Kliknij wygenerowany adres URL w terminalu, aby autoryzować clasp. Zaloguj się na konto laboratorium studenckiego, a gdy pojawi się prośba o udzielenie zgód, kliknij Wybierz wszystkie i Dalej. Powinien wyświetlić się komunikat o błędzie podobny do tego poniżej.

Skopiuj adres URL z okna przeglądarki (rozpoczynający się od http://localhost:8888/?code=xxx) i wklej go w otwartej sesji Cloud Shell, a następnie naciśnij Enter. clasp będzie kontynuować proces autoryzacji. Jeśli logowanie się powiedzie, zobaczysz potwierdzenie podobne do You are logged in as [e-mail].

4. Zainstaluj rozszerzenia interfejsu wiersza poleceń clasp Gemini.

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

5. Zainstaluj gcloud rozszerzenia interfejsu wiersza poleceń Gemini.

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

6. Zainstaluj rozszerzenia interfejsu wiersza poleceń Gemini dla deweloperów Google Workspace.

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

7. Utwórz pusty katalog projektu:

mkdir genai-cat-add-on

8. Przejdź do nowo utworzonego katalogu projektu:

cd genai-cat-add-on

9. Skonfiguruj plik kontekstu interfejsu wiersza poleceń Gemini dla tego projektu:

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. Włącz interfejs Google Apps Script API na koncie laboratorium studenckiego. Kliknij interfejs Google Apps Script API i przełącz go z Wyłączony na Włączony.

6. Rozpoczynanie i weryfikowanie konfiguracji interfejsu wiersza poleceń Gemini

1. Uruchom Gemini w katalogu projektu.

gemini

⭐ Wskazówka: jeśli podczas korzystania z interfejsu wiersza poleceń Gemini napotkasz problemy, możesz zawsze skorzystać z porad dotyczących rozwiązywania problemów, aby uruchomić konkretną wersję interfejsu wiersza poleceń Gemini.

2. Domyślnie interfejs wiersza poleceń Gemini poprosi Cię o sprawdzenie i zaakceptowanie zmian w plikach. W tym laboratorium zalecamy wyłączenie tej funkcji. Wciśnij Shift + Tab, aby automatycznie zaakceptować zmiany i zdążyć z wykonaniem zadania. Ta opcja powinna być teraz wyróżniona na ekranie na czerwono.

3. Sprawdź, czy plik GEMINI.md został wczytany, i wyświetl, w jakim kontekście wiersza poleceń Gemini został on wczytany:

/memory show

4. Sprawdź, czy serwery MCP są prawidłowo skonfigurowane. Serwer gcloud MCP może potrzebować trochę czasu na zainicjowanie, więc nie martw się, jeśli wyświetla się jako odłączony. Poczekaj kilka minut i spróbuj ponownie.

/mcp list

ℹ️ Uwaga: podczas wykonywania kolejnych kroków interfejs wiersza poleceń Gemini poprosi Cię o zezwolenie na używanie niektórych narzędzi wymaganych w tym module. Powinieneś(-aś) przyznać mu uprawnienia do uruchamiania wszystkich narzędzi.

7. Tworzenie dodatku do Gmaila

5. Poproś Gemini o utworzenie pierwszej wersji dodatku do Gmaila:

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.

❗Ważne: interfejs CLI Gemini poprosi Cię o zezwolenie na wykonanie dowolnych narzędzi lub rozszerzeń MCP. Możesz zezwolić na zawsze na narzędzia z serwera lub rozszerzenia, o które pyta.

6. Gdy Gemini skończy odpowiadać na prompta, kliknij podany link lub przejdź na stronę główną Apps Script i kliknij projekt genai-cat-add-on.
7. Po lewej stronie kliknij ikonę Ustawienia projektu (ikona koła zębatego) .

8. Wybierz opcję „Wyświetlaj plik manifestu „appsscript.json” w edytorze”.

9. Przejdź do ekranu Edytor i sprawdź wygenerowany kod w Code.gs oraz plik manifestu, który konfiguruje projekt w appsscript.json.

8. Instalowanie i testowanie dodatku

1. Wróć na stronę projektu Apps Script.
2. U góry znajdź przycisk Wdróż.
3. Kliknij strzałkę obok opcji Wdróż i wybierz Test deployments (Testowe wdrożenia).
4. W wyświetlonym oknie dialogowym „Test deployments” (Testowe wdrożenia) powinna być widoczna opcja instalacji nieopublikowanego dodatku.
5. Kliknij przycisk Zainstaluj.
6. Pojawi się komunikat z prośbą o potwierdzenie. Aby zamknąć okno wdrażania, kliknij u dołu Gotowe.
7. Otwórz i odśwież stronę główną Gmaila.
8. Dodatek powinien być teraz dostępny. Dodatek pojawi się w panelu po prawej stronie.
9. Gdy po raz pierwszy użyjesz dodatku, pojawi się prośba o przyznanie mu uprawnień dostępu do niezbędnych danych. Aby przyznać uprawnienia, postępuj zgodnie z instrukcjami wyświetlanymi na ekranie.
10. Powinien pojawić się obraz kota. Jeśli tak się nie stanie, rozwiąż problem za pomocą interfejsu wiersza poleceń Gemini, udostępniając komunikat o błędzie.

9. Wdrażanie logiki generowania obrazów AI

1. Poproś Gemini o dodanie logiki do generowania obrazu:

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. Odśwież stronę główną Gmaila i ponownie otwórz dodatek. W razie potrzeby zaakceptuj nowe uprawnienia.
3. Powinien pojawić się obraz kota wygenerowany przez AI. Jeśli obraz się nie wyświetla, rozwiąż problem za pomocą interfejsu Gemini CLI, udostępniając komunikat o błędzie i postępując zgodnie z instrukcjami.
4. Otwórz e-maila i zobacz, jak obraz zmienia się w dymek z nazwą nadawcy. Rozwiąż problemy z interfejsem wiersza poleceń Gemini podobnie jak w poprzednim kroku.

10. [Opcjonalnie] Dodaj menu wyboru typu zwierzęcia

1. Poproś Gemini o dodanie opcji generowania innych zwierząt oprócz obrazu kota.

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. Odśwież dodatek, klikając 3 pionowe kropki i wybierając Odśwież lub odświeżając stronę główną Gmaila i ponownie otwierając dodatek.
3. Przetestuj nową funkcję, wybierając inne zdjęcie zwierzęcia. Jeśli wystąpią błędy, np. interfejs nie będzie się odświeżać lub pojawi się komunikat o błędzie, rozwiąż problem za pomocą interfejsu wiersza poleceń Gemini. W tym celu udostępnij komunikat o błędzie i postępuj zgodnie z instrukcjami.

11. Czyszczenie danych

Zamykanie interfejsu wiersza poleceń Gemini

Zamknij interfejs Gemini CLI i wyświetl statystyki wykorzystania, wpisując to polecenie:

/quit

Usuwanie projektu Google Cloud

⚠️ Ostrzeżenie: usunięcie tego projektu Google Cloud spowoduje trwałe usunięcie wszystkich zasobów w nim zawartych, w tym wszystkich elementów niezwiązanych z tym modułem. Nie będzie też można ponownie użyć tego niestandardowego identyfikatora projektu w przyszłości. Aby zachować identyfikator, usuń tylko konkretne zasoby utworzone w ramach tego modułu, a nie cały projekt.

Aby uniknąć obciążenia konta Google Cloud opłatami za zasoby użyte w tym ćwiczeniu, zalecamy usunięcie projektu Google Cloud.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Usuwanie projektu Apps Script

⚠️ Uwaga: usunięcie tego projektu Apps Script spowoduje trwałe usunięcie wszystkich zawartych w nim plików i zniszczenie wszystkich aktywnych wdrożeń. Jeśli w tym samouczku używasz istniejącego projektu, ta czynność spowoduje też usunięcie poprzednich prac. Aby zachować wdrożenia do wykorzystania w przyszłości, zalecamy ręczne usuwanie poszczególnych zasobów w projekcie zamiast usuwania całego projektu.

W panelu nawigacyjnym po lewej stronie kliknij ikonę informacji , a następnie ikonę kosza  po prawej stronie ekranu, aby usunąć projekt Apps Script.

12. Wskazówki dotyczące rozwiązywania problemów

• Jeśli masz problemy z interfejsem wiersza poleceń Gemini i rozszerzeniami, możesz użyć tego polecenia, aby uruchomić konkretną działającą wersję interfejsu wiersza poleceń Gemini:

npx https://github.com/google-gemini/gemini-cli#v0.12.0

• Jeśli napotkasz jakieś błędy, poproś Gemini o ich naprawienie i udostępnij błędy oraz kontekst (gdzie występują).
• Jeśli Gemini wdroży rejestrowanie błędów i poprosi Cię o udostępnienie informacji o błędach, ponownie wykonaj czynności, które powodowały błąd, a następnie udostępnij wyniki Gemini.
• Możesz wypróbować prompta w tym stylu:

You have my permission to fix any errors. Please go ahead and make it work.

• Jeśli utkniesz i chcesz pomóc Gemini, możesz użyć tego prompta:

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. Gratulacje!

Udało Ci się ukończyć ćwiczenie i użyć interfejsu wiersza poleceń Gemini do wygenerowania kodu dodatku do Gmaila.

Z tego modułu dowiedziałeś(-aś) się, jak:

• Korzystanie z interfejsu wiersza poleceń Gemini.
• Instaluj narzędzia i rozszerzaj interfejs wiersza poleceń Gemini za pomocą serwerów MCP (Model Context Protocol).
• Tworzenie, wdrażanie i instalowanie dodatku do Gmaila.

Możesz teraz przejść do następnego modułu.