Version: 0.9.45.dev.260427

后端： 1. execute 主链路重构为“上下文工具域 + 主动优化候选闭环”——移除 order_guard，粗排后默认进入主动微调，先诊断再从后端候选中选择 move/swap，避免 LLM 自由全局乱搜 2. 工具体系升级为动态注入协议——新增 context_tools_add / remove、工具域与二级包映射、主动优化白名单；schedule / taskclass / web 工具按域按包暴露，msg0 规则包与 execute 上下文同步重写 3. analyze_health 升级为主动优化唯一裁判入口——补齐 rhythm / tightness / profile / feasibility 指标、候选扫描与复诊打分、停滞信号、forced imperfection 判定，并把连续优化状态写回运行态 4. 任务类能力并入新 Agent 执行链——新增 upsert_task_class 写工具与启动注入事务写入；任务类模型补充学科画像与整天屏蔽配置，粗排支持 excluded_days_of_week，steady 策略改为基于目标位置/单日负载/分散度/缓冲的候选打分 5. 运行态与路由补齐优化模式语义——新增 active tool domain/packs、pending context hook、active optimize only、taskclass 写入回盘快照；区分 first_full / global_reopt / local_adjust，并完善首次粗排后默认 refine 的判定前端： 6. 助手时间线渲染细化——推理内容改为独立 reasoning block，支持与工具/状态/正文按时序交错展示，自动收口折叠，修正 confirm reject 恢复动作仓库： 7. newAgent 文档整体迁入 docs/backend，补充主动优化执行规划与顺序约束拆解文档，删除旧调试日志文件 PS:这次科研了2天，总算是有些进展了——LLM永远只适合做选择题、判断题，不适合做开放创新题。
2026-04-27 01:09:37 +08:00
parent 04b5836b39
commit 66c06eed0a
60 changed files with 9163 additions and 1819 deletions
--- a/backend/newAgent/tools/registry.go
+++ b/backend/newAgent/tools/registry.go
@@ -10,36 +10,62 @@ import (
 	"github.com/LoveLosita/smartflow/backend/newAgent/tools/web"
 )

-// ToolHandler 是所有工具的统一执行签名。
+// ToolHandler 约定所有工具的统一执行签名。
+// 职责边界：
+// 1. 负责消费当前 ScheduleState 与模型传入参数；
+// 2. 返回统一 string 结果，供 execute 节点写回 observation；
+// 3. 不负责 confirm、上下文注入、轮次控制，这些由上层节点处理。
 type ToolHandler func(state *schedule.ScheduleState, args map[string]any) string

-// ToolSchemaEntry 是注入给模型的工具说明快照。
+// ToolSchemaEntry 描述注入给模型的工具快照。
 type ToolSchemaEntry struct {
 	Name       string
 	Desc       string
 	SchemaText string
 }

-// DefaultRegistryDeps 描述默认工具注册表可选依赖。
-//
-// 说明：
-// 1. 这层依赖注入先为后续 websearch / memory 工具预留统一入口；
-// 2. 当前即便部分依赖暂未使用，也不应让业务侧再自行 new 底层 Infra；
-// 3. 后续新增读工具时，应优先在这里扩展依赖而不是走包级全局变量。
+// DefaultRegistryDeps 描述默认注册表需要的外部依赖。
+// 职责边界：
+// 1. 这里只承载工具层需要的依赖注入，不承载业务状态；
+// 2. 某些依赖即便暂未使用也允许保留，避免业务层重新到处 new；
+// 3. 具体依赖缺失时由对应工具自行返回结构化失败结果。
 type DefaultRegistryDeps struct {
 	RAGRuntime infrarag.Runtime

-	// WebSearchProvider Web 搜索供应商。为 nil 时 web_search / web_fetch 返回"暂未启用"，不阻断主流程。
+	// WebSearchProvider 为 nil 时，web_search / web_fetch 仍会注册，
+	// 但 handler 会返回“暂未启用”的只读 observation，不阻断主流程。
 	WebSearchProvider web.SearchProvider
+
+	// TaskClassWriteDeps 供 upsert_task_class 调用持久化层。
+	TaskClassWriteDeps TaskClassWriteDeps
 }

-// ToolRegistry 管理工具注册、查找与执行。
+// ToolRegistry 管理工具注册、过滤与执行。
 type ToolRegistry struct {
 	handlers map[string]ToolHandler
 	schemas  []ToolSchemaEntry
 	deps     DefaultRegistryDeps
 }

+// temporaryDisabledTools 描述“已注册但当前阶段临时禁用”的工具。
+// 设计说明：
+// 1. 这些工具仍保留定义，避免 prompt / 旧链路 / 历史日志里出现悬空名字；
+// 2. execute 会在调用前统一阻断，并向模型返回纠错提示；
+// 3. ToolNames / Schemas 也会默认隐藏它们，避免继续污染 msg0。
+var temporaryDisabledTools = map[string]bool{
+	"min_context_switch": true,
+	"spread_even":        true,
+	"analyze_load":       true,
+	"analyze_subjects":   true,
+	"analyze_context":    true,
+	"analyze_tolerance":  true,
+}
+
+// IsTemporarilyDisabledTool 判断工具是否在当前阶段被临时禁用。
+func IsTemporarilyDisabledTool(name string) bool {
+	return temporaryDisabledTools[strings.TrimSpace(name)]
+}
+
 // NewToolRegistry 创建空注册表。
 func NewToolRegistry() *ToolRegistry {
 	return NewToolRegistryWithDeps(DefaultRegistryDeps{})
@@ -65,7 +91,14 @@ func (r *ToolRegistry) Register(name, desc, schemaText string, handler ToolHandl
 }

 // Execute 执行指定工具。
+// 职责边界：
+// 1. 这里只负责找到 handler 并调用；
+// 2. 若工具临时禁用，直接返回只读失败文案，不进入 handler；
+// 3. 不负责参数 schema 级纠错，具体参数错误交由 handler 返回。
 func (r *ToolRegistry) Execute(state *schedule.ScheduleState, toolName string, args map[string]any) string {
+	if r.IsToolTemporarilyDisabled(toolName) {
+		return fmt.Sprintf("工具 %q 当前阶段已临时禁用，请优先使用 analyze_health、move、swap 等当前主链工具。", strings.TrimSpace(toolName))
+	}
 	handler, ok := r.handlers[toolName]
 	if !ok {
 		return fmt.Sprintf("工具调用失败：未知工具 %q。可用工具：%s", toolName, strings.Join(r.ToolNames(), "、"))
@@ -73,41 +106,126 @@ func (r *ToolRegistry) Execute(state *schedule.ScheduleState, toolName string, a
 	return handler(state, args)
 }

-// HasTool 检查工具是否已注册。
+// HasTool 判断工具是否已注册且当前可见。
 func (r *ToolRegistry) HasTool(name string) bool {
+	if r.IsToolTemporarilyDisabled(name) {
+		return false
+	}
 	_, ok := r.handlers[name]
 	return ok
 }

-// ToolNames 返回已注册工具名（按 schema 顺序）。
+// IsToolTemporarilyDisabled 判断工具是否处于“已注册但暂不允许调用”状态。
+func (r *ToolRegistry) IsToolTemporarilyDisabled(name string) bool {
+	return IsTemporarilyDisabledTool(name)
+}
+
+// ToolNames 返回当前可暴露给模型的工具名。
 func (r *ToolRegistry) ToolNames() []string {
-	names := make([]string, 0, len(r.handlers))
+	names := make([]string, 0, len(r.schemas))
 	for _, item := range r.schemas {
+		if r.IsToolTemporarilyDisabled(item.Name) {
+			continue
+		}
 		names = append(names, item.Name)
 	}
 	return names
 }

-// Schemas 返回 schema 快照。
+// Schemas 返回当前可暴露给模型的 schema 快照。
 func (r *ToolRegistry) Schemas() []ToolSchemaEntry {
-	result := make([]ToolSchemaEntry, len(r.schemas))
-	copy(result, r.schemas)
+	result := make([]ToolSchemaEntry, 0, len(r.schemas))
+	for _, item := range r.schemas {
+		if r.IsToolTemporarilyDisabled(item.Name) {
+			continue
+		}
+		result = append(result, item)
+	}
 	return result
 }

-// IsWriteTool 判断工具是否是写工具（需要 confirm）。
+// SchemasForActiveDomain 返回某业务域当前真正可见的工具 schema。
+// 职责边界：
+// 1. context_tools_add/remove 始终保留，用于动态区协议；
+// 2. 仅当工具域已激活时，才暴露该域下可见工具；
+// 3. schedule 域支持按 pack 过滤；taskclass 目前只有 core。
+func (r *ToolRegistry) SchemasForActiveDomain(activeDomain string, activePacks []string) []ToolSchemaEntry {
+	normalizedDomain := NormalizeToolDomain(activeDomain)
+	effectivePacks := ResolveEffectiveToolPacks(normalizedDomain, activePacks)
+	effectivePackSet := make(map[string]struct{}, len(effectivePacks))
+	for _, pack := range effectivePacks {
+		effectivePackSet[pack] = struct{}{}
+	}
+
+	selected := make([]ToolSchemaEntry, 0, len(r.schemas))
+	for _, item := range r.schemas {
+		name := strings.TrimSpace(item.Name)
+		if r.IsToolTemporarilyDisabled(name) {
+			continue
+		}
+		if IsContextManagementTool(name) {
+			selected = append(selected, item)
+			continue
+		}
+		if normalizedDomain == "" {
+			continue
+		}
+
+		domain, pack, ok := ResolveToolDomainPack(name)
+		if !ok {
+			// 兼容历史未建档工具：仅在 schedule 域下继续暴露，避免突然失联。
+			if normalizedDomain == ToolDomainSchedule {
+				selected = append(selected, item)
+			}
+			continue
+		}
+		if domain != normalizedDomain {
+			continue
+		}
+		if IsFixedToolPack(domain, pack) {
+			selected = append(selected, item)
+			continue
+		}
+		if _, exists := effectivePackSet[pack]; exists {
+			selected = append(selected, item)
+		}
+	}
+
+	result := make([]ToolSchemaEntry, len(selected))
+	copy(result, selected)
+	return result
+}
+
+// IsToolVisibleInDomain 判断某工具在当前动态区下是否应对模型可见。
+func (r *ToolRegistry) IsToolVisibleInDomain(activeDomain string, activePacks []string, toolName string) bool {
+	name := strings.TrimSpace(toolName)
+	if name == "" {
+		return false
+	}
+	for _, item := range r.SchemasForActiveDomain(activeDomain, activePacks) {
+		if strings.TrimSpace(item.Name) == name {
+			return true
+		}
+	}
+	return false
+}
+
+// IsWriteTool 判断工具是否属于写工具。
 func (r *ToolRegistry) IsWriteTool(name string) bool {
-	return writeTools[name]
+	return writeTools[strings.TrimSpace(name)]
+}
+
+// IsScheduleMutationTool 判断工具是否会真实修改 ScheduleState 中的日程布局。
+// 说明：upsert_task_class 会写库，但不修改当前日程预览，因此不计入此集合。
+func (r *ToolRegistry) IsScheduleMutationTool(name string) bool {
+	return scheduleMutationTools[strings.TrimSpace(name)]
 }

 // RequiresScheduleState 判断工具是否依赖 ScheduleState。
-// 调用目的：execute 节点据此决定是否允许在 ScheduleState 为 nil 时调用该工具。
 func (r *ToolRegistry) RequiresScheduleState(name string) bool {
-	return !scheduleFreeTools[name]
+	return !scheduleFreeTools[strings.TrimSpace(name)]
 }

-// ==================== 写工具集合 ====================
-
 var writeTools = map[string]bool{
 	"place":                 true,
 	"move":                  true,
@@ -117,38 +235,83 @@ var writeTools = map[string]bool{
 	"spread_even":           true,
 	"min_context_switch":    true,
 	"unplace":               true,
+	"upsert_task_class":     true,
 }

-// ==================== 不依赖 ScheduleState 的工具集合 ====================
-// 调用目的：这些工具不需要日程状态即可执行，execute 节点在 ScheduleState 为 nil 时允许调用。
+var scheduleMutationTools = map[string]bool{
+	"place":                 true,
+	"move":                  true,
+	"swap":                  true,
+	"batch_move":            true,
+	"queue_apply_head_move": true,
+	"spread_even":           true,
+	"min_context_switch":    true,
+	"unplace":               true,
+}

+// scheduleFreeTools 描述“即使没有 ScheduleState 也能安全执行”的工具。
 var scheduleFreeTools = map[string]bool{
-	"web_search": true,
-	"web_fetch":  true,
+	"web_search":               true,
+	"web_fetch":                true,
+	"upsert_task_class":        true,
+	ToolNameContextToolsAdd:    true,
+	ToolNameContextToolsRemove: true,
 }

-// ==================== 默认注册表 ====================
-
-// NewDefaultRegistry 创建默认日程工具注册表。
+// NewDefaultRegistry 创建默认注册表。
 func NewDefaultRegistry() *ToolRegistry {
 	return NewDefaultRegistryWithDeps(DefaultRegistryDeps{})
 }

-// NewDefaultRegistryWithDeps 创建带依赖的默认日程工具注册表。
+// NewDefaultRegistryWithDeps 创建带依赖的默认注册表。
+// 步骤化说明：
+// 1. 先注册上下文管理工具，保证动态区协议随时可用；
+// 2. 再注册 schedule 域的读、诊断、写工具；
+// 3. 最后注册 taskclass 与 web 工具，并统一按 name 排序，保证 prompt 输出稳定。
 func NewDefaultRegistryWithDeps(deps DefaultRegistryDeps) *ToolRegistry {
 	r := NewToolRegistryWithDeps(deps)

-	// --- 读工具 ---
-	r.Register("get_overview",
-		"获取规划窗口总览（任务视角，全量返回）：保留课程占位统计，展开任务清单（过滤课程明细）。",
+	registerContextTools(r)
+	registerScheduleReadTools(r)
+	registerScheduleAnalyzeTools(r)
+	registerScheduleMutationTools(r)
+	registerTaskClassTools(r, deps)
+	registerWebTools(r, deps)
+
+	sort.Slice(r.schemas, func(i, j int) bool {
+		return r.schemas[i].Name < r.schemas[j].Name
+	})
+	return r
+}
+
+func registerContextTools(r *ToolRegistry) {
+	r.Register(
+		ToolNameContextToolsAdd,
+		"激活指定工具域，并可附带 schedule 二级包 packs。core 固定注入。",
+		`{"name":"context_tools_add","parameters":{"domain":{"type":"string","required":true,"enum":["schedule","taskclass"]},"packs":{"type":"array","items":{"type":"string","enum":["mutation","analyze","detail_read","deep_analyze","queue","web"]}},"mode":{"type":"string","enum":["replace","merge"]}}}`,
+		NewContextToolsAddHandler(),
+	)
+	r.Register(
+		ToolNameContextToolsRemove,
+		"移除指定工具域、指定二级包，或清空全部业务工具域（all=true）。core 固定包不支持 remove。",
+		`{"name":"context_tools_remove","parameters":{"domain":{"type":"string","enum":["schedule","taskclass","all"]},"packs":{"type":"array","items":{"type":"string","enum":["mutation","analyze","detail_read","deep_analyze","queue","web"]}},"all":{"type":"bool"}}}`,
+		NewContextToolsRemoveHandler(),
+	)
+}
+
+func registerScheduleReadTools(r *ToolRegistry) {
+	r.Register(
+		"get_overview",
+		"获取当前窗口总览：保留课程占位统计，展开任务清单。",
 		`{"name":"get_overview","parameters":{}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
+			_ = args
 			return schedule.GetOverview(state)
 		},
 	)
-
-	r.Register("query_range",
-		"查看某天或某时段的细粒度占用详情。day 必填，slot_start/slot_end 选填（不填查整天）。",
+	r.Register(
+		"query_range",
+		"查看某天或某时段的占用详情。day 必填，slot_start/slot_end 选填。",
 		`{"name":"query_range","parameters":{"day":{"type":"int","required":true},"slot_start":{"type":"int"},"slot_end":{"type":"int"}}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
 			day, ok := schedule.ArgsInt(args, "day")
@@ -158,41 +321,41 @@ func NewDefaultRegistryWithDeps(deps DefaultRegistryDeps) *ToolRegistry {
 			return schedule.QueryRange(state, day, schedule.ArgsIntPtr(args, "slot_start"), schedule.ArgsIntPtr(args, "slot_end"))
 		},
 	)
-
-	r.Register("query_available_slots",
-		"查询候选空位池（先返回纯空位，不足再补可嵌入位），适合 move 前的落点筛选。",
+	r.Register(
+		"query_available_slots",
+		"查询候选空位池，适合 move 前筛落点。",
 		`{"name":"query_available_slots","parameters":{"span":{"type":"int"},"duration":{"type":"int"},"limit":{"type":"int"},"allow_embed":{"type":"bool"},"day":{"type":"int"},"day_start":{"type":"int"},"day_end":{"type":"int"},"day_scope":{"type":"string","enum":["all","workday","weekend"]},"day_of_week":{"type":"array","items":{"type":"int"}},"week":{"type":"int"},"week_filter":{"type":"array","items":{"type":"int"}},"week_from":{"type":"int"},"week_to":{"type":"int"},"slot_type":{"type":"string"},"slot_types":{"type":"array","items":{"type":"string"}},"exclude_sections":{"type":"array","items":{"type":"int"}},"after_section":{"type":"int"},"before_section":{"type":"int"},"section_from":{"type":"int"},"section_to":{"type":"int"}}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
 			return schedule.QueryAvailableSlots(state, args)
 		},
 	)
-
-	r.Register("query_target_tasks",
-		"查询候选任务集合，可按 status/week/day/task_id/category 筛选；默认自动入队，供后续 queue_pop_head 逐项处理。",
+	r.Register(
+		"query_target_tasks",
+		"查询候选任务集合，可按 status/week/day/task_id/category 筛选；支持 enqueue。",
 		`{"name":"query_target_tasks","parameters":{"status":{"type":"string","enum":["all","existing","suggested","pending"]},"category":{"type":"string"},"limit":{"type":"int"},"day_scope":{"type":"string","enum":["all","workday","weekend"]},"day":{"type":"int"},"day_start":{"type":"int"},"day_end":{"type":"int"},"day_of_week":{"type":"array","items":{"type":"int"}},"week":{"type":"int"},"week_filter":{"type":"array","items":{"type":"int"}},"week_from":{"type":"int"},"week_to":{"type":"int"},"task_ids":{"type":"array","items":{"type":"int"}},"task_id":{"type":"int"},"task_item_ids":{"type":"array","items":{"type":"int"}},"task_item_id":{"type":"int"},"enqueue":{"type":"bool"},"reset_queue":{"type":"bool"}}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
 			return schedule.QueryTargetTasks(state, args)
 		},
 	)
-
-	r.Register("queue_pop_head",
-		"弹出并返回当前队首任务；若已有 current 则复用，保证一次只处理一个任务。",
+	r.Register(
+		"queue_pop_head",
+		"弹出并返回当前队首任务；若已有 current 则复用。",
 		`{"name":"queue_pop_head","parameters":{}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
 			return schedule.QueuePopHead(state, args)
 		},
 	)
-
-	r.Register("queue_status",
-		"查看当前待处理队列状态（pending/current/completed/skipped）。",
+	r.Register(
+		"queue_status",
+		"查看当前队列状态（pending/current/completed/skipped）。",
 		`{"name":"queue_status","parameters":{}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
 			return schedule.QueueStatus(state, args)
 		},
 	)
-
-	r.Register("get_task_info",
-		"查询单个任务详细信息，包括类别、状态、占用时段、嵌入关系。",
+	r.Register(
+		"get_task_info",
+		"查看单个任务详情，包括类别、状态与落位。",
 		`{"name":"get_task_info","parameters":{"task_id":{"type":"int","required":true}}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
 			taskID, ok := schedule.ArgsInt(args, "task_id")
@@ -202,10 +365,63 @@ func NewDefaultRegistryWithDeps(deps DefaultRegistryDeps) *ToolRegistry {
 			return schedule.GetTaskInfo(state, taskID)
 		},
 	)
+}

-	// --- 写工具 ---
-	r.Register("place",
-		"将一个待安排任务预排到指定位置。自动检测可嵌入宿主。task_id/day/slot_start 必填。",
+func registerScheduleAnalyzeTools(r *ToolRegistry) {
+	r.Register(
+		"analyze_load",
+		"分析整体负载分布（当前阶段已临时禁用，仅保留定义）。",
+		`{"name":"analyze_load","parameters":{"scope":{"type":"string","enum":["full","week","day_range"]},"week_from":{"type":"int"},"week_to":{"type":"int"},"day_from":{"type":"int"},"day_to":{"type":"int"},"granularity":{"type":"string","enum":["day","week","time_of_day"]},"detail":{"type":"string","enum":["summary","full"]}}}`,
+		func(state *schedule.ScheduleState, args map[string]any) string {
+			return schedule.AnalyzeLoad(state, args)
+		},
+	)
+	r.Register(
+		"analyze_subjects",
+		"分析学科分布与连贯性（当前阶段已临时禁用，仅保留定义）。",
+		`{"name":"analyze_subjects","parameters":{"category":{"type":"string"},"include_pending":{"type":"bool"},"detail":{"type":"string","enum":["summary","full"]}}}`,
+		func(state *schedule.ScheduleState, args map[string]any) string {
+			return schedule.AnalyzeSubjects(state, args)
+		},
+	)
+	r.Register(
+		"analyze_context",
+		"分析上下文切换与相邻关系（当前阶段已临时禁用，仅保留定义）。",
+		`{"name":"analyze_context","parameters":{"day_from":{"type":"int"},"day_to":{"type":"int"},"detail":{"type":"string","enum":["summary","day_detail"]},"hard_categories":{"type":"array","items":{"type":"string"}}}}`,
+		func(state *schedule.ScheduleState, args map[string]any) string {
+			return schedule.AnalyzeContext(state, args)
+		},
+	)
+	r.Register(
+		"analyze_rhythm",
+		"分析学习节奏与切换情况。",
+		`{"name":"analyze_rhythm","parameters":{"category":{"type":"string"},"include_pending":{"type":"bool"},"detail":{"type":"string","enum":["summary","full"]},"hard_categories":{"type":"array","items":{"type":"string"}}}}`,
+		func(state *schedule.ScheduleState, args map[string]any) string {
+			return schedule.AnalyzeRhythm(state, args)
+		},
+	)
+	r.Register(
+		"analyze_tolerance",
+		"分析局部容错与调整空间。",
+		`{"name":"analyze_tolerance","parameters":{"scope":{"type":"string","enum":["full","week","day_range"]},"week_from":{"type":"int"},"week_to":{"type":"int"},"day_from":{"type":"int"},"day_to":{"type":"int"},"min_usable_size":{"type":"int"},"min_daily_buffer":{"type":"int"},"detail":{"type":"string","enum":["summary","full"]}}}`,
+		func(state *schedule.ScheduleState, args map[string]any) string {
+			return schedule.AnalyzeTolerance(state, args)
+		},
+	)
+	r.Register(
+		"analyze_health",
+		"主动优化裁判入口：聚焦 rhythm/semantic_profile/tightness，判断当前是否还值得继续优化，并给出候选。",
+		`{"name":"analyze_health","parameters":{"detail":{"type":"string","enum":["summary","full"]},"dimensions":{"type":"array","items":{"type":"string"}},"threshold":{"type":"string","enum":["strict","normal","relaxed"]}}}`,
+		func(state *schedule.ScheduleState, args map[string]any) string {
+			return schedule.AnalyzeHealth(state, args)
+		},
+	)
+}
+
+func registerScheduleMutationTools(r *ToolRegistry) {
+	r.Register(
+		"place",
+		"将一个待安排任务预排到指定位置。task_id/day/slot_start 必填。",
 		`{"name":"place","parameters":{"task_id":{"type":"int","required":true},"day":{"type":"int","required":true},"slot_start":{"type":"int","required":true}}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
 			taskID, ok := schedule.ArgsInt(args, "task_id")
@@ -223,9 +439,9 @@ func NewDefaultRegistryWithDeps(deps DefaultRegistryDeps) *ToolRegistry {
 			return schedule.Place(state, taskID, day, slotStart)
 		},
 	)
-
-	r.Register("move",
-		"将一个已预排任务（仅 suggested）移动到新位置。existing 属于已安排事实层，不参与 move。task_id/new_day/new_slot_start 必填。",
+	r.Register(
+		"move",
+		"将一个已预排任务（仅 suggested）移动到新位置。task_id/new_day/new_slot_start 必填。",
 		`{"name":"move","parameters":{"task_id":{"type":"int","required":true},"new_day":{"type":"int","required":true},"new_slot_start":{"type":"int","required":true}}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
 			taskID, ok := schedule.ArgsInt(args, "task_id")
@@ -243,9 +459,9 @@ func NewDefaultRegistryWithDeps(deps DefaultRegistryDeps) *ToolRegistry {
 			return schedule.Move(state, taskID, newDay, newSlotStart)
 		},
 	)
-
-	r.Register("swap",
-		"交换两个已落位任务的位置。两个任务必须时长相同。task_a/task_b 必填。",
+	r.Register(
+		"swap",
+		"交换两个已落位任务的位置。task_a/task_b 必填，且两任务时长必须一致。",
 		`{"name":"swap","parameters":{"task_a":{"type":"int","required":true},"task_b":{"type":"int","required":true}}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
 			taskA, ok := schedule.ArgsInt(args, "task_a")
@@ -259,9 +475,9 @@ func NewDefaultRegistryWithDeps(deps DefaultRegistryDeps) *ToolRegistry {
 			return schedule.Swap(state, taskA, taskB)
 		},
 	)
-
-	r.Register("batch_move",
-		"原子性批量移动多个任务（仅 suggested，最多2条），全部成功才生效。若含 existing/pending 或任一冲突将整批失败回滚。",
+	r.Register(
+		"batch_move",
+		"原子性批量移动多个任务。moves 必填。",
 		`{"name":"batch_move","parameters":{"moves":{"type":"array","required":true,"items":{"task_id":"int","new_day":"int","new_slot_start":"int"}}}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
 			moves, err := schedule.ArgsMoveList(args)
@@ -271,25 +487,25 @@ func NewDefaultRegistryWithDeps(deps DefaultRegistryDeps) *ToolRegistry {
 			return schedule.BatchMove(state, moves)
 		},
 	)
-
-	r.Register("queue_apply_head_move",
-		"将当前队首任务移动到指定位置并自动出队。仅作用于 current，不接受 task_id。new_day/new_slot_start 必填。",
+	r.Register(
+		"queue_apply_head_move",
+		"将当前队首任务移动到指定位置并自动出队。new_day/new_slot_start 必填。",
 		`{"name":"queue_apply_head_move","parameters":{"new_day":{"type":"int","required":true},"new_slot_start":{"type":"int","required":true}}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
 			return schedule.QueueApplyHeadMove(state, args)
 		},
 	)
-
-	r.Register("queue_skip_head",
-		"跳过当前队首任务（不改日程），将其标记为 skipped 并继续后续队列。",
+	r.Register(
+		"queue_skip_head",
+		"跳过当前队首任务，将其标记为 skipped。",
 		`{"name":"queue_skip_head","parameters":{"reason":{"type":"string"}}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
 			return schedule.QueueSkipHead(state, args)
 		},
 	)
-
-	r.Register("min_context_switch",
-		"在指定任务集合内重排 suggested 任务，尽量让同类任务连续以减少上下文切换。仅在用户明确允许打乱顺序时使用。task_ids 必填（兼容 task_id）。",
+	r.Register(
+		"min_context_switch",
+		"在指定任务集合内减少上下文切换（当前阶段已临时禁用，仅保留定义）。",
 		`{"name":"min_context_switch","parameters":{"task_ids":{"type":"array","required":true,"items":{"type":"int"}},"task_id":{"type":"int"}}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
 			taskIDs, err := schedule.ParseMinContextSwitchTaskIDs(args)
@@ -299,9 +515,9 @@ func NewDefaultRegistryWithDeps(deps DefaultRegistryDeps) *ToolRegistry {
 			return schedule.MinContextSwitch(state, taskIDs)
 		},
 	)
-
-	r.Register("spread_even",
-		"在给定任务集合内做均匀化铺开：先按筛选条件收集候选坑位，再规划并原子落地。task_ids 必填（兼容 task_id）。",
+	r.Register(
+		"spread_even",
+		"在给定任务集合内做均匀化铺开（当前阶段已临时禁用，仅保留定义）。",
 		`{"name":"spread_even","parameters":{"task_ids":{"type":"array","required":true,"items":{"type":"int"}},"task_id":{"type":"int"},"limit":{"type":"int"},"allow_embed":{"type":"bool"},"day":{"type":"int"},"day_start":{"type":"int"},"day_end":{"type":"int"},"day_scope":{"type":"string","enum":["all","workday","weekend"]},"day_of_week":{"type":"array","items":{"type":"int"}},"week":{"type":"int"},"week_filter":{"type":"array","items":{"type":"int"}},"week_from":{"type":"int"},"week_to":{"type":"int"},"slot_type":{"type":"string"},"slot_types":{"type":"array","items":{"type":"string"}},"exclude_sections":{"type":"array","items":{"type":"int"}},"after_section":{"type":"int"},"before_section":{"type":"int"}}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
 			taskIDs, err := schedule.ParseSpreadEvenTaskIDs(args)
@@ -311,9 +527,9 @@ func NewDefaultRegistryWithDeps(deps DefaultRegistryDeps) *ToolRegistry {
 			return schedule.SpreadEven(state, taskIDs, args)
 		},
 	)
-
-	r.Register("unplace",
-		"将一个已落位任务移除，恢复为待安排状态。会自动清理嵌入关系。task_id 必填。",
+	r.Register(
+		"unplace",
+		"将一个已落位任务移除，恢复为待安排状态。task_id 必填。",
 		`{"name":"unplace","parameters":{"task_id":{"type":"int","required":true}}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
 			taskID, ok := schedule.ArgsInt(args, "task_id")
@@ -323,33 +539,37 @@ func NewDefaultRegistryWithDeps(deps DefaultRegistryDeps) *ToolRegistry {
 			return schedule.Unplace(state, taskID)
 		},
 	)
+}

-	// --- Web 搜索读工具 ---
-	// 1. provider 为 nil 时 handler 返回"暂未启用"的 observation，不会阻断主流程；
-	// 2. 两个工具均为读操作，走 action=continue + tool_call 模式。
+func registerTaskClassTools(r *ToolRegistry, deps DefaultRegistryDeps) {
+	r.Register(
+		"upsert_task_class",
+		"创建或更新任务类（统一写入口，必须 confirm）。auto 模式下 start_date/end_date 必须在 task_class 顶层字段。",
+		`{"name":"upsert_task_class","parameters":{"id":{"type":"int"},"task_class":{"type":"object","required":true},"items":{"type":"array","items":{"type":"object"}},"source":{"type":"string"}}}`,
+		NewTaskClassUpsertToolHandler(deps.TaskClassWriteDeps),
+	)
+}
+
+func registerWebTools(r *ToolRegistry, deps DefaultRegistryDeps) {
 	webSearchHandler := web.NewSearchToolHandler(deps.WebSearchProvider)
 	webFetchHandler := web.NewFetchToolHandler(web.NewFetcher())

-	r.Register("web_search",
-		"Web 搜索：根据 query 返回结构化检索结果（标题/摘要/URL/来源域名/时间）。query 必填。",
+	r.Register(
+		"web_search",
+		"Web 搜索：根据 query 返回结构化检索结果。query 必填。",
 		`{"name":"web_search","parameters":{"query":{"type":"string","required":true},"top_k":{"type":"int"},"domain_allow":{"type":"array","items":{"type":"string"}},"recency_days":{"type":"int"}}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
+			_ = state
 			return webSearchHandler.Handle(args)
 		},
 	)
-
-	r.Register("web_fetch",
-		"抓取指定 URL 的正文内容并做最小 HTML 清洗。url 必填。",
+	r.Register(
+		"web_fetch",
+		"抓取指定 URL 的正文内容并做最小清洗。url 必填。",
 		`{"name":"web_fetch","parameters":{"url":{"type":"string","required":true},"max_chars":{"type":"int"}}}`,
 		func(state *schedule.ScheduleState, args map[string]any) string {
+			_ = state
 			return webFetchHandler.Handle(args)
 		},
 	)
-
-	// 按 schema name 排序，确保输出稳定。
-	sort.Slice(r.schemas, func(i, j int) bool {
-		return r.schemas[i].Name < r.schemas[j].Name
-	})
-
-	return r
 }