Version: 0.9.26.dev.260417

后端：
1. Prompt 层从 execute 专属骨架重构为全节点统一四段式 buildUnifiedStageMessages
  - 新增 unified_context.go：定义 StageMessagesConfig + buildUnifiedStageMessages 统一骨架，所有节点（Chat/Plan/Execute/Deliver/DeepAnswer）共用同一套 msg0~msg3 拼装逻辑
  - 新增 conversation_view.go：通用对话历史渲染 buildConversationHistoryMessage，各节点复用，不再各自维护提取逻辑
  - 新增 chat_context.go / plan_context.go / deliver_context.go：各节点自行渲染 msg1（对话视图）和 msg2（工作区），统一层只负责"怎么拼"，不再替节点决定"放什么"
  - Chat/Plan/Deliver/Execute 的 BuildXXXMessages 全部从 buildStageMessages 切到 buildUnifiedStageMessages，移除旧路径
  - 删除 execute_pinned.go：execute 记忆渲染合并到统一层 renderUnifiedMemoryContext
  - Plan prompt 不再在 user prompt 中拼装任务类 ID 列表和 renderStateSummary，改为依赖 msg2 规划工作区；Chat 粗排判断从"上下文有任务类 ID"改为"批量调度需求"
  - Deliver prompt 新增 IsAborted/IsExhaustedTerminal 区分，支持粗排收口和主动终止场景
2. Execute ReAct 上下文简化——移除归档搬运、窗口裁剪和重复工具压缩
  - 移除 splitExecuteLoopRecordsByBoundary、findLatestExecuteBoundaryMarker、tailExecuteLoops、compressExecuteLoopObservationsByTool、buildEarlyExecuteReactSummary、trimExecuteMessage1ByBudget 等六个函数
  - 移除 executeLoopWindowLimit / executeConversationTurnLimit / executeMessage1MaxRunes 等预算常量
  - msg1 不再从历史中归档上一轮 ReAct 结果，只保留真实对话流（user + assistant speak），全量注入
  - msg2 不再按 loop_closed / step_advanced 边界切分"归档/活跃"，直接全量注入全部 ReAct Loop 记录
  - token 预算由统一压缩层兜底，prompt 层不再做提前裁剪
3. 压缩层从 Execute 专属提升为全节点通用 UnifiedCompact
  - 删除 execute_compact.go（Execute 专属压缩文件）
  - 新增 unified_compact.go：UnifiedCompactInput 参数化，各节点（Plan/Chat/Deliver/Execute）构造时从自己的 NodeInput 提取公共字段，消除对 Execute 的直接依赖
  - CompactionStore 接口扩展 LoadStageCompaction / SaveStageCompaction，各节点按 stageKey 独立维护压缩状态互不覆盖
  - 非 4 段式消息时退化成按角色汇总统计，确保 context_token_stats 仍然刷新
4. Retry 重试机制全面下线
  - dao/agent.go：saveChatHistoryCore / SaveChatHistory / SaveChatHistoryInTx 移除 retry_group_id / retry_index /
  retry_from_user_message_id / retry_from_assistant_message_id 四个参数，修复乱码注释
  - dao/agent-cache.go：移除 ApplyRetrySeed 和 extractMessageHistoryID 两个方法
  - conv/agent.go：ToEinoMessages 不再回灌 retry_* 字段到运行期上下文
  - service/agentsvc/agent.go：移除 chatRetryMeta 及 resolveRetryGroupID / buildRetrySeed 等全部重试逻辑
  - service/agentsvc/agent_quick_note.go：整个文件删除（retry 快速补写路径已无用）
  - service/events/chat_history_persist.go：移除 retry 参数传递
5. 节点层瘦身 + 可见消息逐条持久化
  - agent_nodes.go 大幅简化：Chat/Plan/Execute/Deliver 节点方法移除 ToolSchema 注入、状态摘要渲染等逻辑，只做参数转发和状态落盘
  - 新增 visible_message.go：persistVisibleAssistantMessage 统一处理可见 assistant speak 的实时持久化，失败仅记日志不中断主流程
  - 新增 llm_debug.go：logNodeLLMContext 统一打印 LLM 上下文调试日志
  - graph_run_state.go 新增 PersistVisibleMessageFunc 类型 + AgentGraphDeps.PersistVisibleMessage 字段
  - service/agentsvc/agent_newagent.go 精简主循环，注入 PersistVisibleMessage 回调；agent_history.go 精简历史构建
  - token_budget.go 移除 Execute 专属预算检查，统一到通用预算

前端：
1. 移除 retry 相关 UI 和类型
  - agent.ts 移除 retry_group_id / retry_index / retry_total 字段及 normalize 逻辑
  - AssistantPanel.vue 移除 retry 相关 UI 和交互代码（约 700 行精简）
  - dashboard.ts 移除 retry 相关类型定义
  - AssistantView.vue 微调
2. ContextWindowMeter 压缩次数展示和数值格式优化
  - 新增 formatCompactCount 工具函数，千位以上用 k 单位压缩（如 80k）
  - 新增压缩次数显示
3.修复了新对话发消息时，user和assistant消息被自动调换的bug

仓库：无

backend/newAgent/node/agent_nodes.go

@@ -12,12 +12,12 @@ import (
 	"github.com/LoveLosita/smartflow/backend/newAgent/tools/schedule"
 )
 
-// AgentNodes 是 newAgent 通用图的节点容器。
+// AgentNodes 负责把 graph 层的节点调用统一转成 node 层真正的执行入口。
 //
 // 职责边界：
-// 1. 负责把 node 层真正实现的方法统一暴露给 graph 注册；
-// 2. 负责收口"graph 只编排、node 真执行"的结构约束；
-// 3. 负责在每个节点执行成功后统一做状态持久化（Save/Delete）。
+// 1. 这里只做参数转发、依赖注入和状态落盘，不承载业务决策。
+// 2. 各节点真正的执行逻辑仍在对应的 RunXXXNode 内。
+// 3. 节点成功后统一保存快照，方便断线恢复。
 type AgentNodes struct{}
 
 // NewAgentNodes 创建通用节点容器。
@@ -25,104 +25,71 @@ func NewAgentNodes() *AgentNodes {
 	return &AgentNodes{}
 }
 
-// Chat 是聊天入口的正式节点方法。
-//
-// 职责边界：
-// 1. 这里只做 graph -> node 的参数转接；
-// 2. 真正的入口逻辑仍由 RunChatNode 负责；
-// 3. Chat 的 Save 交给 Service 层处理，这里不做持久化。
+// Chat 负责把 graph 的 chat 节点请求转给 RunChatNode。
 func (n *AgentNodes) Chat(ctx context.Context, st *newagentmodel.AgentGraphState) (*newagentmodel.AgentGraphState, error) {
 	if st == nil {
 		return nil, errors.New("chat node: state is nil")
 	}
 
-	// 注入工具 schema 到 ConversationContext，让路由决策更智能。
-	if st.Deps.ToolRegistry != nil {
-		schemas := st.Deps.ToolRegistry.Schemas()
-		toolSchemas := make([]newagentmodel.ToolSchemaContext, len(schemas))
-		for i, s := range schemas {
-			toolSchemas[i] = newagentmodel.ToolSchemaContext{
-				Name:       s.Name,
-				Desc:       s.Desc,
-				SchemaText: s.SchemaText,
-			}
-		}
-		st.EnsureConversationContext().SetToolSchemas(toolSchemas)
-	}
+	// 1. Chat 阶段只负责路由与纯对话，不需要看到工具目录，避免能力细节干扰判断。
+	st.EnsureConversationContext().SetToolSchemas(nil)
 
-	if err := RunChatNode(
-		ctx,
-		ChatNodeInput{
-			RuntimeState:        st.EnsureRuntimeState(),
-			ConversationContext: st.EnsureConversationContext(),
-			UserInput:           st.Request.UserInput,
-			ConfirmAction:       st.Request.ConfirmAction,
-			Client:              st.Deps.ResolveChatClient(),
-			ChunkEmitter:        st.EnsureChunkEmitter(),
-		},
-	); err != nil {
+	if err := RunChatNode(ctx, ChatNodeInput{
+		RuntimeState:          st.EnsureRuntimeState(),
+		ConversationContext:   st.EnsureConversationContext(),
+		UserInput:             st.Request.UserInput,
+		ConfirmAction:         st.Request.ConfirmAction,
+		Client:                st.Deps.ResolveChatClient(),
+		ChunkEmitter:          st.EnsureChunkEmitter(),
+		CompactionStore:       st.Deps.CompactionStore,
+		PersistVisibleMessage: st.Deps.PersistVisibleMessage,
+	}); err != nil {
 		return nil, err
 	}
+
+	saveAgentState(ctx, st)
 	return st, nil
 }
 
-// Confirm 是确认阶段的正式节点方法。
-//
-// 职责边界：
-// 1. 这里只做 graph -> node 的参数转接；
-// 2. 真正的确认逻辑仍由 RunConfirmNode 负责；
-// 3. 不需要 LLM Client — 确认内容由已有状态机械格式化。
-// 4. Confirm 执行成功后保存状态，因为它创建了 PendingInteraction。
+// Confirm 负责把 graph 的 confirm 节点请求转给 RunConfirmNode。
 func (n *AgentNodes) Confirm(ctx context.Context, st *newagentmodel.AgentGraphState) (*newagentmodel.AgentGraphState, error) {
 	if st == nil {
 		return nil, errors.New("confirm node: state is nil")
 	}
 
-	if err := RunConfirmNode(
-		ctx,
-		ConfirmNodeInput{
-			RuntimeState:        st.EnsureRuntimeState(),
-			ConversationContext: st.EnsureConversationContext(),
-			ChunkEmitter:        st.EnsureChunkEmitter(),
-		},
-	); err != nil {
+	if err := RunConfirmNode(ctx, ConfirmNodeInput{
+		RuntimeState:        st.EnsureRuntimeState(),
+		ConversationContext: st.EnsureConversationContext(),
+		ChunkEmitter:        st.EnsureChunkEmitter(),
+	}); err != nil {
 		return nil, err
-	} else if st.Deps.WriteSchedulePreview != nil && st.ScheduleState == nil {
-		flowState := st.EnsureFlowState()
-		log.Printf("[WARN] deliver: schedule state is nil, skip preview write chat=%s", flowState.ConversationID)
 	}
 
 	saveAgentState(ctx, st)
 	return st, nil
 }
 
-// Plan 是规划阶段的正式节点方法。
-//
-// 职责边界：
-// 1. 这里只做 graph -> node 的参数转接；
-// 2. 真正的单轮规划逻辑仍由 RunPlanNode 负责；
-// 3. Plan 执行成功后保存状态，支持意外断线恢复。
+// Plan 负责把 graph 的 plan 节点请求转给 RunPlanNode。
 func (n *AgentNodes) Plan(ctx context.Context, st *newagentmodel.AgentGraphState) (*newagentmodel.AgentGraphState, error) {
 	if st == nil {
 		return nil, errors.New("plan node: state is nil")
 	}
 
-	// 等待后台记忆检索完成，注入最新记忆后再启动 Plan。
+	// 等待后端记忆检索完成，再把最新结果注入上下文。
 	ensureFreshMemory(st)
 
-	if err := RunPlanNode(
-		ctx,
-		PlanNodeInput{
-			RuntimeState:        st.EnsureRuntimeState(),
-			ConversationContext: st.EnsureConversationContext(),
-			UserInput:           st.Request.UserInput,
-			Client:              st.Deps.ResolvePlanClient(),
-			ChunkEmitter:        st.EnsureChunkEmitter(),
-			ResumeNode:          "plan",
-			AlwaysExecute:       st.Request.AlwaysExecute,
-			ThinkingEnabled:     st.Deps.ThinkingPlan,
-		},
-	); err != nil {
+	if err := RunPlanNode(ctx, PlanNodeInput{
+		RuntimeState:          st.EnsureRuntimeState(),
+		ConversationContext:   st.EnsureConversationContext(),
+		UserInput:             st.Request.UserInput,
+		Client:                st.Deps.ResolvePlanClient(),
+		ChunkEmitter:          st.EnsureChunkEmitter(),
+		ResumeNode:            "plan",
+		AlwaysExecute:         st.Request.AlwaysExecute,
+		ThinkingEnabled:       st.Deps.ThinkingPlan,
+		CompactionStore:       st.Deps.CompactionStore,
+		PersistVisibleMessage: st.Deps.PersistVisibleMessage,
+	}); err != nil {
 		return nil, err
 	}
 
@@ -130,12 +97,7 @@ func (n *AgentNodes) Plan(ctx context.Context, st *newagentmodel.AgentGraphState
 	return st, nil
 }
 
-// RoughBuild 是粗排阶段的正式节点方法。
-//
-// 职责边界：
-// 1. 调用注入的 RoughBuildFunc 执行粗排算法；
-// 2. 把粗排结果写入 ScheduleState；
-// 3. 完成后保存状态，支持意外断线恢复。
+// RoughBuild 负责把 graph 的 rough_build 节点请求转给 RunRoughBuildNode。
 func (n *AgentNodes) RoughBuild(ctx context.Context, st *newagentmodel.AgentGraphState) (*newagentmodel.AgentGraphState, error) {
 	if st == nil {
 		return nil, errors.New("rough_build node: state is nil")
@@ -149,48 +111,31 @@ func (n *AgentNodes) RoughBuild(ctx context.Context, st *newagentmodel.AgentGrap
 	return st, nil
 }
 
-// Interrupt 是中断阶段的正式节点方法。
-//
-// 职责边界：
-// 1. 这里只做 graph -> node 的参数转接；
-// 2. 真正的中断逻辑仍由 RunInterruptNode 负责；
-// 3. 不需要 LLM Client — 所有文本已在 PendingInteraction 里。
-// 4. 不需要 Save — 上游节点（Plan/Execute/Confirm）已经存过了。
+// Interrupt 负责把 graph 的 interrupt 节点请求转给 RunInterruptNode。
 func (n *AgentNodes) Interrupt(ctx context.Context, st *newagentmodel.AgentGraphState) (*newagentmodel.AgentGraphState, error) {
 	if st == nil {
 		return nil, errors.New("interrupt node: state is nil")
 	}
 
-	if err := RunInterruptNode(
-		ctx,
-		InterruptNodeInput{
-			RuntimeState:        st.EnsureRuntimeState(),
-			ConversationContext: st.EnsureConversationContext(),
-			ChunkEmitter:        st.EnsureChunkEmitter(),
-		},
-	); err != nil {
+	if err := RunInterruptNode(ctx, InterruptNodeInput{
+		RuntimeState:          st.EnsureRuntimeState(),
+		ConversationContext:   st.EnsureConversationContext(),
+		ChunkEmitter:          st.EnsureChunkEmitter(),
+		PersistVisibleMessage: st.Deps.PersistVisibleMessage,
+	}); err != nil {
 		return nil, err
 	}
+
 	return st, nil
 }
 
-// Execute 是执行阶段的正式节点方法。
-//
-// 职责边界：
-// 1. 这里只做 graph -> node 的参数转接；
-// 2. 真正的单轮执行逻辑仍由 RunExecuteNode 负责。
-//
-// 设计原则：
-// 1. LLM 主导：LLM 自己判断 done_when 是否满足，自己决定何时推进/完成；
-// 2. 后端兜底：只做资源控制、安全兜底、证据记录；
-// 3. 不做硬校验：后端不质疑 LLM 的 advance/complete 决策。
-// 4. Execute 每轮执行成功后保存状态，支持意外断线恢复。
+// Execute 负责把 graph 的 execute 节点请求转给 RunExecuteNode。
 func (n *AgentNodes) Execute(ctx context.Context, st *newagentmodel.AgentGraphState) (*newagentmodel.AgentGraphState, error) {
 	if st == nil {
 		return nil, errors.New("execute node: state is nil")
 	}
 
-	// 按需加载 ScheduleState（首次执行时从 DB 加载，后续复用内存中的 state）。
+	// 1. 首次进入时按需加载日程状态，后续轮次复用内存状态。
 	var scheduleState *schedule.ScheduleState
 	if ss, loadErr := st.EnsureScheduleState(ctx); loadErr != nil {
 		return nil, fmt.Errorf("execute node: 加载日程状态失败: %w", loadErr)
@@ -198,7 +143,7 @@ func (n *AgentNodes) Execute(ctx context.Context, st *newagentmodel.AgentGraphSt
 		scheduleState = ss
 	}
 
-	// 注入工具 schema 到 ConversationContext，让 LLM 能看到可用工具列表。
+	// 2. 把工具 schema 注入上下文，供 LLM 看到真实工具边界。
 	if st.Deps.ToolRegistry != nil {
 		schemas := st.Deps.ToolRegistry.Schemas()
 		toolSchemas := make([]newagentmodel.ToolSchemaContext, len(schemas))
@@ -212,28 +157,26 @@ func (n *AgentNodes) Execute(ctx context.Context, st *newagentmodel.AgentGraphSt
 		st.EnsureConversationContext().SetToolSchemas(toolSchemas)
 	}
 
-	// 等待后台记忆检索完成，注入最新记忆后再启动 Execute。
+	// 3. 等待后端记忆检索结果，再把最新结果注入上下文。
 	ensureFreshMemory(st)
 
-	if err := RunExecuteNode(
-		ctx,
-		ExecuteNodeInput{
-			RuntimeState:          st.EnsureRuntimeState(),
-			ConversationContext:   st.EnsureConversationContext(),
-			UserInput:             st.Request.UserInput,
-			Client:                st.Deps.ResolveExecuteClient(),
-			ChunkEmitter:          st.EnsureChunkEmitter(),
-			ResumeNode:            "execute",
-			ToolRegistry:          st.Deps.ToolRegistry,
-			ScheduleState:         scheduleState,
-			SchedulePersistor:     st.Deps.SchedulePersistor,
-			CompactionStore:       st.Deps.CompactionStore,
-			WriteSchedulePreview:  st.Deps.WriteSchedulePreview,
-			OriginalScheduleState: st.OriginalScheduleState,
-			AlwaysExecute:         st.Request.AlwaysExecute,
-			ThinkingEnabled:       st.Deps.ThinkingExecute,
-		},
-	); err != nil {
+	if err := RunExecuteNode(ctx, ExecuteNodeInput{
+		RuntimeState:          st.EnsureRuntimeState(),
+		ConversationContext:   st.EnsureConversationContext(),
+		UserInput:             st.Request.UserInput,
+		Client:                st.Deps.ResolveExecuteClient(),
+		ChunkEmitter:          st.EnsureChunkEmitter(),
+		ResumeNode:            "execute",
+		ToolRegistry:          st.Deps.ToolRegistry,
+		ScheduleState:         scheduleState,
+		SchedulePersistor:     st.Deps.SchedulePersistor,
+		CompactionStore:       st.Deps.CompactionStore,
+		WriteSchedulePreview:  st.Deps.WriteSchedulePreview,
+		OriginalScheduleState: st.OriginalScheduleState,
+		AlwaysExecute:         st.Request.AlwaysExecute,
+		ThinkingEnabled:       st.Deps.ThinkingExecute,
+		PersistVisibleMessage: st.Deps.PersistVisibleMessage,
+	}); err != nil {
 		return nil, err
 	}
 
@@ -241,12 +184,7 @@ func (n *AgentNodes) Execute(ctx context.Context, st *newagentmodel.AgentGraphSt
 	return st, nil
 }
 
-// OrderGuard 是顺序守卫阶段的正式节点方法。
-//
-// 职责边界：
-// 1. 只负责调用 RunOrderGuardNode 做 suggested 相对顺序校验；
-// 2. 不负责交付文案生成，校验结果统一交给 Deliver 节点收口；
-// 3. 节点执行后保存状态，保证异常中断后仍可复盘守卫结果。
+// OrderGuard 负责把 graph 的 order_guard 节点请求转给 RunOrderGuardNode。
 func (n *AgentNodes) OrderGuard(ctx context.Context, st *newagentmodel.AgentGraphState) (*newagentmodel.AgentGraphState, error) {
 	if st == nil {
 		return nil, errors.New("order_guard node: state is nil")
@@ -260,38 +198,32 @@ func (n *AgentNodes) OrderGuard(ctx context.Context, st *newagentmodel.AgentGrap
 	return st, nil
 }
 
-// Deliver 是交付阶段的正式节点方法。
-//
-// 职责边界：
-// 1. 这里只做 graph -> node 的参数转接；
-// 2. 真正的交付逻辑仍由 RunDeliverNode 负责；
-// 3. 调 LLM 生成任务总结，失败时降级到机械格式化。
-// 4. 任务完成后保存最终状态到 Redis（2h TTL），支持断线恢复和 MySQL outbox 异步持久化。
+// Deliver 负责把 graph 的 deliver 节点请求转给 RunDeliverNode。
 func (n *AgentNodes) Deliver(ctx context.Context, st *newagentmodel.AgentGraphState) (*newagentmodel.AgentGraphState, error) {
 	if st == nil {
 		return nil, errors.New("deliver node: state is nil")
 	}
 
-	if err := RunDeliverNode(
-		ctx,
-		DeliverNodeInput{
-			RuntimeState:        st.EnsureRuntimeState(),
-			ConversationContext: st.EnsureConversationContext(),
-			Client:              st.Deps.ResolveDeliverClient(),
-			ChunkEmitter:        st.EnsureChunkEmitter(),
-			ThinkingEnabled:     st.Deps.ThinkingDeliver,
-		},
-	); err != nil {
+	// 1. Deliver 只做最终收口总结，不需要工具目录，避免无关能力信息污染总结。
+	st.EnsureConversationContext().SetToolSchemas(nil)
+
+	if err := RunDeliverNode(ctx, DeliverNodeInput{
+		RuntimeState:          st.EnsureRuntimeState(),
+		ConversationContext:   st.EnsureConversationContext(),
+		Client:                st.Deps.ResolveDeliverClient(),
+		ChunkEmitter:          st.EnsureChunkEmitter(),
+		ThinkingEnabled:       st.Deps.ThinkingDeliver,
+		CompactionStore:       st.Deps.CompactionStore,
+		PersistVisibleMessage: st.Deps.PersistVisibleMessage,
+	}); err != nil {
 		return nil, err
 	}
 
-	// 任务完成后写排程预览缓存：只有走到 Deliver 才代表排程结果已稳定，
-	// 中断（confirm/ask_user）路径不写，避免把中间态暴露给前端。
+	// 只有真正完成时才写入排程预览，避免中间态污染前端展示。
 	if st.Deps.WriteSchedulePreview != nil && st.ScheduleState != nil {
 		flowState := st.EnsureFlowState()
 		if flowState != nil && flowState.IsCompleted() {
 			if err := st.Deps.WriteSchedulePreview(ctx, st.ScheduleState, flowState.UserID, flowState.ConversationID, flowState.TaskClassIDs); err != nil {
-				// 写缓存失败不阻断主流程，降级为仅 log。
 				log.Printf("[WARN] deliver: 写入排程预览缓存失败 chat=%s: %v", flowState.ConversationID, err)
 			}
 		} else if flowState != nil {
@@ -303,19 +235,16 @@ func (n *AgentNodes) Deliver(ctx context.Context, st *newagentmodel.AgentGraphSt
 	return st, nil
 }
 
-// --- 记忆预取消费辅助 ---
-
-// ensureFreshMemory 等待后台记忆检索完成，将最新结果注入 ConversationContext。
+// ensureFreshMemory 等待后端记忆检索完成，并把最新结果写入 ConversationContext。
 //
-// 设计说明：
-// 1. 只在首次调用时等待 channel（最多 500ms），后续调用直接跳过；
-// 2. 覆盖 ConversationContext 中已有的缓存记忆（UpsertPinnedBlock 按 key 覆盖）；
-// 3. timeout 后保留缓存记忆不替换，保证 Execute ReAct 循环不会因超时丢失记忆。
+// 1. 只在首次调用时等待 channel，后续调用直接跳过。
+// 2. 超时后保留原有上下文，不额外覆盖。
+// 3. 记忆为空时也不做额外写入，避免污染 prompt。
 func ensureFreshMemory(st *newagentmodel.AgentGraphState) {
 	if st == nil || st.Deps.MemoryConsumed || st.Deps.MemoryFuture == nil {
 		return
 	}
-	st.Deps.MemoryConsumed = true // 标记已消费，后续调用直接跳过
+	st.Deps.MemoryConsumed = true
 
 	select {
 	case content := <-st.Deps.MemoryFuture:
@@ -327,20 +256,11 @@ func ensureFreshMemory(st *newagentmodel.AgentGraphState) {
 			})
 		}
 	case <-time.After(newagentmodel.MemoryFreshTimeout):
-		// timeout：保留 ConversationContext 中已有的缓存记忆，不做额外操作
+		// 超时后保留原有上下文即可。
 	}
 }
 
-// --- 持久化辅助 ---
-
-// saveAgentState 在节点执行成功后，将当前运行态快照保存到 Redis。
-//
-// 设计原则：
-// 1. Save 失败只记日志，不中断 Graph 流程；
-// 2. StateStore 为空时静默跳过（骨架期 / 测试环境）；
-// 3. conversationID 为空时也静默跳过，避免写入无效 key。
-//
-// TODO: 接入项目统一的日志框架后，把 _ = err 改成结构化日志。
+// saveAgentState 在节点成功执行后保存运行快照。
 func saveAgentState(ctx context.Context, st *newagentmodel.AgentGraphState) {
 	if st == nil {
 		return
@@ -370,14 +290,7 @@ func saveAgentState(ctx context.Context, st *newagentmodel.AgentGraphState) {
 	_ = store.Save(ctx, flowState.ConversationID, snapshot)
 }
 
-// deleteAgentState 在任务完成后，删除 Redis 中的运行态快照。
-//
-// 设计原则：
-// 1. Delete 失败只记日志，不中断 Graph 流程；
-// 2. 删除是幂等的，key 不存在也视为成功；
-// 3. StateStore 为空时静默跳过。
-//
-// TODO: 接入项目统一的日志框架后，把 _ = err 改成结构化日志。
+// deleteAgentState 在任务完成后删除运行快照。
 func deleteAgentState(ctx context.Context, st *newagentmodel.AgentGraphState) {
 	if st == nil {
 		return