types

type AccumulatedToolCall struct {
	ID        string
	Type      string
	Name      string
	Arguments string // 累积的 JSON 参数
}

type AgentChannel string

type AgentConfig struct {
	AgentID          string                    `json:"agent_id,omitempty" yaml:"agent_id,omitempty"`
	TemplateID       string                    `json:"template_id" yaml:"template_id"`
	TemplateVersion  string                    `json:"template_version,omitempty" yaml:"template_version,omitempty"`
	ModelConfig      *ModelConfig              `json:"model_config,omitempty" yaml:"model_config,omitempty"`
	Sandbox          *SandboxConfig            `json:"sandbox,omitempty" yaml:"sandbox,omitempty"`
	Store            *StoreConfig              `json:"store,omitempty" yaml:"store,omitempty"` // Store 存储配置
	Tools            []string                  `json:"tools,omitempty" yaml:"tools,omitempty"`
	Middlewares      []string                  `json:"middlewares,omitempty" yaml:"middlewares,omitempty"`             // Middleware 列表 (Phase 6C)
	MiddlewareConfig map[string]map[string]any `json:"middleware_config,omitempty" yaml:"middleware_config,omitempty"` // 各中间件的自定义配置
	ExposeThinking   bool                      `json:"expose_thinking,omitempty" yaml:"expose_thinking,omitempty"`
	// RoutingProfile 可选的路由配置标识，例如 "quality-first"、"cost-first"。
	// 当配置了 Router 时，可以根据该字段选择不同的模型路由策略。
	RoutingProfile string                 `json:"routing_profile,omitempty" yaml:"routing_profile,omitempty"`
	Overrides      *AgentConfigOverrides  `json:"overrides,omitempty" yaml:"overrides,omitempty"`
	Context        *ContextManagerOptions `json:"context,omitempty" yaml:"context,omitempty"`
	SkillsPackage  *SkillsPackageConfig   `json:"skills_package,omitempty" yaml:"skills_package,omitempty"` // Skills 包配置
	Metadata       map[string]any         `json:"metadata,omitempty" yaml:"metadata,omitempty"`

	// Multitenancy 多租户配置
	Multitenancy *MultitenancyConfig `json:"multitenancy,omitempty" yaml:"multitenancy,omitempty"`

	// Memory 记忆系统配置（包含向量存储和嵌入模型）
	Memory *MemoryConfig `json:"memory,omitempty" yaml:"memory,omitempty"`

	// CanUseTool 自定义权限检查回调（不序列化）
	// 应用层可以通过此回调完全控制工具权限
	CanUseTool CanUseToolFunc `json:"-"`

	// AllowDangerouslySkipPermissions 允许绕过权限检查
	// 必须显式设置为 true 才能使用 PermissionMode: "bypassPermissions"
	AllowDangerouslySkipPermissions bool `json:"allow_dangerously_skip_permissions,omitempty"`
}

type AgentConfigOverrides struct {
	Permission *PermissionConfig `json:"permission,omitempty"`
	Todo       *TodoConfig       `json:"todo,omitempty"`
}

type AgentEventEnvelope struct {
	Cursor   int64    `json:"cursor"`
	Bookmark Bookmark `json:"bookmark"`
	Event    any      `json:"event"`
}

type AgentInfo struct {
	ID            string         `json:"id"`                    // Agent ID
	AgentID       string         `json:"agent_id"`              // Agent ID（别名）
	TemplateID    string         `json:"template_id"`           // 使用的模板 ID
	Model         string         `json:"model"`                 // 模型名称
	CreatedAt     time.Time      `json:"created_at"`            // 创建时间
	UpdatedAt     time.Time      `json:"updated_at"`            // 更新时间
	State         AgentState     `json:"state"`                 // 当前状态
	StepCount     int            `json:"step_count"`            // 总步骤数
	Cursor        int            `json:"cursor"`                // 当前游标
	MessageCount  int            `json:"message_count"`         // 消息数量（新字段）
	Lineage       []string       `json:"lineage"`               // 血缘关系（新字段）
	ConfigVersion string         `json:"config_version"`        // 配置版本（新字段）
	Metadata      map[string]any `json:"metadata"`              // 自定义元数据
	Tags          []string       `json:"tags,omitempty"`        // 标签
	Description   string         `json:"description,omitempty"` // 描述
}

type AgentRuntimeState string

type AgentState string

type AgentStatus struct {
	AgentID      string            `json:"agent_id"`       // Agent ID
	State        AgentRuntimeState `json:"state"`          // 运行时状态
	StepCount    int               `json:"step_count"`     // 步骤数
	LastSfpIndex int               `json:"last_sfp_index"` // 最后 SFP 索引
	LastBookmark *Bookmark         `json:"last_bookmark"`  // 最后书签
	Cursor       int64             `json:"cursor"`         // 游标
	Breakpoint   BreakpointState   `json:"breakpoint"`     // 断点状态
}

type AgentTemplateDefinition struct {
	ID           string                `json:"id"`
	Version      string                `json:"version,omitempty"`
	SystemPrompt string                `json:"system_prompt"`
	Model        string                `json:"model,omitempty"`
	Tools        any                   `json:"tools"` // []string or "*"
	Permission   *PermissionConfig     `json:"permission,omitempty"`
	Runtime      *AgentTemplateRuntime `json:"runtime,omitempty"`
}

type AgentTemplateRuntime struct {
	ExposeThinking          bool                           `json:"expose_thinking,omitempty"`
	Todo                    *TodoConfig                    `json:"todo,omitempty"`
	SubAgents               *SubAgentConfig                `json:"subagents,omitempty"`
	Metadata                map[string]any                 `json:"metadata,omitempty"`
	ToolTimeoutMs           int                            `json:"tool_timeout_ms,omitempty"`
	MaxToolConcurrency      int                            `json:"max_tool_concurrency,omitempty"`
	ToolsManual             *ToolsManualConfig             `json:"tools_manual,omitempty"`
	PromptCompression       *PromptCompressionConfig       `json:"prompt_compression,omitempty"`
	ConversationCompression *ConversationCompressionConfig `json:"conversation_compression,omitempty"`
	DisabledPromptModules   []string                       `json:"disabled_prompt_modules,omitempty"` // 要禁用的 prompt 模块列表
}

type Alignment string

type AsterUIMessage struct {
	// CreateSurface 创建 Surface 消息
	CreateSurface *CreateSurfaceMessage `json:"createSurface,omitempty"`
	// SurfaceUpdate Surface 更新消息
	SurfaceUpdate *SurfaceUpdateMessage `json:"surfaceUpdate,omitempty"`
	// DataModelUpdate 数据模型更新消息
	DataModelUpdate *DataModelUpdateMessage `json:"dataModelUpdate,omitempty"`
	// BeginRendering 开始渲染消息
	BeginRendering *BeginRenderingMessage `json:"beginRendering,omitempty"`
	// DeleteSurface 删除 Surface 消息
	DeleteSurface *DeleteSurfaceMessage `json:"deleteSurface,omitempty"`
}

type AudioContent struct {
	// Type 音频来源类型: "url", "base64"
	Type string `json:"type"`

	// Source 音频源
	Source string `json:"source"`

	// MimeType MIME 类型，如 "audio/mp3", "audio/wav"
	MimeType string `json:"mime_type,omitempty"`

	// Format 音频格式 (用于某些 Provider)
	Format string `json:"format,omitempty"`

	// Transcript 音频转录文本 (可选)
	Transcript string `json:"transcript,omitempty"`
}

type AudioPlayerProps struct {
	// Src 音频 URL
	Src PropertyValue `json:"src"`
	// Title 标题
	Title *PropertyValue `json:"title,omitempty"`
	// Autoplay 是否自动播放
	Autoplay *PropertyValue `json:"autoplay,omitempty"`
	// Loop 是否循环播放
	Loop *PropertyValue `json:"loop,omitempty"`
}

type BeginRenderingMessage struct {
	// SurfaceID Surface 唯一标识符
	SurfaceID string `json:"surfaceId"`
	// Root 根组件 ID
	Root string `json:"root"`
	// Styles CSS 自定义属性（主题化支持）
	Styles map[string]string `json:"styles,omitempty"`
	// CatalogID 组件目录标识符（可选，覆盖 createSurface 中的值）
	CatalogID string `json:"catalogId,omitempty"`
}

type Bookmark struct {
	// Cursor 游标位置
	Cursor int64 `json:"cursor"`

	// Timestamp 时间戳
	Timestamp int64 `json:"timestamp,omitempty"`
}

type BreakpointState struct {
	// Enabled 是否启用
	Enabled bool `json:"enabled"`

	// Condition 断点条件
	Condition string `json:"condition,omitempty"`

	// HitCount 命中次数
	HitCount int `json:"hit_count,omitempty"`
}

type ButtonProps struct {
	// Label 按钮标签
	Label PropertyValue `json:"label"`
	// Action 动作标识符（用于事件回调）
	Action string `json:"action"`
	// Variant 按钮变体
	Variant ButtonVariant `json:"variant,omitempty"`
	// Disabled 是否禁用
	Disabled *PropertyValue `json:"disabled,omitempty"`
	// Icon 图标名称
	Icon *PropertyValue `json:"icon,omitempty"`
	// ActionContext 动作上下文（点击时自动解析路径引用）
	ActionContext map[string]PropertyValue `json:"actionContext,omitempty"`
}

type ButtonVariant string

type CacheControlBlock struct {
	// Type 缓存类型: "ephemeral"
	Type string `json:"type"`

	// Content 被缓存的内容
	Content ContentBlock `json:"content"`
}

type CanUseToolFunc func(
	ctx context.Context,
	toolName string,
	input map[string]any,
	opts *CanUseToolOptions,
) (*PermissionResult, error)

type CanUseToolOptions struct {
	// Signal 用于取消操作的上下文
	Signal context.Context

	// Suggestions 建议的权限更新
	Suggestions []PermissionUpdate

	// SandboxEnabled 沙箱是否启用
	SandboxEnabled bool

	// BypassSandboxRequested 是否请求绕过沙箱
	BypassSandboxRequested bool
}

type CardProps struct {
	// Children 子组件引用
	Children ComponentArrayReference `json:"children"`
	// Title 标题
	Title *PropertyValue `json:"title,omitempty"`
	// Subtitle 副标题
	Subtitle *PropertyValue `json:"subtitle,omitempty"`
	// Clickable 是否可点击
	Clickable *bool `json:"clickable,omitempty"`
	// Action 点击动作标识符
	Action string `json:"action,omitempty"`
}

type CheckboxProps struct {
	// Checked 选中状态（必须是 path 类型，用于双向绑定）
	Checked PropertyValue `json:"checked"`
	// Label 标签
	Label *PropertyValue `json:"label,omitempty"`
	// Disabled 是否禁用
	Disabled *PropertyValue `json:"disabled,omitempty"`
}

type ClientMessage struct {
	// UserAction 用户动作消息
	UserAction *UserActionMessage `json:"userAction,omitempty"`
	// Error 错误消息
	Error *ProtocolError `json:"error,omitempty"`
}

type CloudCredentials struct {
	AccessKeyID     string `json:"access_key_id,omitempty"`
	AccessKeySecret string `json:"access_key_secret,omitempty"`
	Token           string `json:"token,omitempty"`
}

type CloudSandboxConfig struct {
	Provider    string           `json:"provider"` // "aliyun", "volcengine"
	Region      string           `json:"region"`
	Credentials CloudCredentials `json:"credentials"`
	SessionID   string           `json:"session_id,omitempty"`
	Resources   ResourceLimits   `json:"resources,omitempty"`
}

type ColumnProps struct {
	// Children 子组件引用
	Children ComponentArrayReference `json:"children"`
	// Gap 间距（像素）
	Gap *int `json:"gap,omitempty"`
	// Align 对齐方式
	Align Alignment `json:"align,omitempty"`
}

type CompleteResult struct {
	Status        string    `json:"status"` // "ok" or "paused"
	Text          string    `json:"text,omitempty"`
	Last          *Bookmark `json:"last,omitempty"`
	PermissionIDs []string  `json:"permission_ids,omitempty"`
}

type ComponentArrayReference struct {
	// ExplicitList 显式 ID 列表
	ExplicitList []string `json:"explicitList,omitempty"`
	// Template 模板方式（用于动态列表）
	Template *ComponentTemplate `json:"template,omitempty"`
}

type ComponentDefinition struct {
	// ID 组件唯一标识符
	ID string `json:"id"`
	// Weight 流式渲染权重
	Weight ComponentWeight `json:"weight,omitempty"`
	// Component 组件规格
	Component ComponentSpec `json:"component"`
}

type ComponentSpec struct {
	Text           *TextProps           `json:"Text,omitempty"`
	Image          *ImageProps          `json:"Image,omitempty"`
	Icon           *IconProps           `json:"Icon,omitempty"`
	Video          *VideoProps          `json:"Video,omitempty"`
	AudioPlayer    *AudioPlayerProps    `json:"AudioPlayer,omitempty"`
	Button         *ButtonProps         `json:"Button,omitempty"`
	Row            *RowProps            `json:"Row,omitempty"`
	Column         *ColumnProps         `json:"Column,omitempty"`
	Card           *CardProps           `json:"Card,omitempty"`
	List           *ListProps           `json:"List,omitempty"`
	TextField      *TextFieldProps      `json:"TextField,omitempty"`
	Checkbox       *CheckboxProps       `json:"Checkbox,omitempty"`
	Select         *SelectProps         `json:"Select,omitempty"`
	DateTimeInput  *DateTimeInputProps  `json:"DateTimeInput,omitempty"`
	Slider         *SliderProps         `json:"Slider,omitempty"`
	MultipleChoice *MultipleChoiceProps `json:"MultipleChoice,omitempty"`
	Divider        *DividerProps        `json:"Divider,omitempty"`
	Modal          *ModalProps          `json:"Modal,omitempty"`
	Tabs           *TabsProps           `json:"Tabs,omitempty"`
	Custom         *CustomProps         `json:"Custom,omitempty"`
}

type ComponentTemplate struct {
	// ComponentID 模板组件 ID
	ComponentID string `json:"componentId"`
	// DataBinding 数据源路径（JSON Pointer）
	DataBinding string `json:"dataBinding"`
}

type ComponentWeight string

type ContentBlock interface {
	IsContentBlock()
}

type ContentBlockHelper struct{}

type ContextManagerOptions struct {
	MaxTokens         int    `json:"max_tokens"`
	CompressToTokens  int    `json:"compress_to_tokens"`
	CompressionModel  string `json:"compression_model,omitempty"`
	EnableCompression bool   `json:"enable_compression"`
}

type ControlAskUserEvent struct {
	RequestID string                             `json:"request_id"`
	Questions []Question                         `json:"questions"`
	Respond   func(answers map[string]any) error `json:"-"` // 响应回调
}

type ControlIterationLimitEvent struct {
	CurrentIteration int    `json:"current_iteration"`
	MaxIteration     int    `json:"max_iteration"`
	Message          string `json:"message"`
}

type ControlPermissionDecidedEvent struct {
	CallID    string `json:"call_id"`
	Decision  string `json:"decision"` // "allow" or "deny"
	DecidedBy string `json:"decided_by"`
	Note      string `json:"note,omitempty"`
}

type ControlPermissionRequiredEvent struct {
	Call    ToolCallSnapshot `json:"call"`
	Respond RespondFunc      `json:"-"` // 不序列化回调函数
}

type ControlToolControlEvent struct {
	CallID string `json:"call_id"`
	Action string `json:"action"` // pause|resume|cancel
	Note   string `json:"note,omitempty"`
}

type ControlToolControlResponseEvent struct {
	CallID string `json:"call_id"`
	Action string `json:"action"` // pause|resume|cancel
	OK     bool   `json:"ok"`
	Reason string `json:"reason,omitempty"`
}

type ControlUIActionEvent struct {
	// SurfaceID Surface 唯一标识符
	SurfaceID string `json:"surface_id"`
	// ComponentID 组件 ID
	ComponentID string `json:"component_id"`
	// Action 动作标识符
	Action string `json:"action"`
	// Payload 附加数据
	Payload map[string]any `json:"payload,omitempty"`
}

type ControlUserAnswerEvent struct {
	RequestID string         `json:"request_id"`
	Answers   map[string]any `json:"answers"` // question_index -> answer(s)
}

type ConversationCompressionConfig struct {
	// Enabled 是否启用对话压缩
	Enabled bool `json:"enabled"`

	// TokenBudget 总 Token 预算
	// 默认值: 200000
	TokenBudget int `json:"token_budget,omitempty"`

	// Threshold 触发压缩的使用率阈值 (0.0-1.0)
	// 当 Token 使用率达到此阈值时触发压缩
	// 默认值: 0.80 (80%)
	Threshold float64 `json:"threshold,omitempty"`

	// MinMessagesToKeep 压缩后最少保留的消息数
	// 默认值: 6
	MinMessagesToKeep int `json:"min_messages_to_keep,omitempty"`

	// SummaryLanguage 摘要语言
	// - "zh": 中文
	// - "en": 英文
	// 默认值: "zh"
	SummaryLanguage string `json:"summary_language,omitempty"`

	// UseLLMSummarizer 是否使用 LLM 生成摘要
	// 如果为 false，使用基于规则的快速摘要
	// 默认值: false
	UseLLMSummarizer bool `json:"use_llm_summarizer,omitempty"`
}

type CreateSurfaceMessage struct {
	// SurfaceID Surface 唯一标识符
	SurfaceID string `json:"surfaceId"`
	// CatalogID 组件目录标识符（推荐使用 URL 格式）
	CatalogID string `json:"catalogId,omitempty"`
}

type CustomProps struct {
	// Type 已注册的自定义组件类型名称
	Type string `json:"type"`
	// Props 自定义属性
	Props map[string]PropertyValue `json:"props"`
}

type DataModelOperation string

type DataModelUpdateMessage struct {
	// SurfaceID Surface 唯一标识符
	SurfaceID string `json:"surfaceId"`
	// Path JSON Pointer 路径，默认 "/" 表示根路径
	Path string `json:"path,omitempty"`
	// Op 操作类型：add/replace/remove，默认 replace
	Op DataModelOperation `json:"op,omitempty"`
	// Contents 数据内容（op 为 remove 时可选）
	Contents any `json:"contents,omitempty"`
}

type DateTimeInputProps struct {
	// Value 值（必须是 path 类型，用于双向绑定）
	Value PropertyValue `json:"value"`
	// Label 标签
	Label *PropertyValue `json:"label,omitempty"`
	// Type 输入类型
	Type DateTimeInputType `json:"type,omitempty"`
	// Disabled 是否禁用
	Disabled *PropertyValue `json:"disabled,omitempty"`
	// Min 最小值
	Min *PropertyValue `json:"min,omitempty"`
	// Max 最大值
	Max *PropertyValue `json:"max,omitempty"`
}

type DateTimeInputType string

type DeleteSurfaceMessage struct {
	// SurfaceID Surface 唯一标识符
	SurfaceID string `json:"surfaceId"`
}

type DividerOrientation string

type DividerProps struct {
	// Orientation 方向
	Orientation DividerOrientation `json:"orientation,omitempty"`
}

type DocumentContent struct {
	// Type 文档类型: "url", "base64", "text"
	Type string `json:"type"`

	// Source 文档源
	Source string `json:"source"`

	// MimeType MIME 类型，如 "application/pdf", "text/plain"
	MimeType string `json:"mime_type,omitempty"`

	// Title 文档标题
	Title string `json:"title,omitempty"`
}

type EmbedderConfig struct {
	// Provider 嵌入模型提供商
	// - "openai": OpenAI Embeddings
	// - "gemini": Google Gemini Embeddings
	// - "local": 本地嵌入模型
	Provider string `json:"provider" yaml:"provider"`

	// Model 嵌入模型名称
	// OpenAI: "text-embedding-3-small", "text-embedding-3-large", "text-embedding-ada-002"
	// Gemini: "text-embedding-004", "text-multilingual-embedding-002"
	Model string `json:"model" yaml:"model"`

	// APIKey API 密钥
	APIKey string `json:"api_key,omitempty" yaml:"api_key,omitempty"`

	// Dimensions 嵌入向量维度（仅 v3 模型支持）
	// text-embedding-3-small: 可选 512, 1536
	// text-embedding-3-large: 可选 256, 1024, 3072
	Dimensions int `json:"dimensions,omitempty" yaml:"dimensions,omitempty"`

	// Config 特定提供商的额外配置
	Config map[string]any `json:"config,omitempty" yaml:"config,omitempty"`
}

type Event struct {
	Type      string         `json:"type"`               // 事件类型
	Data      any            `json:"data"`               // 事件数据
	Timestamp time.Time      `json:"timestamp"`          // 时间戳
	Source    string         `json:"source,omitempty"`   // 事件源
	Metadata  map[string]any `json:"metadata,omitempty"` // 元数据
}

type EventType interface {
	Channel() AgentChannel
	EventType() string
}

type ExecutionMode string

type IconProps struct {
	// Name 图标名称
	Name PropertyValue `json:"name"`
	// Size 图标大小
	Size *PropertyValue `json:"size,omitempty"`
	// Color 图标颜色
	Color *PropertyValue `json:"color,omitempty"`
}

type ImageContent struct {
	// Type 图片来源类型: "url", "base64"
	Type string `json:"type"`

	// Source 图片源
	// - 当 Type="url" 时，Source 是图片 URL
	// - 当 Type="base64" 时，Source 是 base64 编码的图片数据
	Source string `json:"source"`

	// MimeType MIME 类型，如 "image/jpeg", "image/png"
	MimeType string `json:"mime_type,omitempty"`

	// Detail 图片细节级别 (OpenAI)
	// - "low": 低分辨率快速处理
	// - "high": 高分辨率详细分析
	// - "auto": 自动选择
	Detail string `json:"detail,omitempty"`
}

type ImageProps struct {
	// Src 图片 URL
	Src PropertyValue `json:"src"`
	// Alt 替代文本
	Alt *PropertyValue `json:"alt,omitempty"`
	// UsageHint 使用提示（尺寸和样式）
	UsageHint ImageUsageHint `json:"usageHint,omitempty"`
}

type ImageUsageHint string

type ListProps struct {
	// Children 子组件引用
	Children ComponentArrayReference `json:"children"`
	// Dividers 是否显示分隔线
	Dividers *bool `json:"dividers,omitempty"`
}

type MemoryConfig struct {
	// Enabled 是否启用记忆系统
	Enabled bool `json:"enabled" yaml:"enabled"`

	// VectorStore 向量存储配置
	VectorStore *VectorStoreConfig `json:"vector_store,omitempty" yaml:"vector_store,omitempty"`

	// Embedder 嵌入模型配置
	Embedder *EmbedderConfig `json:"embedder,omitempty" yaml:"embedder,omitempty"`

	// TopK 检索时返回的最相关结果数量
	// 默认值: 5
	TopK int `json:"top_k,omitempty" yaml:"top_k,omitempty"`

	// Namespace 命名空间（可选）
	// 用于在同一向量存储中隔离不同的知识库
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
}

type Message struct {
	// Role 消息角色
	Role Role `json:"role"`

	// Content 消息内容（简单文本格式，与 ContentBlocks 二选一）
	Content string `json:"content,omitempty"`

	// ContentBlocks 消息内容块（复杂格式，与 Content 二选一）
	// 用于支持多模态内容（文本、工具调用、工具结果等）
	ContentBlocks []ContentBlock `json:"-"`

	// Name 可选的名称字段（用于function/tool角色）
	Name string `json:"name,omitempty"`

	// ToolCalls 工具调用列表（仅assistant角色）
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`

	// ToolCallID 工具调用ID（仅tool角色）
	ToolCallID string `json:"tool_call_id,omitempty"`

	// Metadata 消息元数据，用于可见性控制和标记
	// 如果为 nil，默认双方可见
	Metadata *MessageMetadata `json:"metadata,omitempty"`
}

type MessageMetadata struct {
	// UserVisible 是否对用户 UI 可见
	// 默认为 true，设为 false 可用于隐藏系统消息或摘要
	UserVisible bool `json:"user_visible"`

	// AgentVisible 是否包含在 LLM 上下文中
	// 默认为 true，设为 false 可用于用户专属反馈
	AgentVisible bool `json:"agent_visible"`

	// Source 消息来源标识
	// 可选值: "user", "system", "summary", "tool"
	Source string `json:"source,omitempty"`

	// Tags 自定义标签，用于分类和过滤
	Tags []string `json:"tags,omitempty"`
}

type MessageOperation string

type ModalProps struct {
	// Open 打开状态（必须是 path 类型，用于双向绑定）
	Open PropertyValue `json:"open"`
	// Title 标题
	Title *PropertyValue `json:"title,omitempty"`
	// Children 子组件引用
	Children ComponentArrayReference `json:"children"`
	// Closable 是否可关闭
	Closable *bool `json:"closable,omitempty"`
	// CloseAction 关闭动作标识符
	CloseAction string `json:"closeAction,omitempty"`
}

type ModelConfig struct {
	Provider      string        `json:"provider" yaml:"provider"` // "anthropic", "openai", etc.
	Model         string        `json:"model" yaml:"model"`
	APIKey        string        `json:"api_key,omitempty" yaml:"api_key,omitempty"`
	BaseURL       string        `json:"base_url,omitempty" yaml:"base_url,omitempty"`
	ExecutionMode ExecutionMode `json:"execution_mode,omitempty" yaml:"execution_mode,omitempty"` // 执行模式：streaming/non-streaming/auto
}

type MonitorAgentResumedEvent struct {
	Strategy string             `json:"strategy"` // "crash" or "manual"
	Sealed   []ToolCallSnapshot `json:"sealed"`
}

type MonitorBreakpointChangedEvent struct {
	Previous  BreakpointState `json:"previous"`
	Current   BreakpointState `json:"current"`
	Timestamp time.Time       `json:"timestamp"`
}

type MonitorContextCompressionEvent struct {
	Phase   string  `json:"phase"` // "start" or "end"
	Summary string  `json:"summary,omitempty"`
	Ratio   float64 `json:"ratio,omitempty"`
}

type MonitorErrorEvent struct {
	Severity string         `json:"severity"` // "info", "warn", "error"
	Phase    string         `json:"phase"`    // "model", "tool", "system", "lifecycle"
	Message  string         `json:"message"`
	Detail   map[string]any `json:"detail,omitempty"`
}

type MonitorFileChangedEvent struct {
	Path  string    `json:"path"`
	Mtime time.Time `json:"mtime"`
}

type MonitorReminderSentEvent struct {
	Category string `json:"category"` // "file", "todo", "security", "performance", "general"
	Content  string `json:"content"`
}

type MonitorSchedulerTriggeredEvent struct {
	TaskID      string    `json:"task_id"`
	Spec        string    `json:"spec"`
	Kind        string    `json:"kind"` // "steps", "time", "cron"
	TriggeredAt time.Time `json:"triggered_at"`
}

type MonitorStateChangedEvent struct {
	State AgentRuntimeState `json:"state"`
}

type MonitorStepCompleteEvent struct {
	Step       int   `json:"step"`
	DurationMs int64 `json:"duration_ms,omitempty"`
}

type MonitorTokenUsageEvent struct {
	InputTokens  int64 `json:"input_tokens"`
	OutputTokens int64 `json:"output_tokens"`
	TotalTokens  int64 `json:"total_tokens"`
}

type MonitorToolExecutedEvent struct {
	Call ToolCallSnapshot `json:"call"`
}

type MonitorToolManualUpdatedEvent struct {
	Tools     []string  `json:"tools"`
	Timestamp time.Time `json:"timestamp"`
}

type MultimodalContent interface {
	ContentBlock
	GetMediaType() string
}

type MultipleChoiceDirection string

type MultipleChoiceOption struct {
	// Value 选项值
	Value string `json:"value"`
	// Label 显示标签
	Label string `json:"label"`
	// Description 描述
	Description string `json:"description,omitempty"`
	// Disabled 是否禁用
	Disabled bool `json:"disabled,omitempty"`
}

type MultipleChoiceProps struct {
	// Value 值（必须是 path 类型，用于双向绑定）
	Value PropertyValue `json:"value"`
	// Options 选项数组路径或字面值
	Options PropertyValue `json:"options"`
	// Label 标签
	Label *PropertyValue `json:"label,omitempty"`
	// Disabled 是否禁用
	Disabled *PropertyValue `json:"disabled,omitempty"`
	// Direction 布局方向
	Direction MultipleChoiceDirection `json:"direction,omitempty"`
}

type MultitenancyConfig struct {
	// Enabled 是否启用多租户支持
	Enabled bool `json:"enabled" yaml:"enabled"`

	// OrgID 组织 ID，用于顶层租户隔离
	OrgID string `json:"org_id,omitempty" yaml:"org_id,omitempty"`

	// TenantID 租户 ID，用于组织内的二级隔离
	TenantID string `json:"tenant_id,omitempty" yaml:"tenant_id,omitempty"`

	// Isolation 隔离级别
	// - "none": 不隔离（仅标记）
	// - "data": 数据隔离（向量存储、消息等）
	// - "full": 完全隔离（包括工具、资源等）
	// 默认值: "data"
	Isolation string `json:"isolation,omitempty" yaml:"isolation,omitempty"`
}

type NetworkSandboxSettings struct {
	// AllowLocalBinding 允许进程绑定本地端口（如开发服务器）
	AllowLocalBinding bool `json:"allow_local_binding,omitempty"`

	// AllowUnixSockets 允许访问的 Unix Socket 路径
	// 例如: ["/var/run/docker.sock"]
	AllowUnixSockets []string `json:"allow_unix_sockets,omitempty"`

	// AllowAllUnixSockets 允许访问所有 Unix Socket
	AllowAllUnixSockets bool `json:"allow_all_unix_sockets,omitempty"`

	// HTTPProxyPort HTTP 代理端口
	HTTPProxyPort int `json:"http_proxy_port,omitempty"`

	// SOCKSProxyPort SOCKS 代理端口
	SOCKSProxyPort int `json:"socks_proxy_port,omitempty"`

	// AllowedHosts 允许访问的主机列表
	AllowedHosts []string `json:"allowed_hosts,omitempty"`

	// BlockedHosts 禁止访问的主机列表
	BlockedHosts []string `json:"blocked_hosts,omitempty"`
}

type PermissionConfig struct {
	Mode  PermissionMode `json:"mode"`
	Allow []string       `json:"allow,omitempty"` // 白名单工具
	Deny  []string       `json:"deny,omitempty"`  // 黑名单工具
	Ask   []string       `json:"ask,omitempty"`   // 需要审批的工具
}

type PermissionMode string

type PermissionResult struct {
	// Behavior 行为: "allow" | "deny"
	Behavior string `json:"behavior"`

	// UpdatedInput 修改后的输入参数
	// 权限系统可以修改工具输入（如脱敏、添加限制等）
	UpdatedInput map[string]any `json:"updated_input,omitempty"`

	// UpdatedPermissions 权限更新操作
	UpdatedPermissions []PermissionUpdate `json:"updated_permissions,omitempty"`

	// Message 拒绝原因或说明
	Message string `json:"message,omitempty"`

	// Interrupt 是否中断执行
	Interrupt bool `json:"interrupt,omitempty"`
}

type PermissionRule struct {
	// ToolName 工具名称
	ToolName string `json:"tool_name"`

	// RuleContent 规则内容（可选的额外条件）
	RuleContent string `json:"rule_content,omitempty"`
}

type PermissionUpdate struct {
	// Type 更新类型: "addRules" | "replaceRules" | "removeRules" | "setMode"
	Type string `json:"type"`

	// Rules 规则列表
	Rules []PermissionRule `json:"rules,omitempty"`

	// Behavior 行为: "allow" | "deny" | "ask"
	Behavior string `json:"behavior,omitempty"`

	// Destination 目标: "session" | "project" | "user"
	Destination string `json:"destination,omitempty"`

	// Mode 权限模式（用于 setMode 类型）
	Mode string `json:"mode,omitempty"`
}

type ProgressDoneEvent struct {
	Step   int    `json:"step"`
	Reason string `json:"reason"` // "completed" or "interrupted"
}

type ProgressSessionSummarizedEvent struct {
	MessagesBefore   int     `json:"messages_before"`   // 压缩前消息数
	MessagesAfter    int     `json:"messages_after"`    // 压缩后消息数
	TokensBefore     int     `json:"tokens_before"`     // 压缩前 Token 数
	TokensAfter      int     `json:"tokens_after"`      // 压缩后 Token 数
	TokensSaved      int     `json:"tokens_saved"`      // 节省的 Token 数
	CompressionRatio float64 `json:"compression_ratio"` // 压缩比 (0-1)
	SummaryPreview   string  `json:"summary_preview"`   // 摘要预览 (前150字符)
}

type ProgressTextChunkEndEvent struct {
	Step int    `json:"step"`
	Text string `json:"text"`
}

type ProgressTextChunkEvent struct {
	Step  int    `json:"step"`
	Delta string `json:"delta"`
}

type ProgressTextChunkStartEvent struct {
	Step int `json:"step"`
}

type ProgressThinkChunkEndEvent struct {
	Step int `json:"step"`
}

type ProgressThinkChunkEvent struct {
	Step      int    `json:"step"`
	Delta     string `json:"delta"`               // 增量内容 (流式使用)
	ID        string `json:"id,omitempty"`        // 事件ID
	Stage     string `json:"stage,omitempty"`     // 阶段名称: "任务规划", "推理分析", "工具规划", "结果总结"
	Reasoning string `json:"reasoning,omitempty"` // 完整推理内容 (非流式使用)
	Decision  string `json:"decision,omitempty"`  // 决策/结论
	Context   any    `json:"context,omitempty"`   // 上下文信息
	Timestamp string `json:"timestamp,omitempty"` // ISO8601 时间戳
}

type ProgressThinkChunkStartEvent struct {
	Step int `json:"step"`
}

type ProgressTodoUpdateEvent struct {
	Todos []TodoItem `json:"todos"`
}

type ProgressToolCancelledEvent struct {
	Call   ToolCallSnapshot `json:"call"`
	Reason string           `json:"reason,omitempty"`
}

type ProgressToolEndEvent struct {
	Call ToolCallSnapshot `json:"call"`
}

type ProgressToolErrorEvent struct {
	Call  ToolCallSnapshot `json:"call"`
	Error string           `json:"error"`
}

type ProgressToolIntermediateEvent struct {
	Call  ToolCallSnapshot `json:"call"`
	Label string           `json:"label,omitempty"`
	Data  any              `json:"data,omitempty"`
	// UI 可选的 UI 描述，用于工具输出的结构化渲染
	UI *AsterUIMessage `json:"ui,omitempty"`
}

type ProgressToolProgressEvent struct {
	Call     ToolCallSnapshot `json:"call"`
	Progress float64          `json:"progress"`           // 0.0 - 1.0
	Message  string           `json:"message,omitempty"`  // 进度描述
	Step     int              `json:"step,omitempty"`     // 当前步骤
	Total    int              `json:"total,omitempty"`    // 总步骤
	Metadata map[string]any   `json:"metadata,omitempty"` // 额外元数据
	ETA      int64            `json:"eta_ms,omitempty"`   // 预估剩余时间(ms)
}

type ProgressToolStartEvent struct {
	Call ToolCallSnapshot `json:"call"`
}

type ProgressUIDataUpdateEvent struct {
	// SurfaceID Surface 唯一标识符
	SurfaceID string `json:"surface_id"`
	// Path JSON Pointer 路径，默认 "/" 表示根路径
	Path string `json:"path"`
	// Contents 数据内容
	Contents any `json:"contents"`
}

type ProgressUIDeleteSurfaceEvent struct {
	// SurfaceID Surface 唯一标识符
	SurfaceID string `json:"surface_id"`
}

type ProgressUISurfaceUpdateEvent struct {
	// SurfaceID Surface 唯一标识符
	SurfaceID string `json:"surface_id"`
	// Components 组件定义列表（邻接表模型）
	Components []ComponentDefinition `json:"components,omitempty"`
	// Root 根组件 ID（可选，用于 beginRendering）
	Root string `json:"root,omitempty"`
	// Styles CSS 自定义属性（主题化支持）
	Styles map[string]string `json:"styles,omitempty"`
}

type PromptCompressionConfig struct {
	// Enabled 是否启用压缩
	Enabled bool `json:"enabled"`

	// MaxLength 触发压缩的阈值（字符数）
	// 当 System Prompt 长度超过此值时自动压缩
	// 默认值: 5000
	MaxLength int `json:"max_length,omitempty"`

	// TargetLength 目标长度（字符数）
	// 压缩后的目标长度
	// 默认值: 3000
	TargetLength int `json:"target_length,omitempty"`

	// Mode 压缩模式
	// - "simple": 基于规则的快速压缩
	// - "llm": LLM 驱动的智能压缩
	// - "hybrid": 混合模式（先规则后 LLM）
	// 默认值: "hybrid"
	Mode string `json:"mode,omitempty"`

	// Level 压缩级别
	// - 1: 轻度压缩（保留 60-70%）
	// - 2: 中度压缩（保留 40-50%）
	// - 3: 激进压缩（保留 20-30%）
	// 默认值: 2
	Level int `json:"level,omitempty"`

	// PreserveSections 必须保留的段落标题
	// 这些段落不会被压缩移除
	// 默认值: ["Tools Manual", "Security Guidelines"]
	PreserveSections []string `json:"preserve_sections,omitempty"`

	// CacheEnabled 是否启用压缩结果缓存
	// 启用后相同内容不会重复压缩
	// 默认值: true
	CacheEnabled bool `json:"cache_enabled,omitempty"`

	// Language 提示词语言
	// - "zh": 中文
	// - "en": 英文
	// 默认值: "zh"
	Language string `json:"language,omitempty"`

	// Model LLM 压缩使用的模型
	// 默认值: "deepseek-chat"
	Model string `json:"model,omitempty"`
}

type PropertySchema struct {
	Type        string                     `json:"type"`                  // string, number, boolean, array, object
	Description string                     `json:"description,omitempty"` // 描述
	Enum        []any                      `json:"enum,omitempty"`        // 枚举值
	Items       *PropertySchema            `json:"items,omitempty"`       // 数组元素 schema
	Properties  map[string]*PropertySchema `json:"properties,omitempty"`  // 对象属性（嵌套）
	Required    []string                   `json:"required,omitempty"`    // 必需字段（对象）
	Default     any                        `json:"default,omitempty"`     // 默认值
}

type PropertyValue struct {
	// LiteralString 字面字符串值
	LiteralString *string `json:"literalString,omitempty"`
	// LiteralNumber 字面数字值
	LiteralNumber *float64 `json:"literalNumber,omitempty"`
	// LiteralBoolean 字面布尔值
	LiteralBoolean *bool `json:"literalBoolean,omitempty"`
	// Path JSON Pointer 路径引用
	Path *string `json:"path,omitempty"`
}

type ProtocolError struct {
	// Code 错误代码
	Code string `json:"code"`
	// SurfaceID Surface ID
	SurfaceID string `json:"surfaceId"`
	// Path JSON Pointer 路径（验证错误时使用）
	Path string `json:"path,omitempty"`
	// Message 错误消息
	Message string `json:"message"`
	// Details 错误详情（通用错误时使用）
	Details map[string]any `json:"details,omitempty"`
}

type Question struct {
	Question    string           `json:"question"`     // 完整的问题文本
	Header      string           `json:"header"`       // 简短标签，最多12字符
	Options     []QuestionOption `json:"options"`      // 2-4个选项
	MultiSelect bool             `json:"multi_select"` // 是否多选
}

type QuestionOption struct {
	Label       string `json:"label"`       // 选项标签，1-5个词
	Description string `json:"description"` // 选项说明
}

type ReasoningTrace struct {
	// Step 推理步骤序号
	Step int `json:"step"`

	// Thought 推理思考内容
	Thought string `json:"thought"`

	// ThoughtDelta 推理思考增量 (流式)
	ThoughtDelta string `json:"thought_delta,omitempty"`

	// Type 推理类型
	// - "thinking": 思考过程
	// - "reflection": 反思
	// - "conclusion": 结论
	Type string `json:"type,omitempty"`

	// Confidence 置信度 (0-1)
	Confidence float64 `json:"confidence,omitempty"`
}

type RecoveryConfig struct {
	// Enabled 是否启用恢复机制
	Enabled bool `json:"enabled"`
	// TriggerPatterns 触发恢复的消息模式（正则表达式）
	// 当用户消息匹配这些模式时，认为用户想继续之前的工作
	TriggerPatterns []string `json:"trigger_patterns,omitempty"`
	// MaxTriggerLength 触发恢复的最大消息长度
	// 超过此长度的消息不被视为恢复触发（因为可能是新的详细指令）
	MaxTriggerLength int `json:"max_trigger_length,omitempty"`
}

type RecoveryContext struct {
	// AgentID Agent 标识
	AgentID string `json:"agent_id"`
	// SessionState 会话状态
	SessionState *SessionState `json:"session_state"`
	// OriginalMessage 用户原始消息
	OriginalMessage string `json:"original_message"`
	// WorkDir 工作目录（如果有）
	WorkDir string `json:"work_dir,omitempty"`
	// Metadata 自定义元数据（应用层可以传入额外信息）
	Metadata map[string]any `json:"metadata,omitempty"`
}

type RecoveryHook func(ctx *RecoveryContext) *RecoveryResult

type RecoveryResult struct {
	// ShouldRecover 是否应该执行恢复
	ShouldRecover bool `json:"should_recover"`
	// EnhancedMessage 增强后的消息（如果需要恢复）
	EnhancedMessage string `json:"enhanced_message,omitempty"`
	// Instructions 恢复指令（可选，会被添加到消息前）
	Instructions string `json:"instructions,omitempty"`
}

type ReminderOptions struct {
	SkipStandardEnding bool   `json:"skip_standard_ending,omitempty"`
	Priority           string `json:"priority,omitempty"` // "low", "medium", "high"
	Category           string `json:"category,omitempty"` // "file", "todo", "security", "performance", "general"
}

type ResourceLimits struct {
	CPUQuota    float64       `json:"cpu_quota,omitempty"`    // CPU配额(核数)
	MemoryLimit int64         `json:"memory_limit,omitempty"` // 内存限制(字节)
	Timeout     time.Duration `json:"timeout,omitempty"`      // 超时时间
	DiskQuota   int64         `json:"disk_quota,omitempty"`   // 磁盘配额(字节)
}

type RespondFunc func(decision string, note string) error

type ResumeOptions struct {
	Strategy  ResumeStrategy `json:"strategy,omitempty"`
	AutoRun   bool           `json:"auto_run,omitempty"`
	Overrides *AgentConfig   `json:"overrides,omitempty"`
}

type ResumeStrategy string

type Role string

type RowProps struct {
	// Children 子组件引用
	Children ComponentArrayReference `json:"children"`
	// Gap 间距（像素）
	Gap *int `json:"gap,omitempty"`
	// Align 对齐方式
	Align Alignment `json:"align,omitempty"`
	// Wrap 是否换行
	Wrap *bool `json:"wrap,omitempty"`
}

type SandboxConfig struct {
	Kind            SandboxKind    `json:"kind"`
	WorkDir         string         `json:"work_dir,omitempty"`
	EnforceBoundary bool           `json:"enforce_boundary,omitempty"`
	AllowPaths      []string       `json:"allow_paths,omitempty"`
	WatchFiles      bool           `json:"watch_files,omitempty"`
	Extra           map[string]any `json:"extra,omitempty"` // 云平台特定配置

	// Settings 沙箱安全设置（可选，提供更细粒度的控制）
	Settings *SandboxSettings `json:"settings,omitempty"`

	// PermissionMode 沙箱权限模式
	PermissionMode SandboxPermissionMode `json:"permission_mode,omitempty"`
}

type SandboxIgnoreViolations struct {
	// FilePatterns 忽略的文件路径模式
	// 例如: ["/tmp/*", "*.log"]
	FilePatterns []string `json:"file_patterns,omitempty"`

	// NetworkPatterns 忽略的网络模式
	// 例如: ["localhost:*", "127.0.0.1:*"]
	NetworkPatterns []string `json:"network_patterns,omitempty"`
}

type SandboxKind string

type SandboxPermissionMode string

type SandboxSettings struct {
	// Enabled 是否启用沙箱隔离
	// 当为 true 时，所有命令执行都在沙箱环境中运行
	Enabled bool `json:"enabled,omitempty"`

	// AutoAllowBashIfSandboxed 沙箱启用时自动批准 bash 命令
	// 当沙箱启用时，bash 命令被认为是安全的，可以自动批准
	AutoAllowBashIfSandboxed bool `json:"auto_allow_bash_if_sandboxed,omitempty"`

	// ExcludedCommands 静态白名单，这些命令绕过沙箱限制
	// 例如: ["docker", "git"] - 这些命令将直接执行，不经过沙箱
	ExcludedCommands []string `json:"excluded_commands,omitempty"`

	// AllowUnsandboxedCommands 允许模型请求绕过沙箱
	// 当为 true 时，模型可以在工具输入中设置 dangerouslyDisableSandbox: true
	// 这些请求会回退到权限系统进行审批
	AllowUnsandboxedCommands bool `json:"allow_unsandboxed_commands,omitempty"`

	// Network 网络沙箱配置
	Network *NetworkSandboxSettings `json:"network,omitempty"`

	// IgnoreViolations 忽略特定违规
	IgnoreViolations *SandboxIgnoreViolations `json:"ignore_violations,omitempty"`

	// EnableWeakerNestedSandbox 启用较弱的嵌套沙箱（兼容性）
	EnableWeakerNestedSandbox bool `json:"enable_weaker_nested_sandbox,omitempty"`
}

type SandboxViolation struct {
	Type      string `json:"type"`      // "file" | "network" | "process"
	Path      string `json:"path"`      // 违规路径或地址
	Operation string `json:"operation"` // 操作类型
	Blocked   bool   `json:"blocked"`   // 是否被阻止
	Timestamp int64  `json:"timestamp"` // 时间戳
	Details   string `json:"details"`   // 详细信息
}

type SelectOption struct {
	// Value 选项值
	Value string `json:"value"`
	// Label 显示标签
	Label string `json:"label"`
	// Disabled 是否禁用
	Disabled bool `json:"disabled,omitempty"`
}

type SelectProps struct {
	// Value 值（必须是 path 类型，用于双向绑定）
	Value PropertyValue `json:"value"`
	// Options 选项数组路径或字面值
	Options PropertyValue `json:"options"`
	// Label 标签
	Label *PropertyValue `json:"label,omitempty"`
	// Placeholder 占位符
	Placeholder *PropertyValue `json:"placeholder,omitempty"`
	// Disabled 是否禁用
	Disabled *PropertyValue `json:"disabled,omitempty"`
	// Multiple 是否支持多选
	Multiple *bool `json:"multiple,omitempty"`
}

type SendOptions struct {
	Kind     string           `json:"kind,omitempty"` // "user" or "reminder"
	Reminder *ReminderOptions `json:"reminder,omitempty"`
}

type SessionState struct {
	// HasHistory 是否有历史消息
	HasHistory bool `json:"has_history"`
	// MessageCount 历史消息数量
	MessageCount int `json:"message_count"`
	// IsResumed 是否是恢复的会话（Agent 实例是新创建的，但有历史数据）
	IsResumed bool `json:"is_resumed"`
	// LastMessageTime 最后一条消息的时间
	LastMessageTime *string `json:"last_message_time,omitempty"`
}

type SkillsPackageConfig struct {
	// 技能包来源
	Source  string `json:"source"`  // "local" | "oss" | "s3" | "hybrid"
	Path    string `json:"path"`    // 本地路径或云端 URL
	Version string `json:"version"` // 版本号

	// 命令和技能目录
	CommandsDir string `json:"commands_dir"` // 默认 "commands"
	SkillsDir   string `json:"skills_dir"`   // 默认 "skills"

	// 启用的 commands 和 skills
	EnabledCommands []string `json:"enabled_commands"` // ["write", "analyze", ...]
	EnabledSkills   []string `json:"enabled_skills"`   // ["consistency-checker", ...]
}

type SliderProps struct {
	// Value 值（必须是 path 类型，用于双向绑定）
	Value PropertyValue `json:"value"`
	// Label 标签
	Label *PropertyValue `json:"label,omitempty"`
	// Min 最小值
	Min *float64 `json:"min,omitempty"`
	// Max 最大值
	Max *float64 `json:"max,omitempty"`
	// Step 步长
	Step *float64 `json:"step,omitempty"`
	// Disabled 是否禁用
	Disabled *PropertyValue `json:"disabled,omitempty"`
	// ShowValue 是否显示值
	ShowValue *bool `json:"showValue,omitempty"`
}

type Snapshot struct {
	ID          string           `json:"id"`                    // 快照 ID
	AgentID     string           `json:"agent_id"`              // Agent ID
	Timestamp   time.Time        `json:"timestamp"`             // 快照时间
	Messages    []Message        `json:"messages"`              // 消息历史
	ToolCalls   []ToolCallRecord `json:"tool_calls"`            // 工具调用记录
	State       AgentState       `json:"state"`                 // Agent 状态
	StepCount   int              `json:"step_count"`            // 步骤计数
	Cursor      int              `json:"cursor"`                // 当前位置
	Metadata    map[string]any   `json:"metadata"`              // 元数据
	Description string           `json:"description,omitempty"` // 快照描述
}

type StoreConfig struct {
	// MaxMessages 持久化最多保留的消息数
	// 0 = 无限制（默认值，保持向后兼容）
	// > 0 = 限制消息数，超过后自动修剪最旧的消息
	//
	// 注意：这与 ConversationCompressionConfig 是互补的：
	// - ConversationCompression 是运行时的智能压缩（内存中）
	// - StoreConfig.MaxMessages 是持久化层的硬限制（磁盘上）
	//
	// 推荐值：
	// - 短期对话/测试环境：20
	// - 生产环境/长期对话：0（无限制）或 100
	MaxMessages int `json:"max_messages,omitempty"`

	// AutoTrim 是否在每次保存消息后自动修剪
	// true = 每次 SaveMessages 后自动调用 TrimMessages
	// false = 需要手动调用 TrimMessages
	// 默认值: true
	AutoTrim bool `json:"auto_trim,omitempty"`
}

type StreamAccumulator struct {
	// Content 累积的文本内容
	Content string

	// Reasoning 累积的推理过程
	Reasoning []ReasoningTrace

	// ToolCalls 累积的工具调用
	ToolCalls map[int]*AccumulatedToolCall

	// Usage 最终的 Token 使用情况
	Usage *TokenUsage

	// FinishReason 完成原因
	FinishReason string
}

type StreamChunk struct {
	// Type 块类型
	Type StreamChunkType `json:"type"`

	// Delta 增量文本内容 (用于 text 类型)
	Delta string `json:"delta,omitempty"`

	// ToolCall 工具调用信息 (用于 tool_call 类型)
	ToolCall *ToolCallDelta `json:"tool_call,omitempty"`

	// Usage Token 使用情况 (用于 usage 类型)
	Usage *TokenUsage `json:"usage,omitempty"`

	// Reasoning 推理过程 (用于 reasoning 类型)
	Reasoning *ReasoningTrace `json:"reasoning,omitempty"`

	// Error 错误信息 (用于 error 类型)
	Error *StreamError `json:"error,omitempty"`

	// FinishReason 完成原因 (用于 done 类型)
	FinishReason string `json:"finish_reason,omitempty"`

	// Raw 原始响应数据 (用于调试)
	Raw map[string]any `json:"raw,omitempty"`
}

type StreamChunkType string

type StreamError struct {
	// Code 错误代码
	Code string `json:"code"`

	// Message 错误消息
	Message string `json:"message"`

	// Type 错误类型
	Type string `json:"type,omitempty"`

	// Param 错误参数
	Param string `json:"param,omitempty"`
}

type StreamOptions struct {
	Since *Bookmark `json:"since,omitempty"`
	Kinds []string  `json:"kinds,omitempty"` // 事件类型过滤
}

type SubAgentConfig struct {
	Depth         int                   `json:"depth"`
	Templates     []string              `json:"templates,omitempty"`
	InheritConfig bool                  `json:"inherit_config"`
	Overrides     *AgentConfigOverrides `json:"overrides,omitempty"`
}

type SubAgentExecutor interface {
	// GetSpec 获取子 Agent 规格
	GetSpec() *SubAgentSpec

	// Execute 执行子 Agent 任务
	Execute(ctx context.Context, req *SubAgentRequest) (*SubAgentResult, error)
}

type SubAgentProgressEvent struct {
	// AgentType 子 Agent 类型
	AgentType string `json:"agent_type"`

	// TaskID 任务 ID
	TaskID string `json:"task_id"`

	// Phase 当前阶段
	Phase string `json:"phase"` // "started", "thinking", "tool_use", "completed"

	// Progress 进度 0-100
	Progress int `json:"progress"`

	// Message 进度消息
	Message string `json:"message,omitempty"`
}

type SubAgentRequest struct {
	// AgentType 目标子 Agent 名称
	AgentType string `json:"agent_type"`

	// Task 任务描述
	Task string `json:"task"`

	// Context 上下文数据（可传递给子 Agent）
	Context map[string]any `json:"context,omitempty"`

	// ParentAgentID 父 Agent ID（用于追踪）
	ParentAgentID string `json:"parent_agent_id,omitempty"`

	// Timeout 超时时间覆盖
	Timeout time.Duration `json:"timeout,omitempty"`
}

type SubAgentResult struct {
	// AgentType 执行的子 Agent 类型
	AgentType string `json:"agent_type"`

	// Success 是否成功
	Success bool `json:"success"`

	// Output 主要文本输出
	Output string `json:"output"`

	// Artifacts 产出物（文件路径、结构化数据等）
	Artifacts map[string]any `json:"artifacts,omitempty"`

	// TokensUsed 消耗的 token 数
	TokensUsed int `json:"tokens_used"`

	// Duration 执行耗时
	Duration time.Duration `json:"duration"`

	// StepCount 执行步数
	StepCount int `json:"step_count"`

	// Error 错误信息
	Error string `json:"error,omitempty"`
}

type SubAgentSpec struct {
	// Name 唯一标识符
	Name string `json:"name"`

	// Description 用途描述，供主 Agent 决策时参考
	Description string `json:"description"`

	// Prompt 系统提示词
	Prompt string `json:"prompt"`

	// Tools 可用工具名称列表
	Tools []string `json:"tools"`

	// Model 使用的模型（可选，默认使用主 Agent 的模型）
	Model string `json:"model,omitempty"`

	// Parallel 是否支持并行调用
	Parallel bool `json:"parallel"`

	// MaxTokens 上下文 token 预算
	MaxTokens int `json:"max_tokens,omitempty"`

	// Timeout 执行超时时间
	Timeout time.Duration `json:"timeout,omitempty"`
}

type SubscribeOptions struct {
	Since    *Bookmark      `json:"since,omitempty"`
	Kinds    []string       `json:"kinds,omitempty"`
	Channels []AgentChannel `json:"channels,omitempty"`
}

type SurfaceUpdateMessage struct {
	// SurfaceID Surface 唯一标识符
	SurfaceID string `json:"surfaceId"`
	// Components 组件定义列表（邻接表模型）
	Components []ComponentDefinition `json:"components"`
}

type TabDefinition struct {
	// ID 标签页 ID
	ID string `json:"id"`
	// Label 标签页标签
	Label PropertyValue `json:"label"`
	// Content 标签页内容（子组件引用）
	Content ComponentArrayReference `json:"content"`
	// Icon 图标
	Icon *PropertyValue `json:"icon,omitempty"`
	// Disabled 是否禁用
	Disabled bool `json:"disabled,omitempty"`
}

type TabsProps struct {
	// ActiveTab 当前激活的标签页（必须是 path 类型，用于双向绑定）
	ActiveTab PropertyValue `json:"activeTab"`
	// Tabs 标签页定义列表
	Tabs []TabDefinition `json:"tabs"`
}

type TextBlock struct {
	Text string `json:"text"`
}

type TextFieldInputType string

type TextFieldProps struct {
	// Value 值（必须是 path 类型，用于双向绑定）
	Value PropertyValue `json:"value"`
	// Label 标签
	Label *PropertyValue `json:"label,omitempty"`
	// Placeholder 占位符
	Placeholder *PropertyValue `json:"placeholder,omitempty"`
	// Multiline 是否多行
	Multiline *bool `json:"multiline,omitempty"`
	// Disabled 是否禁用
	Disabled *PropertyValue `json:"disabled,omitempty"`
	// MaxLength 最大长度
	MaxLength *int `json:"maxLength,omitempty"`
	// InputType 输入类型
	InputType TextFieldInputType `json:"inputType,omitempty"`
}

type TextProps struct {
	// Text 文本内容
	Text PropertyValue `json:"text"`
	// UsageHint 使用提示（语义化样式）
	UsageHint TextUsageHint `json:"usageHint,omitempty"`
}

type TextUsageHint string

type TodoConfig struct {
	Enabled             bool `json:"enabled"`
	ReminderOnStart     bool `json:"reminder_on_start"`
	RemindIntervalSteps int  `json:"remind_interval_steps"`
}

type TodoItem struct {
	ID         string    `json:"id"`
	Content    string    `json:"content"`     // 祈使句形式: "Run tests"
	ActiveForm string    `json:"active_form"` // 进行时形式: "Running tests"
	Status     string    `json:"status"`      // "pending", "in_progress", "completed"
	Priority   int       `json:"priority,omitempty"`
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
}

type TokenUsage struct {
	// InputTokens 输入 Token 数
	InputTokens int `json:"input_tokens"`

	// OutputTokens 输出 Token 数
	OutputTokens int `json:"output_tokens"`

	// TotalTokens 总 Token 数
	TotalTokens int `json:"total_tokens"`

	// ReasoningTokens 推理 Token 数 (用于推理模型)
	ReasoningTokens int `json:"reasoning_tokens,omitempty"`

	// CachedTokens 缓存命中的 Token 数 (Prompt Caching)
	CachedTokens int `json:"cached_tokens,omitempty"`

	// CacheCreationTokens 缓存创建的 Token 数
	CacheCreationTokens int `json:"cache_creation_tokens,omitempty"`

	// CacheReadTokens 缓存读取的 Token 数
	CacheReadTokens int `json:"cache_read_tokens,omitempty"`
}

type ToolCall struct {
	// ID 工具调用的唯一标识符
	ID string `json:"id"`

	// Type 工具类型，通常为 "function"
	Type string `json:"type,omitempty"`

	// Name 工具名称
	Name string `json:"name"`

	// Arguments 工具参数（JSON对象）
	Arguments map[string]any `json:"arguments,omitempty"`
}

type ToolCallApproval struct {
	CallID     string    `json:"call_id"`               // 工具调用 ID
	Required   bool      `json:"required"`              // 是否需要审批（新字段）
	Approved   bool      `json:"approved"`              // 是否批准
	Reason     string    `json:"reason,omitempty"`      // 原因
	Timestamp  time.Time `json:"timestamp"`             // 审批时间
	ApprovedBy string    `json:"approved_by,omitempty"` // 审批人
}

type ToolCallAuditEntry struct {
	State     ToolCallState `json:"state"`     // 状态
	Timestamp time.Time     `json:"timestamp"` // 时间戳
	Note      string        `json:"note"`      // 备注
}

type ToolCallDelta struct {
	// Index 工具调用索引
	Index int `json:"index"`

	// ID 工具调用 ID (第一个块)
	ID string `json:"id,omitempty"`

	// Type 工具类型 (通常是 "function")
	Type string `json:"type,omitempty"`

	// Name 工具名称 (第一个块)
	Name string `json:"name,omitempty"`

	// ArgumentsDelta 参数增量 (JSON 片段)
	ArgumentsDelta string `json:"arguments_delta,omitempty"`
}

type ToolCallRecord struct {
	ID           string               `json:"id"`                     // 工具调用 ID
	Name         string               `json:"name"`                   // 工具名称（新字段）
	ToolName     string               `json:"tool_name"`              // 工具名称（兼容）
	Input        map[string]any       `json:"input"`                  // 输入参数
	Output       any                  `json:"output"`                 // 输出结果
	Result       any                  `json:"result"`                 // 执行结果（新字段）
	Error        string               `json:"error,omitempty"`        // 错误信息
	IsError      bool                 `json:"is_error"`               // 是否有错误（新字段）
	Progress     float64              `json:"progress"`               // 执行进度 0-1
	Intermediate map[string]any       `json:"intermediate,omitempty"` // 中间结果
	StartTime    time.Time            `json:"start_time"`             // 开始时间
	EndTime      time.Time            `json:"end_time"`               // 结束时间
	StartedAt    *time.Time           `json:"started_at"`             // 开始时间（新字段，指针）
	CompletedAt  *time.Time           `json:"completed_at"`           // 完成时间（新字段，指针）
	DurationMs   *int64               `json:"duration_ms"`            // 执行时长（毫秒，改为指针）
	Status       ToolCallStatus       `json:"status"`                 // 调用状态
	State        ToolCallState        `json:"state"`                  // 工具调用状态（新字段）
	Approval     ToolCallApproval     `json:"approval"`               // 审批信息（新字段）
	CreatedAt    time.Time            `json:"created_at"`             // 创建时间（新字段）
	UpdatedAt    time.Time            `json:"updated_at"`             // 更新时间（新字段）
	AuditTrail   []ToolCallAuditEntry `json:"audit_trail"`            // 审计跟踪（新字段）
}

type ToolCallSnapshot struct {
	// ID 工具调用ID
	ID string `json:"id"`

	// Name 工具名称
	Name string `json:"name"`

	// State 工具调用状态
	State ToolCallState `json:"state,omitempty"`

	// Progress 进度 0-1
	Progress float64 `json:"progress,omitempty"`

	// Arguments 工具参数
	Arguments map[string]any `json:"arguments,omitempty"`

	// Result 工具执行结果
	Result any `json:"result,omitempty"`

	// Error 错误信息
	Error string `json:"error,omitempty"`

	// Intermediate 中间结果
	Intermediate map[string]any `json:"intermediate,omitempty"`

	// 时间信息
	StartedAt time.Time `json:"started_at,omitempty"`
	UpdatedAt time.Time `json:"updated_at,omitempty"`

	// 控制能力标识
	Cancelable bool `json:"cancelable,omitempty"`
	Pausable   bool `json:"pausable,omitempty"`
}

type ToolCallState string

type ToolCallStatus string

type ToolCaller struct {
	// Type 调用者类型: "direct" (LLM直接调用) 或 "code_execution_20250825" (代码执行中调用)
	Type string `json:"type"`

	// ToolID 代码执行工具的 ID (当 Type="code_execution_20250825" 时)
	ToolID string `json:"tool_id,omitempty"`
}

type ToolDefinition struct {
	Name        string         `json:"name"`         // 工具名称
	Description string         `json:"description"`  // 工具描述
	InputSchema map[string]any `json:"input_schema"` // 输入 Schema
}

type ToolResult struct {
	// ToolCallID 关联的工具调用ID
	ToolCallID string `json:"tool_call_id"`

	// Content 工具执行结果
	Content string `json:"content"`

	// Error 错误信息（如果有）
	Error string `json:"error,omitempty"`
}

type ToolResultBlock struct {
	ToolUseID string `json:"tool_use_id"`
	Content   string `json:"content"`
	IsError   bool   `json:"is_error,omitempty"`

	// 以下字段用于可恢复压缩（Manus Context Engineering）
	// Compressed 标记内容是否已被压缩
	Compressed bool `json:"compressed,omitempty"`
	// OriginalLength 原始内容长度（用于统计和验证）
	OriginalLength int `json:"original_length,omitempty"`
	// ContentHash 原始内容哈希（用于验证恢复）
	ContentHash string `json:"content_hash,omitempty"`
	// References 可恢复的引用列表（文件路径、URL 等）
	References []ToolResultReference `json:"references,omitempty"`
}

type ToolResultReference struct {
	// Type 引用类型: "file_path", "url", "function", "class"
	Type string `json:"type"`
	// Value 引用值
	Value string `json:"value"`
	// Context 上下文信息（可选）
	Context string `json:"context,omitempty"`
}

type ToolSchema struct {
	Type        string                     `json:"type"`                  // "object"
	Properties  map[string]*PropertySchema `json:"properties"`            // 属性定义
	Required    []string                   `json:"required,omitempty"`    // 必需字段
	Description string                     `json:"description,omitempty"` // 描述
}

type ToolUseBlock struct {
	ID     string         `json:"id"`
	Name   string         `json:"name"`
	Input  map[string]any `json:"input"`
	Caller *ToolCaller    `json:"caller,omitempty"` // PTC: 调用者信息
}

type ToolsManualConfig struct {
	// Mode 决定哪些工具会出现在 System Prompt 的 "Tools Manual" 中:
	// - "all"   : 默认值, 所有工具都会注入(除非在 Exclude 中显式排除)
	// - "listed": 仅注入 Include 列表中出现的工具
	// - "none"  : 完全不注入工具手册, 由模型自己通过名称和输入 Schema 推断
	Mode string `json:"mode,omitempty"`

	// Include 仅在 Mode 为 "listed" 时生效, 指定要注入手册的工具名称白名单。
	Include []string `json:"include,omitempty"`

	// Exclude 在 Mode 为 "all" 时生效, 指定不注入手册的工具名称黑名单。
	Exclude []string `json:"exclude,omitempty"`
}

type UIActionEvent struct {
	// SurfaceID Surface ID
	SurfaceID string `json:"surfaceId"`
	// ComponentID 组件 ID
	ComponentID string `json:"componentId"`
	// Action 动作标识符
	Action string `json:"action"`
	// Timestamp ISO 8601 时间戳
	Timestamp string `json:"timestamp"`
	// Context 解析后的上下文数据
	Context map[string]any `json:"context"`
	// Payload 附加数据（向后兼容）
	Payload map[string]any `json:"payload,omitempty"`
}

type UserActionMessage struct {
	// Name 动作名称
	Name string `json:"name"`
	// SurfaceID Surface ID
	SurfaceID string `json:"surfaceId"`
	// SourceComponentID 触发动作的组件 ID
	SourceComponentID string `json:"sourceComponentId"`
	// Timestamp ISO 8601 时间戳
	Timestamp string `json:"timestamp"`
	// Context 解析后的上下文数据
	Context map[string]any `json:"context"`
}

type ValidationErrorCode string

type VectorStoreConfig struct {
	// Type 向量存储类型
	// - "memory": 内存向量存储
	// - "weaviate": Weaviate 向量数据库
	// - "pgvector": PostgreSQL pgvector 扩展
	// - "qdrant": Qdrant 向量数据库
	Type string `json:"type" yaml:"type"`

	// Config 特定存储的配置参数（map）
	// 不同的存储类型有不同的配置需求
	Config map[string]any `json:"config,omitempty" yaml:"config,omitempty"`
}

type VideoContent struct {
	// Type 视频来源类型: "url", "base64"
	Type string `json:"type"`

	// Source 视频源
	Source string `json:"source"`

	// MimeType MIME 类型，如 "video/mp4", "video/webm"
	MimeType string `json:"mime_type,omitempty"`

	// Thumbnail 视频缩略图 URL (可选)
	Thumbnail string `json:"thumbnail,omitempty"`

	// Duration 视频时长(秒)
	Duration float64 `json:"duration,omitempty"`
}

type VideoProps struct {
	// Src 视频 URL
	Src PropertyValue `json:"src"`
	// Poster 封面图 URL
	Poster *PropertyValue `json:"poster,omitempty"`
	// Autoplay 是否自动播放
	Autoplay *PropertyValue `json:"autoplay,omitempty"`
	// Controls 是否显示控制条
	Controls *PropertyValue `json:"controls,omitempty"`
	// Loop 是否循环播放
	Loop *PropertyValue `json:"loop,omitempty"`
	// Muted 是否静音
	Muted *PropertyValue `json:"muted,omitempty"`
}