Gemini CLI - 技術深度解析

🎯 開發動機與解決痛點

在現代軟體開發中，開發者經常需要處理大型程式碼庫、複雜的工作流程，以及重複性的操作任務。傳統的開發工具往往缺乏智慧化的理解能力，無法有效協助開發者理解複雜的程式碼邏輯或自動化繁瑣的操作流程。

                    核心痛點：
                    大型程式碼庫理解困難：傳統工具無法在大規模程式碼中快速理解業務邏輯和架構關係
重複性操作效率低下：手動執行檔案操作、shell 命令、和程式碼重構耗時且易出錯
工具整合複雜度高：不同開發工具之間缺乏統一的整合介面和工作流程
上下文切換成本：在 IDE、終端機、文件之間頻繁切換降低開發效率
缺乏智慧化輔助：現有工具無法根據專案脈絡提供智慧化的建議和自動化操作

                

Gemini CLI 解決了這些核心問題，提供了一個統一的、智慧化的命令列介面，能夠理解程式碼上下文、自動化複雜操作，並與各種開發工具無縫整合。透過 Gemini 的強大 AI 能力和 1M token 的大型上下文視窗，開發者可以在單一介面中完成從程式碼分析到自動化部署的完整工作流程。

🛠️ 技術框架與設計模式

🔧 TypeScript + Node.js

使用 TypeScript 提供強型別安全，Node.js 作為執行環境，確保跨平台相容性和豐富的生態系統支援。

⚛️ React + Ink

創新地使用 React 配合 Ink 函式庫打造終端機 UI，提供豐富的互動體驗和元件化開發模式。

🤖 Google Gemini API

深度整合 Gemini 2.5 Pro API，支援大規模上下文處理和多模態內容理解，提供智慧化的程式碼分析能力。

🔌 MCP 協議整合

支援 Model Context Protocol，提供可擴展的工具生態系統，允許第三方工具無縫整合。

📦 Workspace 單一儲存庫

採用 npm workspaces 管理多套件架構，包含 CLI、核心引擎、和 VS Code 擴充套件。

🛡️ 安全沙盒執行

支援 Docker 和 Podman 沙盒環境，確保程式碼執行的安全性和隔離性。

核心設計模式

🏭 工廠模式 (Factory Pattern)

ToolRegistry 類別作為工具工廠，負責建立和管理各種工具實例，支援動態工具發現和註冊機制。

🎯 策略模式 (Strategy Pattern)

不同的工具執行策略基於工具類型和確認需求，提供靈活的執行流程控制。

👁️ 觀察者模式 (Observer Pattern)

使用事件驅動的串流處理機制，即時處理 Gemini API 回應和工具執行狀態變化。

⚙️ 命令模式 (Command Pattern)

將工具調用封裝為命令物件，支援撤銷、重做、和批次執行操作。

🔄 狀態機模式 (State Machine Pattern)

工具調用生命週期管理，從驗證、排程、執行到完成的完整狀態轉換控制。

🔧 核心 API 客戶端實作

// 從 packages/core/src/core/geminiChat.ts 擷取
export class GeminiChat {
  private sendPromise: Promise<void> = Promise.resolve();

  constructor(
    private readonly config: Config,
    private readonly contentGenerator: ContentGenerator,
    private readonly generationConfig: GenerateContentConfig = {},
    private history: Content[] = [],
  ) {
    validateHistory(history);
  }

  async sendMessage(
    params: SendMessageParameters,
    prompt_id: string,
  ): Promise<GenerateContentResponse> {
    await this.sendPromise;
    const userContent = createUserContent(params.message);
    const requestContents = this.getHistory(true).concat(userContent);

    const response = await retryWithBackoff(apiCall, {
      shouldRetry: (error: Error) => {
        if (error && error.message) {
          if (error.message.includes('429')) return true;
          if (error.message.match(/5\d{2}/)) return true;
        }
        return false;
      },
    });
    return response;
  }
}

這段程式碼展示了 Gemini API 客戶端的核心實作，包含訊息發送、歷史管理、和錯誤重試機制，是整個系統與 AI 模型溝通的關鍵橋樑。

🏭 工具註冊系統設計

// 從 packages/core/src/tools/tool-registry.ts 擷取
export class ToolRegistry {
  private tools: Map<string, Tool> = new Map();

  registerTool(tool: Tool): void {
    if (this.tools.has(tool.name)) {
      if (tool instanceof DiscoveredMCPTool) {
        tool = tool.asFullyQualifiedTool();
      } else {
        console.warn(`Tool with name "${tool.name}" is already registered.`);
      }
    }
    this.tools.set(tool.name, tool);
  }

  async discoverTools(): Promise<void> {
    // 移除先前發現的工具
    for (const tool of this.tools.values()) {
      if (tool instanceof DiscoveredTool || tool instanceof DiscoveredMCPTool) {
        this.tools.delete(tool.name);
      }
    }
    await this.discoverAndRegisterToolsFromCommand();
    await discoverMcpTools(this.config.getMcpServers() ?? {});
  }
}

工具註冊系統採用工廠模式，支援動態工具發現和 MCP 協議整合，提供高度可擴展的架構設計。

🔄 狀態機式工具生命週期管理

// 從 packages/core/src/core/coreToolScheduler.ts 擷取
export class CoreToolScheduler {
  private setStatusInternal(
    targetCallId: string,
    newStatus: Status,
    auxiliaryData?: unknown,
  ): void {
    this.toolCalls = this.toolCalls.map((currentCall) => {
      switch (newStatus) {
        case 'success': {
          const durationMs = existingStartTime 
            ? Date.now() - existingStartTime 
            : undefined;
          return {
            request: currentCall.request,
            tool: toolInstance,
            status: 'success',
            response: auxiliaryData as ToolCallResponseInfo,
            durationMs,
          } as SuccessfulToolCall;
        }
        case 'awaiting_approval':
          return {
            status: 'awaiting_approval',
            confirmationDetails: auxiliaryData as ToolCallConfirmationDetails,
          } as WaitingToolCall;
      }
    });
    this.notifyToolCallsUpdate();
  }
}

採用狀態機模式管理工具調用生命週期，從驗證、排程、執行到完成的完整狀態轉換，確保系統的可靠性和可預測性。

🛡️ 安全的 Shell 執行機制

// 從 packages/core/src/tools/shell.ts 擷取
export class ShellTool extends BaseTool<ShellToolParams, ToolResult> {
  isCommandAllowed(command: string): { allowed: boolean; reason?: string } {
    // 禁止命令替換
    if (command.includes('$(')) {
      return {
        allowed: false,
        reason: 'Command substitution using $() is not allowed for security reasons'
      };
    }

    const blockedCommands = new Set(extractCommands(excludeTools));
    const allowedCommands = new Set(extractCommands(coreTools));

    for (const cmd of commandsToValidate) {
      const isBlocked = blockedCommandsArr.some((blocked) =>
        isPrefixedBy(cmd, blocked),
      );
      if (isBlocked) {
        return { allowed: false, reason: `Command '${cmd}' is blocked` };
      }
    }
    return { allowed: true };
  }
}

Shell 工具實作了完整的安全檢查機制，包含命令白名單、黑名單過濾，和命令替換防護，確保系統執行的安全性。

⚛️ React Hook 式串流處理

// 從 packages/cli/src/ui/hooks/useGeminiStream.ts 擷取
export const useGeminiStream = (
  geminiClient: GeminiClient,
  history: HistoryItem[],
  addItem: UseHistoryManagerReturn['addItem']
) => {
  const processGeminiStreamEvents = useCallback(
    async (stream: AsyncIterable<GeminiEvent>) => {
      for await (const event of stream) {
        switch (event.type) {
          case ServerGeminiEventType.Content:
            geminiMessageBuffer = handleContentEvent(event.value);
            break;
          case ServerGeminiEventType.ToolCallRequest:
            toolCallRequests.push(event.value);
            break;
          case ServerGeminiEventType.Error:
            handleErrorEvent(event.value);
            break;
        }
      }
      if (toolCallRequests.length > 0) {
        scheduleToolCalls(toolCallRequests, signal);
      }
    }, []
  );
}

使用 React Hook 模式處理 Gemini API 串流回應，提供即時的用戶互動體驗和狀態管理。

💡 應用情境

📚 大型程式碼庫分析與重構

開發者可以透過 Gemini CLI 快速理解複雜的程式碼架構，識別重構機會，並自動化執行程式碼修改。支援跨檔案的依賴分析和業務邏輯理解，大幅提升程式碼維護效率。

⚡ 自動化開發工作流程

整合 Git 操作、檔案管理、測試執行等開發任務，提供一站式的開發體驗。可以自動化處理常見的開發流程，如程式碼審查、部署準備、和文件生成。

🔧 客製化工具整合

透過 MCP 協議支援第三方工具整合，開發團隊可以將現有的內部工具和 CI/CD 流程無縫整合到 Gemini CLI 中，建立客製化的開發環境。

🎓 互動式學習與文件生成

新進開發者可以透過自然語言查詢理解程式碼邏輯，系統可以自動生成技術文件、API 說明、和最佳實踐指南，降低學習門檻。

🏢 企業級開發協作

支援多人協作的程式碼審查、知識分享、和技術決策討論。可以整合企業內部的開發工具鏈，提供統一的開發介面和工作流程。

🏗️ 軟體架構圖

Gemini CLI 採用模組化架構，CLI 前端透過串流 API 與核心引擎通訊，核心引擎負責工具管理和 Gemini API 整合，支援多種外部資源存取和 VS Code 整合

❓ 常見問題 Q&A

Q1: Gemini CLI 與傳統 IDE 相比有什麼優勢？

🎯 統一的 AI 驅動介面

不同於傳統 IDE 需要在多個視窗和工具間切換，Gemini CLI 提供單一的智慧化命令列介面，能理解自然語言指令並自動化執行複雜操作。

優勢： 透過自然語言即可完成檔案搜尋、程式碼分析、重構等操作，大幅降低操作複雜度

🔗 強大的整合能力

支援 MCP 協議和工具發現機制，可以無縫整合現有的開發工具鏈，而不需要複雜的外掛安裝和配置。

Q2: 如何確保 Shell 命令執行的安全性？

🛡️ 多層安全防護機制

Gemini CLI 實作了完整的安全檢查機制，包括命令白名單/黑名單過濾、命令替換防護、和使用者確認機制。

安全特性：

禁止危險的命令替換操作 (如 $())
支援 Docker/Podman 沙盒隔離執行
可配置的命令權限控制系統
所有修改性操作都需要使用者明確確認

🏗️ 沙盒執行環境

支援在隔離的容器環境中執行命令，確保主機系統的安全性，特別適合處理不受信任的程式碼或執行實驗性操作。

Q3: 如何擴展 Gemini CLI 的功能？

🔌 MCP 協議整合

透過 Model Context Protocol 可以輕鬆整合第三方工具和服務，只需要實作 MCP 伺服器即可將自訂工具註冊到系統中。

擴展方式：

開發 MCP 伺服器提供自訂工具
使用工具發現命令註冊專案特定工具
透過設定檔配置工具權限和行為
支援動態載入和熱更新機制

⚙️ 工具發現機制

系統可以自動發現專案中的自訂工具定義，並將其整合到工具註冊表中，支援專案層級的工具客製化。

Q4: 是否支援類似 Claude Code 的自訂 command 功能？

✅ 完整支援且更加強大

Gemini CLI 不僅支援類似 Claude Code 的自訂 command 功能，在某些方面甚至更加靈活和強大。可以透過工具發現機制來建立自訂的 prompt 命令。

實作方式：

在專案中建立 .gemini/config.yaml 設定檔
建立工具發現腳本 .gemini/discover-prompts.js
建立工具執行腳本 .gemini/execute-prompt.js
定義自訂 prompt 模板和參數

🚀 使用範例

設定完成後，可以像這樣使用自訂命令：

# 執行程式碼審查 prompt
gemini> code_review

# 審查特定檔案  
gemini> code_review --files "src/main.ts"

# 解釋專案架構
gemini> explain_architecture

# 生成單元測試
gemini> generate_tests --file_path "src/utils.ts"

優勢特點：

無需 MCP server，直接使用 JavaScript 腳本更簡單
支援參數化 prompt，可傳入動態參數
可版本控制，便於團隊共享自訂命令
重新啟動 Gemini CLI 後自動載入新命令

⚙️ 完整實作範例

步驟 1：建立設定檔

# .gemini/config.yaml
toolDiscoveryCommand: "node .gemini/discover-prompts.js"
toolCallCommand: "node .gemini/execute-prompt.js"

步驟 2：建立工具發現腳本

// .gemini/discover-prompts.js
#!/usr/bin/env node

const prompts = [
  {
    name: "code_review",
    description: "執行程式碼審查分析",
    parameters: {
      type: "object",
      properties: {
        files: {
          type: "string",
          description: "要審查的檔案路徑（可選）"
        }
      }
    }
  },
  {
    name: "explain_architecture", 
    description: "解釋專案架構設計",
    parameters: { type: "object", properties: {} }
  },
  {
    name: "generate_tests",
    description: "為指定檔案生成單元測試",
    parameters: {
      type: "object",
      properties: {
        file_path: {
          type: "string",
          description: "要生成測試的檔案路徑"
        }
      },
      required: ["file_path"]
    }
  }
];

// 輸出符合 Gemini CLI 期望的格式
console.log(JSON.stringify(prompts));

步驟 3：建立工具執行腳本

// .gemini/execute-prompt.js
#!/usr/bin/env node

const fs = require('fs');

// 從 stdin 讀取參數
let input = '';
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
  const params = JSON.parse(input);
  const toolName = process.argv[2];
  
  const prompts = {
    code_review: `請對以下程式碼進行詳細審查：
1. 程式碼品質和可讀性
2. 潛在錯誤和安全問題
3. 效能優化建議
4. 最佳實踐遵循

${params.files ? `重點檢查檔案: ${params.files}` : '請分析整個專案'}`,

    explain_architecture: `請分析當前專案的架構設計：
1. 整體架構模式和設計原則
2. 主要模組和元件職責
3. 資料流向和依賴關係
4. 架構優勢和潛在改進點`,

    generate_tests: `請為以下檔案生成完整的單元測試：
檔案路徑: ${params.file_path}

要求：
1. 涵蓋主要功能和邊界情況
2. 使用專案現有的測試框架
3. 包含清晰的測試描述
4. 提供執行和驗證方式`
  };

  const prompt = prompts[toolName];
  if (prompt) {
    console.log(prompt);
  } else {
    console.log(`未知的工具: ${toolName}`);
  }
});

重要提醒：

建立檔案後需要設定執行權限：chmod +x .gemini/*.js
修改設定後需要重新啟動 Gemini CLI 才會生效
所有自訂命令都會受到系統的安全檢查機制保護

Q5: 對於大型專案的效能如何？

🚀 智慧化上下文管理

利用 Gemini 的 1M token 大型上下文視窗，配合智慧化的上下文壓縮和記憶體管理，能有效處理大型程式碼庫。

效能優化：

自動上下文壓縮避免 token 限制
增量式檔案分析和快取機制
非同步串流處理提升回應速度
智慧化的工具執行排程

💾 記憶體與快取策略

實作了完善的記憶體管理機制，包括對話歷史壓縮、檔案內容快取、和增量式程式碼分析，確保在大型專案中的流暢體驗。

🔮 未來展望

Gemini CLI 作為次世代 AI 驅動的開發工具，將持續演進以滿足開發者不斷變化的需求。我們計劃在以下幾個方向進行深度發展，進一步提升開發體驗和工作效率。

🤖 更深度的 AI 整合

整合更多 AI 模型和服務，支援程式碼生成、自動化測試撰寫、和智慧化重構建議，提供更全面的 AI 輔助開發體驗。

🌐 雲端協作平台

建立雲端協作平台，支援團隊間的即時協作、知識分享、和專案管理，讓 Gemini CLI 成為企業級開發協作的核心工具。

📱 多平台支援

擴展到行動裝置和 Web 平台，提供跨裝置的一致開發體驗，讓開發者可以在任何地方繼續工作流程。

🎯 智慧化工作流程

開發更智慧的工作流程自動化功能，能學習開發者的習慣和偏好，主動建議最佳化的開發流程和工具配置。

🔐 企業級安全性

強化安全性功能，支援企業級的權限管理、稽核追蹤、和合規性要求，讓大型組織能安心採用。

🎨 視覺化程式碼理解

整合程式碼視覺化和互動式圖表功能，幫助開發者更直觀地理解複雜的程式碼架構和資料流向。