Aider-AI/aider 終端機 Git 結對編程神器教學:自動建 Commit、RepoMap 與本地模型設定

Aider-AI/aider 透過 AST RepoMap 精準掌握大型專案結構,並自動為每次 AI 修改建立乾淨 Git Commit,一篇學會安裝設定、常用斜線指令與本地模型串接。

Share
Aider官方 GitHub 專案封面圖:Aider 教學
Aider官方開源專案視覺圖。 圖片來源:官方原文。

許多工程師在專案規模變大後,會發現網頁版對話框越來越難用。你必須手動把好幾個關聯檔案複製貼上給模型,改完之後又要一段段貼回編輯器,只要漏掉一個相依函式,整個程式就跑不起來。

更麻煩的是版本控制問題。當 AI 一次幫你改了五個檔案卻不小心改壞功能時,如果沒有乾淨的 Git 紀錄,光是想還原回上一步就足以讓人崩潰。

Aider 就是為了解決這兩個工程痛點而誕生的開源工具。它直接運行在你的終端機裡,結合 RepoMap 全專案結構地圖與原生 Git 自動化,讓每一次對話修改都變成一個獨立、有清楚訊息、隨時能撤銷的 Commit。

在各種圖形介面外掛百花齊放的今天,這套工具依然在開源社群與 OpenRouter 排行榜上名列前茅,甚至連它自身新版本有超過八成以上的程式碼都是由工具自己協助完成。

這篇 Aider 教學會帶你從零完成安裝、看懂 AST RepoMap 如何幫模型省下大量 Token、掌握最實用的終端機斜線指令,並示範如何串接本地 Ollama 模型與設定安全邊界。

為什麼這套終端機工具在開發者圈長紅?拆解 RepoMap 與 Git 雙核心

要理解這套工具為什麼跟一般聊天機器人不同,必須先看它的兩個底層設計:全專案結構地圖 RepoMap,以及強制綁定 Git 的修改工作流。

傳統做法想讓 AI 理解大型專案,只能把整個資料夾的原始碼全部塞進上下文視窗。這不僅會讓推論速度變慢,還會產生驚人的 Token 費用。

這套工具採用了截然不同的工程路徑,它利用抽象語法樹解析技術,為專案裡支援的一百多種程式語言建立索引。這個索引就是所謂的 RepoMap。

它不會把每個函式的實作細節都讀進來,而是提取出所有檔案的類別名稱、函式簽章、參數型別與呼叫關聯。接著再用圖演算法計算哪些符號在專案裡被引用最多次,最後把這份濃縮過的地圖放進提示詞裡。

結果就是模型只需要花費極少的 Token,就能知道整個專案的架構長什麼樣子、要去哪個檔案找定義,以及修改某個介面會影響到哪些模組。

第二個核心是原生 Git 整合。在它的設計哲學裡,AI 不應該直接偷偷覆寫你的檔案而不留痕跡。

每當你在終端機確認讓它修改程式,系統會自動把變更寫入檔案,並用清楚的英文或自訂格式建立一筆 Git Commit。

如果下一秒你發現這段修改不符合預期,甚至不需要自己手動查差異。只要在互動介面裡輸入 /undo,系統就會立刻把剛才那筆自動建立的 Commit 安全還原,讓檔案回到修改前的乾淨狀態。

Aider官方 GitHub 專案封面圖:Aider 教學
Aider官方開源專案視覺圖。 圖片來源:官方原文。
Aider官方介紹與實機示範影片,非本站實測。 來源:官方 YouTube。

安裝與快速啟動:三步驟跑起來

根據官方最新安裝文件,官方推薦使用 uv 或一鍵腳本進行獨立環境安裝,這樣可以避免跟系統原本的 Python 套件發生版本衝突。

如果你使用 macOS 或 Linux,可以直接在終端機執行官方安裝腳本,它會自動處理 Python 3.12 獨立執行環境:

curl -LsSf https://aider.chat/install.sh | sh

如果你已經習慣使用 uv 管理 Python 工具,也可以透過這兩行指令完成安裝:

python -m pip install uv
uv tool install --force --python python3.12 --with pip aider-chat@latest

Windows 使用者則可以透過 PowerShell 執行官方安裝指令,或是先安裝 pipx 後再執行 pipx install aider-chat。

安裝完成後,進到任何一個已經初始化 Git 的專案資料夾,設定好對應的模型供應商 API 金鑰即可啟動。系統支援雲端旗艦模型與本地模型,以下示範幾種最常見的啟動方式:

# 設定 Anthropic Claude 金鑰並啟動
export ANTHROPIC_API_KEY=你的金鑰
aider

# 設定 OpenAI 金鑰並指定模型啟動
export OPENAI_API_KEY=你的金鑰
aider --model gpt-4o

# 透過 DeepSeek API 啟動
export DEEPSEEK_API_KEY=你的金鑰
aider --model deepseek/deepseek-chat

啟動之後,系統會先掃描專案的 Git 狀態並建立 RepoMap。如果你在還沒初始化 Git 的空資料夾裡啟動,它也會主動詢問是否要幫你建立一個新的 Git 儲存庫。

延伸閱讀:Code Mode 是什麼?Claude Code 實驗功能的啟用步驟與限制

必學終端機斜線指令與 Architect 雙模型模式

進到互動介面後,工程師不需要一直離開終端機去按滑鼠,絕大多數的上下文管理與版控操作,都能透過斜線指令完成。以下整理日常開發使用頻率最高的實戰指令:

  • /add <檔案路徑>:把特定檔案加入目前的編輯上下文,讓模型可以讀取並直接修改它。記住一個原則,只加入這次任務真正需要改動的檔案,其餘交給 RepoMap 自動參考即可。
  • /read-only <檔案路徑>:把規格書、資料庫結構定義或參考範例以唯讀方式放進對話,確保模型看得到參考標準,但不會誤改這些檔案。
  • /drop <檔案路徑>:當某個檔案已經修改完畢,用這個指令把它移出上下文,立刻釋放 Token 空間並降低模型分心機率。
  • /diff:檢視上一次修改產生的完整 Git 差異內容,方便快速複查細節。
  • /undo:立刻撤銷剛建立的最後一筆 Git Commit,把檔案還原回修改前的乾淨狀態。
  • /lint 與 /test:直接在對話中觸發專案的語法檢查或單元測試指令,若測試失敗,系統會自動讀取錯誤訊息並嘗試修復。
  • /model <模型名稱>:在對話過程中隨時切換使用的語言模型,不用退出重開。

除了單一模型運作,系統還內建了非常實用的 --architect 架構師模式。這個模式可以把工作拆成兩段:先用推理能力最強的模型擔任架構師,負責分析問題並寫出修改方案;再把方案交給便宜、寫碼速度快的編輯模型,專門負責產生精準的程式碼差異並套用到檔案上。

如果你希望更貼近編輯器體驗,系統也支援 --watch-files 監聽模式。開啟之後,你在任何編輯器裡只要在程式碼註解寫下要求並在結尾加上 AI!,終端機就會在背景自動偵測註解並動手修改。

對於喜歡語音開發的工程師,它還提供 /voice 指令,讓你能直接用說話的方式描述需求或錯誤狀況,系統轉成文字後立刻交給模型執行修改。

串接本地 Ollama 與自訂設定檔教學

對於重視程式碼隱私、或是想在離線環境省下 API 費用的開發團隊,這套工具透過 LiteLLM 底層支援幾乎所有本地端推論引擎,其中最常見的就是 Ollama。

只要本機已經啟動 Ollama 服務並下載好適合寫程式的模型,例如 Qwen 系列或 DeepSeek Coder 模型,就能直接用以下方式啟動:

export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen2.5-coder:32b

在這裡要特別留意模型前綴的寫法。使用 ollama_chat/ 前綴可以讓系統採用完整的對話格式呼叫本地端點,通常比單純的 ollama/ 格式更穩定。

此外,由於本地模型的預設上下文長度有時只有 4,096 或 8,192 Tokens,若專案較大,建議搭配設定檔調整 map-tokens 參數,避免 RepoMap 佔用過多空間而把對話紀錄擠掉。

如果你經常需要在不同專案間切換多組模型與預設參數,可以在專案根目錄或家目錄建立 .aider.conf.yml 設定檔:

model: anthropic/claude-3-7-sonnet-20250219
auto-commits: true
dirty-commits: true
map-tokens: 1024

設定好之後,每次在該目錄啟動就會自動套用這些偏好,不需要每次都敲一長串命令列參數。如果有團隊共用的開發規範,也可以把設定檔一併放進版本控制裡。

終端機工具與主流編輯器 AI 代理比較

很多開發者會猶豫該選純終端機的命令行工具,還是圖形介面的 VS Code 外掛。兩者其實沒有絕對優劣,而是工作習慣與專案情境的差異:

比較維度 Aider 編輯器圖形代理外掛
執行環境 純終端機 CLI,任何編輯器或遠端 SSH 都能用 高度綁定特定 IDE 側邊欄與視窗介面
全專案理解機制 AST 語法樹抽取 RepoMap,依引用權重動態濃縮 多數依賴向量索引或代理自行搜尋檔案
版本控制整合 每次修改強制對應 Git Commit,支援一鍵撤銷 偏重編輯器暫存區差異比對,需手動管理提交
自動化與腳本串接 原生支援非互動模式與 CI 管線呼叫 較難直接嵌入無頭伺服器或自動化腳本
視覺化操作門檻 需熟悉終端機與 Git 基礎觀念 點擊即可操作,對初學者較直覺

實務限制與資安邊界

雖然自動 Git 機制已經提供很好的安全網,但在實際團隊開發上仍有幾點限制需要注意。

首先是「本地模型的能力落差」。編輯機制要求模型必須嚴格遵守特定的 Search and Replace 差異格式,才能把修改精準套進既有檔案。參數量太小的本地模型常常在輸出差異區塊時格式跑掉,導致套用失敗或重複重試。若要用本地模型,建議至少選用 14B 到 32B 以上且針對程式微調的模型。

其次是「環境變數與敏感檔案洩漏風險」。即使你沒有主動執行 /add,為了避免工具意外把 .env、私鑰憑證或機密設定檔送進雲端模型 API,務必在專案根目錄設定 .aiderignore 檔案。它的寫法跟 .gitignore 完全相同,能把所有不該被讀取的路徑徹底排除。

最後是「過度依賴自動提交與無確認模式」。--yes-always 參數可以讓系統全自動執行修改與測試,但若同時開啟自動執行終端機指令,模型有可能在除錯過程中執行到高風險的系統指令。在涉及資料庫或系統層級的專案裡,建議保留每次執行指令前的人工確認提示,並在推送到遠端分支前重新整理過於零碎的自動 Commit。

延伸閱讀:Apple 宣布 macOS 27.3 拆分裝置控制與資料存取權限:AI 代理時代的 Mac 資安新防線

終端機高效率工作流速查與避坑清單

把終端機結對編程融入日常開發時,善用幾個小習慣能讓準確率與速度再提升一個檔次:

  • 善用非互動模式跑批次任務:當你需要幫二十個檔案補上文件字串或統一轉換錯誤處理格式,可以用 --message 參數搭配指令腳本直接批次執行,不用守在螢幕前手動確認。
  • 控制上下文潔癖:每完成一個獨立功能或修復一個錯誤後,養成輸入 /clear 清空對話歷史或 /drop 移除舊檔案的習慣,這不僅省下大量費用,也能避免舊對話干擾模型判斷。
  • 自動測試閉環設定:啟動時加上 --test-cmd "pytest" 與 --auto-test 參數,每次模型改完檔案都會自動跑一次測試,一旦失敗就會直接把錯誤堆疊餵回給模型自我修復。
  • 善用 --read 參數保護關鍵規格:把系統架構文件或介面定義檔以唯讀方式傳入,確保模型在修改實作時嚴格遵守既定契約,不會擅自更改對外介面欄位。

只要掌握這些參數組合,就能在純命令列環境裡建立極為流暢的開發節奏。

常見問題

這份 Aider 教學介紹的工具會把整個專案原始碼都傳給雲端嗎?

不會。系統只會傳送兩部分資料:你明確用 /add 或 /read-only 加入的檔案完整內容,以及透過語法樹萃取出的精簡 RepoMap 結構索引。這樣能大幅減少不必要的 Token 消耗並保護未授權的檔案。

如果我沒有用 Git 管理專案,還可以使用嗎?

技術上可以用 --no-git 關閉 Git 整合,但不建議這麼做。這套工具最強大的防護網就是每次修改自動建立 Commit 與 /undo 快速還原機制。即使是一次性的小腳本,花一秒鐘初始化 Git 都能讓開發過程安全很多。

支援在輸入問題時附帶圖片或網頁文件嗎?

支援。只要使用 /add 指令加上圖片路徑,或是貼上文件網址讓系統抓取內容,支援多模態的模型就能參考介面截圖或最新 API 文件來修改程式碼,對前端切版與串接第三方介面特別實用。

為什麼我的本地 Ollama 模型跑起來常出現編輯失敗?

這通常是因為模型輸出的差異格式不夠精準,或是上下文長度不足。你可以試著改用 --edit-format whole 讓模型輸出完整檔案而非局部差異,或是確認 Ollama 的上下文視窗設定是否足夠容納 RepoMap 與目標檔案。

結語

Aider 證明了 AI 結對編程不需要華麗的動畫介面,只要把語法樹 RepoMap 與 Git 版本控制這兩件工程師最在乎的基本功做到極致,就能在終端機裡創造極高的生產力。

適合誰:熟悉終端機操作與 Git 工作流、經常需要透過 SSH 連上遠端主機開發、或是受夠了 AI 亂改檔案卻難以追蹤還原的軟體工程師。

不適合誰:完全不熟悉 Git 基本指令與命令列操作的新手,或是高度依賴編輯器內即時滑鼠選取與視覺化預覽的前端設計師。

想持續追蹤更多高效率的開源 AI 開發工具教學、模型評測與工程實戰秘訣,歡迎立即免費訂閱 AI 郵報,每週為你送上最精煉的技術整理。

資料來源