06 · VS Code Agent Mode 怎麼用
講清 VS Code Agent Mode 如何計劃、改檔案、呼叫工具、執行命令，並在本地工作區裡接受審查。
VS Code Agent Mode 不是 Chat 換了一個按鈕。VS Code 官方文件把 agent 定義為能自主完成程式設計任務的 AI 助手：給它高層目標，它會自己拆步驟、編輯檔案、執行命令，並在失敗時自我修正。
本章目標：你會把 Agent Mode 當成一個受控本地執行器使用，而不是當成更長的聊天框。重點是任務形狀、工具許可權、pending edits、terminal output 和驗收證據。
1. Agent Mode 的工作閉環
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，不要選專案核心程式碼。按這個順序走，跑完一次就懂邊界：
-
挑一個 demo 儲存庫（自己的 toy 專案、教程儲存庫或 fork 的開源練手倉）。不要第一次就在生產儲存庫裡用。
-
開啟 VS Code，先用 Ask 模式問"解釋當前檔案做什麼"——確認 Copilot 能看到你的程式碼，且回答靠譜。
-
切到 Agent 模式（Chat 面板頂部下拉選單）。
-
寫一個範圍明確的小任務 prompt，例如：
给 src/utils/format.ts 里的 formatDate 函数补一个最小单元测试。 边界： - 只改 tests/ 目录 - 不要改生产代码 - 完成后告诉我运行哪条命令验证 -
看 pending edits（编辑器里显示的待提交改动）：先点开每个被改的文件看 diff，再决定 Keep 还是 Undo。
-
不要直接 Keep 全部。即使 diff 看起来对，也至少检查一遍：是否只动了允许的目录？有没有删掉不该删的？
-
跑测试命令确认改动真的有效。
-
全部满意后再 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
目標：
修復使用者退出登入後仍顯示舊頭像的問題。
範圍：
先檢查 src/auth、src/components/Header 和相關測試。
可以改 auth 與 Header 相關檔案。
不要修改 billing、database、deployment。
執行：
先給計劃。
修改前說明要改哪些檔案。
執行命令前說明原因。
驗收：
展示 diff。
執行相關測試。
說明殘餘風險。這個 prompt 有四個關鍵點：目標、範圍、執行規則、驗收方式。Agent Mode 不怕任務小，怕邊界不清。
6. 審 pending edits，不審總結
Agent 結束後不要只看它的自然語言總結。要看：
- 檔案 diff 是否符合任務邊界。
- 是否有無關格式化、重新命名或重構。
- 命令是否真的執行成功。
- 測試是否覆蓋關鍵路徑。
- 是否有未說明的副作用。
- 失敗時是否能回復。
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：VS Code 官方 agents、Ask/Plan/Agent、permission levels 和 handoff 說明。
- Tools in VS Code：VS Code 官方工具型別、工具選擇、批准和信任邊界。
- Asking GitHub Copilot questions in your IDE：GitHub 官方 IDE Chat 文件，覆蓋 Chat、Plan 和 Agent Mode。
- GitHub Copilot features：官方功能頁，用於定位 Agent mode 在 agentic features 中的位置。