跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
概念

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

​
字段速查

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

​
拿到当前 session ID

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