接入 ACP 编辑器

在支持 Agent Client Protocol 的编辑器中使用 Bub 应用。bub-acp-server 插件让编辑器接入应用已有的模型配置、工具和会话历史。

本指南使用 Zed，通过 stdio 启动 Agent 进程。先在终端验证连接，再配置编辑器。

开始前

你需要：

• 已安装 Bub，并且可以运行 bub --help。
• Bub 的模型配置已经可用。先在编辑器之外用 bub run 确认。
• 一个可以启动自定义 ACP Agent 的编辑器或客户端。本教程使用 Zed。

ACP 进程启动时会读取 Bub 的配置和环境变量，与 bub run 和 bub chat 相同。

1. 安装 ACP server 插件

bub-acp-server 位于 bubbuild/bub-contrib。把它安装到提供 bub 命令的同一个环境中：

bub install bub-acp-server@main

确认命令可用：

bub acp --help

输出中应包含：

Usage: bub acp [OPTIONS]

如果找不到 bub acp，请检查插件是否安装在当前 bub 命令所在的 Python 环境中。

2. 先确认 Bub 本身可用

在编辑器将要使用的同一个 shell 或环境中运行一个轮次：

bub run "Reply with one short sentence: hello from Bub."

先解决这一步遇到的配置或网络问题，再接入编辑器。

如果你的 Bub 配置放在项目 .env 中，需要确保 ACP 进程启动前已经加载这份环境。一个可移植的做法是写一个小启动脚本：

#!/usr/bin/env bash
set -euo pipefail
cd /path/to/your/project
set -a
. ./.env
set +a
exec bub acp

只有需要时才使用启动脚本。如果编辑器环境里直接运行 bub run 已经可用，就可以直接启动 bub acp。

3. 配置 Zed

用 zed: open settings 打开 Zed 设置，并添加一个自定义 Agent 服务：

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

如果 Zed 找不到 bub，可以改用绝对路径，或使用上一步的启动脚本：

{
  "agent_servers": {
    "Bub": {
      "type": "custom",
      "command": "/path/to/bub-acp-wrapper",
      "args": [],
      "env": {}
    }
  }
}

保持编辑器配置和 Bub 配置分离。Zed 负责启动 ACP 进程，并传入 agent_servers.Bub.env 里的环境变量；模型设置、tools、skills、Tape 和插件配置仍然由 Bub 自己读取和管理。

4. 启动 Bub 会话

保存设置后重新加载 Zed。用 cmd-?（macOS）或 ctrl-?（Linux/Windows）打开 Agent 面板，然后点击 + 新建线程并选择 Bub。

发送一条简单消息，例如：

HELLO

你应该会在 Agent 面板中看到 Bub 的回复。工具调用和流式模型文本会通过 ACP 会话更新转发给编辑器，因此轮次运行时可以显示活动状态。

当编辑器重新打开已有线程时，bub-acp-server 会加载匹配的 Bub Tape，并通过和实时轮次相同的 ACP 流式输出路径重放历史。这样恢复出来的用户消息、助手文本和工具事件会与 Bub 记录会话的方式保持一致。

排障

现象	检查
没有 bub acp	把 bub-acp-server 重新安装到编辑器实际使用的 bub 可执行文件所在环境。
编辑器提示无法启动 Bub	使用绝对路径作为 command，或让 command 指向能激活正确环境的启动脚本。
Bub 已启动但提示配置错误	在同一个环境中确认 bub run 可用。如果必要设置放在 .env，在 bub acp 之前加载这份文件。
编辑器无法加载或恢复会话	确认编辑器启动的是同一个 bub 环境，且其中 bub acp --help 可用；同时保持每次启动使用稳定的 BUB_HOME。
重启编辑器后旧线程消失	保持每次启动使用同一个 Bub 环境和 BUB_HOME。bub-acp-server 会把 ACP 会话元数据保存在 Bub 数据目录下，并从 Bub Tape 加载历史。
轮次已开始但界面没有活动显示	在 Zed 中运行 dev: open acp logs，检查 Zed 与 Bub 之间的 JSON-RPC 消息。

下一步

• 配置：Bub 的模型和运行时设置。
• 应用运行流程：Bub 如何把入站消息转成模型调用和出站消息。
• 构建插件：用 hooks、tools 和渠道扩展 Bub。