@zero-library/chat-copilot 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,1417 @@
+import * as react from 'react';
+import react__default from 'react';
+import { ButtonProps, ThemeConfig } from 'antd';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { createRequest, RequestConfig, RenderControl } from '@zero-library/common';
+
+type ConversationMemberEnum = 'user' | 'agent';
+declare enum AgentTypeEnum {
+    DEFAULT = 0,
+    FLOW = 1
+}
+declare enum LibraryTypeEnum {
+    DEFAULT = 0
+}
+
+interface VariableRule {
+    type: 'required' | 'email' | 'pattern' | 'max' | 'min' | 'length' | 'size' | 'enum';
+    value?: string | number | boolean;
+    message?: string;
+}
+interface Variable {
+    name: string;
+    type: 'STRING' | 'LONG' | 'NUMBER' | 'BOOLEAN' | 'FILE' | 'ARRAY_FILE' | 'OBJECT' | 'ARRAY' | 'ARRAY_STRING' | 'ARRAY_NUMBER' | 'ARRAY_DECIMAL' | 'ARRAY_BOOLEAN' | 'ARRAY_OBJECT';
+    value?: any;
+    enableEdit?: boolean;
+    rules?: VariableRule[];
+}
+
+interface ModelConfig {
+    providerName: string;
+    modelName: string;
+    reasoning: boolean;
+}
+interface FileUploadConfig {
+    enabled: boolean;
+    allowedTypes: string[];
+    maxSize: number;
+    maxCount: number;
+}
+interface AgentSpec {
+    model: ModelConfig;
+    knowledge: {
+        mode: number;
+        items: {
+            id: string;
+            name: string;
+        }[];
+    };
+    skills: {
+        mode: number;
+        items: {
+            id: string;
+        }[];
+    };
+    systemPrompt: string;
+    userPrompt: string;
+}
+interface AgentConfig {
+    onboarding: {
+        greeting: string | null;
+        guiding: string[];
+    };
+    options: {
+        fileUpload?: FileUploadConfig;
+    };
+}
+interface AgentInfo {
+    id: string;
+    name: string;
+    description: string;
+    iconUrl: string;
+    agentType: AgentTypeEnum;
+    updatedAt?: string;
+    tagIds?: string[];
+    spec?: AgentSpec;
+    config?: AgentConfig;
+    userInput?: Variable[];
+}
+
+interface UserInputType {
+    inputs: Variable[];
+    outputs: Variable[];
+}
+/**
+ * 创建聊天服务
+ * @param request - 请求函数实例
+ * @returns 聊天服务对象
+ */
+declare const createChatService: (request: ReturnType<typeof createRequest>, config?: RequestConfig) => {
+    fetchAgentInfo: (agentId: string) => Promise<R<AgentInfo>>;
+    createConversationId: (params: ConversationCreate) => Promise<R<string>>;
+    fetchConversations: (params: ConversationsQuery) => Promise<R<ConversationType[]>>;
+    deleteConversation: (id: string) => Promise<R<string>>;
+    fetchMessages: (params: ConversationMessagesQuery) => Promise<R<ConversationMessage[]>>;
+    sendMessageStream: (params: ConversationMessageSend, agentId: string) => Promise<R<ConversationMessage[]>>;
+    cancelMessage: (executionId: string) => Promise<R<string>>;
+    getRecommendQuestions: (params: {
+        conversationId: string;
+        messageId: string;
+    }) => Promise<R<string[]>>;
+    getAgentUserInput: (agentId: string) => Promise<R<UserInputType>>;
+    feedbackUpdate: (params: FeedbackUpdate) => Promise<R<null>>;
+    chatUpload: (agentId: string, data: FormData, conversationId: string, signal?: AbortSignal) => Promise<R<InputFile[]>>;
+    getPreviewUrl: (agentId: string, conversationId: string, path: string) => string;
+};
+
+type RequestInstance = ReturnType<typeof createChatService>;
+/**
+ * 聊天HTTP服务配置接口
+ * 定义聊天组件所需的HTTP服务配置，用于API请求
+ */
+interface ChatHttpServices {
+    /**
+     * 基于axios扩展的配置参数
+     * 支持所有axios配置选项，如baseURL、timeout、headers等
+     * @see {@link RequestConfig}
+     */
+    config?: RequestConfig;
+    /**
+     * 聊天服务和文件服务的合并请求对象（没有测试，暂时不使用）
+     * 可以提供自定义的请求实例，用于替代默认创建的实例
+     */
+    request?: RequestInstance;
+}
+/**
+ * 聊天WebSocket服务配置接口
+ * 定义聊天组件所需的WebSocket服务配置，用于实时消息通信
+ */
+interface ChatWebsocketServices {
+    /**
+     * WebSocket连接基础URL列表，支持多地址容错（目前只支持两个地址）
+     *
+     * 使用方式：
+     * - undefined: 继承http.config.baseURL的值
+     * - []: 空数组表示关闭WebSocket功能
+     * - [url]: 单个URL用于WebSocket连接
+     * - [url1, url2]: 两个URL用于WebSocket连接，支持多端容错
+     */
+    baseURLs?: (string | undefined)[];
+    /**
+     * WebSocket连接参数
+     * - undefined: 继承http.config.headers的值
+     * 附加到WebSocket URL上的查询参数
+     */
+    params?: Record<string, string | number>;
+}
+/**
+ * 聊天服务配置接口
+ * 定义聊天组件所需的所有服务配置，包括HTTP和WebSocket
+ *  * @example
+ * // 基本配置，使用默认继承
+ * const services: ChatServices = {
+ *   http: {
+ *     config: {
+ *       baseURL: '/api',
+ *       timeout: 10000,
+ *       headers: { 'NS-TOKEN': '123456' }
+ *     }
+ *   },
+ *   websocket: {} // 继承http的baseURL和headers参数
+ * }
+ *
+ * @example
+ * // 自定义WebSocket配置
+ * const services: ChatServices = {
+ *   http: {
+ *     config: { baseURL: '/api' }
+ *   },
+ *   websocket: {
+ *     baseURLs: ['/api', '/api/saas'],
+ *     params: { token: 'abc123' }
+ *   }
+ * }
+ *
+ * @example
+ * // 关闭WebSocket功能
+ * const services: ChatServices = {
+ *   http: {
+ *     config: { baseURL: '/api' }
+ *   },
+ *   websocket: {
+ *     baseURLs: [] // 空数组表示关闭WebSocket
+ *   }
+ * }
+ */
+interface ChatServices {
+    /** HTTP服务配置 */
+    http?: ChatHttpServices;
+    /** WebSocket服务配置 */
+    websocket?: ChatWebsocketServices;
+}
+
+/**
+ * 会话策略类型
+ * 定义创建或获取会话的策略
+ *
+ * 取值说明：
+ * - 1: 最近会话策略 - 获取用户最近的会话继续对话
+ * - 2: 新会话策略 - 创建全新的会话开始对话
+ */
+type ConversationStrategy = 1 | 2;
+/**
+ * 会话类型接口
+ */
+interface ConversationType {
+    agentId?: string;
+    agentVersionId?: string;
+    spec?: AgentSpec;
+    id: string;
+    title?: string;
+    updatedAt?: string;
+}
+/**
+ * 创建会话类型接口
+ */
+interface ConversationCreate {
+    agentId: string;
+    convMeta: ConvMeta;
+}
+/**
+ * 会话列表查询参数接口
+ */
+interface ConversationsQuery {
+    agentId: string;
+    convMeta?: ConvMeta;
+}
+/**
+ * 会话消息查询参数接口
+ * 用于获取指定会话的消息列表
+ */
+interface ConversationMessagesQuery {
+    /** 会话ID */
+    conversationId: string;
+}
+interface ConvMeta {
+    /**
+     * 1 正常 2 debug
+     */
+    mode?: number;
+    libraryId?: string;
+    source?: number;
+    libraryType?: LibraryTypeEnum;
+    skillConversationId?: string;
+}
+
+/**
+ * 发送消息类型接口
+ * 定义发送到智能体的消息内容和可选文件
+ */
+interface ConversationMessageSend {
+    /** 会话ID */
+    conversationId?: string;
+    /** 消息内容 */
+    message: string;
+    convMeta?: ConvMeta;
+    /** 附件文件列表 */
+    files?: InputFile[];
+    /** 业务参数，透传到智能体的JSON字符串 */
+    params?: ObjectType<any>;
+    spec?: AgentSpec;
+    stream: boolean;
+    responseMode: number;
+}
+/**
+ * 输入文件接口
+ * 定义聊天中上传文件的属性
+ */
+interface InputFile {
+    /** 文件id */
+    id: string;
+    /** 文件扩展名 */
+    ext: string;
+    /** 文件名 */
+    name: string;
+    /** 文件路径 */
+    path?: string;
+    /** 会话ID */
+    conversationId?: string;
+    /** 文件预览URL */
+    url?: string;
+}
+/**
+ * 文件URL类型接口
+ * 定义通过URL访问的文件信息
+ */
+interface FileUrlType {
+    /** 文件名 */
+    fileName: string;
+    path: string;
+    fileUrl?: string;
+    ext?: string;
+}
+/**
+ * 消息引用类型
+ * 用于消息回复时的引用信息
+ */
+interface MessageQuoteMsg {
+    /** 被引用的消息ID */
+    id?: string;
+    /** 被引用的消息内容 */
+    msgContent?: string;
+    /** 被引用消息的附件文件列表 */
+    msgFiles?: InputFile[];
+}
+/**
+ * 引用内容接口
+ * 扩展消息引用信息，支持更多引用格式
+ * @remarks
+ * 包含引用名称、引用内容、引用参数;
+ * SenderHeader显示顺序：name > msgContent > msgFiles
+ * MessageQuoteMsg显示顺序：quoteMsg > params.citation
+ *
+ * @example
+ * // 引用文档片段
+ * const quote: ReferencesContent = {
+ *   name: '法规条款',
+ *   msgContent: '> 根据《企业所得税法》第XX条规定...',
+ * }
+ */
+interface ReferencesContent extends MessageQuoteMsg {
+    /** 引用名称 */
+    name?: string;
+}
+/**
+ * 引用类型接口
+ * 定义消息引用的各种类型和参数
+ *
+ * @example
+ * // Markdown引用（拼接到正文发送）
+ * const markdownRef: ReferencesType = {
+ *   type: 1,
+ *   content: {
+ *     name: '法规摘要',
+ *     msgContent: '> 根据相关规定...'
+ *   },
+ *   params: {
+ *     source: 'law-001'
+ *   }
+ * }
+ *
+ * // 文案引用（不发送正文）
+ * const textRef: ReferencesType = {
+ *   type: 2,
+ *   content: {
+ *     name: '参考答案',
+ *   },
+ *   params: {
+ *     citation: '建议按以下方式处理...'
+ *   }
+ * }
+ *
+ * // 消息引用
+ * const messageRef: ReferencesType = {
+ *   type: 3,
+ *   content: {
+ *     id: 'msg-001',
+ *     msgContent: '之前的回答内容'
+ *   }
+ * }
+ */
+interface ReferencesType {
+    /** 引用类型：1-Markdown引用（拼正文发） 2-文案引用（不发正文） 3-消息引用 */
+    type: number;
+    /** 引用内容 */
+    content: ReferencesContent;
+    /** 引用参数，最终透传大模型 */
+    params?: ObjectType<any>;
+}
+/**
+ * 消息反馈更新接口
+ * 用于用户对消息进行赞/踩评价
+ */
+interface FeedbackUpdate {
+    /** 执行ID */
+    executionId: string;
+    /** 反馈类型：1-赞 2-踩 */
+    feedback: number;
+    /** 反馈内容描述，非必填 */
+    feedbackContent?: string;
+}
+interface RunStartedEvent {
+    type: 'runStarted';
+    title?: string;
+    show?: boolean;
+}
+interface TextEvent {
+    type: 'text';
+    text?: string;
+    messageContent?: string;
+    reasoningContent?: string;
+}
+interface FilesEvent {
+    type: 'files';
+    files: {
+        id: string;
+        name: string;
+        ext: string;
+    }[];
+}
+interface StepStartedEvent {
+    type: 'stepStarted';
+    stepId: string;
+    title: string;
+}
+interface StepFinishedEvent {
+    type: 'stepFinished';
+    title: string;
+    stepId?: string;
+}
+interface StepErrorEvent {
+    type: 'stepError';
+    stepId?: string;
+    title?: string;
+    errorMessage?: string;
+}
+interface RunFailedEvent {
+    type: 'runFailed';
+    errorMessage?: string;
+}
+interface RunFinishedEvent {
+    type: 'runFinished';
+}
+interface RunStoppedEvent {
+    type: 'runStopped';
+}
+interface ConversationNewTitleEvent {
+    type: 'conversationNewTitle';
+    title: string;
+}
+interface ToolCallEvent {
+    type: 'toolCall';
+    toolCallId?: string;
+    toolName?: string;
+    /** 工具图标 */
+    toolIcon?: string;
+    /** 工具调用标题 */
+    title?: string;
+    /** 工具执行内容 */
+    content?: string;
+    /** 工具调用参数 */
+    arguments?: any;
+    /** 执行状态 */
+    status?: 'pending' | 'running' | 'success' | 'error';
+}
+interface ToolResultEvent {
+    type: 'toolResult';
+    toolCallId?: string;
+    toolName?: string;
+    /** 工具图标 */
+    toolIcon?: string;
+    /** 工具调用标题 */
+    title?: string;
+    /** 工具执行内容 */
+    content?: string;
+    /** 工具执行结果 */
+    result?: any;
+    /** 执行状态 */
+    status?: 'pending' | 'running' | 'success' | 'error';
+    errorMessage?: string;
+    /** 耗时(ms) */
+    duration?: number;
+}
+interface A2uiCommandEvent {
+    type: 'a2uiCommand';
+    /** A2UI 协议命令体 */
+    command: Record<string, any>;
+}
+interface A2uiSchemaEvent {
+    type: 'a2uiSchema';
+    /** A2UI Schema 协议体（如 wizard_schema.v1） */
+    schema: Record<string, any>;
+}
+interface PlanEvent {
+    type: 'plan';
+    title?: string;
+    content?: string;
+    plan?: any;
+}
+type MessageEvent = RunStartedEvent | TextEvent | FilesEvent | StepStartedEvent | StepFinishedEvent | StepErrorEvent | RunFinishedEvent | RunStoppedEvent | ConversationNewTitleEvent | ToolCallEvent | ToolResultEvent | RunFailedEvent | A2uiCommandEvent | A2uiSchemaEvent | PlanEvent;
+/**
+ * 消息类型
+ * 定义智能体和用户之间的消息结构
+ */
+interface ConversationMessage {
+    messageId: string;
+    conversationId: string;
+    executionId: string;
+    role: number;
+    content: MessageEvent[];
+    files?: InputFile[];
+    /** 消息反馈：1-赞 2-踩 */
+    feedback?: number;
+    /** 透传参数 json字符串 */
+    params?: string;
+    /** 引用的消息信息 */
+    quoteMsg?: MessageQuoteMsg;
+    createdAt: string;
+    /** 是否被打断标志 */
+    stopFlag?: boolean;
+    /** 是否正在生成中 */
+    generating?: boolean;
+}
+
+/**
+ * 提供外部操作聊天组件的方法
+ *
+ * @example
+ * // 使用ref调用组件方法
+ * const chatRef = useRef<ChatHandle>(null)
+ * // 在组件中使用
+ * <Chat ref={chatRef} config={chatConfig} />
+ *
+ * // 发送消息
+ * chatRef.current?.sendMessage('你好，帮我分析一下这份报表')
+ *
+ * // 切换智能体会话
+ * chatRef.current?.switchAgentConversation('agent-002')
+ *
+ * // 创建新会话
+ * chatRef.current?.createConversation()
+ *
+ * // 设置引用内容
+ * chatRef.current?.setReferences({
+ *   type: 1,
+ *   content: {
+ *     name: '法规条款',
+ *     msgContent: '> 根据《企业所得税法》第XX条规定...'
+ *   }
+ * })
+ *
+ * // 聚焦输入框
+ * chatRef.current?.senderFocus()
+ */
+interface ChatHandle {
+    /** 发送消息
+     * @param message - 消息内容，如果提供则直接发送该内容，否则使用输入框内容, 且两者必须存在一个
+     * @param files - 文件列表，与消息一起发送的文件
+     * @param params - 透传给大模型的参数，用于控制模型行为
+     *
+     * @remarks
+     * 1. 传参调用则只会将参数直接传入接口，不会影响当前输入框数据
+     * 2. 参数为空则触发默认逻辑，收集输入框数据、引用等内容发送
+     * 3. 如果基于1想发送引用等内容，可以调用setMessage(message)-->sendMessage()
+     *
+     * @example
+     * // 直接发送消息（不影响输入框）
+     * chatRef.current?.sendMessage('你好，帮我分析一下这份报表')
+     *
+     * @example
+     * // 触发默认逻辑（收集输入框内容发送）
+     * chatRef.current?.sendMessage()
+     */
+    sendMessage: (message?: string, files?: InputFile[], params?: ObjectType<any>) => void;
+    /**
+     * 切换到指定的会话
+     *
+     * @param item - 目标会话
+     * @param strategy - 策略
+     *
+     * @example
+     * // 切换到指定会话
+     * chatRef.current?.switchConversation(item)
+     */
+    switchConversation: (id: ConversationType['id']) => Promise<void>;
+    /**
+     * 基于当前接收者创建新的会话
+     *
+     * @example
+     * // 创建新会话
+     * chatRef.current?.createConversation()
+     */
+    createConversation: () => Promise<void>;
+    /**
+     * 设置引用消息
+     * 在输入框中设置引用内容，将在下次发送消息时包含引用信息
+     *
+     * @param references - 引用内容对象, 空则表示清除引用消息
+     *
+     * @example
+     * // 设置Markdown引用
+     * chatRef.current?.setReferences({
+     *   type: 1,
+     *   content: {
+     *     name: '法规条款',
+     *     msgContent: '> 根据《企业所得税法》第XX条规定...'
+     *   },
+     *   params: {
+     *     source: 'law-001'
+     *   }
+     * })
+     *
+     * @example
+     * // 清除引用
+     * chatRef.current?.setReferences()
+     */
+    /**
+     * 直接设置输入框中的文本内容
+     *
+     * @param message - 要设置的消息内容
+     *
+     * @example
+     * // 设置输入框内容
+     * chatRef.current?.setMessage('请帮我分析以下问题...')
+     *
+     * @example
+     * // 清空输入框
+     * chatRef.current?.setMessage('')
+     */
+    setMessage: (message?: string) => void;
+    /**
+     * 设置消息内容参数
+     * 用于设置透传给大模型的参数，这些参数将在下一次发送消息时生效，并在发送后自动清空
+     *
+     * @param params - 消息参数对象，将传递给大模型
+     *
+     * @example
+     * // 设置消息参数
+     * chatRef.current?.setMessageParams({
+     *   citation: '税务局',
+     *   customParam: 'customValue'
+     * })
+     */
+    setMessageParams: (params?: ObjectType<any>) => void;
+    /**
+     * 设置输入框中要上传的文件列表
+     *
+     * @param files - 文件列表
+     *
+     * @example
+     * // 设置文件列表
+     * chatRef.current?.setFiles([
+     *   {
+     *     fileId: 'file-001',
+     *     fileName: '财务报表.xlsx',
+     *     fileUrl: '/files/report.xlsx'
+     *   }
+     * ])
+     *
+     * @example
+     * // 清空文件列表
+     * chatRef.current?.setFiles([])
+     */
+    setFiles: (files?: InputFile[]) => void;
+    /**
+     * 设置全局参数
+     * 更新聊天组件运行时需要的参数
+     *
+     * @param params - 聊天参数对象
+     *
+     * @example
+     * // 设置业务参数
+     * chatRef.current?.setParams({
+     *   businessId: 'case-001',
+     *   businessType: 2,
+     *   source: 1
+     * })
+     *
+     * @example
+     * // 设置扩展参数， 透传大模型
+     * chatRef.current?.setParams({
+     *   params: {
+     *     citation: '税务局',
+     *   }
+     * })
+     */
+    setParams: (params: ObjectType<any>) => void;
+    /**
+     * 设置服务配置
+     * 动态更新聊天组件的服务配置
+     *
+     * @param services - 服务配置对象
+     *
+     * @example
+     * // 更新HTTP配置，WebSocket继承
+     * chatRef.current?.setServices({
+     *   http: {
+     *     config: {
+     *       baseURL: '/new-api',
+     *       headers: {
+     *         token: 'new-token'
+     *       }
+     *     }
+     *   }
+     * })
+     *
+     * @example
+     * // 更新WebSocket配置，http使用默认
+     * chatRef.current?.setServices({
+     *   websocket: {
+     *     baseURLs: ['/api', '/api/backup'],
+     *     params: {
+     *       token: 'new-token'
+     *     }
+     *   }
+     * })
+     */
+    setServices: (services?: ChatServices) => void;
+    /**
+     * 输入框聚焦（如果前一步是设置message，最好加个延时）
+     * 使聊天输入框获得焦点
+     *
+     * @example
+     * // 聚焦输入框
+     * chatRef.current?.senderFocus()
+     */
+    senderFocus: ChatSenderHandle['focus'];
+}
+
+/**
+ * 聊天组件生命周期钩子接口
+ * 定义聊天组件在各种事件发生时的回调函数
+ * @example
+ * // 完整的钩子配置示例
+ * const hooks: ChatHooks = {
+ *   onBeforeInit: () => {
+ *     console.log('聊天组件初始化前')
+ *   },
+ *   onAfterInit: () => {
+ *     console.log('聊天组件初始化后')
+ *   },
+ *   onBeforeSend: (message, files) => {
+ *     // 验证消息内容
+ *     if (!message?.trim()) {
+ *       message.error('请输入消息内容')
+ *       return false // 阻止发送
+ *     }
+ *     return true // 允许发送
+ *   },
+ *   onAfterSend: () => {
+ *     console.log('消息发送完成')
+ *   },
+ *   onRequestInterceptor: [
+ *     (config) => {
+ *       // 添加认证头
+ *       config.headers.Authorization = `Bearer ${tokenManager.get()}`
+ *       return config
+ *     },
+ *     (error) => {
+ *       console.error('请求错误:', error)
+ *       return Promise.reject(error)
+ *     }
+ *   ],
+ *   ...
+ * }
+ */
+interface ChatHooks {
+    /**
+     * 初始化前回调
+     * 在聊天组件初始化之前调用
+     *
+     * @example
+     * onBeforeInit: () => {
+     *   console.log('准备初始化聊天组件')
+     * }
+     */
+    onBeforeInit?: () => void;
+    /**
+     * 初始化后回调
+     * 在聊天组件初始化完成后调用
+     *
+     * @example
+     * onAfterInit: () => {
+     *   console.log('聊天组件初始化完成')
+     * }
+     */
+    onAfterInit?: () => void;
+    /**
+     * 输入框聚焦回调
+     * 当输入框获得焦点时调用
+     *
+     * @example
+     * onSenderFocus: () => {
+     *   console.log('输入框获得焦点')
+     * }
+     */
+    onSenderFocus?: () => void;
+    /**
+     * 头部关闭回调
+     * 当聊天窗口头部关闭按钮被点击时调用
+     *
+     * @example
+     * onHeaderClose: () => {
+     *   console.log('聊天窗口关闭')
+     *   // 可以在这里执行清理操作
+     * }
+     */
+    onHeaderClose?: () => void;
+    /**
+     * 发送消息前回调
+     * 在消息发送前调用，返回false可阻止发送
+     *
+     * @param message - 要发送的消息内容
+     * @param files - 要发送的文件列表
+     * @returns boolean | Promise<boolean> | void - 返回false阻止发送
+     *
+     * @example
+     * onBeforeSend: (message, files) => {
+     *   // 检查消息长度
+     *   if (message.length > 1000) {
+     *     message.error('消息内容过长')
+     *     return false
+     *   }
+     *   return true
+     * }
+     */
+    onBeforeSend?: (message: ConversationMessageSend['message'], files: InputFile[]) => boolean | Promise<boolean> | void;
+    /**
+     * 发送消息后回调
+     * 在消息发送完成后调用
+     *
+     * @example
+     * onAfterSend: () => {
+     *   console.log('消息发送完成')
+     *   // 可以在这里执行后续操作，如滚动到底部
+     * }
+     */
+    onAfterSend?: () => void;
+    /**
+     * A2UI 组件事件回调
+     * 当用户在 A2UI 渲染界面内触发动作（如按钮点击）时触发
+     */
+    onA2uiAction?: (payload: {
+        name: string;
+        surfaceId: string;
+        context: Record<string, any>;
+    }) => void | Promise<void>;
+    /**
+     * 切换智能体前回调
+     * 在切换智能体前调用，返回false可阻止切换
+     *
+     * @param agentId - 目标智能体ID
+     * @returns boolean | Promise<boolean> | void - 返回false阻止切换
+     *
+     * @example
+     * onBeforeSwitchAgent: (agentId) => {
+     *   // 检查智能体权益
+     * }
+     */
+    onBeforeSwitchAgent?: (agentId: string) => boolean | Promise<boolean> | void;
+    /**
+     * 切换智能体后回调
+     * 在切换智能体完成后调用
+     *
+     * @param agent - 新的智能体信息
+     *
+     * @example
+     * onAfterSwitchAgent: (agent) => {
+     *   console.log(`已切换到智能体: ${agent.agentName}`)
+     *   // 可以在这里获取最新的智能体
+     * }
+     */
+    onAfterSwitchAgent?: (agent: AgentInfo) => void;
+    /**
+     * 切换会话前回调
+     * 在切换会话前调用，返回false可阻止切换
+     *
+     * @param conversationId - 目标会话ID
+     * @returns boolean | Promise<boolean> | void - 返回false阻止切换
+     *
+     * @example
+     * onBeforeSwitchConversation: (conversationId) => {
+     *   // 检查当前会话状态
+     *   if (isSendingMessage) {
+     *     message.warning('正在发送消息，请稍后再切换会话')
+     *     return false
+     *   }
+     *   return true
+     * }
+     */
+    onBeforeSwitchConversation?: (conversationId: string) => boolean | Promise<boolean> | void;
+    /**
+     * 在切换会话完成后调用
+     *
+     * @param conversationId - 新的会话ID
+     *
+     * @example
+     * onAfterSwitchConversation: (conversationId) => {
+     *   console.log(`已切换到会话: ${conversationId}`)
+     *   // 可以在这里更新界面状态
+     * }
+     */
+    onAfterSwitchConversation?: (conversationId: string) => void;
+    /**
+     * 初始化消息前回调
+     * 在初始化消息列表前调用，返回false可阻止初始化
+     *
+     * @param conversationId - 会话ID
+     * @returns boolean | Promise<boolean> | void - 返回false阻止初始化
+     *
+     * @example
+     * onBeforeInitMessages: (conversationId) => {
+     *   // 检查会话权限
+     *   if (!hasPermission(conversationId)) {
+     *     message.error('无权访问此会话')
+     *     return false
+     *   }
+     *   return true
+     * }
+     */
+    onBeforeInitMessages?: (conversationId: string) => boolean | Promise<boolean> | void;
+    /**
+     * 初始化消息后回调
+     * 在初始化消息列表完成后调用
+     *
+     * @param messages - 初始化的消息列表
+     *
+     * @example
+     * onAfterInitMessages: (messages) => {
+     *   console.log(`加载了 ${messages.length} 条消息`)
+     *   // 可以在这里执行消息分析等操作
+     * }
+     */
+    onAfterInitMessages?: (messages: ConversationMessage[]) => void;
+    /**
+     * 删除会话前回调
+     * 在删除会话前调用，返回false可阻止删除
+     *
+     * @param conversationId - 要删除的会话ID
+     * @returns boolean | Promise<boolean> | void - 返回false阻止删除
+     *
+     * @example
+     * onBeforeDelConversation: (conversationId) => {
+     *   window.confirm('确定要删除此会话吗？删除后无法恢复。')
+     *   return confirm
+     * }
+     */
+    onBeforeDelConversation?: (conversationId: string) => boolean | Promise<boolean> | void;
+    /**
+     * 在删除会话完成后调用
+     *
+     * @param conversationId - 已删除的会话ID
+     * @param isCurrentConversation - 是否为当前会话
+     *
+     * @example
+     * onAfterDelConversation: (conversationId, isCurrentConversation) => {
+     *   console.log(`会话 ${conversationId} 已删除`)
+     *   if (isCurrentConversation) {
+     *     // 当前会话被删除，可能需要切换到其他会话
+     *   }
+     * }
+     */
+    onAfterDelConversation?: (conversationId: string, isCurrentConversation: boolean) => void;
+    /**
+     * 接收消息前回调
+     * 在接收到WebSocket消息后调用，返回false可阻止渲染
+     *
+     * @param message - 接收到的消息
+     * @returns boolean | Promise<boolean> | void - 返回false阻止渲染
+     *
+     * @example
+     * onBeforeAcceptMessage: (message) => {
+     *   // 过滤特定类型的消息
+     *   if (message.type === 'SYSTEM_NOTIFICATION') {
+     *     handleSystemNotification(message)
+     *     return false // 不在聊天界面显示
+     *   }
+     *   return true
+     * }
+     */
+    onBeforeAcceptMessage?: (message: ConversationMessage) => boolean | Promise<boolean> | void;
+    /**
+     * 在接收到WebSocket消息并处理完成后调用
+     *
+     * @param message - 处理完成的消息
+     *
+     * @example
+     * onAfterAcceptMessage: (message) => {
+     *   console.log('收到新消息:', message)
+     *   // 可以在这里执行消息通知等操作
+     * }
+     */
+    onAfterAcceptMessage?: (message: ConversationMessage) => void;
+    /**
+     * HTTP 请求拦截器
+     * 在每个HTTP请求发送前调用，可用于修改请求配置、添加认证头等
+     *
+     * 拦截器数组包含两个函数：
+     * 1. 第一个函数：处理成功的请求配置
+     *    - 参数：当前请求配置对象
+     *    - 返回：修改后的请求配置对象或Promise
+     * 2. 第二个函数：处理请求错误
+     *    - 参数：错误对象
+     *    - 返回：错误处理结果或Promise
+     *
+     * @example
+     * // 添加认证头和日志
+     * onRequestInterceptor: [
+     *   (config) => {
+     *     // 添加认证头
+     *     config.headers.Authorization = `Bearer ${tokenManager.get()}`
+     *     console.log('发送请求:', config)
+     *     return config
+     *   },
+     *   (error) => {
+     *     // 处理请求错误
+     *     console.error('请求错误:', error)
+     *     return Promise.reject(error)
+     *   }
+     * ]
+     */
+    onRequestInterceptor?: [(config: RequestConfig) => RequestConfig | Promise<RequestConfig>, (error: any) => any];
+    /**
+     * HTTP 响应拦截器
+     * 在每个HTTP响应返回后调用，可用于处理响应数据或错误
+     *
+     * 拦截器数组包含两个函数：
+     * 1. 第一个函数：处理成功的响应
+     *    - 参数：响应对象
+     *    - 返回：处理后的响应数据或Promise
+     * 2. 第二个函数：处理响应错误
+     *    - 参数：错误对象
+     *    - 返回：错误处理结果或Promise
+     *
+     * @example
+     * // 统一处理响应和错误
+     * onResponseInterceptor: [
+     *   (response) => {
+     *     // 统一处理业务错误
+     *     if (response.data.code !== 200) {
+     *       message.error(response.data.message)
+     *     }
+     *     return response.data
+     *   },
+     *   (error) => {
+     *     // 统一处理HTTP错误
+     *     if (error?.response?.status === 401) {
+     *       // 未授权，跳转登录
+     *       onRedirectLogin?.()
+     *     }
+     *     return Promise.reject(error)
+     *   }
+     * ]
+     */
+    onResponseInterceptor?: [(response: any) => any | Promise<any>, (error: any) => any];
+    /**
+     * 重定向到登录页面回调函数
+     * 当用户未授权或认证失败时调用，用于执行跳转登录逻辑
+     *
+     * 使用场景：
+     * - HTTP 401 未授权响应
+     *
+     * @example
+     * // 自定义登录跳转逻辑
+     * onRedirectLogin: () => {
+     *   // 清除认证信息
+     *   tokenManager.clear()
+     *   userInfoManager.clear()
+     *   // 跳转到登录页
+     *   window.location.href = '/login'
+     * }
+     */
+    onRedirectLogin?: () => void;
+    /**
+     * 应用权限验证回调函数
+     * 在访问特定应用前调用，用于验证用户是否有权限使用指定的应用功能
+     *
+     * @param appKey - 应用标识, 特殊场景下会存在与聊天内部，比如AppCard卡片
+     * @returns boolean | Promise<boolean> | void - 返回验证结果或无返回
+     *
+     * @example
+     * // 简单的权限验证
+     * onAppRightVerify: (appKey) => {
+     *   const userRights = getUserRights()
+     *   return userRights.includes(appKey)
+     * }
+     *
+     * @example
+     * // 异步权限验证
+     * onAppRightVerify: async (appKey) => {
+     *   try {
+     *     const result = await checkUserRights(appKey)
+     *     return result.hasRight
+     *   } catch (error) {
+     *     console.error('权限验证失败:', error)
+     *     return false
+     *   }
+     * }
+     */
+    onAppRightVerify?: (appKey: string) => boolean | Promise<boolean> | void;
+    onBeforeFilePreview?: (file?: FileUrlType, isBuiltIn?: boolean) => boolean | Promise<boolean> | void;
+    /**
+     * 文件预览后的回调函数
+     * 在文件预览打开或关闭之后执行，可以用于控制布局等
+     * @param file - 预览的文件对象, 如果不存在则表示已经关闭预览
+     * @param isBuiltIn - 是否为内嵌布局
+     */
+    onAfterFilePreview?: (file?: FileUrlType, isBuiltIn?: boolean) => void;
+    /**
+     * 设置引用消息前回调
+     * 在设置引用消息前调用，返回false可阻止设置
+     *
+     * @param references - 要设置的引用消息, 空则表示正在清除引用消息
+     * @returns boolean | Promise<boolean> | void - 返回false阻止设置
+     *
+     * @example
+     * onBeforeSetReferences: (references) => {
+     *   // 验证引用消息内容
+     *   if (!references || !references.content) {
+     *     message.error('引用消息内容不能为空')
+     *     return false
+     *   }
+     *   return true
+     * }
+     */
+    onBeforeSetReferences?: (references?: ReferencesType) => boolean | Promise<boolean> | void;
+    /**
+     * 设置引用消息后回调
+     * 在设置引用消息完成后调用
+     *
+     * @param references - 已设置的引用消息, 空则表示已清除引用消息
+     *
+     * @example
+     * onAfterSetReferences: (references) => {
+     *   console.log('引用消息已设置:', references)
+     *   // 可以在这里更新界面状态或其他相关操作
+     * }
+     */
+    onAfterSetReferences?: (references?: ReferencesType) => void;
+}
+
+/**
+ * 聊天布局会话列表配置接口
+ * 控制会话列表区域的显示和功能
+ * ConversationList组件默认 header = true
+ * @example
+ * // 自定义会话列表配置
+ * const conversationList: ChatLayoutConversationList = {
+ *   header: true // 显示会话列表头部
+ * }
+ */
+interface ChatLayoutConversationList {
+    /** 会话列表头部渲染控制 */
+    header?: RenderControl<void, ChatLayoutConversationListHeader>;
+}
+/**
+ * 左侧会话列表header渲染控制
+ * 控制会话列表header区域的显示和功能
+ * ChatHeader组件默认 title = true, avatar = true, newConversationBtn = true, conversationListFavoriteBtn = true
+ * @example
+ * // 自定义头部配置
+ * const header: ChatLayoutConversationListHeader = {
+ *   title: true, // 显示标题
+ *   avatar: true, // 显示头像
+ *   newConversationBtn: false, // 隐藏新建会话按钮
+ *   conversationListFavoriteBtn: true // 显示会话收藏列表按钮
+ * }
+ */
+interface ChatLayoutConversationListHeader {
+    /** 标题渲染控制 */
+    title?: RenderControl<void, void>;
+    /** 头像渲染控制 */
+    avatar?: RenderControl<void, void>;
+    /** 新建会话按钮渲染控制 */
+    newConversationBtn?: RenderControl<void, void>;
+    /** 是否显示会话收藏列表按钮 */
+    conversationListFavoriteBtn?: boolean;
+}
+/**
+ * 聊天布局头部配置接口
+ * 控制聊天头部区域的显示和功能
+ * ChatHeader组件默认 title = true, avatar = true, closeBtn = false, newConversationBtn = true, conversationListBtn = true
+ * @example
+ * // 自定义头部配置
+ * const header: ChatLayoutHeader = {
+ *   title: true, // 显示标题
+ *   avatar: true, // 显示头像
+ * }
+ */
+interface ChatLayoutHeader {
+    /** 标题渲染控制 */
+    title?: RenderControl<void, void>;
+    /** 头像渲染控制 */
+    avatar?: RenderControl<void, void>;
+    /** 是否显示关闭按钮 */
+    closeBtn?: boolean;
+    /** 新建会话按钮渲染控制 */
+    newConversationBtn?: RenderControl<void, void>;
+    /** 是否显示智能体性格选择 */
+    agentCharacter?: boolean;
+    /** 是否显示会话列表按钮 */
+    conversationListBtn?: boolean;
+}
+/**
+ * 聊天布局输入框配置接口
+ * 控制输入框区域的功能和样式
+ * ChatSender组件默认 placeholder, extraBtn = false, referencesBtn = false
+ * @example
+ * // 自定义输入框配置
+ * const sender: ChatLayoutSender = {
+ *   placeholder: '请输入您的问题...',
+ *   extraBtn: true, // 显示额外按钮
+ *   referencesBtn: true, // 显示引用按钮
+ *   prompts: true, // 显示推荐问题
+ *   sendBtnProps: () => ({
+ *     type: 'primary',
+ *     children: '发送'
+ *   })
+ * }
+ */
+interface ChatLayoutSender {
+    /** 输入框占位符文本 */
+    placeholder?: string;
+    /** 额外按钮渲染控制 */
+    extraBtn?: RenderControl<void, void>;
+    /** 引用按钮渲染控制 */
+    referencesBtn?: RenderControl<void, void>;
+    /** 底部额外内容渲染控制 */
+    footerBelow?: RenderControl<void, void>;
+    /** 专业技能按钮渲染控制 */
+    skillsBtn?: RenderControl<void, void>;
+    /** 知识库按钮渲染控制 */
+    knowledgeBtn?: RenderControl<void, void>;
+    /** 发送按钮属性配置函数 */
+    sendBtnProps?: () => ButtonProps;
+}
+/**
+ * 消息列表欢迎信息配置
+ * 控制聊天界面初始欢迎信息的显示内容和自定义渲染
+ * @example
+ * // 自定义欢迎信息
+ * const welcomeMessage: ChatLayoutWelcomeMessage = {
+ *   icon: true, // 显示默认图标
+ *   title: {render: () => <>欢迎使用AI助手</>}, // 修改标题
+ *   description: false, // 不显示详情
+ *   prompts: true // 显示推荐问题
+ * }
+ */
+interface ChatLayoutWelcomeMessage {
+    icon?: RenderControl<void, void>;
+    title?: RenderControl<void, void>;
+    description?: RenderControl<void, void>;
+    prompts?: RenderControl<void, void>;
+}
+/**
+ * 聊天布局消息列表配置接口
+ * 控制消息列表区域的显示和功能
+ * @example
+ * // 自定义消息列表配置
+ * const messageList: ChatLayoutMessageList = {
+ *   avatar: {
+ *     user: true,
+ *     agent: true,
+ *     other: false
+ *   },
+ *   firstMessage: false // 不显示首条消息
+ *   welcomeMessage: false // 不显示欢迎消息
+ * }
+ */
+interface ChatLayoutMessageList {
+    /** 首条消息配置 */
+    firstMessages?: ConversationMessage[];
+    /** 头像显示控制：可以是全局布尔值或按成员类型分别控制 */
+    avatar?: boolean | Partial<Record<ConversationMemberEnum, boolean>>;
+    /** 智能体消息操作区渲染控制 */
+    agentActions?: RenderControl<{
+        message: ConversationMessage;
+        dom?: HTMLElement;
+    }, void>;
+    /** message自定义标记渲染组件 */
+    customComponents?: Record<string, any>;
+    /** 欢迎消息渲染控制, 要渲染时如果列表有内容则不渲染 */
+    welcomeMessage?: RenderControl<void, ChatLayoutWelcomeMessage>;
+}
+/**
+ * 聊天布局配置接口（专家和智能体各有一套默认布局）
+ * 控制聊天组件整体布局的显示和功能
+ *
+ * @example
+ * const layout: ChatLayout = {
+ *   leftPanel: false,
+ *   conversationList: false,
+ *   preview: false,
+ *   messageList: true,
+ *   sender: {
+ *     props: {
+ *       prompts: false
+ *     }
+ *   },
+ *   chatHeader: {
+ *     render: (props) => <div>{props.children}</div>:
+ *   },
+ *   disclaimerNotice: false
+ * }
+ */
+interface ChatLayout {
+    /** 左侧面板渲染控制 */
+    leftPanel?: RenderControl<void, void>;
+    /** 会话列表面板渲染控制 */
+    conversationList?: RenderControl<void, ChatLayoutConversationList>;
+    /** 是否允许预览功能 */
+    preview?: boolean;
+    /** 消息列表渲染控制 */
+    messageList?: RenderControl<void, ChatLayoutMessageList>;
+    /** 输入框头部渲染控制 */
+    senderHeader?: RenderControl<void, void>;
+    /** 输入框渲染控制 */
+    sender?: RenderControl<void, ChatLayoutSender>;
+    /** 输入框底部渲染控制 */
+    senderFooter?: RenderControl<void, void>;
+    /** 全局头部渲染控制 */
+    globalHeader?: RenderControl<void, ChatLayoutHeader>;
+    /** 聊天区域头部渲染控制 */
+    chatHeader?: RenderControl<void, ChatLayoutHeader>;
+    /** 免责声明渲染控制 */
+    disclaimerNotice?: RenderControl<void, void>;
+}
+
+interface ChatConfig {
+    agent: AgentInfo;
+    conversationId?: string;
+    conversationStrategy?: ConversationStrategy;
+}
+interface ChatParams {
+    convMeta?: ConvMeta;
+    /** 扩展参数对象 透传大模型 */
+    params?: ObjectType<any>;
+}
+interface ChatProps {
+    theme?: ThemeConfig;
+    config?: ChatConfig;
+    params?: ChatParams;
+    hooks?: ChatHooks;
+    layout?: ChatLayout;
+    services?: ChatServices;
+}
+
+/**
+ * 附件组件属性接口
+ */
+interface AttachmentsProps {
+    /** 文件上传函数，接收 FormData 并返回上传结果 */
+    fileUpload: (formData: FormData, signal?: AbortSignal) => Promise<R<InputFile[]>>;
+    /** 文件上传配置列表，定义允许的文件类型和大小限制 */
+    fileUploadConfig?: FileUploadConfig;
+    /** 额外的上传参数，会附加到 FormData 中 */
+    extraParams?: ObjectType<string | undefined>;
+    /** 当前文件列表 */
+    fileList?: InputFile[];
+    /** 文件列表变化回调函数 */
+    onChange: (fileList: InputFile[]) => void;
+}
+
+/**
+ * ChatSender 组件暴露的方法接口
+ */
+interface ChatSenderHandle {
+    /** 聚焦输入框 */
+    focus: (options?: {
+        cursor?: 'start' | 'end';
+    }) => void;
+}
+/**
+ * 文件上传配置接口
+ */
+interface FileUpload {
+    /** 上传时的额外参数 */
+    params?: ObjectType<any>;
+    /** 文件上传配置列表 */
+    config: FileUploadConfig;
+    /** 文件上传请求函数 */
+    request: AttachmentsProps['fileUpload'];
+}
+/**
+ * ChatSender 组件属性接口
+ */
+interface SenderProps {
+    /** 输入框占位符 */
+    placeholder?: string;
+    /** 输入框内容 */
+    content?: string;
+    /** 文件列表 */
+    fileList?: InputFile[];
+    /** 是否打开文件选择头部 */
+    headerOpen?: boolean;
+    /** 是否正在发送消息 */
+    loading?: boolean;
+    /** 内容变化回调 */
+    onContentChange: (value: string) => void;
+    /** 文件列表变化回调 */
+    onFileListChange: (files: InputFile[]) => void;
+    /** 头部打开状态变化回调 */
+    onHeaderOpenChange: (open: boolean) => void;
+    /** 发送消息回调 */
+    onSend: () => void;
+    /** 取消发送回调 */
+    onCancel?: () => void;
+    /** 输入框聚焦回调 */
+    onFocus?: () => void;
+    /** 头部额外内容 */
+    extraHeader?: React.ReactNode;
+    /** 底部额外内容 */
+    extraFooter?: React.ReactNode;
+    /** 底部下方额外内容 */
+    extraFooterBelow?: React.ReactNode;
+    /** 发送按钮属性 */
+    sendBtnProps?: ButtonProps;
+    /** 文件上传配置 */
+    fileUpload?: FileUpload;
+}
+declare const _default$3: react.ForwardRefExoticComponent<SenderProps & react.RefAttributes<ChatSenderHandle>>;
+
+interface MessageRenderProps {
+    message: ConversationMessage;
+    messageIndex?: number;
+    loading?: boolean;
+    onFilePreview?: (file: InputFile) => void;
+    containerRef?: react__default.Ref<HTMLDivElement>;
+    /** message自定义标记渲染组件 */
+    customComponents?: ChatLayoutMessageList['customComponents'];
+}
+declare const _default$2: react__default.MemoExoticComponent<({ message, messageIndex, loading, containerRef, customComponents }: MessageRenderProps) => react_jsx_runtime.JSX.Element>;
+
+declare const _default$1: ({ firstMessages, welcomeMessage, avatar, agentActions, customComponents }: ChatLayoutMessageList) => react_jsx_runtime.JSX.Element;
+
+declare const _default: react.ForwardRefExoticComponent<ChatProps & react.RefAttributes<ChatHandle>>;
+
+export { type AgentConfig, type AgentInfo, type AgentSpec, _default$1 as BubbleListItems, type ChatConfig, _default as ChatCopilot, type ChatHandle, type ChatProps, _default$3 as ChatSender, type ConversationMessage, type FileUploadConfig, type InputFile, _default$2 as MessageRender };