Version: 0.9.5.dev.260407

后端： 1.粗排链路收口（按 task_class_ids 精确加载 ScheduleState + 规划窗口抗脏数据） - 更新conv/schedule_provider.go：新增 LoadScheduleStateForTaskClasses；优先按本轮任务类加载窗口；buildWindowFromTaskClasses 改为逐条过滤坏日期，避免 DayMapping 被全量任务类污染 - 更新model/state_store.go：新增 ScopedScheduleStateProvider 可选接口 - 更新model/graph_run_state.go：EnsureScheduleState 首次加载时优先走 scoped provider，再做 scope 裁剪 2.粗排建议态语义统一（pending/existing → pending/suggested/existing） - 新建tools/status.go：统一 IsPendingTask / IsSuggestedTask / IsExistingTask / scope 过滤逻辑 - 更新node/rough_build.go：粗排回写后任务显式转 suggested；pending 统计仅看“真实 pending” - 更新tools/state.go：ScheduleTask.Status/Slots/Duration 注释补齐 suggested 语义 - 更新tools/read_helpers.go + read_tools.go：overview/list_tasks/task_info 支持 suggested 展示；占用计算按“已落位任务”统一处理 - 更新tools/write_helpers.go + write_tools.go：place/move/swap/unplace 全量切到 suggested/existing/pending 新语义 - 更新tools/registry.go + SCHEDULE_TOOLS.md：工具描述、参数枚举、文档口径同步到 suggested 语义 - 更新conv/schedule_preview.go：预览层统一通过 IsSuggestedTask 输出 suggested，兼容旧快照 - 更新service/agentsvc/agent_newagent.go：预览 debug 摘要改为 pending/suggested/existing 三态统计 3.粗排调试增强 - 更新node/rough_build.go：新增 applied/day_mapping_miss/task_item_match_miss 统计及样本日志，便于排查 placement 未落回 state 的根因前端：无仓库：无
2026-04-07 23:58:00 +08:00
parent 07d307fe07
commit cdedd3c968
14 changed files with 599 additions and 174 deletions
--- a/backend/conv/schedule_preview.go
+++ b/backend/conv/schedule_preview.go
@@ -30,7 +30,7 @@ func ScheduleStateToPreview(
 	for i := range state.Tasks {
 		t := &state.Tasks[i]
 		// 待安排且无位置的任务不生成 entry。
-		if t.Status == "pending" && len(t.Slots) == 0 {
+		if newagenttools.IsPendingTask(*t) {
 			continue
 		}

@@ -59,7 +59,7 @@ func ScheduleStateToPreview(
 				entry.Type = "task"
 			}

-			// Status 映射：existing 不变，pending（有位置）= suggested。
+			// Status 映射：existing 不变，suggested / 兼容建议态统一输出为 suggested。
 			if shouldMarkSuggestedInPreview(*t) {
 				entry.Status = "suggested"
 			} else {
@@ -113,15 +113,9 @@ func ScheduleStateToPreview(
 // shouldMarkSuggestedInPreview 判断某条 ScheduleTask 在预览层是否应标记为 suggested。
 //
 // 规则说明：
-//  1. pending 任务在预览语义中属于“建议态”；
-//  2. source=task_item 且 Duration>0 的任务来自待排任务池，
-//     即使工具层在 place 后把它改成 existing，预览层也要继续按 suggested 输出。
+//  1. 新语义下，显式 suggested 直接输出为建议态；
+//  2. 兼容旧快照：pending+Slots、existing+Duration>0 的 task_item 也继续按 suggested 输出；
+//  3. 这样前端预览口径可以在迁移期保持稳定，不会因为状态枚举切换而抖动。
 func shouldMarkSuggestedInPreview(t newagenttools.ScheduleTask) bool {
-	if t.Status == "pending" {
-		return true
-	}
-	if t.Source == "task_item" && t.Duration > 0 {
-		return true
-	}
-	return false
+	return newagenttools.IsSuggestedTask(t)
 }
--- a/backend/conv/schedule_provider.go
+++ b/backend/conv/schedule_provider.go
@@ -45,22 +45,54 @@ func (p *ScheduleProvider) LoadScheduleState(ctx context.Context, userID int) (*
 		return nil, err
 	}

-	// 2. 确定规划窗口：优先使用 task class 日期范围，降级到当前周。
-	windowDays, weeks := buildWindowFromTaskClasses(taskClasses)
-	if len(windowDays) == 0 {
-		now := time.Now()
-		currentWeek, _, err := RealDateToRelativeDate(now.Format(DateFormat))
-		if err != nil {
-			return nil, fmt.Errorf("解析当前日期失败: %w", err)
-		}
-		windowDays = make([]WindowDay, 7)
-		for i := 0; i < 7; i++ {
-			windowDays[i] = WindowDay{Week: currentWeek, DayOfWeek: i + 1}
-		}
-		weeks = []int{currentWeek}
+	return p.loadScheduleStateWithTaskClasses(ctx, userID, taskClasses)
+}
+
+// LoadScheduleStateForTaskClasses 按“本轮请求的任务类范围”加载 ScheduleState。
+//
+// 设计说明：
+// 1. 负责：让粗排 / Execute 首次读取的 DayMapping 与本轮 task_class_ids 保持同一时间窗口；
+// 2. 不负责：裁掉窗口内已有的 existing/suggested 阻塞物，这部分仍由日程加载主流程统一保留；
+// 3. 失败策略：若 task_class_ids 为空，则退回全量加载，避免调用方额外分支。
+func (p *ScheduleProvider) LoadScheduleStateForTaskClasses(
+	ctx context.Context,
+	userID int,
+	taskClassIDs []int,
+) (*newagenttools.ScheduleState, error) {
+	if len(taskClassIDs) == 0 {
+		return p.LoadScheduleState(ctx, userID)
 	}

-	// 3. 按周加载日程（含 Event + EmbeddedTask 预加载）。
+	taskClasses, err := p.loadCompleteTaskClassesByIDs(ctx, userID, taskClassIDs)
+	if err != nil {
+		return nil, err
+	}
+
+	return p.loadScheduleStateWithTaskClasses(ctx, userID, taskClasses)
+}
+
+// loadScheduleStateWithTaskClasses 负责把“指定任务类集合”装配成可操作的 ScheduleState。
+//
+// 步骤说明：
+// 1. 先根据传入 taskClasses 计算 DayMapping 窗口，保证粗排坐标能映射回 day_index；
+// 2. 若窗口无法从任务类日期推导，则退回当前周 7 天，兼容普通查询场景；
+// 3. 再按窗口覆盖的周批量拉取 existing schedules，与 taskClasses 一起交给 LoadScheduleState 统一建模。
+func (p *ScheduleProvider) loadScheduleStateWithTaskClasses(
+	ctx context.Context,
+	userID int,
+	taskClasses []model.TaskClass,
+) (*newagenttools.ScheduleState, error) {
+	// 1. 确定规划窗口：优先使用 task class 日期范围，降级到当前周。
+	windowDays, weeks := buildWindowFromTaskClasses(taskClasses)
+	if len(windowDays) == 0 {
+		var err error
+		windowDays, weeks, err = buildCurrentWeekWindow()
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	// 2. 按周加载日程（含 Event + EmbeddedTask 预加载）。
 	var allSchedules []model.Schedule
 	for _, w := range weeks {
 		weekSchedules, err := p.scheduleDAO.GetUserWeeklySchedule(ctx, userID, w)
@@ -70,10 +102,10 @@ func (p *ScheduleProvider) LoadScheduleState(ctx context.Context, userID int) (*
 		allSchedules = append(allSchedules, weekSchedules...)
 	}

-	// 4. 构建额外 item category 映射。
+	// 3. 构建额外 item category 映射。
 	extraItemCategories := buildExtraItemCategories(allSchedules, taskClasses)

-	// 5. 调用已有的 LoadScheduleState 构建内存状态。
+	// 4. 调用已有的 LoadScheduleState 构建内存状态。
 	return LoadScheduleState(allSchedules, taskClasses, extraItemCategories, windowDays), nil
 }

@@ -84,36 +116,43 @@ func (p *ScheduleProvider) LoadScheduleState(ctx context.Context, userID int) (*
 //   - weeks：窗口覆盖的周号（去重、升序），供按周加载日程使用；
 //   - 若无有效日期信息，返回空切片，调用方应降级到默认窗口。
 func buildWindowFromTaskClasses(taskClasses []model.TaskClass) (windowDays []WindowDay, weeks []int) {
-	var minDate, maxDate *time.Time
-	for _, tc := range taskClasses {
-		if tc.StartDate != nil && (minDate == nil || tc.StartDate.Before(*minDate)) {
-			t := *tc.StartDate
-			minDate = &t
-		}
-		if tc.EndDate != nil && (maxDate == nil || tc.EndDate.After(*maxDate)) {
-			t := *tc.EndDate
-			maxDate = &t
-		}
-	}
-	if minDate == nil || maxDate == nil {
-		return nil, nil
-	}
+	minWeek, minDay := 0, 0
+	maxWeek, maxDay := 0, 0
+	hasWindow := false

-	startWeek, startDay, err := RealDateToRelativeDate(minDate.Format(DateFormat))
-	if err != nil {
-		return nil, nil
+	for _, tc := range taskClasses {
+		// 1. 先要求任务类具备完整且合法的起止日期，避免坏数据把整轮窗口拖坏。
+		// 2. 再逐条做绝对日期 -> 相对周/天转换；转换失败的任务类直接忽略，不影响其余合法任务类。
+		// 3. 只有至少一条任务类成功进入窗口后，才返回有效 DayMapping。
+		if tc.StartDate == nil || tc.EndDate == nil || tc.EndDate.Before(*tc.StartDate) {
+			continue
+		}
+		startWeek, startDay, err := RealDateToRelativeDate(tc.StartDate.Format(DateFormat))
+		if err != nil {
+			continue
+		}
+		endWeek, endDay, err := RealDateToRelativeDate(tc.EndDate.Format(DateFormat))
+		if err != nil {
+			continue
+		}
+		if !hasWindow || isRelativeDateBefore(startWeek, startDay, minWeek, minDay) {
+			minWeek, minDay = startWeek, startDay
+		}
+		if !hasWindow || isRelativeDateBefore(maxWeek, maxDay, endWeek, endDay) {
+			maxWeek, maxDay = endWeek, endDay
+		}
+		hasWindow = true
 	}
-	endWeek, endDay, err := RealDateToRelativeDate(maxDate.Format(DateFormat))
-	if err != nil {
+	if !hasWindow {
 		return nil, nil
 	}

 	weeksSet := make(map[int]bool)
-	w, d := startWeek, startDay
+	w, d := minWeek, minDay
 	for {
 		windowDays = append(windowDays, WindowDay{Week: w, DayOfWeek: d})
 		weeksSet[w] = true
-		if w == endWeek && d == endDay {
+		if w == maxWeek && d == maxDay {
 			break
 		}
 		d++
@@ -121,7 +160,7 @@ func buildWindowFromTaskClasses(taskClasses []model.TaskClass) (windowDays []Win
 			d = 1
 			w++
 		}
-		if w > endWeek+1 { // 防止因日期转换异常导致无限循环
+		if w > maxWeek+1 { // 防止因日期转换异常导致无限循环
 			break
 		}
 	}
@@ -134,6 +173,28 @@ func buildWindowFromTaskClasses(taskClasses []model.TaskClass) (windowDays []Win
 	return windowDays, weeks
 }

+// buildCurrentWeekWindow 构造“当前周 7 天”的兜底窗口。
+func buildCurrentWeekWindow() (windowDays []WindowDay, weeks []int, err error) {
+	now := time.Now()
+	currentWeek, _, err := RealDateToRelativeDate(now.Format(DateFormat))
+	if err != nil {
+		return nil, nil, fmt.Errorf("解析当前日期失败: %w", err)
+	}
+	windowDays = make([]WindowDay, 7)
+	for i := 0; i < 7; i++ {
+		windowDays[i] = WindowDay{Week: currentWeek, DayOfWeek: i + 1}
+	}
+	return windowDays, []int{currentWeek}, nil
+}
+
+// isRelativeDateBefore 比较两个“相对周/天”坐标的先后关系。
+func isRelativeDateBefore(leftWeek, leftDay, rightWeek, rightDay int) bool {
+	if leftWeek != rightWeek {
+		return leftWeek < rightWeek
+	}
+	return leftDay < rightDay
+}
+
 // loadCompleteTaskClasses 批量加载用户所有任务类（含 Items 预加载）。
 func (p *ScheduleProvider) loadCompleteTaskClasses(ctx context.Context, userID int) ([]model.TaskClass, error) {
 	basicClasses, err := p.taskClassDAO.GetUserTaskClasses(userID)
@@ -156,6 +217,23 @@ func (p *ScheduleProvider) loadCompleteTaskClasses(ctx context.Context, userID i
 	return complete, nil
 }

+// loadCompleteTaskClassesByIDs 批量加载指定任务类（含 Items 预加载）。
+func (p *ScheduleProvider) loadCompleteTaskClassesByIDs(
+	ctx context.Context,
+	userID int,
+	taskClassIDs []int,
+) ([]model.TaskClass, error) {
+	if len(taskClassIDs) == 0 {
+		return nil, nil
+	}
+
+	complete, err := p.taskClassDAO.GetCompleteTaskClassesByIDs(ctx, userID, taskClassIDs)
+	if err != nil {
+		return nil, fmt.Errorf("加载指定任务类失败: %w", err)
+	}
+	return complete, nil
+}
+
 // LoadTaskClassMetas 加载指定任务类的约束元数据（不含 Items、不含日程），供 Plan 阶段提前消费。
 func (p *ScheduleProvider) LoadTaskClassMetas(ctx context.Context, userID int, taskClassIDs []int) ([]newagenttools.TaskClassMeta, error) {
 	if len(taskClassIDs) == 0 {