会话控制 - Qoder CN

SDK 默认每次调用（TypeScript 的 query()）或连接（Python 的 QoderSDKClient）启动一个全新的会话。通过 options 里几个字段，可以指定会话 ID、恢复历史会话、或从已有会话分叉。

概念

一个 session 对应 CLI 端持久化的一条对话历史（含上下文、工具调用记录、压缩边界等），由 UUID 标识。系统消息 init 里包含本次的 session_id，也是后续 resume / fork 的锚点。下面示例中的认证方式也可以替换成你项目里使用的其他认证方式，参见 SDK 认证。

新建会话

默认

不传任何会话相关字段，每次新建：

import { accessTokenFromEnv, query } from '@qodercn-ai/qodercn-agent-sdk';

const q = query({
  prompt: 'Hello',
  options: { auth: accessTokenFromEnv() },
});

指定 session ID

让调用方决定 session 的 UUID（适合宿主自己管理 session 索引）：

import { randomUUID } from 'node:crypto';

const sessionId = randomUUID();
const q = query({
  prompt: 'Hello',
  options: {
    auth: accessTokenFromEnv(),
    sessionId,
  },
});

恢复会话

按 ID 恢复

const q = query({
  prompt: 'Continue the previous conversation',
  options: {
    auth: accessTokenFromEnv(),
    resume: 'previous-session-id',
  },
});

恢复最近一次

不知道 session ID 时，用 continue: true（TypeScript）/ continue_conversation=True（Python）接上最近修改过的会话：

const q = query({
  prompt: 'Continue',
  options: {
    auth: accessTokenFromEnv(),
    continue: true,
  },
});

resume 和 continue（Python 中为 continue_conversation）不要同时传。

分叉会话

从已有会话派生一条新会话，保留原上下文但获得新的 session ID。原会话不受影响：

const q = query({
  prompt: 'Based on the prior context, explore a different direction',
  options: {
    auth: accessTokenFromEnv(),
    resume: 'source-session-id',
    forkSession: true,
  },
});

要给分叉后的新会话指定 ID：

options: {
  auth: accessTokenFromEnv(),
  resume: 'source-session-id',
  forkSession: true,
  sessionId: 'my-new-session-id',
}

字段速查

字段（TypeScript / Python）	类型	行为
`sessionId` / `session_id`	`string` / `str`	单独使用：用此 ID 新建；与 fork 字段同用：分叉后新会话的 ID
`resume` / `resume`	`string` / `str`	要恢复的 session ID
`continue` / `continue_conversation`	`boolean` / `bool`	`true` 表示恢复最近一次会话
`forkSession` / `fork_session`	`boolean` / `bool`	配合 `resume` 使用，分叉而非接续

拿到当前 session ID

监听 init 系统消息；Python 中 ResultMessage 也带 session_id，两者都可以用来记账：

for await (const msg of q) {
  if (msg.type === 'system' && msg.subtype === 'init') {
    console.log('session_id:', msg.session_id);
  }
}

用户数据目录

用户数据目录用于存放会话历史、资源和日志等 CLI 用户级数据。通过 options.env 设置 QODERCN_CONFIG_DIR，可以指定该目录：

import { accessTokenFromEnv, query } from '@qodercn-ai/qodercn-agent-sdk';

const q = query({
  prompt: 'Analyze this repository',
  options: {
    auth: accessTokenFromEnv(),
    env: {
      ...process.env,
      QODERCN_CONFIG_DIR: '/var/lib/my-agent/qoder',
    },
  },
});

​概念

​新建会话

​默认

​指定 session ID

​恢复会话

​按 ID 恢复

​恢复最近一次

​分叉会话

​字段速查

​拿到当前 session ID

​用户数据目录

概念