外置会话存储

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

外置会话存储会在你的应用所控制的存储中保留每个会话的一份镜像。镜像是一份额外的副本：qodercli 仍然把会话写在本地，任何机器之后都可以通过 session ID 继续同一个会话。

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

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

如果应用始终运行在同一台机器上，通常本地会话存储就够了。

​

工作方式

首次请求
  query()
    -> qodercli 把会话写到本地
    -> SDK 把新增的会话 entry 镜像到你的存储

后续请求，可能在另一台机器上
  query({ resume: sessionId })
    -> SDK 从你的存储读取会话历史
    -> qodercli 继续该会话

这种设计带来两个特性：

• 写入是尽力而为的。 SDK 在后台镜像 entry。写入失败会被上报，但绝不会中断正在进行的对话；参见下文的运维。
• entry 对存储不透明。 你的存储原样保存并返回 SDK 定义的 transcript entry。应用不需要理解 qodercli 的本地文件格式。

​

快速开始

InMemorySessionStore 只把数据保存在当前进程中。在接入共享后端之前，用它来验证接线是否正确——即 query 确实会写入 store 并能从中恢复。它无法演示跨机器恢复，因为进程退出后数据就没了；跨机器场景需要实现真正的存储，见实现存储。

import {
  InMemorySessionStore,
  qodercliAuth,
  query,
} from '@qoder-ai/qoder-agent-sdk';

const store = new InMemorySessionStore();
const options = {
  auth: qodercliAuth(),
  cwd: '/path/to/project',
  sessionStore: store,
};

// 首次 query：运行并记录 session ID。
let sessionId: string | undefined;
for await (const message of query({
  prompt: '记住数字 42。',
  options,
})) {
  if (message.type === 'result') sessionId = message.session_id;
}
if (!sessionId) throw new Error('首次 query 未返回 session ID。');

// 后续 query：从 store 恢复，模型能回忆起之前的上下文。
for await (const message of query({
  prompt: '我让你记住的数字是多少？',
  options: { ...options, resume: sessionId },
})) {
  if (message.type === 'result') console.log(message.result); // -> "42"
}

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

​

在应用中使用

每次需要镜像或恢复会话的 query，都在 options.sessionStore 中传入 store，然后选择如何指定会话：

• 已知 session ID —— 传入 resume: sessionId。
• 该项目最近的会话 —— 传入 continue: true。这要求 store 实现 listSessions。

​

管理外置会话

会话管理函数接受同一个 sessionStore 选项，并在 store 而不是本地文件上操作：

import {
  listSessions,
  getSessionInfo,
  getSessionMessages,
  listSubagents,
  getSubagentMessages,
  renameSession,
  tagSession,
  forkSession,
  deleteSession,
} from '@qoder-ai/qoder-agent-sdk';

const project = { dir: '/path/to/project', sessionStore: store };
const sessions = await listSessions(project);
const messages = await getSessionMessages(sessionId, project);
await renameSession(sessionId, 'Investigation #1', project);
await deleteSession(sessionId, project);

listSessions 要求 store 实现 listSessions；listSubagents 要求 listSubkeys；deleteSession 要求 delete。如果实现了 listSubkeys，getSubagentMessages 也会使用它。

要把已有的本地会话复制进 store——例如迁移一台此前未启用外置存储的机器——使用 importSessionToStore：

import { importSessionToStore } from '@qoder-ai/qoder-agent-sdk';

await importSessionToStore(sessionId, store, { dir: '/path/to/project' });

​

实现存储

SDK 不提供可直接用于生产的存储实现；应用需要针对自己选择的共享存储实现 SessionStore 接口。Redis 和 PostgreSQL 的可运行参考实现展示了具体用法，见 TypeScript 示例或 Python 示例。它们是起点，而非可直接用于生产的实现。

type SessionKey = {
  projectKey: string; // 由 cwd 推导，用于标识项目
  sessionId: string; // 会话 UUID
  subpath?: string; // 子代理 transcript 才有，例如 "subagents/agent-<id>"
};

type SessionStoreEntry = {
  type: string;
  uuid?: string;
  timestamp?: string;
  [key: string]: unknown; // 不透明的 transcript 行——原样保存并返回
};

interface SessionStore {
  // 必需
  append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void>;
  load(key: SessionKey): Promise<SessionStoreEntry[] | null>;
  // 可选——只实现你需要的能力
  listSessions?(
    projectKey: string,
  ): Promise<Array<{ sessionId: string; mtime: number }>>;
  delete?(key: SessionKey): Promise<void>;
  listSubkeys?(key: Omit<SessionKey, 'subpath'>): Promise<string[]>;
}

一个 SessionKey 标识一份 transcript。主会话没有 subpath；每份子代理 transcript 复用相同的 projectKey 和 sessionId，但带有不同的 subpath。把 key 和 entry 当作不透明数据——原样保存并返回，不要解析其中的消息内容。

两个必需方法提供保存与恢复。每个可选方法解锁一项能力：

方法	解锁的能力
append、load	镜像会话并按 ID 恢复 —— 必需
listSessions	用 continue: true 恢复最近会话；列出已存会话
delete	从 store 删除会话
listSubkeys	完整恢复并查看子代理 transcript

​

实现检查清单

• 同一个 key 保持追加顺序，load 返回完整历史。回放依赖顺序。
• 隔离各 key。 绝不要把一个 key 的 entry 返回到另一个 key 下。
• 让 append 幂等。 SDK 可能用相同的 entry 重试失败的写入，因此重试不能重复写入历史。
• listSessions().mtime 返回 Unix 毫秒时间戳，并且只返回主会话，即不带 subpath 的会话。
• 级联删除。 删除主会话时，必须同时删除它的子代理 transcript。
• listSubkeys 只返回相对标识——不要返回绝对路径，也不要返回包含 . 或 .. 的路径。这些会成为存储键，路径穿越片段会让 transcript 逃出它所在的命名空间。
• 串行化并发写入。 如果同一会话可能被多个进程写入，在存储层串行化这些写入。

用 SDK 仓库中的 SessionStore conformance 测试检查这些通用行为，并为具体后端补充并发和重试测试。连接管理、权限、加密、备份、迁移和数据保留仍由应用负责。

​

运维

失败处理。 外置写入失败不会中断当前对话。最后一次重试失败后，SDK 会发出 system/mirror_error 消息。对镜像完整性有要求时应监控它——即使某次写入没成功，对话仍可能成功完成。

调优。

• 外置读取默认最多等待 60 秒。用 loadTimeoutMs 调整。
• sessionStoreFlush 默认为 'batched'。设为 'eager' 会更早镜像 entry，代价是更多的存储请求。

约束。

• 显式指定的会话在 store 中不存在时，SDK 仍可回退到本机上的同 ID 会话。
• sessionStore 不能与 persistSession: false、文件 checkpoint、自定义 transport provider 或实验性的 Cloud Agent runtime 同时使用。
• store 在内置的 Process 和 Worker transport 上受支持。
• store 只保存会话历史，不保存鉴权状态、应用配置、文件 checkpoint 或数据保留策略。