ibc-ai-web-sdk 2.1.0 → 2.1.2

package/README.md

@@ -84,39 +84,75 @@ AIWebSDK.create({
 | `headers` | object | `{}` | | 附加请求头 |
 | `extendInfo` | object | `{}` | | 随请求发送的扩展信息 |
 
-### Token 刷新
+### Token 管理
 
-提供 `refreshTokenFn` 即可，SDK 会自动处理过期检测和刷新。
+SDK 的 Token 生命周期**应与应用层保持一致**，建议应用层为 SDK 签发的 Token TTL 与自身登录态 TTL 相同。
+
+#### 正常刷新
+
+提供 `refreshTokenFn`，SDK 会在 Token 即将过期时自动刷新（默认提前 60 秒）。
 
 ```js
 createAIChatDialog({
-  token: 'initial-access-token',
-  tokenExpiresAt: Date.now() + 30 * 60 * 1000,  // Token 过期时间戳
-  refreshToken: 'initial-refresh-token',          // 可选
+  token: 'st-xxxx',                             // 由应用后端调 /v1/token/create 签发
+  tokenExpiresAt: Date.now() + 7200 * 1000,     // SDK Token 过期时间戳（毫秒），建议与用户登录态一致
+  refreshToken: 'initial-refresh-token',         // 可选：服务端刷新凭证
 
   refreshTokenFn: async ({ token, refreshToken, userId }) => {
-    const res = await fetch('/api/auth/refresh', {
+    // 调自己的后端接口，后端用 API-Key 调 /v1/token/create 拿新 st- Token
+    const res = await fetch('/api/auth/refresh-sdk-token', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ token, refreshToken, userId })
+      body: JSON.stringify({ userId })
     });
     const data = await res.json();
     return {
-      token: data.accessToken,
+      token: data.token,
       expiresAt: data.expiresAt * 1000
     };
   }
 });
 ```
 
+#### Token 彻底失效
+
+当 Token 过期且刷新失败（如刷新接口返回 401），或未配置 `refreshTokenFn` 时，SDK 会触发 `onAuthExpired` 回调。**应用层应在此回调中引导用户重新登录。**
+
+```js
+createAIChatDialog({
+  token: 'st-xxxx',
+  tokenExpiresAt: Date.now() + 7200 * 1000,
+
+  onAuthExpired: ({ reason, message }) => {
+    console.log('SDK Token 已失效:', reason, message);
+    dialog.destroy();        // 销毁 SDK 实例
+    router.push('/login');   // 引导用户重新登录
+  }
+});
+
+// 登录成功后：重新拿 Token，重新初始化 SDK
+async function afterLogin(userId) {
+  // 1. 调后端通过 API-Key 签新 st- Token
+  const { token, expiresAt } = await fetchNewSdkToken(userId);
+  // 2. 重新初始化 SDK
+  dialog = createAIChatDialog({
+    token,
+    tokenExpiresAt: expiresAt * 1000,
+    onAuthExpired: () => { /* 同上 */ }
+  });
+}
+```
+
 | 参数 | 类型 | 说明 |
 |------|------|------|
-| `token` | string | 认证 Token |
-| `tokenExpiresAt` | number | Token 过期时间戳（毫秒） |
-| `refreshToken` | string | refresh token |
+| `token` | string | 认证 Token（由后端用 API-Key 调 `/v1/token/create` 签发） |
+| `tokenExpiresAt` | number | Token 过期时间戳（毫秒）。建议与应用登录态 TTL 一致 |
+| `tokenRefreshBufferMs` | number | 过期前多久提前刷新（毫秒），默认 60000 |
+| `refreshToken` | string | 后端刷新凭证（可选） |
 | `refreshTokenFn` | function | 刷新函数，返回新 token 信息 |
 | `onTokenRefreshed` | function | 刷新成功回调 |
-| `onTokenExpired` | function | 刷新失败回调 |
+| `onAuthExpired` | function | 认证彻底失效回调。**在此处引导用户重新登录** |
+
 ```
 
 ### 高级配置
@@ -431,7 +467,9 @@ data: {"conversationId":"conv_xxx","tokens":{"input":10,"output":15}}
 
 ### 认证
 
-所有请求自动携带 `Authorization: Bearer {token}`。提供 `refreshTokenFn` 后 Token 过期会自动刷新，无需手动处理。
+所有请求自动携带 `Authorization: Bearer {token}`。Token 由应用后端通过 API-Key 调用 `/v1/token/create` 签发，建议 TTL 与应用登录态保持一致。
+
+Token 过期后 SDK 触发 `onAuthExpired` 回调，应用层应引导用户重新登录。登录成功后调用 `updateConfig({ token, tokenExpiresAt, ... })` 或重新初始化 SDK 传入新 Token。
 
 ---
 

package/dist/index.cjs.js

@@ -195,12 +195,19 @@ class AIChatClient {
     silent = false
   } = {}) {
     if (typeof this.config.refreshTokenFn !== 'function') {
-      const error = new Error('Token 已过期且未配置 refreshTokenFn');
+      const authErr = new Error('Token 已过期且未配置 refreshTokenFn');
+      authErr._authExpired = true;
+      authErr._authReason = reason;
       if (!silent) {
         this.stopBackgroundRefresh();
-        this.config.onTokenExpired?.(error);
+        this.config.onAuthExpired?.({
+          reason,
+          message: authErr.message,
+          noRefreshFn: true,
+          error: authErr
+        });
       }
-      throw error;
+      throw authErr;
     }
     if (!this.refreshTokenPromise) {
       this.refreshTokenPromise = Promise.resolve().then(() => this.config.refreshTokenFn({
@@ -227,8 +234,17 @@ class AIChatClient {
           return this.config.token || '';
         }
         this.stopBackgroundRefresh();
-        this.config.onTokenExpired?.(error);
-        throw error;
+        const errMsg = error && (error.message || String(error)) || 'Token 刷新失败，请重新登录';
+        this.config.onAuthExpired?.({
+          reason,
+          message: errMsg,
+          noRefreshFn: false,
+          error
+        });
+        const authErr = new Error(errMsg);
+        authErr._authExpired = true;
+        authErr._authReason = reason;
+        throw authErr;
       }).finally(() => {
         this.refreshTokenPromise = null;
       });
@@ -360,6 +376,9 @@ class AIChatClient {
       }
       return result;
     } catch (error) {
+      if (error && error._authExpired) {
+        return this.createError(ERROR_CODES.AUTH_FAILED, error.message || '登录已过期，请重新登录');
+      }
       if (error && error.name === 'AbortError') {
         return this.createError(ERROR_CODES.TIMEOUT_ERROR, '请求超时，请稍后重试');
       }
@@ -454,6 +473,11 @@ class AIChatClient {
     try {
       return await this.executeMessageStream(prompt, handlers, options, false);
     } catch (error) {
+      if (error && error._authExpired) {
+        const message = error.message || '登录已过期，请重新登录';
+        handlers.onError?.(message, error);
+        return this.createError(ERROR_CODES.AUTH_FAILED, message);
+      }
       if (error && error.name === 'AbortError') {
         const message = '请求超时或已取消';
         handlers.onError?.(message, error.sseData || error);
@@ -3598,7 +3622,7 @@ class AIChatDialog extends HTMLElement {
       tokenRefreshBufferMs: 60000,
       refreshTokenFn: null,
       onTokenRefreshed: null,
-      onTokenExpired: null,
+      onAuthExpired: null,
       authErrorCodes: [],
       title: 'AI 助手',
       welcomeText: 'Hi，我是智能助手 ~\n欢迎随时提问',
@@ -3634,6 +3658,8 @@ class AIChatDialog extends HTMLElement {
       debug: false,
       // P4: 自定义消息操作按钮 — 返回数组 [{label, className?, onClick}] 在 AI 消息下方渲染
       onMessageActions: null,
+      // P5: 浮窗按钮显隐控制 — false 时浮窗按钮隐藏，对话框只能通过 API 打开（登录页等场景）
+      floatButton: true,
       suggestions: [{
         label: '帮我购买一台轻量应用服务器用于部署应用',
         value: '帮我购买一台轻量应用服务器用于部署应用'
@@ -3647,6 +3673,7 @@ class AIChatDialog extends HTMLElement {
     this._chatClient = new AIChatClient(this._config);
     if (this._conversationId) this._chatClient.setConversationId(this._conversationId);
     this.applyConfig();
+    this.setFloatButtonVisible(this._config.floatButton !== false);
     // P1-2 fix: 在 _config 就绪后初始化拖拽，以正确读取 enableDrag
     if (this._config?.enableDrag !== false && this.getAttribute('mode') !== 'inline' && !this._dragInitialized) {
       this.initDraggable();
@@ -3683,6 +3710,21 @@ class AIChatDialog extends HTMLElement {
     if (this._chatClient) this._chatClient.dispose();
     if (this.parentNode) this.parentNode.removeChild(this);
   }
+  // P5: 运行时动态控制浮窗按钮显隐（SPA 路由切换场景：登录页隐藏，业务页显示）
+  setFloatButtonVisible(show) {
+    if (!this._config) this.init({
+      floatButton: show
+    });else this._config.floatButton = show;
+    const btn = this.shadowRoot?.querySelector('.float-button');
+    if (btn) {
+      const dialog = this.shadowRoot?.querySelector('.ai-chat-dialog');
+      const isOpen = dialog?.classList.contains('dialog-visible');
+      if (!isOpen) {
+        btn.style.display = show ? 'flex' : 'none';
+      }
+    }
+    return this;
+  }
   addMessage(message) {
     if (!message || !message.content) return this;
     const msg = {
@@ -3725,6 +3767,7 @@ class AIChatDialog extends HTMLElement {
       if (!this._config.appId && this._config.agentAppId) this._config.appId = this._config.agentAppId;
       if (this._chatClient) this._chatClient.updateConfig(this._config);
       this.loadAppDetail();
+      if ('floatButton' in config) this.setFloatButtonVisible(this._config.floatButton !== false);
     }
     this.applyConfig();
     return this;
@@ -3785,7 +3828,7 @@ class AIChatDialog extends HTMLElement {
     const dialog = this.shadowRoot.querySelector('.ai-chat-dialog');
     const btn = this.shadowRoot.querySelector('.float-button');
     if (dialog) dialog.classList.remove('dialog-visible');
-    if (btn) btn.style.display = 'flex';
+    if (btn) btn.style.display = this._config?.floatButton !== false ? 'flex' : 'none';
   }
   // ==================== 渲染（完整CSS对齐theme.css） ====================
   render() {
@@ -6045,7 +6088,7 @@ class AIChatDialog extends HTMLElement {
     if (!text || typeof text !== 'string') return false;
     if (text === '\n' || text === '\n\n') return false;
     const p = text.trim();
-    if (!p) return true;
+    if (!p) return false;
     return RUNTIME_PLACEHOLDERS.some(k => p.includes(k));
   }
   _isEventLike(text) {
@@ -6281,8 +6324,11 @@ class AIChatDialog extends HTMLElement {
   handleError(err) {
     let displayMsg = '抱歉，网络请求失败，请稍后重试';
     const errMsg = err?.message || '';
+    const errCode = err?.code;
     // 按错误类型分类
-    if (errMsg.includes('Failed to fetch') || errMsg.includes('NetworkError') || errMsg.includes('网络')) {
+    if (err?._authExpired || errCode === 40301) {
+      displayMsg = '登录已过期，请重新登录后再试';
+    } else if (errMsg.includes('Failed to fetch') || errMsg.includes('NetworkError') || errMsg.includes('网络')) {
       displayMsg = '网络连接失败，请检查网络后重试';
     } else if (errMsg.includes('AbortError') || errMsg.includes('超时') || errMsg.includes('timeout')) {
       displayMsg = '请求超时，请稍后重试';
@@ -6660,7 +6706,7 @@ function installVuePlugin(Vue) {
 }
 function useAIChat(options = {}) {
   if (typeof React === 'undefined') {
-    console.warn('[AI Web SDK] React is not loaded, useAIChat skipped');
+    console.warn('[AI Web SDK] React is not loaded globally — useAIChat requires React on window (CDN mode) or use the imperative createAIChatDialog() API directly');
     return {
       open: () => {},
       close: () => {},

package/dist/index.esm.js

@@ -191,12 +191,19 @@ class AIChatClient {
     silent = false
   } = {}) {
     if (typeof this.config.refreshTokenFn !== 'function') {
-      const error = new Error('Token 已过期且未配置 refreshTokenFn');
+      const authErr = new Error('Token 已过期且未配置 refreshTokenFn');
+      authErr._authExpired = true;
+      authErr._authReason = reason;
       if (!silent) {
         this.stopBackgroundRefresh();
-        this.config.onTokenExpired?.(error);
+        this.config.onAuthExpired?.({
+          reason,
+          message: authErr.message,
+          noRefreshFn: true,
+          error: authErr
+        });
       }
-      throw error;
+      throw authErr;
     }
     if (!this.refreshTokenPromise) {
       this.refreshTokenPromise = Promise.resolve().then(() => this.config.refreshTokenFn({
@@ -223,8 +230,17 @@ class AIChatClient {
           return this.config.token || '';
         }
         this.stopBackgroundRefresh();
-        this.config.onTokenExpired?.(error);
-        throw error;
+        const errMsg = error && (error.message || String(error)) || 'Token 刷新失败，请重新登录';
+        this.config.onAuthExpired?.({
+          reason,
+          message: errMsg,
+          noRefreshFn: false,
+          error
+        });
+        const authErr = new Error(errMsg);
+        authErr._authExpired = true;
+        authErr._authReason = reason;
+        throw authErr;
       }).finally(() => {
         this.refreshTokenPromise = null;
       });
@@ -356,6 +372,9 @@ class AIChatClient {
       }
       return result;
     } catch (error) {
+      if (error && error._authExpired) {
+        return this.createError(ERROR_CODES.AUTH_FAILED, error.message || '登录已过期，请重新登录');
+      }
       if (error && error.name === 'AbortError') {
         return this.createError(ERROR_CODES.TIMEOUT_ERROR, '请求超时，请稍后重试');
       }
@@ -450,6 +469,11 @@ class AIChatClient {
     try {
       return await this.executeMessageStream(prompt, handlers, options, false);
     } catch (error) {
+      if (error && error._authExpired) {
+        const message = error.message || '登录已过期，请重新登录';
+        handlers.onError?.(message, error);
+        return this.createError(ERROR_CODES.AUTH_FAILED, message);
+      }
       if (error && error.name === 'AbortError') {
         const message = '请求超时或已取消';
         handlers.onError?.(message, error.sseData || error);
@@ -3594,7 +3618,7 @@ class AIChatDialog extends HTMLElement {
       tokenRefreshBufferMs: 60000,
       refreshTokenFn: null,
       onTokenRefreshed: null,
-      onTokenExpired: null,
+      onAuthExpired: null,
       authErrorCodes: [],
       title: 'AI 助手',
       welcomeText: 'Hi，我是智能助手 ~\n欢迎随时提问',
@@ -3630,6 +3654,8 @@ class AIChatDialog extends HTMLElement {
       debug: false,
       // P4: 自定义消息操作按钮 — 返回数组 [{label, className?, onClick}] 在 AI 消息下方渲染
       onMessageActions: null,
+      // P5: 浮窗按钮显隐控制 — false 时浮窗按钮隐藏，对话框只能通过 API 打开（登录页等场景）
+      floatButton: true,
       suggestions: [{
         label: '帮我购买一台轻量应用服务器用于部署应用',
         value: '帮我购买一台轻量应用服务器用于部署应用'
@@ -3643,6 +3669,7 @@ class AIChatDialog extends HTMLElement {
     this._chatClient = new AIChatClient(this._config);
     if (this._conversationId) this._chatClient.setConversationId(this._conversationId);
     this.applyConfig();
+    this.setFloatButtonVisible(this._config.floatButton !== false);
     // P1-2 fix: 在 _config 就绪后初始化拖拽，以正确读取 enableDrag
     if (this._config?.enableDrag !== false && this.getAttribute('mode') !== 'inline' && !this._dragInitialized) {
       this.initDraggable();
@@ -3679,6 +3706,21 @@ class AIChatDialog extends HTMLElement {
     if (this._chatClient) this._chatClient.dispose();
     if (this.parentNode) this.parentNode.removeChild(this);
   }
+  // P5: 运行时动态控制浮窗按钮显隐（SPA 路由切换场景：登录页隐藏，业务页显示）
+  setFloatButtonVisible(show) {
+    if (!this._config) this.init({
+      floatButton: show
+    });else this._config.floatButton = show;
+    const btn = this.shadowRoot?.querySelector('.float-button');
+    if (btn) {
+      const dialog = this.shadowRoot?.querySelector('.ai-chat-dialog');
+      const isOpen = dialog?.classList.contains('dialog-visible');
+      if (!isOpen) {
+        btn.style.display = show ? 'flex' : 'none';
+      }
+    }
+    return this;
+  }
   addMessage(message) {
     if (!message || !message.content) return this;
     const msg = {
@@ -3721,6 +3763,7 @@ class AIChatDialog extends HTMLElement {
       if (!this._config.appId && this._config.agentAppId) this._config.appId = this._config.agentAppId;
       if (this._chatClient) this._chatClient.updateConfig(this._config);
       this.loadAppDetail();
+      if ('floatButton' in config) this.setFloatButtonVisible(this._config.floatButton !== false);
     }
     this.applyConfig();
     return this;
@@ -3781,7 +3824,7 @@ class AIChatDialog extends HTMLElement {
     const dialog = this.shadowRoot.querySelector('.ai-chat-dialog');
     const btn = this.shadowRoot.querySelector('.float-button');
     if (dialog) dialog.classList.remove('dialog-visible');
-    if (btn) btn.style.display = 'flex';
+    if (btn) btn.style.display = this._config?.floatButton !== false ? 'flex' : 'none';
   }
   // ==================== 渲染（完整CSS对齐theme.css） ====================
   render() {
@@ -6041,7 +6084,7 @@ class AIChatDialog extends HTMLElement {
     if (!text || typeof text !== 'string') return false;
     if (text === '\n' || text === '\n\n') return false;
     const p = text.trim();
-    if (!p) return true;
+    if (!p) return false;
     return RUNTIME_PLACEHOLDERS.some(k => p.includes(k));
   }
   _isEventLike(text) {
@@ -6277,8 +6320,11 @@ class AIChatDialog extends HTMLElement {
   handleError(err) {
     let displayMsg = '抱歉，网络请求失败，请稍后重试';
     const errMsg = err?.message || '';
+    const errCode = err?.code;
     // 按错误类型分类
-    if (errMsg.includes('Failed to fetch') || errMsg.includes('NetworkError') || errMsg.includes('网络')) {
+    if (err?._authExpired || errCode === 40301) {
+      displayMsg = '登录已过期，请重新登录后再试';
+    } else if (errMsg.includes('Failed to fetch') || errMsg.includes('NetworkError') || errMsg.includes('网络')) {
       displayMsg = '网络连接失败，请检查网络后重试';
     } else if (errMsg.includes('AbortError') || errMsg.includes('超时') || errMsg.includes('timeout')) {
       displayMsg = '请求超时，请稍后重试';
@@ -6656,7 +6702,7 @@ function installVuePlugin(Vue) {
 }
 function useAIChat(options = {}) {
   if (typeof React === 'undefined') {
-    console.warn('[AI Web SDK] React is not loaded, useAIChat skipped');
+    console.warn('[AI Web SDK] React is not loaded globally — useAIChat requires React on window (CDN mode) or use the imperative createAIChatDialog() API directly');
     return {
       open: () => {},
       close: () => {},

package/dist/index.umd.js

@@ -197,12 +197,19 @@
         silent = false
       } = {}) {
         if (typeof this.config.refreshTokenFn !== 'function') {
-          const error = new Error('Token 已过期且未配置 refreshTokenFn');
+          const authErr = new Error('Token 已过期且未配置 refreshTokenFn');
+          authErr._authExpired = true;
+          authErr._authReason = reason;
           if (!silent) {
             this.stopBackgroundRefresh();
-            this.config.onTokenExpired?.(error);
+            this.config.onAuthExpired?.({
+              reason,
+              message: authErr.message,
+              noRefreshFn: true,
+              error: authErr
+            });
           }
-          throw error;
+          throw authErr;
         }
         if (!this.refreshTokenPromise) {
           this.refreshTokenPromise = Promise.resolve().then(() => this.config.refreshTokenFn({
@@ -229,8 +236,17 @@
               return this.config.token || '';
             }
             this.stopBackgroundRefresh();
-            this.config.onTokenExpired?.(error);
-            throw error;
+            const errMsg = error && (error.message || String(error)) || 'Token 刷新失败，请重新登录';
+            this.config.onAuthExpired?.({
+              reason,
+              message: errMsg,
+              noRefreshFn: false,
+              error
+            });
+            const authErr = new Error(errMsg);
+            authErr._authExpired = true;
+            authErr._authReason = reason;
+            throw authErr;
           }).finally(() => {
             this.refreshTokenPromise = null;
           });
@@ -362,6 +378,9 @@
           }
           return result;
         } catch (error) {
+          if (error && error._authExpired) {
+            return this.createError(ERROR_CODES.AUTH_FAILED, error.message || '登录已过期，请重新登录');
+          }
           if (error && error.name === 'AbortError') {
             return this.createError(ERROR_CODES.TIMEOUT_ERROR, '请求超时，请稍后重试');
           }
@@ -456,6 +475,11 @@
         try {
           return await this.executeMessageStream(prompt, handlers, options, false);
         } catch (error) {
+          if (error && error._authExpired) {
+            const message = error.message || '登录已过期，请重新登录';
+            handlers.onError?.(message, error);
+            return this.createError(ERROR_CODES.AUTH_FAILED, message);
+          }
           if (error && error.name === 'AbortError') {
             const message = '请求超时或已取消';
             handlers.onError?.(message, error.sseData || error);
@@ -3600,7 +3624,7 @@ Please report this to https://github.com/markedjs/marked.`,e){let s="<p>An error
           tokenRefreshBufferMs: 60000,
           refreshTokenFn: null,
           onTokenRefreshed: null,
-          onTokenExpired: null,
+          onAuthExpired: null,
           authErrorCodes: [],
           title: 'AI 助手',
           welcomeText: 'Hi，我是智能助手 ~\n欢迎随时提问',
@@ -3636,6 +3660,8 @@ Please report this to https://github.com/markedjs/marked.`,e){let s="<p>An error
           debug: false,
           // P4: 自定义消息操作按钮 — 返回数组 [{label, className?, onClick}] 在 AI 消息下方渲染
           onMessageActions: null,
+          // P5: 浮窗按钮显隐控制 — false 时浮窗按钮隐藏，对话框只能通过 API 打开（登录页等场景）
+          floatButton: true,
           suggestions: [{
             label: '帮我购买一台轻量应用服务器用于部署应用',
             value: '帮我购买一台轻量应用服务器用于部署应用'
@@ -3649,6 +3675,7 @@ Please report this to https://github.com/markedjs/marked.`,e){let s="<p>An error
         this._chatClient = new AIChatClient(this._config);
         if (this._conversationId) this._chatClient.setConversationId(this._conversationId);
         this.applyConfig();
+        this.setFloatButtonVisible(this._config.floatButton !== false);
         // P1-2 fix: 在 _config 就绪后初始化拖拽，以正确读取 enableDrag
         if (this._config?.enableDrag !== false && this.getAttribute('mode') !== 'inline' && !this._dragInitialized) {
           this.initDraggable();
@@ -3685,6 +3712,21 @@ Please report this to https://github.com/markedjs/marked.`,e){let s="<p>An error
         if (this._chatClient) this._chatClient.dispose();
         if (this.parentNode) this.parentNode.removeChild(this);
       }
+      // P5: 运行时动态控制浮窗按钮显隐（SPA 路由切换场景：登录页隐藏，业务页显示）
+      setFloatButtonVisible(show) {
+        if (!this._config) this.init({
+          floatButton: show
+        });else this._config.floatButton = show;
+        const btn = this.shadowRoot?.querySelector('.float-button');
+        if (btn) {
+          const dialog = this.shadowRoot?.querySelector('.ai-chat-dialog');
+          const isOpen = dialog?.classList.contains('dialog-visible');
+          if (!isOpen) {
+            btn.style.display = show ? 'flex' : 'none';
+          }
+        }
+        return this;
+      }
       addMessage(message) {
         if (!message || !message.content) return this;
         const msg = {
@@ -3727,6 +3769,7 @@ Please report this to https://github.com/markedjs/marked.`,e){let s="<p>An error
           if (!this._config.appId && this._config.agentAppId) this._config.appId = this._config.agentAppId;
           if (this._chatClient) this._chatClient.updateConfig(this._config);
           this.loadAppDetail();
+          if ('floatButton' in config) this.setFloatButtonVisible(this._config.floatButton !== false);
         }
         this.applyConfig();
         return this;
@@ -3787,7 +3830,7 @@ Please report this to https://github.com/markedjs/marked.`,e){let s="<p>An error
         const dialog = this.shadowRoot.querySelector('.ai-chat-dialog');
         const btn = this.shadowRoot.querySelector('.float-button');
         if (dialog) dialog.classList.remove('dialog-visible');
-        if (btn) btn.style.display = 'flex';
+        if (btn) btn.style.display = this._config?.floatButton !== false ? 'flex' : 'none';
       }
       // ==================== 渲染（完整CSS对齐theme.css） ====================
       render() {
@@ -6047,7 +6090,7 @@ Please report this to https://github.com/markedjs/marked.`,e){let s="<p>An error
         if (!text || typeof text !== 'string') return false;
         if (text === '\n' || text === '\n\n') return false;
         const p = text.trim();
-        if (!p) return true;
+        if (!p) return false;
         return RUNTIME_PLACEHOLDERS.some(k => p.includes(k));
       }
       _isEventLike(text) {
@@ -6283,8 +6326,11 @@ Please report this to https://github.com/markedjs/marked.`,e){let s="<p>An error
       handleError(err) {
         let displayMsg = '抱歉，网络请求失败，请稍后重试';
         const errMsg = err?.message || '';
+        const errCode = err?.code;
         // 按错误类型分类
-        if (errMsg.includes('Failed to fetch') || errMsg.includes('NetworkError') || errMsg.includes('网络')) {
+        if (err?._authExpired || errCode === 40301) {
+          displayMsg = '登录已过期，请重新登录后再试';
+        } else if (errMsg.includes('Failed to fetch') || errMsg.includes('NetworkError') || errMsg.includes('网络')) {
           displayMsg = '网络连接失败，请检查网络后重试';
         } else if (errMsg.includes('AbortError') || errMsg.includes('超时') || errMsg.includes('timeout')) {
           displayMsg = '请求超时，请稍后重试';
@@ -6662,7 +6708,7 @@ Please report this to https://github.com/markedjs/marked.`,e){let s="<p>An error
     }
     function useAIChat(options = {}) {
       if (typeof React === 'undefined') {
-        console.warn('[AI Web SDK] React is not loaded, useAIChat skipped');
+        console.warn('[AI Web SDK] React is not loaded globally — useAIChat requires React on window (CDN mode) or use the imperative createAIChatDialog() API directly');
         return {
           open: () => {},
           close: () => {},