> ## 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、恢复历史会话、或从已有会话分叉。

<div id="概念" />

## 概念

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

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

<div id="新建会话" />

## 新建会话

<div id="默认" />

### 默认

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

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

<div id="指定-session-id" />

### 指定 session ID

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

```typescript theme={null}
import { randomUUID } from 'node:crypto';

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

<div id="恢复会话" />

## 恢复会话

<div id="按-id-恢复" />

### 按 ID 恢复

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

<div id="恢复最近一次" />

### 恢复最近一次

不知道 session ID 时，用 `continue: true` 接上最近修改过的会话：

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

`resume` 和 `continue` 不要同时传。

<div id="分叉会话" />

## 分叉会话

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

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

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

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

<div id="字段速查" />

## 字段速查

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

<div id="拿到当前-session-id" />

## 拿到当前 session ID

监听 `init` 消息：

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