Version: 0.8.3.dev.260328

后端： 1.彻底删除原agent文件夹，并将现agent2文件夹全量重命名为agent(包括全部涉及到的文件以及文档、注释)，迁移工作完美结束 2.修复了重试消息的相关逻辑问题前端： 1.改善了一些交互体验，修复了一些bug，现在只剩少的功能了，现存的bug基本都修复完毕全仓库： 1.更新了决策记录和README文档
2026-03-28 18:00:31 +08:00
parent 5fc9548420
commit 468367d617
108 changed files with 1910 additions and 17173 deletions
--- a/backend/service/agentsvc/agent.go
+++ b/backend/service/agentsvc/agent.go
@@ -3,13 +3,14 @@ package agentsvc
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"log"
 	"strconv"
 	"strings"
 	"time"

-	agentchat "github.com/LoveLosita/smartflow/backend/agent2/chat"
-	agentrouter "github.com/LoveLosita/smartflow/backend/agent2/router"
+	agentchat "github.com/LoveLosita/smartflow/backend/agent/chat"
+	agentrouter "github.com/LoveLosita/smartflow/backend/agent/router"
 	"github.com/LoveLosita/smartflow/backend/conv"
 	"github.com/LoveLosita/smartflow/backend/dao"
 	outboxinfra "github.com/LoveLosita/smartflow/backend/infra/outbox"
@@ -213,6 +214,17 @@ func (s *AgentService) buildChatRetryMeta(ctx context.Context, userID int, chatI

 	sourceUserMessageID := readAgentExtraInt(extra, "retry_from_user_message_id")
 	sourceAssistantMessageID := readAgentExtraInt(extra, "retry_from_assistant_message_id")
+	// 1. retry 请求必须明确指向“被重试的那一轮 user + assistant”。
+	// 2. 若这里拿不到有效父消息 id，继续写库只会生成一组孤立的 index=1 重试消息。
+	// 3. 因此直接拒绝本次请求，让前端刷新历史后重试，比静默写脏数据更安全。
+	if sourceUserMessageID <= 0 || sourceAssistantMessageID <= 0 {
+		return nil, errors.New("重试请求缺少有效的父消息ID，请刷新会话后重试")
+	}
+	// 4. 再进一步校验父消息确实属于当前用户与当前会话，且角色语义正确。
+	// 5. 这样即便前端误把占位 id 或串号 id 发过来，后端也不会继续落错库。
+	if err := s.repo.ValidateRetrySourceMessages(ctx, userID, chatID, sourceUserMessageID, sourceAssistantMessageID); err != nil {
+		return nil, errors.New("重试引用的父消息无效，请刷新会话后重试")
+	}

 	if err := s.repo.EnsureRetryGroupSeed(ctx, userID, chatID, groupID, sourceUserMessageID, sourceAssistantMessageID); err != nil {
 		return nil, err
--- a/backend/service/agentsvc/agent_history.go
+++ b/backend/service/agentsvc/agent_history.go
@@ -46,7 +46,7 @@ func (s *AgentService) GetConversationHistory(ctx context.Context, userID int, c
 		items, cacheErr := s.cacheDAO.GetConversationHistoryFromCache(ctx, userID, normalizedChatID)
 		if cacheErr != nil {
 			log.Printf("读取会话历史视图缓存失败 chat_id=%s: %v", normalizedChatID, cacheErr)
-		} else if items != nil {
+		} else if conversationHistoryCacheCanServe(items) {
 			return items, nil
 		}
 	}
@@ -228,6 +228,18 @@ func normalizeConversationHistoryRole(role string) string {
 	}
 }

+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,
--- a/backend/service/agentsvc/agent_quick_note.go
+++ b/backend/service/agentsvc/agent_quick_note.go
@@ -7,12 +7,12 @@ import (
 	"strings"
 	"time"

-	agentgraph "github.com/LoveLosita/smartflow/backend/agent2/graph"
-	agentllm "github.com/LoveLosita/smartflow/backend/agent2/llm"
-	agentmodel "github.com/LoveLosita/smartflow/backend/agent2/model"
-	agentnode "github.com/LoveLosita/smartflow/backend/agent2/node"
-	agentrouter "github.com/LoveLosita/smartflow/backend/agent2/router"
-	agentstream "github.com/LoveLosita/smartflow/backend/agent2/stream"
+	agentgraph "github.com/LoveLosita/smartflow/backend/agent/graph"
+	agentllm "github.com/LoveLosita/smartflow/backend/agent/llm"
+	agentmodel "github.com/LoveLosita/smartflow/backend/agent/model"
+	agentnode "github.com/LoveLosita/smartflow/backend/agent/node"
+	agentrouter "github.com/LoveLosita/smartflow/backend/agent/router"
+	agentstream "github.com/LoveLosita/smartflow/backend/agent/stream"
 	"github.com/LoveLosita/smartflow/backend/model"
 	"github.com/cloudwego/eino-ext/components/model/ark"
 	"github.com/cloudwego/eino/schema"
@@ -89,7 +89,7 @@ func (e *quickNoteProgressEmitter) Emit(stage, detail string) {
 		e.reasoning.WriteString(detail)
 	}

-	// 3. 调用目的：阶段提示统一走 agent2/stream 的 reasoning chunk 包装，
+	// 3. 调用目的：阶段提示统一走 Agent/stream 的 reasoning chunk 包装，
 	//    避免 service 层继续自己拼 OpenAI 兼容 JSON。
 	err := agentstream.EmitStageAsReasoning(func(payload string) error {
 		e.outChan <- payload
@@ -295,10 +295,10 @@ func buildQuickNoteFinalReply(ctx context.Context, selectedModel *ark.ChatModel,
 }

 // decideQuickNoteRouting 决定当前输入是否进入“随口记 graph”。
-// 该函数只是服务层薄封装，具体控制码解析逻辑已下沉到 agent/route 包。
+// 该函数只是服务层薄封装，具体控制码解析逻辑已下沉到 Agent/router 包。
 func (s *AgentService) decideQuickNoteRouting(ctx context.Context, selectedModel *ark.ChatModel, userMessage string) quickNoteRoutingDecision {
 	// 这里保留方法是为了让 AgentService 对外语义完整，
-	// 同时避免上层调用方直接依赖 route 包，降低耦合。
+	// 同时避免上层调用方直接依赖 Agent/router，降低耦合。
 	_ = s
 	return agentrouter.DecideQuickNoteRouting(ctx, selectedModel, userMessage)
 }
--- a/backend/service/agentsvc/agent_route.go
+++ b/backend/service/agentsvc/agent_route.go
@@ -3,7 +3,7 @@ package agentsvc
 import (
 	"context"

-	agentrouter "github.com/LoveLosita/smartflow/backend/agent2/router"
+	agentrouter "github.com/LoveLosita/smartflow/backend/agent/router"
 	"github.com/cloudwego/eino-ext/components/model/ark"
 )

--- a/backend/service/agentsvc/agent_schedule_plan.go
+++ b/backend/service/agentsvc/agent_schedule_plan.go
@@ -6,9 +6,9 @@ import (
 	"log"
 	"strings"

-	agentgraph "github.com/LoveLosita/smartflow/backend/agent2/graph"
-	agentmodel "github.com/LoveLosita/smartflow/backend/agent2/model"
-	agentnode "github.com/LoveLosita/smartflow/backend/agent2/node"
+	agentgraph "github.com/LoveLosita/smartflow/backend/agent/graph"
+	agentmodel "github.com/LoveLosita/smartflow/backend/agent/model"
+	agentnode "github.com/LoveLosita/smartflow/backend/agent/node"
 	"github.com/LoveLosita/smartflow/backend/conv"
 	"github.com/LoveLosita/smartflow/backend/model"
 	"github.com/LoveLosita/smartflow/backend/pkg"
@@ -157,6 +157,6 @@ func (s *AgentService) runSchedulePlanFlow(
 	// 6. 旁路写入排程预览缓存（结构化 JSON），给查询接口拉取。
 	// 6.1 失败只记日志，不影响本次对话回复；
 	// 6.2 成功后前端可通过 conversation_id 获取 candidate_plans。
-	s.saveSchedulePlanPreviewAgent2(ctx, userID, chatID, finalState)
+	s.saveSchedulePlanPreview(ctx, userID, chatID, finalState)
 	return reply, nil
 }
--- a/backend/service/agentsvc/agent_schedule_preview.go
+++ b/backend/service/agentsvc/agent_schedule_preview.go
@@ -7,20 +7,20 @@ import (
 	"strings"
 	"time"

-	agentmodel "github.com/LoveLosita/smartflow/backend/agent2/model"
-	agentshared "github.com/LoveLosita/smartflow/backend/agent2/shared"
+	agentmodel "github.com/LoveLosita/smartflow/backend/agent/model"
+	agentshared "github.com/LoveLosita/smartflow/backend/agent/shared"
 	"github.com/LoveLosita/smartflow/backend/model"
 	"github.com/LoveLosita/smartflow/backend/respond"
 )

-// saveSchedulePlanPreview 鎶婃帓绋嬬粨鏋滀互缁撴瀯鍖?JSON 蹇収鍐欏叆 Redis銆?
+// saveSchedulePlanPreview 负责把排程结果同步写入“查询预览”所需的缓存与快照。
 //
-// 鑱岃矗杈圭晫锛?
-// 1. 璐熻矗鎶?finalState 涓殑 summary + candidate_plans 鏀舵暃涓虹紦瀛?DTO锛?
-// 2. 璐熻矗浠モ€滃け璐ヤ笉闃绘柇鑱婂ぉ涓婚摼璺€濈殑绛栫暐鎵ц鍐欏叆锛?
-// 3. 涓嶈礋璐?SSE 杩斿洖鍗忚锛屼笉璐熻矗鏁版嵁搴撹惤搴撱€?
+// 职责边界：
+// 1. 负责把 graph 最终状态映射为统一预览 DTO，并先写 Redis、再写 MySQL 快照。
+// 2. 负责执行“失败不阻断主回复”的旁路持久化策略，避免影响聊天主链路。
+// 3. 不负责 SSE 输出，不负责聊天消息落库，也不负责 refine 状态到 plan 状态的转换。
 func (s *AgentService) saveSchedulePlanPreview(ctx context.Context, userID int, chatID string, finalState *agentmodel.SchedulePlanState) {
-	// 1. 鍩虹鍓嶇疆鏍￠獙锛歴tate 涓虹┖鏃剁洿鎺ヨ繑鍥烇紝閬垮厤鍐欏叆鍗婃垚鍝佸揩鐓с€?
+	// 1. 先做最小前置校验，避免把空状态或空会话写成脏快照。
 	if s == nil || finalState == nil {
 		return
 	}
@@ -29,19 +29,14 @@ func (s *AgentService) saveSchedulePlanPreview(ctx context.Context, userID int,
 		return
 	}

-	// 2. 缁勮缂撳瓨蹇収锛?
-	// 2.1 summary 浼樺厛鍙?final summary锛岀┖鍊兼椂浣跨敤缁熶竴鍏滃簳鏂囨锛?
-	// 2.2 candidate_plans 鍋氬垏鐗囨嫹璐濓紝閬垮厤鍚庣画寮曠敤鍏变韩瀵艰嚧鎰忓瑕嗙洊锛?
-	// 2.3 generated_at 鐢ㄤ簬鍓嶇鍒ゆ柇鈥滃綋鍓嶉瑙堢殑鏂伴矞搴︹€濄€?
-	summary := strings.TrimSpace(finalState.FinalSummary)
-	if summary == "" {
-		summary = "排程流程已完成，但未生成结果摘要。"
-	}
+	// 2. 组装统一预览缓存结构。
+	// 2.1 summary 为空时使用统一兜底文案，保证查询接口始终有稳定输出。
+	// 2.2 所有切片字段都做深拷贝，避免缓存与 graph state 共享底层数组。
 	preview := &model.SchedulePlanPreviewCache{
 		UserID:         userID,
 		ConversationID: normalizedChatID,
 		TraceID:        strings.TrimSpace(finalState.TraceID),
-		Summary:        summary,
+		Summary:        schedulePlanSummaryOrFallback(strings.TrimSpace(finalState.FinalSummary)),
 		CandidatePlans: cloneWeekSchedules(finalState.CandidatePlans),
 		TaskClassIDs:   append([]int(nil), finalState.TaskClassIDs...),
 		HybridEntries:  cloneHybridEntries(finalState.HybridEntries),
@@ -49,91 +44,34 @@ func (s *AgentService) saveSchedulePlanPreview(ctx context.Context, userID int,
 		GeneratedAt:    time.Now(),
 	}

-	// 3. 璋冪敤鐩殑锛氬厛鍐?Redis 棰勮锛屼繚璇佸墠绔煡璇㈡帴鍙ｈ兘蹇€熻鍙栫粨鏋勫寲缁撴灉銆?
-	// 3.1 Redis 鏄€滃揩璺緞鈥濓紱澶辫触鍙褰曟棩蹇楋紝涓嶄腑鏂富閾捐矾锛?
-	// 3.2 澶辫触鍏滃簳鐢卞悗缁?MySQL 蹇収鎵挎帴銆?
+	// 3. 先写 Redis 预览，保证前端查询链路优先命中低时延缓存。
+	// 3.1 Redis 写失败只记日志，不中断主流程；
+	// 3.2 真正兜底由后续 MySQL 快照承担。
 	if s.cacheDAO != nil {
 		if err := s.cacheDAO.SetSchedulePlanPreviewToCache(ctx, userID, normalizedChatID, preview); err != nil {
-			log.Printf("鍐欏叆鎺掔▼棰勮缂撳瓨澶辫触 chat_id=%s: %v", normalizedChatID, err)
+			log.Printf("写入排程预览缓存失败 chat_id=%s: %v", normalizedChatID, err)
 		}
 	}

-	// 4. 璋冪敤鐩殑锛氬悓姝ュ啓 MySQL 鐘舵€佸揩鐓э紝淇濊瘉 Redis 澶辨晥鍚庝粛鍙繛缁井璋冦€?
-	// 4.1 杩欓噷閲囩敤鈥滃悓姝ュ啓搴撯€濊€屼笉鏄?outbox锛氬洜涓轰笅涓€杞井璋冭寮哄疄鏃惰鍙栵紱
-	// 4.2 蹇収鍐欏叆澶辫触鍙墦鏃ュ織锛屼笉闃绘柇鏈疆鐢ㄦ埛鍥炲锛岄伩鍏嶄綋楠屾姈鍔紱
-	// 4.3 revision 鑷鐢?DAO 鐨?upsert 鍐茬獊鏇存柊璐熻矗銆?
+	// 4. 再写 MySQL 快照，保证缓存失效后仍能恢复预览与连续微调上下文。
+	// 4.1 这里继续采用“同步写快照”的策略，因为下一轮 refine 依赖强一致读取；
+	// 4.2 写库失败同样只记日志，避免让用户侧回复因为旁路持久化失败而中断。
 	if s.repo != nil {
 		snapshot := buildSchedulePlanSnapshotFromState(userID, normalizedChatID, finalState)
 		if err := s.repo.UpsertScheduleStateSnapshot(ctx, snapshot); err != nil {
-			log.Printf("鍐欏叆鎺掔▼鐘舵€佸揩鐓уけ璐?chat_id=%s: %v", normalizedChatID, err)
+			log.Printf("写入排程状态快照失败 chat_id=%s: %v", normalizedChatID, err)
 		}
 	}
 }

-// saveSchedulePlanPreviewAgent2 鎶?agent2 鐨?schedule_plan 缁撴灉鍐欏叆 Redis 棰勮涓?MySQL 蹇収銆?
+// GetSchedulePlanPreview 按 conversation_id 读取结构化排程预览。
 //
-// 鑱岃矗杈圭晫锛?
-// 1. 璐熻矗鎵挎帴鈥滄柊 agent2 棣栨鎺掔▼閾捐矾鈥濈殑鏈€缁堢姸鎬侊紱
-// 2. 璐熻矗娌跨敤鐜版湁棰勮缂撳瓨/鐘舵€佸揩鐓у崗璁紝淇濊瘉鏌ヨ鎺ュ彛涓?refine 璇诲彇閫昏緫涓嶉渶瑕佽窡鐫€閲嶅啓锛?
-// 3. 涓嶈礋璐?refine 鐘舵€佽浆鎹紝refine 浠嶇户缁蛋鏃ч摼璺殑 saveSchedulePlanPreview銆?
-func (s *AgentService) saveSchedulePlanPreviewAgent2(ctx context.Context, userID int, chatID string, finalState *agentmodel.SchedulePlanState) {
-	// 1. 鍩虹鍓嶇疆鏍￠獙锛歴tate 涓虹┖鏃剁洿鎺ヨ繑鍥烇紝閬垮厤鍐欏叆鍗婃垚鍝佸揩鐓с€?
-	if s == nil || finalState == nil {
-		return
-	}
-	normalizedChatID := strings.TrimSpace(chatID)
-	if normalizedChatID == "" {
-		return
-	}
-
-	// 2. 缁勮缂撳瓨蹇収銆?
-	// 2.1 summary 浼樺厛鍙?final summary锛岀┖鍊兼椂浣跨敤缁熶竴鍏滃簳鏂囨锛?
-	// 2.2 candidate_plans / hybrid_entries / allocated_items 缁熶竴娣辨嫹璐濓紝閬垮厤缂撳瓨涓?graph state 鍏辩敤搴曞眰鍒囩墖锛?
-	// 2.3 generated_at 鐢ㄤ簬鍓嶇鍒ゆ柇鈥滃綋鍓嶉瑙堟槸鍚︿负鏈€鏂版柟妗堚€濄€?
-	summary := strings.TrimSpace(finalState.FinalSummary)
-	if summary == "" {
-		summary = "排程流程已完成，但未生成结果摘要。"
-	}
-	preview := &model.SchedulePlanPreviewCache{
-		UserID:         userID,
-		ConversationID: normalizedChatID,
-		TraceID:        strings.TrimSpace(finalState.TraceID),
-		Summary:        summary,
-		CandidatePlans: cloneWeekSchedules(finalState.CandidatePlans),
-		TaskClassIDs:   append([]int(nil), finalState.TaskClassIDs...),
-		HybridEntries:  cloneHybridEntries(finalState.HybridEntries),
-		AllocatedItems: cloneTaskClassItems(finalState.AllocatedItems),
-		GeneratedAt:    time.Now(),
-	}
-
-	// 3. 鍏堝啓 Redis 棰勮锛屼繚璇佸墠绔煡璇㈡帴鍙ｈ兘绔嬪嵆璇诲彇缁撴瀯鍖栫粨鏋溿€?
-	// 3.1 Redis 鏄€滃揩璺緞鈥濓紱
-	// 3.2 澶辫触鍙褰曟棩蹇楋紝涓嶄腑鏂亰澶╀富閾捐矾銆?
-	if s.cacheDAO != nil {
-		if err := s.cacheDAO.SetSchedulePlanPreviewToCache(ctx, userID, normalizedChatID, preview); err != nil {
-			log.Printf("鍐欏叆鎺掔▼棰勮缂撳瓨澶辫触 chat_id=%s: %v", normalizedChatID, err)
-		}
-	}
-
-	// 4. 鍚屾鍐?MySQL 蹇収锛屼繚璇?Redis 澶辨晥鍚庝粛鑳芥仮澶嶉瑙堜笌杩炵画寰皟涓婁笅鏂囥€?
-	// 4.1 杩欓噷缁х画淇濇寔鈥滃悓姝ュ啓搴撯€濈瓥鐣ワ紝鍥犱负涓嬩竴杞井璋冨蹇収璇诲彇鏄己瀹炴椂渚濊禆锛?
-	// 4.2 鍐欏簱澶辫触鍙墦鏃ュ織锛屼笉闃绘柇鏈疆缁欑敤鎴风殑鏂囨湰鍥炲銆?
-	if s.repo != nil {
-		snapshot := buildSchedulePlanSnapshotFromAgent2State(userID, normalizedChatID, finalState)
-		if err := s.repo.UpsertScheduleStateSnapshot(ctx, snapshot); err != nil {
-			log.Printf("鍐欏叆鎺掔▼鐘舵€佸揩鐓уけ璐?chat_id=%s: %v", normalizedChatID, err)
-		}
-	}
-}
-
-// GetSchedulePlanPreview 鎸?conversation_id 璇诲彇缁撴瀯鍖栨帓绋嬮瑙堛€?
-//
-// 鑱岃矗杈圭晫锛?
-// 1. 璐熻矗鍙傛暟褰掍竴鍖栥€佺紦瀛樿鍙栦笌浼氳瘽褰掑睘鏍￠獙锛?
-// 2. 璐熻矗鎶婄紦瀛?DTO 杞垚 API 鍝嶅簲 DTO锛?
-// 3. 涓嶈礋璐ｈЕ鍙戞帓绋嬶紝涓嶈礋璐ｈˉ绠楃紦瀛樸€?
+// 职责边界：
+// 1. 负责参数归一化、缓存优先读取、会话归属校验和 DB 兜底。
+// 2. 负责把缓存/快照 DTO 转成接口响应 DTO。
+// 3. 不负责触发排程，不负责补算结果，也不负责消息链路落库。
 func (s *AgentService) GetSchedulePlanPreview(ctx context.Context, userID int, chatID string) (*model.GetSchedulePlanPreviewResponse, error) {
-	// 1. 鍙傛暟鏍￠獙锛歝onversation_id 涓虹┖鐩存帴杩斿洖鍙傛暟閿欒锛岄伩鍏嶆棤鏁?Redis 璇锋眰銆?
+	// 1. 先校验会话参数，避免无效请求打到缓存或数据库。
 	normalizedChatID := strings.TrimSpace(chatID)
 	if normalizedChatID == "" {
 		return nil, respond.MissingParam
@@ -142,10 +80,9 @@ func (s *AgentService) GetSchedulePlanPreview(ctx context.Context, userID int, c
 		return nil, errors.New("agent service is not initialized")
 	}

-	// 2. 鏌ヨ缂撳瓨骞舵牎楠屽綊灞烇細
-	// 2.1 缂撳瓨鏈懡涓細缁熶竴杩斿洖鈥滈瑙堜笉瀛樺湪/宸茶繃鏈熲€濓紱
-	// 2.2 鍛戒腑浣?user_id 涓嶄竴鑷达細鎸夋湭鍛戒腑澶勭悊锛岄伩鍏嶆硠闇蹭粬浜轰細璇濅俊鎭紱
-	// 2.3 澶辫触鍏滃簳锛氱紦瀛樿寮傚父鐩存帴涓婃姏锛岀敱 API 灞傜粺涓€閿欒澶勭悊銆?
+	// 2. 优先查 Redis。
+	// 2.1 命中后立即校验 user_id，避免把别人的会话预览泄露给当前用户；
+	// 2.2 缓存异常直接上抛，由接口层统一处理错误响应。
 	if s.cacheDAO != nil {
 		preview, err := s.cacheDAO.GetSchedulePlanPreviewFromCache(ctx, userID, normalizedChatID)
 		if err != nil {
@@ -169,10 +106,9 @@ func (s *AgentService) GetSchedulePlanPreview(ctx context.Context, userID int, c
 		}
 	}

-	// 3. Redis 鏈懡涓椂鍥炶惤 MySQL 蹇収锛?
-	// 3.1 璇诲彇鎴愬姛鍚庣洿鎺ヨ繑鍥烇紝閬垮厤鐢ㄦ埛鐪嬪埌鈥滈瑙堜笉瀛樺湪鈥濈殑鍋囬槾鎬э紱
-	// 3.2 鑻ユ湰娆″懡涓?DB 涓旂紦瀛樺彲鐢紝鍒欓『鎵嬪洖濉?Redis锛屾彁鍗囧悗缁懡涓巼锛?
-	// 3.3 DB 涔熸湭鍛戒腑鏃跺啀杩斿洖 not found銆?
+	// 3. Redis 未命中时回源 MySQL。
+	// 3.1 命中快照后顺手回填 Redis，提高后续命中率；
+	// 3.2 DB 未命中才真正返回 not found，避免缓存过期造成假阴性。
 	if s.repo != nil {
 		snapshot, err := s.repo.GetScheduleStateSnapshot(ctx, userID, normalizedChatID)
 		if err != nil {
@@ -183,36 +119,36 @@ func (s *AgentService) GetSchedulePlanPreview(ctx context.Context, userID int, c
 			if s.cacheDAO != nil {
 				cachePreview := snapshotToSchedulePlanPreviewCache(snapshot)
 				if setErr := s.cacheDAO.SetSchedulePlanPreviewToCache(ctx, userID, normalizedChatID, cachePreview); setErr != nil {
-					log.Printf("鍥炲～鎺掔▼棰勮缂撳瓨澶辫触 chat_id=%s: %v", normalizedChatID, setErr)
+					log.Printf("回填排程预览缓存失败 chat_id=%s: %v", normalizedChatID, setErr)
 				}
 			}
 			return response, nil
 		}
 	}
+
 	return nil, respond.SchedulePlanPreviewNotFound
 }

-// cloneWeekSchedules 瀵瑰懆瑙嗗浘鎺掔▼缁撴灉鍋氭繁鎷疯礉锛岄伩鍏嶅垏鐗囧紩鐢ㄥ叡浜€?
+// cloneWeekSchedules 负责深拷贝周视图排程，避免缓存与运行态共享底层切片。
 func cloneWeekSchedules(src []model.UserWeekSchedule) []model.UserWeekSchedule {
 	return agentshared.CloneWeekSchedules(src)
 }

-// cloneHybridEntries 娣辨嫹璐濇贩鍚堟潯鐩垏鐗囷紝閬垮厤缂撳瓨/鐘舵€佷箣闂寸浉浜掓薄鏌撱€?
+// cloneHybridEntries 负责深拷贝混合排程条目，避免跨请求污染。
 func cloneHybridEntries(src []model.HybridScheduleEntry) []model.HybridScheduleEntry {
 	return agentshared.CloneHybridEntries(src)
 }

-// cloneTaskClassItems 娣辨嫹璐濅换鍔″潡鍒囩墖锛堝寘鍚寚閽堝瓧娈碉級锛岄伩鍏嶈法璇锋眰寮曠敤鍏变韩銆?
+// cloneTaskClassItems 负责深拷贝任务项切片，包含内部指针字段的安全复制。
 func cloneTaskClassItems(src []model.TaskClassItem) []model.TaskClassItem {
 	return agentshared.CloneTaskClassItems(src)
 }

-// buildSchedulePlanSnapshotFromState 鎶?graph 杩愯缁撴灉鏄犲皠鎴愬彲鎸佷箙鍖栧揩鐓?DTO銆?
+// buildSchedulePlanSnapshotFromState 把 graph 最终状态映射成可持久化的快照 DTO。
 //
-// 鑱岃矗杈圭晫锛?
-// 1. 璐熻矗瀛楁鏄犲皠涓庢繁鎷疯礉锛岄伩鍏嶈法灞傚叡浜彲鍙樺垏鐗囷紱
-// 2. 璐熻矗琛ラ綈 state_version 榛樿鍊硷紱
-// 3. 涓嶈礋璐ｆ暟鎹簱鍐欏叆锛堝啓鍏ョ敱 DAO 鎵挎媴锛夈€?
+// 职责边界：
+// 1. 负责字段归一化、深拷贝和 state_version 补齐。
+// 2. 不负责数据库写入，也不负责生成业务摘要文案。
 func buildSchedulePlanSnapshotFromState(userID int, conversationID string, st *agentmodel.SchedulePlanState) *model.SchedulePlanStateSnapshot {
 	if st == nil {
 		return nil
@@ -236,44 +172,11 @@ func buildSchedulePlanSnapshotFromState(userID int, conversationID string, st *a
 	}
 }

-// buildSchedulePlanSnapshotFromAgent2State 鎶?agent2 鐨勬帓绋嬬姸鎬佹槧灏勬垚鍙寔涔呭寲蹇収 DTO銆?
-//
-// 璋冪敤鐩殑锛?
-// 1. 杩欒疆鍙縼绉?schedule_plan锛屼笉鍔?refine锛?
-// 2. 鍥犳 preview/蹇収鍗忚缁х画澶嶇敤鑰佺粨鏋勶紝浣嗚琛ヤ竴涓€渁gent2 state -> snapshot DTO鈥濈殑鏄犲皠灞傦紱
-// 3. 杩欐牱鍙互鍋氬埌锛氳鍒掑垱寤洪摼璺垏鍒?agent2锛岃€?refine / 棰勮鏌ヨ閾捐矾鏆傛椂鏃犻渶澶ф敼銆?
-func buildSchedulePlanSnapshotFromAgent2State(userID int, conversationID string, st *agentmodel.SchedulePlanState) *model.SchedulePlanStateSnapshot {
-	if st == nil {
-		return nil
-	}
-	return &model.SchedulePlanStateSnapshot{
-		UserID:           userID,
-		ConversationID:   conversationID,
-		StateVersion:     model.SchedulePlanStateVersionV1,
-		TaskClassIDs:     append([]int(nil), st.TaskClassIDs...),
-		Constraints:      append([]string(nil), st.Constraints...),
-		HybridEntries:    cloneHybridEntries(st.HybridEntries),
-		AllocatedItems:   cloneTaskClassItems(st.AllocatedItems),
-		CandidatePlans:   cloneWeekSchedules(st.CandidatePlans),
-		UserIntent:       strings.TrimSpace(st.UserIntent),
-		Strategy:         strings.TrimSpace(st.Strategy),
-		AdjustmentScope:  strings.TrimSpace(st.AdjustmentScope),
-		RestartRequested: st.RestartRequested,
-		FinalSummary:     strings.TrimSpace(st.FinalSummary),
-		Completed:        st.Completed,
-		TraceID:          strings.TrimSpace(st.TraceID),
-	}
-}
-
-// snapshotToSchedulePlanPreviewCache 鎶?MySQL 蹇収杞崲涓?Redis 棰勮缂撳瓨缁撴瀯銆?
+// snapshotToSchedulePlanPreviewCache 把 MySQL 快照映射成 Redis 预览缓存结构。
 func snapshotToSchedulePlanPreviewCache(snapshot *model.SchedulePlanStateSnapshot) *model.SchedulePlanPreviewCache {
 	if snapshot == nil {
 		return nil
 	}
-	summary := strings.TrimSpace(snapshot.FinalSummary)
-	if summary == "" {
-		summary = "排程流程已完成，但未生成结果摘要。"
-	}
 	generatedAt := snapshot.UpdatedAt
 	if generatedAt.IsZero() {
 		generatedAt = time.Now()
@@ -282,7 +185,7 @@ func snapshotToSchedulePlanPreviewCache(snapshot *model.SchedulePlanStateSnapsho
 		UserID:         snapshot.UserID,
 		ConversationID: snapshot.ConversationID,
 		TraceID:        strings.TrimSpace(snapshot.TraceID),
-		Summary:        summary,
+		Summary:        schedulePlanSummaryOrFallback(strings.TrimSpace(snapshot.FinalSummary)),
 		CandidatePlans: cloneWeekSchedules(snapshot.CandidatePlans),
 		TaskClassIDs:   append([]int(nil), snapshot.TaskClassIDs...),
 		HybridEntries:  cloneHybridEntries(snapshot.HybridEntries),
@@ -291,7 +194,7 @@ func snapshotToSchedulePlanPreviewCache(snapshot *model.SchedulePlanStateSnapsho
 	}
 }

-// snapshotToSchedulePlanPreviewResponse 鎶?MySQL 蹇収杞崲涓烘煡璇㈡帴鍙ｅ搷搴斻€?
+// snapshotToSchedulePlanPreviewResponse 把 MySQL 快照映射成查询接口响应结构。
 func snapshotToSchedulePlanPreviewResponse(snapshot *model.SchedulePlanStateSnapshot) *model.GetSchedulePlanPreviewResponse {
 	if snapshot == nil {
 		return nil
@@ -300,10 +203,6 @@ func snapshotToSchedulePlanPreviewResponse(snapshot *model.SchedulePlanStateSnap
 	if plans == nil {
 		plans = make([]model.UserWeekSchedule, 0)
 	}
-	summary := strings.TrimSpace(snapshot.FinalSummary)
-	if summary == "" {
-		summary = "排程流程已完成，但未生成结果摘要。"
-	}
 	generatedAt := snapshot.UpdatedAt
 	if generatedAt.IsZero() {
 		generatedAt = time.Now()
@@ -311,8 +210,16 @@ func snapshotToSchedulePlanPreviewResponse(snapshot *model.SchedulePlanStateSnap
 	return &model.GetSchedulePlanPreviewResponse{
 		ConversationID: snapshot.ConversationID,
 		TraceID:        strings.TrimSpace(snapshot.TraceID),
-		Summary:        summary,
+		Summary:        schedulePlanSummaryOrFallback(strings.TrimSpace(snapshot.FinalSummary)),
 		CandidatePlans: plans,
 		GeneratedAt:    generatedAt,
 	}
 }
+
+// schedulePlanSummaryOrFallback 统一收口排程摘要兜底文案，避免各处重复维护默认值。
+func schedulePlanSummaryOrFallback(summary string) string {
+	if strings.TrimSpace(summary) == "" {
+		return "排程流程已完成，但未生成结果摘要。"
+	}
+	return summary
+}
--- a/backend/service/agentsvc/agent_schedule_refine.go
+++ b/backend/service/agentsvc/agent_schedule_refine.go
@@ -6,9 +6,9 @@ import (
 	"log"
 	"strings"

-	agentgraph "github.com/LoveLosita/smartflow/backend/agent2/graph"
-	agentmodel "github.com/LoveLosita/smartflow/backend/agent2/model"
-	agentnode "github.com/LoveLosita/smartflow/backend/agent2/node"
+	agentgraph "github.com/LoveLosita/smartflow/backend/agent/graph"
+	agentmodel "github.com/LoveLosita/smartflow/backend/agent/model"
+	agentnode "github.com/LoveLosita/smartflow/backend/agent/node"
 	"github.com/LoveLosita/smartflow/backend/model"
 	"github.com/LoveLosita/smartflow/backend/respond"
 	"github.com/cloudwego/eino-ext/components/model/ark"
@@ -69,7 +69,7 @@ func (s *AgentService) runScheduleRefineFlow(
 	// 4.2 杩欓噷鎶?refine state 鏄犲皠涓?scheduleplan state锛屽鐢ㄥ凡鏈夎惤鐩橀摼璺紱
 	// 4.3 浣嗚嫢鏄€滅嫭绔嬪鍚堝垎鏀凡鍑虹珯銆佺粓瀹′粛澶辫触鈥濓紝鍒欎笉瑕嗙洊涓婁竴鐗堥瑙堬紝閬垮厤澶栭儴璇互涓烘柊鏂规宸查獙璇侀€氳繃銆?
 	if shouldPersistScheduleRefinePreview(finalState) {
-		s.saveSchedulePlanPreviewAgent2(ctx, userID, chatID, convertRefineStateToPlanState(finalState))
+		s.saveSchedulePlanPreview(ctx, userID, chatID, convertRefineStateToPlanState(finalState))
 	} else {
 		emitStage("schedule_refine.preview.skipped", "复合分支终审未通过，本轮结果不覆盖上一版预览。")
 	}
--- a/backend/service/agentsvc/agent_task_query.go
+++ b/backend/service/agentsvc/agent_task_query.go
@@ -7,9 +7,9 @@ import (
 	"strings"
 	"time"

-	agentgraph "github.com/LoveLosita/smartflow/backend/agent2/graph"
-	agentmodel "github.com/LoveLosita/smartflow/backend/agent2/model"
-	agentnode "github.com/LoveLosita/smartflow/backend/agent2/node"
+	agentgraph "github.com/LoveLosita/smartflow/backend/agent/graph"
+	agentmodel "github.com/LoveLosita/smartflow/backend/agent/model"
+	agentnode "github.com/LoveLosita/smartflow/backend/agent/node"
 	"github.com/LoveLosita/smartflow/backend/model"
 	"github.com/LoveLosita/smartflow/backend/respond"
 	"github.com/cloudwego/eino-ext/components/model/ark"