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

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

@@ -0,0 +1,184 @@
+import { useEffect, useRef, useState } from 'react'
+import { Button } from '../../components/ui/button'
+import {
+  invokeSiteAIFunctionStream,
+  type SiteAIFunctionStreamHandle,
+  type SiteAIMessage,
+} from '../../lib/database-runtime'
+import { useUiLanguage } from '../../lib/ui-language'
+import { AI_FUNCTION_COPY } from './ai-copy'
+import { splitAIStreamDelta } from './ai-delta'
+
+/** 业务型 text AI Function 示例：分区渲染 reasoning 与 answer，并从最终结果解析结构化列表。
+ *
+ * 契约要点（对应 ai-function.md）：
+ * - 一次只维护一条活动 stream handle：新请求开始前 destroy 旧 handle。
+ * - 同时消费 reasoningContent 与 content，思考过程和最终回答分区展示。
+ * - onError 与 onDone 都收口 loading。
+ * - 结构化解析只基于最终 answer（content 的累积值），不基于 reasoning 内容。
+ * - 组件卸载时 destroy 活动 handle，避免流回调更新已卸载组件。
+ */
+export interface TextStreamOperationProps {
+  // functionKey 指向后台配置好的 text/vision AI Function。
+  functionKey: string
+  // variables 渲染 AI Function System Prompt 里的 {{var}} 占位符（可选）。
+  variables?: Record<string, unknown>
+  title?: string
+}
+
+interface StreamState {
+  answer: string
+  error: string
+  reasoning: string
+  streaming: boolean
+}
+
+const INITIAL_STATE: StreamState = {
+  answer: '',
+  error: '',
+  reasoning: '',
+  streaming: false,
+}
+
+/** 把最终回答按行解析成结构化列表项，仅作演示：真实业务应替换为自己的解析规则。 */
+export function parseAnswerItems(answer: string): string[] {
+  return answer
+    .split('\n')
+    .map((line) => line.replace(/^[-*\d.、\s]+/, '').trim())
+    .filter(Boolean)
+}
+
+function useTextStream(
+  functionKey: string,
+  variables: Record<string, unknown> | undefined,
+  unavailableMessage: string,
+) {
+  const streamRef = useRef<SiteAIFunctionStreamHandle | null>(null)
+  const [state, setState] = useState<StreamState>(INITIAL_STATE)
+
+  const stop = () => {
+    streamRef.current?.destroy()
+    streamRef.current = null
+  }
+
+  // 卸载时销毁活动流：回调不再触碰已卸载组件的 setState。
+  useEffect(() => stop, [])
+
+  const ask = (question: string) => {
+    const content = question.trim()
+    if (!content) {
+      return
+    }
+    // 新请求开始前，先释放上一条活动流。
+    stop()
+    setState({ ...INITIAL_STATE, streaming: true })
+
+    const messages: SiteAIMessage[] = [
+      { content: [{ type: 'text', text: content }], role: 'user' },
+    ]
+    const stream = invokeSiteAIFunctionStream({
+      functionKey,
+      messages,
+      ...(variables ? { variables } : {}),
+    })
+    stream.onMessage((delta) => {
+      const { answer, reasoning } = splitAIStreamDelta(delta)
+      setState((current) => ({
+        ...current,
+        answer: current.answer + answer,
+        reasoning: current.reasoning + reasoning,
+      }))
+    })
+    stream.onError((error) => {
+      setState((current) => ({
+        ...current,
+        error: error.message || unavailableMessage,
+        streaming: false,
+      }))
+      stop()
+    })
+    stream.onDone(() => {
+      setState((current) => ({ ...current, streaming: false }))
+      streamRef.current = null
+    })
+    streamRef.current = stream
+  }
+
+  return { ask, state, stop }
+}
+
+/** 文本流式业务操作示例组件。 */
+export function TextStreamOperation({
+  functionKey,
+  variables,
+  title,
+}: TextStreamOperationProps) {
+  const i18n = AI_FUNCTION_COPY[useUiLanguage()].text
+  const { ask, state, stop } = useTextStream(
+    functionKey,
+    variables,
+    i18n.unavailable,
+  )
+  const [draft, setDraft] = useState('')
+
+  const submit = () => {
+    if (state.streaming) {
+      return
+    }
+    ask(draft)
+  }
+
+  const items = state.streaming ? [] : parseAnswerItems(state.answer)
+
+  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.question}
+        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) => setDraft(event.target.value)}
+        placeholder={i18n.questionPlaceholder}
+        value={draft}
+      />
+      <div className="flex gap-2">
+        <Button disabled={state.streaming || !draft.trim()} onClick={submit}>
+          {state.streaming ? i18n.generating : i18n.send}
+        </Button>
+        {state.streaming ? (
+          <Button onClick={stop} variant="secondary">
+            {i18n.stop}
+          </Button>
+        ) : null}
+      </div>
+
+      {state.reasoning ? (
+        <details className="rounded-lg bg-secondary/40 p-3 text-xs text-muted-foreground">
+          <summary className="cursor-pointer select-none">
+            {i18n.reasoning}
+          </summary>
+          <p className="mt-2 whitespace-pre-wrap">{state.reasoning}</p>
+        </details>
+      ) : null}
+
+      {state.answer ? (
+        <div className="whitespace-pre-wrap rounded-lg bg-secondary p-3 text-sm text-secondary-foreground">
+          {state.answer}
+        </div>
+      ) : null}
+
+      {items.length > 0 ? (
+        <ul className="list-disc pl-5 text-sm text-card-foreground">
+          {items.map((item, index) => (
+            <li key={`${index}-${item}`}>{item}</li>
+          ))}
+        </ul>
+      ) : null}
+
+      {state.error ? (
+        <p className="text-sm text-danger">{state.error}</p>
+      ) : null}
+    </section>
+  )
+}

package/templates/database-starter/page/src/examples/ai-function/ai-copy.ts

@@ -0,0 +1,173 @@
+import type { SiteAIMediaTask } from '../../lib/database-runtime'
+import type { UiLanguage } from '../../lib/ui-language'
+
+interface AiFunctionCopy {
+  text: {
+    title: string
+    question: string
+    questionPlaceholder: string
+    send: string
+    generating: string
+    stop: string
+    reasoning: string
+    unavailable: string
+  }
+  image: {
+    title: string
+    description: string
+    descriptionPlaceholder: string
+    generate: string
+    generating: string
+    generatedImage: string
+    failed: string
+    unavailable: string
+    timeout: string
+  }
+  video: {
+    title: string
+    description: string
+    descriptionPlaceholder: string
+    generate: string
+    processing: string
+    generatedVideo: string
+    unavailable: string
+    timeout: string
+  }
+  taskStatus: string
+  statuses: Record<SiteAIMediaTask['status'], string>
+}
+
+export const AI_FUNCTION_COPY = {
+  en: {
+    text: {
+      title: 'Generate text',
+      question: 'Question',
+      questionPlaceholder: 'Enter your question',
+      send: 'Send',
+      generating: 'Generating…',
+      stop: 'Stop',
+      reasoning: 'Reasoning',
+      unavailable: 'AI request is temporarily unavailable',
+    },
+    image: {
+      title: 'Generate an image',
+      description: 'Image description',
+      descriptionPlaceholder: 'Describe the image you want to create',
+      generate: 'Generate image',
+      generating: 'Generating…',
+      generatedImage: 'Generated image',
+      failed: 'Image generation failed',
+      unavailable: 'Image generation is temporarily unavailable',
+      timeout: 'Image generation timed out',
+    },
+    video: {
+      title: 'Generate a video',
+      description: 'Video description',
+      descriptionPlaceholder: 'Describe the video you want to create',
+      generate: 'Generate video',
+      processing: 'Processing…',
+      generatedVideo: 'Generated video',
+      unavailable: 'Video generation is temporarily unavailable',
+      timeout: 'Video generation timed out',
+    },
+    taskStatus: 'Task status: ',
+    statuses: {
+      queued: 'Queued',
+      running: 'Running',
+      succeeded: 'Completed',
+      failed: 'Failed',
+      cancelled: 'Cancelled',
+    },
+  },
+  zh: {
+    text: {
+      title: '生成文本',
+      question: '问题',
+      questionPlaceholder: '请输入问题',
+      send: '发送',
+      generating: '生成中…',
+      stop: '停止',
+      reasoning: '思考过程',
+      unavailable: 'AI 请求暂时不可用',
+    },
+    image: {
+      title: '生成图片',
+      description: '图片描述',
+      descriptionPlaceholder: '描述你想生成的图片',
+      generate: '生成图片',
+      generating: '生成中…',
+      generatedImage: '生成的图片',
+      failed: '图片生成失败',
+      unavailable: '图片生成暂时不可用',
+      timeout: '图片生成等待超时',
+    },
+    video: {
+      title: '生成视频',
+      description: '视频描述',
+      descriptionPlaceholder: '描述你想生成的视频',
+      generate: '生成视频',
+      processing: '处理中…',
+      generatedVideo: '生成的视频',
+      unavailable: '视频生成暂时不可用',
+      timeout: '视频生成等待超时',
+    },
+    taskStatus: '任务状态：',
+    statuses: {
+      queued: '排队中',
+      running: '运行中',
+      succeeded: '已完成',
+      failed: '失败',
+      cancelled: '已取消',
+    },
+  },
+  ja: {
+    text: {
+      title: 'テキストを生成',
+      question: '質問',
+      questionPlaceholder: '質問を入力してください',
+      send: '送信',
+      generating: '生成中…',
+      stop: '停止',
+      reasoning: '推論過程',
+      unavailable: 'AI リクエストを処理できませんでした',
+    },
+    image: {
+      title: '画像を生成',
+      description: '画像の説明',
+      descriptionPlaceholder: '生成したい画像を説明してください',
+      generate: '画像を生成',
+      generating: '生成中…',
+      generatedImage: '生成された画像',
+      failed: '画像の生成に失敗しました',
+      unavailable: '現在、画像を生成できません',
+      timeout: '画像生成の待機時間を超えました',
+    },
+    video: {
+      title: '動画を生成',
+      description: '動画の説明',
+      descriptionPlaceholder: '生成したい動画を説明してください',
+      generate: '動画を生成',
+      processing: '処理中…',
+      generatedVideo: '生成された動画',
+      unavailable: '現在、動画を生成できません',
+      timeout: '動画生成の待機時間を超えました',
+    },
+    taskStatus: 'タスクの状態：',
+    statuses: {
+      queued: '待機中',
+      running: '実行中',
+      succeeded: '完了',
+      failed: '失敗',
+      cancelled: 'キャンセル済み',
+    },
+  },
+} satisfies Record<UiLanguage, AiFunctionCopy>
+
+export function formatAiTaskStatus(
+  status: SiteAIMediaTask['status'],
+  progress: number | undefined,
+  language: UiLanguage,
+): string {
+  const copy = AI_FUNCTION_COPY[language]
+  return `${copy.taskStatus}${copy.statuses[status]}${typeof progress === 'number' ? ` (${progress}%)` : ''}`
+}

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

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest'
+import { splitAIStreamDelta } from './ai-delta'
+import { parseAnswerItems } from './TextStreamOperation'
+
+describe('splitAIStreamDelta', () => {
+  it('reads answer and reasoning increments separately', () => {
+    expect(
+      splitAIStreamDelta({ content: '答', reasoningContent: '想', raw: {} }),
+    ).toEqual({ answer: '答', reasoning: '想' })
+  })
+
+  it('falls back to empty strings when a field is missing', () => {
+    expect(
+      splitAIStreamDelta({ reasoningContent: '只有思考', raw: {} }),
+    ).toEqual({ answer: '', reasoning: '只有思考' })
+    expect(splitAIStreamDelta({ content: '只有回答', raw: {} })).toEqual({
+      answer: '只有回答',
+      reasoning: '',
+    })
+  })
+})
+
+describe('parseAnswerItems', () => {
+  it('splits the final answer into trimmed list items and drops bullets', () => {
+    expect(parseAnswerItems('- 宫保鸡丁\n2. 麻婆豆腐\n\n  ')).toEqual([
+      '宫保鸡丁',
+      '麻婆豆腐',
+    ])
+  })
+})

package/templates/database-starter/page/src/examples/ai-function/ai-delta.ts

@@ -0,0 +1,26 @@
+import type { SiteAIStreamDelta } from '../../lib/database-runtime'
+
+/** text/vision 流式增量拆成「最终回答」与「思考过程」两段。
+ *
+ * reasoning 模型会先持续下发 reasoningContent、再下发 content。页面若只消费 content，
+ * 思考过程区域会一直为空，看起来像没有流式输出。用本 helper 统一取两段增量，
+ * 业务组件不必逐帧判空。SDK 新版本导出了同名 `readSiteAITextDelta`，
+ * 这里内置一份，保证 starter 在任意 channel 版本下都可用。
+ */
+export interface AITextDelta {
+  /** 最终回答增量，进正式结果区。 */
+  answer: string
+  /** 模型思考过程增量，进较小的过程区域。 */
+  reasoning: string
+}
+
+/** 从单帧增量读出 { answer, reasoning }；缺失字段回退为空串。
+ * @param delta SDK 归一化后的流式增量。
+ * @returns 本帧的回答与思考过程增量。
+ */
+export function splitAIStreamDelta(delta: SiteAIStreamDelta): AITextDelta {
+  return {
+    answer: delta.content ?? '',
+    reasoning: delta.reasoningContent ?? '',
+  }
+}

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)
+  })
+})