Version: 0.6.7.dev.260317.doc

补传智能排程落地实施方案(初稿)

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

@@ -0,0 +1,172 @@
+# 智能排程四步走实施方案（实施稿）
+
+## 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`，回退到原接口链路。
+
+---
+
+## 阶段 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：全链路可观测（成功率、重试率、采纳率、成本）。
+