[!info] related notes

• 所属 MOC: AI Agent Application MOC
• 相关: Conversation Persistence, Message Persistence
• 实践: 会话与消息流设计

Session Management

一句话定义

Session Management 是管理用户与 AI Agent 会话生命周期的模块。一个 Session 是一次连续对话的上下文容器，包含会话元数据、消息历史、Agent 状态和用户偏好。

它解决什么问题

AI 对话不是无状态的请求-响应。每次用户发送消息时，需要知道：

• 这是哪个会话？（session_id）
• 之前聊了什么？（消息历史）
• Agent 当前在什么状态？（进行中/等待审批/完成）
• 会话是否过期？

没有 Session Management，每次对话都是独立的，Agent 没有上下文。

核心原理

Session 数据结构

type Session struct {
    ID          string    `json:"id"`
    UserID      string    `json:"user_id"`
    Title       string    `json:"title"`
    Status      string    `json:"status"` // active, archived, deleted
    CreatedAt   time.Time `json:"created_at"`
    UpdatedAt   time.Time `json:"updated_at"`
    ExpiresAt   *time.Time `json:"expires_at,omitempty"`
    Metadata    map[string]any `json:"metadata,omitempty"`
}

Session 生命周期

创建 → 活跃 → 归档
          → 删除
          → 过期自动清理

会话列表 API

// 创建会话
POST /api/sessions
Body: { "title": "..." }
Response: { "id": "sess_xxx", "title": "...", "created_at": "..." }

// 获取会话列表
GET /api/sessions?page=1&limit=20
Response: { "sessions": [...], "total": 100 }

// 获取会话详情（含消息）
GET /api/sessions/:id
Response: { "session": {...}, "messages": [...] }

// 归档会话
PATCH /api/sessions/:id
Body: { "status": "archived" }

// 删除会话
DELETE /api/sessions/:id

典型工程实现

会话服务

type SessionService struct {
    repo      SessionRepository
    msgRepo   MessageRepository
    cache     Cache
}

func (s *SessionService) GetOrCreate(ctx context.Context, userID string, sessionID string) (*Session, error) {
    if sessionID != "" {
        session, err := s.repo.GetByID(ctx, sessionID)
        if err == nil && session.UserID == userID {
            return session, nil
        }
    }
    return s.Create(ctx, userID)
}

func (s *SessionService) Create(ctx context.Context, userID string) (*Session, error) {
    session := &Session{
        ID:        generateID(),
        UserID:    userID,
        Status:    "active",
        CreatedAt: time.Now(),
    }
    return session, s.repo.Save(ctx, session)
}

常见设计模式

1. 自动标题生成

第一条消息发送后，用 LLM 自动生成会话标题。

2. 会话过期

设置 TTL，过期后自动归档或删除。

3. 多设备同步

同一个用户在不同设备上可以看到相同的会话列表。

常见坑

1. 不做会话隔离: 用户 A 能看到用户 B 的会话
2. 消息和会话不一致: 会话删除了但消息还在
3. 不做过期清理: 数据库无限增长
4. Session ID 不安全: 可预测的 ID 导致越权

参考资料

• 会话与消息流设计