smartmate/docs/功能决策记录/智能排程ReAct精排引擎_决策记录.md

智能排程 Agent — ReAct 精排引擎 决策记录（2026-03-21 更新版）

0. 文档说明（先看这里）

• 本文档分为两部分：
  1. 上半部分：当前线上代码对应的“最终链路决策”（2026-03-21 版本）。
  2. 下半部分：2026-03-19 的原始决策内容，原样保留作为发展历程。
• 这样做的目的：
  1. 评审时先看“现在系统到底怎么跑”；
  2. 复盘时还能追踪“从旧方案到现方案”的演进路径。

1. 基本信息（当前版本）

• 记录编号：FDR-008B
• 功能名称：智能排程 ReAct 精排引擎（阶段 2：多任务类分流 + 日级并发 + 周级并发单步优化 + 双通道交付）
• 记录日期：2026-03-21
• 决策状态：已采纳，已落地
• 负责人：SmartFlow 团队
• 关联需求：FDR-008（初版）、FDR-007（智能排程 Agent 阶段 1）

2. 本轮最终决策（A->B 最终态）

2.1 决策摘要

• 决策 1：智能排程入口继续走统一 Agent 分流（action=schedule_plan），不新增独立聊天接口。
• 决策 2：图内分流改为“按 task_class_ids 长度”：
  1. len(task_class_ids) == 1：跳过 daily_split/daily_refine/merge，直接周级优化；
  2. len(task_class_ids) >= 2：先日级并发优化，再周级并发优化。
• 决策 3：周级优化改为“单步动作模式”（每轮只允许 1 个 Move/Swap 或 done）。
• 决策 4：周级预算改为“双预算 + 每有效周保底 + 负载加权”：
  1. 总预算：成功/失败都扣；
  2. 有效预算：仅成功动作扣；
  3. 每个有效周至少 1 个总预算和 1 个有效预算；
  4. 额外预算按周负载加权分配。
• 决策 5：输出采用双通道：
  1. SSE 主通道仅返回终审自然语言（FinalSummary）；
  2. 结构化 candidate_plans 走 /api/v1/agent/schedule-preview 查询（Redis 快照）。

2.2 为什么这样改

• 目标 1：把“单任务类”和“多任务类混排”拆开治理，减少无效模型调用。
• 目标 2：把周级优化从“模型大段犹豫”改成“走一步看一步”，缩短长尾。
• 目标 3：前端同时拿到“可读结论”和“结构化预览”，避免 SSE 里吐 JSON 影响体验。
• 目标 4：预算治理可解释，避免某些有效周被分配为 0 导致“看起来没优化”。

3. 当前全链路（代码真实流程）

3.1 Agent 总分流（与 schedule_plan 的关系）

1. POST /api/v1/agent/chat 进入 AgentService.AgentChat。
2. 先做会话存在性检查（Redis -> DB -> 必要时创建）。
3. 调 route.DecideActionRouting 获取 action。
4. 若 RouteFailed=true：直接返回内部错误（不再回落聊天）。
5. 若 action=schedule_plan：进入 runSchedulePlanFlow。
6. 若 runSchedulePlanFlow 报错：当前策略是记录日志 + 发 fallback 阶段块 + 回退普通聊天（可用性优先）。

3.2 schedule_plan 图编排（当前版本）

flowchart TD
    START([START]) --> plan["plan<br/>提取意图/约束/strategy/task_class_ids/task_tags"]
    plan --> p1{"FinalSummary 非空<br/>或 task_class_ids 为空?"}
    p1 -- "是" --> exit["exit -> END"]
    p1 -- "否" --> rough["rough_build<br/>HybridScheduleWithPlanMulti<br/>+ 可选 ResolvePlanningWindow"]

    rough --> p2{"构建失败或 HybridEntries 为空?"}
    p2 -- "是" --> exit
    p2 -- "否" --> p3{"len(task_class_ids) >= 2 ?"}

    p3 -- "是" --> split["daily_split<br/>按天拆组 + ContextTag 注入 + SkipRefine 标记"]
    split --> drefine["daily_refine(并发)<br/>单天 ReAct，失败回退原天"]
    drefine --> merge["merge<br/>合并结果，冲突回退"]
    merge --> wrefine["weekly_refine(并发按周)<br/>单步 Move/Swap + 双预算"]

    p3 -- "否" --> wrefine
    wrefine --> final["final_check<br/>物理校验 + 总结生成"]
    final --> preview["return_preview<br/>回填 AllocatedItems + 产出 CandidatePlans"]
    preview --> END([END])

4. 节点级职责边界（当前实现）

4.1 plan

1. 先合并 extra.task_class_ids（显式参数优先）；
2. 再用模型抽取 intent/constraints/strategy/task_tags；
3. 模型失败但有 task_class_ids 时，使用参数兜底继续；
4. 最终仍无任务类时，写入 FinalSummary 并提前退出。

4.2 rough_build

1. 调 HybridScheduleWithPlanMulti 统一构建混合条目（existing + suggested）；
2. 生成 CandidatePlans（预览结构）；
3. 可选解析全局窗口边界（PlanStartWeek/Day ~ PlanEndWeek/Day），供周级 Move 硬校验；
4. 失败时写 FinalSummary 并提前退出。

4.3 daily_split

1. 按 (week, day) 拆成 DayGroup；
2. 按 task_item_id -> tag 注入 ContextTag；
3. suggested <= 2 标记 SkipRefine=true，减少低收益模型调用。

4.4 daily_refine（并发）

1. 按天并发执行单天 ReAct；
2. 单天失败只回退该天，不拖垮全局；
3. 发“day_start/day_done”阶段块，并携带进度；
4. Thinking 默认关闭（降低并发阶段长尾）。

4.5 merge

1. 合并 DailyResults；
2. 做冲突校验（同一 (week,day,section) 不能被阻塞条目重复占用）；
3. 有冲突则整体回退到 merge 前快照；
4. 产出 MergeSnapshot，供 final_check 二次回退。

4.6 weekly_refine（并发按周 + 单步动作）

1. 先按周拆数据，仅对“有 suggested 的周”分配预算；
2. 强制每个有效周至少 1 总预算 + 1 有效预算；
3. 剩余预算按周负载加权分配；
4. 单周 worker 循环：
   1. 每轮仅 1 个工具调用（Move/Swap）或 done；
   2. 总预算：调用即扣；
   3. 有效预算：成功才扣；
   4. Move 必须留在 worker 当前周，且受全局窗口 day 边界约束；
   5. 工具结果回灌到下一轮上下文，形成“走一步看一步”。

4.7 final_check

1. 物理校验三项：
   1. 时间冲突；
   2. 节次越界；
   3. suggested 数量与 AllocatedItems 数量一致性。
2. 校验失败时回退 MergeSnapshot；
3. 再由模型生成 2-3 句最终总结（thinking 关闭）。

4.8 return_preview

1. 把 HybridEntries 中 suggested 的最终位置回填到 AllocatedItems；
2. 转换为 CandidatePlans；
3. 若 FinalSummary 为空则兜底填充；
4. 仅返回预览，不直接落库。

5. 工具与约束（当前版本）

5.1 工具集合

1. Swap：交换两个 suggested 任务时间；
2. Move：移动一个 suggested 任务到新时间；
3. TimeAvailable：检查时间段可用性；
4. GetAvailableSlots：列出可用槽位。

5.2 周级单步模式硬约束

1. 仅允许 Move/Swap；
2. 不允许跨 worker 周移动；
3. 若启用全局窗口，Move 必须落在窗口允许的 day 区间；
4. 失败返回工具失败结果，不抛异常中断整周。

6. 输出协议与接口契约（当前版本）

6.1 SSE 主通道

1. 阶段块（伪装 reasoning chunk）用于进度反馈；
2. 最终正文为 FinalSummary（不再吐 JSON）；
3. 结束块遵循 OpenAI 兼容流式格式。

6.2 结构化预览通道

1. 排程结束后把快照写 Redis（user_id + conversation_id 作用域）；
2. 查询接口：GET /api/v1/agent/schedule-preview?conversation_id=...；
3. 未命中返回业务错误码（预览不存在/过期）；
4. 写预览失败只记日志，不阻塞聊天主链路。

7. 失败策略与回退策略（当前版本）

1. 路由控制码失败：直接报内部错误（不回落 chat）。
2. schedule_plan 分支内部失败：上层当前策略仍回落普通聊天（可用性优先）。
3. daily 单天失败：回退该天原方案。
4. merge 冲突：回退 merge 前快照。
5. final_check 失败：回退 MergeSnapshot。
6. 预览缓存写失败：仅影响结构化查询，不影响 SSE 文本回复。

8. 影响范围（当前版本）

8.1 主要模块

1. backend/agent/scheduleplan/*（图编排、日级并发、周级并发、工具、预算、终审）
2. backend/service/agentsvc/agent_schedule_plan.go（服务层接入 graph）
3. backend/service/agentsvc/agent_schedule_preview.go（预览缓存读写）
4. backend/dao/agent-cache.go（预览 Redis DAO）
5. backend/api/agent.go + backend/routers/routers.go（预览查询接口）
6. backend/agent/route/route.go（统一 action 分流）

8.2 数据与存储

1. 主排程流程不直接写最终排程库；
2. 新增 Redis 预览快照读写；
3. 聊天消息仍走统一后置持久化（Redis + outbox/DB）。

9. 验证与回滚（当前版本）

9.1 验证要点

1. task_class_ids=1 时应跳过日级并发，直接周级优化；
2. task_class_ids>=2 时应进入日级并发 + merge + 周级并发；
3. SSE 正文应是自然语言，不应出现粗排 JSON；
4. /agent/schedule-preview 能按 conversation_id 读到 candidate_plans；
5. 预算日志应能解释每周预算分配和消耗。

9.2 回滚策略

1. 软回滚：关闭 schedule_plan 路由命中（临时回落聊天解释）；
2. 逻辑回滚：周级并发退回单线程或关掉 daily_refine；
3. 通道回滚：保留 SSE 文本，临时下线 schedule-preview 查询。

---

附录 A：2026-03-19 原始内容（原文保留，作为发展历程）

智能排程 Agent — ReAct 精排引擎 决策记录

1. 基本信息

• 记录编号：FDR-008
• 功能名称：智能排程 ReAct 精排引擎（阶段 1.5：粗排 + AI 语义化微调）
• 记录日期：2026-03-19
• 决策状态：已采纳，开发中
• 负责人：SmartFlow 团队
• 关联需求：FDR-007（智能排程 Agent 阶段 1）

2. 背景与问题

• 业务背景：阶段 1 已打通"意图识别 → 粗排 → 落库"全链路，但粗排算法是纯规则的线性分配（cursor-based），不考虑科目特性、学习效率曲线、上下文切换成本等语义因素。
• 现状问题：
  1. 粗排结果机械化：高认知负荷科目可能被安排在低效时段（如晚间安排数学）；
  2. 缺乏科目间协调：同类任务可能被分散到不连贯的时间段，增加上下文切换成本；
  3. 用户无法感知 AI 的"思考过程"，排程结果缺乏可解释性。
• 不做此决策的后果：排程质量停留在"能用但不好用"阶段，无法体现 AI 的语义理解能力。

3. 决策目标

• 目标 1：在粗排之后引入 LLM 精排环节，通过 ReAct 范式对任务时间进行语义化优化。
• 目标 2：精排过程中 LLM 的深度思考（reasoning）实时流式推送到前端，用户可见。
• 目标 3：精排结果仅作为预览返回，不自动落库，用户确认后再持久化。
• 目标 4：向后兼容——未注入精排依赖时自动走原有 materialize 路径。
• 非目标：
  • 本阶段不做用户确认后的落库链路（后续阶段）；
  • 本阶段不做 RAG 规则注入（阶段 3）；
  • 本阶段不做多方案对比（只输出一个优化后的方案）。

4. 备选方案

方案 A：后处理脚本（规则引擎）

• 描述：在粗排之后用硬编码规则（如"数学只排上午"）做二次调整。
• 优点：确定性强，无 LLM 调用开销。
• 缺点：规则维护成本高，无法处理复杂的多科目协调；不可解释。
• 复杂度 / 成本：低，但扩展性极差。

方案 B：ReAct 范式 + 手动 Tool 调用（采纳）

• 描述：LLM 开启深度思考，分析粗排结果后通过 Tool（Swap/Move/TimeAvailable/GetAvailableSlots）在内存中调整任务时间，多轮循环直到满意。
• 优点：
  1. 充分利用 LLM 的语义理解能力，优化维度丰富；
  2. reasoning_content 实时推送，用户可见思考过程；
  3. Tool 操作内存数据，天然支持预览模式（不落库）；
  4. 手动 ReAct 循环给予完全的流式控制权。
• 缺点：依赖 LLM 输出质量；深度思考模式耗时较长。
• 复杂度 / 成本：中高，约 1 周。

方案 C：Eino 内置 ToolsNode

• 描述：使用 Eino 框架的 ToolsNode + function_calling 原生能力。
• 优点：框架原生支持，代码量少。
• 缺点：无法在 Tool 执行过程中流式推送 reasoning_content；无法精细控制每轮 SSE 输出；项目中无现有 function_calling 基础设施。
• 复杂度 / 成本：中，但灵活性不足。

5. 最终决策

• 采纳方案：方案 B（ReAct 范式 + 手动 Tool 调用）
• 关键理由：
  1. 手动 ReAct 循环可以精确控制 SSE 流式输出（reasoning + stage + tool_call 穿插）；
  2. Tool 操作纯内存数据，预览模式零风险；
  3. 与现有 graph 架构无缝集成（新增 3 个节点，不破坏原有链路）。

6. 技术方案

6.1 新流程（graph 结构）

plan → preview(粗排) → hybridBuild(混合日程) → reactRefine(ReAct循环) → returnPreview → END

智能排程仅返回预览结果，不自动落库。用户确认后由前端调用独立落库接口完成持久化。

6.1.1 整体 Graph 流程图

下图展示完整的 SchedulePlanGraph 编排结构（ReAct 精排路径）。

flowchart TD
    START([START]) --> plan["plan<br/>意图识别 + 约束提取<br/><i>callScheduleModelForJSON</i>"]

    plan --> plan_br{{"FinalSummary 非空<br/>或 TaskClassID ≤ 0 ?"}}
    plan_br -- 是 --> exit_a["exit → END<br/><i>提前终止</i>"]
    plan_br -- 否 --> preview["preview<br/>调用粗排算法<br/><i>SmartPlanningRaw</i>"]

    preview --> pv_br{{"preview 结果？"}}
    pv_br -- "失败 / 无候选" --> exit_b["exit → END"]
    pv_br -- "成功" --> hybridBuild["hybridBuild<br/>构建混合日程<br/><i>existing + suggested</i>"]

    hybridBuild --> hb_br{{"HybridEntries 非空？"}}
    hb_br -- 空 --> exit_c["exit → END"]
    hb_br -- 非空 --> reactRefine["reactRefine<br/>ReAct 精排循环<br/><i>最多 3 轮 × 5min/轮</i>"]
    reactRefine --> returnPreview["returnPreview<br/>HybridEntries → 预览格式<br/><i>不落库，等用户确认</i>"]
    returnPreview --> END_A([END])

    %% ═══ 样式 ═══
    style reactRefine fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style hybridBuild fill:#e8f5e9,stroke:#2e7d32
    style returnPreview fill:#e8f5e9,stroke:#2e7d32

6.1.2 ReAct 精排内部循环

下图展开 reactRefine 节点内部的 ReAct 循环逻辑（react.go）。 每轮独立设置 5 分钟超时（reactRoundTimeout），reasoning_content 实时推送到 SSE。

flowchart TD
    enter([进入 reactRefine]) --> init["构造初始 messages<br/>system: ReAct 优化 prompt<br/>user: 混合日程 JSON + 约束"]

    init --> round_gate{{"ReactRound < ReactMaxRound (3) ?"}}

    round_gate -- 否 --> max_round["标记完成<br/>'已达最大轮次，使用当前结果'"]
    max_round --> to_return([退出 → returnPreview])

    round_gate -- 是 --> inc["ReactRound++<br/>创建 roundCtx<br/><i>context.WithTimeout(ctx, 5min)</i>"]

    inc --> stream["chatModel.Stream(roundCtx, messages)<br/><i>ThinkingTypeEnabled</i>"]

    stream --> recv_loop["循环 reader.Recv()"]
    recv_loop --> has_reasoning{{"有 reasoning_content ?"}}
    has_reasoning -- 是 --> push_sse["推送到 outChan<br/><i>前端实时可见思考过程</i>"]
    push_sse --> has_content
    has_reasoning -- 否 --> has_content{{"有 content ?"}}
    has_content -- 是 --> acc["累积到 contentBuilder"]
    acc --> recv_more{{"EOF ?"}}
    has_content -- 否 --> recv_more
    recv_more -- 否 --> recv_loop
    recv_more -- 是 --> parse

    stream -- "超时 / 错误" --> timeout["ReactDone = true<br/>'模型调用超时或失败，<br/>使用粗排结果'"]
    timeout --> to_return

    parse["解析 LLM JSON 输出<br/><i>parseReactLLMOutput</i>"]
    parse --> parse_br{{"解析结果？"}}

    parse_br -- 解析失败 --> parse_fail["ReactDone = true<br/>'LLM 输出格式异常'"]
    parse_fail --> to_return

    parse_br -- "done: true" --> done["ReactDone = true<br/>ReactSummary = summary"]
    done --> to_return

    parse_br -- "无 tool_calls<br/>且 done ≠ true" --> auto_done["ReactDone = true<br/>'排程优化已完成'"]
    auto_done --> to_return

    parse_br -- "有 tool_calls" --> dispatch["依次分发 Tool 调用<br/><i>dispatchReactTool</i>"]

    dispatch --> tools["执行工具（纯内存操作）<br/>Swap ─ 交换两个 suggested 时间<br/>Move ─ 移动到新时间段<br/>TimeAvailable ─ 查询是否空闲<br/>GetAvailableSlots ─ 列出可用槽"]

    tools --> append["messages += assistant 输出<br/>messages += tool 结果（user msg）"]
    append --> round_gate

    %% ═══ 样式 ═══
    style stream fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    style dispatch fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style tools fill:#e8f5e9,stroke:#2e7d32
    style push_sse fill:#fce4ec,stroke:#c62828
    style timeout fill:#ffebee,stroke:#b71c1c

6.2 混合日程（HybridScheduleEntry）

将既有日程（existing）和粗排建议（suggested）统一到同一结构：

• existing + course/task：不可移动
• suggested + task：LLM 可通过 Tool 调整

6.3 ReAct Tool 设计

Tool	功能	操作对象
Swap	交换两个 suggested 任务的时间	内存 HybridEntries
Move	移动一个 suggested 任务到新时间	内存 HybridEntries
TimeAvailable	检查目标时间是否可用	只读查询
GetAvailableSlots	返回可用时间段列表	只读查询

6.4 SSE 推送设计

• schedule_plan.hybrid.building/done — 混合日程构建阶段
• schedule_plan.react.round — 第 N 轮优化开始
• reasoning_content 流式 chunk — LLM 深度思考过程（实时推送）
• schedule_plan.react.tool_call — Tool 执行结果
• schedule_plan.react.done — 优化完成
• schedule_plan.preview_return.done — 预览生成完成

7. 影响范围

• 新增文件：
  • backend/agent/scheduleplan/tools_react.go：4 个 Tool + dispatcher + LLM 输出解析
  • backend/agent/scheduleplan/react.go：ReAct 循环核心 + 流式推送
• 修改文件：
  • backend/model/schedule.go：+HybridScheduleEntry
  • backend/agent/scheduleplan/state.go：+ReAct 字段
  • backend/agent/scheduleplan/prompt.go：+ReAct system prompt
  • backend/agent/scheduleplan/nodes.go：+hybridBuild/returnPreview 节点
  • backend/agent/scheduleplan/runner.go：+outChan/modelName/新节点适配
  • backend/agent/scheduleplan/graph.go：+3 节点/重新连线
  • backend/agent/scheduleplan/tool.go：+HybridScheduleWithPlan 依赖
  • backend/service/schedule.go：+HybridScheduleWithPlan 方法
  • backend/service/agent_bridge.go：+注入新依赖
  • backend/service/agentsvc/agent.go：+字段/传参
  • backend/service/agentsvc/agent_schedule_plan.go：+outChan/modelName/新依赖
• 数据与存储影响：无。所有 Tool 操作纯内存，不涉及 DB。
• 接口 / 协议影响：无新增接口。SSE 新增 react 相关阶段推送（向下兼容）。

8. 已知问题与后续优化

8.1 深度思考超时（当前）

• 现象：模型开启深度思考后 reasoning 阶段耗时较长，当前 5 分钟超时仍可能不够。
• 影响：超时后使用粗排结果，精排未生效。
• 后续方案：
  • 调整超时策略（按模型实际耗时动态设置，或改为不设超时由父 context 控制）
  • 优化 prompt，引导模型减少冗余推理
  • 评估是否关闭深度思考，改用普通模式 + 多轮调用换取稳定性

8.2 模型输出质量

• 现象：模型思考过程较啰嗦，可能输出无效的 tool 调用。
• 后续方案：
  • 精炼 ReAct system prompt，加入 few-shot 示例
  • 对 tool_calls 做预校验，过滤明显无效的调用
  • 收集真实案例建立评测集

8.3 用户确认落库链路

• 现象：当前精排结果仅预览，用户确认后的落库链路尚未实现。
• 后续方案：
  • 新增"确认落库"接口或对话指令
  • 复用现有 materialize → apply 路径，从 HybridEntries 转换

8.4 连续对话微调

• 现象：精排后的连续对话微调（如"把数学挪到上午"）尚未与 ReAct 引擎打通。
• 后续方案：
  • 将上一轮 HybridEntries 序列化到对话历史
  • 支持增量 ReAct（只调整用户指定的部分）

9. 验证与回滚

• 验证方式：
  1. go build ./... + go vet ./... 编译通过
  2. 发送排程请求，验证 SSE 流中出现 react 阶段推送和 reasoning_content
  3. 验证不落库：数据库 schedules 表无新增记录
  4. 向后兼容：不注入 HybridScheduleWithPlan 时走原有 materialize 路径
• 回滚方案：在 agent_bridge.go 中注释掉 HybridScheduleWithPlanFunc 注入即可，preview 后自动回退到 materialize 路径。

10. 复盘结论（上线后补充）

• 实际效果：待补充
• 与预期偏差：待补充
• 后续是否需要二次决策：待补充