---
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="/zh-Hant/docs/github-copilot/understanding/05-context-engineering-for-copilot" />
  <Card title="下一篇" description="繼續學習 Copilot Cloud Agent 適合哪些非同步分支任務。" href="/zh-Hant/docs/github-copilot/understanding/07-cloud-agent-pr-loop" />
  <Card title="Agent 工具" description="回到官方重組頁深讀 built-in tools、MCP tools、extension tools 和批准機制。" href="/zh-Hant/docs/github-copilot/official/03-vscode-agent-mode/agent-tools" />
</Cards>
