使用 Gemini CLI 建構三消街機遊戲

1. 簡介

在本程式碼研究室中，您將使用 Gemini 3 和 Gemini CLI (指令列程式設計代理)，建構 CloudCrush (三消街機遊戲)。遊戲會以 Go 語言編寫，並使用 Cloud Run 部署至 Google Cloud。

本程式碼研究室的主要目標是培養相關技能，讓代理程式為您協調建構應用程式，不必手動編寫程式碼。即使您從未使用過這些技術，也可以將所有開發工作委派給 Gemini CLI。

本程式碼研究室適合想瞭解代理式程式碼編寫工作流程的中階開發人員。本實驗室的預估總時長為 60 分鐘。本程式碼研究室建立的資源會採用根據用量計費的方案。

學習內容

使用 Go 和 Ebitengine 架構建構核心三消遊戲邏輯。
使用 WebAssembly (WASM) 調整遊戲，以便在網路瀏覽器上執行
將遊戲及其最高分 API 部署至 Cloud Run。
協調專用子代理程式和擴充功能，進行測試和程式碼審查

必要條件

具備程式設計語言基本知識
雲端基礎架構的基本知識
Google Cloud 控制台基本知識

課程內容

如何與程式碼編寫代理合作建構複雜應用程式
如何在多模態情境中使用 Gemini
如何使用 Cloud Run 將應用程式部署至雲端

軟硬體需求

本研討會完全可以在雲端上使用 Cloud Shell 完成，但如果您偏好使用本機，則需要下列項目：

Gemini CLI。按照 geminicli.com 的說明下載並安裝
Go 工具鍊 (1.26 以上版本)。按照 go.dev 中的操作說明下載並安裝
用於與 Google Cloud 互動的 gcloud CLI。按照 Google Cloud 說明文件中的指示下載並安裝
Google Cloud 帳單帳戶 (用於將遊戲部署至雲端)

主要技術

請參閱下列資源，進一步瞭解我們會用到的技術：

Gemini CLI：開發代理
Gemini 3：Google 最新的前沿大型語言模型

2. 環境設定

專案設定

建立 Google Cloud 專案

在 Google Cloud 控制台的專案選取器頁面中，選取或建立 Google Cloud 專案。
確認 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 指令啟動 Gemini CLI：

gemini

您應該會看到 Gemini CLI 提示：

如果看到 Gemini CLI 提示，表示一切就緒。如果沒有，請再次檢查是否遺漏任何先前的設定步驟。

啟用模型轉向

模型導引功能可讓你在代理程式執行特定任務時，為代理程式提供額外脈絡資訊。當代理程式的方向錯誤時，你可以使用這項功能修正；如要改善代理程式的回覆，或加入原始提示中遺漏的次要功能，也可以使用這項功能。

如要啟用模型導向功能，請使用 /settings 指令開啟設定選單，然後在搜尋方塊中輸入「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

4. 使用規劃模式和模型導引建立遊戲

首先，請建構核心的三消遊戲邏輯。由於這項工作相當複雜，建議您在計畫模式下使用 Gemini CLI，協調開發作業。

在 Gemini CLI 提示中，使用斜線指令 /plan 切換計畫模式：

/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 CLI 即可執行這項指令。輸入 ! (驚嘆號) 進入殼層模式，然後從該處執行指令：

從殼層模式執行的優點是，代理程式環境會立即擷取可能發生的任何問題。舉例來說，在這個情況下，代理程式忘記下載某些依附元件：

按下 Esc 鍵即可退出 Shell 模式，然後要求代理程式檢查並修正錯誤：

成功結果應如下所示：

試玩遊戲並微調遊戲參數，直到您滿意為止 (例如加快或放慢動畫速度、調整對指令的回應方式等)。

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 code 從行動裝置存取遊戲。

8. 使用瀏覽器代理程式測試遊戲

在 Gemini CLI 中，子代理是具有全新情境的獨立角色，非常適合長時間執行和/或高精確度的工作，因為您不希望目前的環境影響結果。

使用傳統測試工具 (例如單元和整合測試) 測試遊戲自然很困難，但我們可以利用瀏覽器代理程式進行一些測試。瀏覽器代理程式可以啟動自己的 Chrome 瀏覽器，並透過發出 DOM 指令瀏覽遊戲畫面。此外，這項工具還能擷取螢幕截圖，方便我們記錄測試結果，並提供給代理商，以便日後對 UI 進行微調。

瀏覽器代理程式目前為實驗功能，因此我們必須先啟用。向 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 鍵退出 Gemini CLI，然後重新啟動。還原與「/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:

現在，您可以使用代理程式拍攝的其中一張圖片，最佳化遊戲 UI。例如，你可以說出：

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. 建立自訂代理程式，確保遊戲安全

「隨興編碼」應用程式常見的疑慮是，如何從程式碼和安全性的角度，維持高品質和最佳做法。雖然您可以嘗試改善提示，嚴格要求這兩方面，但提示內容越多，代理程式的重點就越少，通常會導致結果不盡理想。在這種情況下，使用子代理程式是理想做法，因為子代理程式與主要代理程式的運作環境不同，可以專注於您指派的任務。讓我們建立自訂代理程式，對這段程式碼進行安全稽核，並確保將遊戲部署至 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 專案，可以刪除整個專案。

後續步驟

您可以探索這個平台上的其他 Codelabs，或自行改良 Cloud Crush，繼續學習之旅！

以下提供幾項遊戲改善建議：

新增特殊「Gemini」寶石 (使用 gemini.png)，在配對 4 個以上的寶石時顯示。配對 3 個以上的 Gemini 寶石，即可獲得額外時間！
新增音樂。你可以在 Gemini 首頁使用 Lyria 3 生成音樂。
加入音效
新增其他遊戲模式

祝您編寫程式一切順利！