# IDE 集成

CodeBuddy Code 支持两种与编辑器集成的方式，属于同一层级的 IDE 集成能力：

1. 通过 ACP (Agent Client Protocol) 协议作为通用「智能体服务端」被 IDE 调用
2. 通过 `--ide` 启动参数和 `/ide` 斜杠命令，作为「IDE 插件的后端伴生进程」进行深度集成

## 集成方式一：ACP 协议集成

适用于 Zed 等支持 ACP 的编辑器，将 CodeBuddy Code 作为通用 Agent Server 使用。

### 支持的编辑器

#### Zed 编辑器

通过 ACP 协议完整集成，支持：

- 项目上下文感知
- 工具操作代理（文件读写、终端命令）
- 权限请求交互
- 实时流式响应

配置详见：[ACP 协议集成文档](./acp.md)

## 集成方式二：IDE 插件集成 （`--ide` / `/ide`)

适用于 VS Code / Cursor / Windsurf / JetBrains 系列 IDE，通过插件 + 本地 MCP 服务器的方式集成。IDE 侧插件负责：

- 创建并维护 MCP 连接 （SSE / WebSocket)
- 将工作区信息、选区等上下文通过 MCP 协议传给 CodeBuddy
- 暴露 `openFile` / `openDiff` / `getDiagnostics` / `close_tab` 等 IDE 能力给 CodeBuddy 调用

### `--ide` 启动参数

当您在终端中直接启动 CodeBuddy 时，可以通过 `--ide` 参数让 CLI 主动尝试连接当前工作目录对应的 IDE：

```bash
codebuddy --ide
```

行为说明：

- CodeBuddy 会在当前用户目录下扫描由 IDE 插件创建的锁文件，检测可用的 IDE 实例
- 仅当 IDE 的工作区包含当前目录时才认为是「有效 IDE」
- 仅当**恰好一个**有效 IDE 匹配当前工作目录时才会自动连接；如果零个或多个匹配，自动连接将静默跳过，您可以使用 `/ide` 手动选择
- 检测前会自动清理已退出的 IDE 进程对应的过期锁文件，避免连到无效端口
- 连接成功后，CLI 会通过 IDE MCP 服务器获得：
  - 文件/差异预览 （openFile / openDiff)
  - 诊断信息 （getDiagnostics)
  - 选区变化通知 （selection_changed)

> `--ide` 只是在「您从 IDE 终端手动启动 CLI」时的一种快捷连接方式，不负责真正启动 IDE 或插件。

### `/ide` 斜杠命令

当您在 CodeBuddy 的交互式界面中使用 IDE 插件集成时，可以通过 `/ide` 命令查看和管理当前 IDE 连接状态：

```text
/ide
```

典型用途包括：

- 查看当前是否已连接 IDE、连接的是哪一个 IDE
- 在存在多个可用 IDE 时，选择要连接的实例
- 手动断开或重新建立与 IDE 的 MCP 连接

具体交互行为由 IDE 集成 UI 决定，但整体定位是「管理 IDE 集成状态」而不是直接发起聊天。

## 选择哪种集成方式？

- 如果您的编辑器原生支持 ACP（例如 Zed），推荐使用 **ACP 协议集成**：
  - 使用 `codebuddy --acp` 启动
  - 由编辑器负责会话 UI 和工具代理
- 如果您使用 VS Code / Cursor / JetBrains 等，通过插件市场安装 CodeBuddy 插件，则推荐使用 **`--ide` / `/ide` 插件集成**：
  - 插件负责启动 CodeBuddy 进程并建立 MCP 连接
  - CLI 侧通过 `--ide` / `/ide` 与 IDE 建立和管理连接

两种方式在「集成层级」上是等价的，都是让 CodeBuddy 作为外部 Agent 与 IDE 深度协作，只是接入协议和 UI 承载方不同。

## 未来计划

后续版本将提供更多增强功能：

- 更友好的 DIFF 展示与修改确认流程 （结合 IDE diff 预览）
- 在 IDE 插件中提供更丰富的上下文选择与可视化
- 更多编辑器和 IDE 的官方集成

## 相关文档

- [ACP 协议集成](./acp.md) - 详细的 ACP 配置指南
- [CLI 参考手册](./cli-reference.md) - 命令行参数说明
- [斜杠命令](./slash-commands.md) - 包含 `/ide` 等会话命令总览
