外置会话存储

qodercli 默认把会话历史保存在运行它的机器上。如果服务运行在多台机器、容器或 Serverless 环境中，下一次请求可能由另一台机器处理，导致之前的会话无法继续。

外置会话存储让应用把会话历史同步到自己的共享存储中。之后，无论请求落在哪台机器上，都可以通过 session ID 继续原来的会话。

适合使用外置存储的场景包括：

• 服务有多个实例，请求可能在实例之间切换
• 容器或 Serverless 环境的本地磁盘不可靠
• 需要自行管理会话数据的权限、加密、备份或保留周期

如果应用始终运行在同一台机器上，通常不需要配置外置存储。

​

工作方式

first request
  query()
    -> qodercli saves the session locally
    -> the SDK sends new session history to your store

later request
  query(..., resume=session_id)
    -> the SDK reads session history from your store
    -> qodercli continues the session

外置存储是本地会话的额外副本，不会关闭 qodercli 的本地会话记录。应用不需要理解或管理 qodercli 的本地文件格式。

​

快速开始

SDK 提供 InMemorySessionStore，用于在接入真实存储前验证流程。它只把数据保存在当前进程中，进程退出后数据会丢失。

from qoder_agent_sdk import (
    InMemorySessionStore,
    QoderAgentOptions,
    ResultMessage,
    qodercli_auth,
    query,
)

store = InMemorySessionStore()
session_id = None

options = QoderAgentOptions(
    auth=qodercli_auth(),
    cwd="/path/to/project",
    session_store=store,
)
async for message in query(prompt="Inspect this project.", options=options):
    if isinstance(message, ResultMessage):
        session_id = message.session_id

继续会话时，把记录的 session_id 传给 resume，并再次传入同一个 store：

resume_options = QoderAgentOptions(
    auth=qodercli_auth(),
    cwd="/path/to/project",
    session_store=store,
    resume=session_id,
)

不同机器必须使用相同的 cwd，SDK 才能把请求识别为同一个项目。

​

接入自己的存储

SDK 不提供可直接用于生产的外置存储实现。应用需要实现 SessionStore 协议，把数据写入自己选择的共享存储。

最小实现只需要两个异步方法：

方法	应用需要完成的工作
append(key, entries)	按顺序保存 SDK 提供的新增会话数据
load(key)	返回该 key 下的全部会话数据；不存在时返回 None

以下方法按需实现：

方法	实现后支持的能力
list_sessions(project_key)	使用 continue_conversation=True 恢复最近会话，以及列出外置会话
delete(key)	从外置存储删除会话
list_subkeys(key)	完整恢复和查看子代理产生的会话数据

把 key 和 entries 当作 SDK 提供的不透明数据即可。应用负责保存和原样返回，不需要解析其中的消息内容。

​

存储实现检查清单

只有负责开发 SessionStore 的人员需要关注以下约束：

• 同一个 key 的数据必须保持追加顺序，load 返回完整历史。
• 不同 key 的数据必须相互隔离。
• SDK 可能重试失败的 append，生产实现需要考虑重复提交。
• list_sessions 的 mtime 使用 Unix 毫秒时间戳，并且只返回主会话。
• 删除主会话时，delete 还需要删除该会话的子数据。
• list_subkeys 只返回相对标识，不要返回绝对路径或包含 .、.. 的路径。
• 多个进程可能同时写入同一会话时，存储端需要保证写入顺序。

可以使用 qoder_agent_sdk.testing 中的 run_session_store_conformance 检查通用行为，并为实际存储补充并发和重试测试。连接管理、权限、加密、备份、迁移和数据保留由应用负责。

​

在应用中使用

每次需要保存或恢复外置会话时，都要在 QoderAgentOptions.session_store 中传入 store。

• 已知 session ID：使用 resume
• 恢复该项目最近的会话：使用 continue_conversation=True，并实现 list_sessions
• 管理外置会话：使用 list_sessions_from_store、get_session_messages_from_store、rename_session_via_store、tag_session_via_store、fork_session_via_store 或 delete_session_via_store
• 迁移已有本地会话：使用 import_session_to_store

​

限制与运维

• 外置写入失败不会中断当前对话。最终失败时，SDK 会产生 SDKMirrorErrorMessage；对数据完整性有要求的应用应监控该消息。
• 外置读取默认等待 60 秒，可以通过 load_timeout_ms 调整。
• session_store_flush 默认为 "batched"；"eager" 写入更及时，但会增加存储请求。
• 外置存储中找不到显式指定的 session ID 时，SDK 仍会尝试使用本机上的同 ID 会话。
• Python SDK 不能把外置会话存储与文件 checkpoint、自定义 transport 或实验性的 Cloud Agent runtime 同时使用，并且只支持内置 subprocess transport。
• SessionStore 只保存会话历史，不保存鉴权状态、应用配置、文件 checkpoint 或数据保留策略。