@lark-base-open/base-database-cli 1.1.1 → 1.3.7

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

@@ -1,16 +1,31 @@
-import { describe, expect, it } from 'vitest'
-import { parseProjectMetaResponse } from './project-meta'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { fetchProjectMeta, parseProjectMetaResponse } from './project-meta'
 
-function projectResponse(isOwner: unknown) {
+const runtime = vi.hoisted(() => ({
+  fetch: vi.fn(),
+  resolveDatabaseContext: vi.fn(),
+}))
+
+vi.mock('../../../lib/database-runtime', async (importOriginal) => ({
+  ...(await importOriginal<object>()),
+  ...runtime,
+}))
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.clearAllMocks()
+})
+
+function projectResponse(isOwner: unknown, allowEdit?: unknown) {
   return {
     code: 0,
     data: {
       isOwner,
       site: {
         baseBindings: [],
-        chatbots: [],
         description: 'Owner visibility test',
         name: 'Owner visibility test',
+        ...(allowEdit === undefined ? {} : { allowEdit }),
       },
     },
   }
@@ -32,48 +47,103 @@ describe('project owner visibility', () => {
   })
 })
 
-describe('project chatbot parsing', () => {
-  // 接口的 chatbot 字段全部可选，缺字段不能连带丢掉 isOwner 与应用名称。
-  function responseWithChatbots(chatbots: unknown) {
-    return {
+describe('edit entry permission', () => {
+  it('shows admins and owners when the server allows editing', () => {
+    expect(
+      parseProjectMetaResponse(projectResponse(false, true)).allowEdit,
+    ).toBe(true)
+  })
+
+  it('respects explicit denial and falls back to owner only for old responses', () => {
+    expect(
+      parseProjectMetaResponse(projectResponse(true, false)).allowEdit,
+    ).toBe(false)
+    expect(parseProjectMetaResponse(projectResponse(true)).allowEdit).toBe(true)
+    expect(parseProjectMetaResponse(projectResponse(false)).allowEdit).toBe(
+      false,
+    )
+    expect(
+      parseProjectMetaResponse(projectResponse(false, 'true')).allowEdit,
+    ).toBe(false)
+    expect(
+      parseProjectMetaResponse(projectResponse(true, 'true')).allowEdit,
+    ).toBe(false)
+  })
+})
+
+describe('project metadata', () => {
+  it('preserves page identity and valid Base bindings', () => {
+    const meta = parseProjectMetaResponse({
       code: 0,
       data: {
         isOwner: true,
         site: {
-          baseBindings: [{ baseToken: 'bascnBase', tableIds: ['tbl_a'] }],
-          chatbots,
+          name: ' 应用名称 ',
           description: '应用描述',
-          name: '应用名称',
+          organization: '所属组织',
+          baseBindings: [
+            null,
+            { tableIds: ['missing-token'] },
+            { baseToken: ' bascnBase ', tableIds: ['tbl_a', 42] },
+          ],
         },
       },
-    }
-  }
-
-  it('keeps the rest of the meta when a chatbot omits optional fields', () => {
-    const meta = parseProjectMetaResponse(
-      responseWithChatbots([{ id: 'chat_1' }]),
-    )
+    })
+    expect(meta).toEqual({
+      isOwner: true,
+      allowEdit: true,
+      name: '应用名称',
+      description: '应用描述',
+      organization: '所属组织',
+      baseBindings: [{ baseToken: 'bascnBase', tableIds: ['tbl_a'] }],
+    })
+  })
 
-    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.each([
+    null,
+    { code: 1 },
+    { code: 0, data: { site: null, isOwner: true } },
+  ])('fails closed for an invalid response', (response) => {
+    expect(parseProjectMetaResponse(response)).toEqual({
+      isOwner: false,
+      allowEdit: false,
+      name: '',
+      description: '',
+      organization: '',
+      baseBindings: [],
+    })
   })
 
-  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}' },
-      ]),
-    )
+  it.each(['prod', 'preview'])(
+    'fetches only application metadata in %s',
+    async (env) => {
+      runtime.resolveDatabaseContext.mockResolvedValue({
+        env,
+        gatewayOrigin: '',
+        token: 'meta_test',
+      })
+      runtime.fetch.mockResolvedValue({
+        ok: true,
+        json: async () => projectResponse(true),
+      })
+      class MetaElement {
+        content = ''
+      }
+      const description = new MetaElement()
+      const document = { title: '', querySelector: vi.fn(() => description) }
+      vi.stubGlobal('document', document)
+      vi.stubGlobal('HTMLMetaElement', MetaElement)
 
-    expect(meta.isOwner).toBe(true)
-    expect(meta.chatList).toEqual([
-      { id: 'chat_2', name: '有效', iconInfo: '{"key":"k","type":2}' },
-    ])
-  })
+      const meta = await fetchProjectMeta()
+      expect(runtime.fetch).toHaveBeenCalledWith(
+        `/space/api/bitable/site/v1/meta_test/invoke_get${env === 'preview' ? '?env=preview' : ''}`,
+        { method: 'GET' },
+      )
+      expect(meta.isOwner).toBe(true)
+      expect(document.title).toBe('Owner visibility test')
+      expect(description.content).toBe('Owner visibility test')
+      expect(await fetchProjectMeta()).toBe(meta)
+      expect(runtime.fetch).toHaveBeenCalledTimes(1)
+    },
+  )
 })

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

@@ -5,12 +5,6 @@ import {
   type DatabaseContext,
 } from '../../../lib/database-runtime'
 
-interface ProjectChat {
-  id: string
-  name: string
-  iconInfo: string
-}
-
 export interface ProjectBaseBinding {
   baseToken: string
   tableIds: string[]
@@ -18,11 +12,11 @@ export interface ProjectBaseBinding {
 
 export interface ProjectMeta {
   baseBindings: ProjectBaseBinding[]
-  chatList: ProjectChat[]
   name: string
   description: string
   isOwner: boolean
-  /** 应用所属组织（企业）名，浮层菜单展示用；服务端未下发时为空串。 */
+  allowEdit: boolean
+  /** 应用所属组织（企业）名，账号菜单展示用；服务端未下发时为空串。 */
   organization: string
 }
 
@@ -60,15 +54,15 @@ function readStringArray(value: unknown): string[] {
 }
 
 /** 构造空项目 meta。
- * @returns chatList 为空的项目 meta。
+ * @returns 不包含所有者权限的空项目 meta。
  */
 function createEmptyProjectMeta(): ProjectMeta {
   return {
     baseBindings: [],
-    chatList: [],
     name: '',
     description: '',
     isOwner: false,
+    allowEdit: false,
     organization: '',
   }
 }
@@ -130,41 +124,9 @@ function parseProjectBaseBindings(
   }, [])
 }
 
-/** 解析 Site 绑定的 chatbot 列表。
- *
- * 接口的 chatbot 字段全部可选：缺 id 的条目无法跳转，直接丢弃；名称与图标缺失时
- * 留空交由展示层兜底。单个 chatbot 字段不全不能影响整个项目 meta 的解析。
- *
- * @param rawChatbots 接口返回的 chatbots 字段。
- * @returns 可用于展示的 chatbot 列表。
- */
-function parseProjectChats(rawChatbots: unknown): ProjectChat[] {
-  if (!Array.isArray(rawChatbots)) {
-    return []
-  }
-
-  return rawChatbots.reduce<ProjectChat[]>((chats, chatbot) => {
-    if (!isRecord(chatbot)) {
-      return chats
-    }
-
-    const id = readOptionalString(chatbot, 'id')
-    if (!id) {
-      return chats
-    }
-
-    chats.push({
-      id,
-      name: readOptionalString(chatbot, 'name'),
-      iconInfo: readOptionalString(chatbot, 'iconInfo'),
-    })
-    return chats
-  }, [])
-}
-
 /** 将资源接口响应转换为页面需要的项目 meta。
  * @param rawResponse 接口原始响应。
- * @returns 提取后的应用名称、描述和 chatbot 列表；接口或结构异常时返回空数据。
+ * @returns 提取后的应用名称、描述、所属组织、Base 绑定及所有者状态；接口或结构异常时返回空数据。
  */
 export function parseProjectMetaResponse(rawResponse: unknown): ProjectMeta {
   if (!isRecord(rawResponse)) {
@@ -187,10 +149,14 @@ export function parseProjectMetaResponse(rawResponse: unknown): ProjectMeta {
 
   return {
     baseBindings: parseProjectBaseBindings(site.baseBindings),
-    chatList: parseProjectChats(site.chatbots),
     description: readOptionalString(site, 'description'),
     name: readOptionalString(site, 'name'),
     isOwner: data.isOwner === true,
+    // 老服务端尚未下发 allowEdit 时保留 Owner 入口；显式 false 必须优先。
+    allowEdit:
+      site.allowEdit === undefined
+        ? data.isOwner === true
+        : site.allowEdit === true,
     organization: readOptionalString(site, 'organization'),
   }
 }
@@ -206,12 +172,9 @@ async function requestProjectMeta(
   context: DatabaseContext,
 ): Promise<ProjectMeta> {
   try {
-    const response = await databaseFetch(
-      buildDatabaseInvokeGetPath(context, true),
-      {
-        method: 'GET',
-      },
-    )
+    const response = await databaseFetch(buildDatabaseInvokeGetPath(context), {
+      method: 'GET',
+    })
 
     if (!response.ok) {
       return createEmptyProjectMeta()

package/templates/database-starter/page/src/components/ui-language.test.tsx

@@ -0,0 +1,101 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+const runtime = vi.hoisted(() => ({ getRuntimeContext: vi.fn() }))
+vi.mock('../lib/database-runtime', () => ({ siteRuntime: runtime }))
+
+import UserSelectorEditor from './UserSelectorEditor'
+import UserSelectorPanel from './UserSelectorPanel'
+import { PageState } from './feedback/page-state'
+import { AttachmentImage } from '../lib/attachment-image'
+import App from '../App'
+import {
+  getUiLanguage,
+  getUiLocale,
+  selectUiLanguage,
+} from '../lib/ui-language'
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  runtime.getRuntimeContext.mockReset()
+})
+
+describe('built-in component language', () => {
+  it('prefers supported host locales, then browser locales, then English', () => {
+    expect(selectUiLanguage('ja-JP', 'zh-CN')).toBe('ja')
+    expect(selectUiLanguage('zh_CN', 'ja-JP')).toBe('zh')
+    expect(selectUiLanguage('zh-TW', 'ja-JP')).toBe('zh')
+    expect(getUiLocale('zh')).toBe('zh-CN')
+    expect(selectUiLanguage('fr-FR', 'ja-JP')).toBe('ja')
+    expect(selectUiLanguage(undefined, 'fr-FR')).toBe('en')
+    expect(selectUiLanguage(undefined, undefined)).toBe('en')
+  })
+
+  it('uses the browser language before the host context resolves', () => {
+    vi.stubGlobal('navigator', { language: 'ja-JP' })
+    vi.stubGlobal('document', { documentElement: { lang: 'en' } })
+
+    expect(getUiLanguage()).toBe('ja')
+    expect(getUiLocale()).toBe('ja-JP')
+  })
+
+  it('uses English on server render until the browser resolves the locale', () => {
+    expect(renderToStaticMarkup(<App />)).toContain(
+      'Start with a real business workflow',
+    )
+    expect(renderToStaticMarkup(<UserSelectorEditor value={null} />)).toContain(
+      'Select members',
+    )
+    expect(renderToStaticMarkup(<UserSelectorPanel />)).toContain(
+      'No recommended members yet',
+    )
+    expect(renderToStaticMarkup(<PageState status="error" />)).toContain(
+      'Please try again later',
+    )
+    expect(
+      renderToStaticMarkup(
+        <AttachmentImage
+          attachment={{
+            tableId: 'tblA',
+            fieldId: 'fldA',
+            recordId: 'recA',
+            fileToken: 'fileA',
+          }}
+          alt="attachment"
+        />,
+      ),
+    ).toContain('Loading image')
+  })
+
+  it('uses browser lang until the host locale arrives, then applies the host locale', async () => {
+    vi.resetModules()
+    vi.stubGlobal('navigator', { language: 'zh-CN' })
+    vi.stubGlobal('document', { documentElement: { lang: 'en' } })
+    let resolveContext!: (value: { locale: string }) => void
+    runtime.getRuntimeContext.mockReturnValue(
+      new Promise((resolve) => {
+        resolveContext = resolve
+      }),
+    )
+    const language = await import('../lib/ui-language')
+    const request = language.initializeUiLanguage()
+
+    expect(document.documentElement.lang).toBe('zh-CN')
+    resolveContext({ locale: 'ja-JP' })
+    expect(await request).toBe('ja')
+    expect(language.getUiLanguage()).toBe('ja')
+    expect(document.documentElement.lang).toBe('ja-JP')
+    expect(runtime.getRuntimeContext).toHaveBeenCalledTimes(1)
+  })
+
+  it('falls back to the browser when the host request fails', async () => {
+    vi.resetModules()
+    vi.stubGlobal('navigator', { language: 'ja-JP' })
+    vi.stubGlobal('document', { documentElement: { lang: 'en' } })
+    runtime.getRuntimeContext.mockRejectedValue(new Error('unavailable'))
+    const language = await import('../lib/ui-language')
+
+    expect(await language.initializeUiLanguage()).toBe('ja')
+    expect(document.documentElement.lang).toBe('ja-JP')
+  })
+})

package/templates/database-starter/page/src/examples/ai-function/ImageTaskOperation.tsx

@@ -0,0 +1,202 @@
+import { useEffect, useRef, useState } from 'react'
+import { Button } from '../../components/ui/button'
+import {
+  createSiteAIFunctionTask,
+  getSiteAIFunctionTask,
+  hasRunnableMediaTask,
+  type SiteAIMediaTask,
+} from '../../lib/database-runtime'
+import { useUiLanguage } from '../../lib/ui-language'
+import { AI_FUNCTION_COPY, formatAiTaskStatus } from './ai-copy'
+
+/** 业务型 image AI Function 示例：create task + poll，处理全部终态，并防止旧任务覆盖新结果。
+ *
+ * 契约要点（对应 ai-function.md）：
+ * - 文生图/文生视频统一走任务式：createSiteAIFunctionTask 提交，getSiteAIFunctionTask 轮询。
+ * - 处理 queued/running/succeeded/failed/cancelled 五种状态。
+ * - 用本地自增 requestSeq 作为「当前请求」标记：轮询回调先校验 seq，过期任务的结果直接丢弃，
+ *   避免用户快速多次提交时旧任务把新结果覆盖掉。
+ * - 卸载时清理 timer，回调不再触碰已卸载组件。
+ */
+export interface ImageTaskOperationProps {
+  functionKey: string
+  // referenceImages 支持 1～14 张可访问 URL 或 data:image Base64。
+  referenceImages?: string[]
+  title?: string
+  // pollIntervalMs 轮询节奏，默认 3s；服务端也有轮询上限。
+  pollIntervalMs?: number
+}
+
+interface ImageTaskState {
+  error: string
+  loading: boolean
+  task: SiteAIMediaTask | null
+}
+
+const INITIAL_STATE: ImageTaskState = {
+  error: '',
+  loading: false,
+  task: null,
+}
+
+function useImageTask(
+  functionKey: string,
+  pollIntervalMs: number,
+  messages: { failed: string; unavailable: string },
+) {
+  const [state, setState] = useState<ImageTaskState>(INITIAL_STATE)
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  // requestSeq 单调递增，标识「当前有效请求」；轮询链只对最新一次提交生效。
+  const requestSeq = useRef(0)
+
+  const clearTimer = () => {
+    if (timerRef.current) {
+      clearTimeout(timerRef.current)
+      timerRef.current = null
+    }
+  }
+
+  // 卸载时清理 timer：过期回调不再 setState。
+  useEffect(() => clearTimer, [])
+
+  const poll = (taskId: string, seq: number) => {
+    timerRef.current = setTimeout(async () => {
+      try {
+        const next = await getSiteAIFunctionTask(functionKey, taskId)
+        // 期间已发起新请求：本次结果作废，什么都不做。
+        if (seq !== requestSeq.current) {
+          return
+        }
+        setState((current) => ({ ...current, task: next }))
+        if (next.status === 'succeeded') {
+          setState((current) => ({ ...current, loading: false }))
+          return
+        }
+        if (next.status === 'failed' || next.status === 'cancelled') {
+          setState((current) => ({
+            ...current,
+            error: next.errMessage ?? messages.failed,
+            loading: false,
+          }))
+          return
+        }
+        poll(taskId, seq)
+      } catch (cause) {
+        if (seq !== requestSeq.current) {
+          return
+        }
+        setState((current) => ({
+          ...current,
+          error: cause instanceof Error ? cause.message : messages.unavailable,
+          loading: false,
+        }))
+      }
+    }, pollIntervalMs)
+  }
+
+  const submit = async (prompt: string, referenceImages: string[]) => {
+    const value = prompt.trim()
+    if (!value) {
+      return
+    }
+    clearTimer()
+    const seq = requestSeq.current + 1
+    requestSeq.current = seq
+    setState({ ...INITIAL_STATE, loading: true })
+    try {
+      const created = await createSiteAIFunctionTask({
+        functionKey,
+        capability: 'image',
+        input: {
+          prompt: value,
+          ...(referenceImages.length ? { image: referenceImages } : {}),
+        },
+      })
+      if (seq !== requestSeq.current) {
+        return
+      }
+      setState((current) => ({ ...current, task: created }))
+      if (hasRunnableMediaTask(created)) {
+        poll(created.taskId, seq)
+      } else {
+        setState((current) => ({ ...current, loading: false }))
+      }
+    } catch (cause) {
+      if (seq !== requestSeq.current) {
+        return
+      }
+      setState((current) => ({
+        ...current,
+        error: cause instanceof Error ? cause.message : messages.unavailable,
+        loading: false,
+      }))
+    }
+  }
+
+  return { state, submit }
+}
+
+/** 图片生成业务操作示例组件，支持纯文本、单参考图和多参考图。 */
+export function ImageTaskOperation({
+  functionKey,
+  pollIntervalMs = 3000,
+  referenceImages = [],
+  title,
+}: ImageTaskOperationProps) {
+  const language = useUiLanguage()
+  const copy = AI_FUNCTION_COPY[language]
+  const i18n = copy.image
+  const { state, submit } = useImageTask(functionKey, pollIntervalMs, i18n)
+  const [prompt, setPrompt] = useState('')
+
+  const generate = () => {
+    if (state.loading) {
+      return
+    }
+    void submit(prompt, referenceImages)
+  }
+
+  const images =
+    state.task?.type === 'image_task'
+      ? (state.task.imageAssets ?? []).filter(
+          (asset): asset is typeof asset & { url: string } =>
+            Boolean(asset.url),
+        )
+      : []
+
+  return (
+    <section className="flex flex-col gap-3 rounded-2xl border border-border bg-card p-5">
+      <h2 className="font-semibold text-card-foreground">
+        {title ?? i18n.title}
+      </h2>
+      <textarea
+        aria-label={i18n.description}
+        className="min-h-20 rounded-lg border border-border bg-background p-3 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        onChange={(event) => setPrompt(event.target.value)}
+        placeholder={i18n.descriptionPlaceholder}
+        value={prompt}
+      />
+      <Button disabled={state.loading || !prompt.trim()} onClick={generate}>
+        {state.loading ? i18n.generating : i18n.generate}
+      </Button>
+      {state.task ? (
+        <p className="text-sm text-muted-foreground">
+          {formatAiTaskStatus(state.task.status, state.task.progress, language)}
+        </p>
+      ) : null}
+      {state.error ? (
+        <p className="text-sm text-danger">{state.error}</p>
+      ) : null}
+      <div className="grid grid-cols-2 gap-3">
+        {images.map((asset) => (
+          <img
+            alt={i18n.generatedImage}
+            className="w-full rounded-lg border border-border"
+            key={asset.url}
+            src={asset.url}
+          />
+        ))}
+      </div>
+    </section>
+  )
+}

package/templates/database-starter/page/src/examples/ai-function/README.md

@@ -0,0 +1,14 @@
+# AI Function examples
+
+Reference implementations for business pages. Copy the relevant example into a page and adapt it to the task.
+
+The examples' built-in titles, prompts, buttons, task statuses, and local fallback errors follow the host Runtime Context locale, then the browser language, then English. Supported languages are Chinese, English, and Japanese. A `title` prop supplied by the business Page overrides the built-in title and remains that Page's responsibility. Server-provided error messages and generated AI content are displayed as received.
+
+The components share `ai-copy.ts`. Keep that import when reusing an example, or copy the dictionary alongside the component when moving it to another directory.
+
+- `ai-media-panel.tsx`: `AIImagePanel` and `AIVideoPanel` call image and video AI Functions by `functionKey`. Their shared task hook ignores late results from superseded requests and limits total polling time with `pollDeadlineMs` (five minutes by default). `AIVideoPanel` renders `videoAsset`. The polling loop is exported as `pollMediaTaskUntilTerminal` for reuse and testing.
+- `ai-delta.ts`: `splitAIStreamDelta(delta)` separates streamed output into `{ answer, reasoning }`. The SDK also provides `readSiteAITextDelta`; this example uses a local helper.
+- `TextStreamOperation.tsx`: Text and image understanding stream. Shows how to keep one active stream handle, destroy the old handle before a new request, render `reasoningContent` and `content` separately, close loading state in `onError` and `onDone`, and parse a structured list from the final answer rather than reasoning.
+- `ImageTaskOperation.tsx`: Image task flow using `capability: 'image'`. Shows submission with `createSiteAIFunctionTask`, polling with `getSiteAIFunctionTask`, handling every terminal state (`succeeded`, `failed`, `cancelled`), passing 1–14 reference images, preventing an old task from overwriting a new result with `requestSeq`, and clearing the timer on unmount. For video tasks, use `AIVideoPanel` in `ai-media-panel.tsx`, which renders `videoAsset`.
+
+See the `lark-base-database` Skill's `ai-function.md` for the call contracts: `callSiteAIFunction` for a discriminated result, `invokeSiteAIFunctionStream` for explicit streaming, and `createSiteAIFunctionTask` / `getSiteAIFunctionTask` for media task submission and polling.