会话控制

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',
}

​

字段速查

字段	类型	行为
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);
  }
}

​

生成会话标题

当宿主应用需要给已有会话生成一个短标题时，可以调用 q.generateSessionTitle()：

const title = await q.generateSessionTitle(
  'User asked the agent to review authentication middleware and fix failing tests.',
);

CLI 会通过 control response 返回生成结果。当前 headless control 路径不会持久化该标题；持久化的 ai-title transcript entry 仍可通过 session list 相关 API 读取。

​

读取 subagent transcript

Subagent 会在父会话下写入自己的 transcript。父会话完成后，先用 listSubagents() 获取 subagent ID，再用 getSubagentMessages() 读取某个 subagent 的消息链：

import { getSubagentMessages, listSubagents } from '@qoder-ai/qoder-agent-sdk';

const agentIds = await listSubagents(sessionId, { dir: '/path/to/project' });

for (const agentId of agentIds) {
  const messages = await getSubagentMessages(sessionId, agentId, {
    dir: '/path/to/project',
  });

  console.log(agentId, messages.length);
}

getSubagentMessages() 会沿 subagent transcript 的 parent 链回溯，并按时间顺序返回 user / assistant 消息。