smartmate/docs/backend/智能排程四步走实施方案.md

智能排程四步走实施方案（实施稿）

1. 文档目标

• 目标 1：给出 SmartFlow 智能排程 Agent 的分阶段落地路径，确保功能可持续上线，而不是一次性大改。
• 目标 2：在保证项目推进速度的前提下，提升系统“可解释性、可回滚性、可复用性”，同时增强项目叙事深度。
• 目标 3：明确每一阶段的输入输出、复用点、验收标准、风险与回滚策略。

2. 当前项目可复用资产盘点

• 已有粗排能力：ScheduleService.SmartPlanning + logic.SmartPlanningMainLogic，可直接作为“候选方案生成器”。
• 已有强校验+事务落库能力：TaskClassService.BatchApplyPlans，可直接作为“最终落地执行器”。
• 已有单条插入与冲突检查能力：TaskClassService.AddTaskClassItemIntoSchedule，可作为局部修补路径。
• 已有 Agent 分流和 Graph 基建：route / quicknote / taskquery，可以按同样范式扩展 scheduleplan。
• 已有流式输出链路：可继续使用阶段推送 + OpenAI 兼容流，不破坏现有客户端协议。

3. 总体架构（目标态）

• 分层思路：路由层（识别意图） -> 规划层（生成/调整排程计划） -> 执行层（校验+落库） -> 反馈层（解释结果与下一步建议）。
• 核心原则：
  • 原则 1：模型负责“提议”，后端负责“裁决”（硬校验）。
  • 原则 2：所有写库动作都走既有服务层，不在 Agent 内直接拼 SQL。
  • 原则 3：每个阶段都可独立开关，支持灰度和快速回滚。

---

4. 四步走实施计划

阶段 1：基于现成任务类的粗排 + ReAct 调优 + 连续对话微调

4.1 阶段目标

• 用户已存在任务类时，支持一轮“粗排 -> 校验 -> 自动修补重试 -> 最终落库”。
• 支持连续对话微调（例如“我早八不想学习”）并在已有方案基础上局部调整。

4.2 关键实现

• 新增路由动作：schedule_plan_create、schedule_plan_adjust。
• 新增 backend/agent/scheduleplan 包，建议结构：
  • graph.go：只做节点连线与分支。
  • state.go：保存计划状态、重试计数、错误上下文、版本号。
  • tool.go：封装服务调用工具（粗排、批量应用、局部修补）。
  • nodes.go：节点逻辑（plan/materialize/apply/reflect/finalize）。
  • prompt.go：统一管理系统提示词和结构化输出约束。
• 执行链路建议：
  • plan：产出结构化“排程意图与约束”。
  • preview：调用粗排服务生成候选。
  • materialize：把候选转换为 BatchApplyPlans 可落库结构。
  • apply：调用 BatchApplyPlans。
  • reflect：若失败，把后端错误喂给模型生成修补方案，最多重试 2 次。
  • finalize：输出结果摘要并持久化对话。

4.3 连续对话微调机制

• 设计 PlanSession + PlanVersion：
  • PlanSession：同一轮长期规划会话 ID。
  • PlanVersion：每次调整生成新版本，支持回滚。
• 微调原则：
  • 用户约束变更（如不学早八）只触发受影响槽位重排，不重建全量任务类。
  • 保留“上版方案 + 本次 diff”，方便解释“为什么这样改”。

4.4 验收标准

• 指标 1：排程请求成功率 >= 95%（含自动重试后）。
• 指标 2：平均重试次数 <= 1.2。
• 指标 3：连续对话微调后，最终落库成功率 >= 95%。

4.5 风险与回滚

• 风险：模型给出的方案结构不稳定。
• 应对：严格 JSON Schema 校验，失败直接走默认修补/人工规则。
• 回滚：关闭 ENABLE_SCHEDULE_PLAN_AGENT，回退到原接口链路。

4.6 总流程规划

任务目标：实现一个基于 ReAct 范式的智能排程微调引擎，将“粗排结果”与“既有日程”混合，并通过 AI 进行语义化优化。
1.需要新建的前置函数：
(1)HybridScheduleWithPlan：从数据库中提取和排程时间范围相同的日程，放在sv/schedules.go里面，通过回调来作为一个节点然后调用(如果你有更好的结构建议，欢迎告诉我)
2.需要新建的tool(直接改State)：
(1)Swap:LLM传入带交换两个任务的相对时间(从json中获取，第x周第x-x节)，这个工具会自动寻找并交换时间(通过修改Schedule结构体内部数据实现的)，找不到就报错。
(2)Move:同上，传入一个任务的相对时间(第x周第x-x节)，直接寻找并修改State中的Schedule中的时间。
注意，上述(1)和(2)都必须带合法性检验。
(3)timeAvailable:检测目标时间在当前日程中是否可用，用于服务(2)。
(4)GetAvailableSlots:反馈给AI(json格式)可用时间的列表，用于让AI选择挪动过去的时间。
3.基本流程如下：
(1)获取用户智能排程意图，提取task_class_id，调用SmartPlanning进行粗排，然后再通过上面的前置函数(1)将日程和已经安排好的任务混合，并传入State。
(2)LLM启动深度思考(必须开深度思考)，告诉它上述工具及其作用，让它自由选择调用。prompt你自己写，差不多就是：
考虑不同科目的"上下文切换成本"，某科目更加适合学习的时间段以及人一天的学习效率曲线等因素，修改上述json中status为suggested且type为task的任务，最终形成无论从复习效果，还是学习体感上来看都十分科学合理的学习方案。
(3)此时，模型开启深度思考，推送reasoning stream到前端，和既定的状态chunk穿插。
(4)在思考中，模型一次看好改动逻辑(这就是为啥要开深度思考的原因，逻辑有点绕)，然后思考结束，出结果后一次性调用这些tool。
注意，这里有备选方案，如果模型逻辑不够，那就一次只调一次tool，多调用几次llm，这样用时间换正确率。
(4.1)若调用成功，则直接返回排程结果到前端(禁止落库，用户得看效果再决定是否正式落库，而正式落库用不着agent)
(4.2)若失败，则把失败原因返回LLM，LLM再看情况自己思考并重试。

---

阶段 2：从“我想复习概率论”自动生成任务类，并接入阶段 1

5.1 阶段目标

• 用户只给学习目标（如“我想复习概率论”）时，系统自动生成任务类（章节/题型/轮次/估算工作量），并直接进入阶段 1 的排程链路。

5.2 关键实现

• 新增“任务类规划节点（TaskClass Planner）”：
  • 输入：目标、时间范围、偏好、当前课程负载。
  • 输出：UserAddTaskClassRequest 兼容结构。
• 采用“单次聚合生成 + 后端硬校验”：
  • 模型一次输出任务类结构（减少往返延迟）。
  • 后端用现有 AddOrUpdateTaskClass 做合法性校验与写库。
• 打通链路：
  • Goal -> TaskClass -> SmartPlanning -> BatchApplyPlans。

5.3 验收标准

• 指标 1：任务类自动生成可落库率 >= 90%。
• 指标 2：生成后进入排程全链路成功率 >= 85%。
• 指标 3：任务项粒度可读性（人工抽检）合格率 >= 90%。

5.4 风险与回滚

• 风险：生成任务过粗/过细，导致排程质量差。
• 应对：加入任务项数量上下限、单项时长约束、自动裁剪规则。
• 回滚：关闭 ENABLE_AUTO_TASKCLASS_FROM_GOAL，保留手动任务类模式。

---

阶段 3：引入 Milvus RAG（时间管理知识）并提炼短规则注入排程上下文

6.1 阶段目标

• 将“时间管理方法论”转化为可检索规则，提升排程质量和解释性。

6.2 知识库策略（建议）

• 不直接喂整本书原文，改为“方法卡片库”：
  • 字段建议：rule_id、title、principle、适用场景、反例、执行建议、source。
• 流程建议：
  • 原始文章入库 -> 向量化 -> 检索 TopK -> LLM 提炼“短规则集” -> 注入排程 Planner 提示词。
• 规则注入方式：
  • 注入结构化规则对象，不只注入自由文本，避免提示词漂移。

6.3 验收标准

• 指标 1：RAG 命中率（有有效规则输出）>= 80%。
• 指标 2：用户二次修改率相比阶段 2 下降 >= 15%。
• 指标 3：排程解释中可引用规则比例 >= 90%。

6.4 风险与回滚

• 风险：检索噪声导致排程变差。
• 应对：规则打分阈值、低分规则不注入、A/B 对比评估。
• 回滚：关闭 ENABLE_RAG_SCHEDULE_RULES，继续使用纯模型规划。

---

阶段 4：引入 WebSearch + 记忆系统（长期偏好）

7.1 阶段目标

• 在本地知识不足时用 WebSearch 补充最新学习建议；同时沉淀用户长期偏好，实现更个性化排程。

7.2 WebSearch 触发策略

• 仅在以下情况触发：
  • 本地 RAG 低置信/无结果；
  • 用户明确要求“最新资料/趋势/考试变化”。
• 结果处理：
  • 抓取 -> 摘要 -> 可信度过滤 -> 形成规则候选，再注入 Planner。

7.3 记忆系统设计

• 记忆分层：
  • 长期稳定偏好：早八不学、每日最大学习时长、偏好学习时段。
  • 短期上下文偏好：本次会话临时约束。
• 写入策略：
  • 只有“高置信 + 用户确认”才写长期记忆。
  • 可撤销、可查看、可重置。

7.4 验收标准

• 指标 1：偏好命中后用户手动改计划次数下降 >= 20%。
• 指标 2：WebSearch 触发请求中有效增益比例 >= 60%。
• 指标 3：记忆误写率（用户否认）<= 5%。

7.5 风险与回滚

• 风险：外部信息质量不稳定、记忆污染。
• 应对：来源白名单、置信度阈值、显式确认机制。
• 回滚：分别关闭 ENABLE_WEBSEARCH、ENABLE_USER_MEMORY。

---

8. 工程深度增强建议（可选但推荐）

• 建议 1：引入“排程模拟器（Dry Run）”，先算冲突与可行性评分，再决定是否落库。
• 建议 2：建立“离线评测集”（固定 50~100 条真实场景）做回归评测，避免模型升级导致排程退化。
• 建议 3：把反思失败样本沉淀为“错误词典 + 修复策略库”，提升下一轮成功率。
• 建议 4：增加成本与耗时预算控制（每请求最多模型调用次数、超时兜底回复）。
• 建议 5：在日志中记录“规则来源、模型决策、后端裁决结果”，形成可审计链路。

9. 里程碑建议（可按周）

• 里程碑 1（第 1~2 周）：完成阶段 1，打通粗排+重试+连续微调。
• 里程碑 2（第 3~4 周）：完成阶段 2，打通目标到任务类自动生成。
• 里程碑 3（第 5~6 周）：完成阶段 3，接入 Milvus RAG 规则注入。
• 里程碑 4（第 7~8 周）：完成阶段 4，接入 WebSearch 与记忆系统。

10. 面试叙事建议（附加价值）

• 叙事主线：从“规则系统”升级为“可解释、可进化、可回滚”的 Agent 排程平台。
• 技术亮点：
  • 亮点 1：模型提议 + 后端裁决的双层安全架构。
  • 亮点 2：连续对话下的增量重排与版本管理。
  • 亮点 3：RAG 规则注入和记忆系统带来的个性化规划。
  • 亮点 4：全链路可观测（成功率、重试率、采纳率、成本）。