@tencent-ai/agent-sdk 0.3.99 → 0.3.100

package/cli/dist/web-ui/docs/cn/cli/sdk-sessions.md

@@ -0,0 +1,332 @@
+# 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 参考