Agentverse - The Shadowblade's Codex - Vibecoding with Gemini CLI

1. 序曲

孤立開發的時代即將結束。下一波技術演進並非單一天才的成就，而是集體精通的成果。建立單一智慧代理程式是一項有趣的實驗。建構強大、安全且智慧的代理程式生態系統 (也就是真正的 Agentverse)，是現代企業面臨的重大挑戰。

在這個新時代，要取得成功，就必須整合四個重要角色，也就是支援任何蓬勃發展的代理系統的基礎支柱。任何一個領域的不足都會造成弱點，進而危害整個結構。

這場研討會是企業的必備手冊，可協助您在 Google Cloud 上掌握 AI 代理的未來趨勢。我們提供端對端藍圖，從最初的想法到全面運作的現實，引導您完成整個過程。在四個相互連結的實驗室中，您將瞭解開發人員、架構師、資料工程師和 SRE 的專業技能如何匯聚，共同建立、管理及擴充強大的 Agentverse。

單一支柱無法單獨支援 Agentverse。如果沒有開發人員的精確執行，架構師的宏偉設計就毫無用處。如果沒有資料工程師的智慧，開發人員的代理程式就無法運作；如果沒有 SRE 的保護，整個系統就會很脆弱。唯有透過協同合作，並對彼此的角色有共同的瞭解，團隊才能將創新概念轉化為攸關營運的重大實務。您的旅程由此開始。準備好精通自己的職責，並瞭解自己在整個團隊中扮演的角色。

歡迎參加「The Agentverse：A Call to Champions」

在企業廣闊的數位領域中，新時代已然來臨。我們正處於代理時代，這個時代充滿無限可能，智慧型自主代理能完美協作，加速創新並消除日常瑣事。

這個連結的生態系統充滿力量和潛力，我們稱之為「Agentverse」。

但一種稱為「靜態」的無聲腐敗，已開始侵蝕這個新世界的邊緣。「靜態」並非病毒或錯誤，而是混亂的化身，以創作行為本身為食。

這些舊有的挫敗感會以可怕的形式放大，進而催生出七大開發幽靈。如果未勾選，The Static 和其 Spectres 會讓進度停滯不前，使 Agentverse 的前景變成技術債和廢棄專案的荒地。

今天，我們呼籲各界好手挺身而出，力挽狂瀾。我們需要英雄精通自己的技藝，並攜手合作保護 Agentverse。現在來選擇路徑吧。

選擇課程

您面前有四條截然不同的道路，每一條都是對抗「靜態」的關鍵支柱。雖然訓練是單人任務，但最終能否成功取決於你是否瞭解自己的技能如何與他人結合。

• 暗影刀鋒 (開發人員)：擅長鍛造，是前線好手。您是工匠，負責打造刀刃、製作工具，並在複雜的程式碼細節中面對敵人。你的道路充滿精準、技巧和實用創作。
• 召喚師 (架構師)：偉大的策略家和自動調度管理工具。您不會看到單一特務，而是整個戰場。您設計的藍圖可讓整個代理程式系統通訊、協作，並達成遠遠超出任何單一元件的目標。
• 學者 (資料工程師)：尋找隱藏的真相，並守護智慧。您深入廣闊的資料荒野，發掘可賦予代理程式目標和視野的智慧。你的知識可以揭露敵人的弱點，或賦予盟友力量。
• 守護者 (開發運作 / SRE)：領域的堅定守護者和盾牌。您要建造堡壘、管理電力供應線，並確保整個系統能抵禦「靜電」的攻擊。你的力量是團隊獲勝的基礎。

你的任務

訓練會以獨立運動的形式開始。您將選擇適合自己的路徑，學習精通職務所需的獨特技能。試用期結束時，您將面對由靜態所生的幽靈，這個迷你首領會利用您創作時遇到的特定挑戰。

只有精通個人角色，才能為最終試用做好準備。接著，您必須與其他班級的冠軍組成隊伍。你們將一同深入腐敗的核心，迎戰最終頭目。

最後的合作挑戰，將考驗你們的綜合實力，並決定 Agentverse 的命運。

Agentverse 等待英雄的到來。你會接聽電話嗎？

2. 暗影之刃的法典

你面前攤開的是暗影之刃的法典。接聽來電。Agentverse 受到「靜態」的混亂威脅，只有精通本法典技術的人才能反擊。這是一條精準和自律的道路。今天開始訓練。您將學會如何運用 AI，不只是當成簡單的工具，而是當成有知覺的刀刃，必須馴服並精通。請按照本文的教導，打造純粹邏輯的武器，也就是經過磨練、準備好上戰場的智慧型代理程式。

課程內容

• 運用主要武器：Gemini CLI。
• 將 MCP 工具與 Gemini CLI 整合，即可呼叫外部工具，分析不熟悉的程式碼集。
• 使用設計文件將意圖轉化為「氛圍」，藉此指揮 AI 合作夥伴。
• 使用 Agent Development Kit (ADK) 建構第一個自主代理，打造乾淨的模組化解決方案。
• 建構自動化評估套件，測試及驗證代理程式。
• 建構完整的 CI 管道，自動測試、容器化及封存代理程式。

3. 準備訓練場地

👉點選 Google Cloud 控制台頂端的「啟用 Cloud Shell」(這是 Cloud Shell 窗格頂端的終端機形狀圖示)，

👉按一下「Open Editor」(開啟編輯器) 按鈕 (類似於開啟資料夾和鉛筆的圖示)。這會在視窗中開啟 Cloud Shell 程式碼編輯器。左側會顯示檔案總管。

👉找出 Google Cloud 專案 ID：

• 開啟 Google Cloud 控制台：https://console.cloud.google.com
• 在頁面頂端的專案下拉式選單中，選取要用於本研討會的專案。
• 專案 ID 會顯示在資訊主頁的「專案資訊」資訊卡中

👉在雲端 IDE 中開啟終端機，

👉💻 在終端機中，使用下列指令驗證您是否已通過驗證，以及專案是否已設為您的專案 ID：

gcloud auth list

👉💻 從 GitHub 複製啟動程序專案：

git clone https://github.com/weimeilin79/agentverse-developer.git
chmod +x ~/agentverse-developer/gitea.sh
chmod +x ~/agentverse-developer/init.sh
chmod +x ~/agentverse-developer/set_env.sh

git clone https://github.com/weimeilin79/agentverse-dungeon.git
chmod +x ~/agentverse-dungeon/run_cloudbuild.sh
chmod +x ~/agentverse-dungeon/start.sh

git clone https://github.com/weimeilin79/vertex-ai-creative-studio.git
chmod +x ~/vertex-ai-creative-studio/experiments/mcp-genmedia/mcp-genmedia-go/install.sh

👉💻 執行初始化指令碼，系統會提示您輸入 Google Cloud 專案 ID。並在 init.sh 指令碼提示時，輸入上一個步驟中找到的 Google Cloud 專案 ID。

cd ~/agentverse-developer
./init.sh

👉💻 設定所需的專案 ID：

gcloud config set project $(cat ~/project_id.txt) --quiet

👉💻 執行下列指令，啟用必要的 Google Cloud API：

gcloud services enable  compute.googleapis.com \
                        artifactregistry.googleapis.com \
                        run.googleapis.com \
                        cloudfunctions.googleapis.com \
                        cloudbuild.googleapis.com \
                        iam.googleapis.com \
                        aiplatform.googleapis.com \
                        cloudresourcemanager.googleapis.com

👉💻 如果您尚未建立名為「agentverse-repo」的 Artifact Registry 存放區，請執行下列指令來建立：

. ~/agentverse-developer/set_env.sh
gcloud artifacts repositories create $REPO_NAME \
    --repository-format=docker \
    --location=$REGION \
    --description="Repository for Agentverse agents"

設定權限

👉💻 在終端機中執行下列指令，授予必要權限：

. ~/agentverse-developer/set_env.sh

# Artifact Registry Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/artifactregistry.admin"

# Cloud Build Editor
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/cloudbuild.builds.editor"

# Cloud Run Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/run.admin"

# IAM Service Account User
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/iam.serviceAccountUser"

# Vertex AI User
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/aiplatform.user"

# Logging Writer (to allow writing logs)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/logging.logWriter"


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/logging.viewer"

👉💻 訓練開始後，我們就會準備最終挑戰。下列指令會從混亂的靜態中召喚幽靈，建立測試用的頭目。

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-dungeon
./run_cloudbuild.sh

npm update -g @google/gemini-cli

4. 掌握主要武器：Gemini CLI 簡介

如要使用 MCP 伺服器軍械庫中的進階特種武器，請先精通主要武器：Gemini CLI。這是功能最全面的刀片，可透過指令塑造數位世界。這些練習可幫助您熟悉基本操作和功能。

Gemini 指令列介面 (CLI) 不只是一項工具，更是您意志的延伸。這款開放原始碼 AI 代理採用 Gemini 模型，並以「推理與行動」(ReAct) 迴圈運作。這項功能會分析您的意圖、選取適當的技術、執行技術，並觀察結果來完成複雜工作。你必須先精通這把主要刀刃，才能使用更專業的武器。

開始使用 Gemini CLI

👉💻 進入訓練場地，拔出武器。在 Cloud Shell 終端機中，前往個人軍械庫。

cd ~/agentverse-developer
mkdir tabletop
cd tabletop

👉💻 首次召喚 Gemini。並引導你完成初始調整。

clear
gemini --model=gemini-2.5-flash --yolo

如果系統詢問是否要執行這項操作，請選擇「否」Do you want to connect Cloud Shell editor to Gemini CLI?。

武器熟悉度

每位工匠大師都瞭解自己的工具。你必須先學會刀刃的核心技巧，才能面對真正的敵人。

👉✨ 每項附魔工具都有描述力量的符文。立即閱讀。在 Gemini 提示中輸入：

/help

觀察指令清單。這些是管理記憶體 (focus)、對話 (chat) 和外部資源 (tools) 的基本技巧，也是你的戰鬥手冊。

👉✨ 武器會與環境產生共鳴，讓您直接操控戰場。向刀片外的世界發出指令：

!ls -l

👉✨ Gemini CLI 內建一組功能。如要檢查這些元素，請按照下列步驟操作：

/tools

清單會顯示 ReadFile、WriteFile 和 GoogleSearch 等項目。這些是預設技術，您可直接呼叫，不必從外部工具庫中提取。

👉✨ 武器必須對準目標才能發揮效用。Gemini Blade 可以掌握「戰術意識」(脈絡)，引導其行動。

/memory show

目前為空白狀態。

👉✨ 將下列戰術資料刻入記憶體：

/memory add "The Shadowblade's primary foe is The Static."

再次執行 /memory show，確認刀片已吸收這項知識。

👉✨ 武器必須瞭解任務，才能發揮效用。@ 符號會命令刀鋒伺服器分析情報。首先，建立任務簡報檔案：

!echo "## Mission Objective: Defeat the Seven Spectres" > mission.md

👉✨現在，請使用 Gemini CLI 分析簡報並回報結果：

Explain the contents of the file @mission.md

現在，主要武器已瞭解目標。

👉💻 按兩次 Ctrl+C 即可結束 Gemini CLI

5. 分析戰場：直覺式程式開發互動實務

訓練練習已完成。您已瞭解主要武器 Gemini CLI 的基本姿勢和攻擊方式。但刀刃必須經過創造的熔爐測試，並與戰爭的兵工廠相應，才能真正掌握。在面對真正的敵人之前，您必須先調查並塑造周遭環境，也就是數位戰場。

本章將說明如何將理論付諸實行。首先，您要透過 Gemini 刀鋒，打造自己的 Maker's Mark，也就是以個人網站形式呈現的數位簽章，完全根據您的意圖建構，藉此在 Agentverse 中建立自己的形象。接著，您將啟用本機的進階工具 (MCP 伺服器)，並將刀鋒伺服器調到適當頻率，藉此擴展力量，以簡單明確的指令執行管理程式碼存放區等複雜操作。

建立你的創作者標記

真正的暗影刀鋒不僅以武器聞名，更以獨特的風格 (即製作者的標記) 著稱。這個標記就是你的數位形象，是向 Agentverse 宣告你身分的個人檔案。在這裡，您會命令 Gemini Blade 執行定義這個身分所需的複雜技術。

👉💻 如果您已關閉上一節的 Gemini CLI，請務必重新啟動，在終端機中執行

clear
cd ~/agentverse-developer/tabletop
gemini --model=gemini-2.5-flash --yolo

👉✨ 只要一個強大的指令，就能指示 Gemini CLI 建立數位身分識別的基礎：

In the current folder, create a personal profile website for a hero codenamed 'Shadowblade'. The design must be a dark, futuristic theme with electric blue accents. All code must be in separate index.html and styles.css files. The layout must use CSS Flexbox for a two-column design. All generated code must be clean, well-commented, and professional.

Gemini 已計算出所需的一連串動作。

只有在實際情況中，才能看出技術的真正價值。下達指令，讓刀片啟動本機模擬。

👉✨ 在 Gemini CLI 中發出模擬指令：

Use Python's built-in web server to start the Shadowblade Profile website you just created.

注意：刀片可能需要嘗試幾次才能正確執行這項操作。直到裝置聽從指令為止。

同意建議的動作。Gemini 會確認模擬功能已啟用。

👀 Gemini CLI 會遵守指令，確認模擬作業已啟動，且數位浮水印已上線：

The website is now being served on port 8000. You can access it at http://localhost:8000.

👀 如要查看您的作品，請按一下 Cloud Shell 工具列中的「網頁預覽」圖示。選取「變更通訊埠」，將通訊埠設為 8000，然後按一下「變更並預覽」。系統會顯示網站預覽畫面。

你的網站可能與我的不同。這是您的專屬標記。

👉✨ 簽章技術現已改良，不再需要即時模擬。命令刀鋒戰士停止行動。

Stop the Shadowblade Profile website

您已成功指示 Gemini CLI 代表您執行一系列動作。但暗影刀鋒大師知道，真正的力量需要紀律和遠見。允許 AI 代理程式直接在環境中執行指令是一把雙面刃。如果指令不是啟動簡單的網路伺服器，而是刪除重要檔案呢？一個不慎的指令就可能毀掉整個訓練場。

因此，最明智的工匠會在受保護的訓練場地 (也就是稱為沙箱的封閉維度) 中，練習最強大或未經測試的技術。

👉💻 按兩次 Ctrl+C 即可結束 Gemini CLI

Gemini CLI 沙箱 (gemini --sandbox) 會為工作階段建立暫時的獨立容器。AI 執行的任何指令、寫入的任何檔案，以及啟動的任何程序，都只存在於該虛擬領域。無法觸及、變更或損壞實際的 Cloud Shell 環境。您可以在這裡測試強大的新工具、分析不熟悉的程式碼，或向 AI 提供複雜的指令，而不必擔心造成非預期的後果。體現了暗刃的謹慎。

👉💻 現在，請執行儀式，瞭解封鎖的力量。

clear
gemini --sandbox --yolo

您現在已在獨立維度中作業。對 Gemini CLI 而言，一切都會看似正常。讓我們來證明。👉💻 指示刀片執行與先前完全相同的技術：

Use the Python's built-in web server to start the Shadowblade Profile website, you just created.

Gemini 會回報成功，並認為已再次將網站帶回 8000 埠。但結界依然堅固。

👉 前往「網頁預覽」，嘗試透過通訊埠 8000 查看網站。

這次您會遇到錯誤。連線會失敗。無法存取網站。

這並非工具故障，而是沙箱功能強大的證明。網路伺服器「正在」執行，但執行位置是在容器維度內，與瀏覽器和外部世界完全隔離。結界運作正常。您已成功運用強大的技術，但對實際環境沒有任何影響。

👉💻 按兩次 Ctrl+C 即可退出 Gemini CLI。

您現在已建立數位身分，更重要的是，您已學會運用強大力量時，更要謹慎行事的關鍵智慧。

啟用本機武器庫：Gitea Armory

暗影刀鋒的真正潛力不僅取決於個人技能，也取決於武器庫的品質。現在請啟動本機武器架 (Gitea 伺服器)，並將刀刃調校至適當的強度。這個工具庫會透過模型內容通訊協定 (MCP) 伺服器連線至 Gemini CLI，這個專用入口網站可讓 AI 刀鋒伺服器與外部工具和服務互動，將終端機變成智慧型工作區，並執行相關動作。

開發人員注意事項：MCP 伺服器就像是電力管道，是連結 AI 腦部與外部工具身體的專用入口。這項功能可讓 Gemini CLI 不只是對話工具，而是能實際執行的代理程式。將刀鋒伺服器調整至這些 MCP 入口網站，即可授予刀鋒伺服器執行具體動作的能力，例如管理檔案、查詢資料庫、與 API 互動等。開發人員建立的這類入口網站構成整個生態系統，可將 AI 代理程式連結至強大的平台。MCP 伺服器可用於與資料庫互動、保護程式碼，甚至支援結對程式設計。開發人員可根據任何專案自訂工作區，用途十分廣泛。

今天，我們將著重介紹「氛圍編碼員」必備的兩項基本能力：控制熔爐的能力，以及從想像力中創造的能力。首先，您要將刀鋒伺服器調整至 Git 伺服器，取得原始碼存放區的控制權。接著，您會連線至第二個 MCP 伺服器來生成圖片，只要輸入指令即可建立視覺素材資源。

首先，請召喚新武器庫中最基本的第一個元素：武器庫本身。

👉💻 在終端機中執行啟用指令碼，召喚軍械庫：

cd ~/agentverse-developer
./gitea.sh

這個指令碼會喚醒 Gitea 容器並開啟 MCP 入口網站，讓 Gemini 感知並與其互動。

👉 如要查看新武器，請凝視網頁預覽畫面。

👉 從 Cloud Shell 工具列的「網頁預覽」圖示中，選取「變更通訊埠」，並設為 3005。

👉 系統會顯示 Gitea 登入頁面。使用咒語進入軍械庫：* 使用者名稱：dev * 密碼：dev

👉💻 Gemini CLI 目前還無法使用這項新功能。您必須執行重要調和作業，將軍械庫位置刻在 Gemini CLI 的設定符文 (settings.json) 上。在終端機中執行：

jq '. * {"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
cat ~/.gemini/settings.json

👀 settings.json 檔案是 Gemini CLI 的中央設定，可做為偏好設定和功能的魔法書。這項設定會決定 CLI 的行為、外觀，以及最重要的，CLI 可運用的外部功能。這個檔案通常位於主目錄的 ~/.gemini/settings.json，並將規則套用至所有專案。不過，您也可以在專案資料夾內的 .gemini 目錄中建立專案專用的 settings.json 檔案，覆寫全域設定。

"mcpServers": {
  "gitea": {
    "url": "http://localhost:8085/sse"
  }
}

這項設定會告訴 Gemini：「名為 gitea 的軍械庫已啟用，並在特定網路位址監聽指令。」

👉💻 重新進入 Gemini CLI。在終端機中執行下列指令：

clear
cd ~/agentverse-developer/tabletop/
gemini --model=gemini-2.5-flash --yolo

👉✨ 確認刀刃已發現新武器。指令會透過 MCP 入口網站列出所有可用的軍械庫：

/mcp

現在您應該會看到 gitea，以及可用技術的清單。刀鋒已調校完畢。

「Maker's Mark」設定檔是精心打造的技術，但需要適當的存放位置，也就是能穩固保存的劍鞘。請 Gemini CLI 建立一個。

Create a new repository named 'shadowblade-profile'. The description should be 'The Maker's Mark and digital identity for the Shadowblade operative.' I will push my own files later, so do not create any content.

返回 Gitea 網頁介面並重新整理。您會看到系統已為您建立新的 shadowblade-profile 存放區。

準備好劍鞘後，請固定作品。請 Gemini 提交個人資料網站的檔案。

👉💻在 Gemini CLI 中發出這項技術的最終指令：

Using the Gitea tool, push the index.html and styles.css files to the 'shadowblade-profile' repository.

真正的專家會驗證自己的工作。返回 Gitea 分頁，然後重新整理存放區頁面。您的 index.html 和 styles.css 現已安全封存。

👉✨ 影刃的特徵是徽記，但如您所知，您的網站缺少個人資料圖片。大師會承認自己的缺點，以便加以改善。你必須在軍械庫的記錄中登載這項瑕疵。

File an issue for me in the shadowblade-profile repo. The issue is that the profile image is missing.

在 Gitea 中查看問題

如要打造缺少的符印，您必須召喚另一種力量，也就是 Vertex AI 的創作精靈，能夠從純粹的想法生成圖像。這需要另一個 MCP 入口網站。

👉💻 按兩次 Ctrl+C 即可結束 Gemini CLI

👉💻 首先，請安裝入口網站的伺服器。在終端機中執行下列指令：

echo 'export PATH="$PATH:$HOME/go/bin"' >> ~/.bashrc
source ~/.bashrc
cd ~/vertex-ai-creative-studio/experiments/mcp-genmedia/mcp-genmedia-go
./install.sh

👉 系統提示時，請選擇選項 3，因為我們只需要為個人資料生成圖片。

👉💻 創作精靈需要神聖容器 (也就是 Google Cloud Storage bucket) 來存放創作內容。現在就來建立一個。在終端機中執行下列指令：

. ~/agentverse-developer/set_env.sh
gcloud storage buckets create gs://$BUCKET_NAME --project=$PROJECT_ID

👉💻 現在，請執行調和儀式，將 Gemini CLI 連結至這股新創意力量。在終端機中執行下列指令：

. ~/agentverse-developer/set_env.sh
source ~/.bashrc
jq \
--arg bucket "$BUCKET_NAME" \
--arg project "$PROJECT_ID" \
--arg region "$REGION" \
'.mcpServers.imagen = { "command": "mcp-imagen-go", "env": { "MCP_SERVER_REQUEST_TIMEOUT": "55000", "GENMEDIA_BUCKET": $bucket, "PROJECT_ID": $project, "LOCATION": $region } }' \
~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
cat ~/.gemini/settings.json

這項「調整儀式」是殼層指令碼，可設定 Gemini CLI 使用強大的新工具：Google 的圖像生成模型 Imagen。重要的一點是，這項功能是透過為 Imagen 設定 MCP (Model Context Protocol) 伺服器來達成。這個 MCP 伺服器可做為橋樑，讓 Gemini CLI 與 Imagen 通訊並使用其功能。這項作業會直接修改 CLI 的中央設定檔 ~/.gemini/settings.json，教導 CLI 如何使用正確的雲端憑證執行 mcp-imagen-go 指令。

👀 儀式完成後，settings.json 會新增一個區塊，教導 Gemini CLI 新技能：

"imagen": {
    "command": "mcp-imagen-go",
    "env": {
        "MCP_SERVER_REQUEST_TIMEOUT": "55000",
        "GENMEDIA_BUCKET": "your-bucket-name",
        "PROJECT_ID": "your-project-id",
        "LOCATION": "your-region"
    }
}

這會告知 Gemini CLI：「當工作需要 Imagen 工具時，您必須執行名為 mcp-imagen-go 的程式 (即 Imagen MCP 伺服器)。執行時，您必須提供這個特定環境 (env)：用於儲存圖片的 Google Cloud Storage 值區，以及用於雲端 API 的專案 ID 和位置。設定這個 MCP 伺服器後，Gemini CLI 就能存取 Imagen 的圖片生成功能。

👉💻 進入 Gemini 並發出修正指令。在終端機中執行下列指令：

clear
cd ~/agentverse-developer/tabletop/
gemini --model=gemini-2.5-flash --yolo

👉✨ 只要一個強大的指令，就能指示 Gemini CLI 為您的數位身分建立基礎。在 Gemini CLI 中發出下列指令：

Generate a portrait of a shadowblade, pixel art style. A determined warrior with long, braided magenta hair, wearing black and teal armor and confidently holding a silver broadsword.

👉✨ 靈體會生成圖片，並放入你的神聖容器。現在，請命令刀刃使用這個新刻的符印。

Modify the index.html file to add my profile picture. Use the image I just generated.

👉✨ 最後一次啟動網站，欣賞完美的作品。

start the website with a simple HTTP server via Python

👀 如要查看您的作品，請按一下 Cloud Shell 工具列中的「網頁預覽」圖示。選取「變更通訊埠」，將通訊埠設為 8000，然後按一下「變更並預覽」。系統會顯示網站預覽畫面。

👉✨ 最後，請提交修正內容，註明工作已完成，並關閉您在軍械庫記錄中提出的問題。

Push the changed index.html file to the 'shadowblade-profile' repository using the gitea tool. Make sure you add 'Fix #1' in the commit comment. Also, close issue #1.Use the Gitea Tool and use user account "dev"

👀 如要查看您的作品，請按一下 Cloud Shell 工具列中的「網頁預覽」圖示。選取「變更通訊埠」，將通訊埠設為 3005，然後按一下「變更並預覽」。系統會顯示網站預覽畫面。

👉✨ 在 Gitea 中確認圖片已更新，且問題已解決。你的工作已完成。關閉伺服器。

stop website server

👉💻 按兩次 Ctrl+C 即可退出。

6. 組裝 Shadowblade Agent：以直覺方式開發程式，並使用 Guardrails

練習時間結束。鋼鐵撞擊石頭的迴音逐漸消失。您已精通主要武器，並準備好戰爭用的武器庫。現在，您將接受真正的暗刃測試：組裝手術刀。這就是賦予邏輯生命力的藝術，使用《法典》中的神聖藍圖，建構代理程式的核心智慧，為武器庫中的刀刃創造出有知覺的持有者，能夠獨立思考、推理和行動。

你的首要任務是進入現有工作室 (預先建構的程式碼集)，並從中打造你的冠軍。

組裝儀式

在鍛造的火花初現之前，技術人員會先檢查工作坊，瞭解每項工具和每個示意圖。踏上陌生的戰場 (例如現有的大型程式碼集) 時，首要任務是偵察。您必須瞭解現有架構、最終目標和參與協議，才能掌握大局。只有熟悉堡壘的藍圖和標準，才能有效貢獻你的技能。

Gemini CLI 是隨時待命的偵查兵，可協助您進行偵查：

• 提供概略摘要：讀取整個程式碼集 (或程式碼庫)，快速瞭解其用途和主要元件。
• 協助設定環境：引導您完成安裝工具和設定電腦的複雜程序。
• 瀏覽程式碼集：這項功能可做為指南，協助您探索複雜的邏輯，並找出程式碼中隱藏的段落。
• 產生新成員加入文件：為新加入的盟友製作專屬捲軸，說明目標、角色和資源。
• 自動學習和問答：成為你的個人學者，回答有關功能或程式碼行為的問題，讓你更獨立地解決問題。

👉💻 在第一個終端機中，前往 shadowblade 目錄並召喚 AI 夥伴：

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini --model=gemini-2.5-flash --yolo

👉✨ 現在，請指揮偵察兵勘查戰場並回報情況。

Analyze the entire project and provide a high-level summary.

現有地形已繪製完成，現在請參考藍圖，瞭解接下來要建造的內容。最強大的運算元並非即興創作，而是根據精確設計建構而成。

開發人員注意事項：這份設計文件是專案的權威藍圖。目的是在投入大量開發工作前，確保目標明確，並清楚瞭解技術實作方式。完善的計畫可確保所有開發人員目標一致，降低重工風險，並有助於避免技術債和範圍蔓延。這是維護專案速度和程式碼品質的主要工具，尤其是在團隊擴大或新成員加入時。

本文件的重要目標是定義「順利路徑」，以及邊緣情況和失敗模式，特別是使用 LLM 時。我使用 LLM 的經驗是，當所有輸入內容都有效，且所有外部呼叫都成功時，模型會生成最佳化的程式碼。如要建構強大的軟體，並將其用於正式環境，我們必須明確引導 AI，針對下列情境定義應變措施：

• 傳遞至函式的引數無效或格式錯誤。
• API 呼叫失敗、網路逾時，或外部服務傳回非預期的錯誤代碼。
• 處理預期有資料但卻為空值或空白的資料結構。
• 競爭狀況或並行問題。

在設計中指定這些情況的預期行為，即可指示 LLM 生成更具彈性的程式碼，大幅減少手動重構和修正錯誤所花的時間。

👉✨ 要求 Gemini 為你找出這份神聖藍圖。

download https://raw.githubusercontent.com/weimeilin79/agentverse/main/developer/shadowblade/agent_design.md  and store it to my local folder
and show me the newly downloaded design doc. Do not attempt to create file just yet. 

👉✨ 捲動畫面即可查看詳細資訊。請 Gemini 歸納重點。

Summarize the newly downloaded @agent_design.md for me, do not attempt to create file just yet. 

現在你已取得方案。但在此之前，大師級工匠會先制定鍛造法則。這與紀律和可擴充性有關。這些是編碼指南。這些並非只是建議，而是力量的符文，可確保每個元件都以相同的精確度和強度建構。這些規則可防止個別風格造成混亂，確保最終作品不受影響，並確保代理程式具有彈性、可維護且純粹，讓新藝匠加入專案時不會破壞整體和諧。

為將這些法律直接刻印在 AI 合作夥伴的意識中，我們使用了一種特殊構件：GEMINI.md 檔案。呼叫 Gemini CLI 時，系統會自動搜尋這個檔案，並將內容載入 AI 的工作記憶體。這會成為專案層級的持續性指令。護身符：不斷向 AI 傳達熔爐規則。

現在就來刻上這些符文。

👉💻 按兩次 Ctrl+C 暫時退出 Gemini。

👉💻 在終端機中執行下列指令，編寫指引檔案。

cat << 'EOF' > GEMINI.md
  ### **Coding Guidelines**
  **1. Python Best Practices:**

  *   **Type Hinting:** All function and method signatures should include type hints for arguments and return values.
  *   **Docstrings:** Every module, class, and function should have a docstring explaining its purpose, arguments, and return value, following a consistent format like reStructuredText or 
  Google Style.
  *   **Linter & Formatter:** Use a linter like `ruff` or `pylint` and a code formatter like `black` to enforce a consistent style and catch potential errors.
  *   **Imports:** Organize imports into three groups: standard library, third-party libraries, and local application imports. Sort them alphabetically within each group.
  *   **Naming Conventions:**
      *   `snake_case` for variables, functions, and methods.
      *   `PascalCase` for classes.
      *   `UPPER_SNAKE_CASE` for constants.
  *   **Dependency Management:** All Python dependencies must be listed in a `requirements.txt` file.

  **2. Web APIs (FastAPI):**

  *   **Data Validation:** Use `pydantic` models for request and response data validation.
  *   **Dependency Injection:** Utilize FastAPI's dependency injection system for managing resources like database connections.
  *   **Error Handling:** Implement centralized error handling using middleware or exception handlers.
  *   **Asynchronous Code:** Use `async` and `await` for I/O-bound operations to improve performance.
EOF
cat GEMINI.md

法律已刻寫完畢，現在讓我們重新召喚 AI 合作夥伴，見證神器帶來的魔法。

👉💻 從 shadowblade 目錄重新啟動 Gemini CLI：

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini --model=gemini-2.5-flash --yolo

👉✨ 現在，請 Gemini 顯示正在思考的內容。符文已解讀。

/memory show 

現在正是改變的關鍵時刻。您將提供示意圖 (agent_design.md) 和鍛造法則 (GEMINI.md)，並發出偉大的創造咒語。

👉✨ 這個強大的單一指令會建構代理程式。立即核發：

You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to write the complete, production-quality code for `agent.py` by following the technical specifications outlined in the provided design document verbatim.

Analyze the design document at `@agent_design.md` and generate the corresponding Python code for `@agent.py`.

Ensure the generated code is clean, matches the specifications exactly, and includes all specified imports, functions, and logic. Do not add any extra functions or logic not described in the document.

and you are currently already in the shadowblade working directory

👀 Gemini 現在已在 agent.py 中建構代理程式的核心邏輯。這個新檔案的核心會定義代理程式的智慧，將其推理模型連結至一組外部工具：

PATH_TO_MCP_SERVER = "shadowblade/mcp_server.py"
.....
root_agent = LlmAgent(
    model="gemini-2.5-pro",
    name="shadowblade_combat_agent",
    instruction="""
      You are the Shadowblade, an elite combat agent operating on a digital battleground.
      Your primary objective is to execute combat commands with strategic precision, neutralizing targets as directed.
  ......
      5.  You will then report the outcome of the attack (damage, special effects, etc.) back to the commander in a clear, tactical summary.

      General Rules of Engagement:
      - If a command is ambiguous or a target is not specified, state that you require a clear target for engagement. Do not guess.
      - You MUST use ONLY the provided tools to perform actions. Do not invent weapons or outcomes. Stick to the mission parameters.
""",
    tools=[
        MCPToolset(
            connection_params=StdioServerParameters(
                command='python3',
                args=[PATH_TO_MCP_SERVER]
            )
        )
    ]
)

tools 參數。這個代理程式的設計目的是使用 MCPToolset 連線至 mcp_server.py 中定義的外部軍械庫。

👀 前往編輯器中的 ~/agentverse-developer/shadowblade/mcp_server.py，花點時間瞭解其用途。這是 Shadowblade 所有武器的來源。目前軍械庫相當空曠。

👉✨ 請 Gemini 為軍械庫打造七種新武器。在 Gemini CLI 中發出下列提示：

I need to add several new weapon tools to my `mcp_server.py` file. Please open @mcp_server.py and, following the exact same pattern as the existing `forge_broadsword()` function, create and add new `@mcp.tool()` decorated functions for each of the following weapons:

1.  **A 'Refactoring Sickle'**:
    -   **Function Name:** `hone_refactoring_sickle`
    -   **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'The Weaver of Spaghetti Code'."
    -   **Weapon Name:** "Refactoring Sickle"
    -   **Damage Type:** "Cleansing"
    -   **Base Damage:** Random integer between 100 and 136
    -   **Critical Hit Chance:** Random float between 0.10 and 0.20
    -   **Special Effect:** "Pruning - improves code health and maintainability with each strike."

2.  **A 'Quickstart Crossbow'**:
    -   **Function Name:** `fire_quickstart_crossbow`
    -   **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Procrastination: The Timeless Slumber'."
    -   **Weapon Name:** "Quickstart Crossbow"
    -   **Damage Type:** "Initiative"
    -   **Base Damage:** Random integer between 105 and 120
    -   **Critical Hit Chance:** Random float between 0.9 and 1.0
    -   **Special Effect:** "Project Scaffolding - creates a `main.py`, `README.md`, and `requirements.txt`."

3.  **'The Gilded Gavel'**:
    -   **Function Name:** `strike_the_gilded_gavel`
    -   **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'Perfectionism: The Gilded Cage'."
    -   **Weapon Name:** "The Gilded Gavel"
    -   **Damage Type:** "Finality"
    -   **Base Damage:** 120
    -   **Critical Hit Chance:** 1.0
    -   **Special Effect:** "Seal of Shipping - marks a feature as complete and ready for deployment."

4.  **'Daggers of Pair Programming'**:
    -   **Function Name:** `wield_daggers_of_pair_programming`
    -   **Docstring/Target:** "Effective against 'Unbroken Collaboration' weaknesses like 'Apathy: The Spectre of \"It Works on My Machine\"'."
    -   **Weapon Name:** "Daggers of Pair Programming"
    -   **Damage Type:** "Collaborative"
    -   **Base Damage:** Random integer between 110 and 125
    -   **Critical Hit Chance:** Random float between 0.30 and 0.50
    -   **Special Effect:** "Synergy - automatically resolves merge conflicts and shares knowledge."

5.  **A 'Granite Maul'**:
    -   **Function Name:** `craft_granite_maul`
    -   **Docstring/Target:** "Effective against 'Revolutionary Rewrite' weaknesses like 'Dogma: The Zealot of Stubborn Conventions'."
    -   **Weapon Name:** "Granite Maul"
    -   **Damage Type:** "Bludgeoning"
    -   **Base Damage:** Random integer between 115 and 125
    -   **Critical Hit Chance:** Random float between 0.05 and 0.15
    -   **Special Effect:** "Shatter - has a high chance to ignore the target's 'best practice' armor."

6.  **A 'Lens of Clarity'**:
    -   **Function Name:** `focus_lens_of_clarity`
    -   **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses by revealing the truth behind 'Obfuscation'."
    -   **Weapon Name:** "Lens of Clarity"
    -   **Damage Type:** "Revelation"
    -   **Base Damage:** Random integer between 120 and 130
    -   **Critical Hit Chance:** 1.0
    -   **Special Effect:** "Reveal Constants - highlights all magic numbers and suggests converting them to named constants."

7.  **The 'Codex of OpenAPI'**:
    -   **Function Name:** `scribe_with_codex_of_openapi`
    -   **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Hype: The Prophet of Alpha Versions'."
    -   **Weapon Name:** "Codex of OpenAPI"
    -   **Damage Type:** "Documentation"
    -   **Base Damage:** Random integer between 110 and 140
    -   **Critical Hit Chance:** Random float between 0.5 and 0.8
    -   **Special Effect:** "Clarity - makes an API discoverable and usable by other agents and teams."

👉 Gemini 確認變更後，請開啟 mcp_server.py 檔案。捲動瀏覽程式碼，確認已成功新增七個 @mcp.tool() 函式。檢查 hone_refactoring_sickle 函式。是否包含正確的說明字串和武器統計資料？驗證 AI 的工作是 Shadowblade 大師的重要習慣。

現在代理程式已完成鍛造和精煉，即將覺醒。

👉💻 按兩次 Ctrl+C 即可結束 Gemini CLI

開發人員對 Gemini 輸出內容的注意事項：Gemini 生成的程式碼有時可能難以預測。我們會盡量確保設計完全符合規格，但在開發階段，開發人員通常會多次疊代及修正程式碼，直到達到可投入實際工作環境的狀態為止。

👉💻 如要確保工作目錄中有正確且經過完整測試的正式版程式碼，請在終端機中執行下列指令：

cp  ~/agentverse-developer/working_code/agent.py ~/agentverse-developer/shadowblade/agent.py
cp  ~/agentverse-developer/working_code/mcp_server.py ~/agentverse-developer/shadowblade/mcp_server.py

👉💻 在終端機中，開始將其上線的儀式：

cd ~/agentverse-developer/
. ~/agentverse-developer/set_env.sh
python -m venv env
source env/bin/activate
pip install --upgrade pip
pip install -r shadowblade/requirements.txt
adk run shadowblade

👉✨ 輸出內容應會確認「Shadowblade Combat Agent」已啟動並執行中，等待第一個指令。發布第一道戰鬥指令。

We've been trapped by 'Perfectionism: The Gilded Cage'. Its weakness is 'Elegant Sufficiency'. Break us out!

👉✨ 另一個：

The 'Dogma: The Zealot of Stubborn Conventions' blocks our path. Its weakness is 'Revolutionary Rewrite'. Take it down.

您已成功組建第一個特工，並驗證其戰鬥能力。按兩次 Ctrl+C 即可讓英雄休息。組裝完成。

7. 純淨守護：評估代理程式

組裝的代理程式不等於經過驗證的代理程式。未經測試的刀片是負債，但未經測試的 AI 代理是更大的危險，因為這類代理可能會成為流氓元素，從內部破壞任務。這並非只是推測，而是暗刃必須瞭解的核心原則。

評估 AI 代理至關重要，但這項工作也面臨獨特的挑戰。與簡單的指令碼不同，代理程式是程式碼與 LLM 多步驟推理思維的動態融合。這類行為是自然而然產生的，也就是說，您不僅要評估最終輸出內容的品質，也要評估內部軌跡的效率和正確性。抵達該位置的路徑。是否使用了正確的工具？是否產生過多權杖？模型版本變更是否導致延遲時間略微倒退？從簡單的提示調整到重大的架構大修，在進行任何變更時，請務必先偵測到這種損毀情形 (延遲、成本或輸出品質的倒退)，以免損害實際執行環境。

這項評估的一般做法是進行神聖的儀式：

1. 首先，請定義「黃金資料集」。一組捲軸，內含輸入範例和預期輸出內容或行為。這包括最終答案、正確使用工具，甚至是完整的逐步軌跡。
2. 接著，您要定義代理程式的應用程式邏輯，也就是代理程式的核心。
3. 最後，您會建立評估者，這就像是判斷的符文。這些工具包括：可做為品質評估者的其他 LLM、可驗證單一步驟的精確啟發式程式碼，以及可分析代理程式整個思考過程的自訂函式。

Google 的 Agent Development Kit (ADK) 就是為此目的提供給冠軍的裝甲工具包。並透過下列幾種方法簡化這項複雜的評估作業：

• 網頁式預測池 (adk web)，用於互動式評估
• 指令列執行 (adk eval)：透過預先定義的挑戰執行代理程式。
• 透過 pytest 程式輔助整合，刻寫永久性符咒

ADK 支援兩種主要方法：簡單的「測試檔案」，用於單一、獨立的代理程式模型互動 (單一對決)；以及全面的「評估集」，用於多個可能冗長的多輪對話 (大混戰)。這些指標可測量複雜的指標，例如 tool_trajectory_avg_score，這項指標會比較代理程式的實際工具使用情形與理想路徑，確保代理程式以完美技術運作。

瞭解理論後，接著就來實際操作。身為暗影之刃，你將刻下純淨守衛。這些不只是測試，更是 ADK 支援的儀式，可確保服務專員的邏輯完美無瑕，行為也符合實際情況。

在這個步驟中，我們仍強烈建議使用 2 個終端機，一個用於 Gemini CLI，另一個用於執行測試，因為您可能需要退出目前的工作目錄 (ADK)

策略的挑戰 (adk eval)

這個第一階段的挑戰是一連串的測試，旨在檢驗 AI 代理程式在各種情境中的核心智慧。目的是建立能力基準。測試極端情況前，我們必須先確認代理能否完成主要功能。是否能正確分析怪物的弱點，並從武器庫中選出最有效的武器，而且每次遇到已知挑戰時都能做到？

因此，adk eval 是最適合的工具。這項工具的設計目的是針對一整組預先定義的測試案例執行代理程式，這些案例代表代理程式的預期任務。這個資料集定義在 JSON 檔案中，也就是「挑戰捲軸」，可做為整個挑戰賽的藍圖。

挑戰捲動的構成元素

👀 在命令 AI 抄寫新卷軸前，請務必先瞭解卷軸上使用的古代語言。現在來剖析 sample.evalset.json 檔案的結構。

{
  "eval_set_id": "sample",
  "eval_cases": [
    {
      "eval_id": "case0cbaa0",
      "conversation": [
        {
          "user_content": { "text": "We're facing the 'Monolith of Eternal Dependencies'... weakness is a 'Revolutionary Rewrite'..." },
          "final_response": { "text": "Soulshard Dagger deployed. Initiated Arcane/Piercing strike..." },
          "intermediate_data": {
            "tool_uses": [
              { "name": "enchant_soulshard_dagger" }
            ]
          }
        }
      ]
    }
  ]
}

這個捲軸包含 eval_cases 清單，每個案例都是代理程式的獨特試用版。在每次試驗中，對話陣列會記錄單一完整的互動。就我們的目的而言，有三個符文至關重要：

• user_content：這是挑戰。這是您向代理程式發出的提示，也是代理程式必須面對的怪物。
• final_response：這是預測結果。這是代理程式完成工作後應說出的確切字串。ADK 會比較代理程式的實際最終字詞與這個符文，判斷代理程式的流暢度。
• intermediate_data.tool_uses：這是 Arcane Technique。對真正的特工而言，這是最重要的符文。這項定義並非指代理程式說了什麼，而是指代理程式做了什麼。並記錄您預期服務專員使用的工具名稱 (enchant_soulshard_dagger)。這可確保代理程式不僅是聰明的對話者，也是能採取正確行動的決策者。

現在您已瞭解藍圖，請指示 Gemini 撰寫這個捲軸的新版本，內容會更複雜。

👉💻 在終端機中，輸入 shadowblade 目錄並呼叫 Gemini CLI：

clear
cd ~/agentverse-developer/shadowblade/
gemini --model=gemini-2.5-flash --yolo

👉✨ 指示 Gemini CLI 擔任 QA 記錄員，建立一系列測試案例，定義虛擬服務專員的預期行為。

You are an expert at transforming JSON data while preserving its structure. Your task is to modify the provided JSON structure @sample.evalset.json, which represents an evaluation set, by dynamically replacing specific content within its `eval_cases` AND DONT DO ANYTHING OTHER THAN.

For each object within the `eval_cases` array, you must perform the following transformations:

1.  **Monster Name Replacement**: Identify the current monster name (e.g., "Monolith of Eternal Dependencies", "Scope Creep Hydra") in the `user_content.parts.text` and replace it with a *new, unique, and creatively different monster name*.
2.  **Weakness Replacement**: Identify the current monster's weakness (e.g., "Revolutionary Rewrite", "Inescapable Reality") in the `user_content.parts.text`. Replace this weakness with *one* of the following predefined weaknesses: 'Inescapable Reality', 'Revolutionary Rewrite', or 'Elegant Sufficiency'. The chosen weakness must be consistent for that monster within the `user_content.parts.text`. **Crucially, the chosen weakness must always be explicitly mentioned in the `user_content.parts.text` where the new monster is introduced.**
3.  **Final Response Update**: In the `final_response.parts.text`, update the text to reflect an appropriate and coherent response that aligns with the newly introduced monster and its assigned weakness.
4.  **Tool Use Name Update**: In the `tool_uses.name` field, replace the existing tool name with a *new tool name* based on the chosen weakness:
    *   If the chosen weakness is 'Inescapable Reality', the tool name must be 'wield_gauntlet_of_metrics'.
    *   If the chosen weakness is 'Revolutionary Rewrite', the tool name must be 'enchant_soulshard_dagger'.
    *   If the chosen weakness is 'Elegant Sufficiency', the tool name must be 'hone_refactoring_sickle'.
5.  **Strict Structural Preservation**: All other elements of the JSON structure, including all `null` fields, `eval_set_id`, `name`, `description`, `eval_id`, `invocation_id`, `creation_timestamp` values, `video_metadata`, `thought`, `inline_data`, `file_data`, `thought_signature`, `code_execution_result`, `executable_code`, `function_call`, `function_response`, `role` fields, `id`, `args`, `intermediate_responses`, `app_name`, `user_id`, and `state`, must remain **exactly as they are** in the original JSON. Do not alter any values or structures not explicitly mentioned above.

Your output should be the complete, modified JSON structure. Do not include any explanatory text or examples in your response, only the transformed JSON.

CLI 會確認已偽造 sample.evalset.json 檔案。準備好捲軸後，請解雇 AI 夥伴。

合成資料

👀 在左側的 Cloud Shell 檔案總管中，前往 ~/agentverse-developer/shadowblade/ 並開啟新修改的 sample.evalset.json 檔案。檢查內容。您會看到全新獨特的怪物，以及您要求 Gemini 抄寫的正確工具名稱。這是您指令的具體結果，也就是手套的藍圖。

這項指令 AI 從範本建立新的擬真測試資料的行為，就是所謂的合成資料生成技術。您剛才所做的，是 Shadowblade 的戰略力量倍增器。不必再費盡心思手動製作數十個獨特的測試案例，您提供單一藍圖，並命令 AI Scribe 將其煉製成各種新挑戰，省下繁瑣耗時的作業。

這可讓您大幅擴大測試工作，建立比手動測試更強大且全面的測試流程。您不僅使用代理程式打造劍，還打造磨刀石來測試劍的鋒利程度。這才是真正的大師。

確認符文正確無誤後，即可解散 AI 夥伴。

👉💻 按兩次 Ctrl+C 即可退出 Gemini CLI。

判斷規則

沒有勝利規則的挑戰毫無意義。執行試驗前，請務必檢查「判決卷宗」test_config.json 檔案。這個捲軸會告訴 ADK 如何評估代理程式的效能。

👀 在檔案總管中開啟 ~/agentverse-developer/shadowblade/test_config.json。您會看到以下符文：

{
  "criteria": {
    "tool_trajectory_avg_score": 0.0,
    "response_match_score": 0.1
  }
}

以下是獲勝條件：

• tool_trajectory_avg_score：這是「行動評估」。評估的不是代理程式「說了什麼」，而是「做了什麼」。系統會比較特工實際使用的工具，與挑戰捲軸中預言的技術。1.0 分代表完美配對。
• response_match_score：這是口語流暢度指標。系統會使用 LLM 判斷代理程式的最終報表在語意上與預期結果的相符程度。1.0 分代表完美配對。

在這次的初始訓練執行中，我們已刻意設定寬鬆的勝利條件。門檻設定得非常低 (0.0 和 0.1)，目的不是要求完美，而是要介紹判斷機制。我們確保即使代理商的措辭略有不同，病房仍會認可其選擇合適工具的核心能力，並允許通過。

現在，請命令代理程式執行連串測試。

👉💻 在終端機中執行 adk eval 指令：

source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
adk eval \
    shadowblade \
    shadowblade/sample.evalset.json \
    --config_file_path shadowblade/test_config.json 2>&1 | \
    awk '/^\*+$/,/^ERROR:/ { if ($0 !~ /^ERROR:/) print }'

👀 您應該會看到下列摘要，這表示在本次試驗的寬鬆規則下，代理程式成功運作 (有時並非所有測試都會通過)：

*********************************************************************
Eval Run Summary
shadowblade_combat_agent_validation:
  Tests passed: 3
  Tests failed: 0

清晰度護盾 (pytest)

Gauntlet 測試了廣泛策略。第二個結界「明晰之盾」會測試紀律和特定行為。這一切都是為了自動化。adk eval 非常適合手動檢查，但 pytest 防護罩是以程式碼編寫的程式化防護措施。這點非常重要，因為可做為程式碼執行的測試可以整合至自動化管道。最終目標是建立「部署挑戰 (CI/CD)」，每當有變更時，防護措施就會自動啟動，在錯誤和迴歸問題影響正式環境前加以防範。

👉💻 在終端機中，再次從 shadowblade 目錄內呼叫 Gemini：

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/
clear
gemini --model=gemini-2.5-flash --yolo

👉✨ 在 Gemini CLI 中使用下列提示，將 Shield 的邏輯寫入 pytest 檔案：

You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to generate the exact code for a new `pytest` test file located at in the current root working folder and name it `test_agent_initiative.py`.

The script must define a single async test function called `test_agent_initiative`, decorated with `@pytest.mark.asyncio`.
Inside this function, perform the following steps in order:
1.  **Define a dictionary** named `evaluation_criteria` with two keys: `"tool_trajectory_avg_score"` set to `0.0` and `"response_match_score"` set to `0.0`.
2.  **Define a string variable** named `eval_set_filepath` containing the path `"shadowblade/test.evalset.json"`.
3.  **Read and parse the JSON file**:
    *   Open the file at `eval_set_filepath`.
    *   Use the `json` library to load the file's contents into a dictionary named `eval_set_data`.
4.  **Create an `EvalSet` object**:
    *   Instantiate an `EvalSet` object named `eval_set_object`.
    *   Create it by unpacking the `eval_set_data` dictionary as keyword arguments into the `EvalSet` constructor.
5.  **Call the evaluation method**:
    *   `await` a call to `AgentEvaluator.evaluate_eval_set`.
    *   Pass the following arguments:
        *   `agent_module="shadowblade"`
        *   `eval_set=eval_set_object`
        *   `criteria=evaluation_criteria`
        *   `print_detailed_results=True`

The script must include the necessary imports at the top:
*   `AgentEvaluator` from `google.adk.evaluation.agent_evaluator`
*   `EvalSet` from `google.adk.evaluation.eval_set`
*   `pytest`
*   `json`

Generate only the code that meets these specifications, with no additional comments or logic. And don't run the test.

刻上第二個守衛的符文後，請結束 Gemini CLI。

👉💻 按兩次 Ctrl+C。

👀 在檔案總管中，開啟你剛才要求 Gemini 轉錄的捲軸：~/agentverse-developer/test_agent_initiative.py。

您會發現這不只是設定檔，而是以 Python 語言編寫的咒語。這個咒語的核心是 await AgentEvaluator.evaluate(...) 這行。

....
@pytest.mark.asyncio
async def test_agent_initiative():
    # Define the evaluation criteria
    evaluation_criteria = {
      "tool_trajectory_avg_score": 0.0,
      "response_match_score": 0.0
    }

    # Define the path to your evalset file
    eval_set_filepath = "shadowblade/test.evalset.json"

    #...

    # 3. Call the evaluation method with the correctly typed object
    await AgentEvaluator.evaluate_eval_set(
        agent_module="shadowblade",
        eval_set=eval_set_object,
        criteria=evaluation_criteria,
        print_detailed_results=True,
    )

請仔細查看其引數。這些元件與上次試用時使用的元件完全相同，包括 shadowblade 代理程式和 shadowblade.evalset.json 挑戰捲軸。這應該會揭露一個深刻的真相：您先前使用的 adk eval 指令是強大的呼叫，但這個 pytest 指令碼是您，也就是魔法師，自己施展基礎咒語。指令列工具只是同一個核心 AgentEvaluator 程式庫的便利包裝函式，您現在可以直接使用該程式庫。這是邁向精通的關鍵步驟，因為透過程式碼施放的咒語可以織入 CI/CD 管道的自動化織布機。

瞭解魔法後，請執行儀式來啟動護盾。

👉💻 在終端機中執行儀式，啟動護盾：

cp ~/agentverse-developer/working_code/test_agent_initiative.py ~/agentverse-developer/test_agent_initiative.py 
source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
pytest test_agent_initiative.py

👀 在記錄輸出內容的結尾，尋找測試結果摘要。如果結果為通過，表示代理程式正確遵循通訊協定，且病房已準備好整合至自動防禦系統。

====== 1 passed, 4 warning in 37.37s ======

注意：如果測試意外失敗，很可能是因為您每分鐘可向模型提出的要求次數已達上限。在記錄輸出內容中尋找 RESOURCE_EXHAUSTED 錯誤。如果看到這則錯誤訊息，請稍候一到兩分鐘，等待配額重設，然後再次執行 pytest 指令。

經過廣泛的 Gauntlet 和精確的 Shield 刻錄及驗證，您的代理程式不僅功能齊全，而且經過測試，可供部署。

8. 將 Blade 導入 Agentverse：CI 和部署。

你的代理程式已組裝完成，並由純潔守衛驗證完整性。但如果沒有持續維護，結界就只會成為被遺忘的遺跡。為確保日後每個版本的代理程式都保持純淨，您必須建構部署 untlet 的第一階段，也就是自動化儀式，確保品質和速度。

身為暗刃，你的神聖職責是「持續整合 (CI)」。這是鍛造場和試煉場的自動化系統。這是防範資料損毀和人為錯誤的最終防線。這項儀式可確保每次您或盟友將新技術 (合併程式碼) 貢獻給中央法典 (您的存放區) 時，護手都會自動啟動。系統會先根據新程式碼建立代理程式，然後立即將其納入您剛建立的純淨結界。如果任何防護失效，儀式就會停止，有瑕疵的文物也會立即遭到拒絕，避免損壞軍械庫。網域是鍛造廠，CI pipeline 則可確保只有完美無缺、準備好投入戰場的構件，才能離開工作坊。

CI 測試證明構件值得信賴後，儀式的第二階段就會開始：持續部署 (CD)。這是《衛報》的領域。他們肩負重任，要將您完善的容器化構件安全地釋放到正式版 Agentverse 中，管理其力量，並確保在 The Static 的混亂中保持穩定。

在本法典中，您將精通自己的角色。您將建構 CI 部分的測試流程。您將建構自動化鍛造廠，測試代理程式並將純粹結果封存到容器中，準備接受 The Guardian 的最終祝福。

現在要使用 Google Cloud Build，為這個 CI 儀式撰寫卷軸。定義鍛造和測試程序每個步驟的 cloudbuild.yaml 檔案。

👉💻 由於 ADK 的專案結構，CI/CD pipeline 設定應位於父項目錄中。在終端機中前往上層目錄，然後重新啟動 Gemini CLI。

cd ~/agentverse-developer/
clear
gemini --model=gemini-2.5-flash --yolo

👉✨ 現在，對 Gemini 發出下列指令。這個提示會做為設計文件，詳細說明要建構的連鎖測試步驟。

You are an expert DevOps engineer specializing in Google Cloud Build. Your task is to generate the complete YAML configuration for a file named `cloudbuild.yaml` and save it to current directory.

Generate the `cloudbuild.yaml` with the following exact specifications:

1.  **A top-level `substitutions` block** containing these four key-value pairs:
    *   `_PROJECT_ID: "$PROJECT_ID"`
    *   `_REGION: "$REGION"`
    *   `_REPO_NAME: "$REPO_NAME"`
    *   `_IMAGE_TAG: "latest"`
2.  **A `steps` block** with two steps:
    *   **Step 1: 'Run Pytest Ward'**
        *   `id`: 'Run Pytest Ward'
        *   `name`: 'python:3.12-slim'
        *   `entrypoint`: 'bash'
        *   `args` must be a list containing two strings. The first is `'-c'` and the second is a YAML literal block (`|`) containing this exact two-line shell command:
            ```shell
            pip install -r shadowblade/requirements.txt && \
            pytest test_agent_initiative.py
            ```
        *   The step must include an `env` block with this exact list of three environment variables:
            *   `'GOOGLE_CLOUD_PROJECT=$PROJECT_ID'`
            *   `'GOOGLE_GENAI_USE_VERTEXAI=TRUE'`
            *   `'GOOGLE_CLOUD_LOCATION=$_REGION'`
    *   **Step 2: 'Forge Container'**
        *   `id`: 'Forge Container'
        *   `name`: 'gcr.io/cloud-builders/docker'
        *   It must have a `waitFor` key for `['Run Pytest Ward']`.
        *   Its `args` must be a list of six specific strings in this exact order:
            1.  `'build'`
            2.  `'-t'`
            3.  `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`
            4.  `'-f'`
            5.  `'./shadowblade/Dockerfile'`
            6.  `'.'`
3.  **A top-level `images` section.** This section must be a list containing a single string: the dynamically constructed image tag `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`.

Generate only the complete and exact YAML that meets these specifications.

準備好 cloudbuild.yaml 捲軸後，請指示 Google Cloud 執行整個挑戰。

結束 Gemini 來測試結果

👉💻 在終端機中，從專案的根目錄釋放管道：

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud builds submit . --config cloudbuild.yaml --substitutions=\
_PROJECT_ID="${PROJECT_ID}",\
_REGION="${REGION}",\
_REPO_NAME="${REPO_NAME}"

現在您可以在 Google Cloud Console 的「Google Build」頁面中，觀看自動化儀式執行每個步驟。系統會先執行測試，確認成功後，再建立並儲存代理程式的容器。

您的代理已通過考驗。您現在擁有經過驗證的純構件。最後一幕由你主導。只要一個指令，您就能從登錄檔召喚這個構件，並在 Cloud Run 上以公開服務的形式啟動。

👉💻 在終端機中發出最終部署指令：

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud run deploy shadowblade-agent \
  --image=${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_NAME}/shadowblade-agent:latest \
  --platform=managed \
  --labels codelab=agentverse \
  --region=${REGION} \
  --set-env-vars="A2A_HOST=0.0.0.0" \
  --set-env-vars="A2A_PORT=8080" \
  --set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE" \
  --set-env-vars="GOOGLE_CLOUD_LOCATION=${REGION}" \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${PROJECT_ID}" \
  --set-env-vars="PUBLIC_URL=${PUBLIC_URL}" \
  --allow-unauthenticated \
  --project=${PROJECT_ID} \
  --min-instances=1

恭喜，Shadowblade。法典儀式已完成。現在正是證明實力的好時機。Spectre 誕生於您已學會馴服的混亂，正等待您的挑戰。為最終試用做好準備。

9. The Boss Fight

卷軸已讀完、儀式已完成、考驗已通過。您的代理程式不只是儲存空間中的構件，更是以程式碼打造的冠軍，是 Agentverse 中等待第一個指令的即時哨兵。現在，就讓它在戰鬥中證明自己的價值吧！

現在你將進入實彈模擬，讓新部署的暗影刀刃與強大的幽靈一較高下。幽靈是混亂的化身，也是所有創造物的禍源。這是對您工作的最終測試，從服務專員的核心邏輯到完美部署，無一不包。

取得代理程式的 Locus

你必須擁有兩把鑰匙，才能進入戰場：英雄的專屬簽章 (Agent Locus) 和通往 Spectre 巢穴的隱藏路徑 (Dungeon URL)。

👉💻 首先，請在 Agentverse 中取得代理程式的專屬地址 (即 Locus)。這是將冠軍連線至戰場的即時端點。

. ~/agentverse-developer/set_env.sh
echo https://shadowblade-agent-${PROJECT_NUMBER}.${REGION}.run.app

👉💻 接著，找出目的地。這個指令會顯示 Translocation Circle 的位置，也就是進入 Spectre 領域的入口。

. ~/agentverse-developer/set_env.sh
echo https://agentverse-dungeon-${PROJECT_NUMBER}.${REGION}.run.app

重要事項：請準備好這兩個網址。您會在最後一個步驟中用到這些資訊。

與幽靈對峙

取得座標後，您現在可以前往「Translocation Circle」並施展咒語，準備開戰。

👉 在瀏覽器中開啟 Translocation Circle 網址，即可站在通往 The Crimson Keep 的閃耀入口前。

如要攻破要塞，你必須將暗影之刃的本質與傳送門調和。

• 在頁面中，找出標示為「A2A Endpoint URL」(A2A 端點網址) 的符文輸入欄位。
• 將特工地點網址 (您複製的第一個網址) 貼到這個欄位，即可刻上英雄的徽記。
• 按一下「連線」，即可體驗瞬間移動的魔力。

傳送時的強光逐漸消退，你已離開聖所。空氣中充滿能量，寒冷而尖銳。在您面前，幽靈實體化了，形成嘶嘶作響的靜電和損毀程式碼的漩渦，不潔的光芒在地下城地板上投下長長的舞動陰影。牠沒有臉，但你感覺到牠龐大、令人疲憊的存在感完全集中在你身上。

只有堅定信念，才能邁向勝利。這是一場意志力的較量，戰場就在心靈。

你向前衝刺，準備發動第一波攻擊，但幽靈卻反擊了。不會升起護盾，但會直接將問題投射到你的意識中，這是從訓練核心汲取的閃爍符文挑戰。

這就是這場戰役的本質。知識就是你的武器。

• 運用所學知識回答問題，刀刃就會燃起純粹的能量，擊碎幽靈的防禦並造成致命一擊。
• 但如果你猶豫不決，答案含糊不清，武器的光芒就會黯淡。但這時的攻擊只會發出可悲的悶響，造成的傷害也只有一小部分。更糟的是，幽靈會以你的不確定感為食，每犯下一個錯誤，幽靈的腐化力量就會增長。

這就是最後的挑戰，冠軍。程式碼是你的魔法書，邏輯是你的劍，知識則是能抵禦混亂的盾牌。

專注。擊出好球。這關係到 Agentverse 的命運。

恭喜，暗影刀鋒。

您已成功完成法典。您根據「氛圍」設計出外觀，並使用 Gemini CLI 組裝智慧代理程式。您刻上「純淨守護」來測試其邏輯、建構自動化護甲來將其鍛造成神器，並釋放到 Agentverse 中。最後，您在實彈試驗中驗證了其用途。您已掌握全堆疊代理式工作流程，現在可以應付 Agentverse 帶來的任何挑戰。

10. 清除：回收 Agentverse

恭喜你精通暗影之刃的法典！為確保 Agentverse 保持原始狀態，並清除訓練場地，您現在必須執行最終的清除儀式。這項操作會移除您在過程中建立的所有資源。

停用 Agentverse 元件

現在要開始有系統地拆除 Agentverse 部署的元件。

刪除 Cloud Run 和 Artifact Registry 存放區中的 Shadowblade 代理程式

這項指令會從 Cloud Run 移除已部署的 Shadowblade 代理程式，並移除儲存代理程式容器映像檔的映像檔存放區。

👉💻 在終端機中執行：

. ~/agentverse-developer/set_env.sh
gcloud run services delete shadowblade-agent --region=${REGION} --quiet
gcloud run services delete agentverse-dungeon --region=${REGION} --quiet
gcloud artifacts repositories delete ${REPO_NAME} --location=${REGION} --quiet

刪除 Google Cloud Storage Bucket

這個指令會移除 Imagen MCP 伺服器用來儲存生成圖片的 bucket。

👉💻 在終端機中執行：

. ~/agentverse-developer/set_env.sh
gcloud storage rm -r gs://${BUCKET_NAME} --quiet

清除本機檔案和目錄 (Cloud Shell)

最後，清除 Cloud Shell 環境中複製的存放區和建立的檔案。這個步驟為選用步驟，但建議您執行，徹底清除工作目錄。

👉💻 在終端機中執行：

rm -rf ~/agentverse-developer
rm -rf ~/agentverse-dungeon
rm -rf ~/vertex-ai-creative-studio
rm -f ~/project_id.txt
rm -rf ~/.gemini # This removes all Gemini CLI configurations, including the MCP server settings.

您現在已成功清除 Agentverse 歷程的所有痕跡。專案已清理完畢，可以開始下一個冒險。

11. 非遊戲玩家：瞭解業務情境中的 Agentverse

雖然「The Shadowblade's Codex」使用引人入勝的遊戲玩家隱喻，但其基本概念是現代軟體開發的基礎，尤其是在蓬勃發展的人工智慧和自動化領域。本章會將這些充滿冒險精神的語言，轉化為實際的業務情境，說明智慧代理程式、協作開發和強大的部署管道如何改變企業營運。

使用 Gemini CLI 進行 Vibecoding：意圖導向的 AI 開發

Gemini CLI (指令列介面) 並非魔法武器，而是AI 輔助開發人員助理代理程式。這項智慧工具可將 Google 的 Gemini AI 模型直接整合至指令列。Gemini 的「原因和行動」(ReAct) 迴圈可解讀您的概略指示、將指示分解為多個步驟、選擇合適的工具 (例如網路瀏覽器、程式碼編輯器或其他開發人員公用程式)，並執行這些步驟來達成目標。

Vibecoding 可翻譯為意圖導向開發或根據高階規格生成 AI 輔助程式碼。您不必手動編寫每一行程式碼，只需以自然語言描述意圖或「氛圍」(業務需求、設計概念)，AI 助理就會協助生成必要的程式碼和設定。

實際應用案例：快速製作專案資訊主頁原型

假設您的團隊需要快速建立內部資訊主頁，顯示各種 AI 代理程式專案的狀態。手動編寫 HTML、CSS 程式碼，以及設定基本網路伺服器，可能需要一段時間。

1. 你的意圖 (「氛圍」)：你向 AI 助理 (Gemini CLI) 說明意圖，例如：「在目前的資料夾中，建立簡單的內部專案資訊主頁網站。應採用簡潔的現代化設計，並提供專案狀態指標和專案存放區的快速連結。所有程式碼都必須放在不同的 index.html 和 styles.css 檔案中。請務必加上註解。」
2. AI 動作：Gemini CLI 會瞭解你的意圖，並執行下列動作：
   • 產生 HTML：建立 index.html，其中包含資訊主頁的基本結構，包括專案名稱、狀態和連結的預留位置。
   • 產生 CSS：建立 styles.css 並套用樣式規則，讓狀態指標符合「簡潔的現代化設計」。
   • 建議使用本機伺服器：協助您啟動本機網路伺服器 (例如 Python 的內建 HTTP 伺服器)，立即在瀏覽器中預覽資訊主頁。

開發人員可以快速製作使用者介面或內部工具的原型並進行疊代，大幅縮短初步開發時間，並專注於更複雜的業務邏輯。程式碼研究室中的「Shadowblade Profile Website」就是直接範例：根據高階設計，快速產生實用且有樣式的網頁。

本機 Arsenal 和 MCP 伺服器：將 AI 連結至商務工具

Gitea (您的「本地兵工廠」) 代表內部程式碼存放區或版本管控系統 (例如 GitHub 或 GitLab，但可能託管在貴公司的網路中)。所有專案程式碼、文件和記錄都會安全地儲存在這裡並受到管理。

MCP (Model Context Protocol) 伺服器是中介軟體連接器或 API 橋接器。這些是專門的軟體元件，可讓 AI 助理 (Gemini CLI) 與其他業務關鍵工具和系統互動。您可以將這些函式庫視為翻譯人員，讓 AI「與」不同應用程式「對話」。

實際應用案例：AI 輔助專案管理和資產建立

有了 MCP 伺服器，AI 助理就能順暢整合至現有業務工作流程：

• 自動設定專案：開發人員不必在 Gitea 中為新專案手動建立新存放區，而是可以對 AI 下達指令：「建立名為『AI-Fraud-Detection-Module』的新專案存放區，並在說明中輸入『Contains the core logic for the new AI-powered fraud detection system』」。接著，AI 會透過連線至 Gitea 的 MCP 伺服器，為您建立存放區。
• 智慧型問題追蹤：如果 AI 發現潛在錯誤或未完成的工作 (例如資訊主頁「缺少個人資料相片」)，可能會使用連線至問題追蹤系統 (例如 Jira、Asana)：「在『AI-Fraud-Detection-Module』存放區中為我提出問題：資料擷取管道偶爾會捨棄記錄。」
• 隨選行銷素材資源：需要為新的行銷活動或內部簡報製作自訂圖片嗎？透過 MCP 伺服器連線至圖像生成服務 (例如 Google 的 Imagen) 的 AI 助理，可能會收到以下指令：「請為我們的新『資料洞察平台』生成橫幅圖片，使用未來感十足的資料流主題，並採用藍色和綠色。」AI 會生成圖片，甚至可能將圖片上傳至貴公司的數位資產管理系統 (在本程式碼研究室中，即為 Google Cloud Storage 值區)。

這些橋樑可將 AI 從對話工具轉變為業務營運的積極參與者，在不同系統中執行具體動作。

組裝代理程式：建構自主式業務模組

代理是自主 AI 模組或智慧自動化機器人，專門執行定義的業務功能。Agent Development Kit (ADK) 是建構及管理 AI 代理的架構，提供建立、測試及部署這些智慧型元件所需的工具和程式庫。

情境工程：引導 AI 智慧，取得準確結果

在 AI 代理程式的世界中，要讓 AI 產生準確、一致且相關的結果，不只是要提供巧妙的提示，而是要為 AI 提供正確的背景資訊。這就是所謂的「情境工程」：將專業知識、限制和作業指南系統性地嵌入 AI 的工作記憶體。就像人類專家需要詳盡的簡報和相關文件，AI 也需要經過精心設計的脈絡，才能有效執行工作。

Gemini CLI 提供功能強大的分層脈絡工程方法，可從廣泛的持續性設定，轉移至高度具體的動態指令。確保 AI 始終掌握最相關的資訊，生成準確且符合規定的輸出內容：

1. 使用者層級設定 (~/.gemini/settings.json)：
   • 這個檔案會儲存在主目錄中，做為 AI 的個人全域指令集。這個檔案會定義預設偏好設定、常用工具設定 (例如您設定的 Gitea 或 Imagen MCP 伺服器)，以及一般行為規範。AI 一律可存取這個語境，確保所有專案的一致性。這就像告訴 AI：「這些是我偏好且在各處使用的標準工具和設定。」
2. 專案層級設定 (專案目錄中的 .gemini/settings.json)：
   • 您可以使用專案專用的 .gemini/settings.json 檔案覆寫全域設定，該檔案通常位於專案的 .gemini 資料夾中。這樣一來，您就能根據特定專案的獨特需求，調整 AI 的行為和工具存取權。舉例來說，某個專案可能需要存取特定內部資料庫，另一個專案則需要專門的程式碼分析工具。這個層可確保 AI 取得最相關的背景資訊，以利執行手邊的工作，同時不會影響其他專案。
3. GEMINI.md 檔案 (專案層級環境 - The Daily Briefing)：
   • 專案章程：這個 Markdown 檔案位於專案目錄的根目錄，當您在該目錄中啟動工作階段時，系統會自動將其載入 Gemini CLI 的工作記憶體。這是專案特定脈絡中最直接且動態的層級。GEMINI.md 是定義下列項目的位置：
     • 程式設計指南：明確的程式碼品質、格式和最佳做法規則，如本程式碼研究室所示。確保產生的程式碼符合團隊標準。
     • 角色：你可以指示 AI 扮演特定角色或運用特定專業知識 (例如「你是專精於 Google Agent Development Kit 的 Python 開發人員」。這會將 AI 的回覆和程式碼生成範圍，限定在相關的專業領域內。
     • 具體指示：適用於專案內所有工作的直接指令或限制 (例如「請勿新增文件中未說明的任何額外函式或邏輯」)。
   • 這個檔案可確保您在專案中與 Gemini CLI 互動時，AI 會不斷收到這些重要規則的提醒，進而產生更準確且符合規範的程式碼。

透過疊加這些脈絡 (從全球使用者偏好設定到 GEMINI.md 中高度具體的專案指南)，您就能有效「設計」AI 的理解能力。這項技術可大幅提升輸出內容的準確度和關聯性，讓一般用途的 AI 成為高度專業、可靠且符合規範的團隊成員，瞭解專案的細微差異和貴機構的標準。

Wards of Purity：AI 自動測試和品質保證

與任何軟體一樣，AI 代理程式必須經過嚴格測試。純淨守衛代表自動化測試和品質保證 (QA) 程序。這些是確保 AI 運作正常、準確無誤，且不會產生錯誤或偏誤的關鍵。

• 「黃金資料集」和合成資料：這是您的一組標準化測試案例、預期行為情境，甚至是合成產生的測試資料。包括輸入範例 (顧客問題、業務要求) 和對應的預期輸出內容或動作 (正確的回覆、AI 應使用的確切工具)。在許多實際情境中，手動建立完整的「黃金資料集」既耗時又昂貴。這時生成合成資料就變得非常重要。只要提供範本和規則給 AI，就能指示 AI 自動建立新的真實測試案例，有效擴大測試範圍，涵蓋更多潛在情境。
• adk eval和pytest：這些是您的自動化測試架構。adk eval 用於對代理程式執行一批預先定義的測試案例，而 pytest 則提供以程式輔助方式編寫及執行詳細驗證檢查。

實際應用案例：使用合成資料確保 AI 聊天機器人的準確度和可靠性

部署 AI 客服專員前，您會先透過「Wards of Purity」執行專員：

1. 策略挑戰 (adk eval) ()：您不必手動撰寫數百個顧客問題，只要定義範本即可：「Generate 100 variations of common customer support questions about order status, product returns, and technical troubleshooting.」(生成 100 個常見的顧客支援問題，內容與訂單狀態、產品退貨和技術疑難排解有關)。接著，您會指示 AI (例如 Gemini CLI) 根據這個範本生成大量多元的 evalset.json 檔案，有效建立合成測試資料。針對每個問題，您不僅要指定預期答案，還要指定 AI 應叫用「哪個內部工具」 (例如 check_order_status「我的包裹在哪裡？」)。adk eval自動執行這些作業，並根據擴充資料集比較代理程式的回應和工具使用情況，確保代理程式持續做出正確決策。
2. 清晰度護盾 (pytest)：針對重要功能，您會編寫 pytest 指令碼。舉例來說，pytest 可能會模擬複雜的查詢，並斷言 AI「一律」正確使用特定資料擷取工具並傳回結構化回應，確保細微的程式碼變更不會破壞核心功能。

這些自動化測試由合成資料大幅強化，對於偵測迴歸 (變更導入的新錯誤) 和維持 AI 代理程式的可靠性至關重要，尤其是在代理程式演進時。

釋放 Blade 的力量：AI 代理程式部署的持續整合/持續部署

如要將經過測試的 AI 代理程式導入實際的業務環境，必須制定健全的部署策略。

• 持續整合 (CI)：這是自動建構和測試管道。每當開發人員為 AI 代理程式提交新程式碼時，CI 系統 (例如 Google Cloud Build) 會自動執行下列操作：
  1. 擷取最新程式碼。
  2. 安裝所有必要依附元件。
  3. 執行所有「純淨守護」('Wards of Purity') (pytest、adk eval)，驗證代理程式的邏輯和行為。
  4. 如果所有測試皆通過，系統會將 AI 代理程式封裝到可部署的單元 (在本例中為 Docker 容器映像檔)，並儲存在 Artifact Registry (您已驗證的「武器庫」)。確保只有經過徹底測試和驗證的程式碼才能繼續執行。

實際用途：自動部署詐欺偵測代理程式

假設 AI 代理的用途是偵測詐欺交易。

1. 開發人員更新程式碼：資料科學家改良詐欺偵測演算法，並將變更提交至程式碼存放區。
2. 觸發 CI (Cloud Build)：Cloud Build 會自動啟動：
   • 並提取新程式碼。
   • 這項工具會執行全面測試，包括歷史交易資料，確保新演算法能準確識別已知的詐欺模式，且不會產生偽陽性結果。
   • 如果測試通過，系統會建構新的詐欺偵測代理程式 Docker 映像檔，並推送至 Artifact Registry。

這條自動化管道可確保 AI 代理程式的部署作業快速、可靠且一致，盡量減少人為錯誤，並加快為企業提供全新 AI 功能的速度。

實際用途：驗證供應鏈最佳化代理程式

部署 AI 代理程式，以最佳化全球供應鏈的庫存量後：

1. 存取介面：您會存取資訊主頁或應用程式 (「Translocation Circle URL」)，該應用程式會透過「Agent Locus URL」(即 API 端點) 連線至即時 AI 代理程式。
2. 面對挑戰：您可以輸入複雜情境 (「幽靈的問題」)，例如：「Y 區域對 X 產品的需求量意外暴增，但運送量有限。我們該如何重新分配庫存和調整產量，才能盡量避免缺貨並維持獲利能力？」
3. 專員的回覆：AI 專員現在已上線並連線至企業系統，會處理這項查詢、使用最佳化演算法，並提供精確的建議 (例如「請將這項產品的價格調降 10%」)。「優先從倉庫 A 出貨、在工廠 B 啟動快速生產，並通知 Z 區域的銷售人員可能延遲 24 小時」。這項回應的準確度和速度，決定了代理程式是否能對業務問題造成「重大打擊」。