外置会话存储

qoderclicn 默认把会话历史保存在运行它的机器上。如果服务运行在多台机器、容器或 Serverless 环境中，下一次请求可能由另一台机器处理，导致之前的会话无法继续。外置会话存储会在你的应用所控制的存储中保留每个会话的一份镜像。镜像是一份额外的副本：qoderclicn 仍然把会话写在本地，任何机器之后都可以通过 session ID 继续同一个会话。适合使用外置存储的场景包括：

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

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

工作方式

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

后续请求，可能在另一台机器上
  query（携带 resume=session_id）
    -> SDK 从你的存储读取会话历史
    -> qoderclicn 继续该会话

这种设计带来两个特性：

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

快速开始

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

import {
  InMemorySessionStore,
  qodercliAuth,
  query,
} from '@qodercn-ai/qodercn-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 里传入 store（TypeScript 为 sessionStore，Python 为 session_store），然后选择如何指定会话：

已知 session ID —— 传入 resume。
该项目最近的会话 —— 传入 continue: true（TypeScript）/ continue_conversation=True（Python）。这要求 store 实现列出会话的方法。

管理外置会话

会话管理函数在 store 而不是本地文件上操作。TypeScript 中通过 sessionStore 选项传入 store；Python 中每个函数都以 store 作为第一个参数：

import {
  listSessions,
  getSessionInfo,
  getSessionMessages,
  listSubagents,
  getSubagentMessages,
  renameSession,
  tagSession,
  forkSession,
  deleteSession,
} from '@qodercn-ai/qodercn-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);

列出会话的函数要求 store 实现列出会话的方法；列出子代理的函数要求 listSubkeys / list_subkeys；删除会话的函数要求 delete。如果实现了 listSubkeys / list_subkeys，获取子代理消息的函数也会使用它。要把已有的本地会话复制进 store——例如迁移一台此前未启用外置存储的机器——使用导入函数，注意 session ID 在前、store 在后：

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

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

实现存储

SDK 不提供可直接用于生产的存储实现；应用需要针对自己选择的共享存储实现 SessionStore 接口（TypeScript）/ 协议（Python）。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 复用相同的 project key 和 session ID，但带有不同的 subpath。把 key 和 entry 当作不透明数据——原样保存并返回，不要解析其中的消息内容。两个必需方法提供保存与恢复。每个可选方法解锁一项能力：

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

实现检查清单

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

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

运维

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

外置读取默认最多等待 60 秒。用 loadTimeoutMs / load_timeout_ms 调整。
flush 策略（sessionStoreFlush / session_store_flush）默认为 batched。设为 eager 会更早镜像 entry，代价是更多的存储请求。

约束。

显式指定的会话在 store 中不存在时，SDK 仍可回退到本机上的同 ID 会话。
store 不能与文件 checkpoint 或自定义 transport 同时使用（TypeScript 中也不能与 persistSession: false 同时使用）。TypeScript 中 store 在内置的 Process 和 Worker transport 上受支持；Python 中需要内置的 subprocess transport。
store 只保存会话历史，不保存鉴权状态、应用配置、文件 checkpoint 或数据保留策略。

​工作方式

​快速开始

​在应用中使用

​管理外置会话

​实现存储

​实现检查清单