Sessions - Complete API Reference

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

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

聊天命令

会话控制

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

检查点

/checkpoint save "before refactor"          保存检查点
/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: 'Before major change',
  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} messages)`);
}

// 恢复检查点
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' 将旧消息压缩成摘要

最佳实践

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