Gemini CLI Self Learning

gemini_cli_self_learning_guide_zh.md

Gemini CLI 代理人開發全攻略 (自學版)

本指南專為希望自學掌握 Gemini CLI 的學習者設計。每個章節都建立在前一章節的基礎之上，提供詳細的解釋、範例和實用技巧。

---

1. Gemini CLI 簡介

它是什麼？ Gemini CLI 是一個功能強大的對話式命令列介面，將 Google Gemini 模型的能力直接帶到您的終端機。它專為開發人員、系統管理員以及任何大量使用命令列工作的人而設計。它可以透過自然語言幫助您編寫程式碼、管理檔案系統、執行命令和自動化複雜任務。

它是為誰設計的？

• 軟體工程師：用於編碼、除錯和重構。
• DevOps / SREs：用於編寫腳本、管理基礎設施和自動化部署。
• 資料科學家：用於資料分析、編寫腳本和視覺化。
• 技術文件撰寫人員：用於產生文件和範例。

核心理念： 您不再需要記住複雜的指令，而是可以告訴 CLI 您想做什麼。它會理解您的意圖，使用其工具（如讀取檔案或執行命令），並幫助您達成目標。

---

2. 安裝與設定

2.1. 安裝 Gemini CLI

（注意：這是一個假設的安裝指令。請參考官方文件以獲得實際的指令。）

# 範例安裝指令
npm install -g @google/gemini-cli

透過執行以下指令來驗證安裝：

gemini --version

2.2. 身份驗證

您需要授權 Gemini CLI 存取您的 Google 帳戶以使用 Gemini API。

• Login with Google (推薦): 這是最簡單的入門方式。CLI 將引導您在瀏覽器中完成 OAuth 流程。

  gemini auth login

• Gemini API Key: 對於非互動式環境（如 CI/CD），您可以使用 API 金鑰。
  1. 從 Google AI Studio 取得金鑰。
  2. 將其設定為環境變數：

     export GEMINI_API_KEY="YOUR_API_KEY"

• Vertex AI: 對於企業級應用，您可以設定 CLI 使用 Vertex AI 後端，以增強安全性、隱私和模型選擇。這通常涉及設定服務帳戶並將 CLI 指向您的 Google Cloud 專案。

---

3. 基本互動

3.1. 對話式介面

只需輸入您想做的事情，然後按 Enter。代理人將會解讀您的請求並作出回應。

範例：

列出當前目錄中所有的 python 檔案

3.2. / 斜線指令

斜線指令是給 CLI 本身的元指令，而不是給 AI 模型的。它們幫助您管理會話。

• /help: 顯示可用指令。
• /clear: 清除當前會話歷史。
• /status: 顯示當前狀態和設定。
• /exit: 退出 Gemini CLI。

3.3. @ 符號用於上下文

@ 符號用於引用本地檔案，並將其內容作為您請求的上下文。這對於詢問有關您程式碼的問題非常有用。

範例：

@main.py 這個檔案中的 main 函式用途是什麼？

CLI 將讀取 main.py 的內容，並將其與您的問題一起提供給模型。

3.4. ! Shell 模式

要直接執行 shell 指令，請在其前面加上 !。指令的輸出將被顯示，也可以用作 AI 的上下文。

範例：

!ls -l 根據上面的檔案列表，將所有 .txt 檔案建立一個 zip 壓縮檔。

---

4. 進階用法

4.1. 非互動模式 (CI 模式)

您可以將指令透過管道 (pipe) 傳遞給 Gemini CLI，以便在腳本或 CI/CD 流程中使用。這使您能夠自動化需要 AI 輔助的任務。

範例：

echo "重構 @utils.py 以提高可讀性並添加註解" | gemini

5. 深入理解設定

5.1. 設定檔的層級結構

Gemini CLI 使用層級系統來管理設定，允許全域、專案級和本地的覆寫。

1. 全域: ~/.config/gemini/config.json (使用者層級的設定)
2. 專案: 專案根目錄/.gemini/config.json (專案特定的設定)
3. 本地: .gemini.local.json (本地覆寫，應加入 .gitignore)

5.2. 環境變數與 .env 檔案

對於像 API 金鑰這樣的敏感資訊，最好使用環境變數。Gemini CLI 會自動從您專案根目錄中的 .env 檔案載入變數。

範例 .env 檔案：

GEMINI_API_KEY="your_secret_key"
VERTEX_AI_PROJECT="gcp-project-id"

5.3. 命令列參數

您可以使用命令列旗標覆寫任何設定。這對於一次性的指令或腳本很有用。

範例：

gemini --model=gemini-1.5-pro "總結 @large_file.txt 的內容"

---

6. 掌握工具調用

6.1. 工具的核心概念

工具是 Gemini 模型可以決定調用以獲取資訊或執行操作的函式。這就是代理人與您本地環境互動的方式（讀取檔案、執行命令等）。

6.2. 內建工具

CLI 附帶一組必要的內建工具。模型會根據您的請求智慧地選擇正確的工具。以下是可用的工具及其使用範例：

• list_directory: 列出檔案和目錄。

  範例提示: "顯示 src 目錄中的所有檔案。" 工具調用: print(default_api.list_directory(path='src'))

• read_file: 讀取單一檔案的內容。

  範例提示: "讀取 main.py 檔案並告訴我它的作用。" 工具調用: print(default_api.read_file(absolute_path='main.py'))

• search_file_content: 在多個檔案中搜尋模式。

  範例提示: "在所有 Python 檔案中尋找 calculate_total 函式的出現位置。" 工具調用: print(default_api.search_file_content(pattern='def calculate_total', include='*.py'))

• glob: 尋找符合特定模式的檔案。

  範例提示: "我需要查看專案中所有的 markdown 檔案。" 工具調用: print(default_api.glob(pattern='**/*.md'))

• replace: 取代特定檔案中的文字。

  範例提示: "在 config.yaml 中，將 debug 設定從 true 改為 false。" 工具調用: print(default_api.replace(file_path='config.yaml', old_string='debug: true', new_string='debug: false'))

• write_file: 將內容寫入新檔案或現有檔案。

  範例提示: "建立一個名為 hello.txt 的新檔案，內容為 'Hello, World!'。" 工具調用: print(default_api.write_file(file_path='hello.txt', content='Hello, World!'))

• web_fetch: 從 URL 擷取內容。

  範例提示: "總結 https://example.com/news/latest 這篇文章的要點。" 工具調用: print(default_api.web_fetch(prompt='Summarize https://example.com/news/latest'))

• read_many_files: 一次讀取多個檔案的完整內容。

  範例提示: "讀取 components 目錄中所有的 .ts 檔案，這樣我就可以問關於它們的問題。" 工具調用: print(default_api.read_many_files(paths=['components/**/*.ts']))

• run_shell_command: 執行 shell 指令。

  範例提示: "安裝這個專案的依賴項。" 工具調用: print(default_api.run_shell_command(command='npm install'))

• save_memory: 記住一個事實以供將來的互動使用。

  範例提示: "請記住我偏好的程式語言是 Python。" 工具調द用: print(default_api.save_memory(fact='My preferred programming language is Python.'))

• google_web_search: 執行網路搜尋。

  範例提示: "React 框架的最新版本是什麼？" 工具調用: print(default_api.google_web_search(query='latest version of React framework'))

6.3. 自訂工具 (MCP 伺服器)

對於進階使用者，您可以定義自己的自訂工具。這需要執行一個「模型可呼叫外掛」 (Model-Callable Plugin, MCP) 伺服器，將您的函式公開給 Gemini CLI。這使您能夠將 Gemini 與您自己的 API、資料庫或服務整合。

---

7. 使用 GEMINI.md 掌控記憶能力與上下文

7.1. GEMINI.md 是什麼？

GEMINI.md 檔案是一個強大的功能，它作為您在專案中所有互動的自動、持久性上下文。您可以把它想像成一本「專案聖經」，每次您在該目錄中啟動會話時，Gemini 代理人都會閱讀並理解它。

這意味著您不必重複說明專案的基本事實、架構指南或風格偏好。代理人已經知道了。

7.2. 隱性上下文的力量：一個範例

讓我們用一個範例來說明這個檔案如何讓您的工作流程更有效率。

假設這是您專案根目錄中 GEMINI.md 的內容：

# 專案指南：我的 Web App

## 技術棧
- 前端: React with TypeScript
- CSS: TailwindCSS
- 狀態管理: Redux Toolkit
- 測試: Jest and React Testing Library

## 編碼風格
- 使用帶有 hooks 的函式元件。
- 所有 props 都必須進行型別定義。
- 遵循 Airbnb JavaScript 風格指南。

## 重要事項
- `src/api` 目錄包含所有與後端互動的函式。
- 在提交 pull request 之前，請執行 `npm run lint` 和 `npm test`。

---

它如何改變您的提示

以下是您的問題如何變得更加直接和有效率。

之前 (沒有 GEMINI.md)：

您必須在每個提示中提供所有上下文，這既繁瑣又重複。

• 「請為使用者個人資料頁面建立一個新的 React 函式元件，使用 TypeScript。它應該有型別定義的 props 並使用 TailwindCSS 進行樣式設計。請確保它遵循 Airbnb 風格指南。」
• 「我的專案使用 Redux Toolkit 進行狀態管理，獲取使用者資料的最佳方式是什麼？」
• 「我需要為一個 React 元件編寫測試。我的專案使用 Jest 和 React Testing Library。你能為我產生一個範例測試檔案嗎？」

之後 (有 GEMINI.md)：

因為代理人已經吸收了檔案的內容，您可以提出簡單、直接的問題。

• 「建立一個新的使用者個人資料元件。」
  • （代理人知道要使用 React、TypeScript、函式元件、hooks、型別定義的 props 和 TailwindCSS，並遵循 Airbnb 風格指南。）
• 「我應該如何獲取使用者資料？」
  • （代理人知道您正在使用 Redux Toolkit，並會提供相關的答案，可能會建議從 src/api 目錄建立一個 thunk 或使用 RTK Query。）
• 「為這個元件寫一個測試。」
  • （代理人知道要使用 Jest 和 React Testing Library，並會相應地產生測試。）
• 「在提交 pull request 之前我需要做什麼？」
  • （代理人知道要告訴您執行 npm run lint 和 npm test。）

簡而言之，GEMINI.md 讓您不必重複解釋專案的架構和慣例，使您能與 Gemini 代理人進行更自然、更有效率的對話。

---

8. 沙盒機制以確保安全

8.1. AI 編碼與資安風險

允許 AI 在您的系統上執行命令和修改檔案帶有內在風險。惡意或有錯誤的回應可能會刪除檔案、洩露秘密或安裝惡意軟體。

8.2. 何時啟用沙盒機制

沙盒提供了一個受限制的環境，AI 可以在其中操作而無法完全存取您的系統。

在以下情況下，您應始終啟用沙盒：

• 處理不熟悉或不受信任的程式碼庫時。
• 執行模型建議的複雜檔案操作或 shell 指令時。
• 在監督有限的自動化環境中執行 CLI 時。

沙盒是一個至關重要的安全功能。寧可備而不用，不可用而無備。

---

9. 估算導入成本

使用 Gemini CLI 的成本主要基於底層 Gemini 模型的使用量。成本通常按 token（輸入和輸出）計算。

• 輸入 Tokens: 您傳送給模型的所有內容（您的提示、來自 @ 的檔案上下文、歷史記錄、GEMINI.md）。
• 輸出 Tokens: 模型的回應。

為了管理成本：

• 精確地提出您的提示。
• 使用 @ 僅引用您需要的檔案。
• 如果可用，為較簡單的任務使用較小的模型（例如 Gemini 1.5 Flash vs. Gemini 1.5 Pro）。
• 在您的 Google Cloud 控制台中監控您的使用情況。

---

10. 常見問題 (Q & A)

Q: 這與 ChatGPT 或其他網頁使用者介面有何不同？ A: 關鍵區別在於與您本地開發環境的深度整合。直接讀取/寫入檔案和執行命令的能力使其成為一個真正的「代理人」，能夠執行任務，而不僅僅是回答問題。

Q: 我可以離線使用嗎？ A: 不行。需要有效的網路連線才能與 Gemini API 通訊。

Q: 我如何看到模型正在做什麼？ A: CLI 對其使用的工具是透明的。它會向您顯示它何時正在讀取檔案或執行命令，並且在執行任何修改您系統的操作之前，它會請求您的確認。

Q: 我可以更換正在使用的 AI 模型嗎？ A: 可以，您可以在您的設定檔中或使用 --model 命令列旗標來指定模型。