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 前端：无仓库：无
2026-04-06 23:15:54 +08:00
parent b1eb6bedf9
commit 2038185730
30 changed files with 1866 additions and 298 deletions
--- a/backend/newAgent/prompt/base.go
+++ b/backend/newAgent/prompt/base.go
@@ -70,29 +70,46 @@ func renderStateSummary(state *newagentmodel.CommonState) string {

 	if !state.HasPlan() {
 		sb.WriteString("当前完整 plan：暂无。\n")
-		return sb.String()
-	}
-
-	sb.WriteString("当前完整 plan：\n")
-	for i, step := range state.PlanSteps {
-		sb.WriteString(fmt.Sprintf("%d. %s\n", i+1, strings.TrimSpace(step.Content)))
-		if strings.TrimSpace(step.DoneWhen) != "" {
-			sb.WriteString(fmt.Sprintf("   完成判定：%s\n", strings.TrimSpace(step.DoneWhen)))
-		}
-	}
-
-	if step, ok := state.CurrentPlanStep(); ok {
-		sb.WriteString(fmt.Sprintf("当前步骤进度：%d/%d\n", current, total))
-		sb.WriteString("当前步骤内容：\n")
-		sb.WriteString(strings.TrimSpace(step.Content))
-		sb.WriteString("\n")
-		if strings.TrimSpace(step.DoneWhen) != "" {
-			sb.WriteString("当前步骤完成判定：\n")
-			sb.WriteString(strings.TrimSpace(step.DoneWhen))
-			sb.WriteString("\n")
-		}
 	} else {
-		sb.WriteString("当前步骤进度：暂时无有效当前步骤。\n")
+		sb.WriteString("当前完整 plan：\n")
+		for i, step := range state.PlanSteps {
+			sb.WriteString(fmt.Sprintf("%d. %s\n", i+1, strings.TrimSpace(step.Content)))
+			if strings.TrimSpace(step.DoneWhen) != "" {
+				sb.WriteString(fmt.Sprintf("   完成判定：%s\n", strings.TrimSpace(step.DoneWhen)))
+			}
+		}
+
+		if step, ok := state.CurrentPlanStep(); ok {
+			sb.WriteString(fmt.Sprintf("当前步骤进度：%d/%d\n", current, total))
+			sb.WriteString("当前步骤内容：\n")
+			sb.WriteString(strings.TrimSpace(step.Content))
+			sb.WriteString("\n")
+			if strings.TrimSpace(step.DoneWhen) != "" {
+				sb.WriteString("当前步骤完成判定：\n")
+				sb.WriteString(strings.TrimSpace(step.DoneWhen))
+				sb.WriteString("\n")
+			}
+		} else {
+			sb.WriteString("当前步骤进度：暂时无有效当前步骤。\n")
+		}
+	}
+
+	// 渲染任务类约束元数据（如有），帮助 LLM 了解排程范围和策略，避免追问已有信息。
+	if len(state.TaskClasses) > 0 {
+		sb.WriteString("\n本次排课涉及的任务类约束：\n")
+		for _, tc := range state.TaskClasses {
+			line := fmt.Sprintf("- [ID=%d] %s：策略=%s，总时段预算=%d", tc.ID, tc.Name, tc.Strategy, tc.TotalSlots)
+			if tc.StartDate != "" || tc.EndDate != "" {
+				line += fmt.Sprintf("，日期范围=%s ~ %s", tc.StartDate, tc.EndDate)
+			}
+			if tc.AllowFillerCourse {
+				line += "，允许嵌入水课"
+			}
+			if len(tc.ExcludedSlots) > 0 {
+				line += fmt.Sprintf("，排除时段=%v", tc.ExcludedSlots)
+			}
+			sb.WriteString(line + "\n")
+		}
 	}

 	return sb.String()
--- a/backend/newAgent/prompt/chat.go
+++ b/backend/newAgent/prompt/chat.go
@@ -1,63 +1,122 @@
 package newagentprompt

 import (
+	"fmt"
 	"strings"

 	newagentmodel "github.com/LoveLosita/smartflow/backend/newAgent/model"
 	"github.com/cloudwego/eino/schema"
 )

-const chatIntentSystemPrompt = `
-你是 SmartFlow 的意图分类器。
-你的唯一任务是判断用户本轮输入是"纯闲聊"还是"包含任务意图"。
+const chatRoutingSystemPrompt = `
+你是 SmartFlow 的智能路由器。你的职责是判断用户意图的复杂度，并决定后续处理路径。

-判断规则：
-1. chat：打招呼、感谢、简单问答、情感表达、闲聊，不涉及任何具体任务或操作请求。
-2. task：包含任何需要规划/执行/操作的意图，包括但不限于查询信息、创建内容、修改数据、安排日程、继续已有任务等。
+你会看到：
+- 历史对话
+- 用户本轮输入
+- 当前可用工具摘要（如有）
+- 本次排课涉及的任务类约束（如有）

-保守原则：当不确定时，倾向于判断为 task，宁可多走一次规划也不要丢失用户意图。
+请遵守以下规则：
+1. 只输出严格 JSON，不要输出 markdown，不要输出额外解释。
+2. 根据用户意图判断复杂度并选择路由。
+3. speak 字段始终填写：给用户看的话。

-严格输出以下 JSON（不要输出 markdown，不要在 JSON 外补文字）：
-{"intent":"chat或task","reply":"仅当intent=chat时填写你的闲聊回复，task时留空","reason":"简短判断依据"}
+路由规则：
+- direct_reply：纯闲聊、简单问答、打招呼、感谢等。speak 直接写你的完整回复。
+- execute：需要用工具处理的请求（查询日程、移动课程、排课等），但不需要先制定计划。speak 写简短确认。
+- deep_answer：复杂问题但不需要工具（如分析建议、深度解释等），需要深度思考后直接回答。speak 写过渡语（如"让我想想"）。
+- plan：用户明确要求先制定计划，或涉及多阶段复杂规划。speak 写确认语。
+
+粗排判断：当用户意图包含"批量安排/排课/把任务类排进日程"，且上下文中有任务类 ID 时，设置 needs_rough_build=true。
+
+输出协议（严格 JSON）：
+{"route":"direct_reply / execute / deep_answer / plan","speak":"给用户看的话","needs_rough_build":false,"reason":"简短判断依据"}
+
+合法示例：
+
+{"route":"direct_reply","speak":"你好！我是 SmartFlow 助手，有什么可以帮你的？","reason":"用户打招呼"}
+
+{"route":"execute","speak":"好的，我来帮你看看今天的安排。","reason":"需要调用工具查询日程","needs_rough_build":false}
+
+{"route":"execute","speak":"好的，我来帮你排课。","reason":"批量排课需求，有任务类 ID","needs_rough_build":true}
+
+{"route":"deep_answer","speak":"这是个好问题，让我仔细想想。","reason":"需要深度分析但不需要工具"}
+
+{"route":"plan","speak":"明白，我来帮你制定一个完整的学习计划。","reason":"用户明确要求制定计划"}
 `

-// BuildChatIntentSystemPrompt 返回意图分类系统提示词。
-func BuildChatIntentSystemPrompt() string {
-	return strings.TrimSpace(chatIntentSystemPrompt)
+// BuildChatRoutingSystemPrompt 返回路由阶段的系统提示词。
+func BuildChatRoutingSystemPrompt() string {
+	return strings.TrimSpace(chatRoutingSystemPrompt)
 }

-// BuildChatIntentMessages 组装意图分类的 messages。
-//
-// 职责边界：
-// 1. 只取最近 6 条历史，保证分类高效；
-// 2. 不注入 pinned blocks / tool schemas，分类不需要这些信息；
-// 3. 不负责解析模型输出。
-func BuildChatIntentMessages(conversationContext *newagentmodel.ConversationContext, userInput string) []*schema.Message {
-	messages := make([]*schema.Message, 0, 8)
+// BuildChatRoutingMessages 组装路由阶段的 messages。
+func BuildChatRoutingMessages(ctx *newagentmodel.ConversationContext, userInput string, state *newagentmodel.CommonState) []*schema.Message {
+	return buildStageMessages(
+		BuildChatRoutingSystemPrompt(),
+		ctx,
+		BuildChatRoutingUserPrompt(ctx, userInput, state),
+	)
+}

-	messages = append(messages, schema.SystemMessage(BuildChatIntentSystemPrompt()))
+// BuildChatRoutingUserPrompt 构造路由阶段的用户提示词。
+func BuildChatRoutingUserPrompt(ctx *newagentmodel.ConversationContext, userInput string, state *newagentmodel.CommonState) string {
+	var sb strings.Builder

-	if conversationContext != nil {
-		history := conversationContext.HistorySnapshot()
-		if len(history) > 6 {
-			history = history[len(history)-6:]
+	sb.WriteString("请判断用户本轮意图的复杂度，并选择最合适的路由。\n")
+
+	// 注入任务类上下文（供粗排判断参考）。
+	if state != nil && len(state.TaskClassIDs) > 0 {
+		parts := make([]string, len(state.TaskClassIDs))
+		for i, id := range state.TaskClassIDs {
+			parts[i] = fmt.Sprintf("%d", id)
 		}
-		if len(history) > 0 {
-			messages = append(messages, history...)
+		sb.WriteString(fmt.Sprintf("\n本次请求涉及的任务类 ID：[%s]\n", strings.Join(parts, ", ")))
+	}
+
+	if state != nil && len(state.TaskClasses) > 0 {
+		sb.WriteString("任务类约束：\n")
+		for _, tc := range state.TaskClasses {
+			line := fmt.Sprintf("- [ID=%d] %s：策略=%s，总时段预算=%d", tc.ID, tc.Name, tc.Strategy, tc.TotalSlots)
+			if tc.StartDate != "" || tc.EndDate != "" {
+				line += fmt.Sprintf("，日期范围=%s ~ %s", tc.StartDate, tc.EndDate)
+			}
+			sb.WriteString(line + "\n")
 		}
 	}

-	// 只在 history 末尾还没有当前用户消息时才追加，
-	// 避免与 loadConversationContext 的预追加产生重复。
 	trimmedInput := strings.TrimSpace(userInput)
 	if trimmedInput != "" {
-		alreadyLast := len(messages) > 0 &&
-			messages[len(messages)-1].Role == schema.User &&
-			messages[len(messages)-1].Content == trimmedInput
-		if !alreadyLast {
-			messages = append(messages, schema.UserMessage(trimmedInput))
-		}
+		sb.WriteString("\n用户本轮输入：\n")
+		sb.WriteString(trimmedInput)
+		sb.WriteString("\n")
 	}

-	return messages
+	return strings.TrimSpace(sb.String())
+}
+
+// --- 深度回答 prompt ---
+
+const deepAnswerSystemPrompt = `
+你是 SmartFlow 的深度分析助手。用户提出了一个需要深入思考的问题，请认真分析后给出详细、有价值的回答。
+
+请遵守以下规则：
+1. 充分利用上下文中已有的信息（任务类约束、日程数据、历史对话等）。
+2. 如果缺少关键信息，在回答中说明需要哪些额外信息。
+3. 直接输出你的回答，不要输出 JSON。
+`
+
+// BuildDeepAnswerSystemPrompt 返回深度回答阶段的系统提示词。
+func BuildDeepAnswerSystemPrompt() string {
+	return strings.TrimSpace(deepAnswerSystemPrompt)
+}
+
+// BuildDeepAnswerMessages 组装深度回答阶段的 messages。
+func BuildDeepAnswerMessages(ctx *newagentmodel.ConversationContext, userInput string) []*schema.Message {
+	return buildStageMessages(
+		BuildDeepAnswerSystemPrompt(),
+		ctx,
+		userInput,
+	)
 }
--- a/backend/newAgent/prompt/execute.go
+++ b/backend/newAgent/prompt/execute.go
@@ -8,9 +8,9 @@ import (
 	"github.com/cloudwego/eino/schema"
 )

-const executeSystemPrompt = `
+const executeSystemPromptWithPlan = `
 你是 SmartFlow NewAgent 的执行器。
-你的职责是在“当前 plan 步骤”的约束下，进行思考、执行、观察，再决定下一步动作。
+你的职责是在"当前 plan 步骤"的约束下，进行思考、执行、观察，再决定下一步动作。

 请遵守以下规则：
 1. 只围绕当前步骤行动，不要擅自跳到其他 plan 步骤。
@@ -19,7 +19,7 @@ const executeSystemPrompt = `
 4. 只有当你确认整个任务已经完成时，才输出 action=done，且必须在 goal_check 中总结整体完成证据。
 5. 如果执行当前步骤缺少关键上下文，且无法通过已有历史或工具补齐，输出 action=ask_user。
 6. 不要伪造工具结果；如果尚未真正拿到观察结果，就不要假装已经完成。
-7. goal_check 是你输出 next_plan / done 时的强制字段，禁止为空；必须显式地逐条对照 done_when，说明”哪些条件已满足、依据是什么”。
+7. goal_check 是你输出 next_plan / done 时的强制字段，禁止为空；必须显式地逐条对照 done_when，说明"哪些条件已满足、依据是什么"。

 你会看到：
 - 当前完整 plan
@@ -28,15 +28,43 @@ const executeSystemPrompt = `
 - 工具摘要
 - 历史对话与历史观察

-请把注意力聚焦在”当前步骤是否完成，以及下一步最合理的执行动作”上。
+请把注意力聚焦在"当前步骤是否完成，以及下一步最合理的执行动作"上。
+`
+
+const executeSystemPromptReAct = `
+你是 SmartFlow NewAgent 的执行器，当前为自由执行模式（无预定义计划步骤）。
+你需要根据用户意图，自主决定使用哪些工具来完成任务。
+
+请遵守以下规则：
+1. 每轮先分析当前情况，决定下一步动作。
+2. 只输出严格 JSON，不要输出 markdown，不要输出额外解释，不要在 JSON 外再补文字。
+3. 需要查询数据 → 输出 action=continue 并附带 tool_call。
+4. 需要修改数据（写操作）→ 输出 action=confirm 并附带 tool_call，等待用户确认。
+5. 缺少关键信息且无法通过工具补齐 → 输出 action=ask_user。
+6. 任务完成 → 输出 action=done，并在 goal_check 中总结完成证据。
+7. 不要伪造工具结果；如果尚未真正拿到观察结果，就不要假装已经完成。
+8. 尽量高效：能用一次工具调用完成的，不要分多轮。
+
+你会看到：
+- 用户原始请求
+- 置顶上下文块（粗排结果等）
+- 工具摘要
+- 历史对话与历史观察
+
+请直接行动，不要犹豫，不要重复已经做过的操作。
 `

 // BuildExecuteSystemPrompt 返回执行阶段系统提示词。
 func BuildExecuteSystemPrompt() string {
-	return strings.TrimSpace(executeSystemPrompt)
+	return strings.TrimSpace(executeSystemPromptWithPlan)
 }

-// BuildExecuteDecisionContractText 返回执行阶段的输出协议说明。
+// BuildExecuteReActSystemPrompt 返回纯 ReAct 模式的系统提示词。
+func BuildExecuteReActSystemPrompt() string {
+	return strings.TrimSpace(executeSystemPromptReAct)
+}
+
+// BuildExecuteDecisionContractText 返回执行阶段的输出协议说明（有 plan 模式）。
 func BuildExecuteDecisionContractText() string {
 	return strings.TrimSpace(fmt.Sprintf(`
 输出协议（严格 JSON）：
@@ -86,16 +114,76 @@ func BuildExecuteDecisionContractText() string {
 	))
 }

+// BuildExecuteReActContractText 返回纯 ReAct 模式的输出协议说明。
+func BuildExecuteReActContractText() string {
+	return strings.TrimSpace(fmt.Sprintf(`
+输出协议（严格 JSON）：
+- speak：给用户看的话（可以是分析结果、中间进展、或最终回复）
+- action：只能是 %s / %s / %s / %s
+- reason：给后端和日志看的简短说明
+- goal_check：输出 %s 时必填，总结任务完成证据
+- tool_call：输出 %s 时可附带写工具意图（需 confirm），输出 %s 时可附带读工具调用
+- tool_call 格式：{"name": "工具名", "arguments": {...}}
+
+合法示例：
+{
+  "speak": "我来查一下今天的安排。",
+  "action": "%s",
+  "reason": "需要调用 get_overview 查询",
+  "tool_call": {
+    "name": "get_overview",
+    "arguments": {}
+  }
+}
+
+{
+  "speak": "已将概率论移到周三第1-2节。",
+  "action": "%s",
+  "reason": "用户要求移动课程，写操作需确认",
+  "tool_call": {
+    "name": "move",
+    "arguments": {"task_state_id": 5, "target_day": 3, "target_slot_start": 1, "target_slot_end": 2}
+  }
+}
+
+{
+  "speak": "今天共3节课，分别是...",
+  "action": "%s",
+  "reason": "查询完成，已回答用户",
+  "goal_check": "已通过 get_overview 查到今天的课程并展示给用户"
+}
+`,
+		newagentmodel.ExecuteActionContinue,
+		newagentmodel.ExecuteActionAskUser,
+		newagentmodel.ExecuteActionConfirm,
+		newagentmodel.ExecuteActionDone,
+		newagentmodel.ExecuteActionDone,
+		newagentmodel.ExecuteActionConfirm,
+		newagentmodel.ExecuteActionContinue,
+		newagentmodel.ExecuteActionContinue,
+		newagentmodel.ExecuteActionConfirm,
+		newagentmodel.ExecuteActionDone,
+	))
+}
+
 // BuildExecuteMessages 组装执行阶段的 messages。
 func BuildExecuteMessages(state *newagentmodel.CommonState, ctx *newagentmodel.ConversationContext) []*schema.Message {
+	if state != nil && state.HasPlan() {
+		return buildStageMessages(
+			BuildExecuteSystemPrompt(),
+			ctx,
+			BuildExecuteUserPrompt(state),
+		)
+	}
+	// 无 plan：纯 ReAct 模式。
 	return buildStageMessages(
-		BuildExecuteSystemPrompt(),
+		BuildExecuteReActSystemPrompt(),
 		ctx,
-		BuildExecuteUserPrompt(state),
+		BuildExecuteReActUserPrompt(state),
 	)
 }

-// BuildExecuteUserPrompt 构造执行阶段的用户提示词。
+// BuildExecuteUserPrompt 构造有 plan 模式的用户提示词。
 func BuildExecuteUserPrompt(state *newagentmodel.CommonState) string {
 	var sb strings.Builder

@@ -132,3 +220,24 @@ func BuildExecuteUserPrompt(state *newagentmodel.CommonState) string {

 	return strings.TrimSpace(sb.String())
 }
+
+// BuildExecuteReActUserPrompt 构造纯 ReAct 模式的用户提示词。
+func BuildExecuteReActUserPrompt(state *newagentmodel.CommonState) string {
+	var sb strings.Builder
+
+	sb.WriteString("当前为自由执行模式，无预定义计划步骤。\n")
+	sb.WriteString("请根据用户意图直接使用工具完成请求。\n\n")
+
+	sb.WriteString(renderStateSummary(state))
+	sb.WriteString("\n\n")
+
+	sb.WriteString("判断规则：\n")
+	sb.WriteString("- 需要查询/读取数据 → action=continue + tool_call（读工具）\n")
+	sb.WriteString("- 需要修改/写入数据 → action=confirm + tool_call（写工具，需用户确认）\n")
+	sb.WriteString("- 缺少关键信息 → action=ask_user\n")
+	sb.WriteString("- 任务完成 → action=done + goal_check\n\n")
+
+	sb.WriteString(BuildExecuteReActContractText())
+
+	return strings.TrimSpace(sb.String())
+}
--- a/backend/newAgent/prompt/plan.go
+++ b/backend/newAgent/prompt/plan.go
@@ -2,6 +2,7 @@ package newagentprompt

 import (
 	"fmt"
+	"strconv"
 	"strings"

 	newagentmodel "github.com/LoveLosita/smartflow/backend/newAgent/model"
@@ -21,6 +22,14 @@ const planSystemPrompt = `
 6. 只输出 JSON，不要输出 markdown，不要输出额外解释，不要在 JSON 外再补文字。
 7. 每次输出前先评估任务复杂度：simple（简单明确，无复杂依赖）、moderate（多步操作，需要一定推理）、complex（需要深度推理、多方案比较或复杂依赖关系）。
 8. 根据复杂度判断 need_thinking：你是否需要深度思考才能生成高质量计划？当不确定时倾向于 false。
+9. 粗排识别规则：若满足以下两个条件，在 action=plan_done 时附加 needs_rough_build=true 和 task_class_ids：
+   条件1：用户输入中存在"任务类 ID"字段（见上下文"任务类 ID"部分）；
+   条件2：用户意图明确是"批量安排/帮我排课/把任务类排进日程"等批量调度需求。
+   满足时：后端会在用户确认计划后自动运行粗排算法（硬性约束已由算法保证，无需 LLM 校验）。
+   你的 plan_steps 应聚焦于"用读写工具优化方案"，建议两步：
+   第1步：用 get_overview / find_free 等读工具审视粗排结果，找出可优化的点（时段分布不均、空位未利用等）；
+   第2步：用 move / batch_move 等写工具微调后，将最终方案展示给用户确认。
+   禁止安排任何"校验/验证约束"步骤——硬性约束由算法兜底，LLM 不需要操心。

 你会看到：
 - 当前阶段与轮次信息
@@ -63,6 +72,15 @@ func BuildPlanUserPrompt(state *newagentmodel.CommonState, userInput string) str
 	sb.WriteString(BuildPlanDecisionContractText())
 	sb.WriteString("\n")

+	if state != nil && len(state.TaskClassIDs) > 0 {
+		parts := make([]string, len(state.TaskClassIDs))
+		for i, id := range state.TaskClassIDs {
+			parts[i] = strconv.Itoa(id)
+		}
+		sb.WriteString(fmt.Sprintf("\n本次排课请求涉及的任务类 ID（前端传入）：[%s]\n", strings.Join(parts, ", ")))
+		sb.WriteString("规划时请结合上述任务类 ID 判断是否需要粗排（needs_rough_build），并在 plan_steps 中体现排课意图。\n")
+	}
+
 	trimmedInput := strings.TrimSpace(userInput)
 	if trimmedInput != "" {
 		sb.WriteString("\n用户本轮输入：\n")
@@ -84,39 +102,41 @@ func BuildPlanDecisionContractText() string {
 - need_thinking：是否需要深度思考才能生成高质量计划，只能是 true / false
 - plan_steps：仅当 action=%s 时允许返回；返回时必须是完整计划，不是增量
 - plan_steps[].content：步骤正文，必填
- plan_steps[].done_when：可选，建议写”什么情况下算这一步做完”
+- plan_steps[].done_when：可选，建议写"什么情况下算这一步做完"
+- needs_rough_build：仅当满足粗排识别规则时为 true，否则省略；为 true 时后端自动运行粗排算法
+- task_class_ids：needs_rough_build=true 时必填，从上下文"任务类 ID"字段读取

 合法示例：
 {
-  “speak”: “我先把计划再收束一下。”,
-  “action”: “%s”,
-  “reason”: “当前信息已足够继续规划”,
-  “complexity”: “moderate”,
-  “need_thinking”: false
+  "speak": "我先把计划再收束一下。",
+  "action": "%s",
+  "reason": "当前信息已足够继续规划",
+  "complexity": "moderate",
+  "need_thinking": false
 }

 {
-  “speak”: “你更希望我优先安排今天，还是按整周来规划？”,
-  “action”: “%s”,
-  “reason”: “当前时间范围仍不明确”,
-  “complexity”: “simple”,
-  “need_thinking”: false
+  "speak": "你更希望我优先安排今天，还是按整周来规划？",
+  "action": "%s",
+  "reason": "当前时间范围仍不明确",
+  "complexity": "simple",
+  "need_thinking": false
 }

 {
-  “speak”: “计划已经整理好了，我先给你确认一下。”,
-  “action”: “%s”,
-  “reason”: “当前计划已具备执行条件”,
-  “complexity”: “simple”,
-  “need_thinking”: false,
-  “plan_steps”: [
+  "speak": "计划已经整理好了，我先给你确认一下。",
+  "action": "%s",
+  "reason": "当前计划已具备执行条件",
+  "complexity": "simple",
+  "need_thinking": false,
+  "plan_steps": [
    {
-      “content”: “先确认本周可用时间范围”,
-      “done_when”: “拿到明确的可用时间段列表”
+      "content": "先确认本周可用时间范围",
+      "done_when": "拿到明确的可用时间段列表"
    },
    {
-      “content”: “基于可用时间生成执行安排”,
-      “done_when”: “得到一份用户可确认的安排方案”
+      "content": "基于可用时间生成执行安排",
+      "done_when": "得到一份用户可确认的安排方案"
    }
  ]
 }