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

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

@@ -0,0 +1,196 @@
+import { useCallback, useEffect, useState } from 'react'
+import { fetchProjectMeta, type ProjectMeta } from './utils/project-meta'
+import { ChatbotEntry, resolveChatbotDisplayName } from './chatbot-entry'
+import {
+  getDatabaseContext,
+  resolveDatabaseContext,
+  siteRuntime,
+} from '../../lib/database-runtime'
+
+export type FloatingButtonLanguage = 'en' | 'zh'
+
+interface FloatingButtonProps {
+  language?: FloatingButtonLanguage
+  showChatbotEntry?: boolean
+}
+
+interface FloatingButtonI18n {
+  editSite: string
+}
+
+const BASE_DATABASE_OVERVIEW_URL = 'https://feishu.cn/base/site/detail/overview'
+const CHATBOT_SIDEBAR_DEFAULT_WIDTH = 420
+const FLOATING_BUTTON_PAGE_GAP = 24
+const EMPTY_PROJECT_META: ProjectMeta = {
+  baseBindings: [],
+  chatList: [],
+  description: '',
+  isOwner: false,
+  name: '',
+  organization: '',
+}
+const FLOATING_BUTTON_I18N: Record<FloatingButtonLanguage, FloatingButtonI18n> =
+  {
+    en: {
+      editSite: 'Edit application',
+    },
+    zh: {
+      editSite: '编辑应用',
+    },
+  }
+
+/** 渲染 Base Database 悬浮按钮入口：编辑、Chatbot。
+ *
+ * 原来这里还有一个「三个点」菜单，承载当前账号 / 组织 / 退出登录。它已经下掉了：
+ * 悬浮控件是应用之外的一层浮层，用户不会去那里找账号。身份信息改由应用自己的导航
+ * 承载，见 `page/src/components/database-user-menu`。
+ *
+ * @param props.language 界面语言，支持 en 和 zh，默认 en。
+ * @param props.showChatbotEntry 是否显示 Chatbot 入口，默认 true。
+ * @returns 悬浮按钮组。
+ */
+export function FloatingButton({
+  language = 'en',
+  showChatbotEntry = true,
+}: FloatingButtonProps) {
+  const [projectMeta, setProjectMeta] = useState<ProjectMeta | null>(null)
+  const [isFloatingDataLoaded, setIsFloatingDataLoaded] = useState(false)
+  const [isChatbotOpen, setIsChatbotOpen] = useState(false)
+  const [chatbotSidebarWidth, setChatbotSidebarWidth] = useState(
+    CHATBOT_SIDEBAR_DEFAULT_WIDTH,
+  )
+  // 编辑只在线上给 owner。Preview 本身就只有 owner 进得来，isOwner 恒为 true，
+  // 靠它永远隐藏不掉，必须显式按产物环境判断。
+  const shouldShowEditButton =
+    projectMeta?.isOwner === true && getDatabaseContext().env === 'prod'
+  const shouldOffsetForChatbot = showChatbotEntry && isChatbotOpen
+  const shouldShowFloatingControls =
+    shouldShowEditButton || (showChatbotEntry && !isChatbotOpen)
+  const floatingButtonRight = shouldOffsetForChatbot
+    ? chatbotSidebarWidth + FLOATING_BUTTON_PAGE_GAP
+    : FLOATING_BUTTON_PAGE_GAP
+  const i18n = FLOATING_BUTTON_I18N[language]
+  const genericChatbotName = language === 'zh' ? '智能助手' : 'AI assistant'
+  const chatbotFallbackName = resolveChatbotDisplayName(
+    projectMeta?.name ?? '',
+    genericChatbotName,
+  )
+
+  useEffect(() => {
+    let isCurrentRequest = true
+    setIsFloatingDataLoaded(false)
+
+    /** 读取悬浮控件所需的项目资源数据。 */
+    async function loadFloatingData(): Promise<void> {
+      const nextProjectMeta = await fetchProjectMeta().catch(
+        () => EMPTY_PROJECT_META,
+      )
+
+      if (!isCurrentRequest) {
+        return
+      }
+
+      setProjectMeta(nextProjectMeta)
+      setIsFloatingDataLoaded(true)
+    }
+
+    void loadFloatingData()
+
+    return () => {
+      isCurrentRequest = false
+    }
+  }, [])
+
+  useEffect(() => {
+    if (showChatbotEntry) {
+      return
+    }
+
+    setIsChatbotOpen(false)
+  }, [showChatbotEntry])
+
+  const handleChatbotOpenChange = useCallback((nextIsOpen: boolean) => {
+    setIsChatbotOpen(nextIsOpen)
+  }, [])
+
+  // 编辑按钮走 site.v1 契约：应用发 request-edit，宿主切编辑态后广播 mode-changed。
+  // 应用被独立访问（无宿主）时事件无人消费，回落为打开 Site 管理页。
+  const requestEdit = useCallback(() => {
+    void siteRuntime.requestEdit().catch(async () => {
+      const { token } = await resolveDatabaseContext()
+      const url = new URL(BASE_DATABASE_OVERVIEW_URL)
+      url.searchParams.set('token', token)
+      openExternalUrl(url.toString())
+    })
+  }, [])
+
+  if (!isFloatingDataLoaded || !projectMeta) {
+    return null
+  }
+
+  return (
+    <div
+      className={`fixed bottom-10 flex items-center pr-0 ${shouldOffsetForChatbot ? 'z-[80]' : 'z-40'}`}
+      style={{ right: floatingButtonRight }}
+    >
+      <div
+        className={`${shouldShowFloatingControls ? 'relative z-[80] flex' : 'hidden'} items-center gap-1.5 rounded-full bg-white p-0.5 shadow-[0_4px_4px_rgba(31,35,41,0.06),0_6px_6px_rgba(31,35,41,0.04),0_8px_12px_rgba(31,35,41,0.04)]`}
+        data-floating-controls="true"
+      >
+        {shouldShowEditButton ? (
+          <button
+            type="button"
+            aria-label={i18n.editSite}
+            title={i18n.editSite}
+            className="flex size-12 cursor-pointer items-center justify-center rounded-full bg-transparent text-[#2b2f36] outline-none transition-colors hover:bg-[#1f2329]/5 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 active:bg-[#1f2329]/10"
+            onClick={requestEdit}
+          >
+            <EditIcon />
+          </button>
+        ) : null}
+
+        {showChatbotEntry ? (
+          <ChatbotEntry
+            chatbots={projectMeta.chatList}
+            baseId={projectMeta.baseBindings[0]?.baseToken}
+            className="shrink-0"
+            fallbackName={chatbotFallbackName}
+            onOpenChange={handleChatbotOpenChange}
+            onSidebarWidthChange={setChatbotSidebarWidth}
+          />
+        ) : null}
+      </div>
+    </div>
+  )
+}
+
+/** 使用新标签页打开外部链接。
+ * @param url 待打开的外部链接。
+ */
+function openExternalUrl(url: string): void {
+  window.open(url, '_blank', 'noopener,noreferrer')
+}
+
+/** 编辑应用图标。
+ * @returns 铅笔图标节点。
+ */
+function EditIcon() {
+  return (
+    <svg
+      aria-hidden="true"
+      width="20"
+      height="20"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M12 20h9" />
+      <path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4Z" />
+    </svg>
+  )
+}
+
+export default FloatingButton

package/templates/database-starter/page/src/components/floating-button/local-chat-panel.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+import { resolvePanelSessionKey } from './local-chat-panel'
+
+describe('resolvePanelSessionKey', () => {
+  it('只由 chatbotId 决定会话身份', () => {
+    expect(resolvePanelSessionKey({ chatbotId: 'cb-1' })).toBe('cb-1')
+    expect(resolvePanelSessionKey({ chatbotId: 'cb-2' })).not.toBe(
+      resolvePanelSessionKey({ chatbotId: 'cb-1' }),
+    )
+  })
+
+  // 回归：拖拽侧边栏时父组件每帧重渲染，展示属性（含每次新建的 onClose）
+  // 若进入挂载依赖，面板会逐帧 unmount + mount 并重复拉取 history/list。
+  it('展示属性变化不改变会话身份', () => {
+    const base = resolvePanelSessionKey({ chatbotId: 'cb-1' })
+    const withOtherDisplayProps = resolvePanelSessionKey({
+      chatbotId: 'cb-1',
+      chatbotName: '换了名字',
+      chatbotIconUrl: 'https://example.com/other.png',
+      baseId: 'base-token',
+      onClose: () => undefined,
+    } as { chatbotId: string })
+    expect(withOtherDisplayProps).toBe(base)
+  })
+})

package/templates/database-starter/page/src/components/floating-button/local-chat-panel.tsx

@@ -0,0 +1,197 @@
+import React, { useEffect, useRef, useState } from 'react'
+import { getDatabaseContext } from '../../lib/database-runtime'
+
+/** 面板 IIFE 产物暴露的全局挂载接口（base-site-chat-panel 包）。 */
+interface ChatPanelMountProps {
+  projectId: string
+  chatbotId?: string
+  chatbotName?: string
+  chatbotCount?: number
+  /** chatbot 自己的图标地址，面板 header 与欢迎页使用。 */
+  chatbotIconUrl?: string
+  /** 绑定的 Base token，面板新建会话时通知服务端重置需要。 */
+  baseId?: string
+  /** 面板 header 的关闭按钮回调（Figma 95-195885 右上角功能区）。 */
+  onClose?: () => void
+}
+
+interface ChatPanelSdk {
+  mount: (container: Element, props: ChatPanelMountProps) => void
+  /** 就地更新展示属性，不重建会话。旧版本产物可能没有这个方法。 */
+  update?: (container: Element, props: ChatPanelMountProps) => void
+  unmount: (container: Element) => void
+}
+
+declare global {
+  interface Window {
+    __SITE_CHATBOT_SDK__?: ChatPanelSdk
+  }
+}
+
+/** 面板产物（base-site-chat-panel）的 CDN 目录。
+ *
+ * 面板包按「构建产物发 CDN + 应用静态引用」分发：产物一份托管在 Eden CDN 的
+ * base-site 团队空间，所有应用共享，应用 Artifact 不再携带 ~4MB 产物。
+ * 更新产物时上传到新的版本目录并同步修改此常量。 */
+const PANEL_CDN_BASE =
+  'https://lf3-static.bytednsdoc.com/obj/eden-cn/lapz-lzhi/ljhwZthlaukjlkulzlp/base-site-chat-panel/0.0.1-alpha.45'
+
+let sdkPromise: Promise<ChatPanelSdk | null> | null = null
+
+/** 惰性加载面板产物。
+ *
+ * 面板自带 React 18 与全部 chatbot-sdk 依赖（隔离 bundle），应用只提供容器 DOM；
+ * 产物统一从 CDN 加载，所有应用共享同一份，与应用自身的托管路径无关。
+ */
+function loadChatPanelSdk(): Promise<ChatPanelSdk | null> {
+  if (window.__SITE_CHATBOT_SDK__) {
+    return Promise.resolve(window.__SITE_CHATBOT_SDK__)
+  }
+  if (!sdkPromise) {
+    sdkPromise = new Promise((resolve) => {
+      const stylesheet = document.createElement('link')
+      stylesheet.rel = 'stylesheet'
+      stylesheet.href = `${PANEL_CDN_BASE}/panel.css`
+      document.head.append(stylesheet)
+
+      const script = document.createElement('script')
+      script.src = `${PANEL_CDN_BASE}/panel.js`
+      script.onload = () => resolve(window.__SITE_CHATBOT_SDK__ ?? null)
+      script.onerror = () => resolve(null)
+      document.head.append(script)
+    })
+  }
+  return sdkPromise
+}
+
+interface LocalChatPanelProps {
+  chatbotId: string
+  chatbotName: string
+  /** 应用一共绑定了几个 chatbot。面板据此决定名称右边要不要出切换三角。 */
+  chatbotCount?: number
+  /** 面板产物缺失或加载失败时的回落渲染（如旧版 agent 页 iframe）。 */
+  fallback?: React.ReactNode
+  /** chatbot 自己的图标地址（由 iconInfo 解析）。 */
+  chatbotIconUrl?: string
+  /** 绑定的 Base token（projectMeta.baseBindings[0].baseToken）。 */
+  baseId?: string
+  /** 关闭侧边栏。面板 header 的关闭按钮会调用它（Figma 95-195885）。 */
+  onClose?: () => void
+}
+
+/** 面板会话身份。只有它变化才需要卸载重挂面板。
+ *
+ * 名称、图标、baseId、onClose 属于展示属性，一律不参与 —— 把它们放进挂载
+ * effect 的依赖会让父组件每次重渲染都重建面板，会话历史随之重新拉取一遍。
+ * @param props 当前面板属性。
+ * @returns 用作挂载 effect 唯一依赖的会话身份字符串。
+ */
+export function resolvePanelSessionKey(props: { chatbotId: string }): string {
+  return props.chatbotId
+}
+
+/** 应用内本地化对话面板：加载隔离 bundle 并挂载到容器。
+ *
+ * 产物来源：ai-friendly-base-site/engineering/base-site-chat-panel 的 dist/panel.{js,css}，
+ * 构建后上传到 Eden CDN 的 base-site 团队空间。加载失败时按 fallback 渲染。
+ *
+ * 会话请求与轮询由面板经 site.v1 Runtime 走父页面同源代发；应用被独立访问
+ * （无宿主）时面板自行回落 BFF 纯文本模式，本组件不感知传输细节。
+ */
+export function LocalChatPanel({
+  chatbotId,
+  chatbotName,
+  chatbotCount = 1,
+  chatbotIconUrl,
+  baseId,
+  fallback,
+  onClose,
+}: LocalChatPanelProps) {
+  const containerRef = useRef<HTMLDivElement>(null)
+  const [loadFailed, setLoadFailed] = useState(false)
+  const sessionKey = resolvePanelSessionKey({ chatbotId })
+
+  // 面板挂载后靠 ref 读取最新展示属性。挂载 effect 只认 sessionKey，
+  // 展示属性的引用变化不会 unmount + mount 面板，会话历史也就不会重拉
+  // （典型触发：侧边栏拖拽时父组件每帧重渲染）。
+  const displayPropsRef = useRef({
+    chatbotName,
+    chatbotCount,
+    chatbotIconUrl,
+    baseId,
+  })
+  displayPropsRef.current = {
+    chatbotName,
+    chatbotCount,
+    chatbotIconUrl,
+    baseId,
+  }
+  const onCloseRef = useRef(onClose)
+  onCloseRef.current = onClose
+
+  useEffect(() => {
+    const container = containerRef.current
+    if (!container) {
+      return undefined
+    }
+
+    let disposed = false
+    void loadChatPanelSdk().then((sdk) => {
+      if (disposed) {
+        return
+      }
+      if (!sdk) {
+        setLoadFailed(true)
+        return
+      }
+      sdk.mount(container, {
+        projectId: getDatabaseContext().token,
+        chatbotId: sessionKey,
+        ...displayPropsRef.current,
+        onClose: () => onCloseRef.current?.(),
+      })
+    })
+
+    return () => {
+      disposed = true
+      window.__SITE_CHATBOT_SDK__?.unmount(container)
+    }
+  }, [sessionKey])
+
+  // 展示属性（名称、图标、baseId）晚到时就地更新，不重建会话。
+  useEffect(() => {
+    const container = containerRef.current
+    const sdk = window.__SITE_CHATBOT_SDK__
+    if (!container || !sdk?.update) {
+      return
+    }
+    sdk.update(container, {
+      projectId: getDatabaseContext().token,
+      chatbotId,
+      chatbotName,
+      chatbotCount,
+      chatbotIconUrl,
+      baseId,
+      onClose: () => onCloseRef.current?.(),
+    })
+  }, [chatbotId, chatbotName, chatbotCount, chatbotIconUrl, baseId])
+
+  if (loadFailed) {
+    return (
+      fallback ?? (
+        <div className="flex min-h-0 flex-1 items-center justify-center text-sm text-muted-foreground">
+          对话面板加载失败，请刷新页面重试
+        </div>
+      )
+    )
+  }
+
+  // 面板根节点 .site-chat-root 是 flex:1，挂载容器必须自己是有界高度的 flex column，
+  // 否则消息列表按内容自然高度撑开、输入框被顶出视口。
+  return (
+    <div
+      ref={containerRef}
+      className="flex min-h-0 flex-1 flex-col overflow-hidden"
+    />
+  )
+}

package/templates/database-starter/page/src/components/floating-button/utils/current-user.ts

@@ -0,0 +1,56 @@
+import {
+  fetch as siteRuntimeFetch,
+  getCurrentUser,
+} from '../../../lib/database-runtime'
+
+/** 浮层菜单展示用的当前登录用户信息。 */
+export interface CurrentUser {
+  name: string
+  avatarUrl: string
+  /** 组织名。协议的 getCurrentUser 不含该字段，仅宿主用户接口回落路径提供。 */
+  tenantName: string
+}
+
+/** 读取当前登录用户的展示信息。
+ *
+ * 优先走协议内置 Runtime Function（function.runtime.getCurrentUser，Host 固定分发）；
+ * 旧版宿主未实现时回落父页面代理的 /space/api/user/。两条路都不可用（如应用被
+ * 独立访问）时返回 null，菜单退化为只展示组织名。
+ */
+export async function fetchCurrentUser(): Promise<CurrentUser | null> {
+  try {
+    // 内置 Runtime Function（对齐 MR 29）：协议保证 name / avatarUrl 稳定存在。
+    const user = await getCurrentUser()
+    if (typeof user?.name === 'string' && user.name) {
+      return {
+        name: user.name,
+        avatarUrl: typeof user.avatarUrl === 'string' ? user.avatarUrl : '',
+        tenantName: '',
+      }
+    }
+  } catch {
+    // 继续走宿主用户接口回落
+  }
+  try {
+    const response = await siteRuntimeFetch('/space/api/user/', {
+      headers: { accept: 'application/json' },
+    })
+    if (!response.ok) {
+      return null
+    }
+    const body = (await response.json()) as {
+      data?: { name?: unknown; avatar_url?: unknown; tenant_name?: unknown }
+    }
+    const data = body.data
+    if (!data || typeof data.name !== 'string' || !data.name) {
+      return null
+    }
+    return {
+      name: data.name,
+      avatarUrl: typeof data.avatar_url === 'string' ? data.avatar_url : '',
+      tenantName: typeof data.tenant_name === 'string' ? data.tenant_name : '',
+    }
+  } catch {
+    return null
+  }
+}

package/templates/database-starter/page/src/components/floating-button/utils/env.ts

@@ -0,0 +1,18 @@
+export interface BaseDatabaseEndpointConfig {
+  chatbotOrigin: string
+  customIconUri: string
+  driveStreamOrigin: string
+}
+
+// 仅剩 Chatbot 第二层 iframe 与其图标资源仍依赖这些外部域名，
+// 业务 HTTP 一律经父页面代理，不再配置 OpenAPI 直连域名。
+const ONLINE_ENDPOINT_CONFIG: BaseDatabaseEndpointConfig = {
+  chatbotOrigin: 'https://feishu.cn',
+  customIconUri: 'https://sf1-scmcdn-cn.feishucdn.com/obj/lark-reaction-cn/',
+  driveStreamOrigin: 'https://internal-api-drive-stream.feishu.cn',
+}
+
+/** 读取 Base Database 线上环境的外部服务域名配置。 */
+export function getBaseDatabaseEndpointConfig(): BaseDatabaseEndpointConfig {
+  return ONLINE_ENDPOINT_CONFIG
+}

package/templates/database-starter/page/src/components/floating-button/utils/project-meta.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import { parseProjectMetaResponse } from './project-meta'
+
+function projectResponse(isOwner: unknown) {
+  return {
+    code: 0,
+    data: {
+      isOwner,
+      site: {
+        baseBindings: [],
+        chatbots: [],
+        description: 'Owner visibility test',
+        name: 'Owner visibility test',
+      },
+    },
+  }
+}
+
+describe('project owner visibility', () => {
+  it('uses the backend isOwner verdict', () => {
+    expect(parseProjectMetaResponse(projectResponse(true)).isOwner).toBe(true)
+    expect(parseProjectMetaResponse(projectResponse(false)).isOwner).toBe(false)
+  })
+
+  it('fails closed when isOwner is missing or has the wrong type', () => {
+    expect(parseProjectMetaResponse(projectResponse(undefined)).isOwner).toBe(
+      false,
+    )
+    expect(parseProjectMetaResponse(projectResponse('true')).isOwner).toBe(
+      false,
+    )
+  })
+})
+
+describe('project chatbot parsing', () => {
+  // 接口的 chatbot 字段全部可选，缺字段不能连带丢掉 isOwner 与应用名称。
+  function responseWithChatbots(chatbots: unknown) {
+    return {
+      code: 0,
+      data: {
+        isOwner: true,
+        site: {
+          baseBindings: [{ baseToken: 'bascnBase', tableIds: ['tbl_a'] }],
+          chatbots,
+          description: '应用描述',
+          name: '应用名称',
+        },
+      },
+    }
+  }
+
+  it('keeps the rest of the meta when a chatbot omits optional fields', () => {
+    const meta = parseProjectMetaResponse(
+      responseWithChatbots([{ id: 'chat_1' }]),
+    )
+
+    expect(meta.isOwner).toBe(true)
+    expect(meta.name).toBe('应用名称')
+    expect(meta.baseBindings).toEqual([
+      { baseToken: 'bascnBase', tableIds: ['tbl_a'] },
+    ])
+    expect(meta.chatList).toEqual([{ id: 'chat_1', name: '', iconInfo: '' }])
+  })
+
+  it('drops entries without a usable id and keeps the valid ones', () => {
+    const meta = parseProjectMetaResponse(
+      responseWithChatbots([
+        { name: '没有 id' },
+        'not-an-object',
+        { id: 'chat_2', name: '有效', iconInfo: '{"key":"k","type":2}' },
+      ]),
+    )
+
+    expect(meta.isOwner).toBe(true)
+    expect(meta.chatList).toEqual([
+      { id: 'chat_2', name: '有效', iconInfo: '{"key":"k","type":2}' },
+    ])
+  })
+})