---
title: "Agent Modes 与全局设置"
description: "解释 Antigravity 的 Planning、Fast、Artifact Review、Terminal 自动执行和非 workspace 文件访问设置。"
verifiedAt: "2026-05-06"
---

Agent 能做很多事，但不是每个任务都应该用同一种模式、同一套权限。Google 官方 Agent Modes / Settings 文档把控制点分成两层：conversation-level 的模式选择，以及 Settings pane 里 Agent tab 的全局策略。

学这一页的目标不是记住菜单，而是能判断：当前任务应该让 agent 先规划，还是直接执行；哪些 artifact 必须审查；terminal 命令能否自动跑；是否允许它读 workspace 之外的文件。

> [!NOTE]
> **一句话原则**：简单、局部、低风险任务用 Fast；复杂、跨文件、需要审查证据的任务用 Planning；高副作用能力默认先 Request Review。

> [!TIP]
> **阅读目标**：读完本章，你应该能为一个真实任务选择 Planning 或 Fast，并把 artifact、terminal、workspace 外文件访问三类风险设成可审查状态。

## 1. Conversation-level：Planning 与 Fast

新建 Agent conversation 时，可以选择模式。

| 模式 | 官方定位 | 适合任务 |
| --- | --- | --- |
| Planning | 先研究、思考和规划，再执行；会组织 task groups，产出 artifacts | 深度研究、复杂功能、协作任务、质量优先任务 |
| Fast | 直接执行任务，更适合速度 | 重命名变量、跑几条命令、小范围局部修改 |

不要把 Fast 理解成“更强”。Fast 的优势是少绕路，代价是更少计划和审查。只要任务存在下面任一特征，就优先选 Planning：

- 跨多个目录。
- 会改多个文件。
- 需要浏览器验证。
- 需要先和你确认实现方案。
- 涉及权限、安全、部署、数据或真实账号。

```mermaid
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 在关键点停下来：

```text
使用 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 |

> [!IMPORTANT]
> 只要你还没有建立一套稳定的 diff 审查和回退习惯，就不要默认 Always Proceed。

## 4. Terminal Command Auto Execution

终端命令是最需要谨慎的能力。官方文档列出两种策略：

- **Request Review**：终端命令默认不自动执行，除非在可配置 allow list 中。
- **Always Proceed**：终端命令默认不请求审查，除非在可配置 deny list 中。

第一天建议选 Request Review，然后把低风险命令逐步加入 allow list。例如：

```text
允许：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 写入 / 推送 | 高 |
| 云端部署 / 数据库操作 | 极高 |

> [!WARNING]
> 不要把 `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。

<details>
<summary>深读：为什么默认设置应该偏保守</summary>

Antigravity 的设置项控制的是 Agent 能否在你没有逐步确认的情况下继续推进。Planning / Fast 决定任务是否先规划，Artifact Review Policy 决定计划是否等待审查，Terminal Command Auto Execution 决定命令是否自动执行，Non-Workspace File Access 决定它能否越过当前项目边界。

这些设置叠加起来，才是真实风险面。单看一个开关可能没问题，但 Fast + Always Proceed + Always Proceed terminal + 开放 workspace 外文件访问，会把本地文件、终端和外部系统副作用串到一起。真实项目先保守，再按项目经验逐步放宽。
</details>

## 6. 一套稳妥的默认设置

真实项目的起点可以这样设：

| 设置 | 推荐值 |
| --- | --- |
| 默认 conversation mode | Planning |
| 简单局部任务 | 临时切 Fast |
| Artifact Review Policy | Request Review |
| Terminal Command Auto Execution | Request Review |
| Non-Workspace File Access | 关闭 |
| Browser / 外部系统操作 | 先只读，再白名单 |

这套设置不追求“最少点击确认”，而是追求每一步都能解释、审查和回退。等你对项目、团队流程和 agent 行为有足够经验，再考虑放宽。

## 7. 任务选择模板

启动任务前先判断：

```text
这个任务是否跨文件？
是否会运行命令？
是否需要浏览器？
是否会影响远端系统？
是否需要我看 plan？
是否有明确回退方式？
```

如果其中任意一项回答“是”，用 Planning + Request Review。只有在目标明确、范围小、结果容易回退时，才用 Fast。

## 本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

1. 什么任务适合 Fast，什么任务必须优先用 Planning？
2. Artifact Review Policy 和 Terminal Command Auto Execution 分别控制什么？
3. 为什么不应该默认开放 Non-Workspace File Access？

通过标准：你能给一个真实仓库配置一套默认安全设置，并能说明每个设置降低了哪类副作用风险。

## 官方来源

- [Google Antigravity Agent Modes / Settings](https://antigravity.google/docs/agent-modes-settings) —— 官方说明 Planning、Fast、Artifact Review、Terminal Auto Execution 和非 workspace 文件访问设置。
- [Google Antigravity Agent](https://antigravity.google/docs/agent) —— 官方 Agent 章节，用于理解这些模式和设置服务于多步 Agent 工作流。

## 接下来去哪

<Cards>
  <Card title="Agent 核心工作方式" description="回到 Agent 的组成，理解 model、tools、artifacts 和 knowledge 如何配合。" href="/docs/antigravity/official/01-agent-manager/00-agent-core" />
  <Card title="MCP、权限与安全" description="进一步理解 terminal、file、browser、MCP 的权限边界。" href="/docs/antigravity/official/05-mcp-permissions-security" />
</Cards>
