> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 规划智能体

# **概述**

Planning 功能让智能体模式在修改代码或执行命令之前，前置成一份**实施方案与计划**。\
对于中大型任务（如跨多文件的功能开发、重构或高风险变更），Planning 能提供清晰的可见性、可控的执行流程以及明确的落地路径。

开启 Planning 后，Qoder 会基于你的自然语言需求生成一份结构化的方案与规划。你可以先审阅和调整这份计划，再让智能体按步骤自动执行。

## **适用场景**

推荐在以下场景中启用 Planning：

* 处理**复杂功能**，涉及多个模块或多个文件。
* 预期会经历**多轮迭代**（设计、实现、测试、清理等）。

对于较小小的改动（例如“修正一个拼写错误”“重命名一个变量”等），你可以直接使用智能体执行，以节省时间，无需使用规划。

## **如何在智能体模式中使用**

规划智能体已内置于智能体模式中,无需单独配置。你可以通过两种方式调用它:
自动调用：智能体模式会根据你的请求智能判断何时需要进行规划。
显式调用：使用 /plan 命令显式请求规划智能体。
详细使用步骤如下：

### **1. 描述你的任务**

选择使用 /plan 显式调用，或直接用自然语言描述你的需求。在描述时，建议包含以下信息：

* 变更的目标或要实现的功能。
* 任何限制条件（例如"不能破坏现有 API""对于旧版路径需保持当前行为"等）。
* 可选：提及重要的文件或模块路径。

你的描述越清晰、越具体，生成的计划就会越贴合实际需求。

### **2. 生成计划**

当会话中启用 Planning 时，Qoder 会：

* 分析你的需求以及相关工程上下文。
* 根据需求为您生成一份完整的规划，包含目标、技术方案、技术栈、实施计划等内容。

此阶段不会修改任何文件，也不会执行任何命令——产出仅是一份可审阅的计划。

### **3. 审阅并调整计划**

在执行开始前，你可以根据自己的预期对计划做修改，例如：

* 编辑方案内容，使其更加精确、易懂。
* 补充 AI 未覆盖但你认为重要的步骤。

你也可以直接通过自然语言和 Qoder 协作调整计划，例如：“最后加一步更新文档”。

### **4. 启动执行**

当你确认计划无误后，可以启动执行：

* 智能体会像普通 Agent 模式那样读取文件、修改代码、运行命令，或调用 MCP 工具。
* 待办事项的状态会在聊天底部实时更新（未开始/进行中/已完成）。

根据你的设置，某些操作（尤其是终端命令或 MCP 工具调用）在执行前可能仍需要你手动确认。

### **5. 执行过程中的调整**

在计划执行过程中：

* 你可以随时查看每个待办事项的状态变化。
* 若发现计划本身或执行结果有问题，可以暂停、在聊天中说明新的要求，然后让 Qoder 更新计划后继续。
* 对于阻塞性问题（例如测试失败、依赖缺失等），Qoder 会在对话中明确指出，并规划相应的下一步。

这样，你始终保持决策权，而智能体负责具体的机械工作。

### **6. 收尾与回顾**

当所有待办事项执行完毕（或你主动终止执行）后：

* Qoder 可以按步骤总结本次执行中完成了哪些工作（例如每个 To-do 具体修改了哪些文件）。
* 你可以结合 diff 视图、本地测试或 PR 流程，对最终结果进行正常的代码评审。
* 如有后续工作需求，可以再次开启一个新的 Planning 流程，继续迭代。

## **最佳实践**

* **清晰描述目标**：像给同事派任务那样写你的第一个提示词，说明范围、限制条件和验收标准。
* **对高风险任务默认开启 Planning**：例如重构、接口调整、涉及核心路径的改动等。
* **迭代优化计划**：如果第一版计划不理想，可以让 Qoder 调整，例如“更关注测试部分”“尽量减少对公共接口的改动”等。
* **保持每一步足够小**：一个好的待办事项，应该能在一个较小的 diff 中看清它的影响范围。

借助 Planning，你可以在保持智能体高效率的同时，获得一份经过认真设计的实施方案，在安全与效率之间取得更好的平衡。