Skip to content

An open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作

37.6 KB
Raw Blame
// SiYuan - https://github.com/siyuan-note/siyuan
// Copyright (c) 2020-present, b3log.org
// SPDX-License-Identifier: AGPL-3.0-or-later

package conf

import (
	"encoding/hex"
	"encoding/json"
	"fmt"
	"math"
	"net/url"
	"os"
	"strconv"
	"strings"

	"github.com/88250/lute/ast"
	"github.com/google/uuid"
	"github.com/siyuan-note/siyuan/kernel/util"
)

type AI struct {
	Web             *AIWeb           `json:"web"`
	MCP             *MCP             `json:"mcp"`
	Embedding       *Embedding       `json:"embedding"`
	Rerank          *Rerank          `json:"rerank"`
	Decision        *Decision        `json:"decision"`
	Agent           *Agent           `json:"agent"`
	Editing         *Editing         `json:"editing"`
	ImageGeneration *ImageGeneration `json:"imageGeneration"`
	Providers       []*Provider      `json:"providers"`
}

// AIWeb 独立配置网页搜索和抓取,DeepSeek 两个接口共用凭证,不跟随对话模型切换。
type AIWeb struct {
	SearchProvider string `json:"searchProvider"`
	FetchProvider  string `json:"fetchProvider"`
	APIKey         string `json:"apiKey"`
	Timeout        int    `json:"timeout"`
}

func (web *AIWeb) Normalize() {
	web.SearchProvider = strings.TrimSpace(web.SearchProvider)
	web.FetchProvider = strings.TrimSpace(web.FetchProvider)
	if web.SearchProvider == "" {
		web.SearchProvider = "exa"
	}
	if web.FetchProvider == "" {
		web.FetchProvider = "direct"
	}
	web.APIKey = strings.TrimSpace(web.APIKey)
	web.Timeout = util.NormalizeWebTimeout(web.Timeout)
}

// DefaultAgentConfirmTimeout 是智能体确认超时时间的默认值(秒),也用于智能体提问的等待时长。
const DefaultAgentConfirmTimeout = 600

// DefaultAgentSessionTimeout 是智能体会话总超时时间的默认值(秒)。
const DefaultAgentSessionTimeout = 1800

// MaxAgentSessionTimeout 是智能体会话总超时时间的上限(秒)。
const MaxAgentSessionTimeout = 3600

type Agent struct {
	StreamingMarkdown   bool              `json:"streamingMarkdown"` // 智能体流式输出时渲染 Markdown
	ModelID             string            `json:"modelId"`
	SessionTimeout      int               `json:"sessionTimeout"`
	StreamIdleTimeout   int               `json:"streamIdleTimeout"`
	ConfirmTimeout      int               `json:"confirmTimeout"`
	MaxRetries          int               `json:"maxRetries"`
	Temperature         float64           `json:"temperature"`
	MaxCompletionTokens int               `json:"maxCompletionTokens"`
	MaxToolCallRounds   int               `json:"maxToolCallRounds"`
	CapabilityPolicy    *CapabilityPolicy `json:"capabilityPolicy"`
	ApprovalPolicy      *ApprovalPolicy   `json:"approvalPolicy"`
	Skills              *AgentSkills      `json:"skills"`
}

type AgentSkills struct {
	UserEnabled     []string `json:"userEnabled"`
	BuiltinDisabled []string `json:"builtinDisabled"`
}

type CapabilityPolicy struct {
	Default   string            `json:"default"`
	Overrides map[string]string `json:"overrides"`
}

type ApprovalPolicy struct {
	Default   string                         `json:"default"`
	Overrides map[string]*CapabilityApproval `json:"overrides"`
}

type CapabilityApproval struct {
	Default string            `json:"default"`
	Actions map[string]string `json:"actions"`
}

const (
	ApprovalDecisionRisk    = "risk"
	ApprovalDecisionConfirm = "confirm"
	ApprovalDecisionAllow   = "allow"
)

// Editing holds behavior parameters used by the in-editor chat scenario. They
// are kept here (instead of on Model) to mirror Agent and to decouple scenario
// behavior from the model registry. See https://github.com/siyuan-note/siyuan/issues/17797
type Editing struct {
	ModelID             string  `json:"modelId"`
	MaxHistoryMessages  int     `json:"maxHistoryMessages"`  // Max number of prior turns kept as context
	Temperature         float64 `json:"temperature"`         // Alignment with Agent.Temperature
	MaxCompletionTokens int     `json:"maxCompletionTokens"` // Alignment with Agent.MaxCompletionTokens
}

// ImageGeneration 配置图片生成场景的模型和默认输出参数。
type ImageGeneration struct {
	ModelID        string `json:"modelId"`
	RequestTimeout int    `json:"requestTimeout"`
	Size           string `json:"size"`
	Quality        string `json:"quality"`
	OutputFormat   string `json:"outputFormat"`
}

// 嵌入索引调度的默认值和资源上限,与设置控件范围保持一致。
const (
	DefaultEmbeddingConcurrency = 8
	MaxEmbeddingConcurrency     = 64
	DefaultEmbeddingBatchSize   = 10
	MaxEmbeddingBatchSize       = 128
)

type Embedding struct {
	ID          string `json:"id"`
	Enabled     bool   `json:"enabled"`
	APIKey      string `json:"apiKey"`
	BaseURL     string `json:"baseURL"`
	Name        string `json:"name"`
	Timeout     int    `json:"timeout"`
	Dimensions  int    `json:"dimensions"` // 输出向量维度,仅 text-embedding-3 及以上模型支持;0 表示用模型默认值(不传该参数)
	Concurrency int    `json:"concurrency"`
	BatchSize   int    `json:"batchSize"`
}

// Decision 按供应商隔离凭证,平铺字段仅用于兼容旧配置输入。
type Decision struct {
	Enabled  bool                        `json:"enabled"`
	Provider string                      `json:"provider"`
	Profiles map[string]*DecisionProfile `json:"profiles"`
	Endpoint string                      `json:"endpoint,omitempty"`
	APIKey   string                      `json:"apiKey,omitempty"`
	Name     string                      `json:"name,omitempty"`
	Timeout  int                         `json:"timeout,omitempty"`
}

type DecisionProfile struct {
	Endpoint string `json:"endpoint"`
	APIKey   string `json:"apiKey"`
	Name     string `json:"name"`
	Timeout  int    `json:"timeout"`
}

func (decision *Decision) ActiveOptions() (util.DecisionOptions, error) {
	if decision == nil {
		return util.DecisionOptions{}, fmt.Errorf("decision model not configured")
	}
	provider := strings.TrimSpace(decision.Provider)
	if provider == "" {
		provider = "typesafe"
	}
	if provider != "typesafe" && provider != "openai" {
		return util.DecisionOptions{}, fmt.Errorf("unknown decision provider")
	}
	profile := decision.Profiles[provider]
	if decision.Profiles == nil && provider == "typesafe" {
		profile = &DecisionProfile{decision.Endpoint, decision.APIKey, decision.Name, decision.Timeout}
	}
	if profile == nil || profile.Endpoint == "" || profile.APIKey == "" || profile.Name == "" {
		return util.DecisionOptions{}, fmt.Errorf("decision model not configured")
	}
	return util.DecisionOptions{Provider: provider, Endpoint: profile.Endpoint, APIKey: profile.APIKey, Model: profile.Name, Timeout: profile.Timeout}, nil
}

func (decision *Decision) Configured() bool { _, err := decision.ActiveOptions(); return err == nil }

func defaultDecisionProfile(provider string) *DecisionProfile {
	if provider == "openai" {
		return &DecisionProfile{Endpoint: "https://api.openai.com/v1/decisions", Name: "gpt-6-luna", Timeout: 30}
	}
	return &DecisionProfile{Endpoint: "https://api.typesafe.ai/v1/systemone", Name: "jev-latest", Timeout: 30}
}

func defaultDecision() *Decision {
	return &Decision{Provider: "typesafe", Profiles: map[string]*DecisionProfile{"typesafe": defaultDecisionProfile("typesafe"), "openai": defaultDecisionProfile("openai")}}
}

func (decision *Decision) Normalize() {
	decision.Provider = strings.TrimSpace(decision.Provider)
	if decision.Provider == "" {
		decision.Provider = "typesafe"
	}
	if decision.Profiles == nil {
		decision.Profiles = map[string]*DecisionProfile{"typesafe": {Endpoint: decision.Endpoint, APIKey: decision.APIKey, Name: decision.Name, Timeout: decision.Timeout}}
	}
	for _, provider := range []string{"typesafe", "openai"} {
		profile := decision.Profiles[provider]
		defaults := defaultDecisionProfile(provider)
		if profile == nil {
			profile = defaults
			decision.Profiles[provider] = profile
		}
		profile.Endpoint = strings.TrimSpace(profile.Endpoint)
		profile.APIKey = strings.TrimSpace(profile.APIKey)
		profile.Name = strings.TrimSpace(profile.Name)
		if profile.Endpoint == "" {
			profile.Endpoint = defaults.Endpoint
		}
		if profile.Name == "" {
			profile.Name = defaults.Name
		}
		if profile.Timeout < 1 {
			profile.Timeout = 30
		} else if profile.Timeout > 600 {
			profile.Timeout = 600
		}
	}
	decision.Endpoint, decision.APIKey, decision.Name, decision.Timeout = "", "", "", 0
}

func (decision *Decision) Clone() *Decision {
	if decision == nil {
		return nil
	}
	result := *decision
	if decision.Profiles != nil {
		result.Profiles = make(map[string]*DecisionProfile, len(decision.Profiles))
		for id, profile := range decision.Profiles {
			if profile != nil {
				copy := *profile
				result.Profiles[id] = &copy
			} else {
				result.Profiles[id] = nil
			}
		}
	}
	return &result
}

// Rerank 配置语义搜索结果的重排模型。重排在向量召回后对 query 与候选文档逐对精排,
// 采用主流重排服务的 /rerank 协议(OpenAI 官方暂无 rerank API)。
// 各服务商端点路径不一(Jina /v1/rerank、阿里云 /v1/reranks 等),故 Endpoint 为完整端点地址。
type Rerank struct {
	ID             string                   `json:"id"`
	Enabled        bool                     `json:"enabled"`
	APIKey         string                   `json:"apiKey"`
	Endpoint       string                   `json:"endpoint"` // 完整重排端点 URL,按目标模型文档填写
	Name           string                   `json:"name"`
	RequestFormat  util.RerankRequestFormat `json:"requestFormat"`
	Timeout        int                      `json:"timeout"`
	CandidateCount int                      `json:"candidateCount"` // 向量召回后送入重排的候选文档数,默认 30;越大越准但越慢
}

type Provider struct {
	AuthType string `json:"authType,omitempty"`
	// AccountID 是本机绑定的运行时投影;工作空间配置持久化和设置导出时排除。
	AccountID      string            `json:"accountID,omitempty"`
	Headers        map[string]string `json:"headers,omitempty"`
	ID             string            `json:"id"`
	DisplayName    string            `json:"displayName,omitempty"`
	Enabled        bool              `json:"enabled"`
	APIKey         string            `json:"apiKey"`
	BaseURL        string            `json:"baseURL"`
	Protocol       string            `json:"protocol,omitempty"`
	RequestTimeout int               `json:"requestTimeout"`
	Models         []*Model          `json:"models"`
}

// ClearChatGPTAccountIDs 清除可复制配置中的本机账户引用,不修改登录凭证。
func (ai *AI) ClearChatGPTAccountIDs() {
	for _, provider := range ai.Providers {
		if provider != nil {
			provider.AccountID = ""
		}
	}
}

// Model is the provider-scoped model registry entry. MaxTokens/Temperature/
// MaxContexts remain the persisted UI-facing config (the settings page still
// reads/writes them). Editing holds the runtime view derived from them.
type Model struct {
	ID            string `json:"id"`
	DisplayName   string `json:"displayName,omitempty"`
	Enabled       bool   `json:"enabled"`
	Name          string `json:"name"`
	ContextLength int    `json:"contextLength,omitempty"`
}

type MCP struct {
	Servers        []MCPServer       `json:"servers"`
	ExposurePolicy *CapabilityPolicy `json:"exposurePolicy"`
}

type MCPServer struct {
	ID                   string            `json:"id"`
	Name                 string            `json:"name"`
	Enabled              bool              `json:"enabled"`
	Type                 string            `json:"type"`
	Command              string            `json:"command"`
	Args                 []string          `json:"args"`
	InheritEnv           []string          `json:"inheritEnv"`
	Env                  map[string]string `json:"env"`
	URL                  string            `json:"url"`
	Headers              map[string]string `json:"headers"`
	Timeout              int               `json:"timeout"`
	DisableStandaloneSSE bool              `json:"disableStandaloneSSE"`
	TrustToolAnnotations bool              `json:"trustToolAnnotations"`
}

func defaultEmbedding() *Embedding {
	return &Embedding{Timeout: 30, Concurrency: DefaultEmbeddingConcurrency, BatchSize: DefaultEmbeddingBatchSize}
}

func defaultRerank() *Rerank {
	return &Rerank{
		RequestFormat:  util.RerankRequestFormatCohere,
		Timeout:        30,
		CandidateCount: 30,
	}
}

func defaultAgent() *Agent {
	return &Agent{
		SessionTimeout:      DefaultAgentSessionTimeout,
		StreamIdleTimeout:   120,
		ConfirmTimeout:      DefaultAgentConfirmTimeout,
		MaxRetries:          3,
		Temperature:         1.0,
		MaxCompletionTokens: 0,
		MaxToolCallRounds:   64,
		CapabilityPolicy:    defaultCapabilityPolicy(),
		ApprovalPolicy:      defaultApprovalPolicy(),
		Skills:              &AgentSkills{UserEnabled: []string{}, BuiltinDisabled: []string{}},
	}
}

func defaultApprovalPolicy() *ApprovalPolicy {
	return &ApprovalPolicy{
		Default:   ApprovalDecisionRisk,
		Overrides: map[string]*CapabilityApproval{},
	}
}

func defaultCapabilityPolicy() *CapabilityPolicy {
	return &CapabilityPolicy{
		Default:   "allow",
		Overrides: map[string]string{},
	}
}

func normalizeCapabilityPolicy(policy *CapabilityPolicy) *CapabilityPolicy {
	if policy == nil {
		return defaultCapabilityPolicy()
	}
	if policy.Default != "deny" {
		policy.Default = "allow"
	}
	if policy.Overrides == nil {
		policy.Overrides = map[string]string{}
	}
	for id, decision := range policy.Overrides {
		if id == "" || decision != "allow" && decision != "deny" {
			delete(policy.Overrides, id)
		}
	}
	return policy
}

func (policy *CapabilityPolicy) Allows(id string) bool {
	if policy == nil {
		return true
	}
	if decision := policy.Overrides[id]; decision != "" {
		return decision == "allow"
	}
	return policy.Default != "deny"
}

func (policy *ApprovalPolicy) Decision(id, action string) string {
	if policy == nil {
		return ApprovalDecisionRisk
	}
	if override := policy.Overrides[id]; override != nil {
		if decision := override.Actions[action]; decision != "" {
			return decision
		}
		if override.Default != "" {
			return override.Default
		}
	}
	if policy.Default == "" {
		return ApprovalDecisionRisk
	}
	return policy.Default
}

func defaultEditing() *Editing {
	return &Editing{
		MaxHistoryMessages:  7,
		Temperature:         1.0,
		MaxCompletionTokens: 0,
	}
}

func defaultImageGeneration() *ImageGeneration {
	return &ImageGeneration{RequestTimeout: 300, Size: "1024x1024", Quality: "auto", OutputFormat: "png"}
}

func NewAI() *AI {
	ai := &AI{
		Providers:       []*Provider{},
		MCP:             &MCP{Servers: []MCPServer{}, ExposurePolicy: defaultCapabilityPolicy()},
		Embedding:       defaultEmbedding(),
		Rerank:          defaultRerank(),
		Decision:        defaultDecision(),
		Web:             &AIWeb{SearchProvider: "exa", FetchProvider: "direct", Timeout: 30},
		Agent:           defaultAgent(),
		Editing:         defaultEditing(),
		ImageGeneration: defaultImageGeneration(),
	}

	return ai
}

// ApplyAIEnvironment 仅由启动适配器调用,环境变量不参与默认值或日常规范化。
func ApplyAIEnvironment(ai *AI) {
	apiKey := os.Getenv("SIYUAN_OPENAI_API_KEY")
	apiModel := os.Getenv("SIYUAN_OPENAI_API_MODEL")
	apiBaseURL := os.Getenv("SIYUAN_OPENAI_API_BASE_URL")

	if apiModel != "" && apiBaseURL != "" {
		provider := &Provider{
			BaseURL:        apiBaseURL,
			RequestTimeout: 120,
			Enabled:        true,
			APIKey:         apiKey,
		}
		if timeout := os.Getenv("SIYUAN_OPENAI_API_TIMEOUT"); "" != timeout {
			if v, err := strconv.Atoi(timeout); err == nil {
				provider.RequestTimeout = v
			}
		}

		model := &Model{
			Name:    apiModel,
			Enabled: true,
		}
		if maxTokens := os.Getenv("SIYUAN_OPENAI_API_MAX_TOKENS"); "" != maxTokens {
			if v, err := strconv.Atoi(maxTokens); err == nil {
				ai.Editing.MaxCompletionTokens = v
			}
		}
		if temperature := os.Getenv("SIYUAN_OPENAI_API_TEMPERATURE"); "" != temperature {
			if v, err := strconv.ParseFloat(temperature, 64); err == nil {
				ai.Editing.Temperature = v
			}
		}
		if maxContexts := os.Getenv("SIYUAN_OPENAI_API_MAX_CONTEXTS"); "" != maxContexts {
			if v, err := strconv.Atoi(maxContexts); err == nil {
				ai.Editing.MaxHistoryMessages = v
			}
		}

		provider.Models = append(provider.Models, model)
		ai.Providers = append(ai.Providers, provider)
	}

	if agentTimeout := os.Getenv("SIYUAN_OPENAI_AGENT_TIMEOUT"); "" != agentTimeout {
		if v, err := strconv.Atoi(agentTimeout); err == nil {
			ai.Agent.SessionTimeout = v
		}
	}
	if agentStreamIdleTimeout := os.Getenv("SIYUAN_OPENAI_AGENT_STREAM_IDLE_TIMEOUT"); "" != agentStreamIdleTimeout {
		if v, err := strconv.Atoi(agentStreamIdleTimeout); err == nil {
			ai.Agent.StreamIdleTimeout = v
		}
	}
	if agentConfirmTimeout := os.Getenv("SIYUAN_OPENAI_AGENT_CONFIRM_TIMEOUT"); "" != agentConfirmTimeout {
		if v, err := strconv.Atoi(agentConfirmTimeout); err == nil {
			ai.Agent.ConfirmTimeout = v
		}
	}
	if agentMaxRetries := os.Getenv("SIYUAN_OPENAI_AGENT_MAX_RETRIES"); "" != agentMaxRetries {
		if v, err := strconv.Atoi(agentMaxRetries); err == nil {
			ai.Agent.MaxRetries = v
		}
	}
	if agentTemperature := os.Getenv("SIYUAN_OPENAI_AGENT_TEMPERATURE"); "" != agentTemperature {
		if v, err := strconv.ParseFloat(agentTemperature, 64); err == nil {
			ai.Agent.Temperature = v
		}
	}
	if agentMaxCompletionTokens := os.Getenv("SIYUAN_OPENAI_AGENT_MAX_COMPLETION_TOKENS"); "" != agentMaxCompletionTokens {
		if v, err := strconv.Atoi(agentMaxCompletionTokens); err == nil {
			ai.Agent.MaxCompletionTokens = v
		}
	}
	if agentMaxToolCallRounds := os.Getenv("SIYUAN_OPENAI_AGENT_MAX_TOOL_CALL_ROUNDS"); "" != agentMaxToolCallRounds {
		if v, err := strconv.Atoi(agentMaxToolCallRounds); err == nil {
			ai.Agent.MaxToolCallRounds = v
		}
	}

	embeddingKey := os.Getenv("SIYUAN_OPENAI_EMBEDDING_API_KEY")
	embeddingBaseURL := os.Getenv("SIYUAN_OPENAI_EMBEDDING_BASE_URL")
	embeddingModel := os.Getenv("SIYUAN_OPENAI_EMBEDDING_MODEL")
	if "" != embeddingKey && "" != embeddingBaseURL && "" != embeddingModel {
		ai.Embedding = &Embedding{
			APIKey:  embeddingKey,
			BaseURL: embeddingBaseURL,
			Name:    embeddingModel,
			Timeout: 30,
		}
	}

}

func (ai *AI) HasAnyProvider() bool {
	for _, p := range ai.Providers {
		if p != nil && p.Enabled {
			for _, m := range p.Models {
				if m != nil && m.Name != "" && m.Enabled {
					return true
				}
			}
		}
	}
	return false
}

func (ai *AI) GetModel(id string) (*Provider, *Model) {
	if id == "" {
		return nil, nil
	}

	for _, p := range ai.Providers {
		if p == nil || !p.Enabled {
			continue
		}
		for _, m := range p.Models {
			if m != nil && m.ID == id && m.Enabled {
				return p, m
			}
		}
	}

	for _, p := range ai.Providers {
		if p == nil || !p.Enabled {
			continue
		}
		for _, m := range p.Models {
			if m != nil && m.DisplayName == id && m.Enabled {
				return p, m
			}
		}
	}

	for _, p := range ai.Providers {
		if p == nil || !p.Enabled {
			continue
		}
		for _, m := range p.Models {
			if m != nil && m.Name == id && m.Enabled {
				return p, m
			}
		}
	}

	return nil, nil
}

func (ai *AI) GetEditingModel() (*Provider, *Model) {
	if ai.Editing == nil || ai.Editing.ModelID == "" {
		return nil, nil
	}
	return ai.GetModel(ai.Editing.ModelID)
}

func (ai *AI) GetAgentModel() (*Provider, *Model) {
	if ai.Agent == nil || ai.Agent.ModelID == "" {
		return nil, nil
	}
	return ai.GetModel(ai.Agent.ModelID)
}

func (ai *AI) GetImageGenerationModel() (*Provider, *Model) {
	if ai.ImageGeneration == nil || ai.ImageGeneration.ModelID == "" {
		return nil, nil
	}
	provider, model := ai.GetModel(ai.ImageGeneration.ModelID)
	if provider != nil && provider.AuthType == "chatgpt" {
		return nil, nil
	}
	return provider, model
}

// ReconcileModelIDs 校正各使用场景引用的模型,并将旧版名称引用转换为模型 ID。
// 编辑器和智能体始终回退到首个可用模型,可选的图片生成场景仅清理失效引用。
func (ai *AI) ReconcileModelIDs() {
	firstModelID := ""
	for _, p := range ai.Providers {
		if p == nil || !p.Enabled {
			continue
		}
		for _, m := range p.Models {
			if m != nil && m.Enabled && m.Name != "" {
				firstModelID = m.ID
				break
			}
		}
		if firstModelID != "" {
			break
		}
	}

	if ai.Editing == nil {
		ai.Editing = defaultEditing()
	}
	if _, m := ai.GetModel(ai.Editing.ModelID); m == nil {
		ai.Editing.ModelID = firstModelID
	} else {
		ai.Editing.ModelID = m.ID
	}
	if ai.Agent == nil {
		ai.Agent = defaultAgent()
	}
	if _, m := ai.GetModel(ai.Agent.ModelID); m == nil {
		ai.Agent.ModelID = firstModelID
	} else {
		ai.Agent.ModelID = m.ID
	}
	if ai.ImageGeneration != nil {
		if _, m := ai.GetModel(ai.ImageGeneration.ModelID); ai.ImageGeneration.ModelID != "" {
			if m == nil {
				ai.ImageGeneration.ModelID = ""
			} else {
				ai.ImageGeneration.ModelID = m.ID
			}
		}
	}
}

func (ai *AI) Normalize() {
	if ai.Providers == nil {
		ai.Providers = []*Provider{}
	}
	if ai.MCP == nil {
		ai.MCP = &MCP{Servers: []MCPServer{}, ExposurePolicy: defaultCapabilityPolicy()}
	} else if ai.MCP.Servers == nil {
		ai.MCP.Servers = []MCPServer{}
	}
	ai.MCP.ExposurePolicy = normalizeCapabilityPolicy(ai.MCP.ExposurePolicy)
	serverIDs := map[string]bool{}
	for i := range ai.MCP.Servers {
		if ai.MCP.Servers[i].ID == "" || serverIDs[ai.MCP.Servers[i].ID] {
			data := fmt.Appendf(nil, "mcp:%d:%s:%s", i, ai.MCP.Servers[i].Name, ai.MCP.Servers[i].Type)
			ai.MCP.Servers[i].ID = uuid.NewSHA1(uuid.NameSpaceOID, data).String()
		}
		serverIDs[ai.MCP.Servers[i].ID] = true
	}
	if ai.Agent == nil {
		ai.Agent = defaultAgent()
	} else {
		if ai.Agent.Skills == nil {
			ai.Agent.Skills = &AgentSkills{UserEnabled: []string{}, BuiltinDisabled: []string{}}
		} else {
			seen := map[string]struct{}{}
			normalized := []string{}
			for _, id := range ai.Agent.Skills.UserEnabled {
				id = strings.TrimSpace(id)
				key := strings.ToLower(id)
				if id == "" || id == "." || id == ".." || strings.ContainsAny(id, `/\`) {
					continue
				}
				if _, ok := seen[key]; ok {
					continue
				}
				seen[key] = struct{}{}
				normalized = append(normalized, id)
			}
			ai.Agent.Skills.UserEnabled = normalized
			// 保留未知内置 ID,升级或降级后不丢失用户的禁用选择。
			seen = map[string]struct{}{}
			normalized = []string{}
			for _, id := range ai.Agent.Skills.BuiltinDisabled {
				id = strings.TrimSpace(id)
				if id == "" {
					continue
				}
				if _, ok := seen[id]; ok {
					continue
				}
				seen[id] = struct{}{}
				normalized = append(normalized, id)
			}
			ai.Agent.Skills.BuiltinDisabled = normalized
		}
		ai.Agent.CapabilityPolicy = normalizeCapabilityPolicy(ai.Agent.CapabilityPolicy)
		if ai.Agent.ApprovalPolicy == nil {
			ai.Agent.ApprovalPolicy = defaultApprovalPolicy()
		} else {
			normalizeApprovalPolicy(ai.Agent.ApprovalPolicy)
		}
		if ai.Agent.SessionTimeout < 0 {
			ai.Agent.SessionTimeout = 0
		} else if ai.Agent.SessionTimeout > MaxAgentSessionTimeout {
			ai.Agent.SessionTimeout = MaxAgentSessionTimeout
		}
		if ai.Agent.StreamIdleTimeout < 1 {
			ai.Agent.StreamIdleTimeout = 120
		} else if ai.Agent.StreamIdleTimeout > 600 {
			ai.Agent.StreamIdleTimeout = 600
		}
		if ai.Agent.MaxRetries < 0 {
			ai.Agent.MaxRetries = 0
		} else if ai.Agent.MaxRetries > 10 {
			ai.Agent.MaxRetries = 10
		}
		if ai.Agent.ConfirmTimeout < 0 {
			ai.Agent.ConfirmTimeout = DefaultAgentConfirmTimeout
		}
		ai.Agent.MaxToolCallRounds = max(0, ai.Agent.MaxToolCallRounds)
		if ai.Agent.Temperature < 0 || ai.Agent.Temperature > 2 || math.IsNaN(ai.Agent.Temperature) {
			ai.Agent.Temperature = defaultAgent().Temperature
		}
		ai.Agent.MaxCompletionTokens = max(0, ai.Agent.MaxCompletionTokens)
	}
	ai.pruneOrphanedMCPCapabilityPolicies()
	if ai.Editing == nil {
		ai.Editing = defaultEditing()
	} else {
		if 0 > ai.Editing.MaxCompletionTokens {
			ai.Editing.MaxCompletionTokens = 0
		}
		if 0 > ai.Editing.Temperature {
			ai.Editing.Temperature = 0
		} else if 2 < ai.Editing.Temperature {
			ai.Editing.Temperature = 2
		}
		if 1 > ai.Editing.MaxHistoryMessages {
			ai.Editing.MaxHistoryMessages = 1
		} else if 64 < ai.Editing.MaxHistoryMessages {
			ai.Editing.MaxHistoryMessages = 64
		}
	}
	if ai.ImageGeneration == nil {
		ai.ImageGeneration = defaultImageGeneration()
	}
	if ai.ImageGeneration.RequestTimeout < 1 {
		ai.ImageGeneration.RequestTimeout = 300
	} else if ai.ImageGeneration.RequestTimeout > 600 {
		ai.ImageGeneration.RequestTimeout = 600
	}
	ai.ImageGeneration.Size = strings.TrimSpace(ai.ImageGeneration.Size)
	if ai.ImageGeneration.Size == "" {
		ai.ImageGeneration.Size = "1024x1024"
	}
	ai.ImageGeneration.Quality = strings.TrimSpace(ai.ImageGeneration.Quality)
	if ai.ImageGeneration.Quality == "" {
		ai.ImageGeneration.Quality = "auto"
	}
	ai.ImageGeneration.OutputFormat = strings.ToLower(strings.TrimSpace(ai.ImageGeneration.OutputFormat))
	if ai.ImageGeneration.OutputFormat != "jpeg" && ai.ImageGeneration.OutputFormat != "webp" {
		ai.ImageGeneration.OutputFormat = "png"
	}
	providers := make([]*Provider, 0, len(ai.Providers))
	for providerIndex, p := range ai.Providers {
		if p == nil {
			continue
		}
		p.BaseURL = strings.TrimSpace(p.BaseURL)
		if "" == p.BaseURL {
			p.BaseURL = "https://api.openai.com/v1"
			if util.IsAnthropicMessagesProtocol(p.Protocol) {
				p.BaseURL = "https://api.anthropic.com/v1"
			}
			if util.IsGeminiInteractionsProtocol(p.Protocol) {
				p.BaseURL = "https://generativelanguage.googleapis.com/v1beta"
			}
		}
		p.DisplayName = strings.TrimSpace(p.DisplayName)
		p.APIKey = strings.TrimSpace(p.APIKey)
		if p.AuthType == "chatgpt" {
			p.APIKey = ""
			p.BaseURL = "https://api.openai.com/v1"
			p.Protocol = util.OpenAIProtocolResponses
			p.Headers = nil
		}
		p.Protocol = strings.ToLower(strings.TrimSpace(p.Protocol))
		if p.Protocol == "" {
			p.Protocol = util.OpenAIProtocolChatCompletions
		}
		if 1 > p.RequestTimeout {
			p.RequestTimeout = 120
		} else if 600 < p.RequestTimeout {
			p.RequestTimeout = 600
		}
		if !ast.IsNodeIDPattern(p.ID) {
			p.ID = normalizedAIID(fmt.Sprintf("provider:%d:%s", providerIndex, p.DisplayName))
		}
		models := make([]*Model, 0, len(p.Models))
		for modelIndex, m := range p.Models {
			if m == nil {
				continue
			}
			m.Name = strings.TrimSpace(m.Name)
			if "" == m.Name {
				m.Name = "model"
			}
			m.DisplayName = strings.TrimSpace(m.DisplayName)
			if m.ContextLength < 0 || 100000000 < m.ContextLength {
				m.ContextLength = 0
			}
			if !ast.IsNodeIDPattern(m.ID) {
				m.ID = normalizedAIID(fmt.Sprintf("model:%s:%d:%s", p.ID, modelIndex, m.Name))
			}
			models = append(models, m)
		}
		p.Models = models
		providers = append(providers, p)
	}
	ai.Providers = providers
	if ai.Embedding == nil {
		ai.Embedding = defaultEmbedding()
	}
	if ai.Embedding.Timeout < 1 {
		ai.Embedding.Timeout = 30
	}
	if ai.Embedding.Dimensions < 0 {
		ai.Embedding.Dimensions = 0 // 负值非法,归零表示用模型默认维度
	}
	if ai.Embedding.Concurrency < 1 {
		ai.Embedding.Concurrency = DefaultEmbeddingConcurrency
	}
	ai.Embedding.Concurrency = min(ai.Embedding.Concurrency, MaxEmbeddingConcurrency)
	if ai.Embedding.BatchSize < 1 {
		ai.Embedding.BatchSize = DefaultEmbeddingBatchSize
	}
	ai.Embedding.BatchSize = min(ai.Embedding.BatchSize, MaxEmbeddingBatchSize)
	if !ast.IsNodeIDPattern(ai.Embedding.ID) {
		ai.Embedding.ID = normalizedAIID("embedding")
	}
	if ai.Rerank == nil {
		ai.Rerank = defaultRerank()
	}
	if ai.Decision == nil {
		ai.Decision = defaultDecision()
	}
	ai.Decision.Normalize()
	if ai.Web == nil {
		ai.Web = &AIWeb{}
	}
	ai.Web.Normalize()
	if ai.Rerank.Timeout < 1 {
		ai.Rerank.Timeout = 30
	}
	if util.RerankRequestFormatCohere != ai.Rerank.RequestFormat &&
		util.RerankRequestFormatDashScope != ai.Rerank.RequestFormat {
		ai.Rerank.RequestFormat = util.RerankRequestFormatCohere
	}
	if ai.Rerank.CandidateCount < 5 {
		ai.Rerank.CandidateCount = 5
	} else if ai.Rerank.CandidateCount > 100 {
		ai.Rerank.CandidateCount = 100
	}
	if !ast.IsNodeIDPattern(ai.Rerank.ID) {
		ai.Rerank.ID = normalizedAIID("rerank")
	}
}

// normalizedAIID 补全缺失标识时仅依赖公开配置位置,保持区块 ID 形态且不包含凭据。
func normalizedAIID(seed string) string {
	id := uuid.NewSHA1(uuid.NameSpaceOID, []byte(seed))
	return "20000101000000-" + hex.EncodeToString(id[:])[:7]
}

func (ai *AI) pruneOrphanedMCPCapabilityPolicies() {
	configuredServerIDs := make(map[string]bool, len(ai.MCP.Servers))
	for _, server := range ai.MCP.Servers {
		configuredServerIDs[url.PathEscape(server.ID)] = true
	}

	isOrphaned := func(id string) bool {
		const prefix = "mcp/backend/"
		if !strings.HasPrefix(id, prefix) {
			return false
		}
		serverID, _, ok := strings.Cut(strings.TrimPrefix(id, prefix), "/")
		return ok && !configuredServerIDs[serverID]
	}
	for id := range ai.Agent.CapabilityPolicy.Overrides {
		if isOrphaned(id) {
			delete(ai.Agent.CapabilityPolicy.Overrides, id)
		}
	}
	for id := range ai.Agent.ApprovalPolicy.Overrides {
		if isOrphaned(id) {
			delete(ai.Agent.ApprovalPolicy.Overrides, id)
		}
	}
}

func normalizeApprovalPolicy(policy *ApprovalPolicy) {
	// 旧版中的 confirm 表示未自动批准,实际仍按操作风险判断,因此迁移为 risk。
	if policy.Default == ApprovalDecisionConfirm ||
		policy.Default != ApprovalDecisionAllow && policy.Default != ApprovalDecisionRisk {
		policy.Default = ApprovalDecisionRisk
	}
	if policy.Overrides == nil {
		policy.Overrides = map[string]*CapabilityApproval{}
	}
	for id, override := range policy.Overrides {
		if id == "" || override == nil {
			delete(policy.Overrides, id)
			continue
		}
		if override.Default != ApprovalDecisionAllow && override.Default != ApprovalDecisionConfirm &&
			override.Default != ApprovalDecisionRisk {
			override.Default = ""
		}
		if override.Actions == nil {
			override.Actions = map[string]string{}
		}
		for action, decision := range override.Actions {
			if decision != ApprovalDecisionAllow && decision != ApprovalDecisionConfirm &&
				decision != ApprovalDecisionRisk {
				delete(override.Actions, action)
			}
		}
		if override.Default == "" && len(override.Actions) == 0 {
			delete(policy.Overrides, id)
		}
	}
}

func (ai *AI) DecryptAPIKeys() {
	if ai.Web != nil && ai.Web.APIKey != "" {
		if dec := util.AESDecrypt(ai.Web.APIKey); dec != nil {
			if plain, err := hex.DecodeString(string(dec)); err == nil {
				ai.Web.APIKey = string(plain)
			}
		}
	}
	if ai.Decision != nil {
		decrypt := func(key *string) {
			if *key != "" {
				if dec := util.AESDecrypt(*key); dec != nil {
					if plain, err := hex.DecodeString(string(dec)); err == nil {
						*key = string(plain)
					}
				}
			}
		}
		decrypt(&ai.Decision.APIKey)
		for _, profile := range ai.Decision.Profiles {
			if profile != nil {
				decrypt(&profile.APIKey)
			}
		}
	}

	for _, p := range ai.Providers {
		if p == nil || p.APIKey == "" {
			continue
		}
		dec := util.AESDecrypt(p.APIKey)
		if dec == nil {
			continue
		}
		if plain, err := hex.DecodeString(string(dec)); err == nil {
			p.APIKey = string(plain)
		}
	}
	if ai.Embedding != nil && ai.Embedding.APIKey != "" {
		dec := util.AESDecrypt(ai.Embedding.APIKey)
		if dec == nil {
			return
		}
		if plain, err := hex.DecodeString(string(dec)); err == nil {
			ai.Embedding.APIKey = string(plain)
		}
	}
	if ai.Rerank != nil && ai.Rerank.APIKey != "" {
		dec := util.AESDecrypt(ai.Rerank.APIKey)
		if dec == nil {
			return
		}
		if plain, err := hex.DecodeString(string(dec)); err == nil {
			ai.Rerank.APIKey = string(plain)
		}
	}
}

func (ai *AI) EncryptAPIKeys() {
	if ai.Web != nil && ai.Web.APIKey != "" {
		ai.Web.APIKey = util.AESEncrypt(ai.Web.APIKey)
	}
	if ai.Decision != nil {
		ai.Decision.Normalize()
		for _, profile := range ai.Decision.Profiles {
			if profile != nil && profile.APIKey != "" {
				profile.APIKey = util.AESEncrypt(profile.APIKey)
			}
		}
	}

	for _, p := range ai.Providers {
		if p == nil || p.APIKey == "" {
			continue
		}
		p.APIKey = util.AESEncrypt(p.APIKey)
	}
	if ai.Embedding != nil && ai.Embedding.APIKey != "" {
		ai.Embedding.APIKey = util.AESEncrypt(ai.Embedding.APIKey)
	}
	if ai.Rerank != nil && ai.Rerank.APIKey != "" {
		ai.Rerank.APIKey = util.AESEncrypt(ai.Rerank.APIKey)
	}
}

func NeedsAIMigration(data []byte) bool {
	var topRaw map[string]json.RawMessage
	if err := json.Unmarshal(data, &topRaw); err != nil {
		return false
	}
	aiRaw, ok := topRaw["ai"]
	if !ok {
		return false
	}
	var raw map[string]json.RawMessage
	if err := json.Unmarshal(aiRaw, &raw); err != nil {
		return false
	}
	_, ok = raw["openAI"]
	return ok
}

func MigrateAI(data []byte) *AI {
	var topRaw map[string]json.RawMessage
	if err := json.Unmarshal(data, &topRaw); err != nil {
		return NewAI()
	}
	aiRaw, ok := topRaw["ai"]
	if !ok {
		return NewAI()
	}
	var raw map[string]any
	if err := json.Unmarshal(aiRaw, &raw); err != nil {
		return NewAI()
	}

	ai := &AI{}

	if mcp, ok := raw["mcp"].(map[string]any); ok {
		ai.MCP = migrateMCP(mcp)
	}

	if oai, ok := raw["openAI"].(map[string]any); ok {
		prov := migrateProvider(oai)
		m := migrateModel(oai)
		prov.Models = append(prov.Models, m)
		ai.Providers = append(ai.Providers, prov)

		ai.Agent = &Agent{
			SessionTimeout:    getInt(oai, "agentTimeout"),
			ConfirmTimeout:    getInt(oai, "agentConfirmTimeout"),
			MaxRetries:        getInt(oai, "agentMaxRetries"),
			MaxToolCallRounds: 64,
		}

		maxContexts := getInt(oai, "apiMaxContexts")
		ai.Editing = &Editing{
			MaxHistoryMessages:  maxContexts,
			Temperature:         getFloat(oai, "apiTemperature"),
			MaxCompletionTokens: getInt(oai, "apiMaxTokens"),
		}
	}

	if provs, ok := raw["providers"].([]any); ok {
		for _, item := range provs {
			p, ok2 := item.(map[string]any)
			if !ok2 {
				continue
			}
			if getString(p, "type") == "embedding" {
				ai.Embedding = migrateEmbedding(p)
			} else {
				m := migrateModel(p)
				oldBaseURL := getString(p, "apiBaseURL")
				if existing := findProviderByBaseURL(ai.Providers, oldBaseURL); existing != nil {
					existing.Models = append(existing.Models, m)
				} else {
					prov := migrateProvider(p)
					prov.Models = append(prov.Models, m)
					ai.Providers = append(ai.Providers, prov)
				}
			}
		}
	}

	ai.Normalize()
	assignDefaultModelIDs(ai)

	return ai
}

func assignDefaultModelIDs(ai *AI) {
	if (ai.Editing != nil && ai.Editing.ModelID != "") || (ai.Agent != nil && ai.Agent.ModelID != "") {
		return
	}
	var m *Model
	for _, p := range ai.Providers {
		if p == nil || !p.Enabled {
			continue
		}
		for _, model := range p.Models {
			if model != nil && model.Name != "" && model.Enabled {
				m = model
				break
			}
		}
		if m != nil {
			break
		}
	}
	if m == nil && len(ai.Providers) > 0 && ai.Providers[0] != nil && len(ai.Providers[0].Models) > 0 {
		m = ai.Providers[0].Models[0]
	}
	if m == nil || m.ID == "" {
		return
	}
	if ai.Editing == nil {
		ai.Editing = &Editing{}
	}
	if ai.Editing.ModelID == "" {
		ai.Editing.ModelID = m.ID
	}
	if ai.Agent == nil {
		ai.Agent = &Agent{MaxToolCallRounds: 64}
	}
	if ai.Agent.ModelID == "" {
		ai.Agent.ModelID = m.ID
	}
}

func findProviderByBaseURL(providers []*Provider, baseURL string) *Provider {
	for _, p := range providers {
		if p != nil && p.BaseURL == baseURL && baseURL != "" {
			return p
		}
	}
	return nil
}

func migrateMCP(raw map[string]any) *MCP {
	mcp := &MCP{}
	servers, ok := raw["servers"].([]any)
	if !ok {
		return mcp
	}
	for _, s := range servers {
		sm, ok2 := s.(map[string]any)
		if !ok2 {
			continue
		}
		mcp.Servers = append(mcp.Servers, MCPServer{
			ID:                   getString(sm, "id"),
			Name:                 getString(sm, "name"),
			Enabled:              getBool(sm, "enabled"),
			Type:                 getString(sm, "type"),
			Command:              getString(sm, "command"),
			Args:                 getStringSlice(sm, "args"),
			InheritEnv:           getStringSlice(sm, "inheritEnv"),
			Env:                  getStringMap(sm, "env"),
			URL:                  getString(sm, "url"),
			Headers:              getStringMap(sm, "headers"),
			Timeout:              getInt(sm, "timeout"),
			DisableStandaloneSSE: getBool(sm, "disableStandaloneSSE"),
			TrustToolAnnotations: getBool(sm, "trustToolAnnotations"),
		})
	}
	return mcp
}

func migrateProvider(raw map[string]any) *Provider {
	return &Provider{
		ID:             getString(raw, "id"),
		Enabled:        true,
		APIKey:         getString(raw, "apiKey"),
		BaseURL:        getString(raw, "apiBaseURL"),
		RequestTimeout: getInt(raw, "apiTimeout"),
	}
}

func migrateModel(raw map[string]any) *Model {
	enabled := true
	if v, ok := raw["enabled"]; ok {
		if b, ok2 := v.(bool); ok2 && !b {
			enabled = false
		}
	}
	return &Model{
		ID:          getString(raw, "id"),
		DisplayName: getString(raw, "name"),
		Enabled:     enabled,
		Name:        getString(raw, "apiModel"),
	}
}

func migrateEmbedding(raw map[string]any) *Embedding {
	return &Embedding{
		ID:      getString(raw, "id"),
		Enabled: getBool(raw, "enabled"),
		APIKey:  getString(raw, "apiKey"),
		BaseURL: getString(raw, "apiBaseURL"),
		Name:    getString(raw, "apiModel"),
		Timeout: getInt(raw, "apiTimeout"),
	}
}

func getString(m map[string]any, key string) string {
	if v, ok := m[key]; ok {
		if s, ok := v.(string); ok {
			return s
		}
	}
	return ""
}

func getInt(m map[string]any, key string) int {
	if v, ok := m[key]; ok {
		if f, ok := v.(float64); ok {
			return int(f)
		}
	}
	return 0
}

func getFloat(m map[string]any, key string) float64 {
	if v, ok := m[key]; ok {
		if f, ok := v.(float64); ok {
			return f
		}
	}
	return 0
}

func getBool(m map[string]any, key string) bool {
	if v, ok := m[key]; ok {
		if b, ok := v.(bool); ok {
			return b
		}
	}
	return false
}

func getStringSlice(m map[string]any, key string) []string {
	if v, ok := m[key]; ok {
		if arr, ok := v.([]any); ok {
			ret := make([]string, 0, len(arr))
			for _, item := range arr {
				if s, ok := item.(string); ok {
					ret = append(ret, s)
				}
			}
			return ret
		}
	}
	return nil
}

func getStringMap(m map[string]any, key string) map[string]string {
	if v, ok := m[key]; ok {
		if sm, ok := v.(map[string]any); ok {
			ret := make(map[string]string)
			for k, val := range sm {
				if s, ok := val.(string); ok {
					ret[k] = s
				}
			}
			return ret
		}
	}
	return nil
}