diff --git a/docs/智能排程四步走实施方案.md b/docs/智能排程四步走实施方案.md new file mode 100644 index 0000000..4fa36f7 --- /dev/null +++ b/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:全链路可观测(成功率、重试率、采纳率、成本)。 +