会话控制

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

​

概念

一个 session 对应 CLI 端持久化的一条对话历史（含上下文、工具调用记录、压缩边界等），由 UUID 标识。系统消息 init 里包含本次的 session_id，也是后续 resume / fork 的锚点。

下面示例中的 auth: accessTokenFromEnv() 也可以替换成你项目里使用的其他认证方式，参见 SDK 认证。

​

新建会话

​

默认

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

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

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

​

指定 session ID

让调用方决定 session 的 UUID（适合 host 自己管理 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 接上最近修改过的会话：

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

resume 和 continue 不要同时传。

​

分叉会话

从已有会话派生一条新会话，保留原上下文但获得新的 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',
}

​

字段速查

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

​

拿到当前 session ID

监听 init 消息：

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

​

用户数据目录

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

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

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