@zero-library/chat-agent 2.1.20 → 2.2.0

package/dist/index.d.ts

@@ -1,8 +1,7 @@
-import { createRequest, RenderControl } 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';
 
 /**
@@ -16,27 +15,13 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
  */
 interface UserInfo {
     /** 用户ID */
-    id: number;
-    /** 机构名称 */
-    orgName?: string;
+    id?: string | number;
     /** 用户姓名 */
-    name: string;
-    /** 用户名 */
-    username?: string;
-    /** 手机号 */
-    mobile?: string;
+    name?: string;
     /** 头像地址 */
-    avatar: string;
-    /** 我的邀请码 */
-    myInviteCode?: string;
-    /** 邮箱地址 */
-    email?: string;
+    avatar?: string;
     /** 备注信息 */
     remark?: string;
-    /** 角色ID列表 */
-    roles?: number[];
-    /** 权限代码列表 */
-    permissions?: string[];
 }
 /**
  * 会话列表查询参数接口
@@ -467,13 +452,23 @@ declare const createFileService: (request: ReturnType<typeof createRequest>) =>
 
 /**
  * 会话策略类型
- * 1-最近会话：获取用户最近的会话继续对话
- * 2-新会话：创建全新的会话开始对话
+ * 定义创建或获取会话的策略
+ *
+ * 取值说明：
+ * - 1: 最近会话策略 - 获取用户最近的会话继续对话
+ * - 2: 新会话策略 - 创建全新的会话开始对话
  */
 type ConversationStrategy = 1 | 2;
 /**
  * 引用内容接口
  * 扩展消息引用信息，支持更多引用格式
+ *
+ * @example
+ * // 引用文档片段
+ * const quote: ReferencesContent = {
+ *   name: '法规条款',
+ *   markdown: '> 根据《企业所得税法》第XX条规定...',
+ * }
  */
 interface ReferencesContent extends MessageQuoteMsg {
     /** 引用名称 */
@@ -486,73 +481,418 @@ interface ReferencesContent extends MessageQuoteMsg {
 /**
  * 引用类型接口
  * 定义消息引用的各种类型和参数
+ *
+ * @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;
-    /** 业务扩展数据，JSON字符串格式 */
+    /** 会话来源设置：1-罗拉-APP 2-罗拉-pc端 3-合作伙伴端 4-税协 5-罗拉-cube 6-api */
+    source: number;
+    /** 业务扩展数据，非必填 JSON字符串格式 */
     businessData?: string;
-    /** 业务数据唯一ID */
+    /** 业务数据唯一ID 非必填 */
     businessId?: string;
-    /** 业务类型 */
+    /** 业务类型 非必填 1-风控；2-弹窗 */
     businessType?: number;
-    /** 扩展参数对象 */
+    /** 扩展参数对象 透传大模型 */
     params?: ObjectType<any>;
 }
 /**
  * 聊天布局头部配置接口
  * 控制聊天头部区域的显示和功能
- * 默认 title = true, closeBtn = false, newConversationBtn = true, conversationListBtn = true
+ * 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;
     /** 新建会话按钮渲染控制 */
@@ -565,7 +905,12 @@ interface ChatLayoutHeader {
 /**
  * 聊天布局会话列表配置接口
  * 控制会话列表区域的显示和功能
- * 默认 header = true
+ * ConversationList组件默认 header = true
+ * @example
+ * // 自定义会话列表配置
+ * const conversationList: ChatLayoutConversationList = {
+ *   header: true // 显示会话列表头部
+ * }
  */
 interface ChatLayoutConversationList {
     /** 会话列表头部渲染控制 */
@@ -574,7 +919,19 @@ interface ChatLayoutConversationList {
 /**
  * 聊天布局输入框配置接口
  * 控制输入框区域的功能和样式
- * 默认 placeholder, extraBtn = false, referencesBtn = false
+ * ChatSender组件默认 placeholder, extraBtn = false, referencesBtn = false
+ * @example
+ * // 自定义输入框配置
+ * const sender: ChatLayoutSender = {
+ *   placeholder: '请输入您的问题...',
+ *   extraBtn: true, // 显示额外按钮
+ *   referencesBtn: true, // 显示引用按钮
+ *   prompts: true, // 显示推荐问题
+ *   sendBtnProps: () => ({
+ *     type: 'primary',
+ *     children: '发送'
+ *   })
+ * }
  */
 interface ChatLayoutSender {
     /** 输入框占位符文本 */
@@ -590,19 +947,67 @@ interface ChatLayoutSender {
     /** 是否显示推荐问题 */
     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 {
     /** 左侧面板渲染控制 */
@@ -626,17 +1031,90 @@ interface ChatLayout {
     /** 免责声明渲染控制 */
     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 {
-    /** WebSocket连接基础URL列表，支持多地址容错 */
-    websocketBaseUrls?: string[];
-    /** API基础URL */
-    baseUrl?: string;
-    /** 聊天服务和文件服务的合并请求对象 */
-    request?: ReturnType<typeof createChatService> & ReturnType<typeof createFileService>;
+    /** HTTP服务配置 */
+    http?: ChatHttpServices;
+    /** WebSocket服务配置 */
+    websocket?: ChatWebsocketServices;
 }
 
 /**
@@ -722,9 +1200,23 @@ declare const _default$2: react.ForwardRefExoticComponent<SenderProps & react.Re
 /**
  * 聊天组件配置接口
  * 定义聊天组件的初始化配置选项
+ *
+ * @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 */
+    /** 接收者类型：1-用户 2-专家 3-Agent; 控制默认布局显示 */
     receiverType?: number;
     /** 接收者ID：专家或智能体ID */
     receiverId?: string;
@@ -734,29 +1226,209 @@ interface ChatConfig {
     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'];
 }
 /**
@@ -774,15 +1446,76 @@ interface ChatProps {
     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>>;
 
@@ -801,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 ChatServices, type ConversationStrategy, type InputFile, _default as MessageRender, type MessageRenderProps, type ReferencesType, type SenderProps, type UserInfo };
+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 };