Version: 0.8.3.dev.260328

后端： 1.彻底删除原agent文件夹，并将现agent2文件夹全量重命名为agent(包括全部涉及到的文件以及文档、注释)，迁移工作完美结束 2.修复了重试消息的相关逻辑问题前端： 1.改善了一些交互体验，修复了一些bug，现在只剩少的功能了，现存的bug基本都修复完毕全仓库： 1.更新了决策记录和README文档
2026-03-28 18:00:31 +08:00
parent 5fc9548420
commit 468367d617
108 changed files with 1910 additions and 17173 deletions
--- a/backend/agent/llm/ark.go
+++ b/backend/agent/llm/ark.go
@@ -0,0 +1,83 @@
+package agentllm
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	"github.com/cloudwego/eino-ext/components/model/ark"
+	einoModel "github.com/cloudwego/eino/components/model"
+	"github.com/cloudwego/eino/schema"
+	arkModel "github.com/volcengine/volcengine-go-sdk/service/arkruntime/model"
+)
+
+// ArkCallOptions 是基于 ark.ChatModel 的通用调用选项。
+//
+// 设计目的：
+// 1. 当前 route / quicknote 都还直接持有 *ark.ChatModel；
+// 2. 在它们完全收敛到更抽象的 Client 前，先把重复的 ark 调用样板抽成公共层；
+// 3. 这样本轮就能先删除 route/quicknote 里那几份重复的 Generate 样板代码。
+type ArkCallOptions struct {
+	Temperature float64
+	MaxTokens   int
+	Thinking    ThinkingMode
+}
+
+// CallArkText 调用 ark 模型并返回纯文本。
+//
+// 职责边界：
+// 1. 负责拼 system + user 两段消息；
+// 2. 负责统一配置 thinking / temperature / maxTokens；
+// 3. 负责拦截空响应；
+// 4. 不负责 JSON 解析，不负责业务字段校验。
+func CallArkText(ctx context.Context, chatModel *ark.ChatModel, systemPrompt, userPrompt string, options ArkCallOptions) (string, error) {
+	if chatModel == nil {
+		return "", errors.New("ark model is nil")
+	}
+
+	messages := []*schema.Message{
+		schema.SystemMessage(systemPrompt),
+		schema.UserMessage(userPrompt),
+	}
+	resp, err := chatModel.Generate(ctx, messages, buildArkOptions(options)...)
+	if err != nil {
+		return "", err
+	}
+	if resp == nil {
+		return "", errors.New("模型返回为空")
+	}
+
+	text := strings.TrimSpace(resp.Content)
+	if text == "" {
+		return "", errors.New("模型返回内容为空")
+	}
+	return text, nil
+}
+
+// CallArkJSON 调用 ark 模型并直接解析 JSON。
+func CallArkJSON[T any](ctx context.Context, chatModel *ark.ChatModel, systemPrompt, userPrompt string, options ArkCallOptions) (*T, string, error) {
+	raw, err := CallArkText(ctx, chatModel, systemPrompt, userPrompt, options)
+	if err != nil {
+		return nil, "", err
+	}
+	parsed, err := ParseJSONObject[T](raw)
+	if err != nil {
+		return nil, raw, err
+	}
+	return parsed, raw, nil
+}
+
+func buildArkOptions(options ArkCallOptions) []einoModel.Option {
+	thinkingType := arkModel.ThinkingTypeDisabled
+	if options.Thinking == ThinkingModeEnabled {
+		thinkingType = arkModel.ThinkingTypeEnabled
+	}
+	opts := []einoModel.Option{
+		ark.WithThinking(&arkModel.Thinking{Type: thinkingType}),
+		einoModel.WithTemperature(float32(options.Temperature)),
+	}
+	if options.MaxTokens > 0 {
+		opts = append(opts, einoModel.WithMaxTokens(options.MaxTokens))
+	}
+	return opts
+}
--- a/backend/agent/llm/client.go
+++ b/backend/agent/llm/client.go
@@ -0,0 +1,216 @@
+package agentllm
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/cloudwego/eino/schema"
+)
+
+// ThinkingMode 描述本次模型调用对 thinking 的期望。
+//
+// 职责边界：
+// 1. 这里只表达“调用方希望怎样配置推理模式”；
+// 2. 不直接绑定某个具体模型厂商的参数枚举；
+// 3. 真正如何把它翻译成 ark / OpenAI / 其他 provider 的 option，由后续适配层负责。
+type ThinkingMode string
+
+const (
+	ThinkingModeDefault  ThinkingMode = "default"
+	ThinkingModeEnabled  ThinkingMode = "enabled"
+	ThinkingModeDisabled ThinkingMode = "disabled"
+)
+
+// GenerateOptions 是 Agent 内部统一的模型调用选项。
+//
+// 设计目的：
+// 1. 先把“每个 skill 都会反复传的参数”收敛成一份结构；
+// 2. 让 node 层以后只表达“我要什么”，不再自己重复组织 option；
+// 3. 暂时不追求覆盖所有 provider 参数，先把最常用的几个公共位抽出来。
+type GenerateOptions struct {
+	Temperature float64
+	MaxTokens   int
+	Thinking    ThinkingMode
+	Metadata    map[string]any
+}
+
+// TextResult 是统一文本生成结果。
+//
+// 职责边界：
+// 1. Text 保存模型最终返回的纯文本；
+// 2. Usage 保存本次调用的 token 使用量，供后续统一统计；
+// 3. 不负责 JSON 解析，不负责业务字段映射。
+type TextResult struct {
+	Text  string
+	Usage *schema.TokenUsage
+}
+
+// StreamReader 抽象了“可逐块 Recv 的流式返回器”。
+//
+// 之所以不直接依赖某个具体 SDK 的 reader 类型，是因为 Agent 现在还在建骨架阶段，
+// 后续接 ark、OpenAI 兼容层还是别的 provider，都可以往这个最小接口上适配。
+type StreamReader interface {
+	Recv() (*schema.Message, error)
+	Close() error
+}
+
+// TextGenerateFunc 是文本生成的统一适配函数签名。
+type TextGenerateFunc func(ctx context.Context, messages []*schema.Message, options GenerateOptions) (*TextResult, error)
+
+// StreamGenerateFunc 是流式生成的统一适配函数签名。
+type StreamGenerateFunc func(ctx context.Context, messages []*schema.Message, options GenerateOptions) (StreamReader, error)
+
+// Client 是 Agent 里的统一模型客户端门面。
+//
+// 职责边界：
+// 1. 负责把 node 层的“模型调用意图”收敛到统一入口；
+// 2. 负责统一参数校验、空响应防御、GenerateJSON 复用；
+// 3. 不负责写 prompt，不负责业务 fallback，也不直接持有具体厂商 SDK 细节。
+type Client struct {
+	generateText TextGenerateFunc
+	streamText   StreamGenerateFunc
+}
+
+// NewClient 创建统一模型客户端。
+func NewClient(generateText TextGenerateFunc, streamText StreamGenerateFunc) *Client {
+	return &Client{
+		generateText: generateText,
+		streamText:   streamText,
+	}
+}
+
+// GenerateText 执行一次统一文本生成。
+//
+// 职责边界：
+// 1. 负责做最小必要的入参校验；
+// 2. 负责统一拦截“模型空响应”这类公共问题；
+// 3. 不负责业务 prompt 拼接，也不负责把文本再映射成业务结构。
+func (c *Client) GenerateText(ctx context.Context, messages []*schema.Message, options GenerateOptions) (*TextResult, error) {
+	if c == nil || c.generateText == nil {
+		return nil, errors.New("agent llm client is not ready")
+	}
+	if len(messages) == 0 {
+		return nil, errors.New("llm messages is empty")
+	}
+
+	result, err := c.generateText(ctx, messages, options)
+	if err != nil {
+		return nil, err
+	}
+	if result == nil {
+		return nil, errors.New("llm result is nil")
+	}
+	if strings.TrimSpace(result.Text) == "" {
+		return nil, errors.New("llm returned empty text")
+	}
+	return result, nil
+}
+
+// GenerateJSON 先走统一文本生成，再走统一 JSON 解析。
+//
+// 设计说明：
+// 1. 旧 agent 里每个 skill 都各自写了一份“Generate -> 提取 JSON -> 反序列化”；
+// 2. 这里先把这一整段收敛成公共链路，后续 quicknote/taskquery/schedule 都直接复用；
+// 3. 返回 parsed + rawResult，方便上层既能拿结构化字段，也能在打点/回退时保留原文。
+// 4. 这里做成泛型函数而不是方法，是因为 Go 不支持“方法自带类型参数”。
+func GenerateJSON[T any](ctx context.Context, client *Client, messages []*schema.Message, options GenerateOptions) (*T, *TextResult, error) {
+	result, err := client.GenerateText(ctx, messages, options)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	parsed, err := ParseJSONObject[T](result.Text)
+	if err != nil {
+		return nil, result, err
+	}
+	return parsed, result, nil
+}
+
+// Stream 打开统一流式调用入口。
+//
+// 职责边界：
+// 1. 只负责把“流式生成能力”暴露给上层；
+// 2. 不负责 chunk 到 OpenAI 协议的转换，那部分应放在 stream/；
+// 3. 不负责累计全文，也不负责 token 统计落库。
+func (c *Client) Stream(ctx context.Context, messages []*schema.Message, options GenerateOptions) (StreamReader, error) {
+	if c == nil || c.streamText == nil {
+		return nil, errors.New("agent llm stream client is not ready")
+	}
+	if len(messages) == 0 {
+		return nil, errors.New("llm messages is empty")
+	}
+	return c.streamText(ctx, messages, options)
+}
+
+// BuildSystemUserMessages 构造最常见的“system + history + user”消息列表。
+//
+// 设计说明：
+// 1. 这是旧 agent 中高频重复片段，几乎每个 skill 都会拼一次；
+// 2. 这里先把最稳定的消息编排方式沉淀下来，减少 node 层样板代码；
+// 3. 只做消息切片装配，不做 prompt 生成。
+func BuildSystemUserMessages(systemPrompt string, history []*schema.Message, userPrompt string) []*schema.Message {
+	messages := make([]*schema.Message, 0, len(history)+2)
+	if strings.TrimSpace(systemPrompt) != "" {
+		messages = append(messages, schema.SystemMessage(systemPrompt))
+	}
+	if len(history) > 0 {
+		messages = append(messages, history...)
+	}
+	if strings.TrimSpace(userPrompt) != "" {
+		messages = append(messages, schema.UserMessage(userPrompt))
+	}
+	return messages
+}
+
+// CloneUsage 深拷贝 token usage，避免后续多处累加时共享同一指针。
+func CloneUsage(usage *schema.TokenUsage) *schema.TokenUsage {
+	if usage == nil {
+		return nil
+	}
+	copied := *usage
+	return &copied
+}
+
+// MergeUsage 合并两段 usage。
+//
+// 合并策略：
+// 1. 对“同一次调用不同流分片”的场景，取更大值作为最终值；
+// 2. 对“多次独立调用累计”的场景，应由上层显式做加法，而不是用这个函数；
+// 3. 该函数只适用于“同一次调用的分块 usage 收敛”。
+func MergeUsage(base *schema.TokenUsage, incoming *schema.TokenUsage) *schema.TokenUsage {
+	if incoming == nil {
+		return CloneUsage(base)
+	}
+	if base == nil {
+		return CloneUsage(incoming)
+	}
+
+	merged := *base
+	if incoming.PromptTokens > merged.PromptTokens {
+		merged.PromptTokens = incoming.PromptTokens
+	}
+	if incoming.CompletionTokens > merged.CompletionTokens {
+		merged.CompletionTokens = incoming.CompletionTokens
+	}
+	if incoming.TotalTokens > merged.TotalTokens {
+		merged.TotalTokens = incoming.TotalTokens
+	}
+	if incoming.PromptTokenDetails.CachedTokens > merged.PromptTokenDetails.CachedTokens {
+		merged.PromptTokenDetails.CachedTokens = incoming.PromptTokenDetails.CachedTokens
+	}
+	if incoming.CompletionTokensDetails.ReasoningTokens > merged.CompletionTokensDetails.ReasoningTokens {
+		merged.CompletionTokensDetails.ReasoningTokens = incoming.CompletionTokensDetails.ReasoningTokens
+	}
+	return &merged
+}
+
+// FormatEmptyResponseError 统一生成“模型返回空结果”的错误文案。
+func FormatEmptyResponseError(scene string) error {
+	scene = strings.TrimSpace(scene)
+	if scene == "" {
+		scene = "unknown"
+	}
+	return fmt.Errorf("模型在 %s 场景返回空结果", scene)
+}
--- a/backend/agent/llm/json.go
+++ b/backend/agent/llm/json.go
@@ -0,0 +1,112 @@
+package agentllm
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+)
+
+// ParseJSONObject 解析模型返回中的 JSON 对象。
+//
+// 职责边界：
+// 1. 负责处理“模型输出前后夹杂解释文字 / markdown 代码块”的常见情况；
+// 2. 负责提取最外层 JSON object 并反序列化为目标结构；
+// 3. 不负责业务字段合法性校验，例如 priority 是否在 1~4，应由上层 node 再校验。
+func ParseJSONObject[T any](raw string) (*T, error) {
+	clean := strings.TrimSpace(raw)
+	if clean == "" {
+		return nil, errors.New("模型返回为空，无法解析 JSON")
+	}
+
+	objectText := ExtractJSONObject(clean)
+	if objectText == "" {
+		return nil, fmt.Errorf("模型返回中未找到 JSON 对象: %s", truncateForError(clean))
+	}
+
+	var out T
+	if err := json.Unmarshal([]byte(objectText), &out); err != nil {
+		return nil, fmt.Errorf("JSON 解析失败: %w", err)
+	}
+	return &out, nil
+}
+
+// ExtractJSONObject 从混合文本里提取第一个完整 JSON 对象。
+//
+// 设计说明：
+// 1. LLM 很容易输出“这里是结果：{...}”这种半结构化文本；
+// 2. 这里用括号计数而不是正则，避免嵌套对象一多就误截断；
+// 3. 目前只提取 object，不提取 array，因为当前 agent 的路由/规划契约基本都是对象。
+func ExtractJSONObject(text string) string {
+	clean := trimMarkdownCodeFence(strings.TrimSpace(text))
+	if clean == "" {
+		return ""
+	}
+
+	start := strings.Index(clean, "{")
+	if start < 0 {
+		return ""
+	}
+
+	depth := 0
+	inString := false
+	escaped := false
+	for idx := start; idx < len(clean); idx++ {
+		ch := clean[idx]
+
+		if escaped {
+			escaped = false
+			continue
+		}
+		if ch == '\\' && inString {
+			escaped = true
+			continue
+		}
+		if ch == '"' {
+			inString = !inString
+			continue
+		}
+		if inString {
+			continue
+		}
+
+		switch ch {
+		case '{':
+			depth++
+		case '}':
+			depth--
+			if depth == 0 {
+				return clean[start : idx+1]
+			}
+		}
+	}
+	return ""
+}
+
+func trimMarkdownCodeFence(text string) string {
+	trimmed := strings.TrimSpace(text)
+	if !strings.HasPrefix(trimmed, "```") {
+		return trimmed
+	}
+
+	lines := strings.Split(trimmed, "\n")
+	if len(lines) == 0 {
+		return trimmed
+	}
+
+	// 1. 去掉首行 ```json / ```；
+	// 2. 若末行是 ```，一并去掉；
+	// 3. 中间正文保持原样，避免破坏 JSON 的换行结构。
+	body := lines[1:]
+	if len(body) > 0 && strings.TrimSpace(body[len(body)-1]) == "```" {
+		body = body[:len(body)-1]
+	}
+	return strings.TrimSpace(strings.Join(body, "\n"))
+}
+
+func truncateForError(text string) string {
+	if len(text) <= 160 {
+		return text
+	}
+	return text[:160] + "..."
+}
--- a/backend/agent/llm/quicknote.go
+++ b/backend/agent/llm/quicknote.go
@@ -0,0 +1,170 @@
+package agentllm
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	agentprompt "github.com/LoveLosita/smartflow/backend/agent/prompt"
+	"github.com/cloudwego/eino-ext/components/model/ark"
+)
+
+// QuickNoteIntentOutput 是“随口记意图识别”模型契约。
+type QuickNoteIntentOutput struct {
+	IsQuickNote bool   `json:"is_quick_note"`
+	Title       string `json:"title"`
+	DeadlineAt  string `json:"deadline_at"`
+	Reason      string `json:"reason"`
+}
+
+// QuickNotePriorityOutput 是“随口记优先级评估”模型契约。
+type QuickNotePriorityOutput struct {
+	PriorityGroup      int    `json:"priority_group"`
+	Reason             string `json:"reason"`
+	UrgencyThresholdAt string `json:"urgency_threshold_at"`
+}
+
+// QuickNotePlanOutput 是“随口记单请求聚合规划”模型契约。
+type QuickNotePlanOutput struct {
+	Title              string `json:"title"`
+	DeadlineAt         string `json:"deadline_at"`
+	UrgencyThresholdAt string `json:"urgency_threshold_at"`
+	PriorityGroup      int    `json:"priority_group"`
+	PriorityReason     string `json:"priority_reason"`
+	Banter             string `json:"banter"`
+}
+
+// IdentifyQuickNoteIntent 调用模型识别“是否随口记”。
+func IdentifyQuickNoteIntent(ctx context.Context, chatModel *ark.ChatModel, nowText, userInput string) (*QuickNoteIntentOutput, error) {
+	prompt := fmt.Sprintf(`当前时间（北京时间，精确到分钟）：%s
+用户输入：%s
+请仅输出 JSON（不要 markdown，不要解释），字段如下：
+{
+  "is_quick_note": boolean,
+  "title": string,
+  "deadline_at": string,
+  "reason": string
+}
+字段约束：
+1) deadline_at 只允许输出绝对时间，格式必须为 "yyyy-MM-dd HH:mm"。
+2) 如果用户说了“明天/后天/下周一/今晚”等相对时间，必须基于上面的当前时间换算成绝对时间。
+3) 如果用户没有提及时间，deadline_at 输出空字符串。`,
+		nowText,
+		userInput,
+	)
+
+	parsed, _, err := CallArkJSON[QuickNoteIntentOutput](ctx, chatModel, agentprompt.QuickNoteIntentPrompt, prompt, ArkCallOptions{
+		Temperature: 0,
+		MaxTokens:   256,
+		Thinking:    ThinkingModeDisabled,
+	})
+	return parsed, err
+}
+
+// PlanQuickNotePriority 调用模型评估优先级与紧急分界线。
+func PlanQuickNotePriority(ctx context.Context, chatModel *ark.ChatModel, nowText, title, userInput, deadlineClue, deadlineText string) (*QuickNotePriorityOutput, error) {
+	prompt := fmt.Sprintf(`当前时间（北京时间，精确到分钟）：%s
+请对以下任务评估优先级：
+- 任务标题：%s
+- 用户原始输入：%s
+- 时间线索原文：%s
+- 归一化截止时间：%s
+
+请仅输出 JSON（不要 markdown，不要解释）：
+{
+  "priority_group": 1|2|3|4,
+  "reason": "简短理由",
+  "urgency_threshold_at": "yyyy-MM-dd HH:mm 或空字符串"
+}
+
+额外约束：
+1) urgency_threshold_at 表示“何时从不紧急象限自动平移到紧急象限”；
+2) 若该任务不需要自动平移，可输出空字符串；
+3) 若任务已在紧急象限（priority_group=1 或 3），优先输出空字符串；
+4) 若输出非空时间，必须是绝对时间，且不晚于归一化截止时间（若有）。`,
+		nowText,
+		title,
+		userInput,
+		deadlineClue,
+		deadlineText,
+	)
+
+	parsed, _, err := CallArkJSON[QuickNotePriorityOutput](ctx, chatModel, agentprompt.QuickNotePriorityPrompt, prompt, ArkCallOptions{
+		Temperature: 0,
+		MaxTokens:   256,
+		Thinking:    ThinkingModeDisabled,
+	})
+	return parsed, err
+}
+
+// PlanQuickNoteInSingleCall 一次性完成标题/时间/优先级/banter 聚合规划。
+func PlanQuickNoteInSingleCall(ctx context.Context, chatModel *ark.ChatModel, nowText, userInput string) (*QuickNotePlanOutput, error) {
+	prompt := fmt.Sprintf(`当前时间（北京时间，精确到分钟）：%s
+用户输入：%s
+
+请仅输出 JSON（不要 markdown，不要解释），字段如下：
+{
+  "title": string,
+  "deadline_at": string,
+  "urgency_threshold_at": string,
+  "priority_group": 1|2|3|4,
+  "priority_reason": string,
+  "banter": string
+}
+
+约束：
+1) deadline_at 只允许 "yyyy-MM-dd HH:mm" 或空字符串；
+2) urgency_threshold_at 只允许 "yyyy-MM-dd HH:mm" 或空字符串；
+3) 若用户给了相对时间（如明天/今晚/下周一），必须换算为绝对时间；
+4) 若任务不需要自动平移，可让 urgency_threshold_at 为空；
+5) banter 只允许一句中文，不超过30字，不得改动任务事实。`,
+		nowText,
+		strings.TrimSpace(userInput),
+	)
+
+	parsed, _, err := CallArkJSON[QuickNotePlanOutput](ctx, chatModel, agentprompt.QuickNotePlanPrompt, prompt, ArkCallOptions{
+		Temperature: 0,
+		MaxTokens:   220,
+		Thinking:    ThinkingModeDisabled,
+	})
+	return parsed, err
+}
+
+// GenerateQuickNoteBanter 生成成功写入后的轻松跟进句。
+func GenerateQuickNoteBanter(ctx context.Context, chatModel *ark.ChatModel, userMessage, title, priorityText, deadlineText string) (string, error) {
+	if chatModel == nil {
+		return "", fmt.Errorf("model is nil")
+	}
+
+	prompt := fmt.Sprintf(`用户原话：%s
+已确认事实：
+- 任务标题：%s
+- %s
+- %s
+
+请输出一句轻松自然的跟进话术（仅一句）。`,
+		strings.TrimSpace(userMessage),
+		strings.TrimSpace(title),
+		strings.TrimSpace(priorityText),
+		strings.TrimSpace(deadlineText),
+	)
+
+	text, err := CallArkText(ctx, chatModel, agentprompt.QuickNoteReplyBanterPrompt, prompt, ArkCallOptions{
+		Temperature: 0.7,
+		MaxTokens:   72,
+		Thinking:    ThinkingModeDisabled,
+	})
+	if err != nil {
+		return "", err
+	}
+
+	text = strings.TrimSpace(text)
+	text = strings.Trim(text, "\"'“”‘’")
+	if text == "" {
+		return "", fmt.Errorf("empty content")
+	}
+	if idx := strings.Index(text, "\n"); idx >= 0 {
+		text = strings.TrimSpace(text[:idx])
+	}
+	return text, nil
+}
--- a/backend/agent/llm/route.go
+++ b/backend/agent/llm/route.go
@@ -0,0 +1,50 @@
+package agentllm
+
+import (
+	"strings"
+
+	agentmodel "github.com/LoveLosita/smartflow/backend/agent/model"
+)
+
+// RouteDecisionOutput 是一级路由模型的结构化输出契约。
+//
+// 说明：
+// 1. 这里只定义“模型应该吐什么 JSON”；
+// 2. 真正的 prompt 归 prompt/ 管；
+// 3. 真正的业务分发归 router/ 管。
+type RouteDecisionOutput struct {
+	Action     string  `json:"action"`
+	TrustRoute bool    `json:"trust_route"`
+	Detail     string  `json:"detail"`
+	Confidence float64 `json:"confidence"`
+}
+
+// ToDecision 把模型契约输出映射成 Agent 内部统一路由结果。
+func (o *RouteDecisionOutput) ToDecision() *agentmodel.RouteDecision {
+	if o == nil {
+		return &agentmodel.RouteDecision{Action: agentmodel.ActionChat}
+	}
+
+	action := normalizeRouteAction(o.Action)
+	return &agentmodel.RouteDecision{
+		Action:     action,
+		TrustRoute: o.TrustRoute,
+		Detail:     strings.TrimSpace(o.Detail),
+		Confidence: o.Confidence,
+	}
+}
+
+func normalizeRouteAction(raw string) agentmodel.AgentAction {
+	switch strings.TrimSpace(strings.ToLower(raw)) {
+	case "quick_note", "quick_note_create":
+		return agentmodel.ActionQuickNoteCreate
+	case "task_query":
+		return agentmodel.ActionTaskQuery
+	case "schedule_plan", "schedule_plan_create":
+		return agentmodel.ActionSchedulePlanCreate
+	case "schedule_refine", "schedule_plan_refine":
+		return agentmodel.ActionSchedulePlanRefine
+	default:
+		return agentmodel.ActionChat
+	}
+}
--- a/backend/agent/llm/schedule.go
+++ b/backend/agent/llm/schedule.go
@@ -0,0 +1,175 @@
+package agentllm
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	agentprompt "github.com/LoveLosita/smartflow/backend/agent/prompt"
+	"github.com/LoveLosita/smartflow/backend/model"
+	"github.com/cloudwego/eino-ext/components/model/ark"
+	einoModel "github.com/cloudwego/eino/components/model"
+	"github.com/cloudwego/eino/schema"
+	arkModel "github.com/volcengine/volcengine-go-sdk/service/arkruntime/model"
+)
+
+// ScheduleIntentOutput 是 plan 节点要求模型返回的结构化结果。
+//
+// 兼容说明：
+//  1. 新主语义是 task_class_ids（数组）；
+//  2. 为兼容旧 prompt/旧缓存输出，保留 task_class_id（单值）兜底解析；
+//  3. TaskTags 的 key 兼容两种写法：
+//     3.1 推荐：task_item_id（例如 "12"）；
+//     3.2 兼容：任务名称（例如 "高数复习"）。
+type ScheduleIntentOutput struct {
+	Intent          string            `json:"intent"`
+	Constraints     []string          `json:"constraints"`
+	TaskClassIDs    []int             `json:"task_class_ids"`
+	TaskClassID     int               `json:"task_class_id"`
+	Strategy        string            `json:"strategy"`
+	TaskTags        map[string]string `json:"task_tags"`
+	Restart         bool              `json:"restart"`
+	AdjustmentScope string            `json:"adjustment_scope"`
+	Reason          string            `json:"reason"`
+	Confidence      float64           `json:"confidence"`
+}
+
+// ReactToolCall 是 LLM 输出的单个工具调用。
+type ReactToolCall struct {
+	Tool   string         `json:"tool"`
+	Params map[string]any `json:"params"`
+}
+
+// ReactLLMOutput 是 ReAct 节点要求模型返回的统一 JSON。
+type ReactLLMOutput struct {
+	Done      bool            `json:"done"`
+	Summary   string          `json:"summary"`
+	ToolCalls []ReactToolCall `json:"tool_calls"`
+}
+
+// IdentifySchedulePlanIntent 调用模型识别“排程意图 + 约束 + 任务类集合”。
+func IdentifySchedulePlanIntent(
+	ctx context.Context,
+	chatModel *ark.ChatModel,
+	nowText string,
+	userMessage string,
+	adjustmentHint string,
+) (*ScheduleIntentOutput, error) {
+	prompt := fmt.Sprintf(
+		"当前时间（北京时间）：%s\n用户输入：%s%s\n\n请提取排程意图与约束。",
+		strings.TrimSpace(nowText),
+		strings.TrimSpace(userMessage),
+		strings.TrimSpace(adjustmentHint),
+	)
+
+	parsed, _, err := CallArkJSON[ScheduleIntentOutput](ctx, chatModel, agentprompt.SchedulePlanIntentPrompt, prompt, ArkCallOptions{
+		Temperature: 0,
+		MaxTokens:   256,
+		Thinking:    ThinkingModeDisabled,
+	})
+	return parsed, err
+}
+
+// ParseScheduleReactOutput 解析 ReAct 节点的 JSON 输出。
+func ParseScheduleReactOutput(raw string) (*ReactLLMOutput, error) {
+	return ParseJSONObject[ReactLLMOutput](raw)
+}
+
+// GenerateScheduleDailyReactRound 调用模型生成“单天日内优化”的一轮决策。
+//
+// 职责边界：
+// 1. 只负责统一关闭 thinking、设置温度，并返回纯文本；
+// 2. 不负责工具执行，不负责结果回灌。
+func GenerateScheduleDailyReactRound(
+	ctx context.Context,
+	chatModel *ark.ChatModel,
+	messages []*schema.Message,
+) (string, error) {
+	resp, err := chatModel.Generate(
+		ctx,
+		messages,
+		ark.WithThinking(&arkModel.Thinking{Type: arkModel.ThinkingTypeDisabled}),
+		einoModel.WithTemperature(0),
+	)
+	if err != nil {
+		return "", err
+	}
+	if resp == nil {
+		return "", fmt.Errorf("日内优化调用返回为空")
+	}
+	content := strings.TrimSpace(resp.Content)
+	if content == "" {
+		return "", fmt.Errorf("日内优化调用返回内容为空")
+	}
+	return content, nil
+}
+
+// GenerateScheduleWeeklyReactRound 调用模型生成“单周单步优化”的一轮决策。
+//
+// 职责边界：
+// 1. 周级仍保留 thinking，提高复杂排程准确率；
+// 2. 仅返回最终 content，是否透出思考流由上层决定。
+func GenerateScheduleWeeklyReactRound(
+	ctx context.Context,
+	chatModel *ark.ChatModel,
+	messages []*schema.Message,
+) (string, error) {
+	resp, err := chatModel.Generate(
+		ctx,
+		messages,
+		ark.WithThinking(&arkModel.Thinking{Type: arkModel.ThinkingTypeEnabled}),
+		einoModel.WithTemperature(0.2),
+	)
+	if err != nil {
+		return "", err
+	}
+	if resp == nil {
+		return "", fmt.Errorf("周级单步调用返回为空")
+	}
+	content := strings.TrimSpace(resp.Content)
+	if content == "" {
+		return "", fmt.Errorf("周级单步调用返回内容为空")
+	}
+	return content, nil
+}
+
+// GenerateScheduleHumanSummary 调用模型生成“用户可读”的最终总结。
+func GenerateScheduleHumanSummary(
+	ctx context.Context,
+	chatModel *ark.ChatModel,
+	entries []model.HybridScheduleEntry,
+	constraints []string,
+	actionLogs []string,
+) (string, error) {
+	if chatModel == nil {
+		return "", fmt.Errorf("final summary model is nil")
+	}
+
+	entriesJSON, _ := json.Marshal(entries)
+	constraintText := "无"
+	if len(constraints) > 0 {
+		constraintText = strings.Join(constraints, "、")
+	}
+	actionLogText := "无"
+	if len(actionLogs) > 0 {
+		start := 0
+		if len(actionLogs) > 30 {
+			start = len(actionLogs) - 30
+		}
+		actionLogText = strings.Join(actionLogs[start:], "\n")
+	}
+
+	userPrompt := fmt.Sprintf(
+		"以下是最终排程方案（JSON）：\n%s\n\n用户约束：%s\n\n以下是本次周级优化动作日志（按时间顺序）：\n%s\n\n请基于“结果+过程”输出2-3句自然中文总结，重点说明本方案的优点和改进点。",
+		string(entriesJSON),
+		constraintText,
+		actionLogText,
+	)
+
+	return CallArkText(ctx, chatModel, agentprompt.SchedulePlanFinalCheckPrompt, userPrompt, ArkCallOptions{
+		Temperature: 0.4,
+		MaxTokens:   256,
+		Thinking:    ThinkingModeDisabled,
+	})
+}
--- a/backend/agent/llm/schedule_refine.go
+++ b/backend/agent/llm/schedule_refine.go
@@ -0,0 +1,132 @@
+package agentllm
+
+import (
+	"context"
+	"time"
+
+	"github.com/cloudwego/eino-ext/components/model/ark"
+)
+
+const scheduleRefineNodeTimeout = 120 * time.Second
+
+type ScheduleRefineContractOutput struct {
+	Intent            string                        `json:"intent"`
+	Strategy          string                        `json:"strategy"`
+	HardRequirements  []string                      `json:"hard_requirements"`
+	HardAssertions    []ScheduleRefineAssertionLite `json:"hard_assertions"`
+	KeepRelativeOrder bool                          `json:"keep_relative_order"`
+	OrderScope        string                        `json:"order_scope"`
+}
+
+type ScheduleRefineAssertionLite struct {
+	Metric     string `json:"metric"`
+	Operator   string `json:"operator"`
+	Value      int    `json:"value"`
+	Min        int    `json:"min"`
+	Max        int    `json:"max"`
+	Week       int    `json:"week"`
+	TargetWeek int    `json:"target_week"`
+}
+
+type ScheduleRefinePlannerOutput struct {
+	Summary string   `json:"summary"`
+	Steps   []string `json:"steps"`
+}
+
+type ScheduleRefineToolCall struct {
+	Tool   string         `json:"tool"`
+	Params map[string]any `json:"params"`
+}
+
+type ScheduleRefineReactOutput struct {
+	Done        bool                     `json:"done"`
+	Summary     string                   `json:"summary"`
+	GoalCheck   string                   `json:"goal_check"`
+	Decision    string                   `json:"decision"`
+	MissingInfo []string                 `json:"missing_info,omitempty"`
+	ToolCalls   []ScheduleRefineToolCall `json:"tool_calls"`
+}
+
+type ScheduleRefinePostReflectOutput struct {
+	Reflection   string `json:"reflection"`
+	NextStrategy string `json:"next_strategy"`
+	ShouldStop   bool   `json:"should_stop"`
+}
+
+type ScheduleRefineReviewOutput struct {
+	Pass   bool     `json:"pass"`
+	Reason string   `json:"reason"`
+	Unmet  []string `json:"unmet"`
+}
+
+func GenerateScheduleRefineContract(ctx context.Context, chatModel *ark.ChatModel, systemPrompt, userPrompt string) (*ScheduleRefineContractOutput, string, error) {
+	return callScheduleRefineJSON[ScheduleRefineContractOutput](ctx, chatModel, systemPrompt, userPrompt, ArkCallOptions{
+		Temperature: 0,
+		MaxTokens:   260,
+		Thinking:    ThinkingModeDisabled,
+	})
+}
+
+func GenerateScheduleRefinePlanner(ctx context.Context, chatModel *ark.ChatModel, systemPrompt, userPrompt string, maxTokens int) (*ScheduleRefinePlannerOutput, string, error) {
+	return callScheduleRefineJSON[ScheduleRefinePlannerOutput](ctx, chatModel, systemPrompt, userPrompt, ArkCallOptions{
+		Temperature: 0,
+		MaxTokens:   maxTokens,
+		Thinking:    ThinkingModeDisabled,
+	})
+}
+
+func GenerateScheduleRefineReact(ctx context.Context, chatModel *ark.ChatModel, systemPrompt, userPrompt string, useThinking bool, maxTokens int) (string, error) {
+	thinking := ThinkingModeDisabled
+	if useThinking {
+		thinking = ThinkingModeEnabled
+	}
+	return callScheduleRefineText(ctx, chatModel, systemPrompt, userPrompt, ArkCallOptions{
+		Temperature: 0,
+		MaxTokens:   maxTokens,
+		Thinking:    thinking,
+	})
+}
+
+func GenerateScheduleRefinePostReflect(ctx context.Context, chatModel *ark.ChatModel, systemPrompt, userPrompt string) (*ScheduleRefinePostReflectOutput, string, error) {
+	return callScheduleRefineJSON[ScheduleRefinePostReflectOutput](ctx, chatModel, systemPrompt, userPrompt, ArkCallOptions{
+		Temperature: 0,
+		MaxTokens:   220,
+		Thinking:    ThinkingModeDisabled,
+	})
+}
+
+func GenerateScheduleRefineReview(ctx context.Context, chatModel *ark.ChatModel, systemPrompt, userPrompt string) (*ScheduleRefineReviewOutput, string, error) {
+	return callScheduleRefineJSON[ScheduleRefineReviewOutput](ctx, chatModel, systemPrompt, userPrompt, ArkCallOptions{
+		Temperature: 0,
+		MaxTokens:   240,
+		Thinking:    ThinkingModeDisabled,
+	})
+}
+
+func GenerateScheduleRefineSummary(ctx context.Context, chatModel *ark.ChatModel, systemPrompt, userPrompt string) (string, error) {
+	return callScheduleRefineText(ctx, chatModel, systemPrompt, userPrompt, ArkCallOptions{
+		Temperature: 0.35,
+		MaxTokens:   280,
+		Thinking:    ThinkingModeDisabled,
+	})
+}
+
+func GenerateScheduleRefineRepair(ctx context.Context, chatModel *ark.ChatModel, systemPrompt, userPrompt string) (string, error) {
+	return callScheduleRefineText(ctx, chatModel, systemPrompt, userPrompt, ArkCallOptions{
+		Temperature: 0.15,
+		MaxTokens:   240,
+		Thinking:    ThinkingModeDisabled,
+	})
+}
+
+func callScheduleRefineText(ctx context.Context, chatModel *ark.ChatModel, systemPrompt, userPrompt string, options ArkCallOptions) (string, error) {
+	nodeCtx, cancel := context.WithTimeout(ctx, scheduleRefineNodeTimeout)
+	defer cancel()
+	return CallArkText(nodeCtx, chatModel, systemPrompt, userPrompt, options)
+}
+
+func callScheduleRefineJSON[T any](ctx context.Context, chatModel *ark.ChatModel, systemPrompt, userPrompt string, options ArkCallOptions) (*T, string, error) {
+	nodeCtx, cancel := context.WithTimeout(ctx, scheduleRefineNodeTimeout)
+	defer cancel()
+	return CallArkJSON[T](nodeCtx, chatModel, systemPrompt, userPrompt, options)
+}
--- a/backend/agent/llm/taskquery.go
+++ b/backend/agent/llm/taskquery.go
@@ -0,0 +1,83 @@
+package agentllm
+
+import (
+	"context"
+
+	agentprompt "github.com/LoveLosita/smartflow/backend/agent/prompt"
+	"github.com/cloudwego/eino-ext/components/model/ark"
+)
+
+// TaskQueryPlanOutput 描述计划节点返回的结构化查询方案。
+//
+// 职责边界：
+// 1. 只承接模型输出，不在这里做合法性校验。
+// 2. 字段为空或非法时，由 node 层继续归一化与兜底。
+type TaskQueryPlanOutput struct {
+	UserGoal         string `json:"user_goal"`
+	Quadrants        []int  `json:"quadrants"`
+	SortBy           string `json:"sort_by"`
+	Order            string `json:"order"`
+	Limit            int    `json:"limit"`
+	IncludeCompleted *bool  `json:"include_completed"`
+	Keyword          string `json:"keyword"`
+	DeadlineBefore   string `json:"deadline_before"`
+	DeadlineAfter    string `json:"deadline_after"`
+}
+
+// TaskQueryRetryPatch 描述反思节点允许回写的计划补丁。
+//
+// 输入输出语义：
+// 1. 指针字段为 nil 表示“不改这个字段”。
+// 2. 非 nil 但值为空字符串，表示显式清空该条件。
+type TaskQueryRetryPatch struct {
+	Quadrants        *[]int  `json:"quadrants,omitempty"`
+	SortBy           *string `json:"sort_by,omitempty"`
+	Order            *string `json:"order,omitempty"`
+	Limit            *int    `json:"limit,omitempty"`
+	IncludeCompleted *bool   `json:"include_completed,omitempty"`
+	Keyword          *string `json:"keyword,omitempty"`
+	DeadlineBefore   *string `json:"deadline_before,omitempty"`
+	DeadlineAfter    *string `json:"deadline_after,omitempty"`
+}
+
+// TaskQueryReflectOutput 描述反思节点对本轮查询结果的判定。
+//
+// 输入输出语义：
+// 1. Satisfied=true 表示当前结果可直接收口。
+// 2. NeedRetry=true 表示建议再跑一轮，但真正是否重试由 node 层结合次数上限决定。
+// 3. Reply 是可直接给用户的候选文案，允许为空。
+type TaskQueryReflectOutput struct {
+	Satisfied  bool                `json:"satisfied"`
+	NeedRetry  bool                `json:"need_retry"`
+	Reason     string              `json:"reason"`
+	Reply      string              `json:"reply"`
+	RetryPatch TaskQueryRetryPatch `json:"retry_patch"`
+}
+
+// PlanTaskQuery 负责调用模型，把自然语言查询规划成结构化检索参数。
+//
+// 职责边界：
+// 1. 只负责模型调用与 JSON 解析。
+// 2. 不负责结果兜底、限流裁剪或时间归一化。
+func PlanTaskQuery(ctx context.Context, chatModel *ark.ChatModel, nowText, userInput string) (*TaskQueryPlanOutput, error) {
+	parsed, _, err := CallArkJSON[TaskQueryPlanOutput](ctx, chatModel, agentprompt.TaskQueryPlanPrompt, agentprompt.BuildTaskQueryPlanUserPrompt(nowText, userInput), ArkCallOptions{
+		Temperature: 0,
+		MaxTokens:   260,
+		Thinking:    ThinkingModeDisabled,
+	})
+	return parsed, err
+}
+
+// ReflectTaskQuery 负责让模型判断当前查询结果是否满足用户意图。
+//
+// 职责边界：
+// 1. 只负责反思提示词调用与结构化解析。
+// 2. 不负责实际执行重试，也不负责拼接最终兜底回复。
+func ReflectTaskQuery(ctx context.Context, chatModel *ark.ChatModel, prompt string) (*TaskQueryReflectOutput, error) {
+	parsed, _, err := CallArkJSON[TaskQueryReflectOutput](ctx, chatModel, agentprompt.TaskQueryReflectPrompt, prompt, ArkCallOptions{
+		Temperature: 0,
+		MaxTokens:   380,
+		Thinking:    ThinkingModeDisabled,
+	})
+	return parsed, err
+}