终端

执行和管理终端命令

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

检查支持

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

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

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

执行命令

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
  }
}
参数类型必需描述
sessionIdSessionId是此请求的会话 ID
commandstring是要执行的命令
argsstring[]-命令参数数组
envEnvVariable[]-命令的环境变量。每个变量有：name（环境变量名称）和 value（环境变量值）
cwdstring-命令的工作目录。必须是绝对路径。
outputByteLimitnumber-要保留的最大输出字节数。超过后，较早的输出会被截断以保持在此限制内。当超过限制时，客户端从输出的开头截断以保持在此限制内。客户端必须确保截断发生在字符边界处以保持有效的字符串输出，即使这意味着保留的输出略少于指定的限制。

客户端立即返回终端 ID 而不等待完成：

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

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

Agent 必须在不再需要时使用 terminal/release 释放终端。

嵌入工具调用

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

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "tool_call",
      "toolCallId": "call_002",
      "title": "Running tests",
      "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
    }
  }
}
字段类型必需描述
outputstring是到目前为止捕获的终端输出
truncatedboolean是输出是否因字节限制而被截断
exitStatusTerminalExitStatus-仅在命令已退出时存在。包含：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
  }
}
字段类型描述
exitCodenumber进程退出代码（如果被信号终止可能为 null）
signalstring终止进程的信号（如果正常退出可能为 null）

终止命令

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

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

终止命令后，终端仍然有效，可用于：

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

Agent 必须在使用完毕后仍调用 terminal/release。

构建超时

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

  1. 使用 terminal/create 创建终端
  2. 为所需超时时长启动计时器
  3. 同时等待计时器到期或 terminal/wait_for_exit 返回
  4. 如果计时器先到期：
    • 调用 terminal/kill 终止命令
    • 调用 terminal/output 检索任何最终输出
    • 将输出包含在对模型的响应中
  5. 完成后调用 terminal/release

释放终端

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

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

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