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

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

@@ -0,0 +1,86 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+const locale = vi.hoisted(() => ({ language: 'en' as 'en' | 'zh' | 'ja' }))
+vi.mock('../../lib/ui-language', () => ({
+  useUiLanguage: () => locale.language,
+}))
+
+import { formatAiTaskStatus } from './ai-copy'
+import { TextStreamOperation } from './TextStreamOperation'
+import { ImageTaskOperation } from './ImageTaskOperation'
+import { AIImagePanel, AIVideoPanel } from './ai-media-panel'
+
+afterEach(() => {
+  locale.language = 'en'
+})
+
+describe('AI Function example language', () => {
+  it.each([
+    {
+      language: 'en' as const,
+      textTitle: 'Generate text',
+      question: 'Enter your question',
+      imageTitle: 'Generate an image',
+      imagePrompt: 'Describe the image you want to create',
+      videoTitle: 'Generate a video',
+      videoPrompt: 'Describe the video you want to create',
+      status: 'Task status: Running (45%)',
+    },
+    {
+      language: 'zh' as const,
+      textTitle: '生成文本',
+      question: '请输入问题',
+      imageTitle: '生成图片',
+      imagePrompt: '描述你想生成的图片',
+      videoTitle: '生成视频',
+      videoPrompt: '描述你想生成的视频',
+      status: '任务状态：运行中 (45%)',
+    },
+    {
+      language: 'ja' as const,
+      textTitle: 'テキストを生成',
+      question: '質問を入力してください',
+      imageTitle: '画像を生成',
+      imagePrompt: '生成したい画像を説明してください',
+      videoTitle: '動画を生成',
+      videoPrompt: '生成したい動画を説明してください',
+      status: 'タスクの状態：実行中 (45%)',
+    },
+  ])('renders built-in copy in $language', (expected) => {
+    locale.language = expected.language
+    const text = renderToStaticMarkup(
+      <TextStreamOperation functionKey="text" />,
+    )
+    const image = renderToStaticMarkup(
+      <ImageTaskOperation functionKey="image" />,
+    )
+    const imagePanel = renderToStaticMarkup(
+      <AIImagePanel functionKey="image" />,
+    )
+    const videoPanel = renderToStaticMarkup(
+      <AIVideoPanel functionKey="video" />,
+    )
+
+    expect(text).toContain(expected.textTitle)
+    expect(text).toContain(expected.question)
+    expect(image).toContain(expected.imageTitle)
+    expect(image).toContain(expected.imagePrompt)
+    expect(imagePanel).toContain(expected.imageTitle)
+    expect(imagePanel).toContain(expected.imagePrompt)
+    expect(videoPanel).toContain(expected.videoTitle)
+    expect(videoPanel).toContain(expected.videoPrompt)
+    expect(formatAiTaskStatus('running', 45, expected.language)).toBe(
+      expected.status,
+    )
+  })
+
+  it('preserves a title supplied by the business Page', () => {
+    locale.language = 'ja'
+    expect(
+      renderToStaticMarkup(
+        <AIVideoPanel functionKey="video" title="Project video" />,
+      ),
+    ).toContain('Project video')
+  })
+})

package/templates/database-starter/page/src/examples/ai-function/ai-media-panel.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  activateMediaTaskRequestTracker,
+  createMediaTaskRequestTracker,
+  pollMediaTaskUntilTerminal,
+  type MediaTaskPollUpdate,
+} from './ai-media-panel'
+import type { SiteAIMediaTask } from '../../lib/database-runtime'
+
+function videoTask(taskId: string, status: string): SiteAIMediaTask {
+  return {
+    type: 'video_task',
+    taskId,
+    status: status as SiteAIMediaTask['status'],
+    requestId: `req-${taskId}`,
+  }
+}
+
+function nowClock(start: number) {
+  let time = start
+  return {
+    advance: (ms: number) => (time += ms),
+    now: () => time,
+  }
+}
+
+describe('pollMediaTaskUntilTerminal', () => {
+  it('drops updates once isCurrent becomes false (旧任务晚到)', async () => {
+    const updates: MediaTaskPollUpdate[] = []
+    let current = true
+    const clock = nowClock(0)
+    const fetchTask = vi
+      .fn<() => Promise<SiteAIMediaTask>>()
+      .mockImplementationOnce(async () => {
+        current = false
+        return videoTask('t1', 'succeeded')
+      })
+
+    await pollMediaTaskUntilTerminal({
+      fetchTask,
+      isCurrent: () => current,
+      timing: {
+        deadline: 60_000,
+        intervalMs: 10,
+        now: clock.now,
+        sleep: async (ms) => {
+          clock.advance(ms)
+        },
+      },
+      onUpdate: (update) => updates.push(update),
+      timeoutMessage: 'timeout',
+      failureMessage: 'failed',
+    })
+
+    expect(fetchTask).toHaveBeenCalledTimes(1)
+    expect(updates).toEqual([])
+  })
+
+  it('emits a timeout finish and stops when the deadline passes', async () => {
+    const updates: MediaTaskPollUpdate[] = []
+    const clock = nowClock(0)
+    const fetchTask = vi
+      .fn<() => Promise<SiteAIMediaTask>>()
+      .mockResolvedValue(videoTask('t1', 'queued'))
+
+    await pollMediaTaskUntilTerminal({
+      fetchTask,
+      isCurrent: () => true,
+      timing: {
+        deadline: 25,
+        intervalMs: 10,
+        now: clock.now,
+        sleep: async (ms) => {
+          clock.advance(ms)
+        },
+      },
+      onUpdate: (update) => updates.push(update),
+      timeoutMessage: '视频不可用（轮询超时）',
+      failureMessage: '视频不可用',
+    })
+
+    expect(updates[updates.length - 1]).toMatchObject({
+      finished: true,
+      error: '视频不可用（轮询超时）',
+    })
+  })
+
+  it('stops on succeeded/failed/cancelled terminal states', async () => {
+    for (const terminal of ['succeeded', 'failed', 'cancelled']) {
+      const updates: MediaTaskPollUpdate[] = []
+      const clock = nowClock(0)
+      const fetchTask = vi
+        .fn<() => Promise<SiteAIMediaTask>>()
+        .mockResolvedValueOnce(videoTask('t1', 'queued'))
+        .mockResolvedValueOnce(videoTask('t1', terminal))
+
+      await pollMediaTaskUntilTerminal({
+        fetchTask,
+        isCurrent: () => true,
+        timing: {
+          deadline: 10_000,
+          intervalMs: 10,
+          now: clock.now,
+          sleep: async (ms) => {
+            clock.advance(ms)
+          },
+        },
+        onUpdate: (update) => updates.push(update),
+        timeoutMessage: 'timeout',
+        failureMessage: '视频不可用',
+      })
+
+      expect(fetchTask).toHaveBeenCalledTimes(2)
+      const last = updates[updates.length - 1]
+      expect(last).toMatchObject({ finished: true })
+      if (terminal === 'succeeded') {
+        expect(last?.error).toBeUndefined()
+      } else {
+        expect(last?.error).toBeTruthy()
+      }
+    }
+  })
+
+  it('surfaces fetch errors and stops polling', async () => {
+    const updates: MediaTaskPollUpdate[] = []
+    const clock = nowClock(0)
+    const fetchTask = vi
+      .fn<() => Promise<SiteAIMediaTask>>()
+      .mockRejectedValueOnce(new Error('network broken'))
+
+    await pollMediaTaskUntilTerminal({
+      fetchTask,
+      isCurrent: () => true,
+      timing: {
+        deadline: 10_000,
+        intervalMs: 10,
+        now: clock.now,
+        sleep: async (ms) => {
+          clock.advance(ms)
+        },
+      },
+      onUpdate: (update) => updates.push(update),
+      timeoutMessage: 'timeout',
+      failureMessage: '视频不可用',
+    })
+
+    expect(updates).toEqual([{ finished: true, error: 'network broken' }])
+  })
+
+  it('preserves a server-provided task error', async () => {
+    const updates: MediaTaskPollUpdate[] = []
+    const failed = {
+      ...videoTask('t1', 'failed'),
+      errMessage: 'Server error: quota exceeded',
+    }
+
+    await pollMediaTaskUntilTerminal({
+      fetchTask: async () => failed,
+      isCurrent: () => true,
+      timing: {
+        deadline: 10_000,
+        intervalMs: 10,
+        now: () => 0,
+        sleep: async () => {},
+      },
+      onUpdate: (update) => updates.push(update),
+      timeoutMessage: 'Localized timeout',
+      failureMessage: 'Localized fallback',
+    })
+
+    expect(updates).toEqual([
+      { finished: true, error: 'Server error: quota exceeded', task: failed },
+    ])
+  })
+})
+
+describe('media task request lifecycle', () => {
+  it('invalidates the previous request when a new request begins', () => {
+    const tracker = createMediaTaskRequestTracker()
+    const cleanup = activateMediaTaskRequestTracker(tracker)
+    const firstRequestId = tracker.begin()
+    const secondRequestId = tracker.begin()
+
+    expect(tracker.isCurrent(firstRequestId)).toBe(false)
+    expect(tracker.isCurrent(secondRequestId)).toBe(true)
+    cleanup()
+  })
+
+  it('reactivates after the StrictMode effect replay and invalidates on cleanup', () => {
+    const tracker = createMediaTaskRequestTracker()
+
+    const firstCleanup = activateMediaTaskRequestTracker(tracker)
+    firstCleanup()
+    const secondCleanup = activateMediaTaskRequestTracker(tracker)
+    const requestId = tracker.begin()
+
+    expect(tracker.isCurrent(requestId)).toBe(true)
+    secondCleanup()
+    expect(tracker.isCurrent(requestId)).toBe(false)
+  })
+})

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

@@ -0,0 +1,382 @@
+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'
+
+// AI Function 媒体示例：文生图和文生视频统一使用任务提交 + 轮询。
+// functionKey 指向对应能力 AI Function；页面提交 prompt，model/尺寸/时长由配置声明。
+
+export interface AIImagePanelProps {
+  functionKey: string
+  referenceImages?: string[]
+  title?: string
+  pollIntervalMs?: number
+  pollDeadlineMs?: number
+}
+
+export interface AIVideoPanelProps {
+  functionKey: string
+  title?: string
+  // pollIntervalMs 轮询节奏，默认 3s；服务端也有轮询上限。
+  pollIntervalMs?: number
+  // pollDeadlineMs 单次任务总轮询时限，超过后放弃并结束 loading。默认 5 分钟。
+  pollDeadlineMs?: number
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 3000
+const DEFAULT_POLL_DEADLINE_MS = 5 * 60 * 1000
+
+export interface MediaTaskRequestTracker {
+  activate: () => void
+  begin: () => number
+  deactivate: () => void
+  isCurrent: (requestId: number) => boolean
+}
+
+export function createMediaTaskRequestTracker(): MediaTaskRequestTracker {
+  let active = false
+  let sequence = 0
+  return {
+    activate: () => {
+      active = true
+    },
+    begin: () => {
+      sequence += 1
+      return sequence
+    },
+    deactivate: () => {
+      active = false
+      sequence += 1
+    },
+    isCurrent: (requestId) => active && requestId === sequence,
+  }
+}
+
+export function activateMediaTaskRequestTracker(
+  tracker: MediaTaskRequestTracker,
+): () => void {
+  tracker.activate()
+  return () => tracker.deactivate()
+}
+
+export interface MediaTaskPollUpdate {
+  error?: string
+  finished: boolean
+  task?: SiteAIMediaTask
+}
+
+/** pollMediaTaskUntilTerminal 是可复用的轮询循环：
+ *  - `isCurrent()` 返回 false 时立即中止（旧任务），不 emit 更新；
+ *  - `now()` 超过 `deadline` 时按超时结束；
+ *  - 收到 succeeded/failed/cancelled 时结束；否则继续下一轮。
+ * 参数 <= 3 个：通过 config 传入，便于测试与复用。 */
+export async function pollMediaTaskUntilTerminal(config: {
+  fetchTask: () => Promise<SiteAIMediaTask>
+  isCurrent: () => boolean
+  timing: {
+    deadline: number
+    intervalMs: number
+    now: () => number
+    sleep: (ms: number) => Promise<void>
+  }
+  onUpdate: (update: MediaTaskPollUpdate) => void
+  timeoutMessage: string
+  failureMessage: string
+}): Promise<void> {
+  const { fetchTask, isCurrent, timing, onUpdate } = config
+  const { deadline, intervalMs, now, sleep } = timing
+  while (isCurrent()) {
+    await sleep(intervalMs)
+    if (!isCurrent()) return
+    if (now() >= deadline) {
+      onUpdate({ error: config.timeoutMessage, finished: true })
+      return
+    }
+    try {
+      const next = await fetchTask()
+      if (!isCurrent()) return
+      if (next.status === 'succeeded') {
+        onUpdate({ finished: true, task: next })
+        return
+      }
+      if (next.status === 'failed' || next.status === 'cancelled') {
+        onUpdate({
+          error: next.errMessage ?? config.failureMessage,
+          finished: true,
+          task: next,
+        })
+        return
+      }
+      onUpdate({ finished: false, task: next })
+    } catch (cause) {
+      if (!isCurrent()) return
+      onUpdate({
+        error: cause instanceof Error ? cause.message : config.failureMessage,
+        finished: true,
+      })
+      return
+    }
+  }
+}
+
+interface MediaTaskState {
+  error: string
+  loading: boolean
+  task: SiteAIMediaTask | null
+}
+
+const INITIAL_STATE: MediaTaskState = { error: '', loading: false, task: null }
+
+interface MediaTaskOptions {
+  capability: 'image' | 'video'
+  failureMessage: string
+  functionKey: string
+  pollDeadlineMs?: number
+  pollIntervalMs?: number
+  referenceImages?: string[]
+  timeoutMessage: string
+}
+
+interface SubmitMediaTaskOptions
+  extends Required<
+    Pick<MediaTaskOptions, 'pollDeadlineMs' | 'pollIntervalMs'>
+  > {
+  capability: MediaTaskOptions['capability']
+  failureMessage: string
+  functionKey: string
+  isCurrent: () => boolean
+  onCreated: (task: SiteAIMediaTask) => void
+  onUpdate: (update: MediaTaskPollUpdate) => void
+  prompt: string
+  referenceImages: string[]
+  timeoutMessage: string
+}
+
+function useMediaTaskRequestTracker(scope: string): MediaTaskRequestTracker {
+  const trackerRef = useRef<MediaTaskRequestTracker | null>(null)
+  if (!trackerRef.current) trackerRef.current = createMediaTaskRequestTracker()
+  const tracker = trackerRef.current
+  useEffect(() => activateMediaTaskRequestTracker(tracker), [scope, tracker])
+  return tracker
+}
+
+function applyPollUpdate(
+  current: MediaTaskState,
+  update: MediaTaskPollUpdate,
+): MediaTaskState {
+  return {
+    ...current,
+    ...(update.task ? { task: update.task } : {}),
+    ...(update.error ? { error: update.error } : {}),
+    ...(update.finished ? { loading: false } : {}),
+  }
+}
+
+async function submitMediaTask(options: SubmitMediaTaskOptions): Promise<void> {
+  const created = await createSiteAIFunctionTask({
+    functionKey: options.functionKey,
+    capability: options.capability,
+    input: {
+      prompt: options.prompt,
+      ...(options.capability === 'image' && options.referenceImages.length
+        ? { image: options.referenceImages }
+        : {}),
+    },
+  })
+  if (!options.isCurrent()) return
+  options.onCreated(created)
+  if (!hasRunnableMediaTask(created)) {
+    options.onUpdate({ finished: true })
+    return
+  }
+  await pollMediaTaskUntilTerminal({
+    fetchTask: () => getSiteAIFunctionTask(options.functionKey, created.taskId),
+    isCurrent: options.isCurrent,
+    timing: {
+      deadline: Date.now() + options.pollDeadlineMs,
+      intervalMs: options.pollIntervalMs,
+      now: () => Date.now(),
+      sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    },
+    onUpdate: options.onUpdate,
+    timeoutMessage: options.timeoutMessage,
+    failureMessage: options.failureMessage,
+  })
+}
+
+function useMediaTask(options: MediaTaskOptions) {
+  const {
+    capability,
+    failureMessage,
+    functionKey,
+    pollDeadlineMs = DEFAULT_POLL_DEADLINE_MS,
+    pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+    referenceImages = [],
+    timeoutMessage,
+  } = options
+  const [state, setState] = useState<MediaTaskState>(INITIAL_STATE)
+  const tracker = useMediaTaskRequestTracker(`${capability}:${functionKey}`)
+
+  const submit = async (prompt: string) => {
+    const value = prompt.trim()
+    if (!value) return
+    const requestId = tracker.begin()
+    const isCurrent = () => tracker.isCurrent(requestId)
+    setState({ ...INITIAL_STATE, loading: true })
+    try {
+      await submitMediaTask({
+        capability,
+        failureMessage,
+        functionKey,
+        isCurrent,
+        onCreated: (task) => setState((current) => ({ ...current, task })),
+        onUpdate: (update) =>
+          setState((current) => applyPollUpdate(current, update)),
+        pollDeadlineMs,
+        pollIntervalMs,
+        prompt: value,
+        referenceImages,
+        timeoutMessage,
+      })
+    } catch (cause) {
+      if (!isCurrent()) return
+      setState((current) => ({
+        ...current,
+        error: cause instanceof Error ? cause.message : failureMessage,
+        loading: false,
+      }))
+    }
+  }
+  return {
+    error: state.error,
+    loading: state.loading,
+    submit,
+    task: state.task,
+  }
+}
+
+/** 图片生成示例：支持纯文本、单参考图、多参考图，提交任务后轮询并展示图片资源。 */
+export function AIImagePanel({
+  functionKey,
+  pollDeadlineMs,
+  pollIntervalMs,
+  referenceImages = [],
+  title,
+}: AIImagePanelProps) {
+  const i18n = AI_FUNCTION_COPY[useUiLanguage()].image
+  const [prompt, setPrompt] = useState('')
+  const { error, loading, submit, task } = useMediaTask({
+    capability: 'image',
+    failureMessage: i18n.unavailable,
+    functionKey,
+    pollDeadlineMs,
+    pollIntervalMs,
+    referenceImages,
+    timeoutMessage: i18n.timeout,
+  })
+
+  const generate = async () => {
+    const value = prompt.trim()
+    if (!value || loading) return
+    await submit(value)
+  }
+
+  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={loading || !prompt.trim()} onClick={generate}>
+        {loading ? i18n.generating : i18n.generate}
+      </Button>
+      {error ? <p className="text-sm text-danger">{error}</p> : null}
+      <div className="grid grid-cols-2 gap-3">
+        {(task?.type === 'image_task' ? (task.imageAssets ?? []) : [])
+          .filter((asset): asset is typeof asset & { url: string } =>
+            Boolean(asset.url),
+          )
+          .map((asset) => (
+            <img
+              alt={i18n.generatedImage}
+              className="w-full rounded-lg border border-border"
+              key={asset.url}
+              src={asset.url}
+            />
+          ))}
+      </div>
+    </section>
+  )
+}
+
+/** 文生视频示例：提交任务后按节奏轮询，成功后展示视频。 */
+export function AIVideoPanel({
+  functionKey,
+  pollDeadlineMs,
+  pollIntervalMs,
+  title,
+}: AIVideoPanelProps) {
+  const language = useUiLanguage()
+  const i18n = AI_FUNCTION_COPY[language].video
+  const [prompt, setPrompt] = useState('')
+  const { error, loading, submit, task } = useMediaTask({
+    capability: 'video',
+    failureMessage: i18n.unavailable,
+    functionKey,
+    pollDeadlineMs,
+    pollIntervalMs,
+    timeoutMessage: i18n.timeout,
+  })
+
+  const generate = async () => {
+    const value = prompt.trim()
+    if (!value || loading) return
+    await submit(value)
+  }
+
+  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={loading || !prompt.trim()} onClick={generate}>
+        {loading ? i18n.processing : i18n.generate}
+      </Button>
+      {task ? (
+        <p className="text-sm text-muted-foreground">
+          {formatAiTaskStatus(task.status, task.progress, language)}
+        </p>
+      ) : null}
+      {error ? <p className="text-sm text-danger">{error}</p> : null}
+      {task?.type === 'video_task' &&
+      task.status === 'succeeded' &&
+      task.videoAsset?.url ? (
+        <video
+          aria-label={i18n.generatedVideo}
+          className="w-full rounded-lg border border-border"
+          controls
+          src={task.videoAsset.url}
+        />
+      ) : null}
+    </section>
+  )
+}