@lark-base-open/base-database-cli 1.4.5 → 1.4.8

package/skills/lark-base-database/references/development.md

@@ -2,12 +2,20 @@
 
 先按[Function 调用契约](#function-调用契约)核对实际调用路由与参数形态，再选择示例。SDK 是否安装只决定 API 文档与导入来源，不决定位置数组或命名对象；未安装 SDK 时保留用户现有依赖与 helper，不为消除分支而安装 SDK 或覆盖 helper。新建仅用 workspace。
 
-实现或修改 Page 的运行时接入时读取。FaaS 新增或修改时，还须在 meta.json 显式声明 inputSchema，见[FaaS 开发](faas.md#faas-开发)。基础单表写入与批量调用见[Mutation Function](mutations.md)。查询语法见[Database Function](database-function.md)，服务端 handler 与记录写入见[FaaS 协议](faas.md)，设计原则见[工程质量](style-guide.md)。
+实现或修改 Page 的运行时接入时读取。FaaS 新增或修改时，还须在 meta.json 显式声明 inputSchema，见[FaaS 开发](faas.md#faas-开发)。基础单表写入与批量调用见[Mutation Function](mutations.md)，查询语法见[Database Function](database-function.md)，模型能力见[AI Function](ai-function.md)，服务端 handler 与记录写入见[FaaS 协议](faas.md)，设计原则见[工程质量](style-guide.md)。
 
 ## 工程内平台指引
 
 开发前读取工程根目录 AGENTS.md 的 base-app 托管段落；它记录当前模板、实际安装的 SDK 版本与包内 docs 路径。SDK 工程按该版本包内文档实现 API；未安装 SDK 的 classic 按[调用契约](#function-调用契约)选择相应 helper 示例；已安装 SDK 但缺少文档时先核对包内容，不据此改用位置参数。CLI 在 init、check、deploy、dev 时维护该段落，不自动升级依赖。
 
+### SDK 类型诊断
+
+SDK 属性不存在或返回类型不匹配时，从报错表达式追踪实际调用 API 的返回类型，再核对已安装 SDK 的包内文档和类型声明；名称相近的类型不能直接互换。搜索未命中时，按该包 `package.json` 的 `exports` / `types` 定位声明，不据此猜测字段。
+
+修复应调整与真实契约不符的字段访问，或对已确认的扩展值做运行时检查和类型收窄。`as any`、双重断言或 `Record<string, unknown>` 只改变静态类型判断，不能单独证明字段存在。字段契约与示例以 SDK 文档为准。
+
+修正后重新运行 `base-database-cli check`，并按[验证方法](verification.md)在用户已授权范围内检查受影响页面的真实返回和展示，以及需求涉及的加载、缺失值回退、错误与重试。尚未完成运行态检查时明确列为未验证，不能以编译通过代替。
+
 ## 本地开发入口
 
 `dev [directory]` 默认使用当前目录，指定工程目录时写作 `base-database-cli dev ./app`；`--json` 流式输出，每行一个 JSON 事件。
@@ -22,7 +30,7 @@
 
 收到 `dev.host_not_connected` 时，向用户说明宿主尚未加载本地开发服务器，本地修改还未在宿主中生效；按事件提示打开 CLI 输出的链接并允许浏览器本地网络访问后重试。若页面直接显示已发布应用，说明当前域名暂不支持本地开发，改用 `base-database-cli deploy` 发布 Preview 验证。该提示只出现一次，dev 继续运行，稍后连接仍会发出 `dev.ready`。等待阈值默认 120 秒，可用 `BASE_DATABASE_DEV_HOST_TIMEOUT_MS` 调整（正整数毫秒）。
 
-FaaS 变化默认只本地构建；仅在用户已授权修改共享 Preview 时添加 `--deploy-preview`，它启动时及后续 FaaS 变化后发布完整应用 Preview。SQL/Mutation/绑定/依赖变化暂停自动发布，需单独检查并显式 deploy 后重启 dev。发布结果未知时保留回执并停止自动写入，已知 publishId 用 `deployments status <publishId> --wait` 只读核对，禁止盲目重发。退出会清理 Vite、监听、构建进程与本地锁。
+FaaS 变化默认只本地构建；仅在用户已授权修改共享 Preview 时添加 `--deploy-preview`，它启动时及后续 FaaS 变化后发布完整应用 Preview。Database Function、Mutation、AI Function、binding 或依赖变化暂停自动发布，需单独检查并显式 deploy 后重启 dev。发布结果未知时保留回执并停止自动写入，已知 publishId 用 `deployments status <publishId> --wait` 只读核对，禁止盲目重发。退出会清理 Vite、监听、构建进程与本地锁。
 
 配对令牌保存在项目 `.base-database-cli/state/dev-pairing-token`（权限 600），dev 重启保持不变；`dev --reset-pairing` 重新生成后须用新的 CLI 链接打开。令牌仅通过环境变量传给 Vite 子进程；`--json` 的地址已打码，完整地址只在人类可读输出显示。state 目录已由模板 gitignore 和上传打包规则排除。旧 SDK 不支持配对时须先升级工程 SDK。
 
@@ -37,10 +45,11 @@ project/
 ├── page/
 ├── database-functions/<functionId>/{main.sql,meta.json}
 ├── mutations/<functionId>/{spec.json,meta.json}
-└── server/functions/<functionId>/{index.ts,meta.json}
+├── server/functions/<functionId>/{index.ts,meta.json}
+└── ai/<functionKey>/meta.json                        # 按需创建
 ```
 
-Database Function、Mutation 与 FaaS 的 `functionId` 在应用内全局唯一，匹配 `/^[A-Za-z0-9_-]+$/`；Database Function ID 长度为 1～64。`functionId` 会作为 URL 路径段参与运行态调用，除该字符集外不接受其它字符。不同 FaaS Function 目录独立构建，不跨目录 import。classic 的 Page 和 `server-functions/` 分别维护 npm 工程与锁；新建 `init` 使用根 workspace（page + server），唯一根 package-lock.json；SDK 使用已发布版本，新建仅用 workspace。
+Database Function、Mutation、FaaS 与 AI Function 的 `functionId`（AI 配置中称 `functionKey`）在应用内全局唯一，匹配 `/^[A-Za-z0-9_-]+$/`，长度为 1～64。该标识会作为 URL 路径段参与运行态调用，除该字符集外不接受其它字符。不同 FaaS Function 目录独立构建，不跨目录 import。classic 的 Page 和 `server-functions/` 分别维护 npm 工程与锁；新建 `init` 使用根 workspace（page + server），唯一根 package-lock.json；AI 声明不属于 npm workspace。SDK 使用已发布版本，新建仅用 workspace。
 
 ## 第三方依赖策略
 
@@ -72,9 +81,11 @@ base-database-cli lark-cli -- api GET /open-apis/base/v3/sites/<app-token>/get -
 
 Function ID 为源码目录名且在应用内唯一。输入协议与工程配置的判定统一见[输入声明](workspace-migration.md#classic-输入声明)，CLI 不推断用户 helper。确认分支后，workspace 使用 SDK 示例；classic 分别读取[命名对象 helper](legacy-development.md#命名对象-helper)或[位置参数 helper](legacy-development.md#位置参数-helper)。参数名来自冻结的 meta.params / spec.params / inputSchema，不从 SQL 文本猜测。
 
-`contracts generate` 统一生成 `function-clients` 与 Function 输入类型映射：SQL 的参数名称、可选性与 `parameterOptions` enum、Mutation 声明，以及 FaaS Standard Schema 同次生成。workspace `defineFunction` 的 `meta.inputSchema` 直接用于 Agent 开放 schema；已有手写 `meta.json` `inputSchema` 工程继续兼容。生成类型只约束输入，运行时仍负责校验，不能凭 TypeScript 类型假定远端结果；Database Function 输出保持 unknown。
+`contracts generate` 使用工程已安装 SDK 的 codegen 生成 Function 客户端及类型映射，支持 SQL 参数、Mutation 声明和 FaaS Standard Schema。workspace `defineFunction` 的 `meta.inputSchema` 用于 Agent 开放 schema；已有手写 `meta.json` `inputSchema` 工程继续兼容。具体 API 和推断类型以该 SDK 包内 docs 为准；类型不能证明远端结果符合业务预期。
 
-Function 成功返回一层 `{code,msg,data}`。SQL data 为 ResultJSON；Mutation data 含 record_ids 及可选 records、record_not_found、ignored_fields；FaaS data 为业务结果。成功码不代表批量全部成功，见[调用与结果](mutations.md#调用与结果)。页面运行时 SDK 用法仅在工程已安装 SDK 时读取 SDK 包内文档；本 Skill 不复制 SDK API 说明。
+Function 成功返回一层 `{code,msg,data}`。SQL data 为 ResultJSON；Mutation data 含 record_ids 及可选 records、record_not_found、ignored_fields；FaaS data 为业务结果；AI Function data 按能力返回 text 结果或媒体任务回执。成功码不代表批量全部成功，见[调用与结果](mutations.md#调用与结果)。页面运行时 SDK 用法仅在工程已安装 SDK 时读取 SDK 包内文档；本 Skill 不复制 SDK API 说明。
+
+开发期命令行调试对所有 Function 使用同一条公共链路：先发布或复用目标 Preview，再按[调用站点函数](agent-tools.md#调用站点函数)读取说明并调用 `/functions/<function-id>/invoke`，站点管理者显式传 `env=preview` 与 `includeInternal=true`。AI Function 也使用公共 Function 说明与 `/functions/<function-id>/invoke`；text/vision 检查聚合结果，image/video 读取任务回执并按任务状态继续，页面流式显示仍在真实 Page 中验收。恢复、配置写入和发布不由调用命令代替。
 
 ## Page 调用
 
@@ -164,7 +175,7 @@ export function eventFields(now: number) {
 
 ## AI 对话与调用
 
-AI 调用按 [AI Function](ai-function.md) 实现，不创建 FaaS 模型代理，也不直连模型域名。
+AI 配置与 Page 调用按 [AI Function](ai-function.md) 实现，不创建 FaaS 模型代理，也不直连模型域名。工程恢复、Preview 配置写入和发布沿用公共 Function 工作流；开发期调用按本页[Function 调用契约](#function-调用契约)执行。
 workspace 的 AI 调用按已安装 SDK 的 docs/README.md 索引定位 API 与示例，不假定工程存在 classic 示例文件；classic 示例路径与语言接入见[存量 Page 参考](legacy-development.md#classic-ai-示例)。
 
 ## 开发期与运行态输出
@@ -174,6 +185,7 @@ workspace 的 AI 调用按已安装 SDK 的 docs/README.md 索引定位 API 与
 | lark-cli 默认 JSON 输出 | 先检查进程退出与外层 `ok`，再按该命令的 `data` 契约取值；错误诊断见 `error`      |
 | Page                    | 参阅已安装 SDK 的 docs/compat.md 与 docs/page.md                                 |
 | Database Function       | `data` 为 ResultJSON，包含 rows 等查询信息                                       |
+| AI Function             | text/vision 读取文本结果；image/video 读取任务 ID 后查询最终状态                 |
 | FaaS handler            | 返回 `{data,code,msg}`，data 为业务结果，不再由 Page 二次解包                    |
 | FaaS 下游记录写入       | 检查下游 envelope 和各 batch 的结果语义，见[FaaS 协议](faas.md#应用记录写入协议) |
 
@@ -205,17 +217,23 @@ workspace 的输入类型与 `DatabaseFunctionParameterOptions` 统一生成在
 
 ## 工程迁移与 SDK 升级
 
-工程结构和 helper 改动由 coding agent 按[工程迁移指南](workspace-migration.md)执行并验证；CLI 不自动改写。SDK 升级需在用户授权范围内核对依赖及调用方。
+修改已有工程先运行 `base-database-cli check --json`，读取成功或失败报告中的 `warnings`。`check`、`contracts generate`、`deploy` 和工程内 `doctor` 都读取实际安装的 SDK 版本：低于 CLI starter 默认版本时提醒（包括 patch 差异），相同或更高版本正常进入后续检查。API 用法以已安装包内文档为准；实际 codegen、契约格式和构建错误按诊断处理。
+
+- `SDK_BEHIND_CLI` 是非阻断的版本提醒。默认保留 SDK，读取警告 `packagePath` 所在包的 docs 和示例，不套用标注较新适用版本的 Skill 示例。
+- `SDK_VERSION_INVALID` 表示已安装 SDK 的包信息损坏，先修复工程依赖。`doctor` 将此错误记录在 `sdkCompatibility` 中（`severity: error`），继续检查登录、scope 和服务；`check`、`contracts generate`、`deploy` 则停止并报告该错误。
+- 用户已授权升级 SDK 时，执行警告给出的 `upgradeCommand`。读取目标 SDK `CHANGELOG.md` 中跨过的每个不兼容版本的 Migration：确认会坏什么、定位受影响调用、按步骤修改源码。然后依次运行 `base-database-cli contracts generate`、`base-database-cli check --json` 和工程 build；失败时按诊断继续迁移，不用 `as` 强转或自行指定返回泛型绕过迁移错误。
+
+CLI 不自动升级依赖或改写业务代码。工程结构和 helper 改动由 coding agent 按[工程迁移指南](workspace-migration.md)执行；结构迁移另需用户授权，不因 SDK 警告擅自进行。
 
 ### 手动迁移页面 helper
 
 操作步骤与改前/改后示例统一见[逐步迁移](workspace-migration.md#逐步迁移)。保留自定义业务逻辑，未经核对不覆盖 helper。
 
-## 本地检查与契约生成
+## Check 与契约生成
 
-`check` 先按需安装依赖，再核对 Function 契约，最后构建 Page/FaaS。workspace 或 SDK 工程的契约发生变化时会报告 `CONTRACT_STALE`；先在项目根显式执行 `base-database-cli contracts generate`，再运行 `base-database-cli check --json`，不要反复 check 或手改生成物。
+`check` 先在本地读取全部 Function 声明，按需安装依赖、核对 Function 契约，再用与 deploy 相同的本次 kind 集合调用统一 `/functions/validate`，最后构建 Page/FaaS。payload 始终声明 `sql/edge/mutation`；存在 `ai/` 根时还声明 ai kind，其中空根表示明确校验空集合。Validate 不修改 binding、draft、Artifact 或发布状态。workspace 或 SDK 工程的契约发生变化时会报告 `CONTRACT_STALE`；先在项目根显式执行 `base-database-cli contracts generate`，再运行 `base-database-cli check --json`，不要反复 check 或手改生成物。
 
-只有无 App SDK 的 classic 使用本地 metadata 自动更新输入类型。生成形态仍按[Function 调用契约](#function-调用契约)选择；check 的自动生成不改变 helper 路由。`--no-install` 要求依赖已经就绪，不能绕过契约核对。
+只有无 App SDK 的 classic 使用本地 metadata 自动更新输入类型。生成形态仍按[Function 调用契约](#function-调用契约)选择；check 的自动生成不改变 helper 路由。`--no-install` 要求依赖已经就绪，不能绕过契约核对。只有明确没有应用 API 访问条件的离线检查才使用 `--local-only`；结果中的 `serverValidation.status=not_run` 表示 SQL 编译、Catalog、AI model profile 和其他服务端语义均未验证。显式 `--skip-ai-functions` 时，AI 声明不进入本次校验 payload，结果中的 AI 数量为 0，不能报告 AI 已校验。旧工程缺少整个 `ai/` 根时同样不声明 ai kind，但结果会给出 `AI_FUNCTION_ROOT_ABSENT_PRESERVED`，表示远端 AI 被保留且未校验、未同步；先用公共 `pull` 恢复，而不是把缺失根当成空集合。
 
 ## dev 页面 bootstrap
 

package/skills/lark-base-database/references/faas.md

@@ -564,8 +564,7 @@ batch 路由单批最多 200 条。多选、多人员和多值关联这些集合
 
 当前 CLI 的 `contracts generate` 可从 SDK `defineFunction` 的独立 `contract.ts`
 提取 input/output；先用 `base-database-cli contracts --help` 核对能力。旧版本可继续手写 meta，
-不因此中断既有工程。CLI 只执行隔离后的 Schema 构造和 Standard JSON Schema 转换，
-无法隔离或转换时警告并使用 unknown/runtime-only，不执行业务入口。
+不因此中断既有工程。CLI 通过 esbuild 打包 `contract.ts`，并在有超时、内存和输出边界的子进程中执行顶层 Schema 构造与 Standard JSON Schema 转换；不执行 `index.ts`、handler 或业务入口。无法表示为 JSON Schema 的规则会警告并使用 unknown/runtime-only；语法、导入、导出、提前退出或超时属于阻塞错误，先按提示修复再生成。
 
 用 `contracts generate <工程目录>` 显式更新生成区和 Page 类型客户端；check/deploy
 发现过期契约时需要重新生成。后端发现 FG 不可用时使用 `--runtime-only` 省略发现 Schema，

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

@@ -94,9 +94,9 @@ const task = await createSiteAIFunctionTask({
 
 `reasoningContent` 是模型思考过程增量，`content` 是最终回答增量：两者分区渲染，思考过程放较小的过程区域，最终回答进正式结果区。**要从结果里解析结构化列表时，基于最终 answer（`content` 累积值）解析，不要基于 reasoning 内容解析。** 业务页面只处理 SDK 返回的 `{ content?, reasoningContent?, raw }`，无需自行解析原始流式传输格式。
 
-`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 的任务接口，任务完成判定统一见[任务受理与完成](ai-function.md#任务受理与完成)，classic 结果字段分别为 imageAssets / videoAsset。所有响应携带 `requestId`，用于监控与排查。
+`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 的任务接口，任务完成判定见[能力与调用入口](ai-function.md#能力与调用入口)，classic 结果字段分别为 imageAssets / videoAsset。所有响应携带 `requestId`，用于监控与排查。
 
-媒体任务只允许运行时覆盖有限字段：image 使用 `input.prompt` / `input.size` / `input.image`，video 使用 `input.prompt` / `input.image_url` / `input.duration`；model、张数、比例、水印等保持在 AI Function 配置中。`input.image` 接受单个字符串或字符串数组，数量上限按[模型能力](ai-function.md#可用模型-profile)核对；`input.duration` 必须是正数，并会按模型 Profile 上限收紧。图片生成参考 starter 的 `page/src/examples/ai-function/ImageTaskOperation.tsx`（只渲染 `imageAssets`），文生视频参考同目录 `ai-media-panel.tsx` 中的 `AIVideoPanel`（渲染 `videoAsset`）。两个示例按[任务受理与完成](ai-function.md#任务受理与完成)轮询，在新请求时通过 `requestSeq` 忽略旧任务结果，且带总轮询时限（`pollDeadlineMs`，默认 5 分钟）以避免死轮询；组件卸载时也停止 timer。不要用没有总时限或取消处理的 `while` 轮询。
+媒体任务只允许运行时覆盖有限字段：image 使用 `input.prompt` / `input.size` / `input.image`，video 使用 `input.prompt` / `input.image_url` / `input.duration`；model、张数、比例、水印等保持在 AI Function 配置中。`input.image` 接受单个字符串或字符串数组，数量上限按[最短闭环](ai-function.md#最短闭环)查询的 profile 自描述核对；`input.duration` 必须是正数，并会按模型 Profile 上限收紧。图片生成参考 starter 的 `page/src/examples/ai-function/ImageTaskOperation.tsx`（只渲染 `imageAssets`），文生视频参考同目录 `ai-media-panel.tsx` 中的 `AIVideoPanel`（渲染 `videoAsset`）。两个示例按[能力与调用入口](ai-function.md#能力与调用入口)轮询，在新请求时通过 `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 都采用严格字段白名单，多余字段会被拒绝。
 
@@ -111,7 +111,7 @@ AI credit 耗尽会作为不可重试的错误返回，消息为 `AI credit is e
 ## 页面实现检查
 
 1. 页面按 `functionKey` 调用；`callSiteAIFunction` 显式传与配置相同的 `capability`。System Prompt / model / 参数由 AI Function 配置声明，`messages/input` 与 `params` 是本次运行输入。
-2. 指定模型或参数前先查 `/open-apis/base/v3/sites/:token/ai/model_profiles`；`:token` 取当前应用配置的 `appToken`，能力标记必须与 `capability_type` 匹配。
+2. 指定模型或参数前先执行 `base-database-cli ai-functions models`；能力标记必须与 `capability_type` 匹配，参数只按 `ai_function_parameters` 配置。
 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` 收尾。

package/skills/lark-base-database/references/legacy-development.md

@@ -51,7 +51,7 @@ await invokeDatabaseFunction<{ created: boolean | null }>('createTask', {
 });
 ```
 
-契约生成与 check 的职责、依赖准备顺序见[本地检查与契约生成](development.md#本地检查与契约生成)。classic 的自动生成文件是 `page/src/lib/database-function-inputs.generated.ts`，不手改；具体参数形态按上方已选择的分支使用。
+契约生成与 check 的职责、依赖准备顺序见[Check 与契约生成](development.md#check-与契约生成)。classic 的自动生成文件是 `page/src/lib/database-function-inputs.generated.ts`，不手改；具体参数形态按上方已选择的分支使用。
 
 metadata 只声明输入，因此生成文件只约束调用参数。调用结果仍由 Page 按 operation 定义
 `invokeDatabaseFunction<TData>` 的 `TData`，并在运行时校验真实响应；CLI 不根据 handler
@@ -110,7 +110,7 @@ interface DatabaseRows<TRow> {
 }
 ```
 
-浏览器 SDK 对 Database Function、Mutation 和 FaaS 都只返回一层 `{data,code,msg}`。`invokeDatabaseFunction<TData>` 的 `TData` 只描述当前 operation 约定的顶层 `data`：Database Function 通常是 ResultJSON，FaaS 则以各 handler 的业务结果为准，不能统一假设存在 `recordId`。页面只检查一次顶层 `code`，再按 operation 契约校验 `data`；不得写成 `invokeDatabaseFunction<FaasHandlerResult<TData>>`，也不得对 `result.data` 二次解包。否则后端已经写入成功时，页面仍可能误报失败。
+本页 classic helper 对 Database Function、Mutation 和 FaaS 都只返回一层 `{data,code,msg}`。此 helper 的 `invokeDatabaseFunction<TData>` 中，`TData` 只描述当前 operation 约定的顶层 `data`：Database Function 通常是 ResultJSON，FaaS 则以各 handler 的业务结果为准，不能统一假设存在 `recordId`。页面只检查一次顶层 `code`，再按 operation 契约校验 `data`；不得对 `result.data` 二次解包。workspace SDK 按 codegen 映射推断结果，不沿用本页的显式泛型调用。
 
 运行时业务数据在边界处校验，不能只依赖 TypeScript 泛型。`functionId` 和所有路由是工程常量；用户输入只进入已声明的业务参数。
 

package/skills/lark-base-database/references/mutations.md

@@ -253,16 +253,15 @@ const result = await invokeDatabaseFunction('removeTaskAttachments', { taskId: '
 {"code":0,"msg":"success","data":{"record_ids":["recA"],"records":[{"rec_id":"recA","fldTitle":"准备评审"}]}}
 ```
 
-Page 结果类型与检查（单次、批量共用）：
+Page 示例适用版本：SDK 0.3.0 起。API 用法以已安装包内 docs 为准；未满足版本时按[SDK 升级流程](development.md#工程迁移与-sdk-升级)处理。以下仅检查业务码、部分失败和预期写入数量，平台返回结构由 SDK 提供。
+
+Page 结果检查（单次、批量共用）：
 
 <!-- example: mutation-result -->
 ```ts
-type MutationResult = {
-  record_ids: string[]
-  record_not_found?: string[]
-  ignored_fields?: {id: string; name: string; reason: string}[]
-}
-function assertComplete(result: MutationResult) {
+import type { DatabaseMutationResult } from '@lark-base-open/base-database-app-sdk/page'
+
+function assertComplete(result: DatabaseMutationResult) {
   const missing = result.record_not_found ?? []
   const ignored = result.ignored_fields ?? []
   if (missing.length || ignored.length) {
@@ -278,20 +277,26 @@ Page 一组参数调用（对应上文 `renameTasks`，一组参数修改一条
 
 <!-- example: mutation-single -->
 ```ts
-const result = await invokeDatabaseFunction<MutationResult>('renameTasks', { title: '统一标题', taskId: 'recA' })
+const result = await invokeDatabaseFunction('renameTasks', { title: '统一标题', taskId: 'recA' })
 if (result.code !== 0) throw new Error(result.msg || '写入失败')
 if (!result.data) throw new Error('写入结果缺失，请刷新核对')
 assertComplete(result.data)
+if (result.data.record_ids.length !== 1) {
+  throw new Error('写入记录数量不匹配，请刷新核对')
+}
 ```
 
 Page 多组参数调用（对应上文 `createTask`，每组创建一条记录）：
 
 <!-- example: mutation-batch -->
 ```ts
-const result = await invokeDatabaseMutationBatch<MutationResult>('createTask', [{ title: '准备评审' }, { title: '补充文档' }])
+const result = await invokeDatabaseMutationBatch('createTask', [{ title: '准备评审' }, { title: '补充文档' }])
 if (result.code !== 0) throw new Error(result.msg || '写入失败')
 if (!result.data) throw new Error('写入结果缺失，请刷新核对')
 assertComplete(result.data)
+if (result.data.record_ids.length !== 2) {
+  throw new Error('批量写入返回的记录数量异常，请刷新核对')
+}
 ```
 
 workspace 从已安装 SDK `/page` 导入两个 helper，并按包内 docs 核对 API；classic 按[helper 契约与导入](legacy-development.md#function-调用契约)选择实际形态。返回 `{code, data?, msg?}`。先检查顶层业务码，再检查 `data` 中的部分结果，不重复解包。

package/skills/lark-base-database/references/release.md

@@ -37,13 +37,13 @@ README、源码、配置和部署依赖属于 Preview 制品输入，变化后
 base-database-cli check --json
 ```
 
-check 的依赖准备、契约核对、`CONTRACT_STALE` 恢复和无 SDK classic 自动生成条件统一见[本地检查与契约生成](development.md#本地检查与契约生成)。该命令只做本地验证，不替代服务端查询校验或真实运行态验收。
+check 的依赖准备、契约核对、`CONTRACT_STALE` 恢复、统一服务端 Validate 和无 SDK classic 自动生成条件见[Check 与契约生成](development.md#check-与契约生成)。默认 check 通过证明本次 payload 已通过无副作用服务端校验，仍不替代真实运行态验收；本地存在 `ai/` 根时 payload 包含 AI，空根表示明确校验空集合。旧工程缺少整个 `ai/` 根时保留远端 AI，并在结果中标明 AI 未校验、未同步，先执行公共 `pull` 恢复声明。显式 `--local-only` 只证明本地结构与构建，显式 `--skip-ai-functions` 只校验排除 AI 后的 payload。
 
 依赖安装使用 CLI 随包固定的 npm，不受宿主 PATH 中 npm 版本影响。Preview deploy 在安装前获取目标应用的服务端依赖策略，并校验最终制品范围内全部 `package.json`；受限来源、非法 manifest 或策略查询失败时不会安装、构建或上传。添加依赖时的查询与判断见[第三方依赖策略](development.md#第三方依赖策略)。安装失败时保留子项目路径、npm 版本与原始错误：lock 不一致先核对本次 `package.json` 变更，按 CLI 错误提示修复该子项目的 lock 并检查差异，再重试一次；网络或权限错误先解决对应原因。不要盲删 lock、循环切换 npm 版本，也不要用 `--no-install` 掩盖安装失败；重试仍失败时保留证据并定位原因，不自动报告部署成功。
 
 ## Preview
 
-第三方 Agent 的首次 Preview 在执行 `deploy` 前，先根据 FaaS 源码和用户需求判断是否需要环境变量。没有自定义环境变量引用、且用户未要求查询或配置环境变量时，跳过环境变量流程，直接继续本节发布，不执行 `environment-variables list` 或额外询问配置。有引用或用户明确要求时，再按[环境变量协议](environment-variables.md)收集引用、声明缺失定义并核对 Preview 值。缺少必填值时一次性询问，保留工程与当前会话；收到完整回复后保存并自动继续首次 Preview。CLI 在构建前校验声明，Artifact 上传与源码回读后、Preview 发布前再次校验必填值。普通更新和 Prod 仍按本流程的制品与授权契约执行。
+第三方 Agent 的首次 Preview 在执行 `deploy` 前，先根据 FaaS 源码和用户需求判断是否需要环境变量。没有自定义环境变量引用、且用户未要求查询或配置环境变量时，跳过环境变量流程，直接继续本节发布，不执行 `environment-variables list` 或额外询问配置。有引用或用户明确要求时，再按[环境变量协议](environment-variables.md)收集引用、声明缺失定义并核对 Preview 值。缺少必填值时一次性询问，保留工程与当前会话；收到完整回复后保存并自动继续首次 Preview。CLI 在构建前校验声明，草稿提交后、Preview 发布前再次校验必填值。普通更新和 Prod 仍按本流程的制品与授权契约执行。
 
 在含 `base-database.jsonc` 的目录执行：
 
@@ -51,7 +51,7 @@ check 的依赖准备、契约核对、`CONTRACT_STALE` 恢复和无 SDK classic
 base-database-cli deploy
 ```
 
-CLI 先解析账号环境、查询依赖策略并校验 package.json 来源，再安装依赖、提取 SDK 契约、检查声明与查询、构建 Page/FaaS、归档和发布。安装仍早于依赖 SDK 的契约提取；查询校验失败不继续构建。Function 同步与失败恢复按[发布顺序与错误边界](#function-发布顺序与错误边界)处理。
+CLI 先解析账号环境、查询依赖策略并核对源码基线、校验 package.json 来源，再安装依赖、提取 SDK 契约、检查声明与查询、构建 Page/FaaS、归档和发布。安装仍早于依赖 SDK 的契约提取；查询校验失败不继续构建。Function 同步与失败恢复按[发布顺序与错误边界](#function-发布顺序与错误边界)处理。
 
 等待命令完成，进程仍在运行不代表失败，不重复启动部署。只有发布成功响应中的顶层 `baseAppUrl` 是可信交付入口，制品大小、SHA-256 和 publish ID 用于追溯。不能用历史 URL、管理后台、Catalog 或内部 `staticUrl` 替代缺失入口。
 
@@ -95,11 +95,11 @@ CLI 先解析账号环境、查询依赖策略并校验 package.json 来源，
 
 ## Function 发布顺序与错误边界
 
-Preview 将 sql/edge/mutation 与本地非空且未跳过的 ai 放入同一次 `/functions` PUT；PUT 成功后才同步 agent-tools 策略、上传 Artifact 并发布 Preview。不先单独同步 AI。空 ai/ 或 `--skip-ai-functions` 不声明 ai kind，保留远端 AI；交付时说明 AI 未同步及未验证。
+Preview 将 sql/edge/mutation、源码包及新增绑定原子提交到草稿，修订不匹配时拒绝整轮写入，成功后再提交受修订保护的 Preview 发布。存在 `ai/` 且未跳过时，AI 按本地全集覆盖：空目录删除全部 AI，非空目录覆盖声明集；缺少目录或 `--skip-ai-functions` 时保留远端 AI 及其排除项，其他 Function 的工具策略仍应用本地声明，并说明 AI 未同步、未验证。普通建站不先单独同步 AI。
 
-Prod 提升已完成的 Preview，不重新执行 Function PUT，不单独同步 AI，也不重新构建或上传制品。`--skip-ai-functions` 不会把尚未生成的新 Preview 混入 Prod。
+Prod 提升已完成且经用户确认的 Preview，不重新提交草稿，不单独同步 AI，也不重新构建或上传制品。`--skip-ai-functions` 不会把尚未生成的新 Preview 混入 Prod。
 
-这些步骤不是跨 Base 绑定、Function、策略、Artifact 与发布的事务。Function PUT 前可能已经更新 Base 绑定，之后的步骤也可能部分完成。确定的校验或 feature gate 错误按原因修正；超时、断网或结果未知先通过已有发布 ID、绑定与 Function 只读查询核对已执行状态，再决定下一步，不能据此断言远端状态未变更或盲目重跑写入。普通建站不需要额外执行 `ai-functions sync`；该显式命令会独立全量覆盖草稿，包括空集合删除，须有对应授权。
+草稿提交和异步发布是两个阶段：提交成功不代表发布成功。确定的校验或 feature gate 错误按原因修正；并发冲突、缺少基线和未知结果统一按[远端更新与冲突恢复](workspace.md#远端更新与冲突恢复)处理。各类 Function 沿用同一套发布流程，不为任一 Function 类型额外执行同步命令。
 
 ## Prod
 
@@ -111,7 +111,7 @@ Prod 提升已完成的 Preview，不重新执行 Function PUT，不单独同步
 base-database-cli deploy --production --yes
 ```
 
-CLI 读取 `.base-database-cli/state/preview.json`，校验应用 appToken、Artifact SHA-256 与工作区输入指纹，发布同一份制品，不重建或上传替代品。Preview 记录缺失或与当前工程不一致时，重新生成 Preview 并取得确认。`--yes` 只是向 CLI 传递已有授权。
+CLI 读取 `.base-database-cli/state/preview.json`，校验应用 appToken、Artifact SHA-256 与工作区输入指纹，并由服务端核对确认的 Preview ID 及对应草稿修订，发布同一份内容，不重建或上传替代品。Preview 记录缺失、无法证明修订或与本地/远端不一致时，停止 Prod，整合后重新生成 Preview 并取得确认。`--yes` 只是向 CLI 传递已有授权。
 
 Prod 发布不会自动更新 Base workflow。存在通知集成时，按 Preview 留存的清单逐个完成[生产入口切换](notifications.md#生产入口切换)。切换失败则明确报告“Prod 已发布，但通知入口切换未完成”，保存失败对象与证据；不重复发布应用来掩盖外部配置失败。
 

package/skills/lark-base-database/references/verification.md

@@ -13,7 +13,7 @@
 | 查询校验 | Catalog、参数声明、失败节点与支持集 | 缩小到具体错误，不通过猜参数类型绕过 |
 | 构建 | Page/FaaS 编译错误、依赖与模板调用契约 | 修复实现，不伪造类型让错误协议编译通过 |
 | 发布 | publish ID、真实状态、制品与返回入口 | 使用[发布任务查询](#发布任务查询)确认现状，不盲目启动第二次发布 |
-| Page/Function | HTTP 状态、业务码、输入输出与 invoke LogID | 按 [Page](development.md)、[Database Function](database-function.md)、[Mutation](mutations.md)、[FaaS](faas.md) 分层定位 |
+| Page/Function | HTTP 状态、业务码、输入输出与 invoke LogID | 按 [Page](development.md)、[Database Function](database-function.md)、[Mutation](mutations.md)、[FaaS](faas.md)、[AI Function](ai-function.md) 分层定位 |
 | 通知与原生配置 | 目标资源完整定义、入口、状态与失败节点 | 按[通知状态](notifications.md#状态与失败处理)保留授权范围 |
 
 ## 发布任务查询
@@ -35,33 +35,24 @@ base-database-cli deployments status <publish-id> --wait
 
 静态检查、构建、查询编译、部署成功分别证明对应阶段，不证明完整业务链路。新建 Base 的常规验证或发布后补齐示例数据，先完整读取并执行[示例数据验收](release.md#从零建站示例数据验收)，其中包含 CLI 写入格式和页面 Database Function 回读的实际路径；用户明确要求运行态验收时可以追加本次范围内的只读 Database Function 调用和可用浏览器检查。
 
-AI 与其他 Function 的 Preview/Prod 发布顺序、skip 行为和错误恢复统一见[发布参考](release.md#function-发布顺序与错误边界)。`ai-functions validate` 是编辑期可选自检。
+各类 Function 的 Preview/Prod 发布顺序、skip 行为和错误恢复统一见[发布参考](release.md#function-发布顺序与错误边界)。默认 `base-database-cli check` 除项目结构、依赖、契约与 Page/FaaS 构建外，还用与 deploy 相同的 payload 执行统一服务端 Validate；存在 `ai/` 根时包含 AI，缺少整个根时保留远端 AI 并报告未校验、未同步。显式 `--local-only` 时不运行服务端阶段，不能据此报告服务端 Function 有效；显式 `--skip-ai-functions` 时 AI 也不在 payload 中，不能报告 AI 已校验。
 
-写入验收先确认目标、测试数据和用户授权，尤其已有 Base、业务通知和不可逆操作。不得仅为测试而创建生产业务记录或外发消息。用户要求的写入验证完成后，清理仍遵守同一资源操作的授权要求。
-
-浏览器不可用、没有必要登录态或 Preview 不支持多角色时，报告未验证项和恢复条件，不索取或输出原始 Cookie/Token。Preview 的可用角色与身份见[Preview 与 Prod 准入](permission-design.md#preview-与-prod-准入)，单账号通过不能作为多角色权限验收；普通成员检查需在已授权的 Prod 任务中进行。
-
-## AI 验收判定
+普通 `deploy` 会把本地声明的全部 Function 交给统一服务端校验和写入，任一项失败就整批拒绝且不落库。各类声明的全量覆盖与显式跳过边界见[发布参考](release.md#function-发布顺序与错误边界)。
 
-AI Function 调试至少有三种互不等价的「成功」，不能互相替代地报告：
+命令行运行态检查使用公共 Function 入口。先按[调用站点函数](agent-tools.md#调用站点函数)读取目标环境中的函数说明，再调用返回的 `callCommand`。开发期 Preview 检查在 `--params` 中显式传 `env=preview` 与 `includeInternal=true`，Prod 检查传 `env=prod`，不能用 Prod 成功推断未发布的本地修改已经生效。
 
-- **配置校验成功**：deploy 内配置校验通过，或可选的 `ai-functions validate` 返回 data 中的 `valid === true` 且 `results` 各项 `code === 0`，只证明 `meta.json` 合法，不代表能跑通。
-- **运行态调用成功**：接口能返回文本或 `taskId`，证明 Function 存在、未 `disabled`、鉴权与模型链路初步可用。CLI 对 text/vision 返回聚合文本。
-- **UI 流式成功**：页面 `onMessage` 多次收到增量并实时渲染，证明 SDK 回调与业务组件的增量显示已接通。
+## Function 证据分层
 
-尤其对文本 AI Function：CLI 聚合返回成功或超时，都**不能**直接判断页面 SSE 是否正常。页面选择 `invokeSiteAIFunctionStream` 时，用真实页面验证多次 `onMessage` 增量和单次 `onDone`，错误时为 `onError` 且无 `onDone`；选择 `callSiteAIFunction` 聚合时，验证得到 `{type:'text'}` 和完整 `content`。媒体能力用 task 接口验证终态。
+- **Check**：默认 check 成功证明工程结构、声明、依赖、本地构建及本次 payload 的服务端 Function 语义校验通过；缺少 `ai/` 根或显式 `--skip-ai-functions` 时不包含 AI 校验证据。`--local-only` 成功只证明本地部分，`serverValidation.status=not_run`。
+- **配置写入**：deploy 的草稿原子提交回执成功，证明本次各类声明通过服务端校验并进入目标 Preview 草稿；不证明运行态调用成功。
+- **运行态调用**：公共 `/functions/<function-id>/invoke` 返回顶层业务成功及预期 data，证明目标环境的 Function 存在、鉴权通过且本次执行成功。AI 的 OpenAPI 媒体回执字段为 `task_id`，页面 SDK 映射为 `taskId`；任务受理仍须查询终态。
+- **页面运行态**：按 Page 实际入口验证数据、交互和展示。AI 流式入口验证多次 `onMessage` 增量和单次 `onDone`，错误时为 `onError` 且无 `onDone`；聚合时，验证得到 `{type:'text'}` 和完整 `content`。命令行聚合成功不能替代 UI 流式证据。
 
-普通建站未做运行态检查时列为未验证；用户要求验收时按所选调用方式验证 Preview。Prod 是否验证按用户诉求决定。
+这些检查按用户要求的范围执行，不把 Preview 页面必验或 Prod 再验设为所有开发任务的前置条件。未执行的层级列为未验证；不得用静态检查、测试环境、CLI 调试或页面证据相互推断。
 
-读取 `ai-functions validate --json` 的 stdout 时，CLI 直接输出 data 对象；按下面的判定读取（不再解一层 data）：
+写入验收先确认目标、测试数据和用户授权，尤其已有 Base、业务通知和不可逆操作。不得仅为测试而创建生产业务记录或外发消息。用户要求的写入验证完成后，清理仍遵守同一资源操作的授权要求。
 
-<!-- example: ai-validation-result -->
-```js
-const data = JSON.parse(stdout);
-const configurationValid = data.valid === true &&
-  Array.isArray(data.results) &&
-  data.results.every(result => result != null && result.code === 0);
-```
+浏览器不可用、没有必要登录态或 Preview 不支持多角色时，报告未验证项和恢复条件，不索取或输出原始 Cookie/Token。Preview 的可用角色与身份见[Preview 与 Prod 准入](permission-design.md#preview-与-prod-准入)，单账号通过不能作为多角色权限验收；普通成员检查需在已授权的 Prod 任务中进行。
 
 ## 重试与失败证据
 

package/skills/lark-base-database/references/workspace-migration.md

@@ -46,25 +46,16 @@ if (result.code !== 0 || !result.data) throw new Error(result.msg);
 export const rows = result.data.rows;
 ```
 
-改后先确认已安装 SDK 的类型扩展协议。对于只导出输入映射的生成模块，在独立源码 `page/src/function-inputs.ts` 连接 SDK；不改生成文件，不复制一份参数定义。已有生成客户端提供同一扩充时核对后复用，避免冲突。
+先按[SDK 版本与升级](development.md#工程迁移与-sdk-升级)核对并获得所需升级授权。以下 Page 示例适用版本：SDK 0.2.0 起。安装配套 SDK 后运行 `contracts generate`，由 codegen 同时生成 Function ID 的输入和输出映射；不手写模块扩充或返回泛型。纯 SQL 工程也须生成类型，缺少映射时先核对 CLI/SDK 版本与生成结果。
 
-<!-- example: migration-input-augmentation -->
-```ts
-import type { DatabaseFunctionInputMap as GeneratedInputs } from './generated/function-inputs';
-import '@lark-base-open/base-database-app-sdk/page';
-declare module '@lark-base-open/base-database-app-sdk/page' {
-  interface DatabaseFunctionInputMap extends GeneratedInputs {}
-}
-```
-
-改后（workspace SDK，加载上述扩充）：
+改后（workspace SDK）：
 
 <!-- example: migration-named -->
 ```ts
-import type {} from './function-inputs';
 import { invokeDatabaseFunction } from '@lark-base-open/base-database-app-sdk/page';
-const result = await invokeDatabaseFunction<{ rows: unknown[] }>('searchTasks', { status: '进行中' });
+const result = await invokeDatabaseFunction('searchTasks', { status: '进行中' });
 if (result.code !== 0 || !result.data) throw new Error(result.msg);
+if (!Array.isArray(result.data.rows)) throw new Error('查询结果结构无效');
 export const rows = result.data.rows;
 ```
 
@@ -81,6 +72,6 @@ npm run check --workspace page
 base-database-cli check --json
 ```
 
-`contracts generate` 必须成功，生成文件与实际调用方一同审阅；`check --json` 必须成功且各检查项无 failed，不能只看 JSON 可解析。CONTRACT_STALE 先重新生成后核对源变更；非法 functionInputs 按配置错误修正；布局冲突按真实目录与锁修复，不能删除 template 绕过校验。check 的职责和先后顺序见[本地检查与契约生成](development.md#本地检查与契约生成)。
+`contracts generate` 必须成功，生成文件与实际调用方一同审阅；`check --json` 必须成功且各检查项无 failed，不能只看 JSON 可解析。CONTRACT_STALE 先重新生成后核对源变更；非法 functionInputs 按配置错误修正；布局冲突按真实目录与锁修复，不能删除 template 绕过校验。check 的职责和先后顺序见[Check 与契约生成](development.md#check-与契约生成)。
 
 编译通过不证明请求行为正确。用请求替身覆盖迁移过的输入/输出分支，随后在已有授权范围内按[发布与交付](release.md)部署并验收同一 Preview。未完成运行态验收时交接明确“本地通过，Preview 待验收”，不宣称业务迁移完成。

package/skills/lark-base-database/references/workspace.md

@@ -61,7 +61,7 @@ CI 跳过更新检查；其他环境正常检查。检查失败不阻塞任务
 
 非 doctor 命令可能只透出错误文字而没有 subtype；按上述原文特征判定，不因缺少码名就把应用权限未开通误判为用户未授权，无法匹配时保留原错误继续定位。
 
-AI Function 管理命令或 deploy 返回 `800004011`（`ai function feature is not enabled`）不是 scope 问题，auth login 无效；按[未开通 AI Function](ai-function.md#未开通-ai-function-时)降级处理。其他错误按其原因处理。
+公开回执同时返回 `800004011` 和 `ai function feature is not enabled` 时才可判定 AI Function 门禁；这不是 scope 问题，auth login 无效，按[AI Function 失败处理](ai-function.md#失败处理)的 fail-closed 与用户授权边界处理。统一 Function 接口若只返回 `800004011`、`function write failed` 与 LogID，CLI 无法读取服务端日志或从 LogID 判因，不得推断为 AI 门禁。其他错误按公开回执实际原因处理。
 
 ## 先选择工程来源
 
@@ -73,7 +73,19 @@ base-database-cli context . --summary --json
 
 它只汇总本地配置、Catalog、Function metadata、init/Preview 回执和部署输入 fingerprint；不认证、不访问远端、不构建或发布。摘要保留决策所需的状态、资源数量、readiness 和 next action，不输出本地路径、fingerprint 值或逐项资源。需要排障时去掉 `--summary` 查看完整快照。`project.status=uninitialized` 表示当前目录缺少 `base-database.jsonc`，按下述工程来源选择 init 或 pull，不能仅凭空目录自行推断远端来源。不要从快照推断运行态、权限或发布成功。
 
-已有工程直接增量修改；只有远端应用时，在空目录执行 `base-database-cli pull . --app-token <app-token> --env online`；确认为新建时才 init。保留用户未提交内容，不能以恢复工程为由覆盖非空目录。
+已有工程直接增量修改；deploy 提示远端变化或缺少基线时，按[远端更新与冲突恢复](#远端更新与冲突恢复)整合。只有远端应用时，在空目录执行 `base-database-cli pull . --app-token <app-token> --env online`；确认为新建时才 init。保留用户未提交内容，不能以恢复工程为由覆盖非空目录。
+
+## 远端更新与冲突恢复
+
+CLI 自动保存 init、pull 和提交成功后的草稿基线。`REMOTE_SOURCE_CHANGED`、`REMOTE_BASELINE_MISSING` 或 pull 的 `sourceBaseline.status=requires-reconciliation` 时，用同一应用、环境和 profile 执行 `base-database-cli pull <临时目录> --app-token <app-token>`；比较并整合源码，以及返回材料路径中的 Function、binding 和工具策略。保留本地身份、凭证及需求外内容；无法判断的业务冲突请用户决定。合并后执行 check，再用 `base-database-cli deploy --baseline-from <临时目录>` 显式采用已审阅的基线。远端再次变化时重新拉取、比较，不自动采用最新修订。
+
+应用尚无源码包时，pull 返回 `source=unavailable`，只导出草稿基线与配置材料；使用已有本地工程完成比较与整合，不把材料目录当作恢复后的源码工程。
+
+`DRAFT_SUBMISSION_UNKNOWN`、`DRAFT_RESPONSE_UNKNOWN` 或 `PUBLISH_OUTCOME_UNKNOWN` 表示结果未知，先停止写入。草稿通过临时目录 pull 比较，发布通过[发布任务查询](verification.md#发布任务查询)核对现有记录；仍无法确认时报告错误，不自动重提。`DRAFT_PROTOCOL_UNSUPPORTED` 时需要平台升级，不退回逐接口覆盖写入。
+
+`pull` 是整个应用的统一恢复入口，从 `source_code` 一次恢复 Page、Database Function、Mutation、FaaS、AI Function 和工程配置。普通 deploy 上传的源码包包含当时本地完整的 `ai/<functionKey>/meta.json`；源码包已有 `ai/` 时后端原样返回，不按数据库草稿覆盖。只有整个 `ai/` 根缺失时，才用同份当前草稿声明补全 AI Function；源码包和当前草稿都没有 AI Function 时，恢复结果仍没有 `ai/`。已有源码包下载失败、损坏或权限不足时整次恢复失败，不由 CLI 按 Function 类型拼接工程。
+
+恢复出的工程是后续本地事实源。普通 deploy 按其中各类 Function 的完整本地集合覆盖远端草稿，因此执行 deploy 前应审阅全部声明。
 
 ## 需求与 Base 定位
 
@@ -165,6 +177,7 @@ page/                # React 页面
 database-functions/                 # Database Functions
 mutations/           # 基础写入声明
 server/              # workspace 服务端 FaaS Functions
+ai/<functionKey>/meta.json # 使用 AI Function 时创建；每个目录声明一个 AI Function
 package.json         # page + server npm workspaces
 package-lock.json    # 唯一根依赖锁
 .base-database-cli/      # 被 Git 忽略的 CLI 本地状态与临时制品
@@ -186,7 +199,7 @@ package-lock.json    # 唯一根依赖锁
 
 ## 增量修改与追加绑定
 
-先读取 `base-database.jsonc`、`catalog.json`、相关源码和本地修改。按需求决定是否需要远端发布状态或最新 schema；只改 UI 不重复拉取全部远端资源。修改保留需求外 Function，因为部署更新是全量覆盖。
+先读取 `base-database.jsonc`、`catalog.json`、相关源码和本地修改。按需求决定是否需要远端发布状态或最新 schema；只改 UI 不重复拉取全部远端资源。修改保留需求外 Function：Database Function、Mutation、FaaS，以及存在 `ai/` 根时的 AI Function，以本地项目声明全量覆盖远端草稿；AI 的声明目录是 `ai/*/meta.json`，空根表示权威空集合。旧工程缺少整个 `ai/` 根时不覆盖远端 AI，先用公共 `pull` 恢复声明。新增、修改或删除任何 Function 都先改本地事实源，再走公共 check/deploy 流程。
 
 需要绑定同一 Base 中的新表时，不重新执行 init 或 pull。先从 `lark-cli base +table-list/get` 的真实结果取得 ID，再在项目根目录执行：
 
@@ -216,6 +229,7 @@ base-database-cli lark-cli -- api GET /open-apis/base/v3/sites/<app-token>/catal
 | Page | page/ | page/ |
 | FaaS 源码与契约清单 | server/functions/、server/contracts.generated.json | server-functions/functions/、server-functions/contracts.generated.json |
 | SQL / Mutation | database-functions/、mutations/ | database-functions/、mutations/ |
+| AI Function | ai/<functionKey>/meta.json | ai/<functionKey>/meta.json |
 | npm 锁 | 根 package-lock.json，Page/server 不建嵌套 lock | page/ 与 server-functions/ 各自的 lock |
 
 workspace 使用平台构建器。classic 在服务端声明 SDK（dependencies 或 devDependencies）或服务端能解析 SDK 时使用平台构建器，否则执行服务端工程自身 build。仅 Page 装 SDK 可启用 Page/契约 codegen，不自动把服务端变为 SDK 工程；两项能力由各自消费位置决定。平台构建器按同一函数清单构建并核对 meta.json/index.ts，生成 CJS 与 manifest；传统 handler 保留调用约定，SDK defineFunction 注入运行时绑定。

package/templates/database-starter/page/README.md

@@ -29,7 +29,7 @@ The application runs in a BaseApp iframe. It does not hold login credentials or
 
 Do not call `postMessage`, use the raw Channel Client, or fetch a business domain directly from business code.
 
-Declare the model, System Prompt, reasoning depth, image size, video duration, and related settings in `ai/<functionKey>/meta.json` at the project root. Validate with `base-database-cli ai-functions validate <functionKey>` and sync through `deploy`. The page sends call-specific `params` and `messages` or `input` for the selected `functionKey`. Preview uses the draft configuration; Prod uses it only after production publication. Before calling a Function, confirm that its `functionKey` has been synced and that `disabled` is not `true`.
+Declare the model, System Prompt, reasoning depth, image size, video duration, and related settings in `ai/<functionKey>/meta.json` at the project root. Run the project-level check, then use an ordinary `deploy`; the unified Function write validates and publishes AI declarations together with Database Function, Mutation, and FaaS declarations. The page sends call-specific `params` and `messages` or `input` for the selected `functionKey`. Preview uses the draft configuration; Prod uses it only after production publication. Before calling a Function, confirm that the latest project Preview was published and that `disabled` is not `true`.
 
 ## Request identity and CSRF
 

package/templates/database-starter-v2/README.md

@@ -16,10 +16,10 @@ workspace 工程结构。
 
 ## Status and limitations
 
-模板使用已正式发布的 SDK；远端构建与业务系统仍需单独验收。
+模板固定 SDK 依赖版本；远端构建与业务系统仍需单独验收。
 
 ## Local project
 
-workspace 使用唯一根 npm workspace（page、server）和根 package-lock.json，SDK 正式版本由 page、server 的 package.json 精确固定，需提供 codegen 入口；缺失时按 CLI 报错给出的安装命令执行，版本与新建工程模板一致；安装依赖后执行 contracts generate，再运行 check。
+workspace 使用唯一根 npm workspace（page、server）和根 package-lock.json；Database Function、Mutation、FaaS 与可选的 AI Function 声明分别位于 `database-functions/`、`mutations/`、`server/functions/` 与 `ai/<functionKey>/meta.json`。SDK 版本由 page、server 的 package.json 精确固定，需提供 codegen 入口；缺失时按 CLI 报错给出的安装命令执行，版本与新建工程模板一致；安装依赖后执行 contracts generate，再运行 check。各类 Function 的恢复、校验和发布统一使用项目级 pull/check/deploy 流程。默认 `check` 完整解析全部 Function 并调用统一服务端 Validate；明确离线时才使用 `--local-only`。
 
 安装后阅读 node_modules/@lark-base-open/base-database-app-sdk/docs/README.md。运行 contracts generate → check；本地 check 使用 CLI 内置平台构建器。云端根 npm ci 后直接调用平台构建器，Page 执行 npm run build --workspace page，不从工程脚本调用 CLI。classic 仅保留存量兼容。

package/templates/database-starter-v2/package-lock.json

@@ -133,9 +133,9 @@
       "license": "MIT"
     },
     "node_modules/@lark-base-open/base-database-app-sdk": {
-      "version": "0.1.0",
-      "resolved": "https://registry.npmjs.org/@lark-base-open/base-database-app-sdk/-/base-database-app-sdk-0.1.0.tgz",
-      "integrity": "sha512-XR2rBZLdVISuOd6ovd1tCZwsgBi1hjqkxlVncsbavAsDxbDmeO9BvNPphvoBUpx3TBEB3DcTVPJzBaqoQUY1JA==",
+      "version": "0.3.2",
+      "resolved": "https://registry.npmjs.org/@lark-base-open/base-database-app-sdk/-/base-database-app-sdk-0.3.2.tgz",
+      "integrity": "sha512-HqO18QiUOMtChsU9qN6mHgraMadDGVTeV1UIpvmKrmo079tkCnaCZ6I9VwfcXEwOyZRLOoazN7PqTTW8dlp9Ug==",
       "dependencies": {
         "@lark-base-open/base-site-channel": "0.1.6",
         "@radix-ui/react-popover": "1.2.0",
@@ -2210,7 +2210,7 @@
     "page": {
       "version": "0.0.0",
       "dependencies": {
-        "@lark-base-open/base-database-app-sdk": "0.1.0",
+        "@lark-base-open/base-database-app-sdk": "0.3.2",
         "@tanstack/react-query": "5.104.1",
         "react": "19.2.7",
         "react-dom": "19.2.7"
@@ -2227,7 +2227,7 @@
     "server": {
       "version": "0.0.0",
       "dependencies": {
-        "@lark-base-open/base-database-app-sdk": "0.1.0",
+        "@lark-base-open/base-database-app-sdk": "0.3.2",
         "zod": "4.6.5"
       },
       "devDependencies": {

package/templates/database-starter-v2/page/package.json

@@ -9,7 +9,7 @@
     "build": "tsc --noEmit && vite build"
   },
   "dependencies": {
-    "@lark-base-open/base-database-app-sdk": "0.1.0",
+    "@lark-base-open/base-database-app-sdk": "0.3.2",
     "react": "19.2.7",
     "react-dom": "19.2.7",
     "@tanstack/react-query": "5.104.1"

package/templates/database-starter-v2/server/package.json

@@ -7,7 +7,7 @@
     "check": "tsc --noEmit"
   },
   "dependencies": {
-    "@lark-base-open/base-database-app-sdk": "0.1.0",
+    "@lark-base-open/base-database-app-sdk": "0.3.2",
     "zod": "4.6.5"
   },
   "devDependencies": {

package/dist/contract-worker.d.ts

@@ -1,12 +0,0 @@
-import type { ContractEntry } from './contract-extractor.js';
-export interface ConvertedContract {
-    input?: Record<string, unknown>;
-    output?: Record<string, unknown>;
-    warnings: string[];
-}
-export { validateFullSchema } from './app-builder/schema.js';
-/** Only a validated Schema-only graph reaches this subprocess. This is not an arbitrary-code sandbox. */
-export declare function convertContract(entry: ContractEntry): Promise<ConvertedContract>;
-/** Read-only context uses the same isolated extraction without an async API. */
-export declare function convertContractSync(entry: ContractEntry): ConvertedContract;
-//# sourceMappingURL=contract-worker.d.ts.map

package/dist/contract-worker.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"contract-worker.d.ts","sourceRoot":"","sources":["../src/contract-worker.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AACD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,yGAAyG;AACzG,wBAAsB,eAAe,CACnC,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAE5B;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,iBAAiB,CAoF3E"}