Version: 0.9.2.dev.260406

后端：
   1.Chat 四路由升级（二分类 chat/task → 四路由 direct_reply/execute/deep_answer/plan）
     - 新建model/chat_contract.go：路由决策模型，含 NeedsRoughBuild 粗排标记
     - 更新node/chat.go：四路由分流；新增 deep_answer 深度回答路径（二次 LLM 开 thinking）
     - 更新prompt/chat.go：意图分类 prompt 升级为四路由 prompt；新增 deep_answer prompt
   2.粗排节点（RoughBuild）全链路
     - 新建node/rough_build.go：粗排节点，调用注入的算法函数，结果写入 ScheduleState 后进 Execute 微调
     - 更新graph/common_graph.go：注册 RoughBuild 节点；Chat/Confirm 后可路由至粗排
     - 更新model/graph_run_state.go：新增 RoughBuildPlacement/RoughBuildFunc 类型；Deps 注入入口
     - 更新model/plan_contract.go：PlanDecision 新增 NeedsRoughBuild/TaskClassIDs 字段
     - 更新node/plan.go：plan_done 时写入粗排标记和 TaskClassIDs
   3.任务类约束元数据（TaskClassMeta）贯穿 prompt → tools → 持久化
     - 更新tools/state.go：新增 TaskClassMeta；ScheduleState.TaskClasses；ScheduleTask.TaskClassID；Clone 深拷贝
     - 更新conv/schedule_state.go：加载时构建 TaskClassMeta；Diff 支持 HostEventID 嵌入关系
     - 更新conv/schedule_provider.go：新增 LoadTaskClassMetas 按需加载
     - 更新model/state_store.go：ScheduleStateProvider 接口新增 LoadTaskClassMetas
     - 更新prompt/base.go：renderStateSummary 渲染任务类约束
     - 更新prompt/plan.go：注入任务类 ID 上下文和粗排识别规则
     - 更新tools/read_tools.go：GetOverview 展示任务类约束
     - 更新model/common_state.go：CommonState 新增 TaskClassIDs/TaskClasses/NeedsRoughBuild
   4.Execute 健壮性增强（correction 重试 + 纯 ReAct 模式）
     - 更新node/execute.go：未知工具名/空文本走 correction 重试而非 fatal；maxConsecutiveCorrections 提升为包级常量；新增无 plan 纯ReAct 模式；工具结果截断；speak 排除 ask_user/confirm
     - 更新prompt/execute.go：新增 ReAct 模式 system prompt 和 contract
   5.写入持久化完善（task_item source + 嵌入水课）
     - 更新conv/schedule_persist.go：place/move/unplace 支持 task_item source，含嵌入水课和普通 task event 两条路径
     - 新建conv/schedule_preview.go：ScheduleState → 排程预览缓存，复用旧格式，前端无需改动
   6.状态持久化体系（Redis → MySQL outbox 异步）
     - 更新dao/cache.go：Redis 快照 TTL 从 24h 改为 2h，配合 MySQL outbox
     - 新建model/agent_state_snapshot_record.go：快照 MySQL 记录模型
     - 新建service/events/agent_state_persist.go：outbox 异步持久化处理器
     - 更新cmd/start.go + inits/mysql.go：注册快照事件处理器 + AutoMigrate
     - 更新service/agentsvc/agent_newagent.go：注入 RoughBuildFunc；outbox 异步写快照；排程结果写 Redis 预览缓存
   7.基础设施与稳定性
     - 更新stream/sse_adapter.go：outChan 满时静默丢弃，保证持久化不被 SSE 阻断
     - 更新service/agentsvc/agent.go：新增 readAgentExtraIntSlice；outChan 容量 8→256
     - 更新node/agent_nodes.go：Chat 注入工具 schema；Deliver 改 saveAgentState 替代 deleteAgentState
前端：无
仓库：无

backend/newAgent/model/chat_contract.go

@@ -0,0 +1,72 @@
+package model
+
+import (
+	"fmt"
+	"strings"
+)
+
+// ChatRoute 表示 Chat 节点路由决策的目标路径。
+type ChatRoute string
+
+const (
+	// ChatRouteDirectReply 简单任务：Chat 节点直接输出回复，不再调用下游节点。
+	ChatRouteDirectReply ChatRoute = "direct_reply"
+
+	// ChatRouteExecute 中等任务：需要用工具处理，直接进 Execute ReAct 循环。
+	ChatRouteExecute ChatRoute = "execute"
+
+	// ChatRouteDeepAnswer 复杂问答：需要深度思考但不需工具，Chat 节点原地开 thinking 回答。
+	ChatRouteDeepAnswer ChatRoute = "deep_answer"
+
+	// ChatRoutePlan 复杂规划：需要先制定计划，进 Plan 节点。
+	ChatRoutePlan ChatRoute = "plan"
+)
+
+// ChatRoutingDecision 是 Chat 节点单次路由决策的结构化输出。
+//
+// 职责边界：
+// 1. Route 决定后续处理路径；
+// 2. Speak 始终填写：给用户看的话；
+// 3. NeedsRoughBuild 仅在 route=execute 且满足粗排条件时为 true；
+// 4. Reason 给后端和日志看。
+type ChatRoutingDecision struct {
+	Route           ChatRoute `json:"route"`
+	Speak           string    `json:"speak,omitempty"`
+	NeedsRoughBuild bool      `json:"needs_rough_build,omitempty"`
+	Reason          string    `json:"reason,omitempty"`
+}
+
+// Normalize 统一清洗路由决策中的字符串字段。
+func (d *ChatRoutingDecision) Normalize() {
+	if d == nil {
+		return
+	}
+	d.Route = ChatRoute(strings.TrimSpace(string(d.Route)))
+	d.Speak = strings.TrimSpace(d.Speak)
+	d.Reason = strings.TrimSpace(d.Reason)
+}
+
+// Validate 校验路由决策的最小合法性。
+func (d *ChatRoutingDecision) Validate() error {
+	if d == nil {
+		return fmt.Errorf("chat routing decision 不能为空")
+	}
+
+	d.Normalize()
+
+	switch d.Route {
+	case ChatRouteDirectReply, ChatRouteExecute, ChatRouteDeepAnswer, ChatRoutePlan:
+		// ok
+	case "":
+		return fmt.Errorf("chat routing decision.route 不能为空")
+	default:
+		return fmt.Errorf("未知 route: %s", d.Route)
+	}
+
+	// direct_reply 必须有 speak。
+	if d.Route == ChatRouteDirectReply && d.Speak == "" {
+		return fmt.Errorf("direct_reply 必须携带 speak")
+	}
+
+	return nil
+}

backend/newAgent/model/common_state.go

@@ -1,5 +1,9 @@
 package model
 
+import (
+	newagenttools "github.com/LoveLosita/smartflow/backend/newAgent/tools"
+)
+
 // Phase 表示 agent 主循环当前所处的大阶段。
 type Phase string
 
@@ -39,6 +43,17 @@ type CommonState struct {
 
 	// 连续修正计数：LLM 连续输出不合法决策的次数，超过阈值后强制终止避免死循环。
 	ConsecutiveCorrections int `json:"consecutive_corrections"`
+
+	// TaskClassIDs 本次排课请求涉及的任务类 ID 列表，由前端 extra.task_class_ids 传入。
+	// Plan 节点据此判断是否需要粗排；跨轮次持久化，不会因会话恢复而丢失。
+	TaskClassIDs []int `json:"task_class_ids,omitempty"`
+	// TaskClasses 本次排课涉及的任务类约束元数据（含日期、策略、时段预算等），
+	// 在 Service 层从 DB 加载并注入，供 Plan prompt 直接消费，避免 LLM 因信息不足而追问用户。
+	TaskClasses []newagenttools.TaskClassMeta `json:"task_classes,omitempty"`
+
+	// NeedsRoughBuild 由 Plan 节点在 plan_done 时写入，标记 Confirm 后是否需要走粗排节点。
+	// 粗排节点执行完毕后会将此字段重置为 false。
+	NeedsRoughBuild bool `json:"needs_rough_build,omitempty"`
 }
 
 func NewCommonState(traceID string, userID int, conversationID string) *CommonState {

backend/newAgent/model/graph_run_state.go

@@ -29,6 +29,20 @@ func (r *AgentGraphRequest) Normalize() {
 	r.ConfirmAction = strings.TrimSpace(r.ConfirmAction)
 }
 
+// RoughBuildPlacement 是粗排算法返回的单条放置结果。
+// 字段使用 DB 坐标系（week/dayOfWeek/section），由 RoughBuild 节点转换为 ScheduleState 的 day_index。
+type RoughBuildPlacement struct {
+	TaskItemID  int
+	Week        int
+	DayOfWeek   int
+	SectionFrom int
+	SectionTo   int
+}
+
+// RoughBuildFunc 是粗排算法的依赖注入签名。
+// 由 service 层封装 HybridScheduleWithPlanMulti 后注入，newAgent 层不直接依赖外层 model。
+type RoughBuildFunc func(ctx context.Context, userID int, taskClassIDs []int) ([]RoughBuildPlacement, error)
+
 // AgentGraphDeps 描述 graph/node 层运行时真正依赖的可插拔能力。
 //
 // 设计目的：
@@ -45,6 +59,7 @@ type AgentGraphDeps struct {
 	ToolRegistry      *newagenttools.ToolRegistry
 	ScheduleProvider  ScheduleStateProvider // 按 DAO 注入，Execute 节点按需加载 ScheduleState
 	SchedulePersistor SchedulePersistor     // 按 DAO 注入，用于写工具执行后持久化变更
+	RoughBuildFunc    RoughBuildFunc        // 按 Service 注入，粗排算法入口
 }
 
 // EnsureChunkEmitter 保证 graph 运行时始终有一个可用的 chunk 发射器。

backend/newAgent/model/plan_contract.go

@@ -44,14 +44,18 @@ const (
 // 1. Speak 是本轮先对用户说的话；若 action=ask_user，通常这里会承载要追问的问题；
 // 2. Action 是规划阶段的下一步动作类型；
 // 3. Reason 是给后端和日志看的简短解释；
-// 4. PlanSteps 只在 plan_done 时要求返回，表示本轮最终确认下来的完整自然语言计划。
+// 4. PlanSteps 只在 plan_done 时要求返回，表示本轮最终确认下来的完整自然语言计划；
+// 5. NeedsRoughBuild 为 true 时，Confirm 后自动触发粗排节点，不需要 LLM 在 plan_steps 里手动描述放置步骤；
+// 6. TaskClassIDs 是本次粗排涉及的任务类 ID 列表，与 CommonState.TaskClassIDs 保持一致。
 type PlanDecision struct {
-	Speak        string         `json:"speak,omitempty"`
-	Action       PlanAction     `json:"action"`
-	Reason       string         `json:"reason,omitempty"`
-	Complexity   PlanComplexity `json:"complexity"`
-	NeedThinking bool           `json:"need_thinking"`
-	PlanSteps    []PlanStep     `json:"plan_steps,omitempty"`
+	Speak           string         `json:"speak,omitempty"`
+	Action          PlanAction     `json:"action"`
+	Reason          string         `json:"reason,omitempty"`
+	Complexity      PlanComplexity `json:"complexity"`
+	NeedThinking    bool           `json:"need_thinking"`
+	PlanSteps       []PlanStep     `json:"plan_steps,omitempty"`
+	NeedsRoughBuild bool           `json:"needs_rough_build,omitempty"`
+	TaskClassIDs    []int          `json:"task_class_ids,omitempty"`
 }
 
 // Normalize 统一清洗规划决策中的字符串字段。

backend/newAgent/model/state_store.go

@@ -57,6 +57,8 @@ type AgentStateStore interface {
 // 使用接口而非具体 DAO 类型，避免 model → dao 的循环依赖。
 type ScheduleStateProvider interface {
 	LoadScheduleState(ctx context.Context, userID int) (*newagenttools.ScheduleState, error)
+	// LoadTaskClassMetas 只加载指定任务类的约束元数据，供 Plan 节点提前消费。
+	LoadTaskClassMetas(ctx context.Context, userID int, taskClassIDs []int) ([]newagenttools.TaskClassMeta, error)
 }
 
 // SchedulePersistor 定义持久化 ScheduleState 变更的接口。