@lark-base-open/base-database-cli 1.3.9 → 1.4.3

package/skills/lark-base-database/references/ai-function.md

@@ -1,19 +1,19 @@
 # Base Database AI Function
 
+本参考中的 SDK 页面 API 仅适用于工程已安装 `@lark-base-open/base-database-app-sdk` 的情况；未安装时不得按 SDK 示例新增依赖或替换原实现，继续使用[冻结的classic AI Function 参考](legacy-ai-function.md)。
+
 本文说明如何在 Page 中配置和调用 AI Function。AI Function 是随应用版本发布的 AI 能力：文本可以按页面需要使用流式或一次性结果；图像和视频生成始终先创建任务、再轮询结果。页面只按 `functionKey` 调用平台 AI 能力；Base 数据读取仍使用 Database Function，写入按[Mutation 与 FaaS 分工](mutations.md#写入方式选择)选择。
 
 AI Function 是按需可选能力：需求不涉及模型或 AI 时不要创建 `ai/`，也不需要执行本文任何命令或开通 AI 能力；普通 `deploy` 在空 `ai/` 时自动跳过 AI Function 同步。只有需求包含 AI 对话、生成、分类、总结、文生图、文生视频或“查数据后让模型分析”时才读取本文。
 
-每个 AI Function 的配置保存在 `ai/<functionKey>/meta.json`。配置决定模型、System Prompt、思考深度、尺寸、时长和变量；页面只传入 `functionKey`、本次的 `variables` 与 `messages` 或 `input`。
-
-本文中的 `/sites/`、`siteToken` 和 `Site*` 是 SDK 与平台接口的既有名称；它们都指向当前 Base Database 应用，不需要额外创建或绑定其他产品对象。本地工程中的应用标识始终从 `base-database.jsonc` 的 `appToken` 读取。
+每个 AI Function 的配置保存在 `ai/<functionKey>/meta.json`。配置决定模型、System Prompt、思考深度、尺寸、时长和变量；页面只传入 `functionKey`、本次的 `params` 与 `messages` 或 `input`。
 
 ## 阅读路径
 
 1. 第一次实现时先执行[零背景最短闭环](#零背景最短闭环)。
 2. 再按需求读取[四类能力与配置契约](#四类能力与配置契约)和[Page 调用方式](#page-调用方式)。
 3. 修改已有应用时，工程若来自 `pull`，`ai/` 已与远端一致；工程不是 `pull` 得到而 `ai/` 又非空时，按[恢复已有 AI Function](#恢复已有-ai-function)核对。
-4. 最后按[页面实现检查](#页面实现检查)和[区分三种调试成功](#区分三种调试成功)验收。
+4. 实现按[页面实现检查](#页面实现检查)核对；用户要求运行态验收时，按[AI 验收判定](verification.md#ai-验收判定)执行。
 
 ## 零背景最短闭环
 
@@ -22,7 +22,7 @@ AI Function 是按需可选能力：需求不涉及模型或 AI 时不要创建
 AI Function 不是 FaaS 代码，也不是页面直接请求模型。一个可运行的 AI 功能必须同时有两部分：
 
 ```text
-ai/<functionKey>/meta.json       # 应用版本中的托管配置
+ai/<functionKey>/meta.json       # 应用版本中的配置
 page/...                         # 使用同一个 functionKey 的页面调用代码
 ```
 
@@ -31,11 +31,9 @@ page/...                         # 使用同一个 functionKey 的页面调用
 1. 修改已有应用且工程不是 `pull` 得到时，先按[恢复已有 AI Function](#恢复已有-ai-function)核对远端配置；新建应用或 `pull` 得到的工程继续下一步。
 2. 查询 `model_profiles`，按 `capability` 选择真实 `profile_id`；禁止猜测示例 ID。
 3. 为每个 AI 功能选择唯一、稳定的 `functionKey`，创建严格 JSON 文件 `ai/<functionKey>/meta.json`。`functionKey` 只能含字母、数字、下划线和连字符，长度 1～64；目录名就是调用 key。
-4. 在 Page 中从 `./lib/database-runtime` 导入 helper，使用完全相同的 `functionKey`。调用 `callSiteAIFunction` 时显式传 `capability`；不要依赖 SDK 按 `messages` 或 `input` 猜调用链路。
-5. 对每个本地 AI Function 执行 `ai-functions validate <functionKey>`，只有返回 `is_success: true` 才继续。
-6. 执行一次普通 `deploy`。`deploy` 会构建页面、全量同步 `ai/` 到草稿版本并发布 Preview；正常发布流程不需要先手工执行 `ai-functions sync`。
-7. 执行 `ai-functions list`，核对目标 `functionKey`、`capability_type`、`model_profile_id` 和 `disabled=false`；再在命令返回的 `baseAppUrl` 页面发起一次真实调用。
-8. text/vision 使用显式流式入口时必须看到页面增量与 `onDone`，使用聚合入口时必须得到 `{type:'text'}`；image/video 必须轮询到 `succeeded` 并渲染生成资源。CLI `debug` 只用于辅助定位，不能代替页面链路验收。
+4. 在 workspace Page 中从 `@lark-base-open/base-database-app-sdk/page` 导入 SDK，使用完全相同的 `functionKey`。调用 `callSiteAIFunction` 时显式传 `capability`；不要依赖 SDK 按 `messages` 或 `input` 猜调用链路。
+5. 执行一次普通 `deploy`。发布顺序与 skip/Prod 行为按[发布参考](release.md#function-发布顺序与错误边界)执行。
+6. 运行态未检查时列为未验证；用户要求验收时按[AI 验收判定](verification.md#ai-验收判定)执行，Prod 是否验证按用户诉求决定。
 
 最小文本配置与页面调用如下。把 `replace-with-profile-id` 换成 `model_profiles` 返回的真实值。`showAnswer` 是你的页面状态更新函数，需要替换为实际 UI 代码：
 
@@ -45,10 +43,13 @@ page/...                         # 使用同一个 functionKey 的页面调用
   "description": "根据菜单和用餐条件生成推荐",
   "config": {
     "capability_type": "text",
-    "output_mode": "stream",
     "model_profile_id": "replace-with-profile-id",
     "system_prompt": "只推荐 {{menu}} 中的菜品。",
-    "variables": [{ "name": "menu", "type": "string", "required": true }],
+    "input_schema": {
+      "type": "object",
+      "properties": { "menu": { "type": "string" } },
+      "required": ["menu"]
+    },
     "text": {
       "reasoning_depth": "standard",
       "temperature": 0.7
@@ -58,12 +59,12 @@ page/...                         # 使用同一个 functionKey 的页面调用
 ```
 
 ```ts
-import { callSiteAIFunction } from './lib/database-runtime';
+import { callSiteAIFunction } from '@lark-base-open/base-database-app-sdk/page';
 
 const result = await callSiteAIFunction({
   functionKey: 'recommend_dishes',
   capability: 'text',
-  variables: { menu: '番茄炒蛋、宫保鸡丁、青椒肉丝' },
+  params: { menu: '番茄炒蛋、宫保鸡丁、青椒肉丝' },
   messages: [
     {
       role: 'user',
@@ -78,22 +79,26 @@ if (result.type === 'text') showAnswer(result.content);
 
 AI Function 和 Database Function 一样按应用版本保存：Preview 读取草稿版本，Prod 读取已发布版本。实现 AI 需求时，把每个 AI 功能建模为 `ai/<functionKey>/meta.json`，执行 `deploy` 后由 CLI 将 AI Function 全量同步到当前草稿版本。
 
-部署前先执行 AI Function 静态校验：`functionKey`、`capability_type`、`output_mode`、`model_profile_id`、变量声明、System Prompt 占位符和能力专属参数都必须符合当前服务端契约。运行态调用进入鉴权、额度、并发和模型调用链路；目标 Function 必须存在，且配置没有设置 `disabled: true`。
+部署校验的适用条件、顺序和失败边界见[验证方法](verification.md#验证方法)。
+
+配置要求：`functionKey`、`capability_type`、`input_schema`、`model_profile_id`、变量声明、System Prompt 占位符和能力专属参数都必须符合当前服务端契约。运行态调用进入鉴权、额度、并发和模型调用链路；目标 Function 必须存在，且配置没有设置 `disabled: true`。
 
-Preview 发布成功后，必须在页面里触发一次真实 AI Function 调用（`callSiteAIFunction` 或 `invokeSiteAIFunctionStream`）：收到结果、`onMessage` 增量或 `onDone` 才能说明 Preview 运行态链路可用。目标 Function 不存在时检查本地声明和 Functions 同步结果；返回 `ai function is disabled` 时检查该 Function 的 `disabled` 配置；模型不可用时重新查询 `model_profiles` 并校验配置；额度、并发或服务错误按实际错误码处理。无法通过应用配置解决时，保留 `requestId` 和脱敏错误摘要，向平台支持反馈。
+运行态未检查时列为未验证；用户要求验收时按[AI 验收判定](verification.md#ai-验收判定)执行，Prod 是否验证按用户诉求决定。
 
-Prod 验证只能发生在用户明确确认并完成 `deploy --production --yes` 之后。Prod 发布成功后，在生产 `baseAppUrl` 页面再次触发真实 AI Function 调用；收到结果或 `onDone` 才能报告 Prod AI 链路已生效。发布 Prod 前，即使 Preview 已验证成功，也只能报告 Preview AI 可用。
+### 调用排障
+
+目标 Function 不存在时检查本地声明和 Functions 同步结果；返回 `ai function is disabled` 时检查该 Function 的 `disabled` 配置；模型不可用时重新查询 `model_profiles` 并校验配置；额度、并发或服务错误按实际错误码处理。无法通过应用配置解决时，保留 `requestId` 和脱敏错误摘要，向平台支持反馈。
 
 ### 恢复已有 AI Function
 
 `pull` 恢复源码制品的同时，会读取远端 AI Function 草稿并写回 `ai/<functionKey>/meta.json`，返回 `aiFunctions.status` 为 `restored` 或 `not_enabled`；当前账号未开通时不落 `ai/`，此后 deploy 不触碰远端 AI Function。`deploy` 在本地 `ai/` 非空时先核对远端已有 key 是否都在本地，缺失则拒绝并列出 key，不会静默删除；`ai-functions sync` 则把本地 `ai/` 当作全集立即全量覆盖（含空集合）。因此只有工程不是 `pull` 得到、且 `ai/` 非空时，才需要手工执行下列恢复：
 
 1. `ai-functions list` 取得草稿版本全部远端 key。
-2. 对每个 key 执行 `ai-functions pull <functionKey>`。该命令只把详情打印为 JSON，**不会写文件**；读取返回的 snake_case 字段 `function.name`、`function.description`、`function.config_json`，把 `config_json` 字符串解析成 JSON 对象后还原为 `ai/<functionKey>/meta.json`。`disabled` 位于这个 `config` 对象内，不在 `meta.json` 顶层。
-3. 比较远端 key 集合与本地 `ai/` 目录。需求外的远端 Function 必须保留所有配置值；JSON 缩进和字段顺序不影响语义。本地缺少任一远端 key，或 `config_json` 无法解析时，禁止 `ai-functions sync` 和显式删除操作，`deploy` 前也必须补齐。
+2. 对每个 key 执行 `ai-functions pull <functionKey>`。该命令读取 preview 详情中的 `spec`，解析配置并写入 `ai/<functionKey>/meta.json`；仅查看时使用 `ai-functions get <functionKey>`。`disabled` 位于这个 `config` 对象内，不在 `meta.json` 顶层。
+3. 比较远端 key 集合与本地 `ai/` 目录。需求外的远端 Function 必须保留所有配置值；JSON 缩进和字段顺序不影响语义。本地缺少任一远端 key，或 `spec` 缺失或无法解析时，禁止 `ai-functions sync` 和显式删除操作，`deploy` 前也必须补齐。
 4. 只有用户明确授权删除具体 Function 后，才能让该 key 从本地全集缺失并执行全量同步。
 
-空 `ai/` 在 `deploy` 里是“本次不修改 AI Function”：CLI 会返回 `{ skipped: true, reason: 'no_local_ai_functions' }` 并跳过 AI Function 同步；仅 Page/Database Function/FaaS 会随本次 deploy 发布。本地已存在 `ai/` 声明但本次发布要完全不动 AI Function 时，使用显式参数 `deploy --skip-ai-functions`（生产发布追加在 `--production --yes` 之后），返回中带 `aiFunctionsSkipped: true`，交付报告必须说明 AI Function 未同步且未验证。`ai-functions sync` 与 deploy 不同，只要执行就是立即写远端草稿的全量覆盖操作，空集合会把远端 AI Function **全部删除**；因此仅在用户明确授权删除或有强规划时使用。常规发布不必单独执行 `ai-functions sync`。
+deploy 的 AI 同步、skip 行为、Prod 提升与显式 sync 的区别统一见[发布顺序与错误边界](release.md#function-发布顺序与错误边界)。
 
 ## 选择 AI Function
 
@@ -102,10 +107,10 @@ Prod 验证只能发生在用户明确确认并完成 `deploy --production --yes
 | 业务动作       | 数据路径                   | 页面职责                                                            |
 | -------------- | -------------------------- | ------------------------------------------------------------------- |
 | 查询           | Page → Database Function   | 固定 Function ID，校验查询结果                                      |
-| 写入           | Page → FaaS → Base Records | 固定 Function ID，由 FaaS 校验并写入                                |
-| AI 对话 / 生成 | Page → AI Function         | 传 functionKey + variables + messages/input，消费结果，维护会话状态 |
+| 写入 | Page → Mutation 或 FaaS | 按[写入方式选择](mutations.md#写入方式选择)：普通单表写入用 Mutation，需要业务校验或编排时用 FaaS |
+| AI 对话 / 生成 | Page → AI Function         | 传 functionKey + params + messages/input，消费结果，维护会话状态 |
 
-需要先查 Base 再问模型时，先完成 Database Function 查询，在 Page 内把经过裁剪的结果放入 `messages` 或 `variables`，再按 `functionKey` 调用 AI Function。需要把 AI 结果写回 Base 时，再调用对应 FaaS。
+需要先查 Base 再问模型时，先完成 Database Function 查询，在 Page 内把经过裁剪的结果放入 `messages` 或 `params`，再按 `functionKey` 调用 AI Function。需要把 AI 结果写回 Base 时，按[写入方式选择](mutations.md#写入方式选择)选用 Mutation 或 FaaS。
 
 典型路由：
 
@@ -120,12 +125,12 @@ Prod 验证只能发生在用户明确确认并完成 `deploy --production --yes
 
 一个 AI Function 只承载一种能力，由 `capability_type` 决定用哪条运行链路与哪组配置字段：
 
-| capability_type | output_mode       | 运行链路                            | 专属配置字段                                                                                                                                       |
-| --------------- | ----------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `text`          | `stream` / `sync` | 通过 SDK 获取文本流或完整文本       | `text.reasoning_depth`(off/light/standard/deep) / `text.temperature`                                                                               |
-| `vision`        | `stream` / `sync` | 多模态理解；输入受下文 SDK 类型限制 | 同 text，且模型 Profile 必须声明本次使用的 image / video / audio / file 输入                                                                       |
-| `image`         | `sync`            | 创建图片任务并轮询结果              | `image.size` / `image.response_format`(url/b64_json) / `image.sequential_image_generation`(auto/disabled) / `image.max_images` / `image.watermark` |
-| `video`         | `async`           | 创建视频任务并轮询结果              | `video.resolution` / `video.ratio` / `video.duration` / `video.watermark` / `video.seed`                                                           |
+| capability_type | mode     | 运行链路                            | 专属配置字段                                                                                                                                       |
+| --------------- | -------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `text`          | `stream` | 通过 SDK 获取文本流或完整文本       | `text.reasoning_depth`(off/light/standard/deep) / `text.temperature`                                                                               |
+| `vision`        | `stream` | 多模态理解；输入受下文 SDK 类型限制 | 同 text，且模型 Profile 必须声明本次使用的 image / video / audio / file 输入                                                                       |
+| `image`         | `task`   | 创建图片任务并轮询结果              | `image.size` / `image.response_format`(url/b64_json) / `image.sequential_image_generation`(auto/disabled) / `image.max_images` / `image.watermark` |
+| `video`         | `task`   | 创建视频任务并轮询结果              | `video.resolution` / `video.ratio` / `video.duration` / `video.watermark` / `video.seed`                                                           |
 
 `AIFunctionConfig` 结构（落 `ai/<functionKey>/meta.json` 的 `config` 字段）：
 
@@ -137,10 +142,13 @@ Prod 验证只能发生在用户明确确认并完成 `deploy --production --yes
   "description": "根据口味/预算/人数和菜单推荐菜品",
   "config": {
     "capability_type": "text",
-    "output_mode": "stream",
     "model_profile_id": "replace-with-text-profile-id",
     "system_prompt": "你是点餐助手，只推荐 {{menu}} 中的菜品。",
-    "variables": [{ "name": "menu", "type": "string", "required": true }],
+    "input_schema": {
+      "type": "object",
+      "properties": { "menu": { "type": "string" } },
+      "required": ["menu"]
+    },
     "text": {
       "reasoning_depth": "standard",
       "temperature": 0.7
@@ -149,13 +157,13 @@ Prod 验证只能发生在用户明确确认并完成 `deploy --production --yes
 }
 ```
 
-静态校验（保存/发布前执行，按能力分支）：`capability_type` 合法；`model_profile_id` 来自可用模型列表且能力匹配（文本模型不能配给文生图）；`system_prompt` 里的 `{{var}}` 都在 `variables` 声明；`variables` 名称唯一、类型合法、required 项不带默认值；`output_mode` 与 `capability_type` 相容；文本 `temperature` 必须在 0～2 内；vision 要求 profile 至少声明 image / video / audio / file 中一种媒体输入，调用时每个 content part 还必须命中该 profile 的 `input_modalities`；image `max_images` 与 video `duration` 不超平台上限，video `seed` 必须为 -1 或更大。
+配置合法性要求（由 deploy 校验，按能力分支）：`capability_type` 合法；`model_profile_id` 来自可用模型列表且能力匹配（文本模型不能配给文生图）；`system_prompt` 里的 `{{var}}` 都在 `input_schema.properties` 声明；`input_schema` 属性类型合法，required 列表引用已声明属性；文本 `temperature` 必须在 0～2 内；vision 要求 profile 至少声明 image / video / audio / file 中一种媒体输入，调用时每个 content part 还必须命中该 profile 的 `input_modalities`；image `max_images` 与 video `duration` 不超平台上限，video `seed` 必须为 -1 或更大。
 
-变量类型只能是 `string`、`number`、`boolean`、`object`。调用时 `variables` 的运行时类型必须匹配声明，required 变量不可缺失；`object` 同时接受对象和数组。`system_prompt` 适用于四类能力：text/vision 作为 system message，image/video 作为基础提示词；媒体调用的 `input.prompt` 会追加到这个基础提示词。
+`input_schema` 是描述 `params` 的 object JSON Schema，支持 type、properties、required、additionalProperties、items、prefixItems、enum、数值/长度限制、oneOf、anyOf、pattern 和 default。pattern 使用 RE2；不支持 $ref 或外部加载。作者 Schema 最大 32 KiB、256 个节点、16 层。default 使用真实 JSON 值；有有效 default 的顶层属性无需 required。缺失属性由执行器补默认值，显式 null 只有 Schema 允许才合法，且不会触发默认值。`system_prompt` 适用于四类能力；媒体 `input.prompt` 追加到基础提示词。
 
 `disabled` 是 `config.disabled`，省略或 `false` 表示可调用，`true` 表示保留配置但停止调用。`video.seed=-1` 表示随机种子。
 
-图片生成和文生视频的最小配置分别如下。这里的 `output_mode` 是服务端能力配置约束，不代表浏览器可以同步得到最终媒体；Page 对 image/video 都必须创建任务并轮询。
+图片生成和文生视频的最小配置分别如下。Page 对 image/video 创建任务并轮询，mode 由服务端按能力推导。
 
 ```json
 {
@@ -163,7 +171,7 @@ Prod 验证只能发生在用户明确确认并完成 `deploy --production --yes
   "description": "根据商品描述生成海报",
   "config": {
     "capability_type": "image",
-    "output_mode": "sync",
+    "input_schema": { "type": "object", "properties": {} },
     "model_profile_id": "replace-with-image-profile-id",
     "system_prompt": "生成适合商品展示的图片。",
     "image": {
@@ -183,7 +191,7 @@ Prod 验证只能发生在用户明确确认并完成 `deploy --production --yes
   "description": "根据脚本生成短视频",
   "config": {
     "capability_type": "video",
-    "output_mode": "async",
+    "input_schema": { "type": "object", "properties": {} },
     "model_profile_id": "replace-with-video-profile-id",
     "system_prompt": "生成简洁、自然的宣传短视频。",
     "video": {
@@ -197,24 +205,13 @@ Prod 验证只能发生在用户明确确认并完成 `deploy --production --yes
 }
 ```
 
-示例里的尺寸、时长和其他参数只是结构演示，必须根据 `model_profiles` 返回的能力与业务要求调整，再用 `ai-functions validate` 让服务端做最终校验。
-
-当前图片模型按 Seedream 5.0 lite 契约校验 `image.size`：可以使用分辨率档位 `2K`、`3K`、`4K`，也可以使用 `WIDTHxHEIGHT`。像素尺寸必须同时满足总像素数在 3,686,400～16,777,216 之间、宽高比在 1:16～16:1 之间；默认使用 `2048x2048`。服务端不会把非法尺寸自动放大或缩小，`ai-functions validate` 和运行时调用都会直接拒绝。
-
-`image.sequential_image_generation` 决定单图或组图：
+示例里的尺寸、时长和其他参数只是结构演示，必须根据 `model_profiles` 返回的能力与业务要求调整，由 `deploy` 完成服务端校验，编辑期可选 `ai-functions validate` 自检。
 
-| 模式       | `sequential_image_generation` | `input.image`         | 输出上限                            |
-| ---------- | ----------------------------- | --------------------- | ----------------------------------- |
-| 文生单图   | `disabled`                    | 省略                  | 1 张                                |
-| 单图生单图 | `disabled`                    | 单个字符串或 1 项数组 | 1 张                                |
-| 多图生单图 | `disabled`                    | 2～14 项数组          | 1 张                                |
-| 文生组图   | `auto`                        | 省略                  | 最多 15 张                          |
-| 单图生组图 | `auto`                        | 单个字符串或 1 项数组 | 最多 14 张                          |
-| 多图生组图 | `auto`                        | 2～14 项数组          | 参考图数与最终生成图数之和不超过 15 |
+图片尺寸、像素与数量上限按实际选择的 model_profiles 和服务端校验反馈确定，不将某一模型版本的限制推广到其他模型。示例参数只演示结构；缺少范围说明时先用编辑期 `ai-functions validate` 获取明确校验反馈，修正参数后再发布，不靠反复模型调用试探限制。
 
-`image.max_images` 为 1～15，只在 `auto` 下生效；`0` 或省略表示使用平台默认值。服务端会按参考图数量和模型 Profile 上限进一步收紧。
+`image.sequential_image_generation` 选择单图（disabled）或组图（auto）；参考图使用 `input.image`，输入格式按下表。`image.max_images` 的可选范围、参考图数量与输出数量之间的约束以当前模型和服务端校验反馈为准，不从示例中的数量推断所有模型上限。
 
-参考图不是 AI Function 的固定配置，属于每次调用输入。Channel SDK 导出的 `SiteAIImageGenerationInput` 定义了公开类型；使用 `input.image` 传一条可访问 URL / `data:image/...;base64,...` 字符串，或传包含 1～14 个此类字符串的数组。
+参考图属于每次调用输入，不是 AI Function 固定配置；使用可访问 URL / data:image/...;base64,... 字符串或非空字符串数组。接入类型以 SDK 的 SiteAIImageGenerationInput 为准。
 
 ### 参考图来源与传参
 
@@ -225,7 +222,7 @@ Prod 验证只能发生在用户明确确认并完成 `deploy --production --yes
 | 公网可访问图片    | HTTPS URL                                                                                        |
 | 浏览器本地 `File` | 用 `FileReader.readAsDataURL` 转成完整的 `data:image/...;base64,...`；只用于满足请求体限制的小图 |
 | Base 附件         | 用 `fetchAttachmentDownloadUrl(context, ref)` 换取短时效 URL                                     |
-| 多张参考图        | 由上述字符串组成的 1～14 项数组                                                                  |
+| 多张参考图        | 由上述字符串组成的非空数组，数量先按服务端契约校验                                                                  |
 
 `file_token` 只是附件资源标识，不能直接传给模型；浏览器 `blob:` URL 也不能使用，因为它只在当前页面上下文有效。不要手工拼 Box 下载地址。Base 附件场景同时读取[文件传输](file-transfer.md#展示与下载)，使用真实的 `tableId`、`fieldId`、`recordId` 和 `fileToken` 证明附件位置：
 
@@ -234,7 +231,7 @@ import {
   createSiteAIFunctionTask,
   fetchAttachmentDownloadUrl,
   resolveDatabaseContext,
-} from './lib/database-runtime';
+} from '@lark-base-open/base-database-app-sdk/page';
 
 const context = await resolveDatabaseContext();
 const sourceImageUrl = await fetchAttachmentDownloadUrl(context, {
@@ -282,33 +279,36 @@ base-database-cli lark-cli -- \
 
 ## CLI 建模与调试
 
-AI Function 在本地以声明式目录维护：每个 `ai/<functionKey>/meta.json` 声明一个 AI Function，`deploy` 时随发布走**全量覆盖**同步（新增、修改和删除均以本地全集为准）。
+AI Function 在本地以声明式目录维护：每个 `ai/<functionKey>/meta.json` 声明一个 AI Function，`deploy` 时随发布走**全量覆盖**同步（适用条件与发布顺序见[发布参考](release.md#function-发布顺序与错误边界)）。
 
 ```bash
 # 列出应用中的 AI Function
 base-database-cli ai-functions list
 
-# 读取单个配置用于本地编辑 / diff
+# 查看草稿配置；--env prod 仅显示已发布公开契约
+base-database-cli ai-functions get <functionKey>
+
+# 恢复草稿配置到本地文件
 base-database-cli ai-functions pull <functionKey>
 
 # 全量覆盖同步本地 ai/ 声明
 base-database-cli ai-functions sync
 
-# 保存/发布前静态校验单个 AI Function
+# 编辑期可选：静态校验单个 AI Function
 base-database-cli ai-functions validate <functionKey>
 
 # 调试 text/vision：聚合返回完整文本与 firstTokenMs
 base-database-cli ai-functions debug <functionKey> \
-  --env preview --messages '[{"role":"user","content":[{"type":"text","text":"概括缺货风险"}]}]' --variables '{"menu":"..."}'
+  --env preview --messages '[{"role":"user","content":[{"type":"text","text":"概括缺货风险"}]}]' --params '{"menu":"..."}'
 
-# 调试 image/video：两者都提交媒体任务并返回 taskId；image 可带一张或多张参考图
+# 调试 image/video：两者都提交媒体任务并返回 task_id；image 可带一张或多张参考图
 base-database-cli ai-functions debug <functionKey> \
   --env preview \
   --input '{"prompt":"保持角色一致，生成一组新品海报","image":["https://example.com/ref-1.png","https://example.com/ref-2.png"]}' \
-  --variables '{}'
+  --params '{}'
 
 # 查询文生图 / 文生视频任务
-base-database-cli ai-functions task <functionKey> <taskId> --env preview
+base-database-cli ai-functions task <functionKey> <task_id> --env preview
 
 # 查看用量汇总（总量 + 按日期分布 + 按 Function/能力/错误码分维度）
 base-database-cli ai-functions usage \
@@ -316,119 +316,25 @@ base-database-cli ai-functions usage \
   --model <profileId> --capability-type text
 ```
 
-CLI 调试对 text/vision 返回聚合文本，对 image/video 返回 taskId；随后使用 `ai-functions task` 查询任务。验证页面逐帧显示时，使用 `invokeSiteAIFunctionStream` 并观察回调。
+CLI 调试对 text/vision 返回聚合文本，对 image/video 返回 task_id；随后使用 `ai-functions task` 查询任务。验证页面逐帧显示时，使用 `invokeSiteAIFunctionStream` 并观察回调。
 
 应用所有者可用 `ai-functions usage` 查询用量汇总。对应接口 `GET /open-apis/base/v3/sites/:token/ai_functions/usage/summary` 返回总量、`by_date`（Key 为 `YYYYMMDD`）、`by_function`、`by_capability`、`error_dist`。`from/to` 为 `YYYYMMDD` 区间（含），不传则聚合全部历史。`--model` 接受 `model_profiles` 返回的 `profiles[].profile_id`。
 
-image / video 创建任务后返回 `taskId` 和状态。使用同一应用、Function 与环境轮询，处理 `queued`、`running`、`succeeded`、`failed`、`cancelled`，仅在成功终态读取生成资源。平台会在应用绑定的 Base 中维护任务记录；页面通过任务接口读状态，不直接修改这些记录。
-
-`taskId` 是不透明的任务标识，原样传给查询接口；不要解析它或用 Base record ID 替代。创建失败时报告错误，不凭空构造 taskId。
-
-## Page 调用方式
-
-新建工程已包含本节所需的 Page runtime；实现 AI Function 时不需要安装、替换或选择 SDK。修改已有工程时，除非用户明确要求升级页面依赖，否则保留已有 `package.json` 与 lockfile，不因新增 AI Function 自行改依赖。
-
-starter 的 `page/src/lib/database-runtime.ts` 导出 key 化调用入口。调用 `callSiteAIFunction` 时显式提供与配置一致的 `capability`：text/vision 走流式聚合，image/video 走任务提交。页面统一使用这些 helper，由 SDK 处理流式和媒体任务通信。Page 不得自行调用全局 `fetch` 绕过 SDK，也不得在代理失败时降级直连。
-
-| 能力   | Page 本次输入                                     | 推荐入口                                                                                                 | 完成条件                         |
-| ------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------- |
-| text   | `messages` + 可选 `variables`                     | `invokeSiteAIFunctionStream` 需要逐帧 UI；`callSiteAIFunction` 需额外传 `capability:'text'` 取得聚合文本 | `onDone` 或 `{type:'text'}`      |
-| vision | 多模态 `messages` + 可选 `variables`              | 与 text 相同；统一入口传 `capability:'vision'`，输入类型必须属于模型 Profile 的 `input_modalities`       | `onDone` 或 `{type:'text'}`      |
-| image  | `capability:'image'` + `input` + 可选 `variables` | `createSiteAIFunctionTask`，也可用统一入口创建任务                                                       | `succeeded` 且读取 `imageAssets` |
-| video  | `capability:'video'` + `input` + 可选 `variables` | `createSiteAIFunctionTask`，也可用统一入口创建任务                                                       | `succeeded` 且读取 `videoAsset`  |
-
-```ts
-import {
-  callSiteAIFunction,
-  invokeSiteAIFunctionStream,
-  createSiteAIFunctionTask,
-} from './lib/database-runtime';
-
-// 本例调用 text，因此只处理 text 结果。
-const result = await callSiteAIFunction({
-  functionKey: 'recommend_dishes',
-  capability: 'text',
-  variables: { menu: '...' },
-  messages: [
-    {
-      role: 'user',
-      content: [{ type: 'text', text: '按预算 100 元推荐两道菜' }],
-    },
-  ],
-});
-if (result.type === 'text') {
-  showAnswer(result.content); // 替换为实际的页面状态更新
-}
-
-// 显式流式（text/vision）：逐帧增量
-const stream = invokeSiteAIFunctionStream({
-  functionKey: 'recommend_dishes',
-  messages: [
-    { role: 'user', content: [{ type: 'text', text: '概括今天的缺货风险' }] },
-  ],
-  variables: { menu: '...' },
-});
-// reasoning 模型会先持续下发 delta.reasoningContent，再下发 delta.content。
-// 只消费 content 会让「思考过程」区域一直为空，看起来像没有流式输出，必须两者都消费。
-stream.onMessage((delta) => {
-  if (delta.reasoningContent) appendReasoning(delta.reasoningContent);
-  if (delta.content) appendAnswer(delta.content);
-});
-stream.onError((error) => showError(error.message));
-stream.onDone(() => markAnswerComplete());
-// 只在用户取消、组件卸载或新请求替代旧请求时调用；不要在注册回调后立即销毁。
-const cancel = () => stream.destroy();
-// appendReasoning、appendAnswer、showError、markAnswerComplete 都是页面自己的状态更新函数。
-
-// 多模态理解仍使用 capability:'vision'。content part 统一为 text、image、video、audio、file；
-// 实际可用组合以 model_profiles 返回的 input_modalities 为准。
-const multimodal = invokeSiteAIFunctionStream({
-  functionKey: 'understand_assets',
-  messages: [
-    {
-      role: 'user',
-      content: [
-        { type: 'text', text: '总结这些素材' },
-        { type: 'image', url: imageUrl, detail: 'high' },
-        { type: 'video', url: videoUrl, fps: 2 },
-        { type: 'audio', url: audioUrl },
-        { type: 'file', url: pdfUrl, filename: 'report.pdf' },
-      ],
-    },
-  ],
-});
-
-// 图片生成 / 文生视频：提交后必须轮询。
-// image 完整可复用实现见 starter 的 `ImageTaskOperation.tsx`；video 参考 `ai-media-panel.tsx` 中的 `AIVideoPanel`。
-const task = await createSiteAIFunctionTask({
-  functionKey: 'make_promo',
-  capability: 'image',
-  input: {
-    prompt: '保持角色一致，生成一组新品海报',
-    image: ['https://example.com/ref-1.png', 'https://example.com/ref-2.png'],
-  },
-});
-```
-
-公开协议不暴露供应商字段，五类 part 固定为 `{type:'text', text}`、`{type:'image', url, detail?}`、`{type:'video', url, fps?}`、`{type:'audio', url}`、`{type:'file', url, filename?}`。四类非文本输入统一使用 `url`，不支持 `file_id`；本地文件先编码成 data URL。后端 Ark adapter 会把 image/video 转成 `image_url`/`video_url` 对象，把音频 URL 转成 `input_audio.url + format`（format 按链接后缀推断），把音频 data URL 拆成 `input_audio.data + format`，把文件映射为 `file.file_url` 或 `file.file_data`。
-
-文件理解当前只支持 PDF，单文件不得超过 50 MB。公网 URL 必须是 HTTP(S)，路径以 `.pdf` 结尾；若签名 URL 的路径没有后缀，必须补 `filename:'*.pdf'`。本地 PDF 使用 `data:application/pdf;base64,...`，并且必须带 `filename:'*.pdf'`。`filename` 只用于校验和 data URL 场景的 Ark 请求；URL 场景不会把它透传给供应商。Chat 文件理解返回仍是文本流，不新增文件输出类型。
+## 任务受理与完成
 
-`reasoningContent` 是模型思考过程增量，`content` 是最终回答增量：两者分区渲染，思考过程放较小的过程区域，最终回答进正式结果区。**要从结果里解析结构化列表时，基于最终 answer（`content` 累积值）解析，不要基于 reasoning 内容解析。** 业务页面只处理 SDK 返回的 `{ content?, reasoningContent?, raw }`，无需自行解析原始流式传输格式。
+image / video 创建任务后返回 `task_id` 和状态。使用同一应用、Function 与环境轮询，处理 `queued`、`running`、`succeeded`、`failed`、`cancelled`，仅在成功终态读取生成资源。平台会在应用绑定的 Base 中维护任务记录；页面通过任务接口读状态，不直接修改这些记录。
 
-`SiteAIFunctionResult` 是可判别联合（用 `switch(result.type)` 判别，避免字符串解析媒体结果）：`{ type:'text', content }` / `{ type:'image_task', taskId, status }` / `{ type:'video_task', taskId, status }`。Ark Chat 的 `choices.message.content` / `choices.delta.content` 是文本，因此 vision 表示多模态输入理解、文本输出；它不会在 Chat 响应中生成图片、视频或音频。需要媒体输出时必须显式调用 image/video AI Function 的任务接口，任务成功后分别从 `imageAssets` / `videoAsset` 读取结果。所有响应携带 `requestId`，用于监控与排查。
+`task_id` 是不透明的任务标识，原样传给查询接口；不要解析它或用 Base record ID 替代。创建失败时报告错误，不凭空构造 task_id。
 
-媒体任务只允许运行时覆盖有限字段：image 使用 `input.prompt` / `input.size` / `input.image`，video 使用 `input.prompt` / `input.image_url` / `input.duration`；model、张数、比例、水印等保持在 AI Function 配置中。`input.image` 接受单个字符串或 1～14 项字符串数组；`input.duration` 必须是正数，并会按模型 Profile 上限收紧。图片生成参考 starter 的 `page/src/examples/ai-function/ImageTaskOperation.tsx`（只渲染 `imageAssets`），文生视频参考同目录 `ai-media-panel.tsx` 中的 `AIVideoPanel`（渲染 `videoAsset`）。两个示例都轮询并处理 `queued`、`running`、`succeeded`、`failed`、`cancelled`，在新请求时通过 `requestSeq` 忽略旧任务结果，且带总轮询时限（`pollDeadlineMs`，默认 5 分钟）以避免死轮询；组件卸载时也停止 timer。不要用没有总时限或取消处理的 `while` 轮询。
-
-`messages[].content` 必须是非空 content part 数组，不接受字符串。业务调用只允许 `user` / `assistant`：`user` 可传 `text`、`image`、`video`、`audio`、`file`，`assistant` 只允许 `text`；System Prompt 只能由 AI Function 配置管理，调用方不得发送 `system`。每个 message 与 part 都采用严格字段白名单，多余字段会被拒绝。
+## Page 调用方式
 
-图片 `detail` 仅允许 `low` / `high` / `xhigh`，视频 `fps` 仅允许 `[0.2, 5]`。媒体与文件 `url` 必须是非空 HTTP(S) URL 或合法 data URL；音频 data URL 的 MIME 必须对应 `mp3` / `wav` / `aac` / `m4a` / `pcm` / `ac3` / `alac`。音频 HTTP(S) URL 的路径后缀必须是这些格式之一（Ark 要求显式 format，服务端按后缀推断，签名参数不受影响），没有可识别后缀的链接请改传音频 data URL。文件只接受 PDF，并遵循上一段的 filename 和大小约束。每个 part 还必须命中所选 Profile 的 `input_modalities`。不要用 `any` 或自行 `fetch` 绕过公开类型与服务端校验。
+页面运行时 API 用法以工程已安装的 SDK 文档为准：读取 `node_modules/@lark-base-open/base-database-app-sdk/docs/README.md`，再按索引查看对应页面文档；旧模板可查[冻结的 AI 参考](legacy-ai-function.md#page-调用方式)。AI Function 的 Page 输入、能力与任务结果约束仍按本页前文执行。若工程使用 `defineFunction`，CLI 生成的 `meta.inputSchema` 是 Agent 开放能力的 schema；已有工程手写的 `meta.json` `inputSchema` 保持兼容，不要求迁移。
 
 ## System prompt 与数据边界
 
-System Prompt 在 **AI Function 配置**里维护，随版本快照进入线上；平台不代管、不隐藏，也**不承诺保护 System Prompt**，因此不得放入密钥、Token、内部凭据或不可向最终访问者暴露的内容。页面通过 `variables` 注入运行时值，占位符 `{{var}}` 由服务端渲染。
+System Prompt 在 **AI Function 配置**里维护，随版本快照进入线上；平台不代管、不隐藏，也**不承诺保护 System Prompt**，因此不得放入密钥、Token、内部凭据或不可向最终访问者暴露的内容。页面通过 `params` 注入运行时值，占位符 `{{var}}` 由服务端渲染。
 
-传给模型的数据遵循最小必要原则。Database Function 查询结果先在 Page 内筛选字段和记录，只发送完成当前任务所需的内容；不得把整个 Catalog、整表数据、登录凭证或原始下游响应无差别塞入 `messages` / `variables`。
+传给模型的数据遵循最小必要原则。Database Function 查询结果先在 Page 内筛选字段和记录，只发送完成当前任务所需的内容；不得把整个 Catalog、整表数据、登录凭证或原始下游响应无差别塞入 `messages` / `params`。
 
 ## 计费与失败处理
 
@@ -440,44 +346,32 @@ System Prompt 在 **AI Function 配置**里维护，随版本快照进入线上
 
 AI Function 的管理接口（`ai-functions list/pull/validate/sync/usage` 以及 `deploy` 内的同步）按当前用户做 feature gate。未开通的用户会收到业务码 `800004011`、消息 `ai function feature is not enabled`；CLI 会把它翻译为带降级路径的错误。它不是 scope 缺失，重新 `auth login` 不会改变结果，不要循环授权或重试。
 
-处理方式：向用户说明当前账号未开通 AI Function；需求中的 AI 部分标记为阻塞，恢复条件是账号开通后重新 `deploy`。其余 Page、Database Function、FaaS 用 `deploy --skip-ai-functions` 正常发布，交付报告写明 AI Function 未同步、页面中的 AI 入口在开通前不可用。`deploy` 在写入任何远端 Function 之前先同步 AI Function，因此收到该错误时远端没有中间态，可直接加参数重跑。
+处理方式：向用户说明当前账号未开通 AI Function；需求中的 AI 部分标记为阻塞，恢复条件是账号开通后重新 `deploy`。其余 Page、Database Function、FaaS 用 `deploy --skip-ai-functions` 正常发布，交付报告写明 AI Function 未同步、页面中的 AI 入口在开通前不可用。降级前按[发布错误边界](release.md#function-发布顺序与错误边界)核对已执行步骤；未知写入先只读确认，不能盲目重跑。
 
 ### 页面如何处理运行态错误
 
-页面只能可靠地按错误性质处理。收到 AI credit、并发限制或服务错误时，保留 `error.code`、`error.message` 和本次 `requestId`，结束 loading，并按错误是否可重试给出提示；不要在页面里自动重试，更不要绕过 AI Function 直连模型。
-
-AI credit 耗尽会作为不可重试的错误返回，消息为 `AI credit is exhausted`。应提示应用 owner 检查可用 credit 或联系平台支持，不能把它当作网络故障反复重试。
+参阅已安装 SDK 文档，入口见[Page 调用方式](#page-调用方式)。
 
 ## 页面实现检查
 
-1. 页面按 `functionKey` 调用；`callSiteAIFunction` 显式传与配置相同的 `capability`。System Prompt / model / 参数由 AI Function 配置声明，`messages/input` 与 `variables` 是本次运行输入。
-2. 指定模型或参数前先查 `/open-apis/base/v3/sites/:token/ai/model_profiles`；`:token` 取当前应用配置的 `appToken`，能力标记必须与 `capability_type` 匹配。
-3. 用 `switch(result.type)` 判别渲染，不直接渲染 `delta.raw`；流式每个面板只有一个活动 handle，取消与卸载均调用 `destroy()`。
-4. text/vision 流式同时消费 `delta.reasoningContent` 与 `delta.content`（或用 `readSiteAITextDelta` 取 `{ answer, reasoning }`），分区渲染；结构化解析只基于最终 answer。
-5. `onError` 与 `onDone` 都结束 loading；image/video 用 `getSiteAIFunctionTask` 轮询到 `succeeded`/`failed`/`cancelled` 收尾。
-6. vision 不绕过公开 `SiteAIMessage` 类型猜测媒体 content；只提交所选 Profile 的 `input_modalities` 已声明的 image / video / audio / file，未暴露对应输入契约时明确报告阻塞。
-7. AI 调用走 AI Function，页面不保存模型凭证。
-8. 与 Base 数据组合时，查询仍走 Database Function；写入按[Mutation 与 FaaS 分工](mutations.md#写入方式选择)选择。
-
-## 区分三种「调试成功」
-
-AI Function 调试至少有三种互不等价的「成功」，不能互相替代地报告：
-
-- **配置校验成功**：`ai-functions validate` 返回 `is_success: true`，只证明 `meta.json` 合法，不代表能跑通。
-- **运行态调用成功**：接口能返回文本或 `taskId`，证明 Function 存在、未 `disabled`、鉴权与模型链路初步可用。CLI 对 text/vision 返回聚合文本。
-- **UI 流式成功**：页面 `onMessage` 多次收到增量并实时渲染，证明 SDK 回调与业务组件的增量显示已接通。
+按工程已安装的 SDK 文档验证调用、取消、错误与输出语义；老模板参考[冻结检查](legacy-ai-function.md#页面实现检查)。AI Function 页面只能通过宿主 broker 调用，不能直连模型域名或在代理失败时绕过宿主。
 
-尤其对文本 AI Function：CLI 聚合返回成功或超时，都**不能**直接判断页面 SSE 是否正常。页面选择 `invokeSiteAIFunctionStream` 时，用真实页面验证多次 `onMessage` 和 `onDone`；选择 `callSiteAIFunction` 聚合时，验证得到 `{type:'text'}` 和完整 `content`。媒体能力用 task 接口验证终态。
+配置校验、运行态调用与 UI 流式成功的区别见[AI 验收判定](verification.md#ai-验收判定)。
 
 ## AI Function 交付 checklist
 
 ```text
 1. 查询 model_profiles，选择 capability 匹配的 profile_id。
-2. 写 ai/<functionKey>/meta.json，先 validate（reasoning_depth 用 off/light/standard/deep；仅当 profile 的 thinking_levels 含 off 时关闭才生效）。
+2. 写 ai/<functionKey>/meta.json，由 deploy 校验（reasoning_depth 用 off/light/standard/deep；仅当 profile 的 thinking_levels 含 off 时关闭才生效）。
 3. 文本流式 UI 同时消费 delta.reasoningContent 与 delta.content。
 4. `callSiteAIFunction` 显式传 capability；文生图/文生视频使用 create task + poll task，不走文本 stream。
 5. 修改已有应用时，远端全部 key 已恢复到本地，未意外触发全量删除。
 6. record_id 不依赖短长度（^rec[A-Za-z0-9]{1,32}$）。
-7. deploy 后 ai-functions list 确认 function 存在且 disabled=false。
-8. 用真实页面按所选入口验证 text/vision（流式为多次 `onMessage` 增量和单次 `onDone`，错误时为 `onError` 且无 `onDone`；聚合为 text result）；用 task 接口验证 image/video 终态。
+7. 运行态未检查即列未验证；用户要求验收时按下述 AI 验收判定执行，Prod 验证按用户诉求决定。
 ```
+
+CLI 的 list/get/debug/task 默认 `--env preview`；prod 只读已发布版本，不作为草稿编辑依据。env 是函数版本，不是 CLI 运行环境。list 会读取全部分页后筛选 AI，pull 缺少 spec 或权限失败时停止。validate 仅验证指定本地项，不写入、不调用模型；sync 使用 kinds=[ai] 全覆盖，管理写入与校验不传 env。
+
+运行态验收方法见[AI 验收判定](verification.md#ai-验收判定)。
+
+CLI debug 使用 `--params` 对象：text/vision 发送 `{params,messages}`，image/video 发送 `{params,input}`；不能混用 messages 和 input。新请求不传 mode/output_mode。媒体任务回执 `task_id` 仅表示受理，保存 key/env 后续查原任务；查询成功不表示生成成功，failed/cancelled 停止并报告错误，不重新提交。SDK 对页面保持 `taskId` 字段。超时/断网可能已执行和计费，结果未知时保留 requestId/LogID，不自动重试。

package/skills/lark-base-database/references/database-function-limitations.md

@@ -6,7 +6,7 @@
 
 原则：先确认业务要保留的结果语义，再选择查询形式。判定时按诊断的位置、语义码和 Catalog 类型定位问题；默认采用生成参考中与当前条件匹配、已有验证的形式，并逐项核对其前提。
 
-例外：目录没有等价 SQL、前提不成立或改写会改变空值、行数及排序时，转到[SQL 外实现放在哪](../SKILL.md#sql-外实现放在哪)选择消费结果的实现位置。单个组合失败不代表组成它的所有能力都不可用；版本或运行环境不一致时，保留诊断和 LogID，先核对事实源。
+例外：目录没有等价 SQL、前提不成立或改写会改变空值、行数及排序时，转到[SQL 外实现放在哪](#sql-外实现放在哪)选择消费结果的实现位置。单个组合失败不代表组成它的所有能力都不可用；版本或运行环境不一致时，保留诊断和 LogID，先核对事实源。
 
 ## Stored Query 与分页
 
@@ -18,12 +18,20 @@
 
 默认逐列投影，保持输出 Schema 稳定；连接的每一侧使用明确的表或带别名的派生表，分阶段表达复杂查询。常规生成优先简单连接、顶层查询与带别名的派生表，而不是依靠深层组合表达全部业务逻辑。确需复杂组合时，依据生成参考和目标环境验证决定，而不将生成偏好当作平台能力结论。
 
-Database Function 需要 Catalog 中真实表依赖，以确定数据上下文；与 Base 数据无关的计算按[SQL 外实现放在哪](../SKILL.md#sql-外实现放在哪)处理。动态返回规模由调用方校验为非负整数并限制最大值；服务端资源预算以诊断中的实际限制为准。
+Database Function 需要 Catalog 中真实表依赖，以确定数据上下文；与 Base 数据无关的计算按[SQL 外实现放在哪](#sql-外实现放在哪)处理。动态返回规模由调用方校验为非负整数并限制最大值；服务端资源预算以诊断中的实际限制为准。
 
 ## 按位置取值
 
-先明确分区、排序、并列值与空分区的业务含义，再查[生成参考中的修复策略](base-sql-errors.generated.md)。默认只采用满足前提的已验证形式；没有等价形式时沿用[SQL 外实现选择原则](../SKILL.md#sql-外实现放在哪)。
+先明确分区、排序、并列值与空分区的业务含义，再查[生成参考中的修复策略](base-sql-errors.generated.md)。默认只采用满足前提的已验证形式；没有等价形式时沿用[SQL 外实现选择原则](#sql-外实现放在哪)。
 
 ## NULL 与数值边界
 
-改写前明确空值、空集合、数值精度和错误行为是否属于结果契约。默认保留业务所需语义，并按[生成参考的前提与验证说明](base-sql-errors.generated.md)选择修法；防护写法会改变错误行为时，先确认业务接受该变化。需要 SQL 外处理的部分统一按[实现位置原则](../SKILL.md#sql-外实现放在哪)决定，不把截断结果或丢失空值的结果当作等价替代。
+改写前明确空值、空集合、数值精度和错误行为是否属于结果契约。默认保留业务所需语义，并按[生成参考的前提与验证说明](base-sql-errors.generated.md)选择修法；防护写法会改变错误行为时，先确认业务接受该变化。需要 SQL 外处理的部分统一按[实现位置原则](#sql-外实现放在哪)决定，不把截断结果或丢失空值的结果当作等价替代。
+
+## SQL 外实现放在哪
+
+原则：SQL 无法等价表达时，在消费查询结果的代码中完成计算；选择位置首先看数据可见性，再看规模与复用需求。
+
+判定：只有计算仅影响查看者本就有权看到的行的展示、结果集小且无需跨页面复用时，才适合放在 Page。若计算需要查看者不应看到的明细、数据量大、需要跨页面复用或写回，则放在 FaaS（SQL 报错中的 “Edge Function” 即指 FaaS），并沿用既有身份、权限和参数边界；FaaS 仍需在服务端校验调用者权限，只返回允许公开的结果。不能先把无权查看的明细发给浏览器，再靠 Page 过滤或隐藏。
+
+默认：拿不准时选 FaaS。把应在服务端处理的计算放到 Page，可能泄露数据；多一道服务端调用通常更容易纠正。SQL 报错中的“SQL 外实现”不等于一律新建 FaaS，也不构成绕过现有权限模型的授权。