Name: 会话管理APISkill
Rating: 5 (1 reviews)

name: 会话 description: “会话管理，对话历史和检查点” emoji: “💬”

会话 - 完整API参考

跨渠道管理对话会话、历史、检查点和重置。

聊天命令

会话控制

/new                                        开始新对话
/reset                                      重置当前会话
/session                                    查看会话信息
/session list                               列出活动会话

检查点

/checkpoint save "重构前"                  保存检查点
/checkpoint list                            列出检查点
/checkpoint restore <id>                    恢复检查点
/checkpoint delete <id>                     删除检查点

历史

/history                                    查看对话历史
/history export                             导出为Markdown
/history clear                              清除历史（保留会话）

设置

/session scope main                         使用主会话
/session scope channel                      每渠道会话
/session scope peer                         每用户会话
/session reset-time 00:00                   设置每日重置时间
/session idle-reset 30                      30分钟空闲后重置

TypeScript API参考

创建会话管理器

import { createSessionManager } from 'clodds/sessions';

const sessions = createSessionManager({
  // 会话范围
  scope: 'per-channel-peer',  // 'main' | 'per-peer' | 'per-channel-peer'

  // 自动重置
  dailyResetHour: 0,  // 午夜重置
  idleResetMinutes: 30,  // 30分钟空闲后重置

  // 存储
  storage: 'sqlite',
  dbPath: './sessions.db',

  // 加密
  encryptTranscripts: true,
  encryptionKey: process.env.SESSION_KEY,
});

获取或创建会话

const session = await sessions.getOrCreateSession({
  userId: 'user-123',
  channelId: 'telegram-456',
  peerId: 'peer-789',
});

console.log(`会话ID: ${session.id}`);
console.log(`创建时间: ${session.createdAt}`);
console.log(`消息数量: ${session.messageCount}`);
console.log(`最后活动时间: ${session.lastActivityAt}`);

添加消息到历史

// 添加用户消息
await sessions.addMessage({
  sessionId: session.id,
  role: 'user',
  content: '我的投资组合价值是多少？',
});

// 添加助手消息
await sessions.addMessage({
  sessionId: session.id,
  role: 'assistant',
  content: '您的投资组合价值为$10,234.56',
  usage: {
    inputTokens: 500,
    outputTokens: 200,
  },
});

获取历史

// 获取对话历史
const history = await sessions.getHistory(session.id, {
  limit: 50,
  format: 'messages',  // 'messages' | 'markdown' | 'text'
});

for (const msg of history) {
  console.log(`[${msg.role}] ${msg.content}`);
}

清除历史

// 清除对话但保留会话
await sessions.clearHistory(session.id);

重置会话

// 完全重置（新会话）
await sessions.reset({
  userId: 'user-123',
  channelId: 'telegram-456',
});

检查点

// 保存检查点
const checkpoint = await sessions.saveCheckpoint({
  sessionId: session.id,
  name: '重大变更前',
  description: '在重构交易策略前保存状态',
});

console.log(`检查点ID: ${checkpoint.id}`);
console.log(`保存的消息数量: ${checkpoint.messageCount}`);

// 列出检查点
const checkpoints = await sessions.listCheckpoints(session.id);

for (const cp of checkpoints) {
  console.log(`${cp.id}: ${cp.name} (${cp.messageCount} 条消息)`);
}

// 恢复检查点
await sessions.restoreCheckpoint(checkpoint.id);

// 删除检查点
await sessions.deleteCheckpoint(checkpoint.id);

导出会话

// 导出为Markdown
const markdown = await sessions.export(session.id, {
  format: 'markdown',
  includeMetadata: true,
});

// 导出为JSON
const json = await sessions.export(session.id, {
  format: 'json',
});

会话清理

// 删除旧会话
await sessions.cleanup({
  olderThan: '30d',  // 删除30天前的会话
  keepCheckpoints: true,
});

会话范围

范围	描述	使用场景
`main`	单一全局会话	个人使用
`per-peer`	每用户会话	多用户，共享渠道
`per-channel-peer`	每用户每渠道会话	完全隔离

自动重置行为

触发	行为
每日重置	在配置的小时开始新会话
空闲重置	不活动后开始新会话
手动重置	用户运行`/new`或`/reset`

加密

当encryptTranscripts: true时：

所有消息使用AES-256-GCM加密
每会话加密密钥
从主密钥安全派生密钥

上下文窗口管理

// 获取上下文感知历史（用于LLM）
const context = await sessions.getContextHistory({
  sessionId: session.id,
  maxTokens: 100000,  // 适应上下文窗口
  strategy: 'smart',  // 'recent' | 'smart' | 'summarize'
});

// 'smart' 保持系统消息 + 最近消息 + 重要消息
// 'summarize' 将旧消息压缩成摘要

最佳实践

选择合适的范围 — 多用户使用每渠道-每用户范围
使用检查点 — 在重大变更或实验前
定期导出 — 备份重要对话
设置空闲重置 — 防止上下文陈旧
启用加密 — 用于敏感对话