smartmate/docs/backend/主动优化整套改造计划.md

主动优化整套改造计划

1. 文档目的

本文档只回答一件事：这轮主动优化链路改完之后，整体会如何工作。

重点不放在实现细节，而放在以下 4 个问题：

1. 哪些能力保留，哪些能力直接删除。
2. task_class、粗排、主动优化三者之间的职责如何重新划分。
3. 首次排程时，agent 的完整执行链路会变成什么样。
4. 时间窗口过紧时，agent 应该如何自动放宽要求，避免陷入无意义重试。

---

2. 改造后的核心原则

2.1 LLM 只负责“语义认知优化”

这轮改造后的总原则是：

1. 确定性算法负责“排得下、排得合法、排得别太离谱”。
2. LLM 负责“学起来舒不舒服、搭配顺不顺、是否符合用户偏好”。

换句话说，LLM 不再负责：

1. 全局负载均衡。
2. 均匀铺开任务。
3. 追逐空窗、碎片率、最大 gap 之类的统计指标。
4. 为了把报表修漂亮而反复搬运任务。

LLM 保留的价值只有两类：

1. 学科语义理解。
2. 基于语义和偏好的认知微调。

2.2 主动优化从“统计修表”改成“认知微调”

改造完成后，主动优化不再问：

1. 哪天更满。
2. 哪天更空。
3. 哪门课间隔是不是又多了 1 天。
4. 空窗碎片率是不是还可以再低一点。

改造完成后，主动优化只问：

1. 这一天切换是不是太碎。
2. 两门课放在一起，认知上是不是太累。
3. 连续学习块是不是太长。
4. 当前安排是不是违背了用户偏好。
5. 在当前时间窗口下，这个问题是不是值得继续修。

---

3. 工具去留

3.1 保留

3.1.1 analyze_health

保留，且继续作为主动优化的唯一总入口。

新职责：

1. 汇总当前排程在认知节奏上的主要问题。
2. 汇总当前排程和用户偏好的冲突。
3. 判断当前是否还有足够可调整空间继续优化。
4. 判断当前是否已经可以合理收口。

3.1.2 analyze_rhythm

保留，作为 analyze_health 的下钻工具。

新职责：

1. 解释某一天为什么学起来别扭。
2. 解释某几个任务为什么不适合连在一起。
3. 解释当前切换多、连续块长、高强度相邻等问题落在哪些具体任务上。

3.1.3 现有点查工具

全部保留，尤其是：

1. query_range
2. query_target_tasks
3. query_available_slots
4. get_task_info

原因很简单：

1. health/rhythm 只负责指出问题和方向。
2. LLM 真正落到“挪哪个任务、往哪里挪”时，仍然必须依赖这些点查工具。

3.1.4 现有写工具

全部保留。

主动优化改的是“如何观察和决策”，不是“如何写入”。

但写工具在主动优化里的使用优先级要重排：

1. slack 高时，允许 move 和 swap 一起参与小范围微调。
2. slack 低时，默认优先考虑 swap，不优先考虑 move。
3. slack 低时若使用 swap，只允许交换属于不同 task_class 的任务。
4. 这样做的目的不是保守，而是用“跨类互换”天然保证类内顺序不被破坏。

---

3.2 删除

3.2.1 删除 analyze_load

原因：

1. 负载均衡是确定性算法的职责。
2. 它会强烈诱导 LLM 变成搬格子苦力。
3. 它无法体现 LLM 真正有优势的学科语义判断。

3.2.2 删除 analyze_tolerance

原因：

1. 容错本质上是粗排风格与窗口宽松度问题。
2. 它不适合作为主动优化主链路的独立分析工具。
3. 它容易继续把模型引向“留空窗/修空窗”的伪目标。

3.2.3 删除所有 gap/load/tolerance 驱动指标

以下指标全部退出主动优化链路：

1. max_gap
2. avg_gap
3. gap_std_dev
4. fragmentation_rate
5. avg_gap_size
6. max_gap_size
7. days_without_buffer
8. utilization_rate
9. load_std_dev
10. load_range
11. budget_progress
12. days_to_end

说明：

1. 它们可以在未来作为统计观察数据重建。
2. 但本轮改造后，它们不再参与主动优化决策，不再生成 issue，不再生成 next action。

---

4. task_class 改造后会怎样

4.1 新增 3 个语义字段

每个 task_class 新增以下字段：

1. subject_type
2. difficulty_level
3. cognitive_intensity

这 3 个字段只服务于一个目标：让后续排程和主动优化不再对着学科名裸猜。

4.2 写入时机

这 3 个字段不在排程时临时生成，而是在创建或更新 task_class 时就提前写好。

也就是说：

1. 用户创建任务类。
2. LLM 在任务类阶段补全这 3 个字段。
3. 任务类一旦落库，后续粗排和主动优化都直接读取。

兜底策略：

1. 老数据如果没有这 3 个字段，排程时允许临时现判一次。
2. 现判完成后，应补写回 task_class，避免下次重复猜。

4.3 这 3 个字段后续如何被使用

粗排阶段：

1. 可以作为轻量参考，但不是主驱动。

主动优化阶段：

1. analyze_health 直接消费这 3 个字段。
2. analyze_rhythm 直接消费这 3 个字段。
3. LLM 在诊断“背靠背是否太累、连续块是否太长、某种切换是否合理”时，统一以这 3 个字段为事实基础。

---

5. 粗排算法改造后会怎样

5.1 粗排负责的事

改造后，粗排要提前吃掉原本不该交给 LLM 的工作。

粗排的职责固定为：

1. 保证可行。
2. 保证顺序合法。
3. 保证基础分布别太离谱。
4. 保证不要明显堆到少数几天。
5. 保证不要把整段窗口排成毫无操作空间的死局。

5.2 粗排不负责的事

粗排不追求：

1. 认知体验最优。
2. 学科搭配最优。
3. 用户偏好最优。

这些交给 LLM 后续做 1 到 2 轮小范围微调。

5.3 粗排后的预期结果

粗排完成后，产物应该是：

1. 一个合法可执行的初稿。
2. 一个从统计上看不难看，但未必最舒服的日程。
3. 一个仍然留有少量可调整空间的底盘。

也就是说，粗排之后不需要“完美”，只需要“足够好，值得微调”。

---

6. analyze_health 改造后会怎样

6.1 定位

analyze_health 变成“认知健康总览”。

它不再是统计体检工具，而是 execute 阶段判断“要不要继续动、该往哪种认知方向动”的入口。

6.2 新职责

改造后它只看三件事：

1. 当前认知节奏是否别扭。
2. 当前安排是否违背用户偏好。
3. 当前窗口是否还允许继续优化。

6.3 新输出口径

它输出的问题应该是这种风格：

1. 某天高强度切换过多。
2. 两门高强度课背靠背。
3. 某天连续高强度学习块过长。
4. 当前安排违背“早上别排硬课”之类的用户偏好。
5. 当前可调整空间过低，剩余问题属于必要妥协。

它不再输出这种风格：

1. 哪天负载更满。
2. 最大空窗还有几天。
3. 空窗碎片率还可以再压多少。
4. 某一科是不是再均匀一点更漂亮。

6.4 新 can_close 含义

改造后，can_close 的语义要收紧为：

1. 当前没有明显值得继续修的认知问题。
2. 当前没有明显违背用户偏好的安排。
3. 或者虽然还存在小问题，但当前 slack 已低，继续优化收益不高。

也就是说，can_close 不再由统计指标主导，而由“是否还有高价值认知问题”主导。

---

7. analyze_rhythm 改造后会怎样

7.1 定位

analyze_rhythm 变成 analyze_health 的明细镜。

只有当 health 发现某类认知问题值得继续查时，才进一步调用 rhythm。

7.2 新职责

它要回答的不是“排得均不均”，而是：

1. 哪一天切换太碎。
2. 哪一段连续块太长。
3. 哪几个任务挨在一起会特别累。
4. 哪些切换虽然换科了，但其实仍属于同一种脑力模式。

7.3 新输出风格

它的输出重点应围绕：

1. 日内切换次数。
2. 连续学习块结构。
3. 高强度相邻关系。
4. 同类/异类学科切换关系。
5. 某一天内部的认知压力分布。

它不再承担：

1. 跨天 gap 追踪。
2. 学科分散度统计优化。
3. 预算推进告警。

---

8. 新增 slack 后会怎样

8.1 为什么必须加 slack

有些用户给的时间窗口非常紧。

这时“高强度背靠背”不一定是错误，而可能是当前窗口下的必要代价。

如果没有 slack 概念，agent 会误以为：

1. 这是可修的问题。
2. 我应该继续搬。
3. 继续搬总能更好。

然后就进入无意义重试。

8.2 slack 的职责

slack 不负责决定“舒服不舒服”，只负责决定“还有没有优化余地”。

也就是说，它是健康分析里的第二层判断：

1. 有问题，不代表值得继续修。
2. 值得继续修，还要看当前有没有空间修。

8.3 slack 接入后的行为

改造后：

1. 若 slack 高，按正常标准检查认知问题。
2. 若 slack 中，允许小问题存在，但仍可做 1 次小范围微调。
3. 若 slack 低，自动放宽要求，允许必要的背靠背、较长连续块、略多切换。
4. 若 slack 低但仍存在明显可改善的认知问题，优先尝试一次低成本 swap，而不是优先尝试 move。
5. 这个 swap 必须限定为“只交换不同 task_class 的任务”，从而避免打乱任一类内部顺序。
6. 若一次 swap 后没有明显改善，则倾向收口，不进入连续搬运。

8.4 slack 带来的收口变化

改造后，agent 不会再因为下面这类场景反复挣扎：

1. 时间太紧，不得不连着上两门硬课。
2. 可动任务几乎都被前驱后继夹死。
3. 当前再动只会拆东墙补西墙。

这时 analyze_health 应直接给出结论：

1. 当前仍有认知妥协点。
2. 但由于可调整空间有限，已属于合理结果。
3. 可以收口，或只在用户明确要求时继续深挖。

---

9. 改造后的首次排程完整链路

这是你最关心的部分：改完以后，首次排程到底怎么跑。

9.1 第 0 步：任务类先带语义字段

在真正排程前，相关 task_class 已经具备：

1. subject_type
2. difficulty_level
3. cognitive_intensity

如果缺失，先补齐再进入完整主动优化链路。

9.2 第 1 步：确定性粗排先出底盘

系统先用确定性算法完成一版粗排。

这一步的结果要求是：

1. 可排下。
2. 顺序合法。
3. 分布不难看。
4. 还留有一点可调整空间。

9.3 第 2 步：进入 analyze_health

粗排完成后，不再先看 load，不再先看 gap，而是直接进入 analyze_health。

这一步会判断：

1. 当前有哪些高价值认知问题。
2. 当前是否存在用户偏好冲突。
3. 当前 slack 高不高。
4. 当前是否值得继续动。

9.4 第 3 步：必要时下钻 analyze_rhythm

只有当 health 发现值得修的问题时，LLM 才进一步调用 analyze_rhythm。

这一步的作用是：

1. 把问题定位到某一天、某几个任务、某种相邻关系。
2. 给 LLM 读写工具调用提供更明确的认知方向。

9.5 第 4 步：LLM 用旧点查工具锁定目标

接下来 LLM 不会根据 health/rhythm 直接拍脑袋写入。

它仍然要走：

1. query_range
2. query_target_tasks
3. query_available_slots
4. get_task_info

也就是说，新的分析工具负责“告诉它为什么动、朝哪动”，旧点查工具负责“告诉它具体怎么动”。

当 slack 低时，这一步的目标还会进一步收窄为：

1. 先找有没有值得做的一次性交换机会。
2. 优先找跨 task_class 的互换对象。
3. 只有在没有合适 swap，且单步 move 的收益明显高于风险时，才考虑 move。

9.6 第 5 步：LLM 做 1 到 2 次小范围微调

改造后，主动优化默认只做小范围微调，不做全盘翻修。

默认目标是：

1. 消除最明显的认知别扭点。
2. 避免新问题比旧问题更重。
3. 不为了报表漂亮而继续搬运。

这里再补一条强规则：

1. slack 高时，可以正常比较 move 与 swap。
2. slack 低时，优先考虑一次跨 task_class 的 swap 来调整不同科目间的相对顺序。
3. slack 低时，不鼓励进入多步 move 链路。
4. swap 的价值在于：它更像“整理现有坑位里的学科顺序”，而不是“重新开一轮搬家”。

9.7 第 6 步：再做一次 analyze_health

写操作后再次进入 analyze_health。

这一步不是看统计报表有没有更均匀，而是看：

1. 主要认知问题是否缓解。
2. 用户偏好冲突是否减少。
3. 当前 slack 是否已不支持继续动。
4. 是否可以收口。

9.8 第 7 步：合理收口

最终存在三种收口方式：

1. 问题已明显改善，可以正常收口。
2. 还存在小问题，但 slack 过低，按“合理妥协”收口。
3. 用户明确还不满意，再继续下一轮。

其中第 2 种收口还要补一层判断：

1. 不是一看到 slack 低就立刻停手。
2. 而是先看是否存在一次低成本、跨 task_class 的 swap 机会。
3. 若存在且收益明确，可先做这一次整理式调整。
4. 若不存在，或做完后仍无明显改善，再按“合理妥协”收口。

---

10. 改造后的局部调整链路

改造后，不是所有用户请求都要走完整主动优化链路。

10.1 默认仍走旧链路

用户如果只是说：

1. 把这个任务挪一下。
2. 这节课换一天。
3. 给我把这个排到周末。

这类请求默认继续走旧点查 + 旧写工具链路。

原因：

1. 这是局部执行问题。
2. 不值得每次都拉起 health/rhythm 做一轮体检。

10.2 只有两类情况再启动主动优化分析

1. 首次排程。
2. 用户明确表达认知感受或结构性问题。

例如：

1. “切换太多了，心累。”
2. “这些硬课连着看着就难受。”
3. “帮我整体调顺一点。”

---

11. 改造后的最终表现

改完以后，这条链路的预期表现应该是：

1. 用户创建任务类时，学科语义先被沉淀下来。
2. 粗排算法先给出一个合法且分布不难看的初稿。
3. 主动优化不再围着负载、空窗、gap 打转。
4. analyze_health 只关心认知体验、偏好冲突、可调整空间。
5. analyze_rhythm 只负责解释具体哪段学起来别扭。
6. LLM 只做 1 到 2 次高价值认知微调，不再做长链路苦力搬运。
7. 时间窗口很紧时，agent 会承认“这是必要妥协”，而不是继续死磕。

一句话总结：

改造后，这套链路不再追求“把报表修漂亮”，而是追求“把这份日程修得更像人能学下去”。

---

12. 实施顺序

按以下顺序落地：

1. 先改 task_class，补 3 个语义字段及写入链路。
2. 再删 analyze_load、analyze_tolerance 及相关主链路接入。
3. 再重写 analyze_health 的职责、指标和收口口径。
4. 再重写 analyze_rhythm 的职责和输出结构。
5. 再补 slack 及其自动放宽规则。
6. 最后改 execute prompt 和链路收口逻辑。

这样做的原因是：

1. 先有语义数据，分析工具才不至于空转。
2. 先把旧统计驱动砍掉，execute 才不会继续被错误方向牵着跑。
3. 最后再调 prompt，才不会变成给旧结构打补丁。

---

13. 本轮验收口径

如果改造成功，至少应满足以下表现：

1. 首次排程时，agent 不再为了负载均匀或空窗漂亮反复搬任务。
2. 日志中的主动优化理由，主要变成认知体验和偏好，而不是统计指标。
3. 当时间很紧时，agent 会主动接受必要妥协，不再死循环。
4. 当用户只是提局部挪动需求时，不会动辄拉起全局体检。
5. 主动优化完成后的结果，解释口径更像“为什么这样学更顺”，而不是“哪些数字变好看了”。