Agent Modes 与全局设置

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:#22c55e

2. 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 工作流。