| name | lumina_conversation |
| description | Use this skill when working with Agent conversations, memory, or streaming output. Covers conversationId lifecycle, MemoryManager dual-track memory (Redis hot + DB cold), and executeStream context loading. |
Lumina 会话与记忆管理规范
功能概述
本技能包用于规范 Lumina 框架的 Agent 多轮对话、会话记忆管理和流式输出，涵盖 conversationId 生命周期、MemoryManager 双轨记忆（Redis 热记忆 + DB 冷存储）、executeStream 上下文加载机制。
会话模型
数据结构
| 表 | 说明 | 迁移版本 |
|---|
lumina_conversation | 会话主表（UUID、标题、Agent 关联） | Flyway V3 |
lumina_message | 消息记录（角色、内容、会话关联） | Flyway V3 |
conversationId 生命周期
- 创建：调用
POST /api/v1/conversations，生成 UUID 作为 conversationId
- 多轮交互：每次 Agent 执行传入 conversationId，历史消息自动加载为上下文
- 持久化：所有 user/assistant 消息持久化到
lumina_message 表
- 回放：通过 conversationId 查询历史消息，支持前端会话列表和历史回放
双轨记忆机制
Redis 热记忆（MemoryManager）
@Autowired
private MemoryManager memoryManager;
List<Msg> context = memoryManager.loadMessages(conversationId);
memoryManager.saveMessage(conversationId, Msg.user(task));
memoryManager.saveMessage(conversationId, Msg.assistant(response));
| 属性 | 值 |
|---|
| 存储 | Redis |
| 上下文窗口 | CONTEXT_WINDOW = 20 条最近消息 |
| 特性 | 低延迟读取，自动滑动窗口裁剪 |
| 用途 | Agent 执行时快速加载对话上下文 |
DB 冷存储
| 属性 | 值 |
|---|
| 存储 | MySQL lumina_message 表 |
| 特性 | 永久持久化，全量消息记录 |
| 用途 | 历史回放、审计、分析 |
双轨同步
- 消息同时写入 Redis（热）和 DB（冷）
- Redis 超过窗口自动裁剪（仅保留最近 20 条）
- DB 始终保留全量消息
- Redis 数据丢失时，可从 DB 重建热记忆
引擎接入
方法签名
Result<AgentResponse> execute(AgentExecutionRequest request);
Result<AgentResponse> executeSync(AgentExecutionRequest request);
SseEmitter executeStream(AgentExecutionRequest request);
AgentExecutionRequest 包含 conversationId 字段，用于关联会话上下文。
上下文加载流程
1. 接收 conversationId
2. buildContextMessages(conversationId)
→ 从 MemoryManager 加载历史消息（Redis 热记忆，最多 20 条）
→ 映射为 Msg 列表（MsgRole 映射：USER → user, ASSISTANT → assistant, SYSTEM → system）
3. 将当前用户输入追加到 Msg 列表
4. 执行 Agent（传入完整 Msg 列表）
5. 执行完成后，保存 user 消息和 assistant 响应到双轨记忆
MsgRole 映射
| 数据库角色 | AgentScope MsgRole | 说明 |
|---|
USER | MsgRole.USER | 用户消息 |
ASSISTANT | MsgRole.ASSISTANT | Agent 响应 |
SYSTEM | MsgRole.SYSTEM | 系统提示词 |
API 接口
| 方法 | 路径 | 说明 |
|---|
| POST | /api/v1/conversations | 创建会话 |
| GET | /api/v1/conversations | 会话列表 |
| GET | /api/v1/conversations/{uuid}/messages | 获取历史消息 |
| POST | /api/v1/agents/{id}/execute/stream?task=&conversationId= | 多轮流式执行 |
流式执行示例
POST /api/v1/agents/{agentId}/execute/stream?task=你好&conversationId=abc-123
Accept: text/event-stream
→ data: {"chunk": "你"}
→ data: {"chunk": "好"}
→ data: {"done": true, "messageId": 456}
- 使用 SSE（Server-Sent Events）推送流式响应
- 响应完成后返回最终 messageId 和完整响应
前端集成
AgentChat 组件
- 会话列表：展示历史会话，支持切换、新建、删除
- 消息回放：加载
GET /api/v1/conversations/{uuid}/messages 回显历史
- 流式渲染：SSE 接收 chunk，逐字渲染 Agent 响应
- 多轮对话：每次发送携带当前 conversationId，保持上下文连续
最佳实践
- conversationId 传递：多轮对话必须传入 conversationId，否则上下文断裂
- 双轨写入：消息同时写 Redis 和 DB，确保数据一致性
- 窗口管理：Redis 热记忆自动裁剪，不要手动管理窗口大小
- 流式异常处理：SSE 连接断开时，已生成的内容仍需持久化
- 消息顺序：按时间戳排序，保证对话逻辑连贯
