im

type Adapter interface {
	// Platform returns the platform identifier.
	Platform() Platform

	// VerifyCallback verifies the signature/token of an incoming callback request.
	// Returns nil if verification passes.
	VerifyCallback(c *gin.Context) error

	// ParseCallback parses the raw IM callback request into a unified IncomingMessage.
	// Returns nil message for non-message events (e.g., URL verification).
	ParseCallback(c *gin.Context) (*IncomingMessage, error)

	// SendReply sends a reply back to the IM platform.
	SendReply(ctx context.Context, incoming *IncomingMessage, reply *ReplyMessage) error

	// HandleURLVerification handles the initial URL verification challenge from the IM platform.
	// Returns true if this request is a verification request and has been handled.
	HandleURLVerification(c *gin.Context) bool
}

type AdapterFactory func(ctx context.Context, channel *IMChannel, msgHandler func(ctx context.Context, msg *IncomingMessage) error) (Adapter, context.CancelFunc, error)

type ChannelSession struct {
	ID          string         `json:"id"            gorm:"type:varchar(36);primaryKey;default:uuid_generate_v4()"`
	Platform    string         `json:"platform"      gorm:"type:varchar(20);not null"`
	UserID      string         `json:"user_id"       gorm:"type:varchar(128);not null"`
	ChatID      string         `json:"chat_id"       gorm:"type:varchar(128);not null;default:''"`
	ThreadID    string         `json:"thread_id"     gorm:"type:varchar(128);not null;default:''"`
	SessionID   string         `json:"session_id"    gorm:"type:varchar(36);not null;index"`
	TenantID    uint64         `json:"tenant_id"     gorm:"not null;index"`
	AgentID     string         `json:"agent_id"      gorm:"type:varchar(36);default:''"`
	IMChannelID string         `json:"im_channel_id" gorm:"type:varchar(36);default:''"`
	Status      string         `json:"status"        gorm:"type:varchar(20);not null;default:'active'"`
	Metadata    types.JSON     `json:"metadata"      gorm:"type:jsonb;default:'{}'"`
	CreatedAt   time.Time      `json:"created_at"`
	UpdatedAt   time.Time      `json:"updated_at"`
	DeletedAt   gorm.DeletedAt `json:"deleted_at"    gorm:"index"`
}

type ChannelWithAgent struct {
	ID          string    `json:"id"`
	TenantID    uint64    `json:"tenant_id"`
	AgentID     string    `json:"agent_id"`
	AgentName   string    `json:"agent_name"`
	Platform    string    `json:"platform"`
	Name        string    `json:"name"`
	Enabled     bool      `json:"enabled"`
	Mode        string    `json:"mode"`
	OutputMode  string    `json:"output_mode"`
	Locale      string    `json:"locale"`
	SessionMode string    `json:"session_mode"`
	BotIdentity string    `json:"bot_identity"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

type ChatType string

type ClearCommand struct{}

type Command interface {
	// Name is the primary token used after "/" (e.g. "kb", "mode").
	Name() string
	// Description is the one-line summary shown in /help output.
	Description() string
	// Execute runs the command and returns a reply to send to the user.
	Execute(ctx context.Context, cmdCtx *CommandContext, args []string) (*CommandResult, error)
}

type CommandAction int

type CommandContext struct {
	// Incoming is the raw IM message that triggered the command.
	Incoming *IncomingMessage
	// Session is the IM channel session for this user×chat combination.
	Session *ChannelSession
	// TenantID is the tenant that owns this bot deployment.
	TenantID uint64
	// AgentName is the display name of the bound agent (empty if none).
	AgentName string
	// CustomAgent is the bound agent configuration. Commands that need to
	// inspect agent-level settings (e.g. /search reading KBSelectionMode)
	// can access it directly. May be nil when no agent is bound.
	CustomAgent *types.CustomAgent
	// ChannelOutputMode is the channel-level output mode configured by the admin
	// ("stream" or "full").
	ChannelOutputMode string
}

type CommandRegistry struct {
	// contains filtered or unexported fields
}

type CommandResult struct {
	// Content is the Markdown reply sent back to the user.
	Content string
	// Action requests a service-level side effect (reset, clear, …).
	Action CommandAction
}

type FileDownloader interface {
	// DownloadFile downloads a file resource from the IM platform.
	// Returns the file content reader, the resolved file name, and any error.
	DownloadFile(ctx context.Context, msg *IncomingMessage) (io.ReadCloser, string, error)
}

type FullOutputProgressSender interface {
	StreamSender
	SupportsFullOutputProgress() bool
}

type HelpCommand struct {
	// contains filtered or unexported fields
}

type IMChannel struct {
	ID              string         `json:"id"          gorm:"type:varchar(36);primaryKey;default:uuid_generate_v4()"`
	TenantID        uint64         `json:"tenant_id"   gorm:"not null;index:idx_im_channels_tenant"`
	AgentID         string         `json:"agent_id"    gorm:"type:varchar(36);not null;index:idx_im_channels_agent"`
	Platform        string         `json:"platform"    gorm:"type:varchar(20);not null"`
	Name            string         `json:"name"        gorm:"type:varchar(255);not null;default:''"`
	Enabled         bool           `json:"enabled"     gorm:"not null;default:true"`
	Mode            string         `json:"mode"        gorm:"type:varchar(20);not null;default:'websocket'"`
	OutputMode      string         `json:"output_mode"       gorm:"type:varchar(20);not null;default:'stream'"`
	Locale          string         `json:"locale"            gorm:"type:varchar(16);not null;default:''"`
	KnowledgeBaseID string         `json:"knowledge_base_id" gorm:"type:varchar(36);default:''"`
	BotIdentity     string         `` /* 158-byte string literal not displayed */
	SessionMode     string         `json:"session_mode"      gorm:"type:varchar(20);not null;default:'user'"`
	Credentials     types.JSON     `json:"credentials"       gorm:"type:jsonb;not null;default:'{}'"`
	CreatedAt       time.Time      `json:"created_at"`
	UpdatedAt       time.Time      `json:"updated_at"`
	DeletedAt       gorm.DeletedAt `json:"deleted_at"  gorm:"index"`
}

type IMChannelSummary struct {
	ID                    string    `json:"id"`
	TenantID              uint64    `json:"tenant_id"`
	AgentID               string    `json:"agent_id"`
	Platform              string    `json:"platform"`
	Name                  string    `json:"name"`
	Enabled               bool      `json:"enabled"`
	Mode                  string    `json:"mode"`
	OutputMode            string    `json:"output_mode"`
	Locale                string    `json:"locale"`
	KnowledgeBaseID       string    `json:"knowledge_base_id"`
	BotIdentity           string    `json:"bot_identity"`
	SessionMode           string    `json:"session_mode"`
	CredentialsConfigured bool      `json:"credentials_configured"`
	CreatedAt             time.Time `json:"created_at"`
	UpdatedAt             time.Time `json:"updated_at"`
}

type IMStreamMode int

type IMStreamParts struct {
	Mode IMStreamMode

	// Quick-QA (RagPipelineProgress on Web):
	PipelineToolSteps []IMToolStep // query_understand / knowledge_search rows
	ReasoningInner    string       // model reasoning_content — separate "思考" section

	// Agent (AgentStreamDisplay on Web):
	AgentInner     string       // retracted preambles + thoughts ("思考过程")
	AgentToolSteps []IMToolStep // tool progress lines (one row per tool_call_id)
	LiveAnswer     string       // optimistic answer stream before tools retract it

	Answer string // final answer (complete / knowledge QA)
}

type IMToolStep struct {
	ToolCallID string
	ToolName   string
	Pending    bool
	Success    bool
	Arguments  map[string]any
	Data       map[string]interface{}
	Output     string
}

type IncomingMessage struct {
	// Platform identifies which IM platform the message comes from.
	Platform Platform
	// MessageType is "text" (default) or "file".
	MessageType MessageType
	// UserID is the IM-platform user identifier.
	UserID string
	// UserName is the display name of the user (optional).
	UserName string
	// ChatID is the group/channel ID (empty for direct messages).
	ChatID string
	// ChatType distinguishes direct message from group chat.
	ChatType ChatType
	// Content is the text content of the message (empty for file messages).
	Content string
	// MessageID is the IM-platform message identifier (for dedup).
	MessageID string
	// FileKey is the platform file identifier (for file messages).
	FileKey string
	// FileName is the original file name (for file messages).
	FileName string
	// FileSize is the file size in bytes (for file messages, optional).
	FileSize int64
	// ThreadID is the platform-specific thread identifier.
	// - Slack: thread_ts (top-level message uses its own timestamp)
	// - Mattermost: root_id, or post_id if top-level
	// - Feishu/Lark: root_id, or message_id if top-level
	// - Telegram: message_thread_id (Forum Topics only)
	// Empty for platforms without thread support (WeCom, DingTalk).
	// In thread mode, top-level messages use their own ID as ThreadID,
	// effectively creating a new session per top-level message.
	ThreadID string
	// Quote is the quoted/replied message, if any.
	// Populated by adapters on platforms that support quote-reply.
	Quote *QuotedMessage
	// Extra holds platform-specific fields (e.g., WeCom stream ID).
	Extra map[string]string
}

type InfoCommand struct {
	// contains filtered or unexported fields
}

type MessageType string

type Platform string

type QueueMetrics struct {
	// Depth is the current number of requests waiting in the queue.
	Depth int
	// ActiveWorkers is the number of workers currently executing a QA request.
	ActiveWorkers int64
	// TotalEnqueued is the cumulative number of requests enqueued.
	TotalEnqueued int64
	// TotalProcessed is the cumulative number of requests dequeued and executed.
	TotalProcessed int64
	// TotalRejected is the cumulative number of requests rejected (queue full / per-user limit).
	TotalRejected int64
	// TotalTimeout is the cumulative number of requests discarded due to queue timeout.
	TotalTimeout int64
}

type QuotedMessage struct {
	// MessageID is the platform message ID of the quoted message.
	MessageID string
	// Content is the text content. Empty for non-text message types.
	Content string
	// SenderID is the platform user ID of the quoted message's author.
	SenderID string
	// IsBotMessage indicates whether the quoted message was from the bot.
	IsBotMessage bool
	// NonTextType records the original message type when the quoted message
	// has no extractable text (e.g. "image", "file", "video").
	// Empty when Content is populated. Used to generate LLM instructions
	// instead of content placeholders that cause hallucination.
	NonTextType string
}

type ReplyMessage struct {
	// Content is the text content (Markdown).
	Content string
	// IsStreaming indicates whether this is a streaming chunk.
	IsStreaming bool
	// IsFinal marks the last chunk of a streaming reply.
	IsFinal bool
	// Extra holds platform-specific fields.
	Extra map[string]string
}

type SearchCommand struct {
	// contains filtered or unexported fields
}

type Service struct {
	// contains filtered or unexported fields
}

type SessionMode string

type StopCommand struct{}

type StreamDisplayPhase int

type StreamSender interface {
	// StartStream initializes a streaming reply session (e.g., creates a streaming card).
	// Returns a platform-specific stream ID for subsequent chunk/end calls.
	StartStream(ctx context.Context, incoming *IncomingMessage) (string, error)

	// UpdateStreamContent replaces the user-visible stream text with fullContent so far.
	// Platforms with replace semantics (WeCom, Telegram edit, etc.) show this as the entire message.
	UpdateStreamContent(ctx context.Context, incoming *IncomingMessage, streamID string, fullContent string) error

	// FinalizeStream performs the final replace with answer-only content (thinking/tools stripped).
	FinalizeStream(ctx context.Context, incoming *IncomingMessage, streamID string, finalContent string) error

	// EndStream finalizes a streaming reply.
	EndStream(ctx context.Context, incoming *IncomingMessage, streamID string) error
}

type SupervisorConfig struct {
	// Name identifies the supervised connection in logs (e.g. "DingTalk channel xxx").
	Name string

	// MaxConnAge is the interval between proactive reconnections.
	// Defaults to defaultRecycleInterval when <= 0.
	MaxConnAge time.Duration

	// RetryDelay is the backoff after a failed connect attempt.
	// Defaults to defaultSupervisorRetryDelay when <= 0.
	RetryDelay time.Duration

	// Connect establishes a fresh connection and returns a stop function that
	// tears it down cleanly (preventing any further internal reconnects).
	// It may wrap either a blocking or a non-blocking SDK Start: the only
	// contract is that it returns once the connection has been established
	// (or the attempt has failed), along with a stop function.
	Connect func(ctx context.Context) (stop func(), err error)
}

type ThinkBlockStyle struct {
	// ThinkingHeader is shown when the think block is still in-progress (no closing tag yet).
	ThinkingHeader string // e.g. "> 💭 **思考中...**\n" or "💭 _思考中..._\n"
	// ThoughtHeader is shown before the think block content.
	ThoughtHeader string // e.g. "> 💭 **思考过程**\n" or "💭 *思考过程*\n"
	// LinePrefix is prepended to each line of think content.
	LinePrefix string // e.g. "> " or "> _"
	// LineSuffix is appended to each line of think content (before newline).
	LineSuffix string // e.g. "" or "_"
	// Separator is inserted between the think block and the rest of the content.
	Separator string // e.g. "\n---\n\n" or "\n"
}