@lark-base-open/base-database-app-sdk 0.0.0-stage → 0.0.1-alpha.0

package/docs/exports.md

@@ -0,0 +1,39 @@
+# 公开导出清单
+
+由 package.json exports 指向的实际 dist ESM 与 TypeScript 声明生成；在 SDK 源码仓运行 npm run docs:exports 更新，npm test 校验。server/shared 另提供 CJS；CSS 入口为 /page/styles.css。没有根入口或源码通配入口。
+
+## page
+
+值：`AttachmentImage`、`BaseAppProvider`、`CAPABILITY_CATALOG`、`CapabilityUnavailableError`、`DatabaseUserMenu`、`DiagnosticCode`、`FloatingButton`、`SDKError`、`SITE_RUNTIME_PROTOCOL_VERSION`、`SiteChatbotStreamAdapter`、`SiteChatbotStreamError`、`SiteRuntimeApi`、`SiteRuntimeClient`、`SiteRuntimeErrorCode`、`SiteRuntimeEvent`、`SiteRuntimeFunction`、`SiteRuntimeInvocationError`、`UiLanguageContext`、`UserSelectorEditor`、`UserSelectorPanel`、`buildAttachmentCoverUrl`、`buildDatabaseInvokeFunctionPath`、`buildDatabaseInvokeGetPath`、`callSiteAIFunction`、`classifyRuntimeError`、`createSiteAIFunctionTask`、`createSiteRuntimeClient`、`createSiteRuntimeFetch`、`fetch`、`fetchAttachmentCover`、`fetchAttachmentDownloadUrl`、`getCapabilities`、`getCurrentUser`、`getDatabaseContext`、`getRuntimeCapabilities`、`getSiteAIFunctionTask`、`getUiLanguage`、`getUiLocale`、`hasCapability`、`hasRunnableMediaTask`、`initializeUiLanguage`、`installLinkGuard`、`invokeApi`、`invokeDatabaseFunction`、`invokeDatabaseMutationBatch`、`invokeHttp`、`invokeSiteAIFunctionStream`、`isValidSiteFunctionName`、`logout`、`normalizeSiteAIMediaTask`、`openAttachmentDownload`、`openLink`、`queryCapability`、`readCapabilities`、`readSiteAITextDelta`、`requestEdit`、`requireCapability`、`resolveDatabaseContext`、`selectUiLanguage`、`siteRuntime`、`startBaseApp`、`uploadAttachment`、`useBaseApp`、`useOptionalBaseApp`、`useUiLanguage`。
+
+类型与值完整清单：`AttachmentImage`、`BaseAppContextValue`、`BaseAppHandle`、`BaseAppProvider`、`CAPABILITY_CATALOG`、`CallSiteAIFunctionParams`、`CapabilityContext`、`CapabilityDescriptor`、`CapabilityMap`、`CapabilityName`、`CapabilityQueryResult`、`CapabilityUnavailableError`、`CapabilityUnavailableReason`、`DatabaseAttachmentRef`、`DatabaseAudience`、`DatabaseContext`、`DatabaseEnv`、`DatabaseFunctionInputMap`、`DatabaseFunctionInvocation`、`DatabaseFunctionResponse`、`DatabaseUserMenu`、`DatabaseUserMenuProps`、`DevelopmentPairChallenge`、`DevelopmentPairProof`、`DiagnosticCategory`、`DiagnosticCode`、`FloatingButton`、`FloatingButtonProps`、`FunctionEnvelope`、`FunctionInputMap`、`FunctionMap`、`InvokeSiteAIFunctionStreamParams`、`JsonValue`、`LinkGuardOptions`、`RuntimeCapabilities`、`RuntimeChannel`、`RuntimeContextReader`、`RuntimeDiagnostic`、`SDKError`、`SDKErrorOptions`、`SITE_RUNTIME_PROTOCOL_VERSION`、`SiteAIAudioContentPart`、`SiteAICapabilityType`、`SiteAIFileContentPart`、`SiteAIFunctionError`、`SiteAIFunctionOptions`、`SiteAIFunctionResult`、`SiteAIFunctionStreamCloseRequest`、`SiteAIFunctionStreamDone`、`SiteAIFunctionStreamError`、`SiteAIFunctionStreamHandle`、`SiteAIFunctionStreamMessage`、`SiteAIFunctionStreamOpenRequest`、`SiteAIFunctionVariables`、`SiteAIImageAsset`、`SiteAIImageContentPart`、`SiteAIImageGenerationInput`、`SiteAIImageTask`、`SiteAIMediaTask`、`SiteAIMediaTaskBase`、`SiteAIMessage`、`SiteAIMessageContentPart`、`SiteAIStreamDelta`、`SiteAIStreamMessageParam`、`SiteAITaskStatus`、`SiteAITextContentPart`、`SiteAITextDelta`、`SiteAITextMessageParam`、`SiteAIUserMessageParam`、`SiteAIVideoAsset`、`SiteAIVideoContentPart`、`SiteAIVideoGenerationInput`、`SiteAIVideoTask`、`SiteAttachmentTarget`、`SiteAttachmentUploadCancelRequest`、`SiteAttachmentUploadOptions`、`SiteAttachmentUploadPayload`、`SiteAttachmentUploadProgress`、`SiteAttachmentUploadRequest`、`SiteAttachmentUploadResult`、`SiteChatbotStreamAdapter`、`SiteChatbotStreamCloseRequest`、`SiteChatbotStreamError`、`SiteChatbotStreamMessage`、`SiteChatbotStreamOpenRequest`、`SiteFunctionDefinition`、`SiteFunctionInvokeRequest`、`SiteHttpCancelRequest`、`SiteHttpMethod`、`SiteHttpRequest`、`SiteHttpRequestInit`、`SiteHttpRequestOptions`、`SiteHttpResponse`、`SiteHttpResponseType`、`SiteOpenLinkRequest`、`SiteOpenLinkResult`、`SiteProjectEnv`、`SiteRuntimeApi`、`SiteRuntimeClient`、`SiteRuntimeContext`、`SiteRuntimeError`、`SiteRuntimeErrorCode`、`SiteRuntimeEvent`、`SiteRuntimeFunction`、`SiteRuntimeInvocationError`、`SiteRuntimeLoadFailedEvent`、`SiteRuntimeModeChangedEvent`、`SiteRuntimeReadyEvent`、`SiteRuntimeUserInfo`、`StartBaseAppOptions`、`UiLanguage`、`UiLanguageContext`、`User`、`UserSelectorAction`、`UserSelectorEditor`、`UserSelectorEditorProps`、`UserSelectorEditorValue`、`UserSelectorMode`、`UserSelectorPanel`、`UserSelectorPanelProps`、`UserSelectorSearchAction`、`UserSelectorValue`、`WriteResult`、`buildAttachmentCoverUrl`、`buildDatabaseInvokeFunctionPath`、`buildDatabaseInvokeGetPath`、`callSiteAIFunction`、`classifyRuntimeError`、`createSiteAIFunctionTask`、`createSiteRuntimeClient`、`createSiteRuntimeFetch`、`fetch`、`fetchAttachmentCover`、`fetchAttachmentDownloadUrl`、`getCapabilities`、`getCurrentUser`、`getDatabaseContext`、`getRuntimeCapabilities`、`getSiteAIFunctionTask`、`getUiLanguage`、`getUiLocale`、`hasCapability`、`hasRunnableMediaTask`、`initializeUiLanguage`、`installLinkGuard`、`invokeApi`、`invokeDatabaseFunction`、`invokeDatabaseMutationBatch`、`invokeHttp`、`invokeSiteAIFunctionStream`、`isValidSiteFunctionName`、`logout`、`normalizeSiteAIMediaTask`、`openAttachmentDownload`、`openLink`、`queryCapability`、`readCapabilities`、`readSiteAITextDelta`、`requestEdit`、`requireCapability`、`resolveDatabaseContext`、`selectUiLanguage`、`siteRuntime`、`startBaseApp`、`uploadAttachment`、`useBaseApp`、`useOptionalBaseApp`、`useUiLanguage`。
+
+## server
+
+值：`SDKError`、`bindFunctionRuntime`、`createServerContext`、`defineFunction`、`normalizeRecordsResult`。
+
+类型与值完整清单：`AttachmentInput`、`Attachments`、`DefineFunctionOptions`、`DefinedFunction`、`DiagnosticCategory`、`Fields`、`FunctionEnvelope`、`FunctionResult`、`JsonValue`、`LegacyFunctionHandler`、`RawFunctionContext`、`RecordsClient`、`RecordsOperation`、`RecordsResultRequest`、`RuntimeBuildProfile`、`RuntimeDiagnostic`、`SDKError`、`SDKErrorOptions`、`ServerContext`、`Target`、`WriteResult`、`bindFunctionRuntime`、`createServerContext`、`defineFunction`、`normalizeRecordsResult`。
+
+## shared
+
+值：`CAPABILITY_CATALOG`、`CapabilityUnavailableError`、`DiagnosticCode`、`SDKError`、`classifyRuntimeError`。
+
+类型与值完整清单：`CAPABILITY_CATALOG`、`CapabilityContext`、`CapabilityDescriptor`、`CapabilityMap`、`CapabilityName`、`CapabilityQueryResult`、`CapabilityUnavailableError`、`CapabilityUnavailableReason`、`DiagnosticCategory`、`DiagnosticCode`、`FunctionEnvelope`、`JsonValue`、`RuntimeCapabilities`、`RuntimeDiagnostic`、`SDKError`、`SDKErrorOptions`、`WriteResult`、`classifyRuntimeError`。
+
+## testing
+
+值：`DEFAULT_SITE_HTTP_BRIDGE_ALLOWLIST`、`createHttpHandlers`、`createMockHost`。
+
+类型与值完整清单：`DEFAULT_SITE_HTTP_BRIDGE_ALLOWLIST`、`HttpFixture`、`MockApi`、`MockCall`、`MockHandlerContext`、`MockHostOptions`、`createHttpHandlers`、`createMockHost`。
+
+## components
+
+值：`AttachmentImage`、`BaseAppProvider`、`DatabaseUserMenu`、`FloatingButton`、`UiLanguageContext`、`UserSelectorEditor`、`UserSelectorPanel`、`getUiLanguage`、`getUiLocale`、`initializeUiLanguage`、`selectUiLanguage`、`useBaseApp`、`useOptionalBaseApp`、`useUiLanguage`。
+
+类型与值完整清单：`AttachmentImage`、`BaseAppContextValue`、`BaseAppProvider`、`DatabaseAudience`、`DatabaseUserMenu`、`DatabaseUserMenuProps`、`FloatingButton`、`FloatingButtonProps`、`UiLanguage`、`UiLanguageContext`、`User`、`UserSelectorAction`、`UserSelectorEditor`、`UserSelectorEditorProps`、`UserSelectorEditorValue`、`UserSelectorMode`、`UserSelectorPanel`、`UserSelectorPanelProps`、`UserSelectorSearchAction`、`UserSelectorValue`、`getUiLanguage`、`getUiLocale`、`initializeUiLanguage`、`selectUiLanguage`、`useBaseApp`、`useOptionalBaseApp`、`useUiLanguage`。
+
+## vite
+
+值：`baseAppDevelopmentPairingPlugin`。
+
+类型与值完整清单：`baseAppDevelopmentPairingPlugin`。

package/docs/page.md

@@ -0,0 +1,101 @@
+# 页面运行时
+
+从 `@lark-base-open/base-database-app-sdk/page` 导入。协议通信复用 channel/runtime；SDK 另提供能力感知链接拦截、老模板数据库/AI 兼容适配、启动管理与平台组件。[`siteRuntime`](exports.md#page) 是默认单例；单测可把模拟 channel 交给 [`createSiteRuntimeClient`](exports.md#page)。
+
+生命周期：首屏挂载后调用 `siteRuntime.ready()`，启动失败调用 `reportLoadFailed(code)`；不要等业务数据加载完成才上报 ready。`getRuntimeContext()` 返回 locale/colorScheme/mode/protocolVersion，可选 env/siteToken/capabilities；缺 env/token 的旧宿主由 SDK 的 getDatabaseContext/resolveDatabaseContext 保留路径兜底。
+[`getCurrentUser`](exports.md#page)、[`logout`](exports.md#page)、[`requestEdit`](exports.md#page)、`siteRuntime.subscribeModeChanged` 保持 channel 返回语义。
+
+## HTTP 代理
+
+<!-- example: http.ts -->
+```ts
+import { invokeHttp, fetch as hostFetch } from '@lark-base-open/base-database-app-sdk/page';
+export async function loadUser(signal: AbortSignal) {
+  const response = await invokeHttp({ url: '/space/api/user', signal });
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  const data: unknown = await response.json();
+  return data;
+}
+export async function loadWithFetch() {
+  const response = await hostFetch('/space/api/user');
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  return response.json() as Promise<unknown>;
+}
+```
+
+业务 HTTP 经宿主代理，只接受单个 `/` 开头的相对地址和宿主配置白名单；默认清单见 testing.md。绝对地址、跨源、目录穿越、反斜杠、fragment、控制字符被拒绝。
+方法仅 DELETE/GET/PATCH/POST/PUT；body 只支持字符串，GET 不能有 body。禁止透传 Authorization、Connection、Content-Length、Cookie、Host、Origin、Proxy-Authorization、Referer、Transfer-Encoding，以及 sec-/x-forwarded-/rpc- 前缀请求头。身份由宿主注入。
+4xx/5xx 正常返回 Response，必须自行检查 ok。文本与 arrayBuffer 使用明确的 responseType；旧宿主不支持二进制时失败，不降级为文本或直连。超时默认 30 秒、最高 60 秒；取消不证明远端写入已撤销，写入失败不得盲目重试。
+
+## 外链
+
+<!-- example: link.ts -->
+```ts
+import { siteRuntime, hasCapability, openLink } from '@lark-base-open/base-database-app-sdk/page';
+import type { SiteRuntimeContext } from '@lark-base-open/base-database-app-sdk/page';
+export async function canOpenLink() {
+  const context: SiteRuntimeContext = await siteRuntime.getRuntimeContext();
+  return hasCapability(context, 'link.open');
+}
+// 在点击之前查询能力。用户点击时立即调用，避免因等待查询失去用户激活。
+export function onSupportedLinkClick(url: string) {
+  return openLink(url);
+}
+```
+
+[`openLink`](exports.md#page) 支持 http/https/mailto/tel；宿主拒绝 javascript/data/file 等协议。HTTP(S) 必须经过宿主 seclink，服务不可用时失败关闭；opened 只代表宿主已提交导航，不保证弹窗可见。
+`installLinkGuard()` 同步返回 cleanup，内部异步查询能力；查询前、查询失败或显式能力表缺 link.open 时不拦截；无能力字段采用 host-baseline-84afb07 并安装拦截。onDiagnostic 收到脱敏提示，默认 console.warn。应在页面启动时安装，而不是点击后才查询。支持能力时沿用 channel guard：捕获外链、_blank 与中键；download/hash/普通同源导航不接管。cleanup 也阻止迟到查询安装。
+不要将 guard 当作任意 HTML 的安全过滤器；尤其不允许把不可信字符串直接设为 href。浏览器原生行为仍受 iframe sandbox 限制。
+
+## 附件字节上传
+
+<!-- example: upload.ts -->
+```ts
+import { requireCapability, siteRuntime } from '@lark-base-open/base-database-app-sdk/page';
+export async function upload(baseToken: string, tableId: string, file: File) {
+  await requireCapability('attachment.upload');
+  let dimensions: { image_width: number; image_height: number } | undefined;
+  if (!file.type) throw new Error('无法识别文件类型');
+  if (file.type.startsWith('image/')) {
+    const url = URL.createObjectURL(file);
+    try {
+      const image = new Image(); image.src = url; await image.decode();
+      if (image.naturalWidth <= 0 || image.naturalHeight <= 0) throw new Error('无法读取图片尺寸');
+      dimensions = { image_width: image.naturalWidth, image_height: image.naturalHeight };
+    } finally { URL.revokeObjectURL(url); }
+  }
+  const result = await siteRuntime.uploadAttachment({ baseToken, tableId, file,
+    onProgress: ({ loaded, total }) => console.info(`${loaded}/${total}`) });
+  return { file_token: result.fileToken, ...dimensions };
+  // 下一步经业务 FaaS 挂载；上传成功不代表单元格写入成功。
+}
+```
+
+baseToken/tableId 来自 Catalog，必须成对属于应用绑定；不传 fieldId。只接受非空 File，上限 2 GiB，不接受 Blob；普通 HTTP bridge 不上传文件。返回 fileToken 是资源标识，name/size/mimeType 是客户端信息；持久化权威值以服务端为准。临时下载 URL 不持久化或写入日志。
+进度以回调 total 为分母，100% 不等于完成。首条进度之后连续 120 秒无新进度会报告停滞，未收到首条进度可能仍在排队；超时不是上传未发生的证明。先保留 token 并核对结果，不自动重传。
+上传不会自动挂载到单元格。图片宽高应从原始 File 解码后透传给业务 FaaS；移除附件引用不等于删除云盘文件。展示使用 /page 或 /components 的 [`AttachmentImage`](exports.md#page)；[`fetchAttachmentCover`](exports.md#page) 返回 Blob，[`fetchAttachmentDownloadUrl`](exports.md#page) 返回临时链接，参数及完整附件坐标见 [兼容 API](compat.md) 与 [组件](components.md)。写入由业务 FaaS 调用 /server 的 ctx.records，见 [服务端 SDK](server.md)；页面不导入 server。附件业务规则见 随 CLI 安装的 lark-base-database Skill 中的「Skill 文件传输」（references/file-transfer.md）。
+
+## 其他兼容导出
+
+[`invokeApi`](exports.md#page) 使用 [`FunctionMap`](exports.md#page) 定义的 function 点号路径，不是 Database Function ID。
+[`fetch`](exports.md#page)/[`invokeHttp`](exports.md#page) 返回 Response。[`callSiteAIFunction`](exports.md#page)、任务与流式 API、[`SiteChatbotStreamAdapter`](exports.md#page) 保持兼容导出；已有返回联合类型和事件语义不变。
+[`invokeDatabaseFunction`](exports.md#page)、[`invokeDatabaseMutationBatch`](exports.md#page)、[`resolveDatabaseContext`](exports.md#page) 已由 /page 提供，保持老模板语义，见 [兼容 API](compat.md)。[`invokeApi`](exports.md#page) 的 function 点号路径不能替代 Database Function ID。
+
+SDK 文档说明本版本 API、组件、兼容语义与可编译示例。业务规则、服务端契约、Mutation 结果、CLI 命令与发布流程，请查阅 [@lark-base-open/base-database-cli](https://www.npmjs.com/package/@lark-base-open/base-database-cli) 随包安装的 lark-base-database Skill 及其 references。升级 CLI 时以该版本随包 Skill 为准。
+
+## 本机开发上下文
+
+独立路由为 `https://<宿主>/baseapp/dev/<siteToken>/<port>`，端口仅限 43100–43109，
+本地 origin 固定为 `http://127.0.0.1:<port>`，加载根路径 `/`。使用 CLI 输出的带配对令牌片段链接打开。
+宿主检查编辑权限并完成挑战配对，通过后直接进入应用，常驻提示本机地址、preview 环境与写入范围；不再提供应用内确认页。
+浏览器原生“本地网络访问”授权是访问 loopback 的前置条件：若浏览器提示，需允许当前宿主访问本机网络；此前已拒绝时到该站点的浏览器权限设置恢复。
+这项浏览器授权独立于应用内配对，不能由 SDK 代替用户授予。
+无令牌或非编辑者直接打开线上版本；复制地址栏链接给别人会自动打开线上版本。普通入口不加载 loopback。
+页面隐藏不销毁，聚焦与30秒轮询复查权限；离开、本地登出或检测到权限失效即回收；当前标签刷新复用 sessionStorage 令牌，但重新挑战配对。不调用服务端开发会话接口。
+
+`SiteRuntimeContext.development` 可选，结构为
+`{ localOrigin: string, projectEnv: 'preview', artifactVersion: string | null }`。
+本机页面没有平台发布制品版本时 `artifactVersion` 为 null；上下文不携带凭据。
+Function 仍通过宿主代理访问远端 preview，不能以该字段获取权限。
+main.tsx 在开发和生产都直接导入配置；Vite 插件仅提供服务端配对接口，不生成启动虚拟模块。
+入口是否可用由宿主环境 CSP 策略决定；普通宿主 CSP 不因开发模式而放宽。

package/docs/server.md

@@ -0,0 +1,92 @@
+# 服务端 SDK
+
+`server` 支持 Node ES2022 的 ESM 和 CJS，无 React、DOM 和 channel 运行依赖。类型消费者需要 Node 类型；Standard Schema 使用精确版本 `@standard-schema/spec@1.0.0` 的类型接口，不引入验证库运行时。Schema 可同步或异步，不要求实现 JSON Schema 转换。契约生成由 CLI 负责。
+
+`defineFunction({input, output, handler})` 保持 `(rawParams, context)` ABI。输入转换结果交给 handler，输出转换结果经过无损 JSON 检查，再返回 `{code:0,msg:'success',data}`。业务对象里的 code/data/msg 都是业务数据。void 业务请返回 null。拒绝 undefined、BigInt、非有限数、Date、循环、getter、Symbol、稀疏数组、方法和 toJSON；先由 Schema 转换成 JSON 值可通过。
+
+输入 issues 映射 400；输出 issues、校验器异常、非 JSON 输出及普通异常映射 500。[`SDKError`](exports.md#server) 可设置有限非零整数 wireCode，SDK_TIMEOUT 默认 504、SDK_CANCELLED 默认 499。safeMessage 必须是开发者提供的安全文案；不要传原始 error.message。结构化诊断仅记录码、字段路径、retryable、outcome，不记录校验消息或被拒值。网关可能脱敏 500，不能承诺客户端看到 SDK 字符串码。
+
+旧 faas-entry 对错误返回仍会构造 `{code,msg,data:{code,msg}}`；先判断外层 code，错误 data 不是输出契约。运行时实现不需要升级。跨 server/shared、ESM/CJS 的 [`SDKError`](exports.md#server) 用同版本 Symbol 标识识别。
+
+<!-- example: server.ts -->
+```ts
+import { z } from "zod";
+import {
+  defineFunction,
+  bindFunctionRuntime,
+} from "@lark-base-open/base-database-app-sdk/server";
+// 实际工程将 input/output 放独立 contract.ts，CLI 只提取 Schema 依赖图。
+const input = z.object({ title: z.string().min(1) });
+const ignored = z.object({
+  id: z.string(),
+  name: z.string(),
+  reason: z.string(),
+});
+const output = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("success"),
+    appliedIds: z.array(z.string()),
+    notFoundIds: z.tuple([]),
+    ignoredFields: z.tuple([]),
+    attachments: z.json().optional(),
+    noop: z.boolean().optional(),
+  }),
+  z.object({
+    status: z.literal("partial"),
+    appliedIds: z.array(z.string()),
+    notFoundIds: z.array(z.string()),
+    ignoredFields: z.array(ignored),
+    attachments: z.json().optional(),
+  }),
+  z.object({
+    status: z.literal("failed"),
+    code: z.string(),
+    upstreamCode: z.number().optional(),
+    retryable: z.literal(false),
+    appliedIds: z.tuple([]),
+  }),
+  z.object({
+    status: z.literal("unknown"),
+    code: z.string(),
+    retryable: z.literal(false),
+    requestedIds: z.array(z.string()).optional(),
+    logid: z.string().optional(),
+  }),
+]);
+const handler = defineFunction({
+  input,
+  output,
+  handler: (params, ctx) =>
+    ctx.records.create(
+      { baseToken: "baseFromCatalog", tableId: "tblFromCatalog" },
+      [{ title: params.title }],
+    ),
+});
+// 此绑定入口由 CLI 生成；业务 handler 不选择区域、不持有身份凭据。
+export default bindFunctionRuntime(handler, {
+  platformEnv: "online",
+  brand: "feishu",
+});
+```
+
+[`bindFunctionRuntime`](exports.md#server) 为每次调用复制 context 并添加私有非凭据 profile，不改全局或原 context。CLI 为模板 1/2 的 defineFunction 入口注入 profile 和 runtime 绑定；模板 1 从当前已验证账号品牌与工程 runtimeProfile 生成，模板 2 使用 generated/runtime-profile.ts。未绑定 profile 时 records 返回 SDK_RUNTIME_PROFILE_MISSING；不支持的环境/品牌返回 SDK_RUNTIME_PROFILE_UNSUPPORTED。online 支持 feishu/lark，pre、boe 仅支持 feishu。域名只是原 runtime 的路由标记，真实回调地址和身份仍由平台控制；SDK 不发身份头、不猜域、不跨区重试。
+
+| records 操作 | 参数与限制 |
+| --- | --- |
+| create | [`Target`](exports.md#server) + 1–200 个字段对象；返回 ID 必须逐条对应 |
+| update | [`Target`](exports.md#server) + record ID 到 patch 的映射，1–200 条；applied/notFound 必须完整、不重叠 |
+| delete | [`Target`](exports.md#server) + 1–200 个不同 record ID；applied 为回显减 notFound |
+| appendAttachments | record ID → 字段名或 ID → file_token/可选图片尺寸数组 |
+| removeAttachments | 同样的映射，数组项只允许 file_token |
+
+[`Target`](exports.md#server) 为 catalog 的 baseToken/tableId。record ID 校验 `^rec[A-Za-z0-9]{1,32}$`。附件最多 50 个 token，空字段数组和空记录映射被移除，全空本地 no-op。响应按 data.attachments 的字段 ID 读取，不以请求中的字段名猜测。
+
+统一 [`WriteResult`](exports.md#server)：success 含 appliedIds；partial 保留 appliedIds、notFoundIds 和 ignoredFields；本地校验/profile/发送前取消返回 failed；HTTP 401/403/404 及明确权限/不存在业务码（91403、1254302、1254043、1254044）返回 failed 并保留 upstreamCode；其余已发请求后的网络错误、超时、取消、业务错误或不完整回执返回 unknown。HTTP 200 也必须检查 body.code。SDK 不会盲目把下游错误码当作“确定未写入”。不拆批、不自动重试；取消不撤销写入。unknown 后应核对结果，附件保留已上传 token。仅实际响应含 logid 头才保留，记录回调通常没有该头。
+
+[兼容 API](compat.md) · [公开导出](exports.md)
+
+示例与测试使用精确固定的 Zod 4.2.1（devDependency），验证真实 Standard Schema 的转换、refine 与异步校验；SDK 的 server 产物不捆绑 Zod。消费此示例的工程需自行固定安装 Zod。
+
+SDK 的 ctx.records 方法和 [`WriteResult`](exports.md#server) 是本包 API；底层记录 payload、CellValue、Mutation 与服务端业务规范以 Skill 为唯一正文来源。
+
+SDK 文档说明本版本 API、组件、兼容语义与可编译示例。业务规则、服务端契约、Mutation 结果、CLI 命令与发布流程，请查阅 [@lark-base-open/base-database-cli](https://www.npmjs.com/package/@lark-base-open/base-database-cli) 随包安装的 lark-base-database Skill 及其 references。升级 CLI 时以该版本随包 Skill 为准。

package/docs/shared.md

@@ -0,0 +1,21 @@
+# 共享类型与诊断
+
+/shared 同时提供 ESM/CJS，不依赖 React、DOM 或 channel。提供 [`SDKError`](exports.md#shared)、[`SDKErrorOptions`](exports.md#shared)、[`FunctionEnvelope`](exports.md#shared)、[`WriteResult`](exports.md#shared)、[`JsonValue`](exports.md#shared)，以及能力目录、能力类型和 [`classifyRuntimeError`](exports.md#shared)；精确名单见 [导出清单](exports.md#shared)。
+
+[`FunctionEnvelope`](exports.md#shared) 是调用包裹类型；[`WriteResult`](exports.md#shared) 的 success/partial/failed/unknown 表示记录写入结果，见 [server](server.md)。[`JsonValue`](exports.md#shared) 描述 JSON 数据；类型断言不能替代 [`defineFunction`](exports.md#server) 的运行时校验。[`classifyRuntimeError`](exports.md#shared) 只按稳定错误码分类，不推断原始错误消息，也不证明写入是否发生。
+
+SDK 文档说明本版本 API、组件、兼容语义与可编译示例。业务规则、服务端契约、Mutation 结果、CLI 命令与发布流程，请查阅 [@lark-base-open/base-database-cli](https://www.npmjs.com/package/@lark-base-open/base-database-cli) 随包安装的 lark-base-database Skill 及其 references。升级 CLI 时以该版本随包 Skill 为准。
+
+<!-- example: shared.ts -->
+```ts
+import { classifyRuntimeError, type WriteResult } from '@lark-base-open/base-database-app-sdk/shared';
+export function writeMessage(result: WriteResult): string {
+  switch (result.status) {
+    case 'success': return `已写入 ${result.appliedIds.length} 条`;
+    case 'partial': return '部分完成，请检查缺失记录和忽略字段';
+    case 'failed': return '请求未发送，请修正输入或运行环境';
+    case 'unknown': return '结果待核对，请勿直接重试';
+  }
+}
+export const describeError = classifyRuntimeError;
+```

package/docs/start-base-app.md

@@ -0,0 +1,47 @@
+# 启动应用
+
+从 `/page` 导入 [`startBaseApp`](exports.md#page)，传入 `app: App`（React ComponentType），通过 `/page/styles.css` 加载组件样式。SDK 不认识业务 App 的路径，也不会在 Node 侧执行业务代码。返回 `{ ready, dispose }`；ready 是首次 React effect 提交后的宿主通知 Promise。调用者应处理 ready 拒绝，并在热替换或移除页面时 dispose。
+
+选项与默认值：root 为 `#root`（可传选择器或 HTMLElement）；strictMode、linkGuard、reportLifecycle、platformUI 均为 true。theme 为 host，取宿主 colorScheme；locale 为 host，取宿主语言，不支持的语言映射 en。locale 可显式设 zh/en/ja，theme 可设 light/dark。providers 接收 ReactNode 并返回包裹后的 ReactNode；slots.loading 与 slots.error 接受 React 组件，error 只收到安全 code。onDiagnostic 接收 SDK 的脱敏 [`RuntimeDiagnostic`](exports.md#page)。
+
+顺序：解析 root、发起 channel 上下文请求、能力感知链接拦截、Provider/错误边界/App、首次 effect 后 ready。StrictMode 不重复上报。启动错误报 APP_BOOT_FAILED；ready 之后的业务错误只交 onDiagnostic。root 缺失使 ready 拒绝，重复挂载同一 root 同步抛 APP_ALREADY_STARTED。dispose 幂等，卸载 React、退订 mode、清理链接拦截和 UI 缓存；ready 前 dispose 使 ready 拒绝 APP_DISPOSED。共享 channel 连接不销毁，以免影响同页面其他调用者。
+
+linkGuard:false 完全不安装拦截；能力不支持时 SDK 同样保持原生行为。reportLifecycle:false 不发 ready/load-failed，但 ready Promise 仍表达本地挂载结果。platformUI:false 隐藏默认悬浮按钮，不改变权限或宿主开发标识。关闭选项用于迁移中明确选择行为。
+
+开发与生产统一由 main.tsx 直接导入 base-app.config.ts 并调用 startBaseApp(options)，不使用虚拟入口。CLI 自动安装 `/vite` 的配对服务端中间件；HMR 不重配对，整页或 iframe 重载才配对。
+
+运行示例与构建类型检查位于包内 examples；SDK 尚未发布时只使用本批 tarball 验证，不代表 registry 已可安装。
+
+<!-- example: start-base-app.tsx -->
+```tsx
+import { startBaseApp } from '@lark-base-open/base-database-app-sdk/page';
+import '@lark-base-open/base-database-app-sdk/page/styles.css';
+function App() { return <main>订单工作台</main>; }
+export function mountApp() {
+  const app = startBaseApp({ app: App, locale: 'zh', theme: 'host' });
+  void app.ready.catch(() => console.warn('应用启动失败'));
+  return () => app.dispose(); // 卸载或 HMR 时调用。
+}
+```
+
+<!-- example: vite.ts -->
+```ts
+import { baseAppDevelopmentPairingPlugin } from '@lark-base-open/base-database-app-sdk/vite';
+export const plugins = [baseAppDevelopmentPairingPlugin()];
+```
+
+## 本地开发配对（FE1C）
+
+使用 CLI 输出的 `/baseapp/dev/<siteToken>/<port>#t=<令牌>` 打开；宿主读取后立刻移除片段并按站点、端口存当前标签 sessionStorage。复制地址栏链接给别人会自动打开线上版本。无令牌或非编辑者直接降级，有令牌但未连接/配对失败保持错误页。普通线上页面不启用此协议。
+
+访问本机服务前，浏览器可能要求当前宿主的原生“本地网络访问”授权；需在浏览器提示或站点权限设置中允许。它是浏览器安全前置，不是应用内确认页，也不由 SDK 自动授予；配对成功后应用直接进入。
+
+`development-pairing.json` 是 CLI、宿主和 SDK 的协议常量唯一来源；其他仓的镜像必须逐字段校验。CLI 每项目生成 32 字节随机数的 base64url 令牌，持久化并仅通过 `BASE_APP_DEV_PAIRING_TOKEN` 环境变量交给 Vite。`baseAppDevelopmentPairingPlugin()` 必须排在中间件链最前，令牌不进入客户端产物、日志或 NDJSON。
+
+插件在实际监听端口的 `http://127.0.0.1:43100` 至 `43109` 提供 `POST /__base_app/dev-pair`，请求体为 `{challenge}`（32 字节随机数的 base64url）。要求 Host 精确匹配监听地址；Origin 精确等于本机 origin，或无 Origin 时 Sec-Fetch-Site 为 same-origin。显式外域/null Origin 即使带 same-origin 也拒绝。响应无 CORS 头、禁止缓存；服务端按监听端口确定 origin，不读取请求体 origin。
+
+返回 `{proof}`，proof 为 `HMAC-SHA256(UTF8(令牌字符串), UTF8("base-app-dev-pair.v1\n" + localOrigin + "\n" + challenge))` 的 base64url。令牌不先 base64url 解码；宿主 WebCrypto 必须采用相同 key 字节。每次 channel 握手宿主生成新挑战，通过 `site.v1.development.pair` 调用 iframe，iframe 同源 fetch 后返回 proof；宿主常量时间验证通过，广播 `site.v1.development.paired` 的 `{challenge}`。SDK 启动和 runtime Promise 方法等待匹配的 accepted，宿主仍负责在配对前拒绝所有业务调用（不能依赖客户端 gate 作为安全边界）。旧 SDK 不支持配对时宿主失败关闭并要求升级。
+
+Vite HMR 不关闭 gate，不重新配对；仅整页或 iframe 重载重新配对。普通页面与旧 channel 宿主/夹具组合保留原行为。
+
+平台 UI 使用 @tanstack/react-query，BaseAppProvider 管理缓存生命周期和应用/环境/身份隔离；它是组件的必需 peer。React/ReactDOM peer 接受 ^19.2.0，业务可按锁文件使用兼容补丁版本。server/shared 没有 React 运行时导入。

package/docs/testing.md

@@ -0,0 +1,57 @@
+# 测试替身
+
+安装可选 peer msw@2.11.6 后从 SDK/testing 导入。单元/组件测试使用 [`createMockHost`](exports.md#testing)().channel；不需要手工 mock channel 模块。替身无真实身份、无后端或 seclink 服务，不作为开发主路径或真实授权证明。开发时应使用真实宿主会话。
+
+<!-- example: mock.ts -->
+```ts
+import { createMockHost } from '@lark-base-open/base-database-app-sdk/testing';
+import { createSiteRuntimeClient } from '@lark-base-open/base-database-app-sdk/page';
+export async function testUser() {
+  const host = createMockHost({ capabilities: { 'function.invoke': { version: 1 } } });
+  const runtime = createSiteRuntimeClient(host.channel);
+  try { return await runtime.getCurrentUser(); }
+  finally { host.dispose(); }
+}
+```
+
+`createMockHost({context,capabilities,bindings,allowedRoutes,secureLinkAvailable,functions,handlers,failures})`：context 提供模拟 locale/env/siteToken；capabilities 缺失模拟 84afb07 宿主，空表显式关闭能力；bindings 默认空，拒绝全部上传；allowedRoutes 默认固定宿主白名单。
+11 个 site.v1 API 都有默认响应，业务函数只有显式登记才允许；`handlers` 可替换下游结果，但不能绕过前置拒绝规则。`failures` 为指定 API 注入错误码。HTTP handler 返回 wire response（body/headers/status/statusText），runtime client 转为 Response。
+`calls/events` 仅保留测试夹具数据；dispose 清理监听、流、挂起请求和浏览器宿主。HTTP/上传支持定点取消；可通过 emit 注入进度、mode、AI error/done，通过 emitStreamMessage 注入带 seq 的流消息。默认不模拟真实上传耗时、AI 内容、并发排队、seclink 重定向或 backend 身份。
+`mount(container,url,allowedOrigin?)` 在真实浏览器中使用 channel 的 Host 创建 iframe；默认 origin 来自 url，sandbox 保留脚本/同源/下载限制，不允许弹窗（不模拟表单和模态框）。返回卸载函数。origin/source 错误由真实 channel 丢弃，不虚构业务错误回包；直接 channel 对象是内存调用，不声称校验浏览器 origin。
+
+## HTTP 层 MSW
+
+<!-- example: msw.ts -->
+```ts
+import { createHttpHandlers } from '@lark-base-open/base-database-app-sdk/testing';
+export const handlers = createHttpHandlers([
+  { method: 'post', url: 'https://service.example/items', status: 201, body: { id: 'item-1' } },
+]);
+// 交给 MSW setupServer(...handlers) 或 setupWorker(...handlers)。
+```
+
+MSW 工厂仅服务真正的 HTTP 请求，如 FaaS 下游或页面直接请求。宿主 postMessage 调用不经过网络，需上述 mock host。测试入口及 MSW 不会被 page/server/shared 导入。
+
+## 拒绝规则来源与逐条对照
+
+固定来源：base-site-web `84afb07a7a4c05c09f7791cb67c4fe82bac23df8`，2026-10-09。下表路径均相对该仓根，行号按原源码。源码只读快照存于 test/fixtures/host-84afb07，provenance.json 锁定 SHA256。test/host-fixture.ts 在隔离 VM 中执行原源码，仅替换日志、平台配置、身份注入与下游传输；拒绝规则不替换。
+
+| 规则 | 原文件:行 | 测试 |
+|---|---|---|
+| origin 白名单，绑定 sourceWindow | apps/site-web/src/view/preview/runtime-host.ts:106；channel src/host.ts:255（935e447） | test/browser/run.mjs：真实 Host 接受正确请求，错误 origin/source 不调用 handler |
+| http/https/mailto/tel 之外链接，空 URL、相对 URL | apps/site-web/src/view/preview/open-link.ts:17 | rules.test.ts 链接矩阵，javascript/data/file 逐例 |
+| http(s) seclink 不可用 | apps/site-web/src/view/preview/open-link.ts:35 | rules.test.ts seclink 不可用 |
+| 单斜杠、跨域、反斜杠、fragment、编码、穿越、控制字符 | apps/site-web/src/view/preview/http-proxy.ts:81 | rules.test.ts HTTP 路径矩阵 |
+| Header 类型、名称、禁止清单及前缀 | apps/site-web/src/view/preview/http-proxy.ts:108 | rules.test.ts 每个受限头单独用例 |
+| method、body、GET body、timeout | apps/site-web/src/view/preview/http-proxy.ts:133 | rules.test.ts HTTP init 矩阵 |
+| 默认路由白名单/方法 | apps/site-web/src/view/preview/http-bridge-allowlist.ts:24、134 | rules.test.ts 非白名单与合法读取；默认表逐条等价测试 |
+| responseType、空/重复/过长 requestId | apps/site-web/src/view/preview/http-proxy.ts:212 | rules.test.ts 与 runtime.test.ts |
+| 上传 File、非空、2 GiB、Base/表成对绑定 | apps/site-web/src/view/preview/attachment-proxy.ts:51、312 | rules.test.ts 附件矩阵 |
+| 封面/下载 file/table/field/record、应用、环境、单文件对应 | apps/site-web/src/view/preview/http-attachment-context.ts:24–106 | rules.test.ts 下载坐标矩阵及封面缺坐标拒绝 |
+| Function 格式与发布清单 | apps/site-web/src/view/preview/function-proxy.ts:40–55 | runtime.test.ts 函数拒绝 |
+
+实现采用原宿主的纯校验片段（HTTP normalize、白名单匹配、附件上下文）；仅移除平台配置读取并导出测试需要的函数，不复制 channel 实现。宿主版本变化时需更新快照、规则和矩阵一起审查。生产鉴权仍由真正的宿主和服务端执行，模拟成功不证明真实权限。
+
+## 验证入口
+
+npm test 执行构建、node:test、入口依赖扫描和 examples 的 TypeScript 编译；server/shared 还在无 DOM、带 Node types 的配置下检查。test/browser/run.mjs 为本地真实 Chrome 页面夹具服务，使用 agent-browser 独立会话访问并采集结果；浏览器检查需显式执行，未宣称已自动接入仓外 CI。

package/docs/upgrade.md

@@ -0,0 +1,44 @@
+# 迁移到 SDK 0.0.1-alpha.0
+
+先核对工程 AGENTS.md 中的模板版本、实际安装 SDK 和 CLI 随包 Skill。SDK 未发布期间仅在本地验收副本使用经审核 tarball；正式模板不写 file:/tarball 依赖，也不伪造 registry lock。老模板持续兼容并维护安全与事实更正，未设截止日期。
+
+## 老模板 database-runtime.ts → SDK（仍可保持模板 1）
+
+1. 保存可回滚的源码和锁文件，核对 page/src/lib/database-runtime.ts 是否有业务定制。显式选择并安装 SDK 到 Page 工程，按其 peerDependencies 对齐 React/react-dom 与 TanStack Query；MSW 仅测试入口需要。codemod 不选择版本、不安装依赖。
+2. 在项目根运行 `base-database-cli codemod database-runtime .` 查看默认 dry-run 的 changes/conflicts。仅受支持原模板指纹可自动迁移；定制 helper、未知引用或类型冲突须先人工审查，不覆盖定制逻辑。
+3. 审查后运行 `base-database-cli codemod database-runtime . --apply`。存在冲突时不应用；检查输出 applied 和文件 diff。该操作迁移 helper 引用并适配输入类型声明，不搬目录、不升级模板版本、不迁移组件或启动入口。再次 dry-run 应无 changes。
+4. 对使用 [`defineFunction`](exports.md#server) 的 FaaS，把 input/output 放独立 contract.ts，在项目根运行 `base-database-cli contracts generate .`，检查生成契约、输入扩充和页面客户端。生成失败或 runtime-only 警告须处理；Database Function 输出仍为 unknown。生成器属于 CLI，SDK 没有 createFunctionClient 导出，消费工程生成的客户端。
+5. 手工检查其余 channel/runtime 导入与 [`FunctionMap`](exports.md#page) 扩充：channel 的 [`FunctionMap`](exports.md#page) 声明目标保持原样；[`DatabaseFunctionInputMap`](exports.md#page) 的新扩充目标为 SDK/page。兼容调用仍返回 envelope，HTTP 失败仍抛错，不二次解包。详见 [兼容说明](compat.md)。
+6. 选择保留旧启动入口或采用 [startBaseApp](start-base-app.md)。采用后移除重复的 createRoot、guard、ready/load-failed 和默认悬浮按钮；保留业务 Provider、样式及路由。仅迁移 import 不要求更换布局。
+7. 运行类型检查及 `base-database-cli check --json`；按 Skill 的验收和发布流程验证真实宿主中的链接、附件、成员选择与写入结果。验证失败时恢复源码与锁文件，不能把 mock 成功当作真实权限证明。
+
+guard 仍同步返回 cleanup，安装前异步查询能力。缺 capabilities 字段采用 host-baseline-84afb07；显式空表或缺 link.open 时不拦截。只保留一处 guard；查询期间原生行为仍受 iframe sandbox 约束。测试替身只在测试中导入。
+
+## 模板 1 → 2：手动迁移
+
+codemod 不做模板结构升级；应在独立副本逐项迁移。模板 2 当前非默认，公开 SDK 安装/根锁及远端流水线尚待发布和验收，本地构建通过不代表可远端交付。
+
+- 将 server-functions/functions 移到 server/functions；保留 Function ID、meta.json 和业务 handler，database-functions、mutations、Catalog 与应用绑定保持对应关系。移除旧布局前核对搬迁完整性，避免同时留下 server 与 server-functions。
+- 根 package.json 使用 private、type:module 和 workspaces:[page,server]；两成员保留各自依赖声明，统一到唯一根 package-lock.json。合并依赖版本后重新生成根锁，不拼接两份旧锁，不保留成员锁或嵌套 workspace。正式锁须在依赖公开可安装后生成。
+- base-database.jsonc 标明 template:{name:"database-starter",version:2}。不能只改版本字段而保留旧目录；CLI 会拒绝混杂布局或锁冲突。
+- 根 base-app.config.ts 绑定业务 App、Provider 与启动选项；page/src/main.tsx 从 SDK/page 导入 [`startBaseApp`](exports.md#page) 并传入 options，同时加载 SDK/page/styles.css 和业务 CSS。生产入口直接导入，不依赖仅 serve 可用的 virtual:base-app。
+- 将复制的平台组件导入改为 SDK/page 或 SDK/components；核对 props、插槽、语言和样式覆盖，保留业务组件。平台权限仍由宿主判断。
+- server 源码采用 ESM，TypeScript 配置 noEmit；由 CLI build-server 做类型检查并输出兼容运行时的 CJS，不把 tsc emit 当作打包。不要手写 runtime profile 或凭据，绑定由 CLI 生成。
+- 再运行 contracts generate、Page 构建、build-server 和 check；依 Skill 做 Preview 与真实浏览器验收。遇到 REMOTE_TEMPLATE_2_BUILD_UNVERIFIED 保留未验收状态，不以本地成功消除警告。
+
+SDK 文档说明本版本 API、组件、兼容语义与可编译示例。业务规则、服务端契约、Mutation 结果、CLI 命令与发布流程，请查阅 [@lark-base-open/base-database-cli](https://www.npmjs.com/package/@lark-base-open/base-database-cli) 随包安装的 lark-base-database Skill 及其 references。升级 CLI 时以该版本随包 Skill 为准。
+
+老工程参考：随 CLI 安装的 lark-base-database Skill 中的「页面」（references/legacy-development.md）、随 CLI 安装的 lark-base-database Skill 中的「AI」（references/legacy-ai-function.md）、随 CLI 安装的 lark-base-database Skill 中的「附件」（references/legacy-file-transfer.md）。命令选项与发布步骤以对应 CLI 随包 Skill 为准，此处仅标明迁移中需要调用的命令。
+
+保留旧启动入口的最小示例（采用 [`startBaseApp`](exports.md#page) 时不要重复调用）：
+
+<!-- example: upgrade.ts -->
+```ts
+// 模板 1 可先迁移 helper 导入；切换启动入口与模板 2 是独立的手动步骤。
+import { installLinkGuard, siteRuntime, classifyRuntimeError } from '@lark-base-open/base-database-app-sdk/page';
+export function initializeRuntime() {
+  const uninstall = installLinkGuard();
+  void siteRuntime.ready().catch(error => console.warn(classifyRuntimeError(error)));
+  return uninstall;
+}
+```

package/examples/capabilities.ts

@@ -0,0 +1,7 @@
+import { getRuntimeCapabilities, requireCapability, classifyRuntimeError } from '@lark-base-open/base-database-app-sdk/page';
+export async function inspectHost() {
+  const capabilities = await getRuntimeCapabilities();
+  try { await requireCapability('function.invoke'); }
+  catch (error) { return { capabilities, diagnostic: classifyRuntimeError(error) }; }
+  return { capabilities };
+}

package/examples/compat.ts

@@ -0,0 +1,21 @@
+import {
+  invokeDatabaseFunction,
+  invokeDatabaseMutationBatch,
+  type DatabaseFunctionResponse,
+} from "@lark-base-open/base-database-app-sdk/page";
+// CLI 生成到工程文件；空 map 不接受任意 string。
+declare module "@lark-base-open/base-database-app-sdk/page" {
+  interface DatabaseFunctionInputMap {
+    list_orders: { status: string };
+  }
+}
+export async function loadOrders(): Promise<DatabaseFunctionResponse> {
+  return invokeDatabaseFunction("list_orders", { status: "open" });
+}
+export async function writeOrders() {
+  const result = await invokeDatabaseMutationBatch("update_order", [
+    { recordId: "rec1", status: "done" },
+  ]);
+  // 兼容 API 保留 envelope，不能把 code/data/msg 再次解包。
+  return result;
+}

package/examples/components.tsx

@@ -0,0 +1,11 @@
+import { useState } from 'react';
+import { AttachmentImage, BaseAppProvider, DatabaseUserMenu, UserSelectorEditor, type UserSelectorEditorValue } from '@lark-base-open/base-database-app-sdk/components';
+import { siteRuntime, type DatabaseAttachmentRef } from '@lark-base-open/base-database-app-sdk/page';
+export function Details({ attachment }: { attachment: DatabaseAttachmentRef }) {
+  const [value, setValue] = useState<UserSelectorEditorValue>();
+  return <BaseAppProvider runtime={siteRuntime} locale="zh" theme="light">
+    <DatabaseUserMenu audience="enterprise" />
+    <UserSelectorEditor value={value} onChange={setValue} />
+    <AttachmentImage attachment={attachment} alt="订单附件" size={360} />
+  </BaseAppProvider>;
+}

package/examples/contract-types.ts

@@ -0,0 +1,41 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import {
+  defineFunction,
+  type DefinedFunction,
+} from "@lark-base-open/base-database-app-sdk/server";
+import { invokeDatabaseFunction } from "@lark-base-open/base-database-app-sdk/page";
+const transform: StandardSchemaV1<string, number> = {
+  "~standard": {
+    version: 1,
+    vendor: "type-test",
+    validate: (value) => ({ value: Number(value) }),
+  },
+};
+const output: StandardSchemaV1<number, string> = {
+  "~standard": {
+    version: 1,
+    vendor: "type-test",
+    validate: (value) => ({ value: String(value) }),
+  },
+};
+const fn = defineFunction({
+  input: transform,
+  output,
+  handler: (value) => value + 1,
+});
+const typed: DefinedFunction<typeof transform, typeof output> = fn;
+void typed;
+defineFunction({
+  input: transform,
+  output,
+  // @ts-expect-error handler 的参数是转换后的 number
+  handler: (value: string) => value.length,
+});
+// @ts-expect-error handler 返回必须满足 output 的输入 number
+defineFunction({ input: transform, output, handler: () => "bad" });
+export function rejectedCalls() {
+  // @ts-expect-error 生成 map 未声明此 ID
+  void invokeDatabaseFunction("missing", []);
+  // @ts-expect-error 统一 SQL 命名参数不能传位置数组
+  void invokeDatabaseFunction("list_orders", ["open"]);
+}

package/examples/development-context.ts

@@ -0,0 +1,17 @@
+import type { SiteRuntimeContext } from "@lark-base-open/base-database-app-sdk/page";
+export function localAddress(context: SiteRuntimeContext): string | undefined {
+  const development = context.development;
+  if (!development) return undefined;
+  const env: "preview" = development.projectEnv;
+  const version: string | null = development.artifactVersion;
+  // @ts-expect-error 轻量上下文没有服务端会话 ID。
+  development.sessionId;
+  // @ts-expect-error 轻量上下文没有服务端租约。
+  development.expiresAt;
+  return `${development.localOrigin} (${env}, ${version ?? "local"})`;
+}
+
+import { siteRuntime } from "@lark-base-open/base-database-app-sdk/page";
+export async function readDevelopmentOrigin() {
+  return (await siteRuntime.getRuntimeContext()).development?.localOrigin;
+}

package/examples/http.ts

@@ -0,0 +1,12 @@
+import { invokeHttp, fetch as hostFetch } from '@lark-base-open/base-database-app-sdk/page';
+export async function loadUser(signal: AbortSignal) {
+  const response = await invokeHttp({ url: '/space/api/user', signal });
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  const data: unknown = await response.json();
+  return data;
+}
+export async function loadWithFetch() {
+  const response = await hostFetch('/space/api/user');
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  return response.json() as Promise<unknown>;
+}

package/examples/link.ts

@@ -0,0 +1,10 @@
+import { siteRuntime, hasCapability, openLink } from '@lark-base-open/base-database-app-sdk/page';
+import type { SiteRuntimeContext } from '@lark-base-open/base-database-app-sdk/page';
+export async function canOpenLink() {
+  const context: SiteRuntimeContext = await siteRuntime.getRuntimeContext();
+  return hasCapability(context, 'link.open');
+}
+// 在点击之前查询能力。用户点击时立即调用，避免因等待查询失去用户激活。
+export function onSupportedLinkClick(url: string) {
+  return openLink(url);
+}

package/examples/mock.ts

@@ -0,0 +1,8 @@
+import { createMockHost } from '@lark-base-open/base-database-app-sdk/testing';
+import { createSiteRuntimeClient } from '@lark-base-open/base-database-app-sdk/page';
+export async function testUser() {
+  const host = createMockHost({ capabilities: { 'function.invoke': { version: 1 } } });
+  const runtime = createSiteRuntimeClient(host.channel);
+  try { return await runtime.getCurrentUser(); }
+  finally { host.dispose(); }
+}

package/examples/msw.ts

@@ -0,0 +1,5 @@
+import { createHttpHandlers } from '@lark-base-open/base-database-app-sdk/testing';
+export const handlers = createHttpHandlers([
+  { method: 'post', url: 'https://service.example/items', status: 201, body: { id: 'item-1' } },
+]);
+// 交给 MSW setupServer(...handlers) 或 setupWorker(...handlers)。

package/examples/page.ts

@@ -0,0 +1,6 @@
+import { siteRuntime, installLinkGuard, classifyRuntimeError } from '@lark-base-open/base-database-app-sdk/page';
+export function mountPage() {
+  const cleanup = installLinkGuard({ onDiagnostic: diagnostic => console.warn(diagnostic) });
+  void siteRuntime.ready().catch(error => console.warn(classifyRuntimeError(error)));
+  return cleanup;
+}