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

## 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：全链路可观测（成功率、重试率、采纳率、成本）。

