Skip to main content
对话与会话

会话控制

SDK 默认每次调用（TypeScript 的 query()）或连接（Python 的 QoderSDKClient，Java 的 client.query() / client.openSession()）启动一个全新的会话。通过 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（TypeScript、Python）

让调用方决定 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',
  },
});
Java 的 resume(...) 只接受由 ASCII 字母、数字、_ 和 - 组成的 ID，含其他字符时 build() 抛出 InvalidOptionsException。

恢复最近一次

不知道 session ID 时，用 continue: true（TypeScript）/ continue_conversation=True（Python）/ continueSession(true)（Java）接上最近修改过的会话： 
const q = query({
  prompt: 'Continue',
  options: {
    auth: accessTokenFromEnv(),
    continue: true,
  },
});
resume 和 continue（Python 中为 continue_conversation）不要同时传。Java 同时设置 resume(...) 和 continueSession(true) 时，build() 抛出 InvalidOptionsException。

分叉会话

从已有会话派生一条新会话，保留原上下文但获得新的 session ID。原会话不受影响： 
const q = query({
  prompt: 'Based on the prior context, explore a different direction',
  options: {
    auth: accessTokenFromEnv(),
    resume: 'source-session-id',
    forkSession: true,
  },
});
Java 的 forkSession(true) 必须配合 resume(...) 或 continueSession(true)，否则 build() 抛出 InvalidOptionsException。 要给分叉后的新会话指定 ID（TypeScript、Python）： 
options: {
  auth: accessTokenFromEnv(),
  resume: 'source-session-id',
  forkSession: true,
  sessionId: 'my-new-session-id',
}

字段速查

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

用 SessionRepository 打开会话（Java）

上面的 Java 选项同样适用于 client.openSession(options)。也可以通过 client.sessions() 返回的 SessionRepository 直接打开多轮会话：
Java
SessionRepository sessions = client.sessions();

QoderSession resumed = sessions.continueSession("previous-session-id", options)
        .toCompletableFuture().join();
QoderSession forked = sessions.fork("source-session-id", options)
        .toCompletableFuture().join();
continueSession(null, options) 继续最近的会话；fork 的会话 ID 不能为 null。每次调用都启动新的 CLI 进程，返回的会话由调用方关闭。仓库的 list()、get()、delete() 需要外部会话存储，见外置会话存储。

拿到当前 session ID

监听 init 系统消息；Python 中 ResultMessage 也带 session_id，两者都可以用来记账。Java 从 initialization() 结果的 sessionId() 读取，消息的 sessionId() 也带会话 ID： 
for await (const msg of q) {
  if (msg.type === 'system' && msg.subtype === 'init') {
    console.log('session_id:', msg.session_id);
  }
}

用户数据目录

用户数据目录用于存放会话历史、资源和日志等 CLI 用户级数据。通过 options.env（Java 为 putEnvironment(...)）设置 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',
    },
  },
});
Java 的 CLI 子进程默认只继承 PATH（Windows 另含 TEMP 等系统目录变量），不需要像 TypeScript 那样展开 process.env；CLI 需要的其他变量也要显式传入，见子进程环境。