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 中的位置。