可扩展性

添加自定义数据和能力

Agent Client Protocol 提供了内置的扩展机制，允许实现添加自定义功能同时保持与核心协议的兼容性。这些机制确保 Agent 和客户端可以在不破坏互操作性的情况下进行创新。

_meta 字段

协议中的所有类型都包含一个 _meta 字段，类型为 { [key: string]: unknown }，实现可以使用它来附加自定义信息。这包括请求、响应、通知，甚至嵌套类型如内容块、工具调用、计划条目和能力对象。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/prompt",
  "params": {
    "sessionId": "sess_abc123def456",
    "prompt": [
      {
        "type": "text",
        "text": "Hello, world!"
      }
    ],
    "_meta": {
      "traceparent": "00-80e1afed08e019fc1110464cfa66635c-7a085853722dc6d2-01",
      "zed.dev/debugMode": true
    }
  }
}

客户端可以将字段传播给 Agent 用于关联目的，如 requestId。_meta 中的以下根级键 应该 保留给 W3C trace context，以保证与现有 MCP 实现和 OpenTelemetry 工具的互操作：

  • traceparent
  • tracestate
  • baggage

实现 不得 在规范定义的类型的根级别添加任何自定义字段。所有可能的名称都保留给未来的协议版本。

扩展方法

协议保留任何以下划线（_）开头的方法名用于自定义扩展。这允许实现添加新功能而不会与未来协议版本冲突的风险。

扩展方法遵循标准 JSON-RPC 2.0 语义：

  • 请求 - 包含 id 字段并期望收到响应
  • 通知 - 省略 id 字段且为单向

自定义请求

除了协议指定的请求外，实现 可以 暴露和调用自定义 JSON-RPC 请求，只要其名称以下划线（_）开头。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "_zed.dev/workspace/buffers",
  "params": {
    "language": "rust"
  }
}

收到自定义请求后，实现 必须 以提供的 id 相应响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "buffers": [
      { "id": 0, "path": "/home/user/project/src/main.rs" },
      { "id": 1, "path": "/home/user/project/src/editor.rs" }
    ]
  }
}

如果接收端不识别自定义方法名，它应返回标准的”Method not found”错误：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

为避免此类情况，扩展 应该 声明其自定义能力，以便调用方可以先检查其可用性，并相应地调整其行为或界面。

自定义通知

自定义通知是以下划线（_）开头的常规 JSON-RPC 通知。与所有通知一样，它们省略 id 字段：

{
  "jsonrpc": "2.0",
  "method": "_zed.dev/file_opened",
  "params": {
    "path": "/home/user/project/src/editor.rs"
  }
}

与自定义请求不同，实现 应该 忽略未识别的通知。

枚举和标签联合变体

ACP 还在定义了自定义或未来回退的类枚举字段和标签联合中保留以 _ 为前缀的值用于实现特定扩展。

  • 以 _ 开头的值保留给实现特定扩展。
  • 不以 _ 开头的未知值保留给未来的 ACP 变体。
  • 扩展 不得 定义自定义非下划线值。
  • 实现 不得 将未知的非下划线值视为自定义扩展。

此规则仅在 schema 定义回退路径时适用。当接收方无法在不理解变体的情况下安全继续时，封闭判别器仍然可以拒绝未知值。

在存储、重放、代理或转发数据时，实现 应该 保留未知值和任何原始标签联合负载。在显示未知值时，实现 应该 回退到与字段用途匹配的通用 UI 行为。

声明自定义能力

实现 应该 使用能力对象中的 _meta 字段来声明对扩展及其方法的支持：

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 2,
    "capabilities": {
      "session": {
        "load": {}
      },
      "_meta": {
        "zed.dev": {
          "workspace": true,
          "fileNotifications": true
        }
      }
    }
  }
}

这允许实现在初始化期间协商自定义功能，而不会破坏与标准客户端和 Agent 的兼容性。