# SDK 会话管理

> **版本要求**：本文档针对 CodeBuddy Agent SDK v0.1.0 及以上版本。

本文档介绍如何在 SDK 中管理会话，包括获取会话 ID、恢复会话、分叉会话和多轮对话。

## 概述

会话（Session）是 CodeBuddy 的核心概念，用于：

- **保持对话上下文**：多轮对话中 AI 能记住之前的内容
- **支持会话恢复**：可以从上次中断的地方继续
- **支持会话分叉**：从某个点创建分支，探索不同方向

每个会话都有一个唯一的 `session_id`，可以用于后续恢复。

## 获取会话 ID

会话开始时，SDK 会返回一个 `system` 类型的初始化消息,其中包含 `session_id`。

### 使用 query API

::: code-group

```typescript [TypeScript]
import { query } from '@tencent-ai/agent-sdk';

let sessionId: string | undefined;

const q = query({
  prompt: '帮我构建一个 Web 应用',
  options: {
    model: 'deepseek-v3.1'
  }
});

for await (const message of q) {
  // 从初始化消息中获取 session_id
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id;
    console.log(`会话 ID: ${sessionId}`);
    // 保存 sessionId 供后续恢复使用
  }

  console.log(message);
}

// sessionId 可以保存到数据库或文件中
```

```python [Python]
import asyncio
from codebuddy_agent_sdk import query, CodeBuddyAgentOptions, SystemMessage

session_id = None

async def main():
    global session_id

    options = CodeBuddyAgentOptions(model="deepseek-v3.1")

    async for message in query(prompt="帮我构建一个 Web 应用", options=options):
        # 从初始化消息中获取 session_id
        if isinstance(message, SystemMessage):
            session_id = message.data.get("session_id")
            print(f"会话 ID: {session_id}")
            # 保存 session_id 供后续恢复使用

        print(message)

asyncio.run(main())
# session_id 可以保存到数据库或文件中
```

:::

### 使用 v2 Session API (TypeScript)

```typescript
import { unstable_v2_createSession } from '@tencent-ai/agent-sdk';

const session = unstable_v2_createSession({
  model: 'deepseek-v3.1'
});

await session.send('帮我构建一个 Web 应用');

for await (const message of session.stream()) {
  if (message.type === 'system' && message.subtype === 'init') {
    console.log(`会话 ID: ${message.session_id}`);
  }
  console.log(message);
}

// 使用 session.sessionId 获取（初始化后可用）
console.log(`会话 ID: ${session.sessionId}`);

session.close();
```

### 使用 Client API (Python)

```python
from codebuddy_agent_sdk import CodeBuddySDKClient, CodeBuddyAgentOptions

async def main():
    options = CodeBuddyAgentOptions(model="deepseek-v3.1")

    async with CodeBuddySDKClient(options=options) as client:
        await client.query("帮我构建一个 Web 应用")

        async for message in client.receive_response():
            if isinstance(message, SystemMessage):
                print(f"会话 ID: {message.data.get('session_id')}")
            print(message)
```

## 恢复会话

使用之前保存的 `session_id` 可以恢复会话，继续之前的对话。

### 使用 resume 选项

::: code-group

```typescript [TypeScript - query API]
import { query } from '@tencent-ai/agent-sdk';

// 使用之前保存的 session_id
const savedSessionId = 'abc123-xyz789';

const q = query({
  prompt: '继续我们之前的工作',
  options: {
    model: 'deepseek-v3.1',
    resume: savedSessionId  // 恢复指定会话
  }
});

for await (const message of q) {
  console.log(message);
}
```

```typescript [TypeScript - v2 API]
import { unstable_v2_resumeSession } from '@tencent-ai/agent-sdk';

// 使用之前保存的 session_id
const savedSessionId = 'abc123-xyz789';

const session = unstable_v2_resumeSession(savedSessionId, {
  model: 'deepseek-v3.1'
});

await session.send('继续我们之前的工作');

for await (const message of session.stream()) {
  console.log(message);
}

session.close();
```

```python [Python]
from codebuddy_agent_sdk import query, CodeBuddyAgentOptions

# 使用之前保存的 session_id
saved_session_id = "abc123-xyz789"

options = CodeBuddyAgentOptions(
    model="deepseek-v3.1",
    resume=saved_session_id  # 恢复指定会话
)

async for message in query(prompt="继续我们之前的工作", options=options):
    print(message)
```

:::

### 继续最近的会话

使用 `continue` / `continue_conversation` 选项可以自动继续最近的会话：

::: code-group

```typescript [TypeScript]
const q = query({
  prompt: '继续',
  options: {
    model: 'deepseek-v3.1',
    continue: true  // 继续最近的会话
  }
});
```

```python [Python]
options = CodeBuddyAgentOptions(
    model="deepseek-v3.1",
    continue_conversation=True  # 继续最近的会话
)
```

:::

## 多轮对话

多轮对话允许在同一个会话中进行多次交互，保持上下文连贯。

### TypeScript：使用 query API

每次新的 query 调用使用 `resume` 恢复会话：

```typescript
import { query } from '@tencent-ai/agent-sdk';

async function multiTurnWithQuery() {
  let sessionId: string;

  // 第一轮对话
  const q1 = query({
    prompt: '帮我创建一个 React 项目',
    options: { model: 'deepseek-v3.1' }
  });

  for await (const msg of q1) {
    if (msg.type === 'system' && msg.subtype === 'init') {
      sessionId = msg.session_id;
    }
    if (msg.type === 'result') {
      console.log('第一轮完成');
    }
  }

  // 第二轮对话（恢复会话）
  const q2 = query({
    prompt: '添加一个用户登录页面',
    options: {
      model: 'deepseek-v3.1',
      resume: sessionId
    }
  });

  for await (const msg of q2) {
    if (msg.type === 'result') {
      console.log('第二轮完成');
    }
  }

  // 第三轮对话
  const q3 = query({
    prompt: '添加表单验证',
    options: {
      model: 'deepseek-v3.1',
      resume: sessionId
    }
  });

  for await (const msg of q3) {
    console.log(msg);
  }
}
```

### TypeScript：使用 v2 Session API

v2 API 提供更简洁的多轮对话体验：

```typescript
import { unstable_v2_createSession } from '@tencent-ai/agent-sdk';

async function multiTurnWithSession() {
  const session = unstable_v2_createSession({
    model: 'deepseek-v3.1'
  });

  try {
    // 第一轮对话
    await session.send('帮我创建一个 React 项目');
    for await (const msg of session.stream()) {
      console.log(msg);
    }

    // 第二轮对话（自动保持上下文）
    await session.send('添加一个用户登录页面');
    for await (const msg of session.stream()) {
      console.log(msg);
    }

    // 第三轮对话
    await session.send('添加表单验证');
    for await (const msg of session.stream()) {
      console.log(msg);
    }

  } finally {
    session.close();
  }
}
```

### Python：使用 CodeBuddySDKClient

```python
from codebuddy_agent_sdk import CodeBuddySDKClient, CodeBuddyAgentOptions

async def multi_turn_conversation():
    options = CodeBuddyAgentOptions(model="deepseek-v3.1")

    async with CodeBuddySDKClient(options=options) as client:
        # 第一轮对话
        await client.query("帮我创建一个 React 项目")
        async for msg in client.receive_response():
            print(msg)

        # 第二轮对话（自动保持上下文）
        await client.query("添加一个用户登录页面")
        async for msg in client.receive_response():
            print(msg)

        # 第三轮对话
        await client.query("添加表单验证")
        async for msg in client.receive_response():
            print(msg)
```

## 相关文档

- [SDK 概览](sdk.md) - 快速入门和使用示例
- [SDK 权限控制](sdk-permissions.md) - 权限模式和 canUseTool
- [TypeScript SDK 参考](sdk-typescript.md) - 完整 API 参考
- [Python SDK 参考](sdk-python.md) - 完整 API 参考
