1. Giới thiệu
Trong lớp học lập trình này, bạn sẽ tạo CloudCrush, một trò chơi arcade ghép 3, bằng cách sử dụng Gemini 3 và Gemini CLI, tác nhân lập trình dòng lệnh của chúng tôi. Trò chơi này sẽ được viết bằng Go và triển khai trên Google Cloud bằng Cloud Run.
Mục tiêu chính của lớp học lập trình này là phát triển các kỹ năng điều phối tác nhân để xây dựng ứng dụng cho bạn thay vì viết mã theo cách thủ công. Bạn sẽ uỷ quyền tất cả các tác vụ phát triển cho Gemini CLI, ngay cả khi trước đây bạn chưa từng sử dụng các công nghệ này.
Lớp học lập trình này dành cho các nhà phát triển có trình độ trung cấp muốn tìm hiểu quy trình làm việc lập trình dựa trên tác nhân. Tổng thời lượng ước tính cho bài thực hành này là 60 phút. Các tài nguyên được tạo trong lớp học lập trình này sử dụng mô hình giá dựa trên mức tiêu thụ.
Bạn sẽ thực hiện
- Xây dựng logic cốt lõi của trò chơi ghép 3 bằng Go và khung Ebitengine.
- Điều chỉnh trò chơi để chạy trên trình duyệt web bằng WebAssembly (WASM)
- Triển khai trò chơi và API điểm số cao của trò chơi đó lên Cloud Run.
- Điều phối các tiện ích và tác nhân phụ chuyên biệt để kiểm thử và xem xét mã
Điều kiện tiên quyết
- Kiến thức cơ bản về ngôn ngữ lập trình
- Kiến thức cơ bản về cơ sở hạ tầng đám mây
- Kiến thức cơ bản về bảng điều khiển Google Cloud
Kiến thức bạn sẽ học được
- Cách làm việc với một tác nhân lập trình để xây dựng các ứng dụng phức tạp
- Cách làm việc với Gemini trong bối cảnh đa phương thức
- Cách triển khai ứng dụng lên đám mây bằng Cloud Run
Bạn cần có
Bạn có thể thực hiện toàn bộ hội thảo này trên đám mây bằng Cloud Shell. Tuy nhiên, nếu muốn sử dụng máy cục bộ, bạn sẽ cần những thứ sau:
- Gemini CLI. Tải xuống và cài đặt theo hướng dẫn trên trang geminicli.com
- Chuỗi công cụ Go (phiên bản 1.26 trở lên). Tải xuống và cài đặt bằng cách làm theo hướng dẫn trong go.dev
- gcloud CLI để tương tác với Google Cloud. Tải xuống và cài đặt theo hướng dẫn trong tài liệu của Google Cloud
- Tài khoản thanh toán Google Cloud (để triển khai trò chơi lên đám mây)
Công nghệ chính
Tại đây, bạn có thể tìm thêm thông tin về các công nghệ mà chúng tôi sẽ sử dụng:
- Gemini CLI: tác nhân phát triển
- Gemini 3: phiên bản mới nhất của mô hình ngôn ngữ lớn tiên tiến của chúng tôi
2. Thiết lập môi trường
Thiết lập dự án
Tạo một dự án trên Google Cloud
- Trong Google Cloud Console, trên trang chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
- Đảm bảo bạn đã bật tính năng thanh toán cho dự án trên Cloud. Tìm hiểu cách kiểm tra xem tính năng thanh toán có được bật trên một dự án hay không.
Khởi động Cloud Shell
Cloud Shell là một môi trường dòng lệnh chạy trong Google Cloud và được tải sẵn các công cụ cần thiết.
- Nhấp vào Kích hoạt Cloud Shell ở đầu bảng điều khiển Cloud.
- Sau khi kết nối với Cloud Shell, hãy xác minh thông tin xác thực của bạn:
gcloud auth list - Xác nhận rằng dự án của bạn đã được định cấu hình:
gcloud config get project - Nếu dự án của bạn không được thiết lập như mong đợi, hãy thiết lập dự án:
export PROJECT_ID=<YOUR_PROJECT_ID> gcloud config set project $PROJECT_ID
3. Thiết lập dự án
Tạo thư mục dự án
Trước tiên, chúng ta cần tạo một thư mục mới cho dự án của bạn. Trong cửa sổ dòng lệnh, hãy chạy các lệnh sau:
mkdir -p codelab-match3 && cd codelab-match3
Khởi chạy Gemini CLI
Trước tiên, hãy kiểm tra để đảm bảo bạn đã cài đặt Gemini CLI đúng cách. Chạy trong thiết bị đầu cuối:
gemini --version
Bạn sẽ thấy như sau:
$ gemini --version 0.37.1
Bây giờ, hãy chạy Gemini CLI bằng lệnh gemini:
gemini
Bạn sẽ thấy câu lệnh Gemini CLI:
Nếu bạn thấy lời nhắc Gemini CLI, tức là bạn đã sẵn sàng. Nếu không, hãy kiểm tra kỹ xem bạn có bỏ lỡ bước thiết lập nào trước đó hay không.
Bật tính năng Điều khiển bằng mô hình
Điều hướng mô hình là một tính năng cho phép bạn thêm ngữ cảnh bổ sung vào tác nhân trong khi tác nhân vẫn đang thực hiện một nhiệm vụ nhất định. Bạn có thể dùng tính năng này để điều chỉnh hướng đi của tác nhân khi thấy tác nhân đi sai hướng, thêm thông tin làm rõ để cải thiện câu trả lời của tác nhân hoặc thêm các tính năng nhỏ bị bỏ sót trong câu lệnh ban đầu.
Để bật tính năng định hướng mô hình, hãy mở trình đơn cài đặt bằng lệnh /settings rồi nhập "steering" vào hộp tìm kiếm. Sau đó, hãy đặt tuỳ chọn Bật tính năng định hướng mô hình thành true.
Bạn có thể phải khởi động lại CLI để thay đổi có hiệu lực (nhấn phím "r").
Tải các thành phần xuống
Chúng ta cần tải những hình ảnh sẽ được dùng trong trò chơi xuống. Các tệp này được lưu trữ trên GitHub trong kho lưu trữ tại đây. Bạn có thể tải các tệp này xuống theo cách thủ công hoặc yêu cầu Gemini làm việc này cho bạn bằng câu lệnh sau:
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. Tạo trò chơi bằng chế độ kế hoạch và tính năng điều hướng mô hình
Bắt đầu bằng cách xây dựng logic cốt lõi của trò chơi ghép 3. Vì đây là một nhiệm vụ phức tạp, nên tốt nhất là bạn nên sử dụng Gemini CLI ở chế độ lập kế hoạch để điều phối quá trình phát triển.
Bật/tắt chế độ kế hoạch bằng lệnh gạch chéo /plan trong câu lệnh Gemini CLI:
/plan
Khi chế độ lập kế hoạch được bật, hãy sao chép và dán câu lệnh sau vào 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 có thể hỏi bạn một vài câu hỏi làm rõ trước khi tạo kế hoạch.
Ví dụ: ở đây, hệ thống sẽ hỏi xem bạn muốn có một tệp hay một ứng dụng có nhiều tệp:
Và đây là câu hỏi về lựa chọn ưu tiên của chúng ta đối với ảnh động:
Câu hỏi cuối cùng là về việc nhúng các thành phần vào chính tệp nhị phân bằng go:embed:
Sau khi trả lời tất cả các câu hỏi, bạn có thể xem lại lần cuối trước khi nhấn Enter để gửi.
Sau khi hoàn tất kế hoạch, bạn sẽ được nhắc xem lại kế hoạch đó:
Ở cuối hộp đánh giá, bạn có thể chấp nhận kế hoạch như hiện tại hoặc thêm ý kiến phản hồi của bạn.
Hãy tận dụng cơ hội này để thêm một yêu cầu mới mà bạn đã bỏ lỡ trong câu lệnh ban đầu:
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.
Bạn sẽ được nhắc xác nhận kế hoạch triển khai lần cuối:
Nhấn phím Enter để tác nhân bắt đầu thực hiện yêu cầu. Lúc này, tác nhân sẽ thoát khỏi chế độ lập kế hoạch và bắt đầu viết mã.
Tại thời điểm này, thông thường chúng ta sẽ cần đợi quá trình này hoàn tất hoặc gián đoạn bằng phím Esc nếu muốn thay đổi quá trình triển khai. Tuy nhiên, vì đã bật tính năng định hướng mô hình, nên chúng ta có thể xếp hàng các chỉ dẫn để điều chỉnh mô hình.
Trong khi tác nhân đang hoạt động, hãy dán nội dung sau vào cửa sổ trò chuyện của tác nhân để minh hoạ khả năng "định hướng mô hình", cho thấy cách bạn có thể xếp hàng đợi các lệnh để xoay vòng việc triển khai:
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.
Bạn sẽ thấy câu lệnh này được xếp hàng đợi dưới dạng "gợi ý định hướng":
Chấp nhận kế hoạch và xem nhân viên hỗ trợ thực hiện tất cả các yêu cầu của bạn.
Khi tác nhân hoàn tất việc triển khai, hãy chạy go run main.go trên thư mục dự án để minh hoạ phiên bản dành cho máy tính. Bạn không cần rời khỏi Gemini CLI để chạy lệnh này. Loại ! (dấu chấm than) để chuyển sang chế độ shell và chạy lệnh từ đó:
Lợi ích của việc chạy từ chế độ shell là mọi vấn đề có thể xảy ra đều được ghi lại ngay lập tức trong ngữ cảnh tác nhân. Ví dụ: trong trường hợp này, tác nhân quên tải một số phần phụ thuộc xuống:
Bạn có thể thoát chế độ shell bằng cách nhấn phím thoát, sau đó yêu cầu tác nhân kiểm tra và khắc phục lỗi:
Kết quả thành công sẽ có dạng như sau:
Hãy thử chơi trò chơi và tinh chỉnh các thông số của trò chơi cho đến khi bạn hài lòng với trải nghiệm (ví dụ: tăng hoặc giảm tốc độ ảnh động, điều chỉnh cách trò chơi phản hồi các lệnh, v.v.)
5. Điều chỉnh trò chơi để chạy trên trình duyệt web
Trò chơi Ebitengine mà bạn vừa tạo là một ứng dụng dành cho máy tính. Để cho phép chạy trong web, chúng ta có thể chuyển đổi nó thành WebAssembly.
Hãy dùng câu lệnh sau để hướng dẫn trợ lý:
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.
Sau khi tác nhân hoàn tất nhiệm vụ, bạn có thể hướng dẫn tác nhân chạy máy chủ trò chơi ở chế độ nền.
Bạn có thể quản lý các quy trình chạy nền bằng tổ hợp phím Ctrl+B:
Nhấn tổ hợp phím Ctrl+B một lần nữa để đóng cửa sổ này.
Bây giờ, hãy mở http://localhost:8080 trong trình duyệt để xem trò chơi đang chạy trên web:
Giờ đây, khi đã chạy ứng dụng trên web, bạn chỉ cần tinh chỉnh lần cuối trước khi triển khai ứng dụng lên đám mây.
6. Tạo màn hình tiêu đề và bảng xếp hạng
Trò chơi hoạt động nhưng thiếu một số tính năng chính để mang lại trải nghiệm arcade phù hợp. Trước tiên, hãy thêm một màn hình tiêu đề rồi thêm một bảng xếp hạng để bạn có thể cạnh tranh với bạn bè!
Khắc phục cả hai vấn đề bằng câu lệnh sau:
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).
Sau đây là ví dụ về màn hình tiêu đề:
Ứng dụng bắt đầu trông chuyên nghiệp hơn một chút! 🙂
7. Triển khai trò chơi lên Cloud Run
Cuối cùng thì chúng ta cũng có thể chia sẻ tác phẩm của mình với mọi người! Triển khai trò chơi lên Google Cloud Run để có thể truy cập vào trò chơi từ mọi nơi.
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.
Vì trò chơi hiện đang hoạt động trên đám mây, nên việc không cho phép trò chơi chạy trên thiết bị di động sẽ là một cơ hội bị bỏ lỡ. Bạn có thể thực hiện việc này bằng lời nhắc sau:
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.
Chạy lại trò chơi trên trình duyệt. Hãy thử truy cập vào trò chơi trên thiết bị di động bằng mã QR.
8. Sử dụng tác nhân trình duyệt để kiểm thử trò chơi
Trong Gemini CLI, tác nhân phụ là một nhân cách riêng biệt với bối cảnh mới, phù hợp với những công việc có thời gian thực hiện dài và/hoặc độ chính xác cao mà bạn không muốn bối cảnh hiện tại ảnh hưởng đến kết quả.
Các trò chơi vốn rất khó kiểm thử bằng các công cụ kiểm thử thông thường (ví dụ: kiểm thử đơn vị và kiểm thử tích hợp), nhưng chúng ta có thể sử dụng tác nhân trình duyệt để thực hiện một số kiểm thử cho chúng ta. Tác nhân trình duyệt có thể khởi động trình duyệt Chrome riêng và điều hướng các màn hình trò chơi bằng cách đưa ra các lệnh DOM. Công cụ này cũng có khả năng chụp ảnh màn hình. Chúng ta có thể dùng ảnh chụp màn hình để ghi lại quá trình kiểm thử và gửi lại cho nhân viên hỗ trợ để họ điều chỉnh giao diện người dùng sau này.
Tác nhân trình duyệt hiện đang ở giai đoạn thử nghiệm, vì vậy, trước tiên chúng ta cần bật tác nhân này. Đưa ra câu lệnh này cho Gemini CLI để bật tác nhân ở cấp dự án.
Create a .gemini/settings.json file with the following content to
configure the browser sub agent:
{
"agents": {
"overrides": {
"browser_agent": {
"enabled": true
}
}
}
}
Bạn cần khởi động lại tác nhân để thay đổi này có hiệu lực. Lưu cuộc trò chuyện hiện tại bằng lệnh /chat save:
Thoát Gemini CLI bằng cách nhấn tổ hợp phím Ctrl+D hai lần rồi khởi động lại. Khôi phục cuộc trò chuyện với /chat resume cloud-crush.
Giờ đây, bạn có thể truy cập vào tác nhân trình duyệt. Bất cứ khi nào muốn uỷ quyền một tác vụ cho tác nhân trình duyệt, bạn có thể đề cập đến tác vụ đó bằng @browser_agent:
Bây giờ, hãy sử dụng tác nhân trình duyệt để đánh giá trò chơi mà chúng ta đã triển khai:
@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.
Bạn sẽ thấy màn hình xác nhận:
Sau khi bạn đồng ý cho nhân viên hỗ trợ và các công cụ cần thiết, một cửa sổ trình duyệt Chrome mới sẽ mở ra. Đây là trình duyệt do nhân viên hỗ trợ kiểm soát. Gợi ý trực quan sẽ là đường viền màu xanh dương trên màn hình và thông báo ở dưới cùng cho biết "Gemini CLI đang kiểm soát trình duyệt này":
Khi hoàn tất, hệ thống sẽ hiển thị một thông báo như sau:
Sau đây là một số ảnh chụp màn hình do tác nhân trình duyệt chụp:
title_screen.png:
game_board.png:
Giờ là thời điểm thích hợp để sử dụng một trong những hình ảnh do tác nhân chụp để tối ưu hoá giao diện người dùng của trò chơi. Ví dụ, bạn có thể nói:
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. Tạo một tác nhân tuỳ chỉnh để bảo mật trò chơi
Một mối lo ngại thường gặp đối với các ứng dụng "được tạo bằng AI" là làm thế nào để duy trì chất lượng cao và các phương pháp hay nhất từ cả góc độ lập trình và bảo mật. Mặc dù bạn có thể cố gắng cải thiện câu lệnh để đảm bảo tính chặt chẽ cho cả hai khía cạnh này, nhưng càng thêm nhiều thông tin vào câu lệnh thì tác nhân sẽ càng ít tập trung, điều này thường dẫn đến kết quả không tối ưu. Đối với loại tình huống này, việc sử dụng các tác nhân phụ là lý tưởng vì chúng hoạt động trên một bối cảnh riêng biệt với tác nhân chính và có thể tập trung vào nhiệm vụ mà bạn giao cho chúng. Hãy tạo một tác nhân tuỳ chỉnh để kiểm tra bảo mật mã này và đảm bảo rằng chúng ta không làm lộ bất kỳ thông tin đăng nhập nào hoặc tự đặt mình vào nguy cơ không cần thiết khi triển khai trò chơi này lên 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.
Bạn cần khởi động lại CLI để thay đổi có hiệu lực. Lưu phiên trò chuyện bằng /chat save và tiếp tục bằng /chat resume như chúng ta đã làm trước đây.
Khi tiếp tục, CLI sẽ tự động phát hiện tác nhân mới khi khởi động:
Nhấp vào Acknowledge and Enable rồi yêu cầu tác nhân thực hiện kiểm tra bảo mật đối với mã trò chơi bằng câu lệnh sau:
@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
Bạn sẽ thấy như sau:
Sau khi hoàn tất quy trình kiểm tra, công cụ này sẽ đưa ra các đề xuất. Trong ví dụ này, công cụ này đã tìm thấy một số điểm quan trọng cần khắc phục:
Nếu bạn phát hiện thấy vấn đề, chỉ cần yêu cầu Gemini CLI sửa cho bạn! 🙂
10. Kết luận
Xin chúc mừng! Bạn đã sử dụng thành công Gemini CLI để tạo, triển khai, kiểm thử và kiểm tra một trò chơi điện tử, minh hoạ các quy trình làm việc nâng cao của tác nhân từ giàn giáo ban đầu đến việc triển khai.
Dọn dẹp
Nếu không có ý định quay lại lớp học lập trình này sau, bạn nên xoá các tài nguyên đã tạo trong lớp học lập trình này.
- Xoá dịch vụ Cloud Run:
Yêu cầu Gemini CLI xoá tệp đó cho bạn:
I'm finished with this project. Delete the cloud run deployment.
- Xoá thư mục dự án:
cd .. && rm -rf codelab-match3
Ngoài ra, bạn có thể xoá toàn bộ dự án trên Google Cloud nếu dự án đó chỉ được tạo cho lớp học lập trình này.
Các bước tiếp theo
Bạn có thể tiếp tục hành trình học tập bằng cách khám phá các lớp học lập trình khác trên nền tảng này hoặc tự mình cải thiện Cloud Crush!
Một số đề xuất để cải thiện trò chơi:
- Thêm một Gem đặc biệt "Gemini" (sử dụng gemini.png) xuất hiện khi bạn ghép 4 Gem trở lên. Ghép 3 viên ngọc Gemini trở lên sẽ giúp người chơi có thêm thời gian bổ sung!
- Thêm nhạc. Bạn có thể tạo nhạc bằng Lyria 3 trên trang chủ của Gemini.
- Thêm hiệu ứng âm thanh
- Thêm các chế độ chơi khác
Chúc bạn lập trình vui vẻ!