[AI] agent / Gemini CLI === ###### tags: `AI Tools` ###### tags: `AI`, `tools`, `agent`, `gemini`, `追蹤`, `commit`, `摘要` <br> [TOC] <br> ## Intro > 官方說明 https://google-gemini.github.io/gemini-cli/ <br> ### 安裝方式 1. **安裝 Node.js** 用 NodeSource（系統層級，全機可用） > [[HackMD] JavaScript Runtime](/ioPaKTHcTVOkDyJXraPYLA) (安裝 Node.js) ``` # 1) 先準備基本工具 sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg # 2) 啟用 Node.js 22.x LTS 的套件庫（要 20.x 就把 22.x 改成 20.x） curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - # 3) 安裝 sudo apt-get install -y nodejs # 4) 驗證 node -v npm -v npx -v ``` 2. **擇一安裝** ``` # 免安裝（跑一次就好） npx https://github.com/google-gemini/gemini-cli # 全域安裝（npm） sudo npm install -g @google/gemini-cli ``` - [首次安裝完，會跳出驗證畫面](#首次安裝完，會跳出驗證畫面) 3. **查看版本** (針對全域安裝？)（待驗證） ``` $ which gemini /usr/bin/gemini $ gemini --version 0.6.1 # 202 ``` <br> ### 安裝方式 - Troubleshooting - ### `Command 'npx' not found` ``` $ npx https://github.com/google-gemini/gemini-cli Command 'npx' not found, but can be installed with: sudo apt install npm ``` - ### 直接安裝 Node.js 用 NodeSource（系統層級，全機可用） > [[HackMD] JavaScript Runtime](/ioPaKTHcTVOkDyJXraPYLA) ``` # 1) 先準備基本工具 sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg # 2) 啟用 Node.js 22.x LTS 的套件庫（要 20.x 就把 22.x 改成 20.x） curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - # 3) 安裝 sudo apt-get install -y nodejs # 4) 驗證 node -v npm -v npx -v ``` - ### `npm WARN EBADENGINE Unsupported engine` ``` $ npx https://github.com/google-gemini/gemini-cli Need to install the following packages: github:google-gemini/gemini-cli Ok to proceed? (y) y npm WARN EBADENGINE Unsupported engine { npm WARN EBADENGINE package: '@google/gemini-cli@0.7.0-nightly.20250918.2722473a', npm WARN EBADENGINE required: { node: '>=20.0.0' }, npm WARN EBADENGINE current: { node: 'v18.19.1', npm: '9.2.0' } npm WARN EBADENGINE } ``` - 錯誤原因 - **Gemini CLI 需要 Node.js ≥ 20**，但你的環境是 **Node v18.19.1** <br> --- ## 啟動方式 ### 首次安裝完，會跳出驗證畫面 ![](https://hackmd.io/_uploads/HydMg4znlg.png) ``` How would you like to authenticate for this project? ● 1. Login with Google 2. Use Gemini API Key 3. Vertex AI ``` - 會彈出登入畫面，按照導引流程進行 <br> ### 後續啟動 ``` $ cd /path/to/your-repo $ gemini ``` <br> --- ## 指令 ### 退出程式 ``` > /quit ``` ### 更多指令 ![](https://hackmd.io/_uploads/Sk3dF4G2gl.png) <br> --- ## 使用範例1：追蹤近期 commit > 需在 Git 專案根目錄執行 `gemini` 指令 > ``` > ~/workspace/k8s/slinky/slurm-operator$ gemini > ``` - ### Prompt 針對目前 repo，請彙整最近兩天的 commit：列出每筆的 commit ID、變更摘要、關鍵檔案與修改重點，並以白話解釋此 commit 的目的與可能影響；最後給一份整體趨勢與待辦建議。 - ### 執行過程 ![](https://hackmd.io/_uploads/HJVi4VGhgg.png) - ### 執行範例 > https://github.com/SlinkyProject/slurm-operator ``` Commit 2: 新增主機名稱解析服務 * 變更摘要: feat: add hostname resolution service * 關鍵檔案: * internal/builder/worker_service.go: 新增了建立 Headless Service 的主要邏輯。 * internal/controller/nodeset/nodeset_sync.go: 在 NodeSet 的同步流程中呼叫上述新邏輯。 * internal/builder/login_app.go & worker_app.go: 修改了應用程式設定，以利用新的服務。 * docs/index.rst: 新增了相關文件。 * 修改重點: * 為 NodeSet 的 Pods 建立一個 Kubernetes Headless Service。 * 這使得 NodeSet 中的每個 Pod (計算節點) 都有一個可以被叢集內部解析的穩定 DNS 名稱 (hostname)。 * 同時更新了 LoginSet (登入節點)，讓它們也能利用這個服務來解析計算節點的主機名稱。 * 目的與可能影響: * 目的: 解決特定工作負載 (workloads) 需要透過主機名稱來找到並與其他節點溝通的需求。在這之前，節點間的通訊可能只能依賴 IP 位址，而 IP 位址在 Pod 重啟後可能會改變。 * 影響: * 正面: 大幅提升了 Slurm 叢集在 Kubernetes 上運行的相容性和靈活性，特別是對於那些依賴主機名稱解析的 MPI 或其他平行計算應用。 * 潛在: 這個新功能引入了新的 Kubernetes Service 物件。需要確保 RBAC 權限設定正確，且不會與現有網路策略衝突。 ``` - snapshot ![](https://hackmd.io/_uploads/SJsXONG2ee.png) ![](https://hackmd.io/_uploads/rkOPOEznlx.png) <br> --- <br> ## 討論 ### 用 gemini 問 local .git ，怎麼安裝和使用？ - ### gpt-5 (2025/09/25) 沒問題！Gemini CLI 已經能在終端機裡直接「讀你的本機程式碼庫（含 Git 專案）」並回答問題、跑指令與幫你改檔。下面給你從安裝到在本機 `.git` 專案上實際使用的最短路徑。 --- ### 安裝 **系統需求**：Node.js ≥ 20（macOS / Linux / Windows）([google-gemini.github.io][1]) 三種快速方式擇一： ```bash # 免安裝（跑一次就好） npx https://github.com/google-gemini/gemini-cli # 全域安裝（npm） npm install -g @google/gemini-cli # macOS / Linux（Homebrew） brew install gemini-cli ``` 以上指令與需求見官方文件的 Installation 區塊。([google-gemini.github.io][1]) --- ### 登入 / 授權 進入 CLI 後首選用 Google 帳號 OAuth 登入（免費額度：60 req/min、1,000 req/日；模型為 Gemini 2.5 Pro，1M token 視窗）。也支援 **Gemini API Key** 或 **Vertex AI**： ```bash # 方式一：Google 登入（開啟後依畫面指示登入） gemini # 方式二：Gemini API Key export GEMINI_API_KEY="你的API金鑰" gemini # 方式三：Vertex AI（企業用） export GOOGLE_API_KEY="你的API金鑰" export GOOGLE_GENAI_USE_VERTEXAI=true gemini ``` 額度、模型與三種登入方式詳見官方「Authentication Options」。([google-gemini.github.io][1]) --- ### 在本機 Git 專案上使用（最短路徑） 1. **進到你的 repo**： ```bash cd /path/to/your-repo gemini ``` Gemini CLI 會把「目前資料夾」視為工作根目錄；所有檔案工具都在這個範圍內運作。([google-gemini.github.io][2]) 2. **直接發問（互動模式）** 在出現 `> GEMINI` 介面後，你可以直接打： * 「幫我**總結這個程式庫的架構**與模組關係」 * 「找出**定義 `foo()`** 的檔案與使用處」 * 「請**執行 `git log --since='yesterday' --oneline`**，並摘要昨天的變更」 （CLI 會用 **shell tool** 執行並先詢問你確認，適用任何 `git` 指令。）([google-gemini.github.io][3]) 3. **一次性問答（非互動模式，方便寫腳本）** ```bash gemini -p "Explain the architecture of this codebase" # 需要機器可讀回傳： gemini -p "Explain the architecture of this codebase" --output-format json ``` ([google-gemini.github.io][1]) 4. **跨資料夾讀取（單次或動態加入）** ```bash # 啟動時一口氣加進多個資料夾 gemini --include-directories ../lib,../docs # 啟動後用指令加入/檢視工作目錄 /directory add ../lib,../docs /directory show ``` ([google-gemini.github.io][1]) --- ### 與 Git / 專案檔案的互動細節 * **預設遵守 `.gitignore`，且會忽略 `.git/` 與常見雜項資料夾**（例如 `node_modules`）。 這能避免把不必要或巨大的檔案塞進模型上下文。檔案工具也會在 Git repo 內優先用 **`git grep`** 加速內容搜尋。([google-gemini.github.io][2]) * 想讓它**讀到被 `.gitignore` 排除的檔案**或**包含 `.git/` 內部**（通常不需要）： 你可以在專案的 `.gemini/settings.json` 調整： ```json { "context": { "fileFiltering": { "respectGitIgnore": false } } } ``` 另外，多檔案讀取工具 `read_many_files` 也能關掉預設排除（含 `.git/`）： `useDefaultExcludes=false`、`respect_git_ignore=false`。([google-gemini.github.io][4]) * **常用檔案/搜尋工具**（模型會自動呼叫，並在敏感操作前向你確認）： * `list_directory`、`read_file`、`search_file_content`（內容搜尋在 repo 裡會用 `git grep`）([google-gemini.github.io][2]) * `write_file`（改檔前會顯示 diff 要你同意）([google-gemini.github.io][2]) * `run_shell_command`（跑 `git`、`npm`…；可在設定只允許 `git` 類指令）([google-gemini.github.io][3]) --- ### 快速範例（在 Git 專案根目錄執行） * **總結架構** ``` > 請閱讀 src/**/*.ts 與 docs/**/*.md，畫出模組互動與資料流摘要 ``` （模型會用多檔案讀取與搜尋工具聚合內容。）([google-gemini.github.io][5]) * **找出變更摘要** ``` > 請執行：git log --since="yesterday" --oneline --stat > 再幫我分門別類整理成 Changelog（Fix/Feat/Docs 等） ``` （CLI 會以 shell tool 執行並回傳 stdout，再請模型整理。）([google-gemini.github.io][3]) * **全庫快速問答（非互動）** ```bash gemini -p "列出此專案最重要的5支服務與入口檔，並指出其相依關係" ``` ([google-gemini.github.io][1]) --- ### 進階：專案專屬說明書 `GEMINI.md` 在專案根目錄放一個 `GEMINI.md`，可告訴 Gemini「如何閱讀與回答這個專案」；也可用 `/memory` 指令查看、更新記憶。([google-gemini.github.io][1]) （例如：專案目的、程式風格、測試策略、常見腳本、輸出格式要求等。） --- ### 安全提醒 * CLI 具備**改檔**與**跑系統指令**能力；寫檔會先顯示 diff、跑指令會先徵求你同意，但仍建議在**可信的 repo**中使用，並避免對不明專案給出危險指令（如 `rm -rf`）。([google-gemini.github.io][2]) * 今年曾通報過 CLI 的安全弱點並已修補，建議保持在最新版： ```bash npm i -g @google/gemini-cli@latest # 或 brew upgrade gemini-cli ``` （新聞背景參考。） ([Medium][6]) --- 如果你要「只讓它用 Git 指令、不允許其它系統指令」，可在 `.gemini/settings.json` 加上： ```json { "tools": { "core": ["run_shell_command(git)"] } } ``` （只允許以 `git` 開頭的 shell 指令。）([google-gemini.github.io][3]) 需要我直接幫你針對某個 repo 設好 `.gemini/settings.json` 與 `GEMINI.md` 的範本嗎？我可以依你的語言/專案風格客製一份。 [1]: https://google-gemini.github.io/gemini-cli/ "Gemini CLI | gemini-cli" [2]: https://google-gemini.github.io/gemini-cli/docs/tools/file-system.html "Gemini CLI file system tools | gemini-cli" [3]: https://google-gemini.github.io/gemini-cli/docs/tools/shell.html "Shell Tool (run_shell_command) | gemini-cli" [4]: https://google-gemini.github.io/gemini-cli/docs/cli/configuration.html "Gemini CLI Configuration | gemini-cli" [5]: https://google-gemini.github.io/gemini-cli/docs/tools/multi-file.html "Multi File Read Tool (read_many_files) | gemini-cli" [6]: https://medium.com/google-cloud/practical-gemini-cli-bring-your-own-system-instruction-19ea7f07faa2?utm_source=chatgpt.com "Practical Gemini CLI: Bring your own system instruction" <br> {%hackmd vaaMgNRPS4KGJDSFG0ZE0w %}