会话列表

发现已有的会话

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

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

在列出会话之前，客户端必须先完成初始化阶段。支持 session 方法面的 Agent 必须支持 session/list。

会话列表流程

同时声明 session.additionalDirectories 的 Agent 可以在返回的 SessionInfo 对象中包含 additionalDirectories，以报告已列出会话的额外工作区根。

如果 Agent 声明了 session.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 声明了 `session.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 和 config_option_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"
      }
    }
  }
}

所有字段都是可选的。仅包含已更改的字段；省略的字段保持不变。将可为 null 的字段设置为 null 以清除它。

字段	类型	描述
`title`	`string \| null`	会话的人类可读标题。设置为 `null` 以清除。
`updatedAt`	`string \| null`	最后活动的 ISO 8601 时间戳。设置为 `null` 以清除。
`_meta`	`object \| null`	Agent 特定元数据更新。省略以保持不变；设置为 `null` 以清除。参阅可扩展性。

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

与其他会话方法的交互

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

客户端调用 session/list 发现可用会话
用户从列表中选择一个会话
客户端使用所选的 sessionId 调用 session/resume 恢复对话，可选地设置 replayFrom 以请求历史重放