> ## 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.

# Agent 模式

Agent 模式是 Quest 下的自主编程能力。Agent 会端到端完成开发任务——自主澄清需求、规划方案、执行代码、验证结果，无需持续人工介入。

## 适用场景

* **功能开发与重构**：适合开发新功能、修复疑难 Bug 或进行代码重构。在处理这类需要明确技术方案的任务时，建议选择 Spec 驱动场景。Agent 会自动检视项目全局代码，并先生成结构化的 Spec 文档，确保整体方向与你的预期一致后再进行编码。
* **原型快速验证**：适合验证产品想法或从零搭建演示原型。选择原型探索场景后，Agent 会跳过 Spec 阶段直接进入编码。利用概要文件区的实时预览能力，你可以立刻看到代码运行的实际效果。
* **自动化工具搭建**：适合编写批量处理脚本、数据清洗工具或自定义 CLI 脚本。选择创建工具场景，Agent 会自动评估当前环境，选择最合适的技术栈完成工具的端到端开发。
* **快速迭代优化**：适合探索性的调整。你可以先让 Agent 跑出一个基础版本，在查看初步效果后，直接在对话框中用自然语言（例如“按钮再大一点”、“切换成暗色主题”）追加需求，进行持续的快速迭代。

## 使用指南

### 创建任务

点击左侧任务列表顶部的 **创建 Quest** 按钮，在弹出的面板中选择 **Agent** 模式。你可以在此处指定初始需求并选择是否需要 Spec 驱动。

### 编辑已发送消息

在对话过程中，如果你发现自己遗漏了关键上下文或指令有误，可以点击已发送消息气泡进入编辑状态。在编辑状态下，你可以：

* **修改提示词**：重新编辑输入的文字指令，使其更准确。
* **修改附带上下文**：增删或替换消息中附带的文件、代码片段和截图等。
* **切换模型与模式**：根据任务难度切换到更强大的模型，或更改对话模式。

修改完成后重新提交，工作区文件将安全地回滚到该轮对话之前的状态，从这条消息开始产生的所有后续文件变更都会被自动丢弃，让你毫无负担地纠正方向。

<Note>编辑状态下暂不支持上下文压缩和一键优化提示词功能，需手动调整输入。</Note>

### Revert

在 Agent 自主执行期间，如果它选择的技术路线不符合你的期望，或者你对当前对话轮次生成的代码不满意，你可以直接点击对话流中的 **Revert** 按钮。工作区会立即恢复到该轮操作之前的状态，撤销的内容可以在 Diff View 中同步查看与对比。这为你提供了极其安全的试错空间。

<Note>Experts 模式暂不支持 Revert。</Note>

## 最佳实践

### 写好任务描述

避免使用诸如“帮我改下代码”等模糊指令。尽量明确说明你的具体目标、倾向的技术栈以及验收标准（例如：“用 React 编写一个带分页的表格组件”）。通过 `@` 引用相关文件或代码片段，能极大帮助 Agent 准确理解项目上下文。

### 选对场景和环境

* **复杂度区分**：涉及多个文件的复杂功能开发，建议选 Spec 驱动以确保方案清晰；对于快速验证的小想法，直接选原型探索跳过 Spec 即可。
* **环境隔离**：简单的局部修改可以使用 Local 环境快速得到反馈；而涉及大量文件修改的重型开发，强烈建议使用 Worktree 环境，以实现变更的绝对隔离，确保主分支安全。

### 善用迭代

不要期望 AI 一次性交付完美的复杂系统。你可以先让 Agent 完成 MVP（最小可行性产品）版本，确认大方向正确后，再通过多轮对话不断追加细节需求。在 Spec 驱动模式下，多通过对话让 Agent 去修改 Spec，而不是自己手动去改，这样 Agent 能保持最好的上下文理解。Agent 支持无限次迭代，你可以像指导真实工程师一样与它协作，直到满意为止。