通过 ACP 接入 IDE

Agent Client Protocol（ACP）是一套开放的标准协议，允许代码编辑器（如 Zed）以子进程方式启动 Agent，并通过 JSON-RPC 双向流式交换会话、提示词、工具调用状态和代码编辑操作。

bub-acp-server 插件将 Bub 应用接入 ACP 协议，使你能够在日常使用的 IDE 中直接唤出 Bub 进行代码编写、重构与排障。

开始之前

已安装 Bub 应用，并配置可用模型。
已安装 Zed 编辑器（或其他支持 ACP 协议的客户端）。

Zed 等应用程序在启动时，其继承的 PATH 和环境变量通常与终端（如 ~/.zshrc 或 ~/.bashrc）不同。请先通过终端确认当前环境的 bub 绝对路径：

command -v bub

1. 安装插件

在包含 Bub 的 Python 环境中安装适配器插件：

bub install bub-acp-server@main
bub acp --help

如果安装成功，终端输出将显示：

Usage: bub acp [OPTIONS]

bub-acp-server 默认使用标准输入输出（stdio）与宿主编辑器通信。

2. 配置 Zed

在 Zed 中使用快捷键 Cmd+Shift+P（macOS）或 Ctrl+Shift+P（Linux/Windows）打开命令面板，输入并执行 zed: open settings，在打开的 settings.json 中添加 agent_servers 配置。

方案 A：全局安装

如果 bub 位于系统全局 PATH 中，且不需要额外加载特定项目的 .env 文件，可直接配置：

{
  "agent_servers": {
    "Bub": {
      "type": "custom",
      "command": "bub",
      "args": ["acp"],
      "env": {}
    }
  }
}

如果 Zed 报错找不到 bub，请将 "command" 替换为前面通过 command -v bub 获取到的绝对路径。

方案 B：使用包装脚本

如果你的项目依赖特定的 Python 虚拟环境，或者模型 API Key 保存在工作区根目录的 .env 中，强烈建议编写一个启动包装脚本（例如 ~/.bub/bub-acp-wrapper）：

#!/usr/bin/env bash
set -euo pipefail

# 1. 激活虚拟环境（若有）
# source /path/to/venv/bin/activate

# 2. 加载工作区或用户环境变量
if [ -f "$PWD/.env" ]; then
  set -a
  source "$PWD/.env"
  set +a
fi

# 3. 使用绝对路径启动 Bub ACP
exec /path/to/your/bub acp

赋予执行权限后，在 Zed 设置中直接指向该脚本：

chmod +x ~/.bub/bub-acp-wrapper

{
  "agent_servers": {
    "Bub": {
      "type": "custom",
      "command": "/Users/yourname/.bub/bub-acp-wrapper",
      "args": [],
      "env": {}
    }
  }
}

3. 启动会话

保存设置后重启 Zed 或重新加载配置：

按 Cmd+?（macOS）或 Ctrl+?（Linux/Windows）打开 Zed 的 Agent 侧边面板。
在模型/后端选择菜单中切换为 Bub。
在输入框中输入消息进行测试：
```
你好！请介绍一下你自己。
```
Bub 将通过流式传输把响应、思考过程及工具调用步骤逐一投递在面板上。

4. 会话与恢复

bub-acp-server 具备完整的会话生命周期管理能力：

新建会话：在 Zed 面板新建 Thread，对应底层开启一条全新的会话 Tape。
历史恢复：切换回旧 Thread 时，Bub 会从持久化 Tape 存储中提取并重放该会话的历史消息与工具上下文。
持久化绑定：会话的元数据索引存放在 $BUB_HOME/acp-sessions.json。只要你的 BUB_HOME 和工作区路径保持稳定，重启编辑器后历史会话列表依然完好无损。
模型与推理参数：在 Zed 界面中调节的思考深度（Reasoning Effort）或选择的具体模型别名，会自动附加在本次 ACP 会话的后续请求中。

5. 远程服务模式

在大多数本地开发场景中，默认的 stdio 是最轻量且低开销的选择。如果你把 Bub 部署在云端开发机（Remote Server）或 Docker 容器内，需要供本地开发机上的编辑器远程调用，可以使用 HTTP/WebSocket 服务模式。

方式 1：独立启动服务

# 启动 HTTP 服务
bub acp --transport http

# 或启动 WebSocket 服务
bub acp --transport websocket

默认监听地址为 127.0.0.1:28200（HTTP 端点为 http://127.0.0.1:28200/acp，WebSocket 端点为 ws://127.0.0.1:28200/acp）。

方式 2：作为 Bub Gateway 渠道长驻运行

通过网关模式可以同时维护会话池与后台连接：

bub gateway --enable-channel acp-server

环境变量	默认值	作用说明
`BUB_ACP_SERVER_HOST`	`127.0.0.1`	监听的主机 IP（如需对外开放可设为 `0.0.0.0`，注意网络安全）
`BUB_ACP_SERVER_PORT`	`28200`	服务端口
`BUB_ACP_SERVER_CERTFILE`	空	TLS 证书路径（开启 HTTPS/WSS 必须）
`BUB_ACP_SERVER_KEYFILE`	空	TLS 私钥路径

故障排查

常见问题	排查切入点	解决建议
Zed 提示找不到 Agent Server	检查 `"command"` 路径	在终端执行 `command -v bub`，将配置中的 `command` 改为系统绝对路径。
面板显示启动失败或退回	环境变量未生效（如缺少 API Key）	采用方案 B 编写 wrapper 脚本，在脚本中强制 `source` 所需的 `.env`。
不清楚协议握手卡在哪里	查看 Zed 的 ACP 通信日志	在 Zed 中打开命令面板，执行 `dev: open acp logs`，实时观察 JSON-RPC 的交互事件。
工具调用没有正常触发	检查客户端能力协商（Capabilities）	确认工作区具有读写权限；在同一终端下先用 `bub run` 测试工具是否正常。
会话历史无法保存	检查 `BUB_HOME` 目录权限	确保运行 Zed 的用户对 `~/.bub` 目录拥有读写权限。