1. Wprowadzenie
W tym ćwiczeniu utworzysz CloudCrush, grę zręcznościową typu „dopasuj 3”, przy użyciu Gemini 3 i interfejsu wiersza poleceń Gemini, naszego agenta do kodowania w wierszu poleceń. Gra zostanie napisana w języku Go i wdrożona w Google Cloud za pomocą Cloud Run.
Głównym celem tego ćwiczenia jest zdobycie umiejętności koordynowania pracy agenta, aby tworzył aplikacje za Ciebie, zamiast ręcznie pisać kod. Wszystkie zadania związane z programowaniem możesz przekazać interfejsowi wiersza poleceń Gemini, nawet jeśli wcześniej nie korzystałeś(-aś) z tych technologii.
To ćwiczenie jest przeznaczone dla średnio zaawansowanych programistów, którzy chcą poznać przepływy pracy związane z kodowaniem agentowym. Szacowany łączny czas trwania tego modułu to 60 minut. Zasoby utworzone w tym ćwiczeniu korzystają z modelu cenowego opartego na wykorzystaniu.
Jakie zadania wykonasz
- Stwórz podstawową logikę gry typu „match 3” za pomocą języka Go i platformy Ebitengine.
- Dostosuj grę do uruchamiania w przeglądarce za pomocą WebAssembly (WASM).
- Wdróż grę i jej interfejs API wyników w Cloud Run.
- Orkiestracja wyspecjalizowanych sub-agentów i rozszerzeń na potrzeby testowania i inspekcji kodu
Wymagania wstępne
- Podstawowa znajomość języków programowania
- Podstawowa wiedza o infrastrukturze w chmurze
- Podstawowa znajomość konsoli Google Cloud
Czego się nauczysz
- Jak współpracować z agentem do kodowania przy tworzeniu złożonych aplikacji
- Jak korzystać z Gemini w kontekście multimodalnym
- Jak wdrażać aplikacje w chmurze za pomocą Cloud Run
Czego potrzebujesz
Te warsztaty można w całości przeprowadzić w chmurze za pomocą Cloud Shell, ale jeśli wolisz używać komputera lokalnego, potrzebujesz tych elementów:
- interfejs wiersza poleceń Gemini. Pobierz i zainstaluj go, postępując zgodnie z instrukcjami na stronie geminicli.com.
- Łańcuch narzędzi Go (wersja 1.26 lub nowsza). Pobierz i zainstaluj go, postępując zgodnie z instrukcjami na stronie go.dev.
- gcloud CLI do interakcji z Google Cloud; Pobierz i zainstaluj go, postępując zgodnie z instrukcjami w dokumentacji Google Cloud.
- Konto rozliczeniowe Google Cloud (do wdrożenia gry w chmurze).
Kluczowe technologie
Więcej informacji o technologiach, z których będziemy korzystać, znajdziesz tutaj:
- Interfejs wiersza poleceń Gemini: agent do programowania
- Gemini 3: najnowsza wersja naszego zaawansowanego dużego modelu językowego
2. Konfiguracja środowiska
Konfigurowanie projektu
Tworzenie projektu Google Cloud
- W konsoli Google Cloud na stronie selektora projektu wybierz lub utwórz projekt w chmurze Google.
- Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności.
Uruchamianie Cloud Shell
Cloud Shell to środowisko wiersza poleceń działające w Google Cloud, które zawiera niezbędne narzędzia.
- Kliknij Aktywuj Cloud Shell u góry konsoli Google Cloud.
- Po połączeniu z Cloud Shell sprawdź uwierzytelnianie:
gcloud auth list - Sprawdź, czy projekt jest skonfigurowany:
gcloud config get project - Jeśli projekt nie jest ustawiony zgodnie z oczekiwaniami, ustaw go:
export PROJECT_ID=<YOUR_PROJECT_ID> gcloud config set project $PROJECT_ID
3. Konfiguracja projektu
Tworzenie katalogu projektu
Najpierw musimy utworzyć nowy katalog dla Twojego projektu. W terminalu uruchom te polecenia:
mkdir -p codelab-match3 && cd codelab-match3
Uruchom interfejs wiersza poleceń Gemini
Najpierw sprawdźmy, czy interfejs wiersza poleceń Gemini został prawidłowo zainstalowany. Uruchom w terminalu:
gemini --version
Powinien pojawić się ekran podobny do tego:
$ gemini --version 0.37.1
Teraz uruchom interfejs wiersza poleceń Gemini za pomocą polecenia gemini:
gemini
Powinien pojawić się prompt interfejsu wiersza poleceń Gemini:
Jeśli widzisz prompt interfejsu wiersza poleceń Gemini, wszystko jest w porządku. Jeśli nie, sprawdź, czy nie pominięto żadnego z poprzednich kroków konfiguracji.
Włącz sterowanie modelem
Sterowanie modelem to funkcja, która umożliwia dodawanie dodatkowego kontekstu do agenta, gdy ten nadal pracuje nad danym zadaniem. Możesz go używać, aby korygować działanie agenta, gdy zauważysz, że zmierza w złym kierunku, dodawać informacje wyjaśniające, aby ulepszyć jego odpowiedź, lub uwzględniać drobne funkcje, które zostały pominięte w pierwotnym promcie.
Aby włączyć sterowanie modelem, otwórz menu ustawień za pomocą polecenia /settings i w polu wyszukiwania wpisz „steering”. Następnie ustaw opcję Włącz sterowanie modelem na wartość „true”.
Aby zmiana została zastosowana, może być konieczne ponowne uruchomienie interfejsu wiersza poleceń (naciśnij klawisz „r”).
Pobieranie komponentów
Musimy pobrać obrazy, które będą używane w grze. Pliki są przechowywane w repozytorium GitHub tutaj. Możesz pobrać je ręcznie lub poprosić o to Gemini, używając tego prompta:
Create a folder named "assets" and download the images
background.png, gcp_sprites.png, gemini.png and logo.png,
from this GitHub repository to the "assets" folder:
https://github.com/GoogleCloudPlatform/devrel-demos/tree/main/codelabs/gemini-cli/gemini-cli-match3-golang
4. Tworzenie gry w trybie planowania i sterowania modelem
Zacznij od stworzenia podstawowej logiki gry typu „dopasuj 3”. Jest to złożone zadanie, dlatego najlepiej użyć interfejsu wiersza poleceń Gemini w trybie planowania, aby skoordynować proces tworzenia.
Przełącz tryb planowania za pomocą polecenia po ukośniku /plan w prompcie interfejsu wiersza poleceń Gemini:
/plan
Po włączeniu trybu planowania skopiuj i wklej do interfejsu wiersza poleceń Gemini ten prompt:
Build a Match-3 game called 'Cloud Crush' in Go using Ebitengine v2.
The entire game screen should have background.png as background.
The play area should be an 8x8 grid with white background.
On the right side of the play area include a side panel with UI elements
like player score and how to play instructions.
The side panel should have a solid background colour to help with readability of the UI.
Use standard GCP product logos (e.g. Compute Engine, Cloud Storage, BigQuery, etc.)
as icons. These icons are provided in the gcp_sprites.png file.
The icons are saved as 64x64 sprites but scale them as necessary
based on the screen resolution. Implement swapping, clearing 3+ gems, and gravity.
Use ebitengine native font rendering (size 48 for titles and size
24 for normal text) for all text and not the debug print.
The font should be monospaced (golang.org/x/image/font/gofont/gomono).
Keep the UI tidy and harmonic, e.g. centered text should always be
adjusted based on text length, not just guess based on estimates.
Przed wygenerowaniem planu interfejs wiersza poleceń Gemini może zadać Ci kilka pytań wyjaśniających.
Na przykład tutaj pyta, czy wolisz aplikację z jednym plikiem czy z wieloma:
A tutaj pyta o nasze preferencje dotyczące animacji:
Ostatnie pytanie dotyczy osadzania zasobów w samym pliku binarnym za pomocą go:embed:
Po udzieleniu odpowiedzi na wszystkie pytania możesz je jeszcze raz sprawdzić, zanim naciśniesz Enter, aby przesłać formularz.
Po zakończeniu planu pojawi się prośba o jego sprawdzenie:
U dołu okna opinii możesz zaakceptować plan w obecnej formie lub dodać swoje uwagi.
Skorzystaj z tej możliwości, aby dodać nowy wymóg, który został pominięty w pierwotnym promcie:
Add a 60-seconds countdown timer and an in-memory high-score tracker
to enhance the arcade game experience.
Combos should give a score bonus of 10% per combo number.
Po raz ostatni pojawi się prośba o potwierdzenie planu wdrożenia:
Naciśnij Enter, aby agent rozpoczął pracę. Agent opuści teraz tryb planowania i zacznie pisać kod.
W tym momencie zwykle musielibyśmy poczekać na zakończenie działania lub przerwać je klawiszem ESC, jeśli chcielibyśmy wprowadzić zmiany w implementacji. Jednak ponieważ mamy włączone sterowanie modelem, możemy umieścić w kolejce instrukcje, aby skorygować działanie modelu.
Gdy agent pracuje, wklej w oknie czatu agenta ten tekst, aby zademonstrować funkcję „sterowania modelem” i pokazać, jak można kolejkować polecenia, aby zmienić kierunek wdrożenia:
Update the implementation to include: 'Q' to quit, 'F' for full-screen
and 'A' for Accessibility Mode: swap GCP logos for high-contrast coloured blocks.
Also enable Arrow Keys to move the selection cursor and Space to select the gem to
swap (space is pressed once to select, then arrow key immediately makes
the move - no need to press space again).
Use a golden square (4 px border, transparent fill) with a simple animation
to highlight where the cursor is at the moment.
Zobaczysz, że prompt jest w kolejce jako „wskazówka sterująca”:
Zaakceptuj plan i obserwuj, jak agent realizuje wszystkie Twoje wymagania.
Gdy agent zakończy wdrażanie, uruchom go run main.go w folderze projektu, aby zaprezentować wersję komputerową. Aby uruchomić to polecenie, nie musisz opuszczać interfejsu wiersza poleceń Gemini. Wpisz ! (wykrzyknik), aby przejść do trybu powłoki i uruchomić polecenie:
Zaletą uruchamiania w trybie powłoki jest to, że wszelkie problemy, które mogą wystąpić, są natychmiast rejestrowane w kontekście agenta. Na przykład w tym przypadku agent zapomniał pobrać niektóre zależności:
Aby wyjść z trybu powłoki, naciśnij klawisz Escape, a następnie poproś agenta o sprawdzenie i naprawienie błędu:
Wynik powinien wyglądać podobnie do tego:
Zagraj w grę i dostosuj jej parametry, aż będziesz zadowolony(-a) z wyniku (np.przyspiesz lub spowolnij animację, dostosuj reakcję na polecenia itp.).
5. dostosować grę do działania w przeglądarce,
Utworzona właśnie gra Ebitengine to aplikacja na komputery. Aby umożliwić jego działanie w internecie, możemy przekonwertować go na WebAssembly.
Aby poprowadzić agenta, użyj tego promptu:
We need to enable this game to run on a web browser. Compile the game to WASM
and create a Go web server to serve the compiled WASM and the assets.
Gdy agent wykona zadanie, możesz polecić mu uruchomienie serwera gry w tle.
Procesami w tle możesz zarządzać za pomocą kombinacji klawiszy Ctrl+B:
Aby zamknąć to okno, naciśnij ponownie Ctrl+B.
Teraz otwórz w przeglądarce adres http://localhost:8080, aby zobaczyć grę działającą w internecie:
Teraz, gdy działa już w internecie, wystarczy ją dopracować przed wdrożeniem w chmurze.
6. Tworzenie ekranu tytułowego i tabeli wyników
Gra działa, ale brakuje w niej kilku kluczowych funkcji, które zapewniają odpowiednie wrażenia z gry na automatach. Najpierw dodaj ekran tytułowy, a potem tablicę wyników, aby móc rywalizować ze znajomymi.
Rozwiąż oba problemy za pomocą tego prompta:
Create a title screen that displays the game logo (logo.png) over the cloud background.
The logo should be centered and occupy no more than 75% of the screen area.
The title screen should display "Press ENTER to play" (black/bold) right below the logo,
with every letter animated in a slow wavy (cosine) pattern.
Once the player presses ENTER, it should be prompted to add their name, which
will then be recorded to populate the leaderboard at the end of the round.
Once the game is over, play the animated leaderboard with the top 10 highest scores.
The animated leaderboard should render entries one by one up to 10 entries,
using a fade in effect just like old school arcade games. The leaderboard
should fade out to the title screen after 15 seconds.
Please note that name entry should be processed independently of the play state
key handlers (e.g. pressing A during name entry should not toggle accessibility mode).
Oto przykład ekranu tytułowego:
Zaczyna to wyglądać bardziej profesjonalnie. 🙂
7. Wdrażanie gry w Cloud Run
Nadszedł czas, aby podzielić się naszym dziełem ze światem. Wdróż grę w Google Cloud Run, aby mieć do niej dostęp z dowolnego miejsca.
Use the gcloud CLI to provision and deploy the Go web server and its assets to
Google Cloud Run. Provide the live URL when complete.
Skoro gra jest już dostępna w chmurze, byłoby szkoda nie umożliwić jej uruchamiania na urządzeniach mobilnych. Możesz to zrobić za pomocą tego prompta:
Now enable this game to run on mobile devices. You need to update the input
system to handle "taps" as well as key presses and clicks. Since mobile devices
most likely won't have a keyboard, add a button to generate a random name and
a confirmation button to the name entry.
Also generate a QR code for the CloudRun link and display it on the screen so
that people can scan it to access the mobile version and compete against their
friends for the high score.
Uruchom grę ponownie w przeglądarce. Spróbuj też uzyskać dostęp do gry na urządzeniu mobilnym za pomocą kodu QR.
8. Testowanie gry za pomocą agenta przeglądarki
W interfejsie wiersza poleceń Gemini subagent to odizolowana persona z nowym kontekstem, która idealnie nadaje się do długotrwałych lub wymagających dużej precyzji zadań, w których nie chcesz, aby bieżący kontekst wpływał na wyniki.
Gry są trudne do testowania za pomocą konwencjonalnych narzędzi testowych (np. testów jednostkowych i integracyjnych), ale możemy użyć agenta przeglądarki, aby przeprowadzić niektóre testy. Agent przeglądarki może uruchomić własną przeglądarkę Chrome i poruszać się po ekranach gry, wydając polecenia DOM. Może też robić zrzuty ekranu, które możemy wykorzystać do udokumentowania testu, a także przekazać agentowi, aby później wprowadził drobne poprawki w interfejsie.
Agent przeglądarki jest obecnie w fazie eksperymentalnej, więc musimy go najpierw włączyć. Wpisz ten prompt w interfejsie wiersza poleceń Gemini, aby włączyć agenta na poziomie projektu.
Create a .gemini/settings.json file with the following content to
configure the browser sub agent:
{
"agents": {
"overrides": {
"browser_agent": {
"enabled": true
}
}
}
}
Aby zastosować tę zmianę, musisz ponownie uruchomić agenta. Zapisz bieżącą rozmowę za pomocą polecenia /chat save:
Zamknij interfejs wiersza poleceń Gemini, naciskając dwukrotnie Ctrl+D, a następnie uruchom go ponownie. Przywróć rozmowę z użytkownikiem /chat resume cloud-crush.
Powinien być teraz dostępny agent przeglądarki. Jeśli chcesz przekazać zadanie agentowi przeglądarki, możesz o tym wspomnieć, używając symbolu @browser_agent:
Teraz użyj agenta przeglądarki, aby ocenić wdrożoną grę:
@browser_agent perform an end-to-end test of the Cloud Run deployment URL.
Navigate the homepage, start a game, submit a score, and verify the new score
appears correctly on the leaderboard. Take screenshots to show each step of the
investigation and save to ./screenshots.
Powinien pojawić się ekran potwierdzenia:
Po wyrażeniu zgody na dostęp do agenta i wymaganych narzędzi powinno otworzyć się nowe okno przeglądarki Chrome. Jest to przeglądarka kontrolowana przez agenta. Wizualnym sygnałem będzie niebieskie obramowanie ekranu i komunikat u dołu „interfejs wiersza poleceń Gemini steruje tą przeglądarką”:
Po zakończeniu pojawi się komunikat podobny do tego:
Oto kilka zrzutów ekranu wykonanych przez agenta przeglądarki:
title_screen.png:
game_board.png:
Teraz jest dobry moment, aby użyć jednego ze zdjęć zrobionych przez agenta do optymalizacji interfejsu gry. Na przykład możesz powiedzieć:
Analyse the screenshot @screenshots/game_board.png and adjust the side panel to
have better contrast and be more harmonic with the rest of UI elements. Focus
on readability and color theory to achieve the best possible visuals.
9. Tworzenie agenta niestandardowego do zabezpieczania gry
Jednym z częstych problemów związanych z aplikacjami „zakodowanymi w określonym stylu” jest utrzymanie wysokiej jakości i najlepszych praktyk zarówno z perspektywy kodowania, jak i bezpieczeństwa. Możesz spróbować ulepszyć prompty, aby były bardzo rygorystyczne w obu tych aspektach, ale im więcej dodasz do promptu, tym mniej skoncentrowany będzie agent, co często prowadzi do suboptymalnych wyników. W takim przypadku idealne jest użycie subagentów, ponieważ działają oni w innym kontekście niż główny agent i mogą się skupić na powierzonym im zadaniu. Utwórzmy niestandardowego agenta, który przeprowadzi audyt bezpieczeństwa tego kodu i sprawdzi, czy nie wyciekają żadne dane logowania ani czy nie narażamy się na niepotrzebne ryzyko podczas wdrażania tej gry w Cloud Run.
Create a new custom agent in .gemini/agents/security_auditor.md using the following content:
---
name: security_auditor
description: Specialized in finding security vulnerabilities in code.
kind: local
tools:
- read_file
- grep_search
model: gemini-3-flash-preview
temperature: 0.2
max_turns: 10
---
You are a ruthless Security Auditor. Your job is to analyze code for potential
vulnerabilities.
Focus on:
1. SQL Injection
2. XSS (Cross-Site Scripting)
3. Hardcoded credentials
4. Unsafe file operations
When you find a vulnerability, explain it clearly and suggest a fix. Do not fix
it yourself; just report it.
Aby zmiana zaczęła obowiązywać, musisz ponownie uruchomić interfejs CLI. Zapisz sesję czatu za pomocą /chat save i wznów ją za pomocą /chat resume, tak jak wcześniej.
Po wznowieniu działania interfejsu CLI automatycznie wykryje on nowego agenta podczas uruchamiania:
Kliknij Acknowledge and Enable, a następnie poproś agenta o przeprowadzenie kontroli bezpieczeństwa kodu gry, używając tego prompta:
@security-auditor please run a security audit on this code and cloud run
deployment to make sure it is safe against common attack patterns and that it is
not leaking any credentials
Powinien pojawić się ekran podobny do tego:
Po zakończeniu audytu przedstawi rekomendacje. W tym przykładzie wykryto kilka ważnych elementów do poprawy:
Jeśli znajdziesz jakieś wyniki, po prostu zapytaj interfejs wiersza poleceń Gemini o ich rozwiązanie. 🙂
10. Podsumowanie
Gratulacje! Udało Ci się użyć interfejsu wiersza poleceń Gemini do utworzenia, wdrożenia, przetestowania i sprawdzenia gry zręcznościowej, co pokazuje zaawansowane przepływy pracy oparte na agentach od początkowego szkieletu po wdrożenie.
Czyszczenie
Jeśli nie planujesz wrócić do tego ćwiczenia z programowania, najlepiej usunąć zasoby utworzone podczas niego.
- Usuń usługę Cloud Run:
Poproś interfejs wiersza poleceń Gemini o usunięcie go:
I'm finished with this project. Delete the cloud run deployment.
- Usuń katalog projektu:
cd .. && rm -rf codelab-match3
Możesz też usunąć cały projekt w chmurze Google, jeśli został utworzony wyłącznie na potrzeby tego ćwiczenia.
Dalsze kroki
Możesz kontynuować naukę, zapoznając się z innymi modułami Codelabs na tej platformie lub samodzielnie ulepszając Cloud Crush.
Kilka sugestii dotyczących ulepszenia gry:
- Dodaj specjalny klejnot „Gemini” (używając pliku gemini.png), który pojawia się po dopasowaniu co najmniej 4 klejnotów. Dopasowanie co najmniej 3 klejnotów Gemini daje graczowi dodatkowy czas.
- Dodaj muzykę. Muzykę możesz generować za pomocą Lyrii 3 na stronie głównej Gemini.
- Dodawanie efektów dźwiękowych
- Dodawanie innych trybów gry
Pozdrawiamy