۱. مقدمه
در این آزمایشگاه کد، شما با استفاده از Gemini 3 و Gemini CLI ، عامل کدنویسی خط فرمان ما، یک بازی آرکید به نام CloudCrush خواهید ساخت. این بازی با زبان Go نوشته شده و با استفاده از Cloud Run روی فضای ابری گوگل مستقر خواهد شد.
هدف اصلی این آزمایشگاه کد، توسعه مهارتهای لازم برای هماهنگسازی عامل (agent) جهت ساخت برنامههای کاربردی برای شما به جای نوشتن کد به صورت دستی است. شما تمام وظایف توسعه را به Gemini CLI واگذار خواهید کرد، حتی اگر قبلاً از این فناوریها استفاده نکرده باشید.
این آزمایشگاه کد برای توسعهدهندگان سطح متوسط است که به دنبال یادگیری گردشهای کاری کدنویسی عاملمحور هستند. مدت زمان تخمینی کل این آزمایشگاه ۶۰ دقیقه است. منابع ایجاد شده در این آزمایشگاه کد از قیمتگذاری مبتنی بر مصرف استفاده میکنند.
کاری که انجام خواهید داد
- منطق اصلی بازی Match-3 را با استفاده از Go و چارچوب Ebitengine بسازید.
- تطبیق بازی برای اجرا در مرورگر وب با استفاده از WebAssembly (WASM)
- بازی و API دارای بالاترین امتیاز آن را در Cloud Run مستقر کنید.
- هماهنگسازی زیرعاملها و افزونههای تخصصی برای آزمایش و بررسی کد
پیشنیازها
- دانش پایه زبانهای برنامهنویسی
- آشنایی اولیه با زیرساخت ابری
- آشنایی اولیه با کنسول ابری گوگل
آنچه یاد خواهید گرفت
- نحوه همکاری با یک متخصص کدنویسی برای ساخت برنامههای پیچیده
- نحوه کار با Gemini در یک زمینه چندوجهی
- نحوه استقرار برنامهها در فضای ابری با استفاده از Cloud Run
آنچه نیاز دارید
این کارگاه میتواند کاملاً روی فضای ابری با استفاده از Cloud Shell انجام شود، اما اگر ترجیح میدهید از دستگاه محلی خود استفاده کنید، به موارد زیر نیاز خواهید داشت:
- رابط خط فرمان Gemini. آن را دانلود و طبق دستورالعملهای geminicli.com نصب کنید.
- ابزار Go (نسخه ۱.۲۶ یا بالاتر). آن را دانلود و با استفاده از دستورالعملهای موجود در go.dev نصب کنید.
- رابط خط فرمان gcloud برای تعامل با گوگل کلود. آن را با استفاده از دستورالعملهای موجود در مستندات گوگل کلود دانلود و نصب کنید.
- یک حساب پرداخت گوگل کلود (برای انتشار بازی در فضای ابری)
فناوریهای کلیدی
در اینجا میتوانید اطلاعات بیشتری در مورد فناوریهایی که ما استفاده خواهیم کرد، بیابید:
- رابط خط فرمان Gemini : عامل توسعه
- جمینی ۳ : آخرین نسخه از مدل زبان بزرگ مرزی ما
۲. تنظیمات محیطی
راهاندازی پروژه
ایجاد یک پروژه ابری گوگل
- در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید .
- مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .
شروع پوسته ابری
Cloud Shell یک محیط خط فرمان است که در Google Cloud اجرا میشود و ابزارهای لازم از قبل روی آن بارگذاری شدهاند.
- روی فعال کردن Cloud Shell در بالای کنسول Google Cloud کلیک کنید.
- پس از اتصال به Cloud Shell، احراز هویت خود را تأیید کنید:
gcloud auth list - تأیید کنید که پروژه شما پیکربندی شده است:
gcloud config get project - اگر پروژه شما مطابق انتظار تنظیم نشده است، آن را تنظیم کنید:
export PROJECT_ID=<YOUR_PROJECT_ID> gcloud config set project $PROJECT_ID
۳. راهاندازی پروژه
ایجاد دایرکتوری پروژه
ابتدا، باید یک دایرکتوری جدید برای پروژه شما ایجاد کنیم. در ترمینال خود، دستورات زیر را اجرا کنید:
mkdir -p codelab-match3 && cd codelab-match3
اجرای رابط خط فرمان Gemini
ابتدا، بررسی میکنیم که Gemini CLI به درستی نصب شده است. دستور زیر را در ترمینال خود اجرا کنید:
gemini --version
شما باید چیزی شبیه به این را ببینید:
$ gemini --version 0.37.1
حالا Gemini CLI را با دستور gemini اجرا کنید:
gemini
شما باید خط فرمان Gemini CLI را ببینید:
اگر خط فرمان Gemini CLI را میبینید، آماده شروع هستید. در غیر این صورت، دوباره بررسی کنید که آیا مراحل راهاندازی قبلی را از دست دادهاید یا خیر.
فعال کردن فرمان مدل
هدایت مدل قابلیتی است که به شما امکان میدهد در حالی که عامل هنوز روی یک وظیفه مشخص کار میکند، زمینههای اضافی به آن اضافه کنید. میتوانید از آن برای اصلاح مسیر عامل در زمانی که میبینید در مسیر اشتباه حرکت میکند، افزودن اطلاعات شفافسازی برای بهبود پاسخ عامل یا افزودن ویژگیهای جزئی که در اعلان اصلی از قلم افتادهاند، استفاده کنید.
برای فعال کردن هدایت مدل، منوی تنظیمات را با استفاده از دستور /settings باز کنید و عبارت "steering" را در کادر جستجو تایپ کنید. سپس گزینه Enable Model Steering را روی true تنظیم کنید.
برای اعمال تغییر، ممکن است لازم باشد CLI را مجدداً راهاندازی کنید (با فشار دادن کلید "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
۴. بازی را با حالت برنامهریزی و هدایت مدل ایجاد کنید
با ساخت منطق اصلی بازی Match-3 شروع کنید. از آنجایی که این یک کار پیچیده است، بهتر است از 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 است:
پس از پاسخ دادن به تمام سوالات، به شما این امکان داده میشود که قبل از زدن دکمه اینتر برای ارسال، آنها را برای آخرین بار مرور کنید.
پس از اتمام طرح، از شما خواسته میشود که آن را بررسی کنید:
در پایین کادر بررسی، میتوانید طرح را همانطور که هست بپذیرید یا بازخورد خود را اضافه کنید.
از این فرصت برای اضافه کردن یک الزام جدید که در دستور اولیه از قلم افتاده بود، استفاده کنید:
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.
برای آخرین بار از شما خواسته میشود که طرح پیادهسازی را تأیید کنید:
برای شروع کار، اینتر را بزنید. اکنون عامل از حالت برنامهریزی خارج شده و شروع به نوشتن کد میکند.
در این مرحله، معمولاً اگر میخواستیم تغییراتی در پیادهسازی ایجاد کنیم، باید منتظر میماندیم تا برنامه تمام شود یا آن را با کلید 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 CLI ندارید. برای ورود به حالت shell، علامت تعجب ( ! ) را تایپ کنید و دستور را از آنجا اجرا کنید:
مزیت اجرا از حالت shell این است که هرگونه مشکلی که ممکن است رخ دهد بلافاصله در زمینه agent ثبت میشود. برای مثال، در این مورد agent فراموش کرده است که برخی از وابستگیها را دانلود کند:
میتوانید با فشردن کلید escape از حالت shell خارج شوید و سپس از agent بخواهید که خطا را بررسی و برطرف کند:
نتیجه موفقیتآمیز باید شبیه به این باشد:
سعی کنید بازی را انجام دهید و پارامترهای بازی را تا زمانی که از تجربه آن راضی هستید، تنظیم کنید (مثلاً انیمیشن را سریعتر یا کندتر کنید، نحوه پاسخ آن به دستورات را تنظیم کنید و غیره).
۵. بازی را برای اجرا روی مرورگر وب تنظیم کنید
بازی 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 را در مرورگر خود باز کنید تا اجرای بازی را در وب مشاهده کنید:
حالا که آن را روی وب اجرا کردهاید، وقت آن رسیده که قبل از استقرار در فضای ابری، آن را کمی اصلاح کنید.
۶. صفحه عنوان و جدول امتیازات را ایجاد کنید
بازی کار میکند اما چند ویژگی کلیدی برای تجربه مناسب یک بازی آرکید را ندارد. اول بیایید یک صفحه عنوان و سپس یک جدول امتیازات اضافه کنیم تا بتوانید با دوستانتان رقابت کنید!
هر دو مشکل را با دستور زیر برطرف کنید:
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).
در اینجا نمونهای از صفحه عنوان آمده است:
داره کم کم حرفه ای تر به نظر میرسه! 🙂
۷. بازی را روی 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.
از آنجایی که بازی اکنون در فضای ابری (cloud) در دسترس است، عدم اجازه اجرای آن بر روی دستگاههای تلفن همراه، یک فرصت از دست رفته خواهد بود. میتوانید این کار را با استفاده از دستور زیر انجام دهید:
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 به بازی دسترسی پیدا کنید.
۸. از مرورگر ایجنت برای تست بازی استفاده کنید
در Gemini CLI، یک sub-agent یک شخصیت ایزوله با یک زمینه جدید است که برای وظایف طولانی مدت و/یا با دقت بالا که در آنها نمیخواهید زمینه فعلی بر نتایج تأثیر بگذارد، ایدهآل است.
تست بازیها با ابزارهای تست مرسوم (مثلاً تستهای واحد و یکپارچهسازی) طبیعتاً دشوار است، اما میتوانیم از عامل مرورگر برای انجام برخی تستها استفاده کنیم. عامل مرورگر قادر است مرورگر کروم خود را راهاندازی کند و با صدور دستورات 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 ذخیره کنید:
با دو بار فشردن Ctrl+D از محیط CLI نرمافزار Gemini خارج شوید و دوباره آن را اجرا کنید. با استفاده از /chat resume cloud-crush مکالمه را بازیابی کنید.
حالا باید به browser agent دسترسی داشته باشید. هر زمان که بخواهید وظیفهای را به browser agent واگذار کنید، میتوانید آن را با @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.
شما باید صفحه تأیید را ببینید:
پس از اینکه به عامل و ابزارهای مورد نیاز رضایت دادید، یک پنجره مرورگر کروم جدید باید باز شود. این مرورگری است که توسط عامل کنترل میشود. نشانه بصری، حاشیه آبی روی صفحه و پیامی در پایین صفحه خواهد بود که میگوید: "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.
۹. یک عامل سفارشی برای ایمنسازی بازی ایجاد کنید
یکی از نگرانیهای رایج در مورد برنامههای «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 بخواهید آن را برایتان حل کند! 🙂
۱۰. نتیجهگیری
تبریک! شما با موفقیت از رابط خط فرمان Gemini برای ساخت، استقرار، آزمایش و ممیزی یک بازی آرکید استفاده کردید و گردشهای کاری پیشرفته عاملگرا را از چارچوببندی اولیه تا استقرار نشان دادید.
تمیز کردن
اگر قصد ندارید بعداً به این آزمایشگاه کد برگردید، بهتر است منابع ایجاد شده در طول این آزمایشگاه کد را حذف کنید.
- سرویس Cloud Run را حذف کنید:
از رابط خط فرمان Gemini بخواهید آن را برای شما حذف کند:
I'm finished with this project. Delete the cloud run deployment.
- حذف دایرکتوری پروژه:
cd .. && rm -rf codelab-match3
از طرف دیگر، اگر پروژه Google Cloud صرفاً برای این آزمایشگاه کد ایجاد شده باشد، میتوانید کل آن را حذف کنید.
مراحل بعدی
شما میتوانید با کاوش در سایر آزمایشگاههای کد در این پلتفرم، یا با بهبود Cloud Crush به تنهایی، سفر یادگیری خود را ادامه دهید!
چند پیشنهاد برای بهبود بازی:
- یک جواهر ویژه "Gemini" (با استفاده از gemini.png) اضافه کنید که هنگام تطبیق بیش از ۴ جواهر ظاهر میشود. تطبیق بیش از ۳ جواهر Gemini به بازیکن زمان اضافی میدهد!
- اضافه کردن موسیقی. میتوانید با استفاده از Lyria 3 در صفحه اصلی Gemini موسیقی تولید کنید.
- جلوههای صوتی اضافه کنید
- اضافه شدن حالتهای بازی دیگر
کدنویسی خوبی داشته باشید!