ACP 编辑器集成

ACP 协议概述

ACP（Agent Communication Protocol，代理通信协议）是一种开放标准协议，旨在实现 AI 代理与编辑器环境之间的标准化通信。随着 AI 编程助手从简单的代码补全进化为能够自主完成复杂任务的代理系统，代理与编辑器之间的高效通信成为关键基础设施。

ACP 协议由 Hermes Agent 团队联合多家编辑器厂商共同提出，其核心理念是解耦代理后端与编辑器前端。通过 ACP，任何兼容 ACP 的编辑器都可以与任何兼容 ACP 的代理进行通信，实现了"一次开发，随处运行"的生态愿景。

ACP 的设计受到 LSP（Language Server Protocol）和 DAP（Debug Adapter Protocol）的启发，但在能力范围上更为广泛——它不仅支持代码编辑操作，还支持文件管理、终端控制、任务编排等复杂交互。

ACP 的工作机制

ACP 采用 JSON-RPC 2.0 作为通信协议基础，通过标准化的方法调用和事件推送实现双向通信。

协议架构

ACP 定义了三个核心层：

核心方法调用

ACP 定义了一系列标准方法，覆盖编辑器与代理交互的常见场景：

// ACP 协议核心方法定义
interface ACPMethods {
  // 代理控制
  "agent/start": { task: string; context?: FileContext };
  "agent/stop": { sessionId: string };
  "agent/status": { sessionId: string };

  // 文件操作
  "file/read": { path: string };
  "file/write": { path: string; content: string };
  "file/diff": { path: string; oldContent: string; newContent: string };

  // 编辑器交互
  "editor/highlight": { range: Range; message?: string };
  "editor/suggest": { position: Position; suggestions: Suggestion[] };
  "editor/selection": { sessionId: string; selection: Selection };

  // 事件推送
  "event/log": { level: string; message: string };
  "event/progress": { sessionId: string; progress: number };
  "event/complete": { sessionId: string; result: TaskResult };
}

ACP 的通信流程遵循"请求-响应"模式，代理发送请求到编辑器，编辑器处理后返回响应。此外，ACP 还支持服务器推送通知，编辑器可以实时接收代理的执行进度和日志信息。

VS Code ACP 扩展安装与配置

安装步骤

# 通过 VS Code 扩展市场安装
code --install-extension hermes-agent.acp-extension

# 或从 GitHub Release 安装
curl -LO https://github.com/hermes-agent/vscode-acp/releases/latest/download/acp-extension.vsix
code --install-extension acp-extension.vsix

配置扩展

安装完成后，在 VS Code 的设置中搜索 "ACP" 进行配置：

{
  "acp.agentPath": "/usr/local/bin/hermes-agent",
  "acp.autoConnect": true,
  "acp.transport": "stdio",
  "acp.maxSessionMemory": 4096,
  "acp.enableRemoteAgents": true,
  "acp.remoteAgentRegistry": "https://registry.hermes-agent.io",
  "acp.logLevel": "info"
}

功能特性

VS Code ACP 扩展提供了丰富的编辑器集成功能：

• 内联代码建议：代理直接在编辑器中以差异对比形式展示代码修改建议
• 任务面板：侧边栏显示当前代理任务状态、进度和执行日志
• 文件变更追踪：代理修改的文件以不同颜色高亮显示
• 对话历史：记录与代理的完整对话历史，支持回滚操作

Cursor / Windsurf ACP 集成

除了 VS Code，ACP 协议也被 Cursor 和 Windsurf 等新一代 AI 编辑器原生支持。

Cursor 集成

在 Cursor 的命令面板中运行 "ACP: Connect to Agent"，输入 Hermes Agent 的启动命令即可建立连接：

# .cursor/acp-config.yaml
agent:
  command: hermes-agent
  args: ["--acp-mode", "--port", "9876"]
  transport: websocket
  autoRestart: true

features:
  inlineSuggestions: true
  taskPanel: true
  terminalIntegration: true

permissions:
  allowFileWrite: true
  allowTerminalExec: true
  allowNetworkAccess: false

Windsurf 集成

Windsurf 提供了更深度的 ACP 集成，支持 Agent 与编辑器的双向协作：

# .windsurf/acp-config.yaml
agent:
  endpoint: "ws://localhost:9876/acp"
  transport: websocket
  heartbeat: 30

collaboration:
  mode: "interactive"  # interactive | autonomous | review
  autoApproveSimpleChanges: true
  requireApprovalFor:
    - fileDelete
    - packageInstall
    - gitPush

远程 Agent 控制模式

ACP 协议的一个重要特性是支持远程 Agent 控制。这意味着 Agent 可以运行在远程服务器或云端，而编辑器在本地运行，通过网络连接进行通信。

远程模式架构

远程 Agent 控制模式特别适用于以下场景：

• 本地计算资源不足，需要利用云端 GPU 运行大模型
• 团队共享 Agent 实例，统一管理配置和工具链
• 在 CI/CD 环境中使用 Agent 进行自动化任务
• 安全敏感项目，代码不能离开内网环境

# 在远程服务器上启动 ACP Server
hermes-agent acp-server \
  --port 9876 \
  --tls-cert /etc/certs/server.crt \
  --tls-key /etc/certs/server.key \
  --auth-token ${ACP_AUTH_TOKEN} \
  --allowed-origins "https://editor.company.com"

# 在本地编辑器连接远程 Agent
# VS Code 命令: ACP: Connect to Remote Agent
# 输入: wss://agent-server.company.com:9876/acp

实战：在编辑器中用 ACP 调用 Hermes Agent

下面我们通过一个完整的实战案例，演示如何在 VS Code 中通过 ACP 调用 Hermes Agent 完成代码重构任务。

场景：重构旧版 React 组件到 Hooks 写法

// 旧版类组件 - 需要重构的目标代码
class UserProfile extends React.Component {
  constructor(props) {
    super(props);
    this.state = { user: null, loading: true, error: null };
  }

  componentDidMount() {
    fetch(`/api/users/${this.props.userId}`)
      .then(res => res.json())
      .then(user => this.setState({ user, loading: false }))
      .catch(err => this.setState({ error: err.message, loading: false }));
  }

  render() {
    if (this.state.loading) return <div>加载中...</div>;
    if (this.state.error) return <div>错误: {this.state.error}</div>;
    return <div>{this.state.user.name}</div>;
  }
}

在 VS Code 中打开目标文件，通过命令面板执行 "ACP: Start Agent Task"，输入以下指令：

请将当前文件中的 UserProfile 类组件重构为 Hooks 函数组件。
要求：
1. 使用 useState 替代 this.state
2. 使用 useEffect 替代生命周期方法
3. 保持功能完全一致
4. 添加 PropTypes 类型定义

Agent 通过 ACP 协议开始工作，你会看到编辑器实时展示重构过程：

import React, { useState, useEffect } from 'react';
import PropTypes from 'prop-types';

function UserProfile({ userId }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    fetch(`/api/users/${userId}`)
      .then(res => res.json())
      .then(user => {
        setUser(user);
        setLoading(false);
      })
      .catch(err => {
        setError(err.message);
        setLoading(false);
      });
  }, [userId]);

  if (loading) return <div>加载中...</div>;
  if (error) return <div>错误: {error}</div>;
  return <div>{user.name}</div>;
}

UserProfile.propTypes = {
  userId: PropTypes.string.isRequired
};

export default UserProfile;

ACP 会以差异对比的方式展示每一处修改，你可以逐段审阅并选择接受或拒绝。整个过程 Agent 自动完成，无需手动复制代码。

通过 ACP 协议，Hermes Agent 与编辑器的深度集成为开发者带来了流畅的 AI 辅助编程体验，实现了从"人工复制粘贴"到"智能代理协作"的范式升级。