開發環境建置指南：Gemini CLI, VS Code 與 Python (Windows 版)

本指南旨在協助初學者在 Windows 系統上建立完整的 Python 開發環境，整合 Gemini CLI 人工智慧工具、VS Code 編輯器以及現代化的 Python 套件管理工具 uv。

第一部分：安裝 Gemini CLI

Gemini CLI 是一個基於命令列的介面，讓我們能直接在終端機與 Gemini AI 互動。它是基於 Node.js 開發的。

1. 安裝 Node.js (前置需求)

由於 Gemini CLI 是 Node.js 應用程式，必須先安裝執行環境。

  1. 前往 Node.js 官方網站：https://nodejs.org/
  2. 下載 LTS (Long Term Support) 版本（建議選擇穩定版）。
  3. 執行安裝檔，依指示完成安裝（大部份選項維持預設即可）。

2. 安裝 Gemini CLI

  1. 開啟 命令提示字元 (Command Prompt) 或 PowerShell。
  2. 輸入以下指令並按 Enter：
    bash npm install -g @google/gemini-cli
  3. 安裝完成後，初次執行 gemini 指令時，系統會引導您透過瀏覽器登入 Google 帳號進行驗證。

3. 常見問題排除：PowerShell 權限問題

如果在 Windows PowerShell 執行 Gemini 相關指令時出現紅色錯誤訊息，提示「依據系統的執行原則，無法載入檔案...」，這是 Windows 的安全機制。

解決步驟：
1. 按「開始」按鈕，搜尋 "PowerShell"。
2. 在 "Windows PowerShell" 上按右鍵，選擇 「以系統管理員身分執行」。
3. 在藍色的終端機視窗中，輸入以下指令並按 Enter：
powershell Set-ExecutionPolicy RemoteSigned
> 解釋：此指令會將您的系統權限設定為 RemoteSigned（遠端簽署）。這代表您自己寫的指令碼可以自由執行，但從網路下載的指令碼必須經過受信任的發布者簽署才能執行。這是一個在「安全性」與「開發便利性」之間取得平衡的設定，也是開發者最常用的設定。

  1. 系統會詢問是否變更執行原則，請輸入 Y 或 A 並按 Enter 確認。
  2. 關閉視窗，重新開啟一般的 PowerShell 即可正常使用。

第二部分：安裝與設定 Visual Studio Code (VS Code)

VS Code 是目前最主流的程式碼編輯器。

1. 下載與安裝

  1. 前往官網：https://code.visualstudio.com/
  2. 下載 Windows 版本並安裝。

2. 安裝 Python 擴充套件

為了讓 VS Code 看得懂 Python 語法並提供除錯功能，需要安裝官方套件。

  1. 開啟 VS Code。
  2. 點擊左側邊欄的 擴充套件圖示 (Extensions)（或按 Ctrl+Shift+X）。
  3. 在搜尋框輸入 Python。
  4. 選擇由 Microsoft 發布的第一個項目（通常下載量最高），點擊 Install。

第三部分：Python 環境與 UV 套件管理 (核心觀念)

這部分是現代 Python 開發最重要的環節。我們將使用 uv 這套新一代工具來管理 Python 環境。

1. 安裝 Python

  1. 前往 Python 官網：https://www.python.org/downloads/
  2. 下載最新版 Python 安裝檔。
  3. 重要關鍵：執行安裝時，務必勾選底部的 "Add Python to PATH" (將 Python 加入環境變數)。這能確保你在終端機打 python 指令時電腦找得到它。
  4. 點擊 "Install Now" 完成安裝。

2. 重要概念：什麼是「虛擬環境」 (Virtual Environment)？

在開始寫程式前，請先理解這個概念。

比喻：想像你在做工藝作業。
* 全域環境 (Global)：就像把你所有的工具（膠水、剪刀、顏料）全部丟在客廳的地板上。如果你同時做兩個專案，一個需要水彩，一個需要油漆，工具混在一起很容易弄髒或拿錯。
* 虛擬環境 (Virtual Environment)：就像為每個專案準備一個 「專屬工具箱」。A 專案的工具箱裡只有它需要的工具；B 專案有另一個獨立的工具箱。

為什麼需要它？
* 避免衝突：專案 A 可能需要舊版的 pandas 套件，而專案 B 需要新版的。如果都裝在電腦全域環境，會發生衝突。
* 保持整潔：當專案結束刪除資料夾時，相關的套件也就跟著消失，不會在電腦深處留下垃圾。

3. 安裝 UV (新一代 Python 管理工具)

uv 是一個極速的 Python 套件與專案管理工具，比傳統的 pip 快上許多，且能同時管理 Python 版本與專案依賴。

詳細安裝說明請參考：uv 官方安裝文件

推薦安裝方法 (Standalone installer)：
這是官方推薦的方式，能確保 uv 能夠自我更新並管理 Python 版本。

開啟 PowerShell，輸入以下指令並按 Enter：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

解釋：這個指令中的 -ExecutionPolicy ByPass 參數是告訴 PowerShell：「僅針對這次執行，暫時忽略權限限制」。這允許我們下載並執行官方的安裝腳本 (install.ps1)，而不需要永久修改系統安全性設定，是一個安全且常見的安裝手法。

其他安裝方法：
* 使用 pip：pip install uv
* 使用 WinGet：winget install --id=astral-sh.uv -e

驗證與更新：
* 驗證安裝：uv --version
* 更新 uv (僅限使用推薦方法安裝者)：uv self update

4. 實戰演練：使用 UV 建立 Python 專案 (標準流程)

假設我們要建立一個名為 my_ai_project 的專案。

步驟 1：初始化專案

在 PowerShell 中操作：

# 1. 建立專案資料夾
mkdir my_ai_project
cd my_ai_project

# 2. 初始化 uv 專案 (這會建立 pyproject.toml 設定檔)
uv init

步驟 2：建立虛擬環境

# 建立一個隱藏的 .venv 資料夾，這就是你的「專屬工具箱」
uv venv

執行後，你會在資料夾中看到 .venv 資料夾，請勿手動修改裡面的檔案。

步驟 3：安裝套件 (Install Packages)

假設我們需要 requests 和 pandas 套件：

# 使用 uv add 加入套件 (這會自動安裝到虛擬環境並更新設定檔)
uv add requests pandas

這取代了傳統的 pip install 指令。uv 會自動解析並下載最適合的版本。

步驟 4：執行程式

當你要執行 Python 程式時，使用 uv run 確保它是使用虛擬環境中的 Python 執行的：

  1. 在 VS Code 中建立一個 main.py 檔案。
  2. 輸入程式碼。
  3. 在終端機執行：
    powershell uv run main.py
    uv run 會自動檢查環境，如果還沒建立虛擬環境或缺套件，它甚至會自動幫你補上，非常方便。

第四部分：專案管理與 Gemini 協作 (Project Context)

在現代軟體開發中，「專案 (Project)」不僅僅是一堆程式碼檔案，它是一個完整的上下文 (Context)，包含了設定檔、說明文件、以及程式碼邏輯。

1. 為什麼「資料夾」很重要？

在使用 VS Code 時，「開啟資料夾 (Open Folder)」 而不是單純「開啟檔案」是非常重要的習慣。
* VS Code 會將該資料夾視為一個 Workspace (工作區)，能正確讀取 .venv (虛擬環境) 與 .vscode (編輯器設定)。
* Gemini CLI 或其他 AI 助理也需要依賴這個資料夾結構來理解整個專案的上下文。

2. 使用 gemini.md 建立 AI 協作指南

為了讓 Gemini 更精準地協助你的專案，我們可以在專案根目錄下建立一個特殊的設定檔。

建立步驟：
1. 在專案根目錄 (例如 my_ai_project/) 建立一個名為 gemini.md 的檔案。
2. 這個檔案就像是給 AI 的「入職手冊」，告訴它你是誰、這個專案在做什麼、以及你希望它遵守的規則。

gemini.md 範例內容：

# 專案名稱：My AI Project

## 專案簡介
這是一個使用 Python 撰寫的網路爬蟲專案，目標是自動收集每日新聞。

## 你的角色
你是一位資深的 Python 後端工程師，擅長寫出乾淨、好維護的程式碼。

## 開發規則
1. 所有程式碼必須加上中文註解。
2. 優先使用 `requests` 與 `BeautifulSoup` 套件。
3. 錯誤訊息請用繁體中文顯示。

3. 如何讓 Gemini 讀取專案設定？

當你在該專案資料夾中開啟終端機並執行 gemini 時，你可以透過以下方式讓 AI 參考這些設定：
* 手動參考：在對話中直接告訴 Gemini 「請參考 gemini.md 的規則」。
* 自動載入 (進階)：部分進階的 AI 整合工具會自動掃描根目錄的 .md 說明檔來建立上下文。

總結

  1. 專案 = 資料夾：養成在 VS Code 中「開啟資料夾」的好習慣。
  2. 環境隔離：使用 uv 為每個專案建立獨立的 .venv。
  3. AI 指引：撰寫 gemini.md 來定義 AI 的角色與專案規則，讓協作更順暢。