1. Введение
В этом практическом занятии вы создадите CloudCrush , аркадную игру в жанре «три в ряд», используя Gemini 3 и Gemini CLI , наш агент командной строки для программирования. Игра будет написана на Go и развернута в облаке Google с помощью Cloud Run.
Главная цель этого практического занятия — развить навыки управления агентом для создания приложений вместо написания кода вручную. Вы делегируете все задачи разработки интерфейсу командной строки Gemini, даже если ранее не использовали эти технологии.
Этот практический семинар предназначен для разработчиков среднего уровня, желающих освоить агентные методы программирования. Ориентировочная общая продолжительность семинара — 60 минут . Ресурсы, используемые в семинаре, оплачиваются по факту использования.
Что вы будете делать
- Разработайте основную логику игры «Три в ряд» с использованием языка Go и фреймворка Ebitengine.
- Адаптируйте игру для запуска в веб-браузере с помощью WebAssembly (WASM).
- Разверните игру и её API для сбора рекордов в Cloud Run .
- Организация работы специализированных субагентов и расширений для тестирования и проверки кода.
Предварительные требования
- Базовые знания языков программирования.
- Базовые знания облачной инфраструктуры.
- Базовые знания консоли Google Cloud.
Что вы узнаете
- Как работать с программистом для создания сложных приложений
- Как работать с Близнецами в мультимодальном контексте
- Как развернуть приложения в облаке с помощью Cloud Run
Что вам понадобится
Этот семинар можно провести полностью в облаке с использованием Cloud Shell, но если вы предпочитаете использовать локальный компьютер, вам потребуется следующее:
- Gemini CLI. Скачайте и установите его, следуя инструкциям на сайте geminicli.com.
- Инструментарий Go (версия 1.26 или выше). Загрузите и установите его, следуя инструкциям на go.dev.
- Интерфейс командной строки gcloud для взаимодействия с Google Cloud. Загрузите и установите его, следуя инструкциям в документации Google Cloud.
- Платежный аккаунт Google Cloud (для развертывания игры в облаке)
Ключевые технологии
Здесь вы найдете более подробную информацию о технологиях, которые мы будем использовать:
- Gemini CLI : агент разработки
- Gemini 3 : последняя версия нашей передовой модели обработки больших языков.
2. Настройка среды
Настройка проекта
Создайте проект в Google Cloud.
- В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud .
- Убедитесь, что для вашего облачного проекта включена функция выставления счетов. Узнайте, как проверить, включена ли функция выставления счетов для проекта .
Запустить Cloud Shell
Cloud Shell — это среда командной строки, работающая в Google Cloud и поставляемая с предустановленными необходимыми инструментами.
- В верхней части консоли Google Cloud нажмите кнопку «Активировать Cloud Shell» .
- После подключения к Cloud Shell подтвердите свою аутентификацию:
gcloud auth list - Убедитесь, что ваш проект настроен:
gcloud config get project - Если параметры вашего проекта заданы не так, как ожидалось, настройте их следующим образом:
export PROJECT_ID=<YOUR_PROJECT_ID> gcloud config set project $PROJECT_ID
3. Настройка проекта
Создайте каталог проекта.
Для начала нам нужно создать новую директорию для вашего проекта. В терминале выполните следующие команды:
mkdir -p codelab-match3 && cd codelab-match3
Запуск Gemini CLI
Для начала давайте убедимся, что Gemini CLI установлен правильно. Выполните в терминале следующую команду:
gemini --version
Вы должны увидеть что-то подобное:
$ gemini --version 0.37.1
Теперь запустите Gemini CLI с помощью команды gemini :
gemini
Вы должны увидеть командную строку Gemini CLI:
Если вы видите командную строку Gemini CLI, значит, все в порядке. В противном случае, еще раз проверьте, не пропустили ли вы какие-либо из предыдущих шагов настройки.
Включить управление моделью
Функция управления моделью позволяет добавлять дополнительный контекст агенту, пока он выполняет заданную задачу. Вы можете использовать её для корректировки курса агента, если видите, что он движется в неправильном направлении, для добавления уточняющей информации, улучшающей ответ агента, или для включения незначительных особенностей, которые были упущены в исходном запросе.
Чтобы включить управление движением модели, откройте меню настроек с помощью команды /settings и введите "steering" в поле поиска. Затем установите параметр Enable Model Steering в значение true.
Возможно, потребуется перезапустить интерфейс командной строки (нажав клавишу "r").
Загрузите ресурсы
Нам нужно загрузить изображения, которые будут использоваться в игре. Файлы хранятся на GitHub в репозитории здесь . Вы можете загрузить их вручную или попросить Gemini сделать это за вас, используя следующую команду:
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. Создайте игру с режимом планирования и управлением моделью.
Начните с разработки основной логики игры «три в ряд». Поскольку это сложная задача, лучше всего использовать Gemini CLI в режиме планирования для координации разработки.
Переключите режим планирования с помощью команды /plan в командной строке Gemini CLI:
/plan
Включив режим планирования, скопируйте и вставьте следующую командную строку в Gemini CLI:
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.
Перед созданием плана Gemini CLI может задать вам несколько уточняющих вопросов.
Например, здесь спрашивается, предпочитаете ли вы приложение, использующее один файл, или приложение, использующее несколько файлов:
А вот и вопрос о наших предпочтениях в отношении анимации:
Последний вопрос касается встраивания ресурсов непосредственно в бинарный файл с помощью go:embed:
После ответа на все вопросы вам предоставляется возможность еще раз просмотреть ответы, прежде чем нажать Enter для отправки.
После завершения составления плана вам будет предложено его просмотреть:
В нижней части поля для отзыва вы можете либо принять предложенный план в том виде, в котором он есть, либо оставить свой отзыв.
Воспользуйтесь этой возможностью, чтобы добавить новое требование, которое было упущено в первоначальном задании:
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.
Вам будет предложено еще раз подтвердить план реализации:
Нажмите Enter, чтобы агент начал работу. Теперь агент выйдет из режима планирования и начнет писать код.
Обычно на этом этапе нам пришлось бы ждать завершения процесса или прерывать его нажатием клавиши ESC, если бы мы хотели внести изменения в реализацию, но поскольку у нас включено управление движением модели, мы можем поставить в очередь инструкции для корректировки курса модели.
Пока агент работает, вставьте следующий текст в окно чата агента, чтобы продемонстрировать возможность «управления моделью», показав, как можно ставить в очередь команды для изменения реализации:
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.
Вы увидите, что этот запрос поставлен в очередь как «подсказка по управлению»:
Примите план и наблюдайте, как агент выполнит все ваши требования.
После завершения реализации агента запустите файл go run main.go в папке проекта, чтобы продемонстрировать настольную версию. Вам не нужно выходить из командной строки Gemini для выполнения этой команды. Введите ! (восклицательный знак), чтобы войти в режим оболочки и выполнить команду оттуда:
Преимущество запуска из командной строки заключается в том, что любые возникающие проблемы немедленно фиксируются в контексте агента. Например, в данном случае агент забыл загрузить некоторые зависимости:
Выйти из режима командной оболочки можно, нажав клавишу Escape, после чего вы можете попросить агента проверить и исправить ошибку:
Успешный результат должен выглядеть примерно так:
Попробуйте поиграть и настроить параметры игры, пока не будете довольны результатом (например, ускорьте или замедлите анимацию, отрегулируйте реакцию на команды и т. д.).
5. Адаптируйте игру для работы в веб-браузере.
Созданная вами игра на Ebitengine — это настольное приложение. Чтобы она могла работать в веб-браузере, мы можем преобразовать её в WebAssembly.
Используйте следующую подсказку, чтобы помочь агенту:
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.
После того как агент выполнит задачу, вы можете дать ему указание запустить игровой сервер в фоновом режиме.
Для управления фоновыми процессами можно использовать сочетание клавиш Ctrl+B :
Нажмите Ctrl+B ещё раз, чтобы закрыть это окно.
Теперь откройте в браузере http://localhost:8080, чтобы увидеть игру, работающую в веб-браузере:
Теперь, когда у вас всё работает в веб-браузере, пришло время внести последние корректировки перед развертыванием в облаке.
6. Создайте титульный экран и таблицу лидеров.
Игра работает, но ей не хватает нескольких ключевых функций для полноценного аркадного опыта. Сначала добавим титульный экран, а затем таблицу лидеров, чтобы вы могли соревноваться с друзьями!
Устраните обе проблемы, используя следующее предложение:
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).
Вот пример заставки:
Теперь всё выглядит немного профессиональнее! 🙂
7. Разверните игру в Cloud Run.
Наконец-то пришло время поделиться нашим творением со всем миром! Разверните игру в Google Cloud Run, чтобы иметь к ней доступ из любой точки мира.
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.
Поскольку игра теперь доступна в облаке, было бы упущением не обеспечить её запуск на мобильных устройствах. Это можно сделать с помощью следующего запроса:
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.
Запустите игру еще раз в браузере. Попробуйте также запустить игру с мобильного устройства, используя QR-код.
8. Используйте браузерный агент для тестирования игры.
В Gemini CLI субагент — это изолированный персонаж с новым контекстом, идеально подходящий для длительных и/или высокоточных задач, где текущий контекст не должен влиять на результаты.
Игры, естественно, сложно тестировать с помощью обычных инструментов тестирования (например, модульных и интеграционных тестов), но мы можем использовать браузерный агент для проведения некоторых тестов. Браузерный агент способен запустить собственный браузер Chrome и перемещаться по игровым экранам, отдавая команды DOM. Он также может делать скриншоты, которые мы можем использовать для документирования теста, а также передавать их обратно агенту для внесения незначительных корректировок в пользовательский интерфейс позже.
В настоящее время браузерный агент находится в экспериментальной стадии, поэтому его необходимо сначала включить. Для включения агента на уровне проекта введите следующую команду в Gemini CLI.
Create a .gemini/settings.json file with the following content to
configure the browser sub agent:
{
"agents": {
"overrides": {
"browser_agent": {
"enabled": true
}
}
}
}
Для вступления изменений в силу необходимо перезапустить агент. Сохраните текущий разговор с помощью команды /chat save :
Закройте Gemini CLI, дважды нажав Ctrl+D , и запустите его снова. Восстановите разговор с помощью /chat resume cloud-crush .
Теперь у вас должен быть доступ к агенту браузера. Когда вы захотите делегировать задачу агенту браузера, вы можете указать это с помощью @browser_agent :
Теперь воспользуйтесь браузерным агентом для оценки развернутой игры:
@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.
Вы должны увидеть экран подтверждения:
После того, как вы дадите согласие агенту и предоставите необходимые инструменты, должно открыться новое окно браузера Chrome. Это браузер, управляемый агентом. Визуальной подсказкой будет синяя рамка на экране и сообщение внизу: «Gemini CLI управляет этим браузером».
После завершения процесса отобразится сообщение примерно такого вида:
Вот несколько скриншотов, сделанных браузерным агентом:
title_screen.png:
game_board.png:
Сейчас самое время использовать одно из изображений, сделанных агентом, для оптимизации пользовательского интерфейса игры. Например, можно сказать:
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. Создайте собственный агент для обеспечения безопасности игры.
Одна из распространенных проблем приложений, созданных с использованием Vibe-coded, — это поддержание высокого качества и соблюдение лучших практик как с точки зрения кодирования, так и безопасности. Хотя можно попытаться улучшить подсказки, сделав их очень строгими в обоих этих аспектах, чем больше вы добавляете в подсказку, тем менее сфокусированным будет агент, что часто приводит к неоптимальным результатам. В подобных сценариях идеально подходит использование субагентов, поскольку они работают в отдельном контексте от основного агента и могут быть сосредоточены исключительно на поставленной перед ними задаче. Давайте создадим пользовательский агент для проведения аудита безопасности этого кода и убедимся, что мы не допускаем утечки учетных данных и не подвергаем себя ненужному риску при развертывании этой игры в 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.
Для вступления изменений в силу потребуется перезапустить CLI. Сохраните сессию чата с помощью /chat save и возобновите её с помощью /chat resume как мы делали ранее.
После возобновления работы CLI он автоматически обнаружит нового агента при запуске:
Нажмите Acknowledge and Enable , а затем попросите агента выполнить проверку безопасности кода игры, используя следующее сообщение:
@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
Вы должны увидеть что-то подобное:
После завершения аудита система выдаст рекомендации. В этом примере она выявила несколько важных моментов, требующих исправления:
Если вы обнаружите какие-либо проблемы, просто попросите Gemini CLI исправить их за вас! 🙂
10. Заключение
Поздравляем! Вы успешно использовали Gemini CLI для сборки, развертывания, тестирования и аудита аркадной игры, продемонстрировав передовые агентские рабочие процессы от первоначальной настройки до развертывания.
Уборка
Если вы не планируете возвращаться к этому практическому занятию позже, лучше удалить ресурсы, созданные во время его проведения.
- Удалите службу Cloud Run:
Попросите Gemini CLI удалить его за вас:
I'm finished with this project. Delete the cloud run deployment.
- Удалите каталог проекта:
cd .. && rm -rf codelab-match3
В качестве альтернативы, вы можете удалить весь проект Google Cloud, если он был создан исключительно для этого практического занятия.
Следующие шаги
Вы можете продолжить обучение, изучая другие практические задания на этой платформе или самостоятельно улучшая Cloud Crush!
Несколько предложений по улучшению игры:
- Добавьте особый драгоценный камень "Близнецы" (используя gemini.png), который появляется при совпадении 4 и более камней. Совпадение 3 и более камней "Близнецы" дает игроку бонусное время!
- Добавьте музыку. Вы можете создавать музыку с помощью Lyria 3 на главной странице Gemini.
- Добавить звуковые эффекты
- Добавить другие режимы игры
Удачного программирования!