---
title: "06 · VS Code Agent Mode 怎么用"
description: "讲清 VS Code Agent Mode 如何计划、改文件、调用工具、运行命令，并在本地工作区里接受审查。"
verifiedAt: "2026-05-06"
---

VS Code Agent Mode 不是 Chat 换了一个按钮。VS Code 官方文档把 agent 定义为能自主完成编程任务的 AI 助手：给它高层目标，它会自己拆步骤、编辑文件、运行命令，并在失败时自我修正。

> [!NOTE]
> **本章目标**：你会把 Agent Mode 当成一个受控本地执行器使用，而不是当成更长的聊天框。重点是任务形状、工具权限、pending edits、terminal output 和验收证据。

## 1. Agent Mode 的工作闭环

```mermaid
flowchart TD
  Goal["高层目标"] --> Plan["拆解步骤"]
  Plan --> Context["读取工作区和相关文件"]
  Context --> Tools["选择工具"]
  Tools --> Edit["编辑文件"]
  Tools --> Command["运行 terminal command"]
  Edit --> Pending["Pending edits / Diff"]
  Command --> Output["Terminal output"]
  Pending --> Review["人工审查"]
  Output --> Review
  Review --> Accept{"接受?"}
  Accept -->|是| Test["测试 / lint / build"]
  Accept -->|否| Iterate["继续迭代或回滚"]
  Test --> Done["提交前审查"]
```

Agent Mode 的核心不是“自动”，而是本地执行闭环：计划、读取、修改、运行、展示证据、人工确认。

### 第一次怎么用：15 分钟最小可执行

新手第一次用 Agent Mode，不要选项目核心代码。按这个顺序走，跑完一次就懂边界：

1. **挑一个 demo 仓库**（自己的 toy 项目、教程仓库或 fork 的开源练手仓）。**不要**第一次就在生产仓库里用。
2. **打开 VS Code，先用 Ask 模式**问"解释当前文件做什么"——确认 Copilot 能看到你的代码，且回答靠谱。
3. **切到 Agent 模式**（Chat 面板顶部下拉菜单）。
4. **写一个范围明确的小任务 prompt**，例如：

   ```text
   给 src/utils/format.ts 里的 formatDate 函数补一个最小单元测试。

   边界：
   - 只改 tests/ 目录
   - 不要改生产代码
   - 完成后告诉我运行哪条命令验证
   ```

5. **看 pending edits**（编辑器里显示的待提交改动）：先点开每个被改的文件看 diff，再决定 Keep 还是 Undo。
6. **不要直接 Keep 全部**。即使 diff 看起来对，也至少检查一遍：是否只动了允许的目录？有没有删掉不该删的？
7. **跑测试命令**确认改动真的有效。
8. 全部满意后再 commit。

跑完这 8 步你就知道：Agent Mode **不是"全自动"**——它把决策点从"写代码"前移到"审 diff"，节省的是写代码时间，不是审查时间。

## 2. Ask、Plan、Agent 先分清

VS Code 官方 agents 总览列出三个 built-in agents：

- **Ask**：回答问题，不主动改文件。
- **Plan**：先研究和生成实施计划。
- **Agent**：按目标执行，改文件、调用工具、跑命令。

选择规则很直接：

| 任务状态 | 入口 |
| --- | --- |
| 只想理解代码或错误 | Ask |
| 需求不清、影响多模块 | Plan |
| 范围清楚，需要真实改代码 | Agent |
| 想后台继续或开 PR | Copilot CLI / Cloud Agent |

很多失败来自入口选错。需求还没说清就开 Agent，它会用有限上下文补脑；应该先 Plan。

## 3. 什么任务适合 Agent Mode

适合：

- 修一个能复现的本地 bug。
- 补一个已有模式明确的小功能。
- 给某个模块补测试。
- 按现有风格重构局部代码。
- 修 lint、类型错误或 failing test。
- 生成文档并同步相关示例。

不适合直接交：

- 删除数据、改生产配置、发布部署。
- 权限、支付、密钥和迁移脚本。
- 没有测试入口的大范围改造。
- 依赖登录后台或本机私密 UI 的操作。
- 一句话需求但没有验收标准。

判断标准：如果一个初级工程师拿到任务也需要先问清楚，Agent Mode 也应该先 Plan 或追问。

## 4. 工具和权限怎么管

VS Code 官方 Tools 文档把 agent 工具分成三类：built-in tools（内置工具，如读写文件、搜索代码库、运行 terminal 命令）、MCP tools（接到外部系统）和 extension tools（VS Code 扩展提供的工具）。没有工具时模型只能生成文本；有工具后，它能读写文件、搜索代码库、运行命令、连接外部服务。

这就是权限边界。

团队默认策略：

- 读文件、搜索代码库：通常可以开放。
- 写文件：限制在任务相关目录。
- terminal command：执行前说明目的和副作用。
- MCP：按任务启用，不默认全开。
- 外部服务、数据库、云资源：默认人工批准。
- destructive command：默认禁止自动执行。

VS Code 还提供不同 permission levels（权限等级）：Default Approvals（默认批准，每个敏感动作前问一次）更适合商业项目初期；Bypass Approvals（跳过批准）和 Autopilot Preview（自动驾驶预览，整段任务无人值守）只适合低风险、可回滚、验证完善的场景。

## 5. 一个可用 prompt

```text
目标：
修复用户退出登录后仍显示旧头像的问题。

范围：
先检查 src/auth、src/components/Header 和相关测试。
可以改 auth 与 Header 相关文件。
不要修改 billing、database、deployment。

执行：
先给计划。
修改前说明要改哪些文件。
运行命令前说明原因。

验收：
展示 diff。
运行相关测试。
说明残余风险。
```

这个 prompt 有四个关键点：目标、范围、执行规则、验收方式。Agent Mode 不怕任务小，怕边界不清。

## 6. 审 pending edits，不审总结

Agent 结束后不要只看它的自然语言总结。要看：

1. 文件 diff 是否符合任务边界。
2. 是否有无关格式化、重命名或重构。
3. 命令是否真的运行成功。
4. 测试是否覆盖关键路径。
5. 是否有未说明的副作用。
6. 失败时是否能回滚。

VS Code 的优势是 pending edits 和 terminal output 都在本地工作区里。把它当成 code review 面板，不要当成聊天记录。

## 7. 和 Cloud Agent 的边界

本地 Agent Mode 适合依赖本地上下文、需要你逐步看改动的任务。Cloud Agent 适合 issue 清楚、能通过分支和 PR 验收的异步任务。

选择规则：

- 要看本地未提交 diff：用 Agent Mode。
- 要用本地浏览器或 terminal：用 Agent Mode。
- 要后台实现 issue 并开 PR：用 Cloud Agent。
- 要团队 reviewer 审查：Cloud Agent 结果必须回到 PR。

不要把本地现场交给 Cloud Agent，也不要把可以异步 PR 化的任务一直卡在本地编辑器里。

## 本章自检

启动 Agent Mode 前确认：

- 任务是否清楚到可以执行？
- 是否应该先 Ask 或 Plan？
- 允许改哪些路径？
- 允许调用哪些工具和命令？
- 结果如何通过 diff、terminal output、test 和 review 验收？

通过标准：你能让 Agent Mode 在受控范围内完成任务，并且不依赖它的口头总结判断是否完成。

## 官方来源

- [Using agents in Visual Studio Code](https://code.visualstudio.com/docs/copilot/agents/overview)：VS Code 官方 agents、Ask/Plan/Agent、permission levels 和 handoff 说明。
- [Tools in VS Code](https://code.visualstudio.com/docs/copilot/concepts/tools)：VS Code 官方工具类型、工具选择、批准和信任边界。
- [Asking GitHub Copilot questions in your IDE](https://docs.github.com/en/copilot/how-tos/chat-with-copilot/chat-in-ide)：GitHub 官方 IDE Chat 文档，覆盖 Chat、Plan 和 Agent Mode。
- [GitHub Copilot features](https://docs.github.com/en/copilot/get-started/features)：官方功能页，用于定位 Agent mode 在 agentic features 中的位置。

## 接下来去哪

<Cards>
  <Card title="上一篇" description="先把 Copilot 的上下文工程和 instructions 优先级理清。" href="/docs/github-copilot/understanding/05-context-engineering-for-copilot" />
  <Card title="下一篇" description="继续学习 Copilot Cloud Agent 适合哪些异步分支任务。" href="/docs/github-copilot/understanding/07-cloud-agent-pr-loop" />
  <Card title="Agent 工具" description="回到官方重组页深读 built-in tools、MCP tools、extension tools 和批准机制。" href="/docs/github-copilot/official/03-vscode-agent-mode/agent-tools" />
</Cards>
