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

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.

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 ?? '',
+  }
+}