smartmate/docs/backend/第二阶段主动调度MVP实现方案.md

# 第二阶段主动调度 MVP 实现方案

## 0. Handoff 说明

本文档仍在讨论中，尚未进入代码实现阶段。接手者请优先阅读本节和第 12 / 13 节，再继续补齐未拍板问题。

当前核心共识：

1. 主动调度主链路走固定 graph / service pipeline，不进入 ReAct 工具循环。
2. 第一版触发源先做 `important_urgent_task` 与 `unfinished_feedback`。
3. task 创建 / 更新时按 `urgency_threshold_at` upsert 主动调度 job；task 完成后把 job 标记为 `canceled`。
4. schedule 动态任务默认 `assumed_completed`，只有用户明确反馈未完成才触发补救。
5. 调度触发信号需要持久化，用于幂等、审计、排障和串联 trigger -> preview -> notification -> apply。
6. task_pool 任务进入日程时不创建孤儿 task_item，而是在 `schedule_events` 上新增 `task_source_type`：
   - `task_source_type=task_item` 时，`rel_id` 指向 `task_items.id`。
   - `task_source_type=task_pool` 时，`rel_id` 指向 `tasks.id`。
7. 主动调度预览新增 `active_schedule_previews`，不塞进 `agent_schedule_states`。
8. 预览保存 `base_version + before_summary + preview_changes`，不保存全量 before 快照。
9. 第一版不做 apply 成功后的撤销按钮；apply 失败必须事务不落库并回写失败原因。
10. 用户确认入口走主动调度详情页和确认 API，不走 Agent resume；详情页采用助手卡片式体验，支持拖动 after 方案后确认。
11. 预览有效期 1 小时。
12. 未完成补救第一版只生成新补做块，不直接移动原已排任务。

当前仍需拍板的问题：

1. `schedule.apply.requested` 第一版到底如何切分同步 / 异步：
   - 已讨论倾向：确认接口同步写 Redis 状态和轻量校验；MySQL 正式写入可异步，因为重校验可能需要几百毫秒。
   - 待继续明确：是否必须通过 outbox / apply request 表保证异步 apply 请求可恢复，还是 MVP 先同步调用 service。
2. 应用幂等键：
   - 已解释：`preview_id + candidate_id` 只能定位候选；若支持拖动，实际 apply 内容可能不同。
   - 待拍板：是否使用独立 `apply_id`，并用 `idempotency_key` 绑定一次确认尝试。
3. 飞书通知：
   - 固定文案是否足够。
   - 跳转 URL 规则。
   - 通知幂等键按 `preview_id` 还是其它组合。
   - 第一版是否落 `notification_records` 表，还是先只记录日志 / outbox 状态。
4. 主动调度代码目录和迁移边界：
   - 第一版放 `backend/service/active_scheduler` 还是新建更独立的 `backend/active_scheduler`。
   - 事件契约是否提前放到 shared/events 风格目录。
5. `active_schedule_jobs / active_schedule_triggers / active_schedule_previews / apply request` 的具体表结构和状态机。
6. task_pool 任务预计节数字段是否本轮加到 `tasks`，还是 MVP 先默认 1 节并在预览中要求用户确认。

建议下一轮继续顺序：

1. 先拍板 apply 同步 / 异步和 `apply_id`。
2. 再拍板主动调度相关表结构与状态机。
3. 再拍板飞书通知最小实现。
4. 最后补详细执行计划：目录、DTO、迁移 SQL、API、worker handler、测试。

## 1. 文档目的

本文档承接《第二阶段主动调度 MVP 功能预期》和《微服务四步迁移与第二阶段并行开发计划》，用于把产品预期逐步落成可执行的工程方案。

本轮讨论采用“先业务逻辑，后执行计划”的方式推进：

1. 先按模块说明业务实现逻辑，确认这件事在产品上到底怎么流转。
2. 再列出需要拍板的问题，避免工程方案提前固化错误边界。
3. 等业务逻辑讨论完成后，再把详细执行计划、文件改动、测试方式补进对应模块。

## 2. 总体实现原则

1. 主动调度只生成诊断、候选和预览，不直接修改正式日程。
2. LLM 只在后端生成的候选里做选择，不自由构造正式写库参数。
3. 后台 worker 是主动调度主链路，API 只提供测试触发、预览查询、用户确认和正式应用入口。
4. 当前仍在 `backend` Go module 内实现，但代码边界按未来 `active-scheduler` 独立服务设计。
5. 飞书第一版只走 `notification.feishu.requested` 通知事件，不承载确认和复杂聊天。
6. 所有触发源统一进入 `active_schedule.triggered`，禁止每种触发单独写一套调度逻辑。
7. 正式应用优先复用现有 schedule / task_class service，不在主动调度模块绕过既有写入链路。

## 3. 目标链路

```text
后台定时 / 事件 / API 测试触发
  -> active_schedule.triggered
  -> 构造 ActiveScheduleContext
  -> 刷新四象限紧急性派生
  -> 读取滚动 24 小时任务与日程事实
  -> 主动观测并生成 issues / decision / candidates
  -> 写入待确认对比预览
  -> 发布 schedule.preview.generated
  -> 发布 notification.feishu.requested
  -> 用户回系统查看并按候选确认
  -> schedule.apply.requested
  -> 复用正式应用链路
  -> schedule.apply.succeeded / schedule.apply.failed
```

## 4. 模块一：触发入口与事件契约

### 4.1 业务实现逻辑简述

主动调度不应该依赖用户打开聊天后才发生。第一版需要支持三类入口：

1. 后台 worker 定时扫描或按事件触发。
2. API dry-run / trigger 测试触发，便于开发和验收。
3. 用户反馈类触发，例如明确说某个已排任务没完成，或表达疲劳。

三类入口最终都归一成同一个 `ActiveScheduleTrigger`，再进入同一条观测链路。

### 4.2 需要拍板的问题

1. 第一版触发源是否只做两个：`important_urgent_task` 和 `unfinished_feedback`？
   - 已确认：第一版先做这两类主触发。`fatigue_feedback` 可作为用户反馈类的后续扩展，不抢第一轮主链路。
2. API 测试触发是否允许直接同步返回诊断结果，还是必须也写入 outbox 后异步消费？
   - 已确认：两种都保留。`dry-run` 同步返回诊断结果，不写预览、不发通知；`trigger` 走正式异步链路，写预览并发布通知事件。
3. `mock_now` 是否只允许测试接口传入，后台真实 worker 禁止传入？
   - 已确认：`mock_now` 只允许 API dry-run / 测试 trigger 使用；后台 worker 正式定时触发必须使用真实当前时间。
4. 同一用户短时间多次触发的去重窗口设多长？
   - 已确认：`important_urgent_task` 按 `user_id + trigger_type + target_task_id` 做 30 分钟去重；`unfinished_feedback` 按用户反馈的 `feedback_id / idempotency_key` 防重复提交，不做固定时间窗强去重。

### 4.3 待补执行计划

业务逻辑确认后补充：

1. DTO 字段定义。
2. 事件名、event_version、payload 示例。
3. API trigger / dry-run 路由设计。
4. worker handler 注册位置。
5. 单元测试与集成测试方案。

## 5. 模块二：ActiveScheduleContext 构造

### 5.1 业务实现逻辑简述

`ActiveScheduleContext` 是主动调度的统一输入快照。它负责把用户、时间窗、任务、日程、四象限任务池、偏好、近期反馈和触发来源装配到一起。

上下文构造阶段需要先触发或复用四象限紧急性派生，避免后台读到懒加载前的旧任务池。

### 5.2 需要拍板的问题

1. 滚动 24 小时如何映射到当前“周 + 星期 + 节次”模型？是否第一版只按节次粒度处理？
   - 已确认：候选窗口按任务 DDL / 当前滚动 24 小时映射到现有相对时间坐标（week/day_of_week/section），正式写入仍同时维护 schedule 现有的绝对时间与相对时间字段。
   - 已确认：第一版统一按 1 节粒度处理；任务预计长度先限定在 1~4 节，后续可在创建 task 时由 AI 根据复杂度写入预计节数。
2. 四象限任务池里的 `tasks` 是否需要映射到 `task_items`，还是主动调度预览直接支持 task_pool 任务？
   - 已确认：不创建无所属任务类的“孤儿 task_item”。四象限任务进入日程时保留 task_pool 身份，通过 `schedule_events.task_source_type=task_pool` 指向 `tasks.id`。
3. 用户偏好第一版从哪里注入：memory 摘要、task_class 配置，还是先只消费已有排程约束？
   - 已确认：若候选目标来自 task 池，优先使用 memory 中的用户偏好；若候选目标来自 task_item，则使用所属 task_class 的硬性偏好和约束。
4. 近期用户反馈是否第一版只作为 trigger payload，不落数据库状态？
   - 已确认：用户反馈类触发信号需要持久化，但不面向前端展示；主要用于幂等、审计、排障和串联 trigger -> preview -> notification -> apply 链路。

### 5.3 待补执行计划

业务逻辑确认后补充：

1. `ActiveScheduleContext` 结构。
2. 任务、日程、偏好、反馈的读取入口。
3. 四象限刷新复用方案。
4. 时间窗转换与边界兜底。

## 6. 模块三：主动观测与候选生成

### 6.1 业务实现逻辑简述

主动观测能力参考 `analyze_health`：后端先做结构化观测，再生成候选，让 LLM 做选择题。

第一版候选限制为 1 到 3 个，动作范围包括：

1. 加入日程预览。
2. 未完成补救预览。
3. 后继挤压重排预览。
4. 延后结束询问。
5. 压缩融合预览。
6. 询问用户。
7. 仅提醒。
8. 收口。

### 6.2 需要拍板的问题

1. 主动观测最终是 Agent 工具，还是 worker 内部 service？第一版是否同时提供内部 service 和工具壳？
   - 已确认：主动观测不作为 ReAct 工具进入工具循环，而是串进固定 graph / service pipeline。LLM 直接消费观测与候选结果，负责选择和表达。
2. “重要且紧急任务未进入日程视图”的可用窗口查找，第一版是否允许打破 task_class 偏好？
   - 已纠正：task_pool 任务不属于 task_class，不存在 task_class 偏好可打破。第一版按用户 memory 偏好和滚动 24 小时内的可用时间生成候选；若 memory 偏好与可用容量冲突，候选中说明偏好未满足的代价，而不是称为“打破 task_class 偏好”。
3. 未完成补救里，局部重排第一版复用现有粗排算法到什么程度？
   - 已确认：第一版做“偏好软化版局部粗排”。输入时间窗为当前时刻到任务类结束日期，只传受影响的部分 item；周几偏好和时段偏好从硬约束降级为优先级，优先排偏好范围内，排不下再打破偏好追加进去，最后恢复这些任务的原有顺序语义。
   - 工程倾向：不直接污染现有粗排主函数，新增一条局部重排实现；底层时间格、可用槽位、冲突判断等公共能力优先抽公共层复用，避免复制第三份逻辑。
4. 压缩融合候选第一版是否固定只找“下一个动态任务”，并默认 50% / 50%？
   - 已确认：第一版固定只找下一个动态任务作为融合对象，并默认按 50% / 50% 压缩；该候选只作为兜底预览，不自动执行。
5. close / ask_user / notify_only 的判定阈值由后端固定，还是允许 LLM 结合上下文选择？
   - 已确认：参考 `analyze_health` 的裁决模式，由后端确定 `close / ask_user / notify_only / select_candidate`。LLM 不决定能不能调度，只在 `select_candidate` 时选择候选；其它场景只负责解释后端理由。

### 6.3 待补执行计划

业务逻辑确认后补充：

1. metrics / issues / decision / candidates schema。
2. 候选合法性校验规则。
3. 候选排序规则。
4. 与现有 `analyze_health` 的复用和隔离边界。
5. 单元测试覆盖场景。

## 7. 模块四：预览、前后对比与确认

### 7.1 业务实现逻辑简述

主动调度候选必须先写入待确认预览，让用户看到“为什么触发、改前是什么、改后是什么、风险是什么、不调整的后果是什么”。

确认粒度按候选项确认，不做整版黑盒确认。确认后才进入正式应用链路。

### 7.2 需要拍板的问题

1. 预览复用 `agent_schedule_states`，还是新增 `active_schedule_previews`？
   - 已确认：新增 `active_schedule_previews` 承载主动调度预览持久化；不直接塞进 `agent_schedule_states`。展示层可以抽通用 before/after change schema，供现有会话排程预览和主动调度预览复用。
2. 预览是否必须保存 before 快照，还是第一版只保存 change item + 当前状态版本？
   - 已确认：第一版不保存全量 before 快照，保存受影响范围的 `before_summary + preview_changes + base_version`，用于展示改前/改后和确认前安全校验。
3. 回滚第一版是“失败后不落库即可”，还是必须支持已应用后的撤销？
   - 已确认：第一版不开放 apply 成功后的撤销能力；apply 必须事务化，失败不落库，并回写 `apply_status / apply_error`。成功后轻量记录 `applied_event_ids`，为审计和后续撤销能力预留。
4. 用户确认入口走现有 Agent resume 协议，还是新增主动调度确认 API？
   - 已确认：不走 Agent resume。MVP 新增主动调度详情页和确认 API；飞书链接进入详情页。详情页采用助手卡片式体验，展示解释文案和日程对比卡片，支持拖动 after 方案后确认。
5. 预览过期时间设多久？
   - 已确认：MVP 预览过期时间为 1 小时；过期后不可确认应用，只能重新触发生成新的预览。

### 7.3 待补执行计划

业务逻辑确认后补充：

1. 预览表或缓存结构。
2. `SchedulePreviewVersion` / `ActiveScheduleChangeItem` schema。
3. 查询预览 API。
4. 确认 API 或 resume 接入方案。
5. 幂等键与状态流转。

## 8. 模块五：正式应用链路

### 8.1 业务实现逻辑简述

主动调度模块不直接写正式日程。用户确认某个候选后，后端把候选转换为现有 service 能理解的正式应用请求。

应用成功后发布 `schedule.apply.succeeded`；失败则发布 `schedule.apply.failed`，并把失败原因写回预览状态。

### 8.2 需要拍板的问题

1. 从任务池任务加入日程时，正式写入目标是 `schedule_events(type=task, rel_id=tasks.id)`，还是先转为 `task_items`？
   - 已确认：不转为 `task_items`。正式写入 `schedule_events.type=task, task_source_type=task_pool, rel_id=tasks.id`，并写入对应 `schedules` 原子节次。
2. 未完成补救涉及已排任务移动时，是否第一版只支持生成新补做块，不支持直接移动原任务？
   - 已确认：第一版只支持生成新的补做块，不直接移动原已排任务。这样可以降低对既有 schedule / task_item 状态的扰动，后续再扩展移动原任务。
3. `schedule.apply.requested` 第一版是否需要 outbox 异步消费，还是确认接口内同步调用 service？
4. 应用幂等键用 `preview_id + candidate_id`，还是单独生成 `apply_id`？

### 8.3 待补执行计划

业务逻辑确认后补充：

1. 候选到正式请求的转换器。
2. 复用 `TaskClassService.BatchApplyPlans` 的条件。
3. task_pool 任务正式落库策略。
4. 应用失败回写方案。
5. 测试场景。

## 9. 模块六：通知触达与飞书边界

### 9.1 业务实现逻辑简述

飞书第一版只提醒用户回系统确认，不在飞书内应用日程、不标记完成、不做复杂 Agent Chat。

主动调度只发布 `notification.feishu.requested`，通知 handler/provider 负责具体投递。这样后续可以把 notification 拆成独立 Go module。

### 9.2 需要拍板的问题

1. 第一版飞书通知文案是否只需要固定模板？
2. 通知是否必须包含跳转链接？如果包含，Web 端预览详情 URL 规则是什么？
3. 通知幂等键是否按 `preview_id`，还是按 `user_id + trigger_type + time_window`？
4. 飞书 provider 第一版放在 backend worker 内，是否需要同步预留 `notification_records` 表？

### 9.3 待补执行计划

业务逻辑确认后补充：

1. `NotificationRequested` DTO。
2. 简版 provider 接口。
3. 飞书配置项。
4. 幂等与失败日志。
5. 后续迁出到 `backend/services/notification` 的边界。

## 10. 模块七：与微服务迁移的协作边界

### 10.1 业务实现逻辑简述

第二阶段开发必须避免阻塞微服务迁移。当前策略是：先在 `backend` 内按服务边界写清楚，等协议稳定后再迁出独立 module。

API、worker、active scheduler、notification、schedule apply 的边界必须从第一版就分清。

### 10.2 需要拍板的问题

1. 是否先完成 `api / worker / all` 启动边界拆分，再合入主动调度主链路？
2. 主动调度代码第一版放在 `backend/service/active_scheduler`，还是 `backend/active_scheduler`？
3. 事件契约是否提前放入 `backend/shared/events` 风格目录，即使当前还未多 module？
4. 第一版是否允许主动调度 service 直接依赖 DAO，还是通过现有 service 读取？

### 10.3 待补执行计划

业务逻辑确认后补充：

1. 目录结构。
2. 依赖注入关系。
3. API / worker 启动装配改动点。
4. 未来迁出 `active-scheduler` 的文件边界。

## 11. 建议讨论顺序

建议按以下顺序逐个讨论：

1. 任务池任务如何进入日程视图。
2. 预览与确认协议。
3. 主动观测候选 schema。
4. 触发事件与 worker 链路。
5. 正式应用链路。
6. 飞书通知边界。
7. 目录结构与迁移边界。

## 12. 本轮决策记录

后续每轮讨论完成后，在这里追加结论。

### 12.1 触发 job 机制

1. `task` 创建或更新时，若存在 `urgency_threshold_at`，则 upsert 一条对应的主动调度 job。
2. job 的触发时间统一取 `urgency_threshold_at`；主动调度不再自行维护 `deadline_at - X` 之类的额外阈值。
3. `task` 完成后，不物理删除 job，而是将仍未执行的 job 标记为 `canceled`，方便后续排查为什么没有触发。
4. `task` 更新 `deadline_at` 或 `urgency_threshold_at` 时，直接覆盖当前有效 job，并刷新 `updated_at`。
5. schedule 动态任务默认不写定时 job；计划时间过去后按 `assumed_completed` 推进，只有用户明确反馈未完成时才进入主动调度链路。

### 12.2 待继续讨论

1. `schedule.apply.requested` 第一版同步调用 service，还是进入 outbox 异步消费。
2. 应用幂等键使用 `preview_id + candidate_id`，还是单独生成 `apply_id`。
3. 飞书通知固定文案、跳转 URL、通知幂等键和 `notification_records` 是否第一版落表。

### 12.3 API 触发、mock_now 与去重

1. API 侧同时提供 `dry-run` 与 `trigger` 两类测试入口：
   - `dry-run`：同步执行主动观测并直接返回诊断和候选；不写预览、不发布飞书通知，主要用于开发调试和验收。
   - `trigger`：进入正式主动调度链路；写入预览，并发布 `notification.feishu.requested`。
2. `mock_now` 只允许 API dry-run / 测试 trigger 使用，用于模拟未来或历史时刻；后台 worker 正式定时触发必须使用真实 `time.Now()`。
3. 使用 `mock_now` 的触发应在 trace / payload 中标记 `is_mock_time=true`，避免排障时把测试触发误认为真实后台触发。
4. `important_urgent_task` 触发按 `user_id + trigger_type + target_task_id` 做 30 分钟去重，避免重复生成预览和重复飞书打扰。
5. `unfinished_feedback` 触发按用户反馈的 `feedback_id / idempotency_key` 做请求幂等；不做固定时间窗强去重，避免用户连续反馈未完成时被错误吞掉。

### 12.4 上下文构造与偏好来源

1. 滚动 24 小时窗口需要映射到现有 `week / day_of_week / section` 坐标，正式应用时仍按现有 schedule 口径同时维护绝对时间与相对时间。
2. 第一版候选以 1 节为最小粒度，任务预计长度限定为 1~4 节。
3. 后续在 task 创建阶段增加预计节数字段时，可由 AI 根据任务复杂度写入该值；主动调度只消费该字段，不在调度阶段重新发明复杂度判断。
4. 偏好来源按目标类型分流：
   - task 池任务：使用 memory 注入的用户偏好。
   - task_item：使用所属 task_class 的硬性偏好和约束。
5. `用户反馈` 在本文档中指显式调度触发信号，不是普通聊天上下文。第一版重点支持 `unfinished_feedback`，即用户明确反馈某个已排动态任务未完成。
6. 调度触发信号持久化为后端链路状态，不直接展示给前端。建议使用类似 `active_schedule_triggers` 的结构承载 `trigger_type / target_type / target_id / idempotency_key / payload_json / status`。

### 12.5 task 池任务进入 schedule 的 schema 分叉

已确认采用方案 A：

1. 在 `schedule_events` 上新增任务来源列：`task_source_type`。
2. `schedule_events.type` 继续表示日程展示与占用类型，保持现有 `course / task` 语义。
3. 当 `type = task` 时，`task_source_type` 表示任务来源：
   - `task_item`：`rel_id` 指向 `task_items.id`。
   - `task_pool`：`rel_id` 指向 `tasks.id`。
4. 原有动态任务块继续使用 `type = task, task_source_type = task_item`。
5. 四象限任务进入日程后使用 `type = task, task_source_type = task_pool`，不创建孤儿 `task_item`。
6. 不扩展 `schedule_events.type` 为 `quadrant_task`，避免把任务来源语义混入日程块展示类型，也避免影响现有按 `event.Type == "task"` 判断的前端、冲突、撤销和预览逻辑。

执行计划待补：需要评估迁移 SQL、模型字段、schedule 读取映射、task_pool apply 链路以及历史 `type=task` 数据的默认来源回填策略。

### 12.6 主动观测链路形态

1. 主动调度主链路走固定 graph / service pipeline，不进入 ReAct 工具循环。
2. graph 建议形态：
   ```text
   ActiveScheduleTrigger
     -> BuildContext
     -> Observe
     -> GenerateCandidates
     -> LLMSelectAndExplain
     -> WritePreview
     -> Notify
   ```
3. `BuildContext / Observe / GenerateCandidates` 使用确定性后端逻辑，负责读取事实、生成诊断、校验候选合法性。
4. `LLMSelectAndExplain` 不调用工具，只直接消费后端给出的结构化结果，负责在候选中选择、生成用户可读解释，或选择 ask_user / close / notify_only。
5. 第一版不提供 ReAct 工具壳；后续如果用户在聊天中主动要求“帮我看看接下来 24 小时安排”，可以再加一个人工触发入口复用同一套 service。
6. API dry-run、API trigger、worker 后台触发都调用同一套主动调度 graph / service，避免出现多套观测逻辑。

### 12.7 未完成补救的局部重排策略

1. 未完成补救里的局部重排不是整周 / 整任务类重排，而是只处理受影响的部分 `task_item`。
2. 局部重排输入：
   - 起点：当前时刻对应的相对时间坐标。
   - 终点：目标任务所属 `task_class.end_date`。
   - 任务集：未完成任务及其被挤压的后继 item，而不是整个 task_class 的全部 item。
3. 粗排约束调整：
   - 原有周几偏好、时段偏好在正式粗排里偏硬约束。
   - 局部补救中改成软偏好：优先落在偏好范围内。
   - 如果偏好范围内排不下，允许打破偏好，把剩余任务继续追加到可用时间里。
4. 排序语义：
   - 补救过程中可以为了找槽位临时调整候选顺序。
   - 输出结果需要恢复这些受影响任务的原有顺序语义，避免把后继关系打乱。
5. 工程实现：
   - 不直接修改现有全量粗排主函数，避免影响现有智能排程行为。
   - 新增一条“局部重排 / 偏好软化粗排”实现。
   - 时间格构建、空位扫描、冲突判断、节次候选等公共能力优先抽公共层复用；若短期无法完全抽出，需要在实现注释中说明原因，避免长期复制第三份粗排逻辑。

### 12.8 压缩融合兜底候选

1. 压缩融合只作为局部重排和延后结束都不可用时的兜底候选。
2. 第一版固定选择“下一个动态任务”作为融合对象，不做跨多个后继任务的复杂搜索。
3. 第一版固定比例为 50% / 50%：
   - 未完成任务压缩到融合块的一半时间。
   - 下一个动态任务压缩到融合块的一半时间。
4. 压缩融合必须写清风险说明：两个任务都会被压缩，需要用户接受 rush 模式。
5. 压缩融合只生成预览，不允许后台自动执行。

### 12.9 主动调度裁决模式

1. 主动调度参考 `analyze_health` 的裁决模式，但不复用其节奏指标。
2. 后端固定执行：
   ```text
   观测事实
     -> 生成 issues
     -> 收集 missing_info
     -> 尝试生成合法 candidates
     -> 构造 decision
   ```
3. `decision.action` 第一版包含：
   - `close`：没有值得处理的问题，或问题已被现有日程覆盖。
   - `ask_user`：缺少关键事实，或需要用户放宽边界才能继续。
   - `notify_only`：有风险但无合法调整候选，也没有一个明确问题能继续推进。
   - `select_candidate`：存在 1~3 个后端校验过的合法候选。
4. 基础裁决规则：
   - 没有 issue -> `close`。
   - 有 issue，但缺关键事实 -> `ask_user`。
   - 有 issue，且有合法 candidates -> `select_candidate`。
   - 有 issue，但没有合法 candidates：
     - 若能通过一个明确问题继续推进 -> `ask_user`。
     - 否则 -> `notify_only`。
5. LLM 职责边界：
   - 不判断候选是否合法。
   - 不自由构造新候选。
   - `select_candidate` 时只在候选里选择最合适的一项，并生成用户可读解释。
   - `ask_user / notify_only / close` 时只负责把后端裁决理由说清楚。

### 12.10 主动调度预览持久化边界

1. 主动调度预览新增独立持久化结构，建议命名为 `active_schedule_previews`。
2. 不复用 `agent_schedule_states` 作为主动调度预览主存储，原因：
   - `agent_schedule_states` 强绑定 `conversation_id`，更适合会话内智能排程快照。
   - 主动调度来自后台 worker，可能没有会话上下文。
   - 主动调度预览需要绑定 `trigger_id / candidate_id / expires_at / apply_status / notification_status`，语义与会话快照不同。
3. 展示协议可以复用：
   - 抽通用 `SchedulePreviewChangeItem` / before-after schema。
   - 现有会话排程预览后续也应补齐改前 / 改后能力。
   - 主动调度预览复用同一套 change schema，但独立存储和流转状态。
4. 这一路径更符合后续微服务拆分：
   - `active-scheduler` 负责生成 `active_schedule_previews`。
   - API 负责查询预览与接收确认。
   - schedule 域负责正式应用。

### 12.11 预览快照、确认校验与 apply 结果

1. 第一版不保存全量 before 快照，避免主动调度预览表过重，也避免未来误用全量快照覆盖用户后续改动。
2. 第一版必须保存：
   - `base_version`：生成预览时的日程基准版本，可使用 schedule hash、相关 event 更新时间摘要或等价版本标识。
   - `before_summary`：只保存受影响范围的改前信息，例如受影响 event、空闲槽位、原 task_item 落位。
   - `preview_changes`：候选准备做的改动，例如新增 task_pool 日程、移动 task_item、压缩融合预览。
3. `before_summary + preview_changes` 的用途：
   - 给用户展示改前 / 改后。
   - 用户确认时校验当前日程是否仍符合预览生成时的基准。
   - 后续补撤销能力时，可以作为局部反向操作的基础。
4. 第一版 apply 策略：
   - 用户确认前不改正式日程，因此不需要回滚。
   - 用户确认后，正式应用必须放在事务里执行。
   - 如果事务失败，正式日程不落库，只把预览标记为 `apply_failed` 并写入 `apply_error`。
5. 第一版不开放 apply 成功后的撤销按钮，不做整版快照覆盖式回滚。
6. apply 成功后轻量记录：
   - `apply_status = applied`
   - `applied_at`
   - `applied_event_ids`
   - 必要时记录 `applied_change_ids`
7. 后续若要支持撤销，应基于后端实际应用成功的 change 做局部反向操作，不能用 apply 前全量快照覆盖整张日程表，避免误删用户后续手动修改。

### 12.12 用户确认入口与聊天增强预留

1. MVP 不走现有 Agent resume 协议，新增主动调度详情页与主动调度确认 API。
2. 飞书通知只包含详情页链接，默认进入：
   ```text
   /active-schedule/previews/:preview_id
   ```
3. 详情页体验采用“助手卡片式”设计，但后端不依赖完整 Agent Chat：
   - 顶部展示助手解释文案。
   - 中间展示日程前后对比卡片。
   - 展示触发原因、建议理由、风险和不调整后果。
   - 支持用户拖动调整 after 方案。
   - 支持确认应用、忽略 / 拒绝。
4. 拖动后的确认请求必须携带 `edited_changes`，后端重新校验，不信任前端坐标。
5. 确认 API 建议语义：
   ```text
   POST /active-schedule/previews/:preview_id/confirm
   ```
   请求包含 `candidate_id / action / edited_changes / idempotency_key`。
6. 后续增强可把同一个 `preview_id` 导入聊天页：
   ```text
   /agent/chat?active_preview_id=xxx
   ```
   聊天页加载同一份主动调度预览，由助手吐出解释消息和同一张日程卡片。
7. 聊天增强必须复用 `active_schedule_previews / preview_changes / confirm API`，不能另起一套确认和应用协议。
8. 若用户从详情页点击“和助手讨论”，再创建或绑定 `conversation_id`；主动调度预览本身的 `conversation_id` 保持可空。

### 12.13 预览过期策略

1. MVP 主动调度预览有效期为 1 小时。
2. `active_schedule_previews` 需要保存 `expires_at = generated_at + 1h`。
3. 超过 `expires_at` 后：
   - 预览仍可查看历史说明。
   - 不允许确认应用。
   - 前端提示用户重新生成建议。
4. 确认 API 必须校验过期状态，避免用户对旧日程基准执行过期候选。

## 13. 共识详述与实现备忘

本节用于保存讨论过程中的关键推理，避免后续上下文压缩或换对话后只剩简短结论。

### 13.1 为什么后台触发不是全量定时扫描

主动调度的“定时”不是 worker 每隔几分钟全表扫 `tasks`，而是 task 本身在创建或更新时写入一条未来到期 job。

推荐语义：

1. task 创建时，如果有 `urgency_threshold_at`，写入或更新对应 `active_schedule_jobs`。
2. task 更新 `deadline_at / urgency_threshold_at` 时，直接 upsert 覆盖当前有效 job，并刷新 `updated_at`。
3. task 完成时，不物理删除 job，而是把未执行 job 标记为 `canceled`。
4. job 到期后，worker 读取 due job，再重新读取 task 真值：
   - task 已完成 -> 标记 skipped / canceled，不进入主动调度。
   - task 已不满足重要且紧急条件 -> 标记 skipped。
   - task 仍未完成且到达触发条件 -> 生成 `active_schedule.triggered`。

这样做的原因：

1. 避免后台全表扫描放大数据库压力。
2. 触发时间与四象限懒平移机制一致，统一使用 `urgency_threshold_at`，不再维护 `deadline_at - X` 这类主动调度私有阈值。
3. `canceled` 比物理删除更利于审计：后续可以解释“为什么这个任务没有触发主动调度”。
4. upsert 覆盖比“取消旧 job 再新建 job”简单，MVP 足够用。

### 13.2 schedule 动态任务为什么不写定时 job

schedule 里的动态任务计划时间过去后，第一版默认按 `assumed_completed` 推进体验，不主动追问、不自动补救。

只有用户明确反馈未完成时，才进入主动调度链路。例如：

```text
刚才那个没做完
这项要延后
今天撑不住了
```

原因：

1. 自动追问会打扰用户，且用户没有反馈时系统无法确认是真没做还是没打卡。
2. 产品口径已经确定为“默认完成，用户反馈纠偏”。
3. 未完成补救属于用户显式触发，不应由时间流逝自动触发。

### 13.3 用户反馈触发信号为什么要持久化

用户反馈类触发信号不展示给前端，它是后端链路状态。建议使用 `active_schedule_triggers` 保存。

它的目的不是做产品卡片，而是：

1. 幂等：同一条“没做完”反馈不要重复触发两次。
2. 审计：用户问“为什么系统给我发飞书”，可以查到触发原因。
3. 排障：worker 失败、跳过、重试都有状态可查。
4. 串链路：`trigger -> preview -> notification -> apply` 能通过 `trigger_id` 串起来。

建议字段方向：

```text
id
user_id
trigger_type          # important_urgent_task / unfinished_feedback
target_type           # task_pool / schedule_event / task_item
target_id
idempotency_key
payload_json
status                # pending / processing / preview_generated / skipped / failed
created_at
updated_at
```

其中 `unfinished_feedback` 不做固定时间窗强去重，而是依赖 `feedback_id / idempotency_key` 幂等；这样用户连续反馈“还是没做完”不会被 30 分钟窗口误吞。

### 13.4 为什么 task_pool 不转成孤儿 task_item

我们讨论过“把四象限任务转成孤儿 task_item”来复用 `BatchApplyPlans`。最终不采用这个方案。

原因：

1. 现有 `task_items` 基本语义是归属于 `task_classes` 的任务块。
2. 虽然模型里 `CategoryID` 是指针，但 DAO / service 很多地方默认 task_item 有所属 task_class：
   - `BatchApplyPlans` 必须传 `TaskClassID`。
   - `ValidateTaskItemIDsBelongToTaskClass` 用 `category_id` 做归属校验。
   - `GetTaskClassIDByTaskItemID` 直接解引用 `CategoryID`。
   - 预览分类、撤销、约束读取也默认 item 有父级。
3. 孤儿 task_item 会带来一串问题：
   - 属于哪个任务类？
   - 用哪个 task_class 的周几 / 时段偏好？
   - 撤销后回到哪里？
   - task 完成后怎么同步 task_item？
   - 前端任务类列表是否显示这个隐藏 item？

最终方案是保留 task_pool 身份，让 schedule 引用 `tasks.id`。

### 13.5 为什么新增 `task_source_type`，而不是扩展 `schedule_events.type`

已确认在 `schedule_events` 上新增 `task_source_type`。

字段语义：

```text
schedule_events.type             # 日程展示 / 占用类型：course / task
schedule_events.task_source_type # 当 type=task 时的业务来源：task_item / task_pool
schedule_events.rel_id           # 指向对应来源表的 id
```

示例：

```text
动态任务块：
type = task
task_source_type = task_item
rel_id = task_items.id

四象限任务：
type = task
task_source_type = task_pool
rel_id = tasks.id
```

不扩展 `type = quadrant_task` 的原因：

1. `type` 现有语义更像“日历上展示/占用的类型”，四象限任务进入日程后仍然是任务块。
2. 现有代码和前端可能大量判断 `event.Type == "task"`；新增 `quadrant_task` 容易漏分支。
3. “四象限”是任务来源 / 优先级语义，不是日程块类型。
4. 后续如果还有 `manual_task / habit_task / external_task`，都塞进 `type` 会把字段语义撑乱。

历史数据回填策略后续执行计划里再细化：历史 `type=task` 可默认回填为 `task_item`，避免破坏旧动态任务块。

### 13.6 task_pool 任务进入日程的正式写入语义

用户确认 task_pool 候选后，不创建 task_item，直接写正式日程：

```text
schedule_events:
  type = task
  task_source_type = task_pool
  rel_id = tasks.id
  name = tasks.title
  start_time / end_time = 绝对时间

schedules:
  event_id = schedule_events.id
  user_id
  week
  day_of_week
  section
```

这意味着后续读取 schedule 时：

1. 如果 `type=task, task_source_type=task_item`，按旧链路关联 `task_items`。
2. 如果 `type=task, task_source_type=task_pool`，关联 `tasks`。
3. 如果 `task_source_type` 为空且 `type=task`，兼容历史数据，默认按 `task_item` 处理。

### 13.7 滚动 24 小时与节次粒度

MVP 按现有课程表坐标工作，滚动 24 小时需要映射到：

```text
week / day_of_week / section
```

正式应用时仍维护现有 schedule 的绝对时间与相对时间：

1. `schedule_events.start_time / end_time` 保存绝对时间。
2. `schedules.week / day_of_week / section` 保存相对节次原子格。

第一版任务长度：

1. 最小粒度统一为 1 节。
2. task_pool 任务预计长度初步限定在 1~4 节。
3. 由于当前 task 缺少预计耗时，第一版可以使用默认值或在候选里让用户确认。
4. 后续创建 task 时增加预计节数字段，由 AI 根据任务复杂度写入；主动调度只消费该字段，不在调度阶段重新判断复杂度。

### 13.8 task_pool 与 task_item 的偏好来源不同

偏好不能混用。

task_pool 任务：

1. 不属于 task_class。
2. 不存在 task_class 的周几 / 时段硬约束。
3. 按用户 memory 中注入的软偏好安排。
4. 如果 memory 偏好与 24 小时容量冲突，候选里说明“未满足偏好”的代价，而不是称为“打破 task_class 偏好”。

task_item：

1. 属于 task_class。
2. 优先使用所属 task_class 的硬性偏好和约束。
3. 未完成补救场景下，部分 task_class 偏好会在局部重排里从硬约束软化为优先级。

### 13.9 主动观测为什么不进 ReAct

主动调度主链路走固定 graph / service pipeline，不进入 ReAct 工具循环。

原因：

1. 这是后台 worker 触发的链路，不是用户实时开放式问答。
2. 它需要稳定、可幂等、可审计、可重试。
3. ReAct 适合开放探索；主动调度 MVP 的目标是减少开放性，让后端出选择题。
4. LLM 不应该自由查全窗、自由构造写库参数或直接 apply。

固定 graph 形态：

```text
ActiveScheduleTrigger
  -> BuildContext
  -> Observe
  -> GenerateCandidates
  -> LLMSelectAndExplain
  -> WritePreview
  -> Notify
```

其中：

1. `BuildContext / Observe / GenerateCandidates` 是确定性后端逻辑。
2. `LLMSelectAndExplain` 不调用工具，只消费结构化观测结果和候选。
3. API dry-run、API trigger、worker 后台触发都复用同一套 graph / service。
4. 后续若聊天里需要“帮我看看接下来 24 小时安排”，可以加人工触发入口，但也只是调用同一套 service，不另写 ReAct 工具循环。

### 13.10 LLM 在选择题模式里的作用

后端给候选，并不代表 LLM 没有价值。后端负责合法性和硬约束，LLM 负责软约束仲裁与表达。

后端擅长：

1. 判断时段是否冲突。
2. 判断候选是否越过 24 小时窗口。
3. 判断容量是否足够。
4. 判断正式写入参数是否合法。
5. 生成 1~3 个可执行候选。

LLM 擅长：

1. 结合用户刚才语气判断是否疲劳。
2. 在候选分数接近时，根据 memory 软偏好选更容易被接受的方案。
3. 把结构化风险翻译成用户能理解的解释。
4. ask_user 时问得更自然，不让用户觉得被系统打断。
5. notify_only 时用提醒语气，而不是制造焦虑。

边界：

1. LLM 不判断候选是否合法。
2. LLM 不自由构造新候选。
3. LLM 只在 `decision.action=select_candidate` 时从候选里选。
4. `close / ask_user / notify_only` 时，LLM 只负责表达后端裁决理由。

一句话：后端保证不出错，LLM 负责更像人。

### 13.11 后端裁决如何参考 analyze_health

主动调度参考 `analyze_health` 的裁决模式，而不是复用其节奏指标。

主动调度自己的裁决流程：

```text
观测事实
  -> 生成 issues
  -> 收集 missing_info
  -> 尝试生成合法 candidates
  -> 构造 decision
```

裁决规则：

1. 没有 issue -> `close`。
2. 有 issue，但缺关键事实 -> `ask_user`。
3. 有 issue，且有合法 candidates -> `select_candidate`。
4. 有 issue，但没有合法 candidates：
   - 如果能通过一个明确问题继续推进 -> `ask_user`。
   - 如果问用户也不能立刻推进，只是需要提醒 -> `notify_only`。

例子：

1. `close`：重要且紧急 task 已经在 schedule 里，或任务已完成。
2. `ask_user`：用户说“刚才那个没做完”，但系统无法定位是哪条 schedule_event；或容量不足，需要问能否延后结束时间。
3. `select_candidate`：找到合法的加入日程 / 未完成补救 / 压缩融合候选。
4. `notify_only`：有风险但没有安全可挪的任务，也没有一个明确问题能继续推进。

### 13.12 未完成补救的局部重排不是全量粗排

未完成补救里的局部重排是“偏好软化版局部粗排”。

输入：

1. 起点：当前时刻对应的相对时间坐标。
2. 终点：目标任务所属 `task_class.end_date`。
3. 任务集：未完成任务及被挤压的后继 item。
4. 不传整个 task_class 的全部 item。

偏好处理：

1. 现有全量粗排里的周几 / 时段偏好偏硬约束。
2. 局部补救中改为软偏好。
3. 优先排偏好范围内。
4. 偏好范围内排不下时，允许打破偏好，把剩余任务继续追加到可用时间里。

顺序处理：

1. 搜索候选时可以为了找槽位临时调整。
2. 输出需要恢复受影响任务的原有顺序语义，避免打乱后继关系。

工程策略：

1. 不直接改现有全量粗排主函数，避免影响当前智能排程行为。
2. 新增局部重排实现。
3. 时间格、可用槽位、冲突判断、节次候选等能力优先抽公共层。
4. 如果短期必须 copy 逻辑，需要在注释里写清楚为什么暂时不能抽公共层，避免长期复制第三份。

### 13.13 压缩融合为什么是兜底

压缩融合不是理想调度，只是当局部重排和延后结束都不可用时的兜底预览。

MVP 规则：

1. 只找下一个动态任务作为融合对象。
2. 不跨多个后继任务搜索。
3. 默认 50% / 50%。
4. 必须向用户说明两个任务都会被压缩。
5. 只生成预览，不允许后台自动执行。

产品语义：

1. 它通常比直接跳过失败任务更好。
2. 但它会牺牲两个任务质量，所以必须用户确认。
3. 后续可以用优先级、DDL、预计耗时动态调整比例，但第一版固定。

### 13.14 为什么主动调度预览不塞进 agent_schedule_states

`agent_schedule_states` 更像会话内智能排程快照，强绑定 `conversation_id`，用于粗排、拖拽、微调。

主动调度预览不同：

1. 可能没有 conversation。
2. 来自后台 worker。
3. 绑定 `trigger_id`。
4. 有 `candidate_id`。
5. 有 `expires_at`。
6. 有通知状态和 apply 状态。
7. 要做幂等、防重复触达、审计。

因此新增 `active_schedule_previews`，但抽通用 before/after 展示协议。

这意味着：

1. 持久化表不复用。
2. 展示 schema 可以复用。
3. 现有会话排程预览后续也应该补改前 / 改后能力。
4. 未来迁出 `active-scheduler` 时，预览表边界更清晰。

### 13.15 before_summary、preview_changes 和 applied_event_ids 的意义

MVP 不保存全量 before 快照，也不做成功后的撤销按钮。

必须保存：

```text
base_version
before_summary
preview_changes
```

原因：

1. 用户打开预览时能看到当时那版改前 / 改后，而不是重新查一个已经变化的当前日程。
2. 用户确认时能校验：生成预览时空的时段，现在是否仍然空。
3. 后续要做撤销时，有局部反向操作基础。

不保存全量 before 的原因：

1. 表会很重。
2. 后续如果误用全量快照覆盖日程，会抹掉用户 apply 后手动做的其它修改。
3. 真正安全的撤销应该按后端实际应用成功的 change 做局部反向操作，而不是整版覆写。

apply 成功后轻量记录：

```text
apply_status
applied_at
applied_event_ids
apply_error
```

这些当前用于审计和排障，不是为了第一版开放撤销按钮。

### 13.16 确认入口为什么先做详情页，而不是直接聊天页

聊天页效果最好，但第一版直接做完整聊天页会引入很多复杂度：

1. 后台 preview 没有天然 `conversation_id`。
2. 用户拖动卡片后，要同步到 Agent state 还是 active preview。
3. 用户一句“换晚点”是否重新跑 graph。
4. 聊天 SSE、卡片状态、确认状态要保持一致。
5. notification 和 agent channel 容易混边界。

折中方案：

1. MVP 做主动调度详情页。
2. UI 设计成助手卡片式：
   - 顶部助手解释。
   - 中间日程对比卡片。
   - 支持拖动 after。
   - 支持确认 / 忽略。
3. 后端仍走 `active_schedule_previews` 和确认 API，不依赖完整 Agent Chat。
4. 后续可以通过 `/agent/chat?active_preview_id=xxx` 把同一份 preview 导入聊天页。
5. 聊天增强必须复用同一套 preview / changes / confirm API。

这样第一版稳定，后续聊天效果也能接上，不会重写链路。

### 13.17 预览 1 小时过期的具体语义

MVP 预览有效期为 1 小时：

```text
expires_at = generated_at + 1h
```

过期后：

1. 可以查看历史说明。
2. 不能确认应用。
3. 前端提示重新生成建议。
4. 确认 API 必须拒绝过期 preview。

原因：主动调度候选依赖当时日程基准，时间越久越可能被用户或其它流程改动。1 小时是 MVP 的安全折中。