smartmate/docs/backend/主动优化顺序约束拆分执行计划.md

# 主动优化顺序约束拆分执行计划

## 1. 本轮目标

本轮要解决的不是单点 bug，而是一个架构错位：

1. 主动优化希望 LLM 在窗口内自主微调，围绕负载、节奏、容错做多轮观察与挪动。
2. 现有顺序保护却是“全局 suggested 基线 + 收口时自动复原”，本质是事后抢救。
3. 两者叠加后，LLM 前面刚优化完，后面又可能被 `order_guard` 否掉，甚至否不回去，只能带着异常结果交付。

因此，本轮的核心目标是：

1. 把“顺序约束”从 graph 收口节点，下沉为写工具层的前置约束。
2. 把“全局顺序冻结”改成“允许跨科目交错，但锁住同任务类内部顺序”。
3. 顺手修掉当前主动优化链路里由旧守卫带来的提示污染、卡片误导、兼容性 bug。
4. 借这次改造，把 `node/execute.go` 继续拆职责，避免后续主动优化逻辑继续堆在单文件里。

---

## 2. 当前问题诊断

### 2.1 产品语义错位

当前系统默认语义仍是：

1. `AllowReorder=false` 时，尽量保持所有 suggested 的全局相对顺序。
2. 若被打乱，则在 `order_guard` 节点尝试按 baseline 复原。

这和我们已经对齐的新产品语义冲突：

1. 用户默认不是“完全不许动顺序”。
2. 用户要的是“每门课内部别乱序，但不同课之间可以交错来换负载”。
3. 主动优化阶段的目标是优化坑位分布，不是死守粗排全局序列。

### 2.2 约束位置放错了

当前顺序保护发生在：

1. `execute` 完成后。
2. `graph/order_guard` 收口前。

这会导致三个问题：

1. 非法移动已经发生，后面只能补救。
2. 补救失败也不会阻断交付，只会吐一句“顺序异常但未复原”。
3. LLM 在执行时完全不知道哪些移动其实不该做，容易白跑。

### 2.3 约束粒度过粗

当前基线是“所有 suggested 任务的时间顺序快照”，这会把下面两类本来合理的操作也一起误伤：

1. 不同任务类之间为了均衡负载而做的交错。
2. 在不破坏科目内部先后关系的前提下做的跨天平衡。

### 2.4 当前 bug 已经暴露

从日志看，至少已有这些具体问题：

1. `order_guard` 尝试复原时出现 `slot_incompatible`。
   - 本质说明旧复原逻辑对“任务时长单位”和“坑位跨度单位”的理解并不稳。
   - 这条链本来就不该继续扩展，而该整体退场。
2. 前端会收到“已记录本轮建议任务顺序基线”“顺序异常但未执行自动复原”这类对用户价值很低的系统话术。
3. `execute` prompt 仍在强调“默认保持 suggested 相对顺序”，这会继续把模型往旧目标上拽。
4. `spread_even` / `move` / `swap` / `batch_move` 当前都不知道“同任务类兄弟节点边界”，所以无法在写入前拦住越界调整。

### 2.5 代码结构已经不适合继续堆功能

当前 `node/execute.go` 已经承载了：

1. execute 主循环。
2. 工具执行。
3. 工具结果摘要。
4. feasibility 守门。
5. task class 写入状态回盘。
6. preview 实时写。
7. 顺序相关拦截。
8. scope 解析。

这类文件继续加主动优化逻辑，后续回归会越来越难定位。

---

## 3. 目标行为

改造后的目标行为如下：

1. LLM 仍然可以主动观察、主动微调、再观察，不退化成一次性确定性求解。
2. 默认允许跨任务类交错调整。
3. 默认不允许打乱同一任务类内部的学习顺序。
4. 每次写工具调用前，后端都能判断这次移动是否越过“同任务类上一个/下一个任务”的合法边界。
5. 如果越界，工具直接返回失败原因，让 LLM 换别的任务或别的坑位，而不是先写进去、最后再抢救。
6. 交付阶段不再出现旧 `order_guard` 的提示文案，也不再依赖它去修复顺序。

一句话概括：

> 允许跨科目穿插优化，但每门课内部始终保持原有学习推进顺序。

---

## 4. 必须补齐的数据

这是本轮最关键的数据面。没有这些字段，后端没法在写工具层判断“这个任务能挪到哪”。

### 4.1 任务类内部顺序 rank

当前 `ScheduleTask` 里有：

1. `TaskClassID`
2. `SourceID`（`task_item.id`）

但没有：

1. 该 `task_item` 在所属任务类里的 `order`

这意味着后端知道“它属于哪门课”，但不知道“它是这门课里的第几个任务”。

本轮需要补：

1. 在 `schedule.ScheduleTask` 增加类似 `TaskOrder` 的运行态字段。
2. 在 `conv/schedule_state.go` 从 `model.TaskClassItem.Order` 映射进来。

### 4.2 顺序边界计算所需的同类兄弟信息

有了 `TaskClassID + TaskOrder` 后，不一定非要把前后兄弟 ID 也落进 state；两种方案都可行：

1. 轻量方案：运行时动态扫描同任务类任务，按 `TaskOrder` 算前驱/后继。
2. 预计算方案：在 state 初始化时直接建立 sibling index。

本轮建议先走轻量方案，原因：

1. 改动面更小。
2. 不引入新的状态同步负担。
3. 足够支撑写工具前置校验。

### 4.3 合法时间边界的统一定义

需要明确一个统一规则：

1. 一个任务的目标位置，必须晚于同任务类前驱任务的结束时间。
2. 必须早于同任务类后继任务的开始时间。
3. 若前驱/后继不存在，则该侧边界开放。
4. 若前驱/后继当前是 pending、未落位，则该侧边界暂不收紧。

这样 LLM 仍有自由度，但自由度被严格限制在“本任务合法活动区间”里。

---

## 5. 方案总览

### 5.1 总体策略

本轮不再沿用“先放任移动，最后 graph 收口时修”的模式，而改成：

1. 写工具调用前先验边界。
2. 合法才允许写。
3. 非法直接返回失败。
4. 收口阶段只做轻量断言，不再自动复原。

### 5.2 顺序保护新哲学

旧哲学：

1. 保护粗排全局时间序列。

新哲学：

1. 保护每个任务类内部的推进顺序。
2. 不保护不同任务类之间的相对先后。

### 5.3 对主动优化的意义

这套改法的直接意义是：

1. LLM 终于可以真的做“负载优化”而不是被全局顺序锁死。
2. LLM 即使选错目标，也会在写工具层收到具体失败原因。
3. 失败原因足够明确时，模型下一步就知道该换任务、换天、还是换工具。

---

## 6. 具体拆分与改动计划

## 6.1 第一步：给 ScheduleState 补顺序语义

涉及文件：

1. `backend/newAgent/tools/schedule/state.go`
2. `backend/newAgent/conv/schedule_state.go`

计划动作：

1. 在 `ScheduleTask` 增加任务类内部顺序字段。
   - 建议名：`TaskOrder int`
2. 仅 `source=task_item` 时填充该字段。
3. 从 `model.TaskClassItem.Order` 注入运行态。
4. 对缺失 order 的历史数据做兜底。
   - 优先使用数据库 order。
   - 若为空，则按 `TaskClass.Items` 当前顺序补稳定序号。

验收结果：

1. 每个 `task_item` 在工具层都能知道自己是所属任务类里的第几项。
2. 查询工具输出里不一定要暴露这个字段给 LLM，但后端必须可用。

## 6.2 第二步：新增“局部顺序约束”公共层

涉及文件：

1. 新增 `backend/newAgent/tools/schedule/order_constraints.go`
2. 复用 `backend/newAgent/tools/schedule/write_helpers.go`

计划动作：

1. 抽一个独立公共层，不把顺序判断散落在每个写工具里重复写。
2. 公共层职责只做一件事：判断某个任务能否落到某个目标时段。
3. 需要提供的核心能力：
   - 找到同任务类前驱任务
   - 找到同任务类后继任务
   - 计算合法最早起点 / 最晚终点
   - 判断目标位置是否越界
   - 输出中文失败原因

建议返回信息：

1. `ok=true/false`
2. 失败原因中文摘要
3. 命中的前驱/后继任务是谁
4. 合法范围描述

这样后面各写工具都能直接复用，不再复制逻辑。

## 6.3 第三步：把约束前置到基础写工具

涉及文件：

1. `backend/newAgent/tools/schedule/write_tools.go`

计划动作：

1. `move` 接入局部顺序约束。
2. `swap` 在交换前对双方交换后的目标位置分别校验。
3. `batch_move` 在克隆态上统一校验整批目标是否都满足局部顺序约束。
4. `place` 也要接入。
   - 因为被 `unplace` 后再次放回，仍然可能破坏同类顺序。
5. `unplace` 暂时不做顺序阻断。
   - 它只是把任务拿出来，不直接打乱同类内部先后。
   - 真正的顺序问题应在后续 `place/move` 时拦截。

验收目标：

1. 任一基础写工具都不能把任务挪出自己的合法兄弟区间。
2. 非法时工具直接失败，且提示能被 LLM 看懂。

## 6.4 第四步：让复合写工具也遵守边界

涉及文件：

1. `backend/newAgent/tools/schedule/compound_tools.go`

计划动作：

1. `spread_even` 生成候选位置后，回填前逐任务校验局部顺序边界。
2. 若规划器给出的结果越界，整次复合写失败并给出明确原因。
3. `min_context_switch` 继续维持 P1 不暴露。
4. 即使未来重开，也必须走同一套局部顺序约束，不允许绕过。

原因：

1. 复合工具最容易“整体看起来更均匀，但把单科内部顺序打乱”。
2. 如果只拦基础写工具，不拦复合工具，系统规则会不一致。

## 6.5 第五步：退役旧 order_guard

涉及文件：

1. `backend/newAgent/node/order_guard.go`
2. `backend/newAgent/graph/common_graph.go`
3. `backend/newAgent/model/common_state.go`
4. `backend/newAgent/node/execute.go`

计划动作：

1. 移除“全局 baseline + 收口复原”的主逻辑。
2. 删除或停用 `SuggestedOrderBaseline` 运行态。
3. 删除 `order_guard` 节点在主动优化链路中的强依赖。
4. 交付前若仍需要安全兜底，只保留一个轻量 final assert：
   - 仅检查每个任务类内部顺序是否仍合法
   - 不自动复原
   - 若非法，视为执行层 bug，直接中止交付并打日志

推荐做法：

1. P1 先彻底切掉 graph 层 `order_guard` 分支。
2. 若担心过渡期风险，再补一个极轻的校验函数在 deliver 前调用。

## 6.6 第六步：同步调整 prompt 与模型目标

涉及文件：

1. `backend/newAgent/prompt/execute_context.go`
2. `backend/newAgent/prompt/execute.go`
3. 视需要补充 `prompt/execute_rule_packs.go`

计划动作：

1. 删除“默认保持 suggested 相对顺序”的旧表述。
2. 改成新的明确描述：
   - 默认保持同任务类内部顺序
   - 允许跨任务类交错调整
   - 不得擅自突破同任务类内部先后
3. 把“非法时工具会直接失败”作为模型可感知规则写进 prompt。

这样 LLM 会更接近真实规则，不会一直沿着旧目标空转。

## 6.7 第七步：拆 execute.go 职责

涉及文件：

1. `backend/newAgent/node/execute.go`
2. 新增若干并行文件

建议拆分方向：

1. `node/execute.go`
   - 只保留主循环、决策分发、节点入口
2. `node/execute_scope_guard.go`
   - 当前步骤作用域解析与日期范围守门
3. `node/execute_tool_runtime.go`
   - `executeToolCall` / `executePendingTool` / preview 写入
4. `node/execute_tool_summary.go`
   - 工具摘要、参数摘要、结果摘要
5. `node/execute_taskclass_runtime.go`
   - task class upsert 状态回盘相关
6. `node/execute_health_runtime.go`
   - feasibility / health 快照更新

这一步的目的不是“为了好看”，而是避免后面继续把主动优化规则、task class 流程规则、工具结果摘要全塞回一个文件。

---

## 7. 本轮顺手修复的 bug 清单

## 7.1 bug A：顺序异常提示污染用户体验

现象：

1. 前端会看到“已记录本轮建议任务顺序基线”
2. 以及“检测到顺序异常，但本次未执行自动复原”

修法：

1. 随 `order_guard` 退役一起移除这两类状态文案。
2. 这类内部守卫信息不再面向用户显式展示。

## 7.2 bug B：`slot_incompatible` 兼容性问题

现象：

1. 日志里出现 `expected_duration=1 slot_duration=2`

判断：

1. 这是旧 `order_guard` 复原链上的单位不一致问题。
2. 该问题不值得单独继续修补。

修法：

1. 旧复原链退役后，这条 bug 自然消失。
2. 本轮只保留一个动作：确认写工具本身的时长计算口径仍正确。

## 7.3 bug C：prompt 仍把模型往“全局不乱序”上引

现象：

1. `execute_context` 里仍写着默认保持 suggested 相对顺序。

修法：

1. 改成“默认保持同任务类内部顺序”。

## 7.4 bug D：复合工具可能绕过新规则

现象：

1. `spread_even` 当前只校验冲突，不校验同类前后边界。

修法：

1. 接入统一局部顺序约束层。

## 7.5 bug E：active optimize 链路和 execute 文件职责缠得太紧

现象：

1. 任何主动优化 bug 都容易改进 `execute.go`，继续涨文件体积。

修法：

1. 本轮同步拆文件，至少把工具执行与摘要逻辑拆出去。

---

## 8. 实施顺序

建议按下面顺序推进，避免中途状态既不兼容旧逻辑，也没完全切到新逻辑。

### 阶段 1：补数据

1. 给 `ScheduleTask` 增加 `TaskOrder`
2. 在 state loader 中完成映射
3. 保证查询 / 粗排 / 预览链路不受影响

### 阶段 2：落局部顺序约束公共层

1. 实现前驱/后继查找
2. 实现目标落位合法性判断
3. 输出中文失败原因

### 阶段 3：接入基础写工具

1. `move`
2. `swap`
3. `batch_move`
4. `place`

### 阶段 4：接入复合写工具

1. `spread_even`
2. 保持 `min_context_switch` 继续禁用

### 阶段 5：切掉旧 order_guard

1. 删除 graph 分支
2. 删除 baseline 运行态
3. 去掉用户可见状态文案

### 阶段 6：更新 prompt

1. 改目标描述
2. 改顺序策略说明
3. 明确非法写工具会被后端拒绝

### 阶段 7：拆 execute.go

1. 先无行为变化拆文件
2. 再补必要注释与最小验证

---

## 9. 验证口径

## 9.1 正向场景

要验证这些场景能通过：

1. 同任务类内部顺序不变，但不同任务类交错后负载更均衡。
2. LLM 将某任务从第 3 天挪到第 20 天，只要仍在其前后兄弟之间，就允许。
3. `spread_even` 可以把多门课拉开，但不会把某一门课内部顺序反过来。

## 9.2 反向场景

要验证这些场景被拦住：

1. 把某门课的第 4 个任务挪到第 1 个任务前面。
2. 把某门课的中间任务挪到其后继任务之后。
3. `swap` 后导致同任务类内部出现逆序。
4. `batch_move` 中有一条越界时整批失败。

## 9.3 交付场景

要确认这些旧副作用消失：

1. 不再出现 `order_guard_initialized`
2. 不再出现 `order_guard_restore_skipped`
3. 不再依赖 `SuggestedOrderBaseline`

## 9.4 代码结构场景

要确认：

1. `execute.go` 文件职责明显变轻
2. 局部顺序约束逻辑只存在一份公共实现

---

## 10. 本轮建议的最小落地范围

如果要控制风险，本轮建议先做到这里：

1. `TaskOrder` 注入
2. 局部顺序约束公共层
3. `move/swap/batch_move/place` 接入
4. `spread_even` 接入
5. prompt 改口径
6. 切掉旧 `order_guard`
7. 拆出 `execute_tool_runtime.go` 与 `execute_tool_summary.go`

这个范围已经足够让主动优化链路从“旧哲学打架”切到“新哲学能跑”。

---

## 11. 预期收益

做完之后，预期表现会变成：

1. LLM 会更敢做真实优化，因为它不再被全局顺序锁死。
2. 后端会在写工具层直接给出“能不能这么挪”的明确反馈。
3. 同一门课的学习推进顺序能被稳定锁住。
4. 不同门课之间仍有足够空间做均衡、分散、减压。
5. 前端不会再收到旧 `order_guard` 带来的迷惑状态。
6. 后续如果继续加主动优化策略，也有更干净的承载位置，不必继续往 `execute.go` 里堆。

---

## 12. 本文档对应的实施结论

本轮建议按以下原则执行：

1. 删除“全局 suggested 顺序守卫”思路。
2. 改为“同任务类内部顺序约束前置到写工具层”。
3. 允许跨任务类交错优化。
4. 顺手清理旧 guard 带来的用户可见噪音与兼容性问题。
5. 同步拆分 execute 相关职责文件，避免继续堆史山。