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

package/templates/database-starter/page/src/lib/database-runtime.ts

@@ -1,9 +1,41 @@
 import {
+  callSiteAIFunction as callRuntimeAIFunction,
+  createSiteAIFunctionTask as createRuntimeAIFunctionTask,
+  getSiteAIFunctionTask as getRuntimeAIFunctionTask,
+  invokeSiteAIFunctionStream as invokeRuntimeAIFunctionStream,
   invokeHttp,
   siteRuntime,
   fetch as siteRuntimeFetch,
+  type CallSiteAIFunctionParams as RuntimeCallSiteAIFunctionParams,
+  type InvokeSiteAIFunctionStreamParams as RuntimeInvokeSiteAIFunctionStreamParams,
+  type SiteAIFunctionResult,
+  type SiteAIFunctionStreamHandle,
+  type SiteAIStreamDelta,
+  type SiteAIImageAsset,
+  type SiteAIImageGenerationInput,
+  type SiteAIVideoTask,
   type SiteProjectEnv,
 } from '@lark-base-open/base-site-channel/runtime'
+import type { DatabaseFunctionInputMap } from './database-function-inputs.generated'
+
+/**
+ * alpha.17 的运行时代码已经会把 responseType 透传给宿主，但其公开 d.ts 仍停留在文本请求，
+ * 且没有声明顶层 signal。这里局部扩宽这一个二进制请求，避免生成工程为了通过 tsc 删除真实
+ * 运行所需字段；SDK 声明补齐后可以直接移除此兼容层。
+ */
+type BinarySiteHttpRequest = {
+  init: {
+    method: 'GET'
+    responseType: 'arrayBuffer'
+    timeoutMs: number
+  }
+  signal?: AbortSignal
+  url: string
+}
+
+const invokeBinaryHttp = invokeHttp as unknown as (
+  request: BinarySiteHttpRequest,
+) => Promise<Response>
 
 /** 内置 Runtime Function（function.runtime.*，由宿主固定分发）。
  * 随 channel 包发布，直接透传官方实现，不在 starter 侧包装。 */
@@ -21,7 +53,7 @@ export interface DatabaseContext {
   token: string
 }
 
-/** 附件在底表里的位置。四个值都来自 catalog.json 与 SQL 结果。 */
+/** 附件在底表里的位置。四个值都来自 catalog.json 与 Database Function 结果。 */
 export interface DatabaseAttachmentRef {
   tableId: string
   fieldId: string
@@ -32,6 +64,71 @@ export interface DatabaseAttachmentRef {
 /** 产物环境沿用 site.v1 协议的规范类型，避免两侧各自声明后漂移。 */
 export type DatabaseEnv = SiteProjectEnv
 
+export type SiteAIMessageContentPart =
+  | { text: string; type: 'text' }
+  | { detail?: 'high' | 'low' | 'xhigh'; type: 'image'; url: string }
+  | { fps?: number; type: 'video'; url: string }
+  | { type: 'audio'; url: string }
+  | { filename?: string; type: 'file'; url: string }
+
+/** AI Function 对话消息。所有 content 都使用非空 parts 数组；System Prompt 由 Function 配置管理。
+ * 元组式 `[X, ...X[]]` 保证空数组无法通过 TS 编译，避免把空 content 推迟到运行态服务端校验。 */
+export type SiteAIMessage =
+  | {
+      content: [SiteAIMessageContentPart, ...SiteAIMessageContentPart[]]
+      role: 'user'
+    }
+  | {
+      content: [
+        Extract<SiteAIMessageContentPart, { type: 'text' }>,
+        ...Array<Extract<SiteAIMessageContentPart, { type: 'text' }>>,
+      ]
+      role: 'assistant'
+    }
+
+type WithSiteAIMessages<T> = T extends unknown
+  ? Omit<T, 'messages'> & { messages?: SiteAIMessage[] }
+  : never
+
+export type CallSiteAIFunctionParams =
+  WithSiteAIMessages<RuntimeCallSiteAIFunctionParams>
+
+export type InvokeSiteAIFunctionStreamParams = Omit<
+  RuntimeInvokeSiteAIFunctionStreamParams,
+  'messages'
+> & { messages: SiteAIMessage[] }
+
+/** 单帧增量与可取消的流句柄。 */
+export type { SiteAIStreamDelta, SiteAIFunctionStreamHandle }
+
+/** AI Function 可判别联合返回与媒体任务态，供页面按 type 分支渲染。 */
+export type SiteAIMediaTask =
+  | SiteAIVideoTask
+  | {
+      capabilityType?: 'image'
+      errCode?: string
+      errMessage?: string
+      imageAssets?: SiteAIImageAsset[]
+      progress?: number
+      requestId: string
+      status: 'cancelled' | 'failed' | 'queued' | 'running' | 'succeeded'
+      taskId: string
+      type: 'image_task'
+    }
+export type {
+  SiteAIFunctionResult,
+  SiteAIImageGenerationInput,
+  SiteAIVideoTask,
+}
+
+const MEDIA_TASK_STATUSES = new Set([
+  'cancelled',
+  'failed',
+  'queued',
+  'running',
+  'succeeded',
+])
+
 /** Function 调用的统一响应包裹结构，与运行态接口一致。 */
 export interface DatabaseFunctionResponse<Data = unknown> {
   code: number
@@ -46,10 +143,8 @@ const ARTIFACT_PATH_PATTERN = /^\/?(preview\/)?app\/([^/]+)(\/|$)/
 const FUNCTION_ID_PATTERN = /^[A-Za-z0-9_-]+$/
 
 const DATABASE_RUNTIME_GATEWAY_PREFIX = '/space/api/bitable/site/v1'
-const ATTACHMENT_COVER_PATH = '/space/api/box/stream/download/v2/cover/'
 const ATTACHMENT_DOWNLOAD_URL_PATH =
   '/space/api/box/file/temporary_download_url'
-const ATTACHMENT_COVER_SIZES = [120, 360, 720, 1280] as const
 const PREVIEW_ENV: DatabaseEnv = 'preview'
 
 let databaseContextPromise: Promise<DatabaseContext> | null = null
@@ -87,6 +182,242 @@ function inferGatewayOrigin(): string {
   }
 }
 
+/** 按 functionKey 调用 AI Function，返回可判别联合结果（text/image_task/video_task）。
+ *
+ * 页面用 switch(result.type) 分支渲染：text 为聚合文本，image_task/video_task
+ * 需再用 getSiteAIFunctionTask 轮询。传 messages 走文本/多模态理解，
+ * 传 input 创建媒体任务；随后用 getSiteAIFunctionTask 轮询。
+ */
+export async function callSiteAIFunction(
+  params: CallSiteAIFunctionParams,
+): Promise<SiteAIFunctionResult> {
+  const result = await callRuntimeAIFunction(
+    params as unknown as RuntimeCallSiteAIFunctionParams,
+  )
+  if (params.input && !params.messages) {
+    return normalizeSiteAIMediaTask(result)
+  }
+  return result
+}
+
+/** 显式流式调用 AI Function（text/vision）：逐帧消费增量，卸载或取消时 destroy。 */
+export function invokeSiteAIFunctionStream(
+  params: InvokeSiteAIFunctionStreamParams,
+): SiteAIFunctionStreamHandle {
+  return invokeRuntimeAIFunctionStream(
+    params as unknown as RuntimeInvokeSiteAIFunctionStreamParams,
+  )
+}
+
+function readString(
+  source: Record<string, unknown>,
+  names: string[],
+): string | undefined {
+  for (const name of names) {
+    const value = source[name]
+    if (typeof value === 'string' && value.trim()) {
+      return value
+    }
+  }
+  return undefined
+}
+
+function readNumber(
+  source: Record<string, unknown>,
+  names: string[],
+): number | undefined {
+  for (const name of names) {
+    const value = source[name]
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      return value
+    }
+  }
+  return undefined
+}
+
+function readCapabilityType(
+  source: Record<string, unknown>,
+): SiteAIMediaTask['capabilityType'] {
+  const value = readString(source, [
+    'capabilityType',
+    'capability_type',
+    'CapabilityType',
+  ])
+  return value === 'image' || value === 'video' ? value : undefined
+}
+
+function normalizeImageAssets(value: unknown): SiteAIImageAsset[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined
+  }
+  return value.filter(isRecord).map((asset) => {
+    const size = readString(asset, ['size', 'Size'])
+    const token = readString(asset, ['token', 'Token'])
+    const url = readString(asset, ['url', 'URL'])
+    return {
+      safetyStatus:
+        readString(asset, ['safetyStatus', 'safety_status', 'SafetyStatus']) ??
+        '',
+      ...(size ? { size } : {}),
+      ...(token ? { token } : {}),
+      ...(url ? { url } : {}),
+    }
+  })
+}
+
+function normalizeVideoAsset(value: unknown): SiteAIVideoTask['videoAsset'] {
+  if (!isRecord(value)) {
+    return undefined
+  }
+  const duration =
+    value.durationSeconds ?? value.duration_seconds ?? value.DurationSeconds
+  const token = readString(value, ['token', 'Token'])
+  const url = readString(value, ['url', 'URL'])
+  return {
+    ...(typeof duration === 'number' ? { durationSeconds: duration } : {}),
+    ...(token ? { token } : {}),
+    ...(url ? { url } : {}),
+  }
+}
+
+function mediaTaskError(
+  message: string,
+  code = 'INVALID_AI_FUNCTION_TASK',
+): Error {
+  const error = new Error(message) as Error & { code: string }
+  error.name = 'SiteAIFunctionTaskError'
+  error.code = code
+  return error
+}
+
+/** 校验并归一化 AI Function 媒体任务响应。
+ *
+ * Channel SDK 新旧版本、OpenAPI 和父页面代理可能返回裸 task 或
+ * `{code,msg,data}` 包裹；页面只接受含合法 taskId/type/status 的任务。
+ */
+export function normalizeSiteAIMediaTask(value: unknown): SiteAIMediaTask {
+  if (!isRecord(value)) {
+    throw mediaTaskError('AI Function task response has an invalid structure')
+  }
+
+  const envelopeError = readEnvelopeError(value)
+  if (envelopeError) {
+    throw mediaTaskError(envelopeError.message, envelopeError.code)
+  }
+  if ('data' in value && value.data !== undefined) {
+    return normalizeSiteAIMediaTask(value.data)
+  }
+
+  const type = readString(value, ['type', 'Type'])
+  const taskId = readString(value, ['taskId', 'task_id', 'TaskID'])
+  const status = value.status ?? value.Status
+  if (
+    (type !== 'image_task' && type !== 'video_task') ||
+    !taskId ||
+    typeof status !== 'string' ||
+    !MEDIA_TASK_STATUSES.has(status)
+  ) {
+    throw mediaTaskError('AI Function task response has an invalid structure')
+  }
+
+  const imageAssets = normalizeImageAssets(
+    value.imageAssets ?? value.image_assets ?? value.ImageAssets,
+  )
+  const videoAsset = normalizeVideoAsset(
+    value.videoAsset ?? value.video_asset ?? value.VideoAsset,
+  )
+  const progress = readNumber(value, ['progress', 'Progress'])
+  const capabilityType = readCapabilityType(value)
+  const errCode = readString(value, ['errCode', 'err_code', 'ErrCode'])
+  const errMessage = readString(value, [
+    'errMessage',
+    'err_message',
+    'ErrMessage',
+  ])
+  return {
+    ...(capabilityType ? { capabilityType } : {}),
+    ...(errCode ? { errCode } : {}),
+    ...(errMessage ? { errMessage } : {}),
+    ...(imageAssets ? { imageAssets } : {}),
+    ...(progress !== undefined ? { progress } : {}),
+    ...(videoAsset ? { videoAsset } : {}),
+    requestId:
+      readString(value, ['requestId', 'request_id', 'RequestID']) ?? '',
+    status: status as SiteAIMediaTask['status'],
+    taskId,
+    type,
+  } as SiteAIMediaTask
+}
+
+function readEnvelopeError(
+  value: Record<string, unknown>,
+): { code: string; message: string } | undefined {
+  const directCode = value.code ?? value.Code
+  if (
+    (typeof directCode === 'number' && directCode !== 0) ||
+    (typeof directCode === 'string' && directCode && directCode !== '0')
+  ) {
+    return {
+      code: String(directCode),
+      message:
+        readString(value, ['msg', 'message', 'Message']) ??
+        'Failed to create the AI Function task',
+    }
+  }
+
+  const baseResp = value.BaseResp ?? value.base_resp ?? value.baseResp
+  if (!isRecord(baseResp)) {
+    return undefined
+  }
+
+  const statusCode =
+    baseResp.StatusCode ?? baseResp.status_code ?? baseResp.statusCode
+  if (
+    (typeof statusCode === 'number' && statusCode !== 0) ||
+    (typeof statusCode === 'string' && statusCode && statusCode !== '0')
+  ) {
+    return {
+      code: String(statusCode),
+      message:
+        readString(baseResp, [
+          'StatusMessage',
+          'status_message',
+          'statusMessage',
+        ]) ?? 'Failed to create the AI Function task',
+    }
+  }
+  return undefined
+}
+
+export function hasRunnableMediaTask(
+  task: SiteAIMediaTask,
+): task is SiteAIMediaTask & { taskId: string } {
+  return (
+    Boolean(task.taskId.trim()) &&
+    (task.status === 'queued' || task.status === 'running')
+  )
+}
+
+/** 提交文生图或文生视频任务，返回封装后的 taskId 与初始状态。 */
+export async function createSiteAIFunctionTask(
+  params: CallSiteAIFunctionParams,
+): Promise<SiteAIMediaTask> {
+  return normalizeSiteAIMediaTask(await createRuntimeAIFunctionTask(params))
+}
+
+/** 轮询文生图或文生视频任务进度与最终资源。 */
+export async function getSiteAIFunctionTask(
+  functionKey: string,
+  taskId: string,
+): Promise<SiteAIMediaTask> {
+  if (!taskId.trim()) {
+    throw mediaTaskError('AI Function task ID must not be empty')
+  }
+  return normalizeSiteAIMediaTask(
+    await getRuntimeAIFunctionTask(functionKey, taskId),
+  )
+}
+
 /** 从产物托管路径推断当前应用 token 与运行环境。
  *
  * 这是宿主未下发上下文时的兜底：BaseApp 形态下 site 与 BaseApp 共用同一个 token，
@@ -172,7 +503,10 @@ export async function resolveDatabaseContext(): Promise<DatabaseContext> {
       host = readHostDatabaseContext(await siteRuntime.getRuntimeContext())
     } catch (error) {
       // 宿主未实现或握手尚未完成时退回路径推断，不阻断业务。
-      console.warn('读取宿主 Runtime 上下文失败，回退产物路径推断', error)
+      console.warn(
+        'Could not read the host Runtime context; inferring it from the artifact path',
+        error,
+      )
     }
 
     const context: DatabaseContext = {
@@ -183,7 +517,7 @@ export async function resolveDatabaseContext(): Promise<DatabaseContext> {
 
     if (!context.token) {
       console.error(
-        '未能确定应用 token：宿主未下发 siteToken，且当前路径不符合产物托管规则',
+        'Cannot determine the app token: the host did not provide siteToken and the current path does not match an artifact path',
       )
     }
 
@@ -206,7 +540,6 @@ function hasCompleteRef(ref: DatabaseAttachmentRef): boolean {
   )
 }
 
-/** baseAppToken 把附件鉴权绑定到应用；省略会退回底表权限判定并导致访客被拒。 */
 function buildAttachmentExtra(
   context: DatabaseContext,
   ref: DatabaseAttachmentRef,
@@ -217,40 +550,76 @@ function buildAttachmentExtra(
       attachments: {
         [ref.fieldId]: { [ref.recordId]: [ref.fileToken] },
       },
-      baseAppToken: context.token,
+      siteToken: context.token,
+      siteEnv: context.env,
     },
   })
 }
 
-/** 封面由浏览器直连网关获取，必须是绝对 URL；尺寸向上匹配服务端档位。
- * 构造 URL 不会检查附件是否挂载成功，不能用于确认写入结果。
- *
- * @returns 可直接交给 img.src 的地址；上下文或附件位置不完整时返回空字符串。
+function attachmentRequestError(operation: string, cause: unknown): Error {
+  // Errors from the SDK can carry actionable host guidance and a distinct type.
+  if (cause instanceof Error) return cause
+  const rawCode = isRecord(cause) ? cause.code : undefined
+  const code =
+    typeof rawCode === 'string' || typeof rawCode === 'number'
+      ? String(rawCode)
+      : ''
+  const summary =
+    code === 'REQUEST_TIMEOUT' || code === '10005'
+      ? `${operation} timed out`
+      : `${operation} failed`
+  return Object.assign(
+    new Error(`${summary}${code ? ` (code ${code})` : ''}`),
+    {
+      cause,
+      ...(code ? { code } : {}),
+    },
+  )
+}
+
+/** 宿主用当前访问者身份同源取图，返回可创建本地 URL 的图片字节。
+ * 调用方在替换或卸载时取消请求并释放自己创建的 Blob URL。
  */
-export function buildAttachmentCoverUrl(
-  context: DatabaseContext,
+export async function fetchAttachmentCover(
   ref: DatabaseAttachmentRef,
   size = 360,
-): string {
-  if (!context.gatewayOrigin || !context.token || !hasCompleteRef(ref)) {
-    return ''
+  options: { signal?: AbortSignal } = {},
+): Promise<Blob> {
+  options.signal?.throwIfAborted()
+  if (!hasCompleteRef(ref) || !Number.isFinite(size) || size <= 0) {
+    throw new Error('Attachment location or image size is invalid')
   }
-
-  const coverSize =
-    ATTACHMENT_COVER_SIZES.find((candidate) => candidate >= size) ??
-    ATTACHMENT_COVER_SIZES[ATTACHMENT_COVER_SIZES.length - 1]
-  const searchParams = new URLSearchParams({
+  const context = await resolveDatabaseContext()
+  options.signal?.throwIfAborted()
+  if (!context.token)
+    throw new Error('Cannot load the attachment image without an app token')
+  const matchedSize =
+    [120, 360, 720, 1280].find((candidate) => candidate >= size) ?? 1280
+  const query = new URLSearchParams({
     extra: buildAttachmentExtra(context, ref),
-    width: String(coverSize),
-    height: String(coverSize),
+    width: String(matchedSize),
+    height: String(matchedSize),
     policy: 'allow_up',
     fallback_source: '1',
   })
-
-  return (
-    `${context.gatewayOrigin}${ATTACHMENT_COVER_PATH}` +
-    `${encodeURIComponent(ref.fileToken)}?${searchParams.toString()}`
-  )
+  const response = await invokeBinaryHttp({
+    url: `/space/api/box/stream/download/v2/cover/${encodeURIComponent(ref.fileToken)}?${query}`,
+    init: { method: 'GET', responseType: 'arrayBuffer', timeoutMs: 45_000 },
+    signal: options.signal,
+  }).catch((cause: unknown) => {
+    throw attachmentRequestError('Attachment image request', cause)
+  })
+  if (!response.ok) {
+    const logId = response.headers.get('x-tt-logid')
+    throw new Error(
+      `Failed to load attachment image: HTTP ${response.status}${logId ? `, LogID ${logId}` : ''}`,
+    )
+  }
+  const blob = await response.blob()
+  if (!blob.size || !blob.type.startsWith('image/')) {
+    throw new Error('The host did not return a valid image')
+  }
+  return blob
 }
 
 /** 经父页面 bridge 取短时效自证链接；原文件由浏览器下载，不进入页面 JavaScript。
@@ -263,11 +632,15 @@ export async function fetchAttachmentDownloadUrl(
   ref: DatabaseAttachmentRef,
 ): Promise<string> {
   if (!context.token) {
-    throw new Error('应用 token 未确定，无法获取附件下载链接')
+    throw new Error(
+      'Cannot get an attachment download URL without an app token',
+    )
   }
 
   if (!hasCompleteRef(ref)) {
-    throw new Error('附件位置不完整，无法获取下载链接')
+    throw new Error(
+      'Cannot get an attachment download URL: the attachment location is incomplete',
+    )
   }
 
   const response = await siteRuntimeFetch(ATTACHMENT_DOWNLOAD_URL_PATH, {
@@ -277,20 +650,48 @@ export async function fetchAttachmentDownloadUrl(
     }),
     headers: { 'content-type': 'application/json' },
     method: 'POST',
+  }).catch((cause: unknown) => {
+    throw attachmentRequestError('Attachment download URL request', cause)
   })
 
+  const logId = response.headers?.get('x-tt-logid')?.trim()
+  let body: unknown
+  try {
+    body = await response.json()
+  } catch {
+    throw new Error(
+      response.ok
+        ? `Attachment download URL response is not valid JSON${logId ? `, LogID ${logId}` : ''}`
+        : `Failed to get attachment download URL: HTTP ${response.status}${logId ? `, LogID ${logId}` : ''}`,
+    )
+  }
+
+  const code = isRecord(body) ? body.code : undefined
+  if (
+    (typeof code === 'number' && code !== 0) ||
+    (typeof code === 'string' && code.trim() !== '' && code.trim() !== '0')
+  ) {
+    const error = new Error(
+      `Attachment service could not provide a download URL (code ${String(code)}${logId ? `, LogID ${logId}` : ''})`,
+    )
+    throw Object.assign(error, { code: String(code), cause: body })
+  }
+
   if (!response.ok) {
-    throw new Error(`附件下载链接获取失败：HTTP ${response.status}`)
+    throw new Error(
+      `Failed to get attachment download URL: HTTP ${response.status}${logId ? `, LogID ${logId}` : ''}`,
+    )
   }
 
-  const body: unknown = await response.json()
   const url =
     isRecord(body) && isRecord(body.data) && typeof body.data.url === 'string'
       ? body.data.url.trim()
       : ''
 
   if (!url) {
-    throw new Error('附件下载链接获取失败：响应缺少 data.url')
+    throw new Error(
+      `Attachment download URL response is missing data.url${logId ? `, LogID ${logId}` : ''}`,
+    )
   }
 
   return url
@@ -299,19 +700,11 @@ export async function fetchAttachmentDownloadUrl(
 /** 构造运行态读取应用信息的统一网关地址。
  *
  * @param context 当前应用上下文。
- * @param withChatbot 是否附带项目绑定的 chatbot 列表。
  * @returns GetInvokeProject 的同源相对路径。
  */
-export function buildDatabaseInvokeGetPath(
-  context: DatabaseContext,
-  withChatbot: boolean,
-): string {
+export function buildDatabaseInvokeGetPath(context: DatabaseContext): string {
   const searchParams = new URLSearchParams()
 
-  if (withChatbot) {
-    searchParams.set('withChatbot', 'true')
-  }
-
   if (context.env === PREVIEW_ENV) {
     searchParams.set('env', PREVIEW_ENV)
   }
@@ -337,7 +730,7 @@ export function buildDatabaseInvokeFunctionPath(
 ): string {
   if (!FUNCTION_ID_PATTERN.test(functionId)) {
     throw new TypeError(
-      `functionId ${functionId} 不满足命名约束 ${String(FUNCTION_ID_PATTERN)}`,
+      `functionId ${functionId} does not match the required pattern ${String(FUNCTION_ID_PATTERN)}`,
     )
   }
 
@@ -353,23 +746,31 @@ export function buildDatabaseInvokeFunctionPath(
 /** 调用应用 Function。
  *
  * 请求经父页面同源代理发往统一网关；整个请求体即 payload，业务参数包在 params 下。
- * 目标环境只走 query 参数 env：服务端 resolveProjectEnv 显式入参优先，且
- * cloneBaseAppHeaders 会剥掉入站的 x-project-env 后按归一化 env 重写，
- * 再带同名 Header 属于重复下发。
+ * 目标环境由 query 参数 env 指定，不重复添加环境 Header。
  * 4xx/5xx 直接抛错，业务码由调用方按 operation 契约校验一次顶层 code。
  *
  * @param functionId Base Database Function ID。
- * @param params 函数入参：SQL Function 用数组，FaaS 用业务对象。
+ * @param params 函数入参：Database Function 用数组，FaaS 用业务对象。
  * @returns 统一包裹的函数响应。
  */
+export type DatabaseFunctionInvocation<Inputs extends object> = [
+  Extract<keyof Inputs, string>,
+] extends [never]
+  ? [functionId: never, params: never]
+  : {
+      [FunctionId in Extract<keyof Inputs, string>]: [
+        functionId: FunctionId,
+        params: Inputs[FunctionId],
+      ]
+    }[Extract<keyof Inputs, string>]
+
 export async function invokeDatabaseFunction<Data = unknown>(
-  functionId: string,
-  params?: unknown,
+  ...[functionId, params]: DatabaseFunctionInvocation<DatabaseFunctionInputMap>
 ): Promise<DatabaseFunctionResponse<Data>> {
   const context = await resolveDatabaseContext()
 
   if (!context.token) {
-    throw new Error(`应用 token 未确定，无法调用 Function ${functionId}`)
+    throw new Error(`Cannot invoke Function ${functionId} without an app token`)
   }
 
   const response = await invokeHttp({
@@ -382,8 +783,40 @@ export async function invokeDatabaseFunction<Data = unknown>(
   })
 
   if (!response.ok) {
-    throw new Error(`Function ${functionId} 调用失败：HTTP ${response.status}`)
+    throw new Error(
+      `Function ${functionId} request failed: HTTP ${response.status}`,
+    )
   }
 
   return (await response.json()) as DatabaseFunctionResponse<Data>
 }
+
+/** 每组参数应用同一份已发布 Mutation 声明；总记录数最多 200。 */
+export async function invokeDatabaseMutationBatch<Data = unknown>(
+  functionId: string,
+  parameterGroups: unknown[][],
+): Promise<DatabaseFunctionResponse<Data>> {
+  if (
+    !Array.isArray(parameterGroups) ||
+    parameterGroups.length < 1 ||
+    parameterGroups.length > 200 ||
+    parameterGroups.some((params) => !Array.isArray(params))
+  ) {
+    throw new TypeError('Mutation batch requires 1 to 200 parameter arrays')
+  }
+  const context = await resolveDatabaseContext()
+  if (!context.token) throw new Error('应用 token 未确定，无法调用 Mutation')
+  const response = await invokeHttp({
+    url: buildDatabaseInvokeFunctionPath(context, functionId),
+    init: {
+      body: JSON.stringify({
+        batch: parameterGroups.map((params) => ({ params })),
+      }),
+      headers: { 'content-type': 'application/json' },
+      method: 'POST',
+    },
+  })
+  if (!response.ok)
+    throw new Error(`Mutation 调用失败：HTTP ${response.status}`)
+  return (await response.json()) as DatabaseFunctionResponse<Data>
+}