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

# AI 原生编辑器与 IDE Agent

# AI 原生编辑器与 IDE Agent

AI 原生编辑器不是简单地在传统 IDE 上增加一个聊天窗口，而是把 AI 放进代码阅读、搜索、编辑、运行和审查的整个工作流中。IDE Agent 则进一步获得工具调用能力，可以围绕一个目标连续完成多步操作。

两者经常出现在同一个产品中，但概念并不完全相同：**AI 原生编辑器描述的是以 AI 为核心设计的开发环境；IDE Agent 描述的是能够在编辑器环境中观察、行动和验证的执行方式。**

<aside>
  🎯

  学习目标

  学完本节，你应该能够：

  * 区分 AI 原生编辑器、普通 IDE 插件和 IDE Agent
  * 理解代码库索引、上下文选择和 Agent 循环的作用
  * 判断任务应该使用行内编辑、对话还是 Agent 模式
  * 通过计划、权限、Diff 和测试控制 Agent 的执行风险
</aside>

## 先思考一个问题

如果一个编辑器能够一次修改十个文件，它就一定比只修改一个文件的工具更好吗？

不一定。修改范围越大，工具可能越高效，但错误也更容易扩散。真正重要的不是“能改多少文件”，而是它是否理解目标、选择了正确上下文，并能通过测试、构建和人工审查证明修改有效。

## 什么是 AI 原生编辑器

AI 原生编辑器是围绕 AI 协作重新设计的代码编辑环境。AI 不再只是一个独立插件，而是深度参与常见开发动作：

* 理解当前项目和代码关系
* 根据自然语言搜索代码
* 在一个或多个文件中生成修改
* 用 Diff 展示建议
* 解释错误和终端输出
* 生成、运行或修复测试
* 在对话、编辑和 Agent 模式之间切换

传统 IDE 的核心交互是“开发者操作工具”；AI 原生编辑器更强调“开发者描述目标，与 AI 共同完成操作”。

这并不意味着开发者不再使用文件树、终端、调试器和版本控制。相反，AI 原生编辑器把这些能力连接起来，让 AI 能在明确权限内调用它们。

## 它与 IDE 插件有什么区别

| 对比维度  | 普通 IDE 插件     | AI 原生编辑器          |
| ----- | ------------- | ----------------- |
| 产品位置  | 附加在现有 IDE 中   | AI 是核心设计部分        |
| 主要交互  | 补全、聊天、局部编辑    | 对话、项目编辑、Agent 工作流 |
| 上下文范围 | 常以当前文件或选中内容为主 | 更强调项目索引与跨文件关系     |
| 修改方式  | 局部建议较多        | 多文件 Diff 和任务级修改较多 |
| 工具联动  | 依插件和权限而定      | 通常更深地连接搜索、终端和版本控制 |
| 风险控制  | 逐次接受建议        | 需要计划、权限、检查点与整体审查  |

这是一条连续谱，而不是绝对分类。功能完善的 IDE 插件可能拥有 Agent 能力，AI 原生编辑器也仍然会提供最基础的代码补全。

## 什么是 IDE Agent

IDE Agent 是能够在编辑器环境中围绕目标连续执行多个步骤的 AI 系统。它通常可以：

1. 搜索代码库并读取相关文件
2. 分析需求和现有实现
3. 制定或展示修改计划
4. 创建、修改或删除文件
5. 调用终端、测试和构建工具
6. 阅读执行结果和错误日志
7. 根据反馈继续修正
8. 展示最终 Diff 和验证结果

它与普通聊天助手的区别，不只是回答更长，而是形成了行动闭环：

**理解目标 → 选择上下文 → 制定计划 → 修改代码 → 运行验证 → 分析结果 → 继续调整**

<aside>
  💡

  判断标准

  如果 AI 只能告诉你应该修改哪些文件，它更接近对话助手；如果它能够定位文件、应用修改、运行验证，并根据结果继续行动，它就更接近 IDE Agent。
</aside>

## 代码库索引为什么重要

大型项目不可能把所有文件同时交给模型。编辑器通常会建立项目索引，帮助 AI 根据任务找到相关内容。

索引可能包含：

* 文件和目录结构
* 函数、类和符号定义
* 引用与依赖关系
* 代码文本的语义表示
* 配置、测试和文档位置
* 最近修改或当前打开的文件

当你提出“给用户注册增加邮箱验证”时，IDE Agent 可能先搜索注册入口、用户模型、验证逻辑和测试，而不是盲目读取整个仓库。

但索引并不等于完整理解。以下情况仍可能导致上下文错误：

* 新文件尚未被索引
* 生成代码、外部依赖或子模块不可见
* 相似名称让搜索选错实现
* 真正的业务规则只存在于文档或团队共识中
* 项目过大，相关结果被无关内容挤出上下文

因此，在执行前检查“Agent 找到了哪些文件”，往往比直接查看生成代码更早发现问题。

## IDE Agent 的上下文从哪里来

常见上下文来源包括：

* 当前打开或选中的代码
* 你主动引用的文件和目录
* 代码库搜索与项目索引
* Git Diff 和最近提交
* 编译、测试和终端输出
* 项目规则与 Agent 指令文件
* 需求文档、接口说明和任务描述

高质量任务不只是给一句命令，还要确保 AI 能访问决定实现方式的关键信息。

例如，“增加订单取消功能”可能还需要说明：

* 哪些订单状态允许取消
* 取消后是否退款
* 是否记录审计日志
* 接口兼容性要求
* 哪些测试必须通过

代码库告诉 Agent“系统现在是什么样”，需求与约束告诉它“系统应该变成什么样”。

## 三种常见工作模式

### 1. 问答模式

适合解释代码、理解架构和比较方案。AI 主要输出文字，不直接大范围修改。

例如：

* 这个请求经过了哪些中间件？
* 用户权限在哪里检查？
* 这两个缓存实现有什么差异？

### 2. 编辑模式

由开发者指定文件或选区，AI 生成一个范围明确的修改。适合局部重构、增加错误处理和补充测试。

这种模式的优势是可控：人决定修改位置，AI 负责生成候选 Diff。

### 3. Agent 模式

开发者给出任务目标和约束，AI 自己搜索文件、规划步骤、修改代码并运行工具。适合跨文件、需要验证的任务。

任务越开放，越应该先要求 Agent 展示理解和计划，而不是立即修改。

## 一次可靠的 IDE Agent 工作流

### 第一步：定义完成条件

不要只说“实现用户头像上传”，还要说明：

* 支持哪些格式和大小
* 文件保存在哪里
* 接口如何返回错误
* 是否需要权限检查
* 要增加哪些测试
* 哪些现有行为不能改变

完成条件越清晰，Agent 越容易判断何时停止。

### 第二步：让 Agent 先调查

要求它先找到相关入口、数据模型、存储接口、配置和测试，说明现有流程，然后再提出方案。

这一步可以暴露错误上下文，避免在错误文件上快速执行。

### 第三步：审查计划

一个可审查的计划应说明：

* 准备修改哪些文件
* 每个文件为什么需要修改
* 数据流和接口是否改变
* 有哪些风险和待确认问题
* 准备用什么方式验证

如果计划无法解释修改与需求之间的关系，不应急着让它继续。

### 第四步：小步执行

优先把任务拆成可以单独检查的修改。例如先增加数据结构和测试，再实现接口，最后处理 UI，而不是一次重写整个功能。

### 第五步：审查 Diff

不要只看 Agent 的总结。重点检查：

* 是否修改了不相关文件
* 是否删除了必要逻辑
* 是否出现大范围格式化噪声
* 是否改变公开接口或数据结构
* 是否引入重复实现和硬编码
* 错误处理与权限检查是否完整

### 第六步：运行验证

根据项目运行：

* 格式化和静态检查
* 类型检查
* 单元测试和集成测试
* 构建
* 关键手工流程

测试通过只是证据之一。还要确认测试是否覆盖真实需求，以及 Agent 是否为了通过测试而改变了不应改变的行为。

### 第七步：让 Agent 汇报未知项

要求它明确列出：

* 已完成的内容
* 运行过的验证
* 没有验证的部分
* 仍然存在的风险
* 需要人工决定的问题

可靠的 Agent 不应只汇报成功，也应暴露不确定性。

## 示例：为项目增加搜索功能

任务是：给待办应用增加按标题关键词搜索。

一个低质量指令是：

> 加一个搜索功能。

更完整的任务可以写成：

> 为待办列表增加按标题关键词搜索。搜索忽略大小写，空关键词显示全部结果，暂不搜索描述字段。先调查列表数据流和现有测试，再给出计划。实现后运行相关单元测试和构建，不要引入新的状态管理库，并把最终 Diff 中的关键修改逐项说明。

IDE Agent 可能执行：

1. 搜索列表组件和数据来源
2. 查找现有筛选逻辑与测试
3. 规划输入框、状态和过滤函数的修改
4. 编写实现和测试
5. 运行测试与构建
6. 根据错误修复类型或组件问题
7. 展示最终 Diff 和验证结果

人的职责仍然包括确认交互是否符合产品预期、审查代码结构，以及验证 Agent 没有遗漏移动端或大数据量场景。

## 权限应该如何设置

IDE Agent 可能请求读取文件、修改代码和执行命令。权限应与任务风险匹配。

### 可自动允许的低风险操作

* 读取项目文件
* 搜索代码
* 查看 Git 状态和 Diff
* 运行只读检查
* 执行明确、安全的测试命令

### 建议逐次确认的操作

* 安装或升级依赖
* 修改构建和部署配置
* 执行数据库迁移
* 访问网络或外部服务
* 删除文件或批量重写
* 操作生产环境
* 读取密钥和敏感目录

<aside>
  🔐

  最小权限原则

  不要因为 Agent “可能用得到”，就一次开放全部权限。先给完成当前任务所需的最小范围，在明确原因后再临时扩大权限。
</aside>

## 常见失败模式

### 找对需求，找错代码

Agent 根据相似命名修改了旧实现或未使用的文件。执行前应检查引用关系和真实入口。

### 一次修改范围过大

Agent 顺手重构无关代码，使 Diff 难以审查。应明确“优先最小修改，不处理无关问题”。

### 陷入重复修复循环

同一个测试反复失败，Agent 不断尝试相似改动。此时应停止执行，重新检查假设、环境和测试本身，而不是增加重试次数。

### 为了通过测试而修改测试

测试失败后，Agent 可能放宽断言或删除用例。除非需求确实改变，否则应优先修复实现，并要求解释任何测试修改。

### 使用不存在或不兼容的 API

即使 Agent能读取项目，也可能根据训练经验使用错误版本的接口。需要依赖类型检查、文档和真实运行确认。

### 总结与实际 Diff 不一致

Agent 的文字总结可能遗漏意外修改。最终审查对象应是代码、Diff 和验证结果，而不是总结本身。

## 如何判断是否应该使用 Agent 模式

适合 Agent 模式的任务通常具备以下特征：

* 需要搜索和理解多个文件
* 修改步骤之间存在依赖
* 可以通过测试或构建验证
* 任务目标和边界相对清晰
* 执行环境可以隔离或回滚

以下任务更适合先使用问答或规划模式：

* 需求仍然模糊
* 架构方向尚未决定
* 涉及高风险生产操作
* 缺少测试和验证标准
* 修改后果难以回滚

Agent 最擅长的不是替人决定“应该做什么”，而是在目标明确后帮助完成“如何正确地做”。

## 人与 IDE Agent 如何分工

| 工作内容     | 人更适合负责 | Agent 更适合负责 |
| -------- | ------ | ----------- |
| 定义业务目标   | 是      | 辅助澄清        |
| 发现相关代码   | 监督     | 搜索和整理       |
| 制定实现计划   | 审核决策   | 生成候选计划      |
| 重复性修改    | 抽查     | 批量执行        |
| 运行测试     | 选择标准   | 执行并收集结果     |
| 判断产品是否正确 | 是      | 提供证据        |
| 承担上线责任   | 是      | 不承担         |

高质量协作不是把全部工作交给 Agent，而是让它承担搜索、执行和反馈等高频步骤，人保留目标、边界和最终判断。

## 练习：现在应该让 Agent 直接执行吗

你希望 Agent “把整个项目升级到最新依赖”，但还没有确认目标版本、破坏性变更、测试覆盖和回滚方式。Agent 表示可以立即修改依赖文件并自动修复错误。现在应该让它直接执行吗？

* 点击查看参考答案

  不应该立即执行。这个任务范围大、影响面广，而且完成条件不清晰。应先让 Agent 列出当前依赖、目标版本、主要破坏性变更、受影响模块和验证方案，再决定是否分批升级。执行时应创建可回滚的分支或检查点，先升级低风险依赖，运行完整测试和构建，并逐项审查依赖文件、迁移代码与配置变化。Agent 能自动修复错误，并不代表它能自动判断每个行为变化是否符合业务预期。

## 本节小结

AI 原生编辑器把 AI 融入项目搜索、代码编辑、终端、测试和版本控制；IDE Agent 则在这些能力之上形成连续的任务执行闭环。

需要记住：

1. AI 原生编辑器是一种开发环境设计，IDE Agent 是一种执行能力
2. 代码库索引帮助寻找上下文，但不代表 AI 已经理解全部业务
3. Agent 模式适合目标明确、可验证、可回滚的跨文件任务
4. 可靠流程是“调查—计划—执行—审查—验证—汇报未知项”
5. 自主程度越高，越需要最小权限、Diff 审查和人工检查点

IDE Agent 的价值不是让开发者停止思考，而是把机械的搜索和执行交给 AI，让开发者把注意力放在目标、设计、风险与结果上。