Version: 0.9.32.dev.260419

后端：
1. 会话历史接口切换为统一时间线读取，并兼容 extra.resume 恢复协议
  - api/agent.go：新增 resume->confirm_action 映射（approve/reject/cancel），恢复请求缺 conversation_id 时拦截；GetConversationHistory 改为 GetConversationTimeline
  - routers/routers.go：路由从 GET /conversation-history 切换为 GET /conversation-timeline
  - model/agent.go：删除 GetConversationHistoryItem 旧 DTO
2. 新增会话时间线持久化链路（MySQL + Redis）
  - 新增 model/agent_timeline.go：定义 timeline kind、AgentTimelineEvent、持久化/返回结构
  - 新增 dao/agent_timeline.go：写入事件、按 seq 查询、查询 max seq
  - inits/mysql.go：AutoMigrate 增加 AgentTimelineEvent
  - dao/cache.go：新增 timeline list/seq key，支持 incr/set seq、append/list、全量回填与删除
  - 新增 service/agentsvc/agent_timeline.go：时间线读写编排（Redis 优先、DB 回源、seq 分配与冲突重试、extra 事件映射）
3. 聊天主链路改为写入 timeline，旧 history 服务下线
  - service/agentsvc/agent.go：普通聊天用户/助手消息改为 appendConversationTimelineEvent
  - service/agentsvc/agent_newagent.go：透传 resume_interaction_id；注入 emitter extra hook 持久化卡片事件；正文写入 timeline
  - 删除 service/agentsvc/agent_history.go：下线 conversation-history 旧缓存编排
4. newAgent 恢复与确认防串单增强
  - newAgent/model/graph_run_state.go：AgentGraphRequest 新增 ResumeInteractionID
  - newAgent/node/agent_nodes.go：透传 ResumeInteractionID
  - newAgent/node/chat.go：增加 stale_resume 校验；accept/reject 兼容 approve/cancel；非法动作返回 invalid_confirm_action
  - newAgent/stream/emitter.go：新增 extraEventHook / SetExtraEventHook，在 extra-only 与 confirm 事件触发
5. 日程暂存后同步刷新预览缓存，避免读到拖拽前旧数据
  - service/agentsvc/agent_schedule_state.go：Save 后重建并覆盖 preview 缓存，保留 trace/candidate 等字段
6. 缓存失效策略调整到 timeline 口径
  - middleware/cache_deleter.go：移除 conversation-history 失效逻辑；ChatHistory/AgentChat/AgentTimelineEvent 加入忽略集合

前端：
7. 新增时间线接口与类型定义
  - frontend/src/api/schedule_agent.ts：新增 TimelineEvent/TimelineToolPayload/TimelineConfirmPayload 与 getConversationTimeline
8. AssistantPanel 全面对接 timeline 重建消息与卡片
  - frontend/src/components/dashboard/AssistantPanel.vue：移除旧 history merge/normalize，新增 rebuildStateFromTimeline；支持 execution mode（always_execute）；支持 resume-only 发送；修复 confirm 弹层手动关闭后重复弹出；会话标题显示放宽；流式中隐藏 action bar
9. 精排弹窗健壮性与交互动效优化
  - frontend/src/components/assistant/ScheduleFineTuneModal.vue：previewData 支持 nullable，新增 visible 控制与 watch 初始化，补齐空值保护并调整弹窗动画

仓库：
10. 新增前端时间线接入说明文档
  - docs/frontend/newagent_timeline_对接说明.md：接口、kind、payload、刷新重建与迁移建议

backend/service/agentsvc/agent.go

@@ -386,18 +386,19 @@ func (s *AgentService) runNormalChatFlow(
 			pushErrNonBlocking(errChan, err)
 			return
 		}
-		s.appendConversationHistoryCacheOptimistically(
-			context.Background(),
+		if _, timelineErr := s.appendConversationTimelineEvent(
+			ctx,
 			userID,
 			chatID,
-			buildOptimisticConversationHistoryItem(
-				"user",
-				userMessage,
-				"",
-				0,
-				requestStart,
-			),
-		)
+			model.AgentTimelineKindUserText,
+			"user",
+			userMessage,
+			nil,
+			0,
+		); timelineErr != nil {
+			pushErrNonBlocking(errChan, timelineErr)
+			return
+		}
 	}
 
 	// 普通聊天链路也需要把助手回复写入 Redis，
@@ -425,18 +426,25 @@ func (s *AgentService) runNormalChatFlow(
 	}); saveErr != nil {
 		pushErrNonBlocking(errChan, saveErr)
 	} else {
-		s.appendConversationHistoryCacheOptimistically(
+		assistantTimelinePayload := map[string]any{}
+		if strings.TrimSpace(assistantReasoning) != "" {
+			assistantTimelinePayload["reasoning_content"] = strings.TrimSpace(assistantReasoning)
+		}
+		if reasoningDurationSeconds > 0 {
+			assistantTimelinePayload["reasoning_duration_seconds"] = reasoningDurationSeconds
+		}
+		if _, timelineErr := s.appendConversationTimelineEvent(
 			context.Background(),
 			userID,
 			chatID,
-			buildOptimisticConversationHistoryItem(
-				"assistant",
-				fullText,
-				assistantReasoning,
-				reasoningDurationSeconds,
-				time.Now(),
-			),
-		)
+			model.AgentTimelineKindAssistantText,
+			"assistant",
+			fullText,
+			assistantTimelinePayload,
+			requestTotalTokens,
+		); timelineErr != nil {
+			pushErrNonBlocking(errChan, timelineErr)
+		}
 	}
 
 	// 9. 在主回复完成后异步尝试生成会话标题（仅首次、仅标题为空时生效）。

backend/service/agentsvc/agent_history.go

@@ -1,257 +0,0 @@
-package agentsvc
-
-import (
-	"context"
-	"fmt"
-	"log"
-	"sort"
-	"strings"
-	"time"
-
-	"github.com/LoveLosita/smartflow/backend/model"
-	"github.com/LoveLosita/smartflow/backend/pkg"
-	"github.com/LoveLosita/smartflow/backend/respond"
-	"gorm.io/gorm"
-)
-
-// GetConversationHistory 返回指定会话的聊天历史。
-//
-// 职责边界：
-// 1. 负责会话 ID 归一化、会话归属校验，以及“先 Redis、后 DB”的读取编排；
-// 2. 负责把缓存消息 / DB 记录统一转换为 API 响应 DTO；
-// 3. 不负责补写会话标题，也不负责修改聊天主链路的缓存写入策略。
-func (s *AgentService) GetConversationHistory(ctx context.Context, userID int, chatID string) ([]model.GetConversationHistoryItem, error) {
-	normalizedChatID := strings.TrimSpace(chatID)
-	if normalizedChatID == "" {
-		return nil, respond.MissingParam
-	}
-
-	// 1. 先做归属校验：
-	// 1.1 Redis 历史缓存只按 chat_id 分桶，不能单靠缓存判断用户归属；
-	// 1.2 因此先查会话是否属于当前用户，避免命中别人会话缓存时产生越权读取；
-	// 1.3 若会话不存在，统一返回 gorm.ErrRecordNotFound，交由 API 层映射为参数错误。
-	exists, err := s.repo.IfChatExists(ctx, userID, normalizedChatID)
-	if err != nil {
-		return nil, err
-	}
-	if !exists {
-		return nil, gorm.ErrRecordNotFound
-	}
-
-	// 2. 优先读取“会话历史视图缓存”：
-	// 2.1 这层缓存专门服务 conversation-history，字段口径与前端展示一致；
-	// 2.2 与 Agent 上下文热缓存解耦，避免为了历史多版本而拖慢首 token；
-	// 2.3 若命中则直接返回，miss 再回源 DB。
-	if s.cacheDAO != nil {
-		items, cacheErr := s.cacheDAO.GetConversationHistoryFromCache(ctx, userID, normalizedChatID)
-		if cacheErr != nil {
-			log.Printf("读取会话历史视图缓存失败 chat_id=%s: %v", normalizedChatID, cacheErr)
-		} else if conversationHistoryCacheCanServe(items) {
-			return items, nil
-		}
-	}
-
-	// 3. Redis miss 时回源 DB：
-	// 3.1 复用现有 GetUserChatHistories 读取最近 N 条历史，保证“重试版本、落库主键、创建时间”口径稳定；
-	// 3.2 再把 DB 结果转换成接口 DTO，作为历史视图缓存回填；
-	// 3.3 失败时直接上抛，由 API 层统一处理。
-	histories, err := s.repo.GetUserChatHistories(ctx, userID, pkg.HistoryFetchLimitByModel("worker"), normalizedChatID)
-	if err != nil {
-		return nil, err
-	}
-
-	items := buildConversationHistoryItemsFromDB(histories)
-
-	if s.cacheDAO != nil {
-		if setErr := s.cacheDAO.SetConversationHistoryToCache(ctx, userID, normalizedChatID, items); setErr != nil {
-			log.Printf("回填会话历史视图缓存失败 chat_id=%s: %v", normalizedChatID, setErr)
-		}
-	}
-
-	return items, nil
-}
-
-// appendConversationHistoryCacheOptimistically 把“刚生成但尚未完成 DB 持久化确认”的消息追加到历史视图缓存。
-//
-// 职责边界：
-// 1. 只服务前端会话历史展示，不参与 Agent 上下文热缓存；
-// 2. 优先复用现有历史视图缓存，miss 时再用 DB 历史做一次启动兜底；
-// 3. 不保证最终权威性，最终仍以 DB 落库成功后的缓存失效与回源结果为准。
-func (s *AgentService) appendConversationHistoryCacheOptimistically(
-	ctx context.Context,
-	userID int,
-	chatID string,
-	newItems ...model.GetConversationHistoryItem,
-) {
-	if s == nil || s.cacheDAO == nil {
-		return
-	}
-	normalizedChatID := strings.TrimSpace(chatID)
-	if userID <= 0 || normalizedChatID == "" || len(newItems) == 0 {
-		return
-	}
-	if ctx == nil {
-		ctx = context.Background()
-	}
-
-	// 1. 优先取历史视图缓存，避免每轮乐观追加都回源 DB。
-	items, err := s.cacheDAO.GetConversationHistoryFromCache(ctx, userID, normalizedChatID)
-	if err != nil {
-		log.Printf("读取会话历史视图缓存失败 chat_id=%s: %v", normalizedChatID, err)
-		return
-	}
-
-	// 2. 缓存 miss 时，用当前 DB 已有历史做一次基线兜底。
-	// 2.1 这样即便本轮是“缓存刚被 retry 补种操作删掉”，也不会只留下最新两条消息；
-	// 2.2 失败策略：DB 兜底失败只记日志并跳过，不阻塞主回复流程。
-	if items == nil {
-		histories, hisErr := s.repo.GetUserChatHistories(ctx, userID, pkg.HistoryFetchLimitByModel("worker"), normalizedChatID)
-		if hisErr != nil {
-			log.Printf("乐观追加历史缓存时回源 DB 失败 chat_id=%s: %v", normalizedChatID, hisErr)
-			return
-		}
-		items = buildConversationHistoryItemsFromDB(histories)
-	}
-
-	merged := append([]model.GetConversationHistoryItem(nil), items...)
-	for _, item := range newItems {
-		merged = appendConversationHistoryItemIfMissing(merged, item)
-	}
-	sortConversationHistoryItems(merged)
-
-	if err = s.cacheDAO.SetConversationHistoryToCache(ctx, userID, normalizedChatID, merged); err != nil {
-		log.Printf("乐观追加会话历史视图缓存失败 chat_id=%s: %v", normalizedChatID, err)
-	}
-}
-
-// buildConversationHistoryItemsFromDB 把数据库聊天记录转换为接口响应。
-//
-// 职责边界：
-// 1. 只透传 DB 已有字段，不尝试补算 reasoning_content；
-// 2. message_content / role 为空时兜底为空串与 system，避免空指针影响接口；
-// 3. 保持 DAO 返回的时间正序，前端可直接渲染。
-func buildConversationHistoryItemsFromDB(histories []model.ChatHistory) []model.GetConversationHistoryItem {
-	items := make([]model.GetConversationHistoryItem, 0, len(histories))
-	for _, history := range histories {
-		content := ""
-		if history.MessageContent != nil {
-			content = strings.TrimSpace(*history.MessageContent)
-		}
-
-		role := "system"
-		if history.Role != nil {
-			role = normalizeConversationHistoryRole(*history.Role)
-		}
-
-		items = append(items, model.GetConversationHistoryItem{
-			ID:                       history.ID,
-			Role:                     role,
-			Content:                  content,
-			CreatedAt:                history.CreatedAt,
-			ReasoningContent:         strings.TrimSpace(derefConversationHistoryText(history.ReasoningContent)),
-			ReasoningDurationSeconds: history.ReasoningDurationSeconds,
-		})
-	}
-	return items
-}
-
-func derefConversationHistoryText(text *string) string {
-	if text == nil {
-		return ""
-	}
-	return *text
-}
-
-func normalizeConversationHistoryRole(role string) string {
-	switch strings.ToLower(strings.TrimSpace(role)) {
-	case "user":
-		return "user"
-	case "assistant":
-		return "assistant"
-	default:
-		return "system"
-	}
-}
-
-func conversationHistoryCacheCanServe(items []model.GetConversationHistoryItem) bool {
-	// 1. 历史接口一旦被前端用于“重试/编辑”等二次动作，消息 id 就必须稳定可追溯。
-	// 2. 乐观缓存里的新消息在 DB 落库前没有自增主键，若直接返回，会让前端拿到占位 id。
-	// 3. 因此只有“缓存里的每条消息都带稳定 DB id”时，才允许直接命中缓存；否则强制回源 DB。
-	for _, item := range items {
-		if item.ID <= 0 {
-			return false
-		}
-	}
-	return items != nil
-}
-
-func buildOptimisticConversationHistoryItem(
-	role string,
-	content string,
-	reasoningContent string,
-	reasoningDurationSeconds int,
-	createdAt time.Time,
-) model.GetConversationHistoryItem {
-	item := model.GetConversationHistoryItem{
-		Role:                     normalizeConversationHistoryRole(role),
-		Content:                  strings.TrimSpace(content),
-		ReasoningContent:         strings.TrimSpace(reasoningContent),
-		ReasoningDurationSeconds: reasoningDurationSeconds,
-	}
-	if !createdAt.IsZero() {
-		t := createdAt
-		item.CreatedAt = &t
-	}
-	return item
-}
-
-func appendConversationHistoryItemIfMissing(
-	items []model.GetConversationHistoryItem,
-	item model.GetConversationHistoryItem,
-) []model.GetConversationHistoryItem {
-	targetKey := conversationHistoryItemSignature(item)
-	for _, existed := range items {
-		if conversationHistoryItemSignature(existed) == targetKey {
-			return items
-		}
-	}
-	return append(items, item)
-}
-
-func conversationHistoryItemSignature(item model.GetConversationHistoryItem) string {
-	if item.ID > 0 {
-		return fmt.Sprintf("id:%d", item.ID)
-	}
-
-	createdAt := ""
-	if item.CreatedAt != nil {
-		createdAt = item.CreatedAt.UTC().Format(time.RFC3339Nano)
-	}
-
-	return fmt.Sprintf(
-		"%s|%s|%s|%d|%s",
-		strings.TrimSpace(item.Role),
-		strings.TrimSpace(item.Content),
-		strings.TrimSpace(item.ReasoningContent),
-		item.ReasoningDurationSeconds,
-		createdAt,
-	)
-}
-
-func sortConversationHistoryItems(items []model.GetConversationHistoryItem) {
-	sort.SliceStable(items, func(i, j int) bool {
-		left := conversationHistoryTimestamp(items[i])
-		right := conversationHistoryTimestamp(items[j])
-		if left.Equal(right) {
-			return conversationHistoryItemSignature(items[i]) < conversationHistoryItemSignature(items[j])
-		}
-		return left.Before(right)
-	})
-}
-
-func conversationHistoryTimestamp(item model.GetConversationHistoryItem) time.Time {
-	if item.CreatedAt == nil {
-		return time.Time{}
-	}
-	return *item.CreatedAt
-}

backend/service/agentsvc/agent_newagent.go

@@ -159,14 +159,19 @@ func (s *AgentService) runNewAgentGraph(
 	}
 
 	// 6. 构造 AgentGraphRequest。
-	var confirmAction string
+	var (
+		confirmAction       string
+		resumeInteractionID string
+	)
 	if len(extra) > 0 {
 		confirmAction = readAgentExtraString(extra, "confirm_action")
+		resumeInteractionID = readAgentExtraString(extra, "resume_interaction_id")
 	}
 	graphRequest := newagentmodel.AgentGraphRequest{
-		UserInput:     userMessage,
-		ConfirmAction: confirmAction,
-		AlwaysExecute: readAgentExtraBool(extra, "always_execute"),
+		UserInput:           userMessage,
+		ConfirmAction:       confirmAction,
+		ResumeInteractionID: resumeInteractionID,
+		AlwaysExecute:       readAgentExtraBool(extra, "always_execute"),
 	}
 	graphRequest.Normalize()
 
@@ -181,6 +186,10 @@ func (s *AgentService) runNewAgentGraph(
 	// 8. 适配 SSE emitter。
 	sseEmitter := newagentstream.NewSSEPayloadEmitter(outChan)
 	chunkEmitter := newagentstream.NewChunkEmitter(sseEmitter, traceID, resolvedModelName, requestStart.Unix())
+	// 关键卡片事件走统一时间线持久化，保证刷新后可重建。
+	chunkEmitter.SetExtraEventHook(func(extra *newagentstream.OpenAIChunkExtra) {
+		s.persistNewAgentTimelineExtraEvent(context.Background(), userID, chatID, extra)
+	})
 
 	// 9. 构造 AgentGraphDeps（由 cmd/start.go 注入的依赖）。
 	deps := newagentmodel.AgentGraphDeps{
@@ -466,19 +475,33 @@ func (s *AgentService) persistNewAgentConversationMessage(
 		return err
 	}
 
-	now := time.Now()
-	s.appendConversationHistoryCacheOptimistically(
+	// 统一写入会话时间线，保证正文与卡片可按单一 seq 顺序重建。
+	timelineKind := model.AgentTimelineKindAssistantText
+	switch role {
+	case "user":
+		timelineKind = model.AgentTimelineKindUserText
+	case "assistant":
+		timelineKind = model.AgentTimelineKindAssistantText
+	}
+	timelinePayload := map[string]any{}
+	if persistPayload.ReasoningContent != "" {
+		timelinePayload["reasoning_content"] = persistPayload.ReasoningContent
+	}
+	if reasoningDurationSeconds > 0 {
+		timelinePayload["reasoning_duration_seconds"] = reasoningDurationSeconds
+	}
+	if _, err := s.appendConversationTimelineEvent(
 		ctx,
 		userID,
 		chatID,
-		buildOptimisticConversationHistoryItem(
-			role,
-			content,
-			persistPayload.ReasoningContent,
-			reasoningDurationSeconds,
-			now,
-		),
-	)
+		timelineKind,
+		role,
+		content,
+		timelinePayload,
+		tokensConsumed,
+	); err != nil {
+		return err
+	}
 	return nil
 }
 

backend/service/agentsvc/agent_schedule_state.go

@@ -5,27 +5,27 @@ import (
 	"errors"
 	"fmt"
 	"log"
+	"strings"
 
 	"github.com/LoveLosita/smartflow/backend/model"
 	newagentconv "github.com/LoveLosita/smartflow/backend/newAgent/conv"
+	newagentmodel "github.com/LoveLosita/smartflow/backend/newAgent/model"
 	"github.com/LoveLosita/smartflow/backend/respond"
 )
 
-// SaveScheduleState 前端暂存日程调整到 Redis 快照。
+// SaveScheduleState 处理前端拖拽后的“暂存排程状态”请求。
 //
 // 职责边界：
-// 1. 只负责更新 Redis 中的 ScheduleState 中 source=task_item 的任务；
-// 2. 接受绝对时间格式（与 apply-batch 统一），由 conv 层转换为内部相对坐标；
-// 3. source=event 的课程保持快照原值不变；
-// 4. 不负责写 MySQL、不负责刷新预览缓存；
-// 5. 不负责触发 graph 执行（由 confirm_action=accept 驱动）。
+// 1. 负责把前端绝对坐标写回当前会话的 ScheduleState 快照；
+// 2. 负责刷新 Redis 预览缓存，保证后续预览读取与最新拖拽一致；
+// 3. 不负责写 MySQL 正式课表，也不负责触发新一轮 graph 执行。
 func (s *AgentService) SaveScheduleState(
 	ctx context.Context,
 	userID int,
 	conversationID string,
 	items []model.SaveScheduleStatePlacedItem,
 ) error {
-	// 1. 加载快照。
+	// 1. 加载会话快照；没有快照说明当前会话不在可微调窗口内。
 	if s.agentStateStore == nil {
 		return errors.New("agent state store 未初始化")
 	}
@@ -33,12 +33,11 @@ func (s *AgentService) SaveScheduleState(
 	if err != nil {
 		return fmt.Errorf("加载快照失败: %w", err)
 	}
-
 	if !ok || snapshot == nil || snapshot.ScheduleState == nil {
 		return respond.ScheduleStateSnapshotNotFound
 	}
 
-	// 2. 校验归属。
+	// 2. 做会话归属校验，防止跨用户写入别人的会话快照。
 	if snapshot.RuntimeState != nil {
 		cs := snapshot.RuntimeState.EnsureCommonState()
 		if cs.UserID != 0 && cs.UserID != userID {
@@ -46,17 +45,98 @@ func (s *AgentService) SaveScheduleState(
 		}
 	}
 
-	// 3. 调用 conv 层将绝对时间放置项应用到 ScheduleState。
+	// 3. 将前端绝对坐标应用到内存态 ScheduleState。
+	// 3.1 这里只修改 source=task_item 任务；
+	// 3.2 source=event 课程位保持不变；
+	// 3.3 坐标非法时由 ApplyPlacedItems 返回明确错误。
 	if err := newagentconv.ApplyPlacedItems(snapshot.ScheduleState, items); err != nil {
 		return err
 	}
 
-	// 4. 写回 Redis。
+	// 4. 先写回运行态快照，确保“拖拽后的状态”成为后续读链路真值。
 	if err := s.agentStateStore.Save(ctx, conversationID, snapshot); err != nil {
 		return fmt.Errorf("保存快照失败: %w", err)
 	}
 
-	log.Printf("[INFO] schedule state saved chat=%s user=%d item_count=%d",
-		conversationID, userID, len(items))
+	// 5. 再刷新预览缓存，避免 GetSchedulePlanPreview 读到拖拽前旧缓存。
+	if err := s.refreshSchedulePreviewAfterStateSave(ctx, userID, conversationID, snapshot); err != nil {
+		return err
+	}
+
+	log.Printf("[INFO] schedule state saved chat=%s user=%d item_count=%d", conversationID, userID, len(items))
+	return nil
+}
+
+// refreshSchedulePreviewAfterStateSave 按“最新快照”重建并覆盖 Redis 预览缓存。
+//
+// 职责边界：
+// 1. 只处理 Redis 预览缓存，不负责 MySQL 快照；
+// 2. 以最新 ScheduleState 为准，修复“预览读到旧拖拽结果”的回滚问题；
+// 3. 尽量保留旧预览中的 trace_id/candidate_plans，避免前端字段突变。
+func (s *AgentService) refreshSchedulePreviewAfterStateSave(
+	ctx context.Context,
+	userID int,
+	conversationID string,
+	snapshot *newagentmodel.AgentStateSnapshot,
+) error {
+	// 1. 依赖不完整时直接跳过，避免写入不完整缓存。
+	if s == nil || s.cacheDAO == nil || snapshot == nil || snapshot.ScheduleState == nil {
+		return nil
+	}
+	normalizedConversationID := strings.TrimSpace(conversationID)
+	if normalizedConversationID == "" {
+		return nil
+	}
+
+	// 2. 从运行态提取 task_class_ids，保证预览过滤口径与会话一致。
+	taskClassIDs := make([]int, 0)
+	if snapshot.RuntimeState != nil {
+		flowState := snapshot.RuntimeState.EnsureCommonState()
+		taskClassIDs = append(taskClassIDs, flowState.TaskClassIDs...)
+	}
+
+	// 3. 基于最新 ScheduleState 生成预览主干（hybrid_entries 为最新真值）。
+	preview := newagentconv.ScheduleStateToPreview(
+		snapshot.ScheduleState,
+		userID,
+		normalizedConversationID,
+		taskClassIDs,
+		"",
+	)
+	if preview == nil {
+		return nil
+	}
+
+	// 4. 合并旧预览里需要保留的字段，避免前端依赖字段突然丢失。
+	existingPreview, err := s.cacheDAO.GetSchedulePlanPreviewFromCache(ctx, userID, normalizedConversationID)
+	if err != nil {
+		return fmt.Errorf("读取排程预览缓存失败: %w", err)
+	}
+	if existingPreview != nil {
+		preview.TraceID = strings.TrimSpace(existingPreview.TraceID)
+		if len(existingPreview.CandidatePlans) > 0 {
+			preview.CandidatePlans = cloneWeekSchedules(existingPreview.CandidatePlans)
+		}
+		if len(existingPreview.AllocatedItems) > 0 {
+			preview.AllocatedItems = cloneTaskClassItems(existingPreview.AllocatedItems)
+		}
+		if len(preview.TaskClassIDs) == 0 && len(existingPreview.TaskClassIDs) > 0 {
+			preview.TaskClassIDs = append([]int(nil), existingPreview.TaskClassIDs...)
+		}
+	}
+	if preview.CandidatePlans == nil {
+		preview.CandidatePlans = make([]model.UserWeekSchedule, 0)
+	}
+	if preview.HybridEntries == nil {
+		preview.HybridEntries = make([]model.HybridScheduleEntry, 0)
+	}
+	if preview.TaskClassIDs == nil {
+		preview.TaskClassIDs = make([]int, 0)
+	}
+
+	// 5. 回写 Redis 预览缓存；失败则返回错误，让前端可感知并重试。
+	if err := s.cacheDAO.SetSchedulePlanPreviewToCache(ctx, userID, normalizedConversationID, preview); err != nil {
+		return fmt.Errorf("刷新排程预览缓存失败: %w", err)
+	}
 	return nil
 }

backend/service/agentsvc/agent_timeline.go

@@ -0,0 +1,388 @@
+package agentsvc
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"log"
+	"strings"
+	"time"
+
+	"github.com/LoveLosita/smartflow/backend/model"
+	newagentstream "github.com/LoveLosita/smartflow/backend/newAgent/stream"
+	"gorm.io/gorm"
+)
+
+// GetConversationTimeline 返回指定会话的统一时间线（正文+卡片）列表。
+//
+// 职责边界：
+// 1. 只读，不修改会话状态；
+// 2. 顺序以 seq 为准，保证刷新后可稳定重建；
+// 3. 优先读 Redis 时间线缓存，未命中再回源 MySQL。
+func (s *AgentService) GetConversationTimeline(ctx context.Context, userID int, chatID string) ([]model.GetConversationTimelineItem, error) {
+	normalizedChatID := normalizeConversationID(chatID)
+	if userID <= 0 || strings.TrimSpace(normalizedChatID) == "" {
+		return nil, gorm.ErrRecordNotFound
+	}
+
+	exists, err := s.repo.IfChatExists(ctx, userID, normalizedChatID)
+	if err != nil {
+		return nil, err
+	}
+	if !exists {
+		return nil, gorm.ErrRecordNotFound
+	}
+
+	if s.cacheDAO != nil {
+		cacheItems, cacheErr := s.cacheDAO.GetConversationTimelineFromCache(ctx, userID, normalizedChatID)
+		if cacheErr == nil && cacheItems != nil {
+			return normalizeConversationTimelineItems(cacheItems), nil
+		}
+		if cacheErr != nil {
+			log.Printf("读取会话时间线缓存失败 user=%d chat=%s err=%v", userID, normalizedChatID, cacheErr)
+		}
+	}
+
+	events, err := s.repo.ListConversationTimelineEvents(ctx, userID, normalizedChatID)
+	if err != nil {
+		return nil, err
+	}
+	items := buildConversationTimelineItemsFromDB(events)
+
+	if s.cacheDAO != nil {
+		if err := s.cacheDAO.SetConversationTimelineToCache(ctx, userID, normalizedChatID, items); err != nil {
+			log.Printf("回填会话时间线缓存失败 user=%d chat=%s err=%v", userID, normalizedChatID, err)
+		}
+		if len(items) > 0 {
+			if err := s.cacheDAO.SetConversationTimelineSeq(ctx, userID, normalizedChatID, items[len(items)-1].Seq); err != nil {
+				log.Printf("回填会话时间线 seq 失败 user=%d chat=%s err=%v", userID, normalizedChatID, err)
+			}
+		}
+	}
+
+	return normalizeConversationTimelineItems(items), nil
+}
+
+// appendConversationTimelineEvent 统一追加单条时间线事件到 Redis + MySQL。
+//
+// 步骤化说明：
+// 1. 先从 Redis INCR 分配 seq，若 Redis 异常则回退 DB MAX(seq)+1；
+// 2. 再写 MySQL，保证刷新时至少有权威持久化；
+// 3. 最后追加 Redis 时间线列表，失败只记日志，不影响主链路返回；
+// 4. 返回分配到的 seq，便于后续扩展在 SSE meta 回传顺序号。
+func (s *AgentService) appendConversationTimelineEvent(
+	ctx context.Context,
+	userID int,
+	chatID string,
+	kind string,
+	role string,
+	content string,
+	payload map[string]any,
+	tokensConsumed int,
+) (int64, error) {
+	if s == nil || s.repo == nil {
+		return 0, errors.New("agent service is not initialized")
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+
+	normalizedChatID := strings.TrimSpace(chatID)
+	normalizedRole := strings.TrimSpace(role)
+	normalizedKind := canonicalizeTimelineKind(kind, normalizedRole)
+	normalizedContent := strings.TrimSpace(content)
+	if userID <= 0 || normalizedChatID == "" || normalizedKind == "" {
+		return 0, errors.New("invalid timeline event identity")
+	}
+
+	seq, err := s.nextConversationTimelineSeq(ctx, userID, normalizedChatID)
+	if err != nil {
+		return 0, err
+	}
+
+	payloadJSON := marshalTimelinePayloadJSON(payload)
+	persistPayload := model.ChatTimelinePersistPayload{
+		UserID:         userID,
+		ConversationID: normalizedChatID,
+		Seq:            seq,
+		Kind:           normalizedKind,
+		Role:           normalizedRole,
+		Content:        normalizedContent,
+		PayloadJSON:    payloadJSON,
+		TokensConsumed: tokensConsumed,
+	}
+	eventID, eventCreatedAt, err := s.repo.SaveConversationTimelineEvent(ctx, persistPayload)
+	if err != nil {
+		// 1. 并发极端场景下（例如 Redis seq 分配失败后 DB 兜底）可能产生重复 seq；
+		// 2. 这里做一次“读取最新 MAX(seq)+1”的重试，避免主链路直接失败；
+		// 3. 重试仍失败则返回错误，让调用方感知真实落库失败。
+		if !isTimelineSeqConflictError(err) {
+			return 0, err
+		}
+		maxSeq, seqErr := s.repo.GetConversationTimelineMaxSeq(ctx, userID, normalizedChatID)
+		if seqErr != nil {
+			return 0, err
+		}
+		persistPayload.Seq = maxSeq + 1
+		var retryErr error
+		eventID, eventCreatedAt, retryErr = s.repo.SaveConversationTimelineEvent(ctx, persistPayload)
+		if retryErr != nil {
+			return 0, retryErr
+		}
+		seq = persistPayload.Seq
+		if s.cacheDAO != nil {
+			if setErr := s.cacheDAO.SetConversationTimelineSeq(ctx, userID, normalizedChatID, seq); setErr != nil {
+				log.Printf("时间线 seq 冲突重试后回写 Redis 失败 user=%d chat=%s seq=%d err=%v", userID, normalizedChatID, seq, setErr)
+			}
+		}
+	}
+
+	if s.cacheDAO != nil {
+		now := time.Now()
+		item := model.GetConversationTimelineItem{
+			ID:             eventID,
+			Seq:            seq,
+			Kind:           normalizedKind,
+			Role:           normalizedRole,
+			Content:        normalizedContent,
+			Payload:        cloneTimelinePayload(payload),
+			TokensConsumed: tokensConsumed,
+		}
+		if eventCreatedAt != nil {
+			item.CreatedAt = eventCreatedAt
+		} else {
+			item.CreatedAt = &now
+		}
+		if err := s.cacheDAO.AppendConversationTimelineEventToCache(ctx, userID, normalizedChatID, item); err != nil {
+			log.Printf("追加会话时间线缓存失败 user=%d chat=%s seq=%d kind=%s err=%v", userID, normalizedChatID, seq, normalizedKind, err)
+		}
+	}
+	return seq, nil
+}
+
+func isTimelineSeqConflictError(err error) bool {
+	if err == nil {
+		return false
+	}
+	text := strings.ToLower(err.Error())
+	return strings.Contains(text, "duplicate") && strings.Contains(text, "uk_timeline_user_chat_seq")
+}
+
+// persistNewAgentTimelineExtraEvent 把 SSE extra 卡片事件写入时间线。
+//
+// 说明：
+// 1. 只持久化真正需要刷新后重建的卡片事件；
+// 2. status/reasoning/finish 等临时过程信号不落时间线；
+// 3. 失败只记日志，不中断当前 SSE 输出。
+func (s *AgentService) persistNewAgentTimelineExtraEvent(ctx context.Context, userID int, chatID string, extra *newagentstream.OpenAIChunkExtra) {
+	kind, ok := mapTimelineKindFromStreamExtra(extra)
+	if !ok {
+		return
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+
+	if _, err := s.appendConversationTimelineEvent(
+		ctx,
+		userID,
+		chatID,
+		kind,
+		"",
+		"",
+		buildTimelinePayloadFromStreamExtra(extra),
+		0,
+	); err != nil {
+		log.Printf("写入 newAgent 卡片时间线失败 user=%d chat=%s kind=%s err=%v", userID, chatID, kind, err)
+	}
+}
+
+func (s *AgentService) nextConversationTimelineSeq(ctx context.Context, userID int, chatID string) (int64, error) {
+	if s.cacheDAO != nil {
+		seq, err := s.cacheDAO.IncrConversationTimelineSeq(ctx, userID, chatID)
+		if err == nil {
+			return seq, nil
+		}
+		log.Printf("会话时间线 seq Redis 分配失败，回退 DB user=%d chat=%s err=%v", userID, chatID, err)
+	}
+
+	maxSeq, err := s.repo.GetConversationTimelineMaxSeq(ctx, userID, chatID)
+	if err != nil {
+		return 0, err
+	}
+	seq := maxSeq + 1
+	if s.cacheDAO != nil {
+		if err := s.cacheDAO.SetConversationTimelineSeq(ctx, userID, chatID, seq); err != nil {
+			log.Printf("会话时间线 seq 回填 Redis 失败 user=%d chat=%s seq=%d err=%v", userID, chatID, seq, err)
+		}
+	}
+	return seq, nil
+}
+
+func buildConversationTimelineItemsFromDB(events []model.AgentTimelineEvent) []model.GetConversationTimelineItem {
+	if len(events) == 0 {
+		return make([]model.GetConversationTimelineItem, 0)
+	}
+	items := make([]model.GetConversationTimelineItem, 0, len(events))
+	for _, event := range events {
+		item := model.GetConversationTimelineItem{
+			ID:             event.ID,
+			Seq:            event.Seq,
+			Kind:           strings.TrimSpace(event.Kind),
+			TokensConsumed: event.TokensConsumed,
+			CreatedAt:      event.CreatedAt,
+		}
+		if event.Role != nil {
+			item.Role = strings.TrimSpace(*event.Role)
+		}
+		if event.Content != nil {
+			item.Content = strings.TrimSpace(*event.Content)
+		}
+		if event.Payload != nil {
+			var payload map[string]any
+			if err := json.Unmarshal([]byte(strings.TrimSpace(*event.Payload)), &payload); err == nil && len(payload) > 0 {
+				item.Payload = payload
+			}
+		}
+		items = append(items, item)
+	}
+	return normalizeConversationTimelineItems(items)
+}
+
+// normalizeConversationTimelineItems 统一收敛 timeline 的 kind/role 口径，避免前端切分失效。
+func normalizeConversationTimelineItems(items []model.GetConversationTimelineItem) []model.GetConversationTimelineItem {
+	if len(items) == 0 {
+		return make([]model.GetConversationTimelineItem, 0)
+	}
+	normalized := make([]model.GetConversationTimelineItem, 0, len(items))
+	for _, item := range items {
+		role := strings.ToLower(strings.TrimSpace(item.Role))
+		kind := canonicalizeTimelineKind(item.Kind, role)
+
+		// kind 缺失时尝试从 role 反推文本类型，保障“用户分段锚点”可用。
+		if kind == "" {
+			switch role {
+			case "user":
+				kind = model.AgentTimelineKindUserText
+			case "assistant":
+				kind = model.AgentTimelineKindAssistantText
+			}
+		}
+		// role 缺失时按文本类型补齐，减少前端额外兼容判断。
+		if role == "" {
+			switch kind {
+			case model.AgentTimelineKindUserText:
+				role = "user"
+			case model.AgentTimelineKindAssistantText:
+				role = "assistant"
+			}
+		}
+
+		item.Kind = kind
+		item.Role = role
+		normalized = append(normalized, item)
+	}
+	return normalized
+}
+
+// canonicalizeTimelineKind 统一 kind 别名，收敛到文档定义值。
+func canonicalizeTimelineKind(kind string, role string) string {
+	normalizedKind := strings.ToLower(strings.TrimSpace(kind))
+	normalizedRole := strings.ToLower(strings.TrimSpace(role))
+	switch normalizedKind {
+	case model.AgentTimelineKindUserText,
+		model.AgentTimelineKindAssistantText,
+		model.AgentTimelineKindToolCall,
+		model.AgentTimelineKindToolResult,
+		model.AgentTimelineKindConfirmRequest,
+		model.AgentTimelineKindScheduleCompleted:
+		return normalizedKind
+	case "text", "message", "query":
+		if normalizedRole == "user" {
+			return model.AgentTimelineKindUserText
+		}
+		if normalizedRole == "assistant" {
+			return model.AgentTimelineKindAssistantText
+		}
+		return normalizedKind
+	default:
+		return normalizedKind
+	}
+}
+
+func marshalTimelinePayloadJSON(payload map[string]any) string {
+	if len(payload) == 0 {
+		return ""
+	}
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return ""
+	}
+	return string(data)
+}
+
+func cloneTimelinePayload(payload map[string]any) map[string]any {
+	if len(payload) == 0 {
+		return nil
+	}
+	cloned := make(map[string]any, len(payload))
+	for key, value := range payload {
+		cloned[key] = value
+	}
+	return cloned
+}
+
+func mapTimelineKindFromStreamExtra(extra *newagentstream.OpenAIChunkExtra) (string, bool) {
+	if extra == nil {
+		return "", false
+	}
+	switch extra.Kind {
+	case newagentstream.StreamExtraKindToolCall:
+		return model.AgentTimelineKindToolCall, true
+	case newagentstream.StreamExtraKindToolResult:
+		return model.AgentTimelineKindToolResult, true
+	case newagentstream.StreamExtraKindConfirm:
+		return model.AgentTimelineKindConfirmRequest, true
+	case newagentstream.StreamExtraKindScheduleCompleted:
+		return model.AgentTimelineKindScheduleCompleted, true
+	default:
+		return "", false
+	}
+}
+
+func buildTimelinePayloadFromStreamExtra(extra *newagentstream.OpenAIChunkExtra) map[string]any {
+	if extra == nil {
+		return nil
+	}
+	payload := map[string]any{
+		"stage":        strings.TrimSpace(extra.Stage),
+		"block_id":     strings.TrimSpace(extra.BlockID),
+		"display_mode": string(extra.DisplayMode),
+	}
+	if extra.Tool != nil {
+		payload["tool"] = map[string]any{
+			"name":              strings.TrimSpace(extra.Tool.Name),
+			"status":            strings.TrimSpace(extra.Tool.Status),
+			"summary":           strings.TrimSpace(extra.Tool.Summary),
+			"arguments_preview": strings.TrimSpace(extra.Tool.ArgumentsPreview),
+		}
+	}
+	if extra.Confirm != nil {
+		payload["confirm"] = map[string]any{
+			"interaction_id": strings.TrimSpace(extra.Confirm.InteractionID),
+			"title":          strings.TrimSpace(extra.Confirm.Title),
+			"summary":        strings.TrimSpace(extra.Confirm.Summary),
+		}
+	}
+	if extra.Interrupt != nil {
+		payload["interrupt"] = map[string]any{
+			"interaction_id": strings.TrimSpace(extra.Interrupt.InteractionID),
+			"type":           strings.TrimSpace(extra.Interrupt.Type),
+			"summary":        strings.TrimSpace(extra.Interrupt.Summary),
+		}
+	}
+	if len(extra.Meta) > 0 {
+		payload["meta"] = cloneTimelinePayload(extra.Meta)
+	}
+	return payload
+}