RooCodeInc/Roo-Code VS Code 開源自主程式代理教學:自訂 Architect 與 Debug 多角色全攻略

Roo Code 是 VS Code 最受歡迎的開源自主程式代理外掛之一,支援 Architect、Code、Ask、Debug 多角色切換與自訂模型 API,一篇掌握安裝與省錢技巧。

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

很多工程師在 VS Code 裡用 AI 寫程式,最常遇到的痛點是對話框給了一段程式碼,自己還得手動複製貼上、開終端機跑測試、再把錯誤訊息貼回去重問。

如果把專案架構規劃、實際改檔、除錯追蹤全部塞進同一個系統提示詞裡,模型很快就會遺忘規範,甚至在還沒確認需求前就亂改核心檔案。

這正是 Roo Code 當時爆紅的原因。它直接駐留在編輯器側邊欄,把 AI 代理拆成 Architect、Code、Ask、Debug 與自訂模式,讓開發者依照任務階段切換權限與工具邊界。

在開始這份 Roo Code 教學之前,必須先講一個關鍵事實:官方在 2026 年 5 月 15 日已正式關閉原版擴充套件並停止維護,團隊將重心轉向雲端代理專案 Roomote。

不過它開創的多角色架構與設定格式並沒有消失。原核心社群開發者已經把程式碼庫分支出來,持續以 ZooCode 名義維護更新,上游來源專案 Cline 也依然保持高頻迭代。

如果你手邊還有舊專案在使用這套設定檔,或是想把這套角色分工工作流搬進現在的開發環境,下面會完整拆解它的核心設計、操作實戰、省錢路由技巧與無痛遷移做法。

為什麼多角色模式能解決 AI 亂改檔痛點?

傳統編輯器輔助工具大多只有「對話」和「套用」兩種狀態。模型拿到寫入權限後,常常為了修一個小問題而順手重構整個模組,讓審查變得非常痛苦。

這套外掛的做法是把代理的能力邊界與系統指令綁定在「模式」上。每個模式只拿到該階段需要的工具,藉此從制度面限制模型的行動半徑。

在預設設計裡,系統一共內建了四種基礎角色,再加上讓團隊自行擴充的自訂模式:

  1. Architect 模式:專注於系統設計、技術規格與重構路線規劃。這個角色主要讀取專案檔案與撰寫設計文件,不會直接對業務程式碼動刀,適合在寫程式前先對齊實作藍圖。
  2. Code 模式:負責日常程式開發、建立檔案、套用差異修改與執行終端機指令。當 Architect 把任務拆解清楚後,再切換到這個模式進行高效率實作。
  3. Ask 模式:定位為專案知識庫問答與文件解說員。它不會修改任何檔案或執行破壞性指令,適合用來快速搞懂陌生程式庫的資料流與相依關係。
  4. Debug 模式:專門用來追蹤執行期錯誤、插入診斷日誌與隔離根本原因。它會優先針對錯誤堆疊與測試輸出進行分析,避免盲目猜測修補。
  5. Custom Modes 自訂模式:允許開發者透過設定檔建立專屬角色,例如資安審查員、資料庫遷移專家或單元測試撰寫代理,並各自指定允許存取的檔案路徑與模型。

這種設計背後的工程邏輯很清楚:用工具權限限制代理的行動範圍,比在提示詞裡寫十次「請不要亂改檔案」更可靠。

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

Roo Code 停止維護後的現況與安裝遷移步驟

在準備動手安裝之前,開發者必須先釐清目前的專案生態。根據官方 GitHub 儲存庫的公告,原版擴充套件已於 2026 年 5 月 15 日停止服務,因此不建議在新專案繼續安裝已停止更新的舊套件。

目前有兩條最穩妥的實戰路徑可以承接這套工作流:

  • 延續原汁原味的多角色體驗與設定檔:改裝社群接手維護的分支 ZooCode。它保留了原本的介面與模式邏輯,並持續補上新模型支援、危險指令防護機制與 Semble 語意搜尋功能。
  • 回到更精簡的上游工作流:直接安裝 Cline。Cline 是當初分支出去的起點,主打 Plan 與 Act 雙階段迴圈,社群生態與企業支援同樣成熟。

無論你選擇哪一條路線,背後的環境準備步驟都完全相通。首先確認本機已安裝最新版 Visual Studio Code,並準備好 Git 版本控制環境,確保每次代理修改前工作區都是乾淨的。

接著前往 VS Code 擴充功能市集搜尋 ZooCodeOrganization.zoo-code,或是前往官方 GitHub 發布頁面下載安裝。如果是既有使用者,可以依照官方提供的遷移指南,把原本的 .roomodes 與設定檔匯入 ZooCode,幾乎不需要重新適應介面。

最後一步是準備至少一組模型供應商 API 金鑰。系統支援 Anthropic、OpenAI、Google Gemini、OpenRouter,或是本機運行的 Ollama 端點,讓你完全掌握模型選擇權與資料流向。

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

自訂角色模式與 MCP 工具串接實戰

這套系統最具代表性的功能,就是把代理角色設定成可版控的專案檔案。當你在專案根目錄建立自訂模式定義時,整個團隊只要拉下儲存庫,就能共用同一套工程規範。

舉例來說,如果你想建立一個只負責寫測試與跑測試的「QA 測試專家」模式,可以在 .roomodes 設定中明確限制這個角色只能編輯 tests/ 目錄底下的檔案,完全不能動到 src/ 核心邏輯。

設定核心概念包含四個關鍵欄位:

  • slug:角色的唯一識別代號,用來在介面或任務委派中呼叫特定角色。
  • name:顯示在模式切換選單上的友善名稱,方便團隊成員辨識。
  • roleDefinition:給模型的系統角色指令,定義它的專業標準、編碼風格與輸出要求。
  • groups:這個模式可以使用的工具權限群組,例如讀取檔案、編輯指定路徑檔案、執行終端機指令或呼叫瀏覽器。

除了角色權限拆分,它也支援整合 MCP 伺服器。這讓代理不只看得到本機程式碼,還能直接查詢資料庫結構、讀取設計稿或對接內部文件系統。

為了避免權限過大,實務上建議針對不同模式設定獨立的 MCP 工具存取白名單。例如讓 Architect 模式可以讀取資料庫結構資訊,但只允許 Code 模式在本地測試環境執行寫入或遷移指令。

模型路由省錢攻略:高階模型規劃、平價模型動手

用自主程式代理最大的隱形成本就是 Token 帳單。如果從頭到尾都讓最昂貴的旗艦推理模型去讀取幾百個檔案、執行格式化與跑測試,一天燒掉數十美元並不罕見。

這套外掛的設定機制支援「依角色綁定不同模型設定檔」,這是許多資深工程師控制成本的核心技巧。以下整理四個常用角色的模型配置策略:

角色模式 建議模型定位 任務特徵 成本優化策略
Architect 模式 高推理能力旗艦模型 跨模組架構分析、拆解實作步驟、評估相依風險 每次新功能只跑一到兩輪規劃,換取後續不走冤枉路
Code 模式 高性價比程式專用模型 依照明確規格修改檔案、補齊型別與 CRUD 邏輯 用較低單價模型執行大量差異編修,搭配自動測試驗證
Ask 模式 快速輕量模型或快取端點 查詢函式定義、解釋錯誤碼、整理現有文件 上下文不需修改檔案,選延遲低且便宜的模型即可
Debug 模式 推理強且支援長上下文模型 分析多層堆疊追蹤、比對非同步時序問題 只貼入關鍵日誌與相關模組,避免把整個專案塞進提示詞

實作時,你可以先在設定介面建立多個 API 設定檔,例如分別命名為 planner-high、coder-fast 與 local-ollama。

接著在各個模式的下拉選單中指定預設使用的設定檔。當你從 Architect 切換到 Code 模式時,系統就會自動切換背後的模型端點與計費來源,完全不用手動修改金鑰,也不必擔心忘記切回平價模型。

此外,善用上下文管理與檔案提及功能也能大幅省錢。不要每次提問都讓代理掃描整個資料夾,而是主動用 @ 符號精準指定這次需要修改的三、五個關聯檔案,這樣能把單輪對話的輸入 Token 壓低一半以上。

資安邊界、自動核准風險與團隊使用限制

開源自主代理把終端機與檔案寫入權限交給語言模型,方便與風險其實是一體兩面。在導入這套工具或其延續分支 ZooCode 時,有三條資安邊界絕對不能放鬆。

第一條邊界是「自動核准清單的收斂」。很多人為了追求全自動體驗,會把執行終端機指令與修改檔案全部勾選自動核准。

一旦專案裡包含資料庫遷移腳本、雲端部署 CLI 或帶有外部依賴的安裝腳本,模型一次誤判就可能刪除本機資料或把測試金鑰推上遠端。實務上只建議對唯讀查詢指令開放自動核准,任何寫入與刪除操作都應該保留人工確認,或是啟用危險指令防護機制來攔截高風險指令。

第二條邊界是「提示詞注入風險」。當你讓代理透過 MCP 讀取外部網頁、Issue 內容或第三方套件文件時,惡意文字有可能偽裝成系統指令,誘導代理讀取 .env 環境變數並透過網路指令傳送到外部伺服器。

因此,敏感的生產環境金鑰絕對不要直接放在開發機的明文專案目錄裡,也應該設定規則檔阻擋代理讀取機密設定檔。

第三條邊界是「程式碼授權與智慧財產合規」。雖然專案本身採用 Apache 2.0 開源授權,但你串接的商業模型 API 是否有資料留存政策、是否會拿程式碼做訓練,取決於各家雲端供應商的企業條款。處理機密專案時,務必改用有零資料留存承諾的企業 API 端點,或直接切換至內網部署的開源模型。

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

常見實戰工作流速查表與進階除錯技巧

為了讓剛接觸多角色代理的工程師更快上手,以下整理三個日常開發最實用的組合技,能大幅減少反覆溝通的次數:

  • 新功能開發三部曲:先切換到 Ask 模式詢問現有模組的資料流向,接著切到 Architect 模式產出實作計畫與影響檔案清單,確認無誤後才切進 Code 模式寫碼並跑測試。
  • 棘手 Bug 定位法:遇到非同步競爭或難以重現的錯誤時,直接開啟 Debug 模式,讓代理先在關鍵節點插入診斷日誌,收集完終端機輸出後再做一次性修復。
  • 團隊規範自動載入:在專案根目錄建立系統規則檔,明確寫入命名慣例、禁止使用的舊函式庫與測試覆蓋率要求,每次開啟新對話都會自動生效。

只要養成「先規劃、再動手、最後審查差異」的節奏,就能把編輯器代理變成真正可靠的團隊戰力。

常見問題

既然原版已經停止維護,現在還值得學這份 Roo Code 教學嗎?

值得學,但不建議在新專案繼續安裝已停止更新的原版套件。它建立的多角色分工與模式權限隔離概念,已經成為目前編輯器代理的主流設計標準。你只要改裝社群延續維護的分支 ZooCode,就能直接沿用這套工作流與設定習慣。

這套工具跟 GitHub Copilot 或 Cursor 有什麼根本差別?

傳統輔助工具偏向在編輯器內提供即時補全與單一對話框,模型選擇也常綁定平台方案。這套開源架構走的是自帶金鑰路線,強調把架構規劃、程式修改與除錯拆成不同權限的角色模式,並讓開發者完全掌控背後呼叫哪一家模型與哪些 MCP 工具。

串接本機 Ollama 模型跑多角色代理的效果好嗎?

對於 Ask 問答或單純的函式重構,高參數量的本機模型可以應付。但如果要讓代理連續執行多步驟工具呼叫、精準產生檔案差異並自行除錯,本機小模型很容易在工具格式上出錯。實務上建議至少使用旗艦雲端模型做 Architect 規劃,本機模型只負責輔助問答。

如何避免代理在修改程式時不小心把專案改壞?

最有效的方法是把 Git 分支保護與模式權限搭配使用。開始大型修改前先開新分支並確保工作區乾淨,接著先用 Architect 模式輸出修改計畫,確認範圍無誤後再切到 Code 模式動手,最後利用系統的差異比對介面逐段檢查才提交。

結語

回顧這套開源編輯器代理的設計理念,它證明了把單一全能代理拆解成 Architect、Code、Ask 與 Debug 多角色,能大幅降低模型暴走與誤改檔案的機率。

適合誰:習慣在 VS Code 內完成所有開發動作、需要嚴格區分架構規劃與改檔權限,並且希望自由混搭不同雲端或本機模型 API 的工程師。如果你重視工具透明性與可版控的團隊規範,這套工作流非常值得導入。

不適合誰:希望零設定開箱即用、不願自己申請與管理 API 金鑰,或是偏好在純終端機環境下用 Git 指令搭配自動化腳本開發的工程師。同時也要留意原版已於 2026 年 5 月關閉,務必改用 ZooCode 或 Cline 作為實際生產環境工具。

想掌握更多開源 AI 開發工具的實戰評測、設定技巧與版本動向,歡迎立即免費訂閱 AI 郵報,每週為你精選最值得動手試用的工程師資源。

資料來源