可扩展性

添加自定义数据和能力

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"
  }
}

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

宣告自定义能力

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

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "loadSession": true,
      "_meta": {
        "zed.dev": {
          "workspace": true,
          "fileNotifications": true
        }
      }
    }
  }
}

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