@zero-library/chat-agent 2.1.19 → 2.2.0

package/dist/index.d.mts

@@ -1,14 +1,40 @@
-import { createRequest, RenderControl, UserInfo } from '@zero-library/common';
+import { createRequest, RequestConfig, RenderControl } from '@zero-library/common';
 import { ButtonProps, ThemeConfig } from 'antd';
 import * as react from 'react';
 import { Conversation, BubbleProps } from '@ant-design/x';
-export * from '@ant-design/x';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
+/**
+ * 聊天服务模块
+ * 提供聊天相关的 API 接口定义和类型声明
+ * 包含会话管理、消息处理、智能体操作等功能
+ */
+/**
+ * 用户信息接口
+ * 定义用户的基本信息和权限配置
+ */
+interface UserInfo {
+    /** 用户ID */
+    id?: string | number;
+    /** 用户姓名 */
+    name?: string;
+    /** 头像地址 */
+    avatar?: string;
+    /** 备注信息 */
+    remark?: string;
+}
+/**
+ * 会话列表查询参数接口
+ * 用于获取用户的会话列表
+ */
 interface ConversationsQuery extends PageReq {
+    /** 业务数据唯一ID，非必填 */
     businessId?: string;
+    /** 业务类型，非必填 */
     businessType?: number;
+    /** 目标ID（如智能体ID、专家ID等） */
     targetId: string;
+    /** 目标类型：1-用户 2-专家 3-Agent 4-税协 */
     targetType: number;
 }
 /**
@@ -148,299 +174,218 @@ interface ConversationRecentQuery {
      */
     receiverType: number;
 }
+/**
+ * 会话消息查询参数接口
+ * 用于获取指定会话的消息列表
+ */
 interface conversationMessagesQuery extends PageReq {
+    /** 会话ID */
     conversationId: string;
 }
+/**
+ * 输入文件接口
+ * 定义聊天中上传文件的属性
+ */
 interface InputFile {
-    /**
-     * Content，文件内容
-     */
+    /** 文件内容（base64编码或URL） */
     content: string;
-    /**
-     * 文件模式 remote_url local_file
-     */
+    /** 文件模式：remote_url（远程URL）| local_file（本地文件） */
     mode: string;
-    /**
-     * Type，文件类型
-     */
+    /** 文件类型（MIME类型） */
     type: string;
-    /**
-     * 文件扩展名
-     */
+    /** 文件扩展名 */
     extension: string;
-    /**
-     * 文件名
-     */
+    /** 文件名 */
     name: string;
 }
+/**
+ * 消息引用类型
+ * 用于消息回复时的引用信息
+ */
 interface MessageQuoteMsg {
-    /**
-     * Id，消息ID
-     */
+    /** 被引用的消息ID */
     id?: string;
-    /**
-     * Msgcontent，消息内容
-     */
+    /** 被引用的消息内容 */
     msgContent?: string;
-    /**
-     * Msgfiles，附件文件列表
-     */
+    /** 被引用消息的附件文件列表 */
     msgFiles?: InputFile[];
 }
+/**
+ * 消息发送者接口
+ * 定义消息发送者的身份信息
+ */
 interface MessageSender {
-    /**
-     * Curruser，是否为当前用户
-     */
+    /** 是否为当前用户 */
     currUser?: boolean;
-    /**
-     * Id，发送者ID
-     */
+    /** 发送者ID */
     id: string;
-    /**
-     * Type，1-用户 2-专家 3-Agent  4-税协
-     */
+    /** 发送者类型：1-用户 2-专家 3-Agent 4-税协 */
     type: number;
 }
+/**
+ * 会话消息接口
+ * 定义聊天消息的完整信息
+ */
 interface ConversationMessage {
-    /**
-     * Conversationid，会话ID
-     */
+    /** 会话ID */
     conversationId: string;
+    /** 会话标题（WebSocket返回时可能包含） */
     conversationTitle?: string;
+    /** 消息类型：WebSocket流式消息类型 */
     type?: 'TEXT_MESSAGE_START' | 'STEP_STARTED' | 'TEXT_MESSAGE_CONTENT' | 'TEXT_MESSAGE_END' | 'RUN_ERROR';
-    /**
-     * Id，消息ID
-     */
+    /** 消息ID */
     id: string;
-    /**
-     * Msgcontent，消息内容
-     */
+    /** 消息内容 */
     msgContent: string;
-    /**
-     * Msgfeedback，消息反馈
-     */
+    /** 消息反馈：1-赞 2-踩 */
     msgFeedback?: number;
-    /**
-     * Msgfiles，附件文件列表
-     */
+    /** 附件文件列表 */
     msgFiles?: InputFile[];
-    /**
-     * 引消息
-     */
+    /** 引用的消息信息 */
     quoteMsg?: MessageQuoteMsg;
-    /**
-     * 发送者信息
-     */
+    /** 发送者信息 */
     sender?: MessageSender;
-    /**
-     * Sendtime，发送时间
-     */
+    /** 发送时间戳 */
     sendTime: number;
-    /**
-     * Stopflag，是否打断
-     */
+    /** 是否被打断标志 */
     stopFlag?: boolean;
 }
+/**
+ * 消息反馈更新接口
+ * 用于用户对消息进行赞/踩评价
+ */
 interface FeedbackUpdate {
-    /**
-     * Conversationid，会话ID
-     */
+    /** 会话ID */
     conversationId: string;
-    /**
-     * Id，消息ID
-     */
+    /** 消息ID */
     id: string;
-    /**
-     * Msgfeedback，反馈类型：1-赞，2-踩
-     */
+    /** 反馈类型：1-赞 2-踩 */
     msgFeedback: number;
-    /**
-     * Msgfeedbackcontent，消息反馈内容
-     */
+    /** 反馈内容描述，非必填 */
     msgFeedbackContent?: string;
 }
+/**
+ * 消息发送参数接口
+ * 定义发送消息时所需的全部参数
+ */
 interface ConversationMessageSend {
-    /**
-     * Conversationid，会话 ID
-     */
+    /** 会话ID */
     conversationId: string;
-    /**
-     * Msgcontent，消息内容
-     */
+    /** 消息内容 */
     msgContent: string;
-    /**
-     * Msgfiles，附件文件列表
-     */
+    /** 附件文件列表 */
     msgFiles?: InputFile[];
-    /**
-     * Params，业务参数,透传到智能体
-     */
+    /** 业务参数，透传到智能体的JSON字符串 */
     params?: string;
-    /**
-     * Quotemsgid，引用的消息 ID，大于 0 的整数
-     */
+    /** 引用的消息ID，大于0的整数 */
     quoteMsgId?: number;
-    /**
-     * Receiverid，接收者 ID。当 receiverType ≠ 3（非 agent）时，后端需填充此字段
-     */
+    /** 接收者ID，当receiverType≠3时由后端填充 */
     receiverId: string;
-    /**
-     * Receivertype，接收者身份，必填：1-用户；2-专家；3-agent 4-税协
-     */
+    /** 接收者类型：1-用户 2-专家 3-agent 4-税协 */
     receiverType: number;
-    /**
-     * Returntype，返回方式：1-http；2-ws（WebSocket）
-     */
+    /** 返回方式：1-http 2-WebSocket */
     returnType: number;
-    /**
-     * Senderid，发送者 ID
-     */
+    /** 发送者ID */
     senderId: string;
-    /**
-     * Sendertype，发送者身份，必填：1-用户；2-专家；3-agent 4-税协
-     */
+    /** 发送者类型：1-用户 2-专家 3-agent 4-税协 */
     senderType: number;
-    /**
-     * Source，会话来源: 1-罗拉-APP; 2-罗拉-pc端; 3-合作伙伴端 4-税协 5-罗拉-cube 6-api
-     */
+    /** 会话来源：1-罗拉-APP 2-罗拉-pc端 3-合作伙伴端 4-税协 5-罗拉-cube 6-api */
     source: number;
-    /**
-     * Stream，是否启用流式返回响应结果
-     */
+    /** 是否启用流式返回 */
     stream: boolean;
 }
 /**
- * FileUploadConfig，文件上传配置
+ * 文件上传配置接口
+ * 定义智能体的文件上传规则
  */
 interface FileUploadConfig {
-    /**
-     * Allowedfiletypes，允许的文件类型
-     */
+    /** 允许的文件类型列表（MIME类型或扩展名） */
     allowedFileTypes: string[];
-    /**
-     * Enabled，是否启用文件上传
-     */
+    /** 是否启用文件上传功能 */
     enabled: boolean;
-    /**
-     * Maxfilecount，最大文件数量
-     */
+    /** 单次上传最大文件数量 */
     maxFileCount: number;
-    /**
-     * Maxfilesize，最大文件大小
-     */
+    /** 单个文件最大大小（字节） */
     maxFileSize?: number;
 }
 /**
- * QuestionBO，推荐问题或热门问题项
+ * 推荐问题接口
+ * 定义单个推荐问题的结构
  */
 interface RecommendQuestion {
-    /**
-     * Id，问题 ID
-     */
+    /** 问题ID */
     id: number;
-    /**
-     * Question，问题内容
-     */
+    /** 问题内容 */
     question: string;
 }
 /**
- * LabelBO，热门问题标签
+ * 热门问题标签接口
+ * 定义热门问题的分类标签
  */
 interface HotQuestionList {
-    /**
-     * Id，标签 ID
-     */
+    /** 标签ID */
     id: number;
-    /**
-     * Items，标签下的问题列表
-     */
+    /** 标签下的问题列表 */
     items: RecommendQuestion[];
-    /**
-     * Name，标签名称
-     */
+    /** 标签名称 */
     name: string;
 }
+/**
+ * 智能体配置接口
+ * 定义智能体的功能配置信息
+ */
 interface AgentConfig {
-    /**
-     * 文件上传配置
-     */
+    /** 文件上传配置列表 */
     fileUpload?: FileUploadConfig[];
-    /**
-     * Labels，热门问题标签列表
-     */
+    /** 热门问题标签列表 */
     labels?: HotQuestionList[];
-    /**
-     * Recommendquestions，推荐问题列表
-     */
+    /** 推荐问题列表 */
     recommendQuestions?: RecommendQuestion[];
 }
+/**
+ * 智能体信息接口
+ * 定义智能体的基本信息和配置
+ */
 interface AgentInfo {
-    /**
-     * Agentname，名称
-     */
+    /** 智能体名称 */
     agentName: string;
-    /**
-     * Agenttype，智能体类型
-     */
+    /** 智能体类型 */
     agentType: number;
-    /**
-     * 智能体的附带信息
-     */
+    /** 智能体的配置信息 */
     config: AgentConfig;
-    /**
-     * Description，描述
-     */
+    /** 智能体描述 */
     description?: string;
-    /**
-     * Id，主键
-     */
+    /** 智能体ID */
     id: string;
-    /**
-     * Isavailable，是否可用
-     */
+    /** 智能体是否可用 */
     isAvailable?: boolean;
-    /**
-     * Logo，logo
-     */
+    /** 智能体Logo地址 */
     logo: string;
+    /** 智能体特性配置，JSON字符串格式 */
     feature?: string;
 }
+/**
+ * 智能体性格接口
+ * 定义智能体的性格特征配置
+ */
 interface AgentCharacter {
-    /**
-     * Agentid，智能体ID
-     */
+    /** 智能体ID */
     agentId: number;
-    /**
-     * Charactername，性格名称
-     */
+    /** 性格名称 */
     characterName: string;
-    /**
-     * Detaillevel，详细程度：1-10
-     */
+    /** 详细程度评级：1-10 */
     detailLevel: number;
-    /**
-     * Humorlevel，幽默程度：1-10
-     */
+    /** 幽默程度评级：1-10 */
     humorLevel: number;
-    /**
-     * Id，id
-     */
+    /** 性格配置ID */
     id: number;
-    /**
-     * Logo，头像，存储图片路径
-     */
+    /** 性格头像图片路径 */
     logo: string;
-    /**
-     * Professionallevel，专业程度：1-10
-     */
+    /** 专业程度评级：1-10 */
     professionalLevel: number;
-    /**
-     * Selected，是否已选择
-     */
+    /** 是否为当前选择的性格 */
     selected: boolean;
-    /**
-     * Sex，性别：1-男，2-女
-     */
+    /** 性别设置：1-男 2-女 */
     sex: number;
 }
 /**
@@ -505,78 +450,671 @@ declare const createFileService: (request: ReturnType<typeof createRequest>) =>
     fileCreate: (fileContent: string, fileName?: string, targetFormat?: string) => Promise<void>;
 };
 
+/**
+ * 会话策略类型
+ * 定义创建或获取会话的策略
+ *
+ * 取值说明：
+ * - 1: 最近会话策略 - 获取用户最近的会话继续对话
+ * - 2: 新会话策略 - 创建全新的会话开始对话
+ */
 type ConversationStrategy = 1 | 2;
+/**
+ * 引用内容接口
+ * 扩展消息引用信息，支持更多引用格式
+ *
+ * @example
+ * // 引用文档片段
+ * const quote: ReferencesContent = {
+ *   name: '法规条款',
+ *   markdown: '> 根据《企业所得税法》第XX条规定...',
+ * }
+ */
 interface ReferencesContent extends MessageQuoteMsg {
+    /** 引用名称 */
     name?: string;
+    /** Markdown格式的引用内容 */
     markdown?: string;
+    /** 其他扩展属性 */
     [key: string]: any;
 }
+/**
+ * 引用类型接口
+ * 定义消息引用的各种类型和参数
+ *
+ * @example
+ * // Markdown引用（拼接到正文发送）
+ * const markdownRef: ReferencesType = {
+ *   type: 1,
+ *   content: {
+ *     name: '法规摘要',
+ *     markdown: '> 根据相关规定...'
+ *   },
+ *   params: {
+ *     source: 'law-001'
+ *   }
+ * }
+ *
+ * // 文案引用（不发送正文）
+ * const textRef: ReferencesType = {
+ *   type: 2,
+ *   content: {
+ *     name: '参考答案',
+ *     markdown: '建议按以下方式处理...'
+ *   }
+ * }
+ *
+ * // 消息引用
+ * const messageRef: ReferencesType = {
+ *   type: 3,
+ *   content: {
+ *     id: 'msg-001',
+ *     msgContent: '之前的回答内容'
+ *   }
+ * }
+ */
 interface ReferencesType {
+    /** 引用类型：1-markdown引用（拼正文发） 2-文案引用（不发正文） 3-消息引用 */
     type: number;
+    /** 引用内容 */
     content: ReferencesContent;
+    /** 引用参数，最终透传大模型 */
     params?: ObjectType<any>;
 }
+/**
+ * 聊天组件生命周期钩子接口
+ * 定义聊天组件在各种事件发生时的回调函数
+ * @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 ${getToken()}`
+ *       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['msgContent'], files: InputFile[]) => boolean | Promise<boolean> | void;
+    /**
+     * 发送消息后回调
+     * 在消息发送完成后调用
+     *
+     * @example
+     * onAfterSend: () => {
+     *   console.log('消息发送完成')
+     *   // 可以在这里执行后续操作，如滚动到底部
+     * }
+     */
     onAfterSend?: () => 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 ${getToken()}`
+     *     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;
 }
+/**
+ * 聊天参数接口
+ * 定义聊天组件的运行时参数
+ */
 interface ChatParams {
-    source?: number;
+    /** 会话来源设置：1-罗拉-APP 2-罗拉-pc端 3-合作伙伴端 4-税协 5-罗拉-cube 6-api */
+    source: number;
+    /** 业务扩展数据，非必填 JSON字符串格式 */
     businessData?: string;
+    /** 业务数据唯一ID 非必填 */
     businessId?: string;
+    /** 业务类型 非必填 1-风控；2-弹窗 */
     businessType?: number;
+    /** 扩展参数对象 透传大模型 */
     params?: ObjectType<any>;
 }
+/**
+ * 聊天布局头部配置接口
+ * 控制聊天头部区域的显示和功能
+ * ChatHeader组件默认 title = true, avatar = true, closeBtn = false, newConversationBtn = true, conversationListBtn = true
+ * @example
+ * // 自定义头部配置
+ * const header: ChatLayoutHeader = {
+ *   title: true, // 显示标题
+ *   avatar: true, // 显示头像
+ *   closeBtn: true, // 显示关闭按钮
+ *   newConversationBtn: false, // 隐藏新建会话按钮
+ *   agentCharacter: true, // 显示智能体性格选择
+ *   conversationListBtn: true // 显示会话列表按钮
+ * }
+ */
 interface ChatLayoutHeader {
+    /** 标题渲染控制 */
     title?: RenderControl<void, void>;
+    /** 头像渲染控制 */
+    avatar?: RenderControl<void, void>;
+    /** 是否显示关闭按钮 */
     closeBtn?: boolean;
+    /** 新建会话按钮渲染控制 */
     newConversationBtn?: RenderControl<void, void>;
+    /** 是否显示智能体性格选择 */
     agentCharacter?: boolean;
+    /** 是否显示会话列表按钮 */
     conversationListBtn?: boolean;
 }
+/**
+ * 聊天布局会话列表配置接口
+ * 控制会话列表区域的显示和功能
+ * ConversationList组件默认 header = true
+ * @example
+ * // 自定义会话列表配置
+ * const conversationList: ChatLayoutConversationList = {
+ *   header: true // 显示会话列表头部
+ * }
+ */
 interface ChatLayoutConversationList {
+    /** 会话列表头部渲染控制 */
     header?: RenderControl<void, void>;
 }
+/**
+ * 聊天布局输入框配置接口
+ * 控制输入框区域的功能和样式
+ * 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>;
+    /** 发送按钮属性配置函数 */
     sendBtnProps?: () => ButtonProps;
+    /** 是否显示推荐问题 */
     prompts?: boolean;
 }
+/**
+ * 消息列表欢迎信息配置
+ * 控制聊天界面初始欢迎信息的显示内容和自定义渲染
+ * @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 {
+    /** 头像显示控制：可以是全局布尔值或按成员类型分别控制 */
     avatar?: boolean | Partial<Record<ConversationMemberEnum, boolean>>;
+    /** 首条消息渲染控制 */
     firstMessage?: RenderControl<void, void>;
+    /** 欢迎消息渲染控制, 要渲染时如果列表有内容则不渲染 */
+    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>;
 }
+type RequestInstance = ReturnType<typeof createChatService> & ReturnType<typeof createFileService>;
+/**
+ * 聊天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 {
-    websocketBaseUrls?: string[];
-    baseUrl?: string;
-    request?: ReturnType<typeof createChatService> & ReturnType<typeof createFileService>;
+    /** HTTP服务配置 */
+    http?: ChatHttpServices;
+    /** WebSocket服务配置 */
+    websocket?: ChatWebsocketServices;
 }
 
 /**
@@ -659,33 +1197,326 @@ interface SenderProps {
 }
 declare const _default$2: react.ForwardRefExoticComponent<SenderProps & react.RefAttributes<ChatSenderHandle>>;
 
+/**
+ * 聊天组件配置接口
+ * 定义聊天组件的初始化配置选项
+ *
+ * @example
+ * // 基本配置 - 指定智能体
+ * const config: ChatConfig = {
+ *   receiverType: 3, // 智能体类型
+ *   receiverId: 'agent-001', // 智能体ID
+ *   conversationStrategy: 2 // 创建新会话
+ * }
+ *
+ * @example
+ * // 指定已有会话
+ * const config: ChatConfig = {
+ *   conversationId: 'conv-001' // 直接打开指定会话
+ * }
+ */
 interface ChatConfig {
+    /** 接收者类型：1-用户 2-专家 3-Agent; 控制默认布局显示 */
     receiverType?: number;
+    /** 接收者ID：专家或智能体ID */
     receiverId?: string;
+    /** 会话ID：已存在的会话ID */
     conversationId?: string;
+    /** 会话策略：1-最近会话 2-新会话 */
     conversationStrategy?: ConversationStrategy;
 }
+/**
+ * 提供外部操作聊天组件的方法
+ *
+ * @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: '法规条款',
+ *     markdown: '> 根据《企业所得税法》第XX条规定...'
+ *   }
+ * })
+ *
+ * // 聚焦输入框
+ * chatRef.current?.senderFocus()
+ */
 interface ChatHandle {
-    sendMessage: (message?: string, files?: InputFile[]) => void;
+    /** 发送消息
+     * @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 agentId - 目标智能体ID
+     * @param strategy - 会话策略，1-使用最近会话，2-创建新会话
+     *
+     * @example
+     * // 切换到指定智能体并创建新会话
+     * chatRef.current?.switchAgentConversation('agent-001')
+     *
+     * @example
+     * // 切换到指定智能体并使用最近会话
+     * chatRef.current?.switchAgentConversation('agent-001', 1)
+     */
     switchAgentConversation: (agentId: AgentInfo['id'], strategy?: ConversationStrategy) => Promise<void>;
-    switchConversation: (id?: Conversation['id']) => Promise<void>;
+    /**
+     * 切换到指定的会话
+     *
+     * @param id - 目标会话ID
+     *
+     * @example
+     * // 切换到指定会话
+     * chatRef.current?.switchConversation('conv-001')
+     */
+    switchConversation: (id: Conversation['id']) => Promise<void>;
+    /**
+     * 基于当前接收者创建新的会话
+     *
+     * @example
+     * // 创建新会话
+     * chatRef.current?.createConversation()
+     */
     createConversation: () => Promise<void>;
+    /**
+     * 设置引用消息
+     * 在输入框中设置引用内容，将在下次发送消息时包含引用信息
+     *
+     * @param references - 引用内容对象
+     *
+     * @example
+     * // 设置Markdown引用
+     * chatRef.current?.setReferences({
+     *   type: 1,
+     *   content: {
+     *     name: '法规条款',
+     *     markdown: '> 根据《企业所得税法》第XX条规定...'
+     *   },
+     *   params: {
+     *     source: 'law-001'
+     *   }
+     * })
+     *
+     * @example
+     * // 清除引用
+     * chatRef.current?.setReferences(undefined)
+     */
     setReferences: (references?: ReferencesType) => void;
+    /**
+     * 直接设置输入框中的文本内容
+     *
+     * @param message - 要设置的消息内容
+     *
+     * @example
+     * // 设置输入框内容
+     * chatRef.current?.setMessage('请帮我分析以下问题...')
+     *
+     * @example
+     * // 清空输入框
+     * chatRef.current?.setMessage('')
+     */
     setMessage: (message?: string) => 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: {
+     *     textInfo: '税务局',
+     *   }
+     * })
+     */
     setParams: (params?: ChatParams) => 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;
+    /**
+     * 输入框聚焦
+     * 使聊天输入框获得焦点
+     *
+     * @example
+     * // 聚焦输入框
+     * chatRef.current?.senderFocus()
+     */
     senderFocus: ChatSenderHandle['focus'];
 }
+/**
+ * 聊天组件属性接口
+ * 定义聊天组件的输入属性
+ */
 interface ChatProps {
+    /** 主题配置 */
     theme?: ThemeConfig;
+    /** 聊天配置 */
     config?: ChatConfig;
+    /** 聊天参数 */
     params?: ChatParams;
+    /** 生命周期钩子 */
     hooks?: ChatHooks;
+    /** 布局配置 */
     layout?: ChatLayout;
+    /** 用户信息, 如果会话成员类型可以区分当前用户则不需要传入此参数；否则必传id */
     userInfo?: UserInfo;
+    /** 服务配置 */
     services?: ChatServices;
 }
+
+/**
+ * 聊天组件
+ * 使用 React.forwardRef 实现的聊天界面组件
+ * 集成了消息收发、会话管理、文件预览等功能
+ *
+ * @example
+ * // 基本使用
+ * <Chat
+ *   config={{
+ *     receiverType: 3,
+ *     receiverId: 'agent-001'
+ *   }}
+ *   params={{
+ *     businessId: 'case-001',
+ *     businessType: 2
+ *   }}
+ * />
+ *
+ * @example
+ * <Chat
+ *   config={{
+ *     receiverType: 3,
+ *     receiverId: 'agent-001'
+ *   }}
+ *   params={{
+ *     businessId: 'case-001',
+ *     businessType: 2
+ *   }}
+ *   // 钩子配置
+ *   hooks={{
+ *     onBeforeSend: (message, files) => {
+ *       if (!message?.trim()) {
+ *         message.error('请输入消息内容')
+ *         return false
+ *       }
+ *       return true
+ *     },
+ *     onAfterSend: () => {
+ *       console.log('消息发送完成')
+ *     }
+ *   }}
+ *   // 布局配置
+ *   layout={{
+ *     preview: true,
+ *     sender: {
+ *       props: {
+ *         placeholder: '请输入您的问题...'
+ *       }
+ *     }
+ *   }}
+ *   // 服务配置
+ *   services={{
+ *     http: {
+ *       config: {
+ *         baseURL: '/api',
+ *         timeout: 30000
+ *       }
+ *     },
+ *     websocket: {
+ *       baseURLs: ['/api', '/api/backup']
+ *     }
+ *   }}
+ * />
+ *
+ */
 declare const _default$1: react.ForwardRefExoticComponent<ChatProps & react.RefAttributes<ChatHandle>>;
 
 /**
@@ -703,4 +1534,4 @@ interface MessageRenderProps {
  */
 declare const _default: ({ message, placement }: MessageRenderProps) => react_jsx_runtime.JSX.Element;
 
-export { type AgentInfo, _default$3 as Attachments, type AttachmentsProps, type ChatConfig, _default$1 as ChatCopilot, type ChatHandle, type ChatHooks, type ChatLayout, type ChatParams, type ChatProps, _default$2 as ChatSender, type ConversationStrategy, type InputFile, _default as MessageRender, type MessageRenderProps, type ReferencesType, type SenderProps };
+export { type AgentInfo, _default$3 as Attachments, type AttachmentsProps, type ChatConfig, _default$1 as ChatCopilot, type ChatHandle, type ChatHooks, type ChatLayout, type ChatParams, type ChatProps, _default$2 as ChatSender, type ChatServices, type ConversationStrategy, type InputFile, _default as MessageRender, type MessageRenderProps, type ReferencesType, type RequestInstance, type SenderProps, type UserInfo };