@lark-base-open/base-database-cli 1.0.0

package/templates/database-starter/page/src/components/floating-button/chatbot-entry.tsx

@@ -0,0 +1,873 @@
+import {
+  memo,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type PointerEvent as ReactPointerEvent,
+} from 'react'
+import { createPortal } from 'react-dom'
+import { getBaseDatabaseEndpointConfig } from './utils/env'
+import { LocalChatPanel } from './local-chat-panel'
+
+interface ChatbotEntryProps {
+  chatbots: ChatbotInfo[]
+  /** 绑定的 Base token，面板新建会话时通知服务端重置需要。 */
+  baseId?: string
+  className?: string
+  fallbackName: string
+  onOpenChange?: (isOpen: boolean) => void
+  onSidebarWidthChange?: (width: number) => void
+}
+
+interface ChatbotInfo {
+  id: string
+  name: string
+  iconInfo: string
+}
+
+const IMG_DEFAULT_SIZE = 120
+const RETRY_INTERVAL_TIME = 2000
+const SUCCESS_STATUS = 200
+const STATUS_TO_RETRY = [202, 204, 403]
+const SIDEBAR_DEFAULT_WIDTH = 420
+const SIDEBAR_MIN_WIDTH = 420
+const SIDEBAR_MAX_WIDTH = 720
+const SIDEBAR_VIEWPORT_MARGIN = 24
+const SIDEBAR_WIDTH_STORAGE_KEY = 'base-site.chatbot-entry.sidebar-width'
+/** 侧边栏开合状态按 chatbot 分开存：同一浏览器可能打开多个应用。 */
+const SIDEBAR_OPEN_STORAGE_PREFIX = 'base-site.chatbot-entry.open:'
+const PLACEHOLDER_CHATBOT_NAMES = new Set([
+  'untitled',
+  'untitled app',
+  'untitled chatbot',
+  'untitled site',
+  'unnamed',
+  'unnamed app',
+  'unnamed chatbot',
+  'unnamed site',
+  '未命名',
+  '未命名应用',
+  '未命名智能体',
+  '未命名站点',
+])
+
+type CoverPolicy = 'allow_up'
+
+enum ChatbotIconType {
+  Icon = 0,
+  SystemIcon = 2,
+  CustomIcon = 5,
+}
+
+interface ChatbotIconInfo {
+  key: string
+  type: ChatbotIconType
+}
+
+interface ChatbotIconProps {
+  iconInfo?: string
+  name?: string
+  className?: string
+  size?: number
+}
+
+const systemIconKeyList = [
+  'purple_baseAgentBox.png',
+  'blue_baseAgentGlasses.png',
+  'yellow_baseAgentIdea.png',
+  'pink_baseAgentGift.png',
+  'green_baseAgentSprout.png',
+  'green_baseAgentChart.png',
+  'purple_baseAgentMagic.png',
+  'pink_baseAgentCat.png',
+  'blue_baseAgentSunglasses.png',
+  'purple_baseAgentCap.png',
+  'yellow_baseAgentStar.png',
+  'green_baseAgentMagnifier.png',
+]
+
+const oldSystemIconKey = [
+  'purple_baseAgentBase.png',
+  'yellow_baseAgentChat.png',
+  'pink_baseAgentData.png',
+  'pink_baseAgentEmail.png',
+  'purple_baseAgentFile.png',
+  'blue_baseAgentSearch.png',
+  'green_baseAgentTask.png',
+  'purple_defaultBaseAgent.png',
+  'blue_emailBaseAgent.png',
+  'blue_messageBaseAgent.png',
+  'blue_notebookBaseAgent.png',
+  'green_fourLeafBaseAgent.png',
+  'green_pluginBaseAgent.png',
+  'orange_notebookBaseAgent.png',
+  'orange_starBaseAgent.png',
+  'pink_tomatoBaseAgent.png',
+  'purple_dataBaseAgent.png',
+  'white_cloudsBaseAgent.png',
+  'yellow_boxBaseAgent.png',
+]
+
+const defaultSystemIcon = systemIconKeyList[0]
+
+/** 渲染 Figma 设计中的 chatbot 浮动入口，并通过侧边栏 iframe 承载会话页。
+ *
+ * TODO(site-baseapp): 本组件仍在 Site 产物内嵌套第二层 feishu.cn iframe，
+ * 与「业务请求一律经父页面代理」的门禁冲突，属于待迁移项。目标形态是在 Site 内
+ * 直接渲染 Chatbot SDK，request / Poll 注入 base-site-channel/runtime 的 fetch，
+ * 长链注入 SiteChatbotStreamAdapter。迁移前置条件：Chatbot SDK 的 ChatbotAdapter
+ * 需先提供独立的 stream adapter 注入参数，宿主侧 StreamBroker 与 MsgBox 凭证链路就绪。
+ *
+ * @param props.chatbots 项目资源中的 chatbot 列表。
+ * @param props.className 入口按钮附加样式。
+ * @param props.fallbackName Chatbot 仍是默认占位名时使用的 Site 名称。
+ * @param props.onOpenChange 打开状态变化回调。
+ * @param props.onSidebarWidthChange 侧边栏宽度变化回调。
+ * @returns chatbot 入口按钮与打开后的侧边栏弹窗。
+ */
+export function ChatbotEntry({
+  chatbots,
+  baseId,
+  className,
+  fallbackName,
+  onOpenChange,
+  onSidebarWidthChange,
+}: ChatbotEntryProps) {
+  const chatbot = chatbots[0] ?? null
+  const [isOpen, setIsOpen] = useState(() =>
+    readStoredSidebarOpen(chatbot?.id ?? ''),
+  )
+  /** 面板挂载后不再随关闭卸载：卸载会丢掉正在跑的那一轮，重开只能从历史重建。 */
+  const [panelMounted, setPanelMounted] = useState(isOpen)
+  const [sidebarWidth, setSidebarWidth] = useState(readStoredSidebarWidth)
+  const [isResizing, setIsResizing] = useState(false)
+  const triggerRef = useRef<HTMLButtonElement>(null)
+  const panelRef = useRef<HTMLElement>(null)
+  /** 拖拽期间的实时宽度。只写 DOM 不进 state，松手才提交。 */
+  const previewWidthRef = useRef(sidebarWidth)
+  const chatbotUrl = chatbot ? buildChatbotUrl(chatbot.id) : null
+  const chatbotDisplayName = chatbot
+    ? resolveChatbotDisplayName(chatbot.name, fallbackName)
+    : ''
+
+  useEffect(() => {
+    storeSidebarWidth(sidebarWidth)
+    onSidebarWidthChange?.(sidebarWidth)
+  }, [onSidebarWidthChange, sidebarWidth])
+
+  useEffect(() => {
+    onOpenChange?.(isOpen)
+  }, [isOpen, onOpenChange])
+
+  useEffect(() => {
+    if (isOpen) {
+      setPanelMounted(true)
+    }
+    storeSidebarOpen(chatbot?.id ?? '', isOpen)
+  }, [chatbot?.id, isOpen])
+
+  /** 关闭侧边栏。必须保持引用稳定：`LocalChatPanel` 用它作为挂载依赖，
+   * 每次渲染换一个新函数会让面板卸载重挂并重新拉取会话历史。 */
+  const handleClosePanel = useCallback(() => {
+    setIsOpen(false)
+  }, [])
+
+  useEffect(() => {
+    if (!isOpen) {
+      return undefined
+    }
+
+    panelRef.current?.focus()
+
+    return () => {
+      triggerRef.current?.focus()
+    }
+  }, [isOpen])
+  useEffect(() => {
+    if (!isResizing) {
+      return undefined
+    }
+
+    const { body } = document
+    const previousCursor = body.style.cursor
+    const previousUserSelect = body.style.userSelect
+    let frameId: number | undefined
+
+    /** 每帧至多同步一次预览宽度。直接写 DOM，不经过 React。
+     *
+     * 拖拽期间 setState 会让整个入口重渲染，`LocalChatPanel` 随之重新挂载，
+     * 面板每帧重新拉一次会话历史（history/list）。预览宽度必须只落到 DOM。 */
+    function applyPreviewWidth(): void {
+      frameId = undefined
+      const panel = panelRef.current
+      if (panel) {
+        panel.style.width = `${previewWidthRef.current}px`
+      }
+    }
+
+    /** 根据指针位置计算右侧栏宽度。 */
+    function handlePointerMove(event: PointerEvent): void {
+      previewWidthRef.current = clampSidebarWidth(
+        window.innerWidth - event.clientX,
+      )
+      if (frameId === undefined) {
+        frameId = window.requestAnimationFrame(applyPreviewWidth)
+      }
+    }
+
+    /** 结束拖动，提交本轮宽度并恢复页面交互。 */
+    function handlePointerUp(): void {
+      if (frameId !== undefined) {
+        window.cancelAnimationFrame(frameId)
+        frameId = undefined
+      }
+      setSidebarWidth(previewWidthRef.current)
+      setIsResizing(false)
+    }
+
+    body.style.cursor = 'col-resize'
+    body.style.userSelect = 'none'
+    window.addEventListener('pointermove', handlePointerMove)
+    window.addEventListener('pointerup', handlePointerUp, { once: true })
+    window.addEventListener('pointercancel', handlePointerUp, { once: true })
+
+    return () => {
+      if (frameId !== undefined) {
+        window.cancelAnimationFrame(frameId)
+      }
+      body.style.cursor = previousCursor
+      body.style.userSelect = previousUserSelect
+      window.removeEventListener('pointermove', handlePointerMove)
+      window.removeEventListener('pointerup', handlePointerUp)
+      window.removeEventListener('pointercancel', handlePointerUp)
+    }
+  }, [isResizing])
+  usePageScrollLock(isOpen)
+
+  /** 启动侧边栏横向拖拽调整。
+   * @param event 拖拽手柄的 pointerdown 事件。
+   */
+  function handleResizeStart(
+    event: ReactPointerEvent<HTMLButtonElement>,
+  ): void {
+    event.preventDefault()
+    const nextWidth = clampSidebarWidth(window.innerWidth - event.clientX)
+    previewWidthRef.current = nextWidth
+    if (panelRef.current) {
+      panelRef.current.style.width = `${nextWidth}px`
+    }
+    setIsResizing(true)
+  }
+
+  if (!chatbot || !chatbotUrl) {
+    return null
+  }
+
+  return (
+    <>
+      {!isOpen ? (
+        <div className="group relative">
+          <span className="pointer-events-none absolute right-0 bottom-[calc(100%+10px)] rounded-md bg-[#1f2329] px-3 py-2 text-xs leading-5 font-normal whitespace-nowrap text-white opacity-0 shadow-[0_4px_8px_-8px_rgba(31,35,41,0.09),0_6px_12px_rgba(31,35,41,0.04),0_8px_24px_8px_rgba(31,35,41,0.04)] transition-opacity after:absolute after:right-4 after:bottom-[-4px] after:size-2 after:rotate-45 after:bg-[#1f2329] group-hover:opacity-100">
+            {chatbotDisplayName}
+          </span>
+          <button
+            ref={triggerRef}
+            type="button"
+            className={`relative m-0 flex size-12 cursor-pointer items-center justify-center overflow-hidden rounded-full border border-[#dee0e3] bg-[#cfd5ff] p-0 outline-none transition-[filter] hover:brightness-[0.98] focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 active:brightness-95 ${className ?? ''}`}
+            aria-label={`打开 ${chatbotDisplayName}`}
+            aria-haspopup="dialog"
+            aria-expanded={isOpen}
+            onClick={() => setIsOpen(true)}
+          >
+            <ChatbotIcon
+              iconInfo={chatbot.iconInfo}
+              name={chatbotDisplayName}
+              size={48}
+            />
+          </button>
+        </div>
+      ) : null}
+
+      {panelMounted
+        ? createPortal(
+            <div
+              className={`fixed inset-0 z-50 ${isOpen ? '' : 'hidden'}`}
+              aria-hidden={!isOpen}
+            >
+              <div
+                className="absolute inset-0 cursor-default bg-[#1f2329]/20"
+                aria-hidden="true"
+              />
+              <aside
+                ref={panelRef}
+                tabIndex={-1}
+                className="absolute top-0 right-0 flex h-dvh max-w-[calc(100vw-24px)] flex-col overflow-hidden border-l border-border shadow-[0_16px_48px_rgba(31,35,41,0.18)] outline-none"
+                style={{
+                  width: sidebarWidth,
+                  backgroundColor: 'var(--card, #ffffff)',
+                }}
+                role="dialog"
+                aria-modal="true"
+                aria-label="Chatbot 侧边栏"
+              >
+                <button
+                  aria-label="拖动调整 chatbot 侧边栏宽度"
+                  className="absolute top-0 bottom-0 left-0 z-10 w-2 -translate-x-1/2 cursor-col-resize touch-none border-0 bg-transparent p-0 outline-none transition-colors hover:bg-primary/15 focus-visible:bg-primary/20 focus-visible:ring-2 focus-visible:ring-primary/30 active:bg-primary/25"
+                  onPointerDown={handleResizeStart}
+                  type="button"
+                />
+                {isResizing ? (
+                  <div
+                    aria-hidden="true"
+                    className="absolute inset-0 z-[1] cursor-col-resize bg-transparent"
+                  />
+                ) : null}
+                <LocalChatPanel
+                  chatbotId={chatbot.id}
+                  chatbotName={chatbotDisplayName}
+                  chatbotCount={chatbots.length}
+                  chatbotIconUrl={getChatbotIconUrl(chatbot.iconInfo)}
+                  baseId={baseId}
+                  onClose={handleClosePanel}
+                  fallback={
+                    <iframe
+                      className="min-h-0 flex-1 border-0 bg-background"
+                      src={chatbotUrl}
+                      title={chatbotDisplayName}
+                      loading="lazy"
+                      referrerPolicy="no-referrer"
+                      allow="clipboard-read; clipboard-write"
+                    />
+                  }
+                />
+              </aside>
+            </div>,
+            document.body,
+          )
+        : null}
+    </>
+  )
+}
+
+/** 将未命名占位值替换为 Site 名称，避免浮动入口暴露无意义名称。 */
+export function resolveChatbotDisplayName(
+  chatbotName: string,
+  fallbackName: string,
+): string {
+  const normalizedChatbotName = chatbotName.trim()
+  if (
+    normalizedChatbotName &&
+    !PLACEHOLDER_CHATBOT_NAMES.has(normalizedChatbotName.toLowerCase())
+  ) {
+    return normalizedChatbotName
+  }
+
+  return fallbackName.trim()
+}
+
+/** 在弹窗打开时锁定页面滚动，关闭后恢复原滚动位置。
+ * @param isLocked 是否需要锁定页面滚动。
+ */
+function usePageScrollLock(isLocked: boolean): void {
+  useEffect(() => {
+    if (!isLocked) {
+      return undefined
+    }
+
+    const { body, documentElement } = document
+    const scrollX = window.scrollX
+    const scrollY = window.scrollY
+    const previousHtmlOverflow = documentElement.style.overflow
+    const previousBodyOverflow = body.style.overflow
+    const previousBodyPosition = body.style.position
+    const previousBodyTop = body.style.top
+    const previousBodyWidth = body.style.width
+
+    // 固定 body 可以避免部分内嵌运行时仍把滚动传递到底层页面。
+    documentElement.style.overflow = 'hidden'
+    body.style.overflow = 'hidden'
+    body.style.position = 'fixed'
+    body.style.top = `-${scrollY}px`
+    body.style.width = '100%'
+
+    return () => {
+      documentElement.style.overflow = previousHtmlOverflow
+      body.style.overflow = previousBodyOverflow
+      body.style.position = previousBodyPosition
+      body.style.top = previousBodyTop
+      body.style.width = previousBodyWidth
+      window.scrollTo({ left: scrollX, top: scrollY })
+    }
+  }, [isLocked])
+}
+
+/** 将侧边栏宽度限制在可用视口范围内。
+ * @param width 拖拽计算出的目标宽度。
+ * @returns 经过最小值、最大值和视口边距约束后的宽度。
+ */
+function clampSidebarWidth(width: number): number {
+  const viewportMaxWidth = Math.max(
+    SIDEBAR_MIN_WIDTH,
+    window.innerWidth - SIDEBAR_VIEWPORT_MARGIN,
+  )
+  const maxWidth = Math.min(SIDEBAR_MAX_WIDTH, viewportMaxWidth)
+
+  return Math.min(Math.max(width, SIDEBAR_MIN_WIDTH), maxWidth)
+}
+
+/** 读取本地保存的侧边栏宽度。
+ * @returns 合法宽度；不存在或异常时返回默认宽度。
+ */
+function readStoredSidebarWidth(): number {
+  if (typeof window === 'undefined') {
+    return SIDEBAR_DEFAULT_WIDTH
+  }
+
+  let storedValue: string | null = null
+  try {
+    storedValue = window.localStorage.getItem(SIDEBAR_WIDTH_STORAGE_KEY)
+  } catch {
+    return SIDEBAR_DEFAULT_WIDTH
+  }
+
+  const parsedWidth = storedValue ? Number(storedValue) : Number.NaN
+  return Number.isFinite(parsedWidth)
+    ? clampSidebarWidth(parsedWidth)
+    : SIDEBAR_DEFAULT_WIDTH
+}
+
+/** 读取侧边栏是否处于打开状态。
+ * @param chatbotId 当前 chatbot 标识。
+ * @returns 上次离开时侧边栏是否打开；读不到时按关闭处理。
+ */
+function readStoredSidebarOpen(chatbotId: string): boolean {
+  if (typeof window === 'undefined' || !chatbotId) {
+    return false
+  }
+
+  try {
+    return (
+      window.localStorage.getItem(
+        `${SIDEBAR_OPEN_STORAGE_PREFIX}${chatbotId}`,
+      ) === '1'
+    )
+  } catch {
+    return false
+  }
+}
+
+/** 保存侧边栏开合状态，供刷新后恢复。
+ * @param chatbotId 当前 chatbot 标识。
+ * @param isOpen 侧边栏是否打开。
+ */
+function storeSidebarOpen(chatbotId: string, isOpen: boolean): void {
+  if (typeof window === 'undefined' || !chatbotId) {
+    return
+  }
+
+  try {
+    const key = `${SIDEBAR_OPEN_STORAGE_PREFIX}${chatbotId}`
+    if (isOpen) {
+      window.localStorage.setItem(key, '1')
+    } else {
+      window.localStorage.removeItem(key)
+    }
+  } catch {
+    // 本地存储不可用时不影响侧边栏本身的开合。
+  }
+}
+
+/** 保存侧边栏宽度，供刷新或重新进入页面时恢复。
+ * @param width 当前侧边栏宽度。
+ */
+function storeSidebarWidth(width: number): void {
+  if (typeof window === 'undefined') {
+    return
+  }
+
+  try {
+    window.localStorage.setItem(SIDEBAR_WIDTH_STORAGE_KEY, String(width))
+  } catch {
+    // 本地存储不可用时保持本次会话内的宽度状态即可。
+  }
+}
+
+/** 拼接 chatbot iframe 地址。
+ * @param chatId chatbot id。
+ * @returns iframe 加载地址。
+ */
+function buildChatbotUrl(chatId: string): string {
+  const { chatbotOrigin } = getBaseDatabaseEndpointConfig()
+
+  return (
+    `${chatbotOrigin}/base/agent/${encodeURIComponent(chatId)}` +
+    `?readonly=true&hideCreate=1&hideHeader=true`
+  )
+}
+
+/** 判断输入是否为普通对象。
+ * @param value 待判断的数据。
+ * @returns 是普通对象时返回 true。
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** 读取固定的系统图标 CDN 前缀。
+ * @returns 系统图标资源前缀。
+ */
+function getCustomIconUri(): string {
+  return getBaseDatabaseEndpointConfig().customIconUri
+}
+
+/** 获取默认系统图标地址。
+ * @returns 默认 chatbot 系统图标地址。
+ */
+function getDefaultSystemIconUrl(): string {
+  return getSystemIconUrl(defaultSystemIcon)
+}
+
+/** 拼接系统图标地址。
+ * @param key 系统图标 key。
+ * @returns 系统图标完整地址。
+ */
+function getSystemIconUrl(key: string): string {
+  return new URL(key, getCustomIconUri()).toString()
+}
+
+/** 解析 chatbot iconInfo。
+ * @param iconStr iconInfo JSON 字符串。
+ * @returns 解析后的图标信息；结构异常时返回 null。
+ */
+function parseChatbotIconInfo(iconStr: string): ChatbotIconInfo | null {
+  try {
+    const iconInfo: unknown = JSON.parse(iconStr)
+    if (!isRecord(iconInfo)) {
+      return null
+    }
+
+    const { key, type } = iconInfo
+    if (
+      typeof key !== 'string' ||
+      (type !== ChatbotIconType.Icon &&
+        type !== ChatbotIconType.SystemIcon &&
+        type !== ChatbotIconType.CustomIcon)
+    ) {
+      return null
+    }
+
+    return {
+      key,
+      type,
+    }
+  } catch {
+    return null
+  }
+}
+
+/** 获取自定义上传图标地址。
+ * @param iconInfo 解析后的图标信息。
+ * @returns 自定义上传图标的 Drive cover 地址。
+ */
+function getCustomIconUrl(iconInfo: ChatbotIconInfo): string {
+  const { type, key } = iconInfo
+  if (type !== ChatbotIconType.CustomIcon || !key) {
+    return ''
+  }
+
+  return getDriveImageUrl(key, {
+    width: IMG_DEFAULT_SIZE,
+    height: IMG_DEFAULT_SIZE,
+    policy: 'allow_up',
+    fallback_source: 1,
+  })
+}
+
+interface CoverOptions {
+  width?: number
+  height?: number
+  policy?: CoverPolicy
+  fallback_source?: number
+}
+
+/** 序列化 URL 查询参数，跳过空值。
+ * @param params 查询参数对象。
+ * @returns 带问号的查询字符串；没有有效参数时返回空字符串。
+ */
+function formatQuery(
+  params: Record<string, string | number | undefined>,
+): string {
+  const searchParams = new URLSearchParams()
+
+  Object.entries(params).forEach(([key, value]) => {
+    if (value === undefined || value === '') {
+      return
+    }
+
+    searchParams.set(key, String(value))
+  })
+
+  const queryString = searchParams.toString()
+  return queryString ? `?${queryString}` : ''
+}
+
+/** 按 bear-web 规则生成 Base Chatbot 自定义图标 cover 地址。
+ * @param fileToken 自定义上传图标 token。
+ * @param coverOptions cover 裁剪参数。
+ * @returns Drive cover 下载地址。
+ */
+function getDriveImageUrl(
+  fileToken: string,
+  coverOptions: CoverOptions,
+): string {
+  if (!fileToken) {
+    return ''
+  }
+
+  const { driveStreamOrigin } = getBaseDatabaseEndpointConfig()
+  const baseUrl =
+    `${driveStreamOrigin}/space/api/box/stream/download/v2/cover/` +
+    `${encodeURIComponent(fileToken)}/`
+
+  return (
+    baseUrl +
+    formatQuery({
+      mount_node_token: fileToken,
+      mount_point: 'base_chatbot',
+      width: coverOptions.width,
+      height: coverOptions.height,
+      policy: coverOptions.policy,
+      fallback_source: coverOptions.fallback_source,
+    })
+  )
+}
+
+/** 带重试地请求自定义图标资源。
+ * @param url 图标资源地址。
+ * @param maxRetry 最大重试次数。
+ * @param retryInterval 初始重试间隔。
+ * @returns 图标资源响应。
+ */
+async function fetchCoverWithRetry(
+  url: string,
+  maxRetry = 6,
+  retryInterval = RETRY_INTERVAL_TIME,
+): Promise<Response> {
+  let retryTime = 0
+
+  async function doFetch(interval: number): Promise<Response> {
+    const response = await fetch(url, { credentials: 'include' })
+    const { status } = response
+
+    if (status === SUCCESS_STATUS) {
+      return response
+    }
+
+    if (STATUS_TO_RETRY.includes(status) && retryTime < maxRetry) {
+      retryTime += 1
+      await new Promise((resolve) => {
+        setTimeout(resolve, interval)
+      })
+      return doFetch(retryTime === 1 ? interval : interval * 2)
+    }
+
+    throw new Error(`Fetch cover failed with status ${status}`)
+  }
+
+  return doFetch(retryInterval)
+}
+
+/** 获取自定义图标 blob 地址，失败时降级获取原 cover。
+ * @param token 自定义上传图标 token。
+ * @returns 可供 img 使用的 blob URL。
+ */
+async function fetchCoverWithFallback(token: string): Promise<string> {
+  try {
+    const coverUrl = getCustomIconUrl({
+      key: token,
+      type: ChatbotIconType.CustomIcon,
+    })
+    const coverRes = await fetchCoverWithRetry(coverUrl, 2, RETRY_INTERVAL_TIME)
+    const blob = await coverRes.blob()
+    return URL.createObjectURL(blob)
+  } catch {
+    const imageUrl = getDriveImageUrl(token, {
+      policy: 'allow_up',
+      fallback_source: 1,
+    })
+    const imgRes = await fetchCoverWithRetry(imageUrl, 3, RETRY_INTERVAL_TIME)
+    const imgBlob = await imgRes.blob()
+    return URL.createObjectURL(imgBlob)
+  }
+}
+
+/** 管理自定义图标 blob URL 缓存，复用并发请求。
+ * @returns 自定义图标缓存管理器实例。
+ */
+class ChatbotIconBlobUrlCache {
+  private readonly blobUrlCache = new Map<string, string>()
+
+  private readonly fetchingPromiseCache = new Map<string, Promise<string>>()
+
+  /** 获取自定义上传图标 blob URL。
+   * @param token 自定义上传图标 token。
+   * @returns 可供 img 使用的 blob URL。
+   */
+  fetch(token: string): Promise<string> {
+    const cachedBlobUrl = this.blobUrlCache.get(token)
+    if (cachedBlobUrl) {
+      return Promise.resolve(cachedBlobUrl)
+    }
+
+    const fetchingPromise = this.fetchingPromiseCache.get(token)
+    if (fetchingPromise) {
+      return fetchingPromise
+    }
+
+    const promise = fetchCoverWithFallback(token)
+      .then((blobUrl) => {
+        this.blobUrlCache.set(token, blobUrl)
+        return blobUrl
+      })
+      .finally(() => {
+        this.fetchingPromiseCache.delete(token)
+      })
+
+    this.fetchingPromiseCache.set(token, promise)
+    return promise
+  }
+
+  /** 读取已缓存的自定义上传图标 blob URL。
+   * @param token 自定义上传图标 token。
+   * @returns 已缓存的 blob URL。
+   */
+  get(token: string): string | undefined {
+    return this.blobUrlCache.get(token)
+  }
+
+  /** 清理自定义上传图标缓存。
+   * @param token 指定 token；不传则清空全部缓存。
+   */
+  clear(token?: string): void {
+    if (token) {
+      const blobUrl = this.blobUrlCache.get(token)
+      if (blobUrl) {
+        URL.revokeObjectURL(blobUrl)
+      }
+
+      this.blobUrlCache.delete(token)
+      this.fetchingPromiseCache.delete(token)
+      return
+    }
+
+    this.blobUrlCache.forEach((blobUrl) => {
+      URL.revokeObjectURL(blobUrl)
+    })
+    this.blobUrlCache.clear()
+    this.fetchingPromiseCache.clear()
+  }
+}
+
+const chatbotIconBlobUrlManager = new ChatbotIconBlobUrlCache()
+
+/** 根据 iconInfo 获取 chatbot 图标地址。
+ * @param iconStr iconInfo JSON 字符串。
+ * @returns 可用于 img 的图标地址。
+ */
+function getChatbotIconUrl(iconStr: string): string {
+  const iconInfo = parseChatbotIconInfo(iconStr)
+  if (!iconInfo) {
+    return getDefaultSystemIconUrl()
+  }
+
+  const customIconUrl = getCustomIconUrl(iconInfo)
+  if (customIconUrl) {
+    return customIconUrl
+  }
+
+  if (
+    iconInfo.type === ChatbotIconType.SystemIcon &&
+    (systemIconKeyList.includes(iconInfo.key) ||
+      oldSystemIconKey.includes(iconInfo.key))
+  ) {
+    return getSystemIconUrl(iconInfo.key)
+  }
+
+  return getDefaultSystemIconUrl()
+}
+
+/** 渲染 chatbot 图标。
+ * @param props.iconInfo chatbot iconInfo JSON 字符串。
+ * @param props.name chatbot 名称，用于图片 alt。
+ * @param props.className 图标容器附加类名。
+ * @param props.size 图标尺寸。
+ * @returns chatbot 图标节点。
+ */
+const ChatbotIcon = memo(
+  ({ iconInfo, name, className, size = 18 }: ChatbotIconProps) => {
+    const style = { width: size, height: size }
+    const [hasError, setHasError] = useState(false)
+    const [iconBlobUrl, setIconBlobUrl] = useState('')
+
+    useEffect(() => {
+      let isCurrentRequest = true
+      setHasError(false)
+      if (!iconInfo) {
+        setIconBlobUrl(getDefaultSystemIconUrl())
+        return () => {
+          isCurrentRequest = false
+        }
+      }
+
+      const iconInfoObj = parseChatbotIconInfo(iconInfo)
+      if (iconInfoObj?.type === ChatbotIconType.CustomIcon) {
+        chatbotIconBlobUrlManager
+          .fetch(iconInfoObj.key)
+          .then((coverUrl) => {
+            if (!isCurrentRequest) {
+              return
+            }
+
+            setIconBlobUrl(coverUrl)
+          })
+          .catch(() => {
+            if (!isCurrentRequest) {
+              return
+            }
+
+            setHasError(true)
+            setIconBlobUrl(getDefaultSystemIconUrl())
+          })
+        return () => {
+          isCurrentRequest = false
+        }
+      }
+
+      setIconBlobUrl(getChatbotIconUrl(iconInfo))
+      return () => {
+        isCurrentRequest = false
+      }
+    }, [iconInfo])
+
+    if (!iconBlobUrl) {
+      return null
+    }
+
+    return (
+      <span
+        className={`m-0 inline-flex shrink-0 items-center justify-center overflow-hidden rounded-full p-0 ${className ?? ''}`}
+        style={style}
+      >
+        <img
+          className="h-full w-full object-cover"
+          src={hasError ? getDefaultSystemIconUrl() : iconBlobUrl}
+          alt={name}
+          onError={() => setHasError(true)}
+        />
+      </span>
+    )
+  },
+)
+
+ChatbotIcon.displayName = 'ChatbotIcon'