Agent Modes 與全域性設定
解釋 Antigravity 的 Planning、Fast、Artifact Review、Terminal 自動執行和非 workspace 檔案訪問設定。
Agent 能做很多事，但不是每個任務都應該用同一種模式、同一套許可權。Google 官方 Agent Modes / Settings 文件把控制點分成兩層：conversation-level 的模式選擇，以及 Settings pane 裡 Agent tab 的全域性策略。
學這一頁的目標不是記住選單，而是能判斷：當前任務應該讓 agent 先規劃，還是直接執行；哪些 artifact 必須審查；terminal 命令能否自動跑；是否允許它讀 workspace 之外的檔案。
一句話原則：簡單、區域性、低風險任務用 Fast；複雜、跨檔案、需要審查證據的任務用 Planning；高副作用能力預設先 Request Review。
閱讀目標：讀完本章，你應該能為一個真實任務選擇 Planning 或 Fast，並把 artifact、terminal、workspace 外檔案訪問三類風險設成可審查狀態。
1. Conversation-level：Planning 與 Fast
新建 Agent conversation 時，可以選擇模式。
| 模式 | 官方定位 | 適合任務 |
|---|---|---|
| Planning | 先研究、思考和規劃，再執行；會組織 task groups，產出 artifacts | 深度研究、複雜功能、協作任務、質量優先任務 |
| Fast | 直接執行任務，更適合速度 | 重新命名變數、跑幾條命令、小範圍區域性修改 |
不要把 Fast 理解成“更強”。Fast 的優勢是少繞路，代價是更少計劃和審查。只要任務存在下面任一特徵，就優先選 Planning：
- 跨多個目錄。
- 會改多個檔案。
- 需要瀏覽器驗證。
- 需要先和你確認實現方案。
- 涉及許可權、安全、部署、資料或真實賬號。
flowchart TD
Task["新任務"] --> Small{"單檔案/低風險?"}
Small -->|是| Fast["Fast"]
Small -->|否| Complex{"需要計劃、證據或審查?"}
Complex -->|是| Planning["Planning"]
Complex -->|否| Fast
Planning --> Artifacts["Task groups / Artifacts / Plan"]
Fast --> Direct["直接執行"]
style Planning fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
style Fast fill:#dcfce7,stroke:#22c55e2. Planning 模式應該怎麼驗收
官方文件提到，Planning 模式會組織 task groups、產出 artifacts，並更充分地研究和計劃。實際用起來，你要明確要求 agent 在關鍵點停下來：
使用 Planning 模式。
先交 implementation plan 和 task groups，不要修改文件。
我确认以后，你再执行第一组任务。驗收 Planning 的重點：
- Plan 是否說明了檔案範圍。
- Task group 是否有順序，不是平鋪願望清單。
- 是否說明了驗證方式。
- 是否明確哪些動作需要許可權確認。
- 是否有可回退策略。
如果 Planning 模式直接開始改大量檔案，說明你的提示詞邊界不夠，或者 artifact review 策略需要收緊。
3. Artifact Review Policy
Settings pane 的 Agent tab 裡有 Artifact Review Policy。官方文件列出的選項是：
- Always Proceed：Agent 不請求 review。
- Request Review：Agent 總是請求 review。
這個策略影響的是 agent 決定要請求使用者審查 implementation plan 時，它到底是停下來等你，還是繼續執行。
推薦策略：
| 場景 | 建議 |
|---|---|
| 第一次使用 Antigravity | Request Review |
| 真實業務專案 | Request Review |
| 生產、支付、賬號、資料庫相關任務 | Request Review |
| 玩具 demo 或低風險批次整理 | 可考慮 Always Proceed |
只要你還沒有建立一套穩定的 diff 審查和回退習慣，就不要預設 Always Proceed。
4. Terminal Command Auto Execution
終端命令是最需要謹慎的能力。官方文件列出兩種策略：
- Request Review：終端命令預設不自動執行，除非在可配置 allow list 中。
- Always Proceed：終端命令預設不請求審查，除非在可配置 deny list 中。
第一天建議選 Request Review，然後把低風險命令逐步加入 allow list。例如：
允许：pwd、ls、rg、cat、git status、pnpm test
谨慎：pnpm install、git commit、git push、cloud deploy
禁止自动执行：rm、ssh、scp、curl | sh、firebase deploy、数据库迁移關鍵不是命令名字本身，而是副作用：
| 命令型別 | 風險 |
|---|---|
| 只讀搜尋 | 低 |
| 測試 / lint / build | 中低，取決於指令碼副作用 |
| 安裝依賴 | 中，可能改 lockfile 或下載程式碼 |
| Git 寫入 / 推送 | 高 |
| 雲端部署 / 資料庫操作 | 極高 |
不要把 Always Proceed 當作效率開關。它會把“每次確認”變成“出事後追責”。真實專案預設從 Request Review 開始。
5. Agent Non-Workspace File Access
官方文件說明，Agent 預設只能訪問當前 workspace 檔案，以及 Antigravity 應用根目錄 ~/.antigravity/，其中包含 artifacts、knowledge items 和其他 Antigravity-specific data。
設定裡的 Agent Non-Workspace File Access 可以允許 Agent 檢視和編輯 workspace 之外的檔案。這個能力要非常謹慎，因為它可能暴露本機敏感資料。
不要輕易開放這些範圍：
~/.ssh/~/.config/- 金鑰目錄
- 瀏覽器 profile
- iCloud / Dropbox 同步目錄
- 其他客戶專案
- 包含
.env或生產憑據的目錄
如果確實需要跨目錄訪問，建議用臨時複製、只讀路徑或單獨測試 workspace，而不是把整個 home 目錄暴露給 agent。
深讀：為什麼預設設定應該偏保守
Antigravity 的設定項控制的是 Agent 能否在你沒有逐步確認的情況下繼續推進。Planning / Fast 決定任務是否先規劃，Artifact Review Policy 決定計劃是否等待審查，Terminal Command Auto Execution 決定命令是否自動執行，Non-Workspace File Access 決定它能否越過當前專案邊界。
這些設定疊加起來，才是真實風險面。單看一個開關可能沒問題，但 Fast + Always Proceed + Always Proceed terminal + 開放 workspace 外檔案訪問，會把本地檔案、終端和外部系統副作用串到一起。真實專案先保守，再按專案經驗逐步放寬。
6. 一套穩妥的預設設定
真實專案的起點可以這樣設：
| 設定 | 推薦值 |
|---|---|
| 預設 conversation mode | Planning |
| 簡單區域性任務 | 臨時切 Fast |
| Artifact Review Policy | Request Review |
| Terminal Command Auto Execution | Request Review |
| Non-Workspace File Access | 關閉 |
| Browser / 外部系統操作 | 先只讀，再白名單 |
這套設定不追求“最少點選確認”，而是追求每一步都能解釋、審查和回退。等你對專案、團隊流程和 agent 行為有足夠經驗，再考慮放寬。
7. 任務選擇模板
啟動任務前先判斷：
这个任务是否跨文件？
是否会运行命令？
是否需要浏览器？
是否会影响远端系统？
是否需要我看 plan？
是否有明确回退方式？如果其中任意一項回答“是”，用 Planning + Request Review。只有在目標明確、範圍小、結果容易回退時，才用 Fast。
本章自檢
完成本章後，用這 3 個問題檢查自己是否真正理解：
- 什麼任務適合 Fast，什麼任務必須優先用 Planning？
- Artifact Review Policy 和 Terminal Command Auto Execution 分別控制什麼？
- 為什麼不應該預設開放 Non-Workspace File Access？
透過標準：你能給一個真實儲存庫配置一套預設安全設定，並能說明每個設定降低了哪類副作用風險。
官方來源
- Google Antigravity Agent Modes / Settings —— 官方說明 Planning、Fast、Artifact Review、Terminal Auto Execution 和非 workspace 檔案訪問設定。
- Google Antigravity Agent —— 官方 Agent 章節，用於理解這些模式和設定服務於多步 Agent 工作流。