VS Code Copilot 计划代理：让 AI 编程更系统化的任务规划工具

对于复杂的开发任务，直接让 AI 生成代码往往会导致需求遗漏、实现不完整或代码质量不佳等问题。Visual Studio Code 引入的 Plan Agent（计划代理） 和 Todo List（任务列表） 功能，为这一问题提供了系统化的解决方案。

本文将深入探讨这两项功能的工作原理、使用场景以及最佳实践，帮助开发者更高效地利用 AI 完成复杂编码任务。

为什么需要计划代理？

传统的 AI 编程助手通常采用”即问即答”的模式：开发者提出需求，AI 立即生成代码。这种模式在处理简单任务时表现良好，但在面对复杂的多步骤任务时存在明显局限：

1. 需求理解不完整：AI 可能无法一次性把握所有需求细节和约束条件
2. 缺乏整体规划：直接编码容易忽视架构设计和依赖关系
3. 难以审查验证：代码生成后才发现不符合预期，返工成本高
4. 进度难以跟踪：长时间运行的任务缺乏可见的进度反馈

VS Code 的 Plan Agent 正是为解决这些痛点而设计的。它在代码实现之前引入了一个规划阶段，通过系统化的任务分解和需求确认，确保 AI 和开发者在同一认知层面上，从而显著提升生成代码的质量和可靠性。

Plan Agent 的核心设计理念

Plan Agent 的工作流程遵循”先规划、后执行”的理念，主要包含三个核心阶段：

1. 深度任务研究阶段

在这个阶段，Plan Agent 像一位经验丰富的架构师一样，利用只读工具对代码库进行全面分析：

• 代码库扫描：识别相关的文件、类、方法和依赖关系
• 约束识别：发现现有的技术栈、编码规范和架构模式
• 需求挖掘：分析用户需求背后的隐含要求和边界条件

这个阶段的关键在于 不做任何代码修改，纯粹聚焦于信息收集和需求理解。通过只读操作，Plan Agent 能够安全地探索代码库，避免意外破坏现有功能。

2. 任务分解与规划阶段

基于研究结果，Plan Agent 将复杂任务拆解为可管理的小步骤：

• 结构化分解：将高层需求转化为具体的技术任务
• 依赖关系梳理：识别任务之间的先后顺序和依赖关系
• 风险点标注：对于模糊或不确定的需求，明确提出待确认问题

Plan Agent 采用标准化的计划格式输出，包含以下关键内容：

• 摘要（Summary）：对整体任务的高层描述
• 实现步骤（Steps）：具体的执行步骤列表
• 开放问题（Open Questions）：需要开发者澄清的疑问

这种结构化的规划输出，为后续的实现提供了清晰的路线图。

3. 协作迭代与审批阶段

Plan Agent 生成的计划草案并非最终版本，而是一个可以反复迭代的工作文档：

• 开发者审查：评估计划的完整性和合理性
• 反馈优化：通过对话方式修正计划细节
• 需求明确：解答开放问题，调整范围或优先级

只有当开发者明确批准计划后，才会进入代码实现阶段。这种”人在回路”的设计，确保了 AI 始终在开发者的掌控之下。

如何使用 Plan Agent

目前，Plan Agent 功能仅在 VS Code Insiders 版本中提供。以下是详细的使用步骤：

步骤 1：启动 Plan Agent

1. 在 VS Code 中按 Ctrl+Alt+I（Windows/Linux）或 Cmd+Alt+I（macOS）打开聊天视图
2. 在代理下拉菜单中选择 Plan

步骤 2：提交高层任务描述

输入一个清晰的任务描述，可以是功能开发、重构、Bug 修复等。任务描述应该包含目标，但不需要过于详细。

示例任务描述：

实现一个支持 OAuth2 和 JWT 的用户认证系统

为所有 API 端点添加单元测试

修复保存按钮在提交后不重置表单字段的问题

步骤 3：审查和迭代计划

Plan Agent 将返回一份包含以下内容的计划草案：

• 高层摘要：任务的整体目标和范围
• 分步骤计划：具体的实现步骤
• 待确认问题：需要开发者澄清的疑问点

此时，你可以继续在 Plan 模式下与 AI 对话，进行多轮迭代：

"第 3 步应该在第 2 步之前完成"

"需要考虑支持多租户场景"

"添加一个关于性能测试的步骤"

最佳实践：在计划阶段充分迭代，确保所有需求和约束都被考虑周全，这将为后续实现奠定坚实基础。

步骤 4：批准并交付实施

当计划满足预期后，你有两种选择：

1. 交付给实现代理：点击”开始实现”按钮，将计划交给默认代理开始编码
   • 可以附加指令，如”从 UI 部分开始”或”只实现步骤 1 和 2”
2. 保存计划：将计划保存为文档，用于团队讨论、代码审查或后续参考
   • 可以要求添加特定章节，如”添加手动测试步骤”

Todo List：任务进度的可视化追踪

在复杂任务执行过程中，VS Code 的代理会自动创建一个 Todo List，将任务分解为多个子任务，并实时更新完成状态。这一机制带来了几个关键优势：

1. 进度可见性

Todo List 提供了直观的进度反馈，开发者可以清楚地看到：

• 哪些任务已完成
• 当前正在处理哪个任务
• 还有哪些任务待完成

这种可见性对于长时间运行的任务尤为重要，避免了”黑盒”般的等待焦虑。

2. 任务聚焦机制

对于 AI 代理而言，Todo List 起到了”工作清单”的作用，帮助代理在处理多步骤任务时保持专注，避免偏离主线或遗漏关键步骤。

3. 自然语言交互

开发者可以使用自然语言与 Todo List 交互：

"将步骤 1 修改为执行 X"

"添加一个新任务：优化数据库查询"

"清除任务列表"

AI 代理会根据开发者的反馈和任务执行过程中收集的信息，自动更新 Todo List。

Todo List 的最佳实践

1. 信任自动更新：除非任务规划明显不合理，否则让代理自动管理更新
2. 适时调整：发现遗漏或需要调整优先级时，及时使用自然语言指令修正
3. 结合检查点：对于关键步骤，使用 VS Code 的 Checkpoints 功能保存中间状态，便于回滚

Plan Agent 与传统 AI 编程助手的对比

这种对比并不意味着 Plan Agent 完全替代传统模式。对于简单的代码生成任务（如”写一个排序函数”），传统模式更高效。而对于复杂任务（如”重构整个认证系统”），Plan Agent 才是更优选择。

实战场景：使用 Plan Agent 重构遗留代码

让我们通过一个实际场景，看看 Plan Agent 如何提升重构任务的质量。

场景描述

假设你需要将一个使用传统 Session 认证的 ASP.NET Core 应用迁移到 JWT 认证。这个任务涉及：

• 多个控制器和中间件的修改
• 数据库 Schema 的调整
• 测试用例的更新
• 配置文件的变更

传统方式的问题

如果直接让 AI 生成代码，可能会遇到：

• 遗漏某些控制器的修改
• 忘记更新依赖注入配置
• 测试用例与新认证方式不兼容
• 配置参数不完整

使用 Plan Agent 的流程

步骤 1：提交任务

将应用从 Session 认证迁移到 JWT 认证，确保向后兼容

步骤 2：审查生成的计划 Plan Agent 可能输出如下计划：

### 摘要

将认证机制从基于 Session 的方式迁移到基于 JWT 的无状态认证，
同时保留对旧版 API 客户端的兼容性支持。

### 实现步骤

1. 安装并配置 JWT 相关 NuGet 包
2. 修改 Startup.cs/Program.cs 的认证配置
3. 更新所有控制器的 [Authorize] 特性
4. 实现 Token 生成和验证服务
5. 添加 Token 刷新机制
6. 更新数据库 Schema（添加 RefreshToken 表）
7. 修改登录端点以返回 JWT
8. 更新单元测试和集成测试
9. 更新 API 文档

### 开放问题

- 是否需要支持 Token 过期时间的动态配置？
- 旧版 Session 认证的过渡期是多久？
- 是否需要实现 Token 黑名单机制？

步骤 3：迭代优化

"添加一个步骤：实现平滑迁移策略，支持同时接受 Session 和 JWT"

步骤 4：批准并执行

"从步骤 1 到 5 开始实现，其他步骤稍后处理"

通过这种方式，Plan Agent 确保了迁移任务的每个方面都被考虑到，显著降低了遗漏关键步骤的风险。

Plan Agent 的局限性与注意事项

尽管 Plan Agent 在处理复杂任务时表现出色，但也有一些局限需要注意：

1. 仅在 Insiders 版本可用

目前，Plan Agent 功能尚未发布到稳定版 VS Code，只能在 VS Code Insiders 中使用。这意味着：

• 功能可能不够稳定，存在 Bug
• API 和交互方式可能会变化
• 不适合在生产环境的关键项目中使用

2. 计划质量依赖代码库质量

Plan Agent 通过分析代码库来理解需求和约束。如果代码库存在以下问题，计划质量会受影响：

• 缺乏注释和文档
• 命名不规范，难以理解
• 架构混乱，依赖关系复杂

建议：在使用 Plan Agent 之前，确保代码库具有基本的可读性和结构清晰性。

3. 不适合所有任务类型

Plan Agent 最适合以下类型的任务：

• 多步骤、多文件的重构
• 需要架构设计的新功能开发
• 涉及多个模块的 Bug 修复

对于以下任务，直接使用传统 AI 助手可能更高效：

• 单个函数的实现
• 简单的代码格式化
• 快速的语法修正

4. 人工审查不可或缺

Plan Agent 生成的计划并非完美无缺，仍然需要开发者的专业判断：

• 技术可行性：计划中的方案是否符合技术约束？
• 业务合理性：是否符合实际业务需求？
• 安全性考虑：是否引入潜在的安全风险？

切勿盲目信任 AI 生成的计划，始终保持批判性思维。

与其他 VS Code Copilot 功能的协同

Plan Agent 并非孤立存在，它与 VS Code Copilot 的其他功能形成了完整的 AI 辅助开发生态：

1. 与 Chat Sessions 的结合

Chat Sessions 允许你保存和恢复对话上下文。结合 Plan Agent，你可以：

• 在不同时间段继续同一个计划任务
• 保存多个备选计划方案进行对比
• 与团队成员共享计划讨论记录

2. 与 Checkpoints 的配合

Checkpoints 功能允许你在关键步骤保存代码状态。在执行 Plan Agent 的计划时：

• 在每个主要步骤完成后创建 Checkpoint
• 如果某个步骤出现问题，快速回滚到上一个 Checkpoint
• 对比不同实现方案的效果

3. 与 Custom Instructions 的集成

通过配置自定义指令，你可以让 Plan Agent 更符合团队的编码规范：

{
  "github.copilot.chat.codeGeneration.instructions": [
    "所有计划必须包含单元测试步骤",
    "优先考虑性能和安全性",
    "遵循公司的架构设计原则"
  ]
}

这样，Plan Agent 生成的计划将自动融入团队的最佳实践。

面向未来：Plan Agent 的演进方向

虽然 Plan Agent 仍处于早期阶段，但从其设计理念可以预见未来的发展方向：

1. 更强的上下文理解能力

未来的 Plan Agent 可能会集成更多数据源：

• Git 提交历史分析，理解代码演进趋势
• Issue 和 PR 记录，把握项目的痛点
• 文档和 Wiki 内容，补充隐性知识

2. 多人协作的计划管理

支持团队成员共同参与计划的制定和审查：

• 计划的版本控制和变更追踪
• 多人批注和讨论功能
• 与项目管理工具（如 Azure DevOps、Jira）的集成

3. 自适应的计划执行

根据执行过程中的实际情况动态调整计划：

• 发现新的依赖关系时，自动调整步骤顺序
• 遇到意外错误时，提出备选方案
• 根据测试结果，优化实现策略

4. 领域专用的计划模板

针对特定领域和技术栈，提供预定义的计划模板：

• 微服务架构迁移计划
• 数据库性能优化计划
• 安全漏洞修复计划

总结与建议

Plan Agent 和 Todo List 代表了 AI 辅助编程的一个重要演进方向：从”即时响应”转向”系统规划”。通过引入规划阶段，这两项功能显著提升了 AI 在复杂任务中的可靠性和可控性。

关键要点回顾

1. 先规划后执行：Plan Agent 通过深度研究、任务分解和协作迭代，确保需求被充分理解
2. 进度可视化：Todo List 提供实时的任务追踪，帮助开发者和 AI 保持同步
3. 人在回路：始终保持人工审查和批准，AI 是助手而非替代品
4. 适用场景：最适合多步骤、多依赖的复杂任务，而非简单的代码生成

实践建议

1. 尝试 Insiders 版本：如果你经常处理复杂任务，建议安装 VS Code Insiders 体验 Plan Agent
2. 投资于代码库质量：良好的代码结构和文档会显著提升 Plan Agent 的效果
3. 建立计划审查清单：制定一套标准，用于评估 AI 生成计划的完整性和合理性
4. 结合其他工具：将 Plan Agent 与 Chat Sessions、Checkpoints 等功能配合使用，形成完整工作流

进一步学习

• VS Code Copilot Chat 工具配置
• 上下文工程用户指南
• Prompt 工程最佳实践

随着 AI 技术的不断发展，像 Plan Agent 这样的工具将越来越多地改变我们的开发方式。拥抱这些变化，但始终保持批判性思维，才能真正发挥 AI 的价值。

原文链接：Planning in VS Code chat - Visual Studio Code