会话列表

发现已有的会话

session/list 方法允许客户端发现 Agent 已知的会话。客户端可以使用此功能显示会话历史并在会话之间切换。

Agent 还可以通过 session_info_update 通知实时向客户端推送会话元数据更新，无需轮询即可保持会话标题和元数据同步。

在列出会话之前，客户端必须先完成初始化阶段以验证 Agent 支持此能力。

检查支持

在尝试列出会话之前，客户端必须通过检查 initialize 响应中的 sessionCapabilities.list 字段来验证 Agent 是否支持此能力：

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "sessionCapabilities": {
        "list": {}
      }
    }
  }
}

如果 sessionCapabilities.list 不存在，则 Agent 不支持列出会话，客户端不得尝试调用 session/list。

同时宣告 sessionCapabilities.additionalDirectories 的 Agent 可以在返回的 SessionInfo 对象中包含 additionalDirectories 以报告列出会话的额外工作区根目录。

如果 Agent 宣告了 sessionCapabilities.delete 能力，客户端可以使用 session/delete 从未来的 session/list 结果中移除会话。

列出会话

客户端通过调用 session/list 方法发现已有会话，可带可选的过滤和分页参数：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/list",
  "params": {
    "cwd": "/home/user/project",
    "cursor": "eyJwYWdlIjogMn0="
  }
}

所有参数都是可选的。带有空 params 对象的请求返回第一页会话。

参数	类型	必需	描述
`cwd`	`string`	-	按工作目录过滤会话。必须是绝对路径。仅返回 `cwd` 匹配的会话。
`cursor`	`string`	-	来自前一次响应 `nextCursor` 字段的不透明游标令牌，用于基于游标的分页。参见分页。

Agent 必须回复会话列表和可选的分页元数据：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "sessions": [
      {
        "sessionId": "sess_abc123def456",
        "cwd": "/home/user/project",
        "title": "Implement session list API",
        "updatedAt": "2025-10-29T14:22:15Z",
        "_meta": {
          "messageCount": 12,
          "hasErrors": false
        }
      },
      {
        "sessionId": "sess_xyz789ghi012",
        "cwd": "/home/user/another-project",
        "title": "Debug authentication flow",
        "updatedAt": "2025-10-28T16:45:30Z"
      },
      {
        "sessionId": "sess_uvw345rst678",
        "cwd": "/home/user/project",
        "updatedAt": "2025-10-27T15:30:00Z"
      }
    ],
    "nextCursor": "eyJwYWdlIjogM30="
  }
}

字段	类型	必需	描述
`sessions`	`SessionInfo[]`	是	会话信息对象数组。
`nextCursor`	`string`	-	不透明游标令牌。如果存在，在下一次请求的 `cursor` 参数中传入此值以获取下一页。如果不存在，则没有更多结果。

SessionInfo

字段	类型	必需	描述
`sessionId`	`string`	是	会话的唯一标识符。
`cwd`	`string`	是	会话的工作目录。始终为绝对路径。
`additionalDirectories`	`string[]`	-	如果 Agent 宣告了 `sessionCapabilities.additionalDirectories`，它可以包含此字段以报告与列出的会话关联的完整有序额外根目录列表。省略和空值是等效的：此 `SessionInfo` 响应报告没有额外根目录。客户端不得将此字段与先前的值合并或从 Agent 特定状态推断额外根目录。
`title`	`string`	-	会话的人类可读标题。可以从第一个提示自动生成。
`updatedAt`	`string`	-	会话中最后活动的 ISO 8601 时间戳。
`_meta`	`object`	-	Agent 特定元数据。参见可扩展性。

当没有会话匹配条件时，Agent 必须返回空的 sessions 数组。

分页

session/list 使用基于游标的分页。请求包含可选的 cursor，当有更多结果可用时响应包含 nextCursor。

客户端必须将缺失的 nextCursor 视为结果结束
客户端必须将游标视为不透明令牌 - 不要解析、修改或持久化它们
Agent 应当在游标无效时返回错误
Agent 应当在内部强制实施合理的页面大小

更新会话元数据

Agent 可以通过 session/update 发送 session_info_update 通知来实时更新会话元数据。这遵循与其他会话通知（如 available_commands_update 和 current_mode_update）相同的模式。

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "session_info_update",
      "title": "Implement user authentication",
      "_meta": {
        "tags": ["feature", "auth"],
        "priority": "high"
      }
    }
  }
}

所有字段都是可选的。仅包含已更改的字段 - 省略的字段保持不变。

字段	类型	必需	描述
`title`	`string \| null`	-	会话的人类可读标题。设为 `null` 以清除。
`updatedAt`	`string \| null`	-	最后活动的 ISO 8601 时间戳。设为 `null` 以清除。
`_meta`	`object`	-	Agent 特定元数据。参见可扩展性。

sessionId、cwd 和 additionalDirectories 字段不包含在更新中。sessionId 已在通知的 params 中，cwd 在会话设置后不可变，ACP 目前未定义 additionalDirectories 的会话中期变更。Agent 通常在第一次有意义的交流后发送此通知以自动生成标题。

与其他会话方法的交互

session/list 仅是发现机制 - 它不会恢复或修改会话：

客户端调用 session/list 发现有可用会话
用户从列表中选择一个会话
客户端使用所选的 sessionId 调用 session/load 以恢复对话