终端 - Agent Client Protocol

终端方法允许代理在客户端环境中执行 shell 命令。这些方法使代理能够运行构建过程、执行脚本并与命令行工具交互，同时提供实时输出流和进程控制。

检查支持

在尝试使用终端方法之前，代理必须通过在 initialize 响应中检查客户端功能字段来验证客户端是否支持此功能：

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "clientCapabilities": {
      "terminal": true
    }
  }
}

如果 terminal 为 false 或不存在，则代理不得尝试调用任何终端方法。

执行命令

terminal/create 方法在新终端中启动命令：

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "terminal/create",
  "params": {
    "sessionId": "sess_abc123def456",
    "command": "npm",
    "args": ["test", "--coverage"],
    "env": [
      {
        "name": "NODE_ENV",
        "value": "test"
      }
    ],
    "cwd": "/home/user/project",
    "outputByteLimit": 1048576
  }
}

sessionId

SessionId

required

此请求的会话 ID

command

string

required

要执行的命令

args

string[]

命令参数数组

env

EnvVariable[]

命令的环境变量。每个变量包含：

name：环境变量名称
value：环境变量值

cwd

string

命令的工作目录（绝对路径）

outputByteLimit

number

要保留的最大输出字节数。一旦超过，早期的输出将被截断以保持在此限制内。当超过限制时，客户端从输出开头截断以保持在此限制内。客户端必须确保在字符边界处截断，以保持有效的字符串输出，即使这意味着保留的输出略小于指定限制。

客户端立即返回终端 ID，无需等待完成：

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "terminalId": "term_xyz789"
  }
}

这允许命令在后台运行，同时代理执行其他操作。创建终端后，代理可以使用 terminal/wait_for_exit 方法等待命令完成。

当不再需要时，代理必须使用 terminal/release 释放终端。

嵌入工具调用

终端可以直接嵌入工具调用中，以向用户提供实时输出：

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "tool_call",
      "toolCallId": "call_002",
      "title": "运行测试",
      "kind": "execute",
      "status": "in_progress",
      "content": [
        {
          "type": "terminal",
          "terminalId": "term_xyz789"
        }
      ]
    }
  }
}

当终端嵌入工具调用时，客户端在生成时显示实时输出，并在释放终端后继续显示。

获取输出

terminal/output 方法检索当前终端输出，无需等待命令完成：

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "terminal/output",
  "params": {
    "sessionId": "sess_abc123def456",
    "terminalId": "term_xyz789"
  }
}

客户端响应当前输出和退出状态（如果命令已完成）：

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "output": "Running tests...\n✓ All tests passed (42 total)\n",
    "truncated": false,
    "exitStatus": {
      "exitCode": 0,
      "signal": null
    }
  }
}

output

string

required

到目前为止捕获的终端输出

truncated

boolean

required

输出是否因字节限制而被截断

exitStatus

TerminalExitStatus

仅在命令已退出时存在。包含：

exitCode：进程退出代码（可能为 null）
signal：终止进程的信号（可能为 null）

等待退出

terminal/wait_for_exit 方法在命令完成时返回：

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "terminal/wait_for_exit",
  "params": {
    "sessionId": "sess_abc123def456",
    "terminalId": "term_xyz789"
  }
}

客户端在命令退出时响应：

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "exitCode": 0,
    "signal": null
  }
}

exitCode

number

进程退出代码（如果被信号终止则可能为 null）

signal

string

终止进程的信号（如果正常退出则可能为 null）

终止命令

terminal/kill 方法终止命令而不释放终端：

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "terminal/kill",
  "params": {
    "sessionId": "sess_abc123def456",
    "terminalId": "term_xyz789"
  }
}

终止命令后，终端保持有效，可与以下方法一起使用：

terminal/output 获取最终输出
terminal/wait_for_exit 获取退出状态

代理在使用完毕后必须仍然调用 terminal/release。

构建超时

代理可以通过组合终端方法实现命令超时：

使用 terminal/create 创建终端
为所需的超时持续时间启动计时器
并发等待计时器到期或 terminal/wait_for_exit 返回
如果计时器先到期：
- 调用 terminal/kill 终止命令
- 调用 terminal/output 检索任何最终输出
- 将输出包含在对模型的响应中
完成后调用 terminal/release

释放终端

terminal/release 终止仍在运行的命令并释放所有资源：

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "terminal/release",
  "params": {
    "sessionId": "sess_abc123def456",
    "terminalId": "term_xyz789"
  }
}

释放后，终端 ID 对所有其他 terminal/* 方法变为无效。如果终端已添加到工具调用，客户端应该在释放后继续显示其输出。

​检查支持

​执行命令

​嵌入工具调用

​获取输出

​等待退出

​终止命令

​构建超时

​释放终端

检查支持

执行命令

嵌入工具调用

获取输出

等待退出

终止命令

构建超时

释放终端