Copilot SDK 支持会话持久化，可在应用重启后恢复对话历史、工具调用结果和 Artifacts。API Key 出于安全从不持久化，BYOK 会话恢复时需重新提供。容器环境必须将持久化目录挂载到持久化存储。

GitHub Copilot SDK 会话持久化：跨重启保存和恢复 Agent 状态

持久化存储的内容

Copilot SDK 会话持久化保存以下数据：

数据类型	说明
完整消息历史	所有对话消息（Full message thread）
工具调用结果缓存	已执行工具的结果（Cached for context）
规划数据	plan.md 文件
Artifacts	files/ 目录下的生成文件

永不持久化：API Key（出于安全考虑，BYOK 会话的 API Key 不会写入磁盘）

启用会话持久化

创建可持久化的会话，需要指定 Session ID：

import { createSession } from '@github/copilot-sdk'

const session = await createSession({
  sessionId: 'user-123-bug-fix-task-456',  // 自定义 Session ID
  persist: true,                             // 开启持久化
  persistDirectory: '/data/sessions'         // 可选，指定存储目录
})

Session ID 命名建议：编码所有权和用途，便于审计和清理：

• user-{userId}-{taskType}-{timestamp}
• org-{orgId}-{workflowName}-{runId}

恢复已有会话

// 使用相同的 Session ID 恢复
const session = await createSession({
  sessionId: 'user-123-bug-fix-task-456',
  persist: true,
  // BYOK 会话需要重新提供 API Key
  auth: {
    type: 'openai',
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-4o'
  }
})

// 恢复时可以更新配置
// session 会加载历史对话，可以继续上次的任务

暂停会话（释放内存）

完成一次对话后暂停会话，保留磁盘状态，释放内存资源：

// 暂停：释放内存但保留磁盘数据
await session.disconnect()

// 之后可以用同一 Session ID 恢复

永久删除会话

// 删除会话所有持久化数据
await session.deleteSession()

容器环境注意事项

在 Docker/Kubernetes 等容器环境中，容器重启会丢失本地文件系统数据。必须将持久化目录挂载到持久化存储：

# Docker Compose 示例
volumes:
  - /persistent-storage/sessions:/data/sessions

# Kubernetes PVC 示例
volumeMounts:
  - name: session-storage
    mountPath: /data/sessions
volumes:
  - name: session-storage
    persistentVolumeClaim:
      claimName: copilot-sessions-pvc

长时间运行任务：无限会话

对于数小时甚至数天的长任务，开启自动压缩模式避免上下文溢出：

const session = await createSession({
  sessionId: 'long-running-analysis-001',
  persist: true,
  infiniteSession: true  // 开启自动压缩，防止上下文窗口溢出
})

SDK 会在上下文接近限制时自动压缩历史，保留关键信息。

并发访问注意

SDK 不提供内置的会话锁定机制，同一 Session ID 的并发访问行为未定义。如果需要防止并发：

// 在应用层实现锁，例如使用 Redis
const lock = await redis.set(`session-lock:${sessionId}`, 1, 'EX', 300, 'NX')
if (!lock) throw new Error('会话正在被其他进程使用')

常见问题

Q: 自动空闲清理会在什么时候触发？

A: SDK 有内置的空闲会话自动清理机制，长时间未使用的会话会被清理。具体时间窗口参考 SDK 文档，生产环境建议设置监控告警避免意外丢失。

Q: 会话数据存在哪里？

A: 默认存储在系统临时目录下的 Copilot SDK 子目录。通过 persistDirectory 参数可以自定义路径，生产环境建议显式指定并确保权限正确。

Q: 会话持久化对性能有影响吗？

A: 有小幅影响（磁盘 I/O）。对于高频短会话（如 API 接口），建议不开启持久化；对于长时间任务（Agent 工作流），持久化带来的可恢复性价值远大于性能开销。