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

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

@@ -7,42 +7,61 @@
 项目命令按 `--profile` → `larkProfile` → `LARKSUITE_CLI_PROFILE` → lark-cli 默认值选择。
 直接调用原生 `lark-cli base +...` 时也必须传入同一个 `--profile <name>`，不能改用默认账号。
 profile 决定账号与品牌，`--env` 决定运行环境。profile 缺失、未授权或与注入凭证冲突时停止，
-不创建新账号、不回退。宿主提供凭证且未选择 profile 时保持宿主上下文，不擅自添加本地 profile。
+不创建新账号、不回退。
 
 新建、恢复或修改工程前读取。只读设计与评审不执行本文件中的资源变更。
 
+## 环境与依赖
+
+CLI/存量 classic 使用 Node.js 20.19+；新建 workspace 与契约生成使用 Node.js 22+。init 在建 Base/应用前检查版本，不满足时返回 `INIT_NODE22_REQUIRED`，升级 Node.js 后再运行 init。
+
+`skill install` 安装用于搭建、修改和发布应用的开发者 Skill；外部 Agent 使用已发布业务功能时，按[站点 Skill 安装](agent-tools.md#安装到本地-agent)运行 `agent-tools skill install`。
+
+公开 CLI 只使用 `online` 环境；`init`、`pull` 等支持环境参数的命令显式传 `--env online`，`deploy` 不接受该参数。CLI、OpenAPI、Accounts、应用和 Page runtime 必须处于同一环境；原生资源操作始终使用 `--as user`。
+
+首次使用 `lark-cli` 时读取当前入口的 `--help`，本会话复用已确认的命令能力；不只按版本号判断。
+
+| 能力 | 使用方式与缺失时处理 |
+| --- | --- |
+| `lark-cli` 可执行文件 | 公开环境缺失时执行 `npx @larksuite/cli@latest install`，其他安装方式见 [github.com/larksuite/cli](https://github.com/larksuite/cli) |
+| `api`、本任务需要的 `base` 命令 | 业务所需能力；按当前帮助和协议执行，真实认证、权限或接口错误按失败阶段处理 |
+| `config` / `auth` | 本地账号管理能力，沿用当前任务选定的 profile；认证错误按[认证与重新授权](#认证与重新授权)处理 |
+| `skills read` | 可选的文档入口。存在时读取 `lark-base` 并沿路由找 reference；不存在时直接读取环境提供的 lark-base 文件与相应命令帮助，后续不反复尝试该入口 |
+| `doctor` | 排障入口，不是每次业务操作的必经步骤。真实认证、权限或接口错误按失败阶段处理 |
+
+自动选择失败时，仅使用当前环境已确认的可执行文件绝对路径设置 `BASE_DATABASE_LARK_CLI_PATH`；不全盘搜索、循环重装或替换宿主认证。只有发生真实认证、身份或 scope 错误时才读取 lark-shared 并恢复原身份，不主动重登或切换 bot。
+Windows 官方 npm 安装的 `lark-cli.cmd` 由 Base Database CLI 解析到同一安装目录下的原生 `lark-cli.exe`；手动指定路径时优先使用该 `.exe`。原生程序由官方安装脚本下载，不随 npm tarball 打包；若缺失，先在终端运行该安装入口的 `lark-cli --version` 完成初始化。该步骤只解决命令调用，不代表用户授权已完成。
+
+优先使用本机已安装的 `base-database-cli`。已知全局安装存在但 PATH 异常时，使用确认过的可执行路径；不自动修改 shell 配置。没有可用本地入口时，回退 `npx @lark-base-open/base-database-cli`；需要固定版本时使用 `npx @lark-base-open/base-database-cli@<已确认的精确版本>`。不猜 npm scope，不全盘搜索或反复安装。
+
+首次使用先确认 `lark-cli` 与 `base-database-cli` 可执行；缺失时按上述安装命令及回退入口处理。执行 `base-database-cli doctor`；认证缺失时按[认证与重新授权](#认证与重新授权)处理，用户完成授权后重新执行 doctor，`ok: true` 后再 init。`init`、`pull` 不会自动触发登录。
+
 ### 公开 CLI 版本预检
 
 本节的全局安装特指 `npm root -g` 对应的 CLI 包目录；不能仅凭 PATH 中存在同名命令就认定满足更新条件。
 
 仅本地公开 CLI：每个会话首次业务操作前，优先确认本机 `base-database-cli` 入口及其 `--help`。已有全局安装时用已核实的全局入口执行 `check-update --json --skill-dir "<当前读取的 lark-base-database 目录>"`；仅通过 npx 使用时沿用已选版本的完整包名入口。使用实际 Skill 加载路径，不猜测默认 Agent 目录。业务命令复用本次确认的入口。
 
-仅托管 Builder（设置了 `BASE_SITE_BUILDER_WORKSPACE_SOURCE` 或 `BASE_SITE_BUILDER_SITE_TOKEN`）及 CI 跳过更新检查；其他环境正常检查。检查失败不阻塞任务。
+CI 跳过更新检查；其他环境正常检查。检查失败不阻塞任务。业务命令输出含更新提示时，也按下述 `status=available` 流程询问用户；同一会话已拒绝时不重复询问。
 
-- `status=current|unavailable|skipped`：不向用户播报更新检查，继续任务。
+- `status=current|skipped`：不向用户播报更新检查，继续任务。
+- `status=unavailable`：静默继续任务，不为更新检查申请额外权限。
 - `status=available`：先确认上述全局入口可用；不可用时按下文说明更新限制并继续任务。可用时说明当前版本和可更新版本，以及会同步已安装的用户级 Lark Base Database Skill，再询问是否升级。拒绝后继续已安装版，本会话不再询问；不要自动执行 npm 或更新命令。
 - 确认全局安装入口且用户同意后，执行 `base-database-cli update --version <返回的 latest 精确版本> --skill-dir "<当前 Skill 目录>" --yes`，成功后重新读取该目录的 SKILL.md 和所需 references。升级会现场查找 Codex、Claude、通用 Agent 用户目录中已安装的本 Skill，并同步这些副本及显式传入的当前目录；不扫描项目或历史自定义目录，不补装已删除的副本。
 - `update` 只允许从全局安装的 CLI 执行，不从 npx 临时副本或项目副本执行，也不移除来源检查。全局命令的 PATH 异常时，通过 `npm root -g` 确认 `@lark-base-open/base-database-cli/dist/cli.js` 的实际位置，用 Node 执行该入口并核对版本。没有全局安装时说明更新限制，继续 npx 业务调用；只有用户明确要求全局安装时才进入安装流程，不将更新确认自动扩展为新建全局安装。
 - `skill.status=mismatch`：简短提示当前 Skill 与 CLI 来自不同版本，可通过本次执行预检的同一 CLI 入口运行 `skill install --dir "<当前 Skill 的父目录>" --force` 同步后重读；不因版本号不同中断业务或自动覆盖。`unknown` 表示未找到有效记录，不推断一致，也不阻塞。
 - 更新失败时按实际结果反馈。`skill-update-failed` 表示 CLI 已更新，但部分 Skill 未同步；说明 `installed` 中的成功目录和 `failed` 中的失败目录，按每项 `repair` 参数数组修复后重读，不宣称整体升级成功，不自动降级或反复重试。
 - 首次使用先确认当前调用入口支持 `check-update`（读取其 `--help`）；旧 CLI 没有该子命令时跳过预检，继续业务，不为预检自动升级。
-- 非托管环境优先使用本机已安装的 `base-database-cli`。已知全局安装存在但 PATH 异常时，使用确认过的可执行路径；不自动修改 shell 配置。没有可用本地入口时，回退 `npx @lark-base-open/base-database-cli`；需要固定版本时使用 `npx @lark-base-open/base-database-cli@<已确认的精确版本>`。不猜 npm scope，不全盘搜索或反复安装。托管环境始终使用宿主入口，不走公开包回退。
 
-## 环境与依赖
+## 认证与重新授权
 
-公开 CLI 只使用 `online` 环境；`init`、`pull` 等支持环境参数的命令显式传 `--env online`，`deploy` 不接受该参数。托管运行时使用宿主已安装的 `base-database-cli` 与唯一默认环境，不重新安装公开 CLI。CLI、OpenAPI、Accounts、应用和 Page runtime 必须处于同一环境；原生资源操作始终使用 `--as user`。
+沿用本任务已选定的 CLI 入口、环境和同一 profile。`not_configured`（原文 `not configured`）、`token_missing`（用户身份原文 `no access token available for user`，或 `need_user_authorization (user: …)`）来自 lark-cli；`need_user_authorization` 是后者的消息标记，`…` 代表实际用户标识。`missing_scopes` 由本 CLI 检查用户 scope 后返回，原文包含 `missing_scopes:` 和 `Run auth login with the same CLI, environment and profile to authorize these user scopes.`：说明缺少用户授权，执行 `base-database-cli auth login`，用户完成授权后只重试原命令一次；仍失败时停止并保留原错误，不循环授权。
 
-首次使用 `lark-cli` 时读取当前入口的 `--help`，本会话复用已确认的命令能力；不只按版本号判断，也不将云电脑等宿主认证环境等同于设置了 `BASE_SITE_BUILDER_*` 的 Builder。
+`app_scope_not_applied` 来自 lark-cli（原文 `access denied: app has not applied for the required scope(s)`，`app` 后可能附应用 ID），表示应用侧尚未申请所需 scope；不执行 auth login，报告应用权限未开通的阻塞并保留原错误，按错误提示处理。
 
-| 能力 | 使用方式与缺失时处理 |
-| --- | --- |
-| `lark-cli` 可执行文件 | 公开环境缺失时执行 `npx @larksuite/cli@latest install`，其他安装方式见 [github.com/larksuite/cli](https://github.com/larksuite/cli)；托管环境缺失时报告环境阻塞，不自行安装 |
-| `api`、本任务需要的 `base` 命令 | 业务所需能力；按当前帮助和协议执行，真实认证、权限或接口错误按失败阶段处理 |
-| `config` / `auth` | 本地账号管理能力。宿主提供认证时不补建 `default` profile；宿主缺少管理命令但通过 `LARKSUITE_CLI_PROFILE` 选择托管凭证时保留该环境变量，不传宿主禁止的 `--profile` 参数，由真实业务请求校验 profile，不回退账号 |
-| `skills read` | 可选的文档入口。存在时读取 `lark-base` 并沿路由找 reference；不存在时直接读取环境提供的 lark-base 文件与相应命令帮助，后续不反复尝试该入口 |
-| `doctor` | 排障入口，不是每次业务操作的必经步骤。先区分管理命令缺失与实际接口失败；旧版 CLI 因缺少管理命令无法继续时报告兼容性阻塞，不伪造配置、认证回执或修改已安装 CLI 来绕过 |
+非 doctor 命令可能只透出错误文字而没有 subtype；按上述原文特征判定，不因缺少码名就把应用权限未开通误判为用户未授权，无法匹配时保留原错误继续定位。
 
-自动选择失败时，仅使用当前环境已确认的可执行文件绝对路径设置 `BASE_DATABASE_LARK_CLI_PATH`；不全盘搜索、循环重装或替换宿主认证。只有发生真实认证、身份或 scope 错误时才读取 lark-shared 并恢复原身份，不主动重登或切换 bot。
+AI Function 管理命令或 deploy 返回 `800004011`（`ai function feature is not enabled`）不是 scope 问题，auth login 无效；按[未开通 AI Function](ai-function.md#未开通-ai-function-时)降级处理。其他错误按其原因处理。
 
 ## 先选择工程来源
 
@@ -54,18 +73,7 @@ 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_SITE_BUILDER_WORKSPACE_SOURCE`，按宿主决定执行，不根据空目录自行推断：
-
-| 来源       | 第一项工程操作                                                                                                                                                       | 约束                                                                              |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `snapshot` | 读取现有配置、Catalog、源码和本地修改                                                                                                                                | 不执行 init/pull                                                                  |
-| `artifact` | `base-database-cli pull . --app-token "$BASE_SITE_BUILDER_SITE_TOKEN"`                                                                                               | pull 失败停止恢复，不退回 init                                                    |
-| `binding`  | `base-database-cli init . --app-token "$BASE_SITE_BUILDER_SITE_TOKEN" --base-token "$BASE_SITE_BUILDER_BASE_TOKEN" --name '<应用名称>' --description '<应用描述>'` | 已有一个 Base 绑定但无可恢复源码；只初始化一次，复用现有应用与 Base，不新建资源 |
-| `empty`    | 执行带 `--app-token "$BASE_SITE_BUILDER_SITE_TOKEN"` 的 init                                                                                                         | 复用宿主应用，不创建另一应用                                                    |
-
-上述四种来源与宿主工程恢复协议一致。`binding` 还必须有非空 `BASE_SITE_BUILDER_BASE_TOKEN`，应用名称与描述从当前需求确定。宿主变量存在但取值不在表中、必需 token 缺失或工程与宿主状态矛盾时，报告恢复条件不满足，不创建新资源掩盖问题。会话历史未恢复但工程有效时，先读取现有工程继续；没有工程的合法 binding 模式仍执行表中的恢复路径。
-
-非托管环境：已有工程直接增量修改；只有远端应用时，在空目录执行 `base-database-cli pull . --app-token <app-token> --env online`；确认为新建时才 init。保留用户未提交内容，不能以恢复工程为由覆盖非空目录。
+已有工程直接增量修改；只有远端应用时，在空目录执行 `base-database-cli pull . --app-token <app-token> --env online`；确认为新建时才 init。保留用户未提交内容，不能以恢复工程为由覆盖非空目录。
 
 ## 需求与 Base 定位
 
@@ -79,8 +87,6 @@ base-database-cli context . --summary --json
 
 ## 初始化
 
-初始化前检查 `BASE_SITE_BUILDER_SITE_TOKEN`。变量非空表示宿主已经创建目标应用：使用 环境已安装的 `base-database-cli` 可执行文件，并在本节的 `init` 命令中追加 `--app-token "$BASE_SITE_BUILDER_SITE_TOKEN"`。该模式仍按需求创建或复用 Base，会更新已有应用的名称和描述，再调用 `bind_base` 和 `catalog`，不会调用应用 create。不要手写 `base-database.jsonc`、不要绕过 CLI 拼装低层 `lark-cli` 请求，也不要用新应用掩盖绑定失败。
-
 ### 从零创建 Base
 
 编写 schema 前，按已确认的文档入口读取字段规范：支持 `skills read` 时先执行 `lark-cli skills read lark-base` 查看文件列表，再读取其中的字段定义 reference（当前为 `references/lark-base-field-json.md`，以列表实际名称为准）；否则直接读取环境中 lark-base 的对应 reference，并用 `lark-cli base +table-create --help` 核对当前命令契约，不再尝试已知缺失的入口。不要猜测属性。`tables[].fields` 使用与 `lark-cli base +base-create/+table-create --fields` 相同的字段定义；init 会先创建每张表的主字段，取得全部真实表 ID 后再按原顺序创建其余字段。
@@ -133,16 +139,6 @@ base-database-cli init . \
   --schema ./base-schema.json
 ```
 
-托管环境 已有应用场景执行：
-
-```bash
-base-database-cli init . \
-  --name 'Todo 管理' \
-  --description '供个人集中创建、跟踪和完成日常任务' \
-  --schema ./base-schema.json \
-  --app-token "$BASE_SITE_BUILDER_SITE_TOKEN"
-```
-
 ### 使用已有 Base
 
 取得已有 Base 的 `bas...` token 后执行：
@@ -155,11 +151,9 @@ base-database-cli init . \
   --base-token basxxxxxxxx
 ```
 
-托管环境 复用已有 Base 与已有应用时，同样改用 `base-database-cli init` 并追加 `--app-token "$BASE_SITE_BUILDER_SITE_TOKEN"`。
-
 该命令调用只读 Base 接口获取 Base 信息并分页列出全部表。未指定 `--app-token` 时，通过应用创建接口的 `baseBindings` 绑定这些表；指定时，通过目标应用的 `bind_base` 绑定这些表。最后从目标应用获取 Catalog。它不会创建或修改 Base、表、字段和记录。
 
-两种路径必须且只能传入 `--schema` 或 `--base-token` 之一，并始终传入非空 `--description`。公开 CLI 的 `--env` 默认且只支持 `online`；托管环境 使用已配置的默认环境。建表顺序与等待由 CLI 管理。
+两种路径必须且只能传入 `--schema` 或 `--base-token` 之一，并始终传入非空 `--description`。公开 CLI 的 `--env` 默认且只支持 `online`。建表顺序与等待由 CLI 管理。
 
 成功结果的 `baseSource` 和 `databaseSource` 分别为 `created` 或 `existing`；新建资源位于 `created`，复用资源位于 `reused`，同时列出表、应用、binding 和工程文件。开始开发前确认以下产物：
 
@@ -170,11 +164,13 @@ catalog.json         # 已绑定数据表的真实 schema
 page/                # React 页面
 database-functions/                 # Database Functions
 mutations/           # 基础写入声明
-server-functions/    # 服务端 FaaS Functions
+server/              # workspace 服务端 FaaS Functions
+package.json         # page + server npm workspaces
+package-lock.json    # 唯一根依赖锁
 .base-database-cli/      # 被 Git 忽略的 CLI 本地状态与临时制品
 ```
 
-旧工程中的 `sql/` 可继续执行 `check` 和 `deploy`，但不要与 `database-functions/` 同时存在。`pull` 恢复旧制品时会把 `sql/` 迁移为 `database-functions/`；新增和修改 Function 使用新目录。
+新建仅支持 workspace（`init`）；classic 的 `server-functions/` 和独立 page/server-functions 依赖锁仅供存量兼容。
 
 只从 `catalog.json` 读取表名、字段名、ID、选项和查询类型，不根据建表输入猜测 Catalog 结果。
 
@@ -208,3 +204,18 @@ base-database-cli lark-cli -- api GET /open-apis/base/v3/sites/<app-token>/catal
 普通 `api` 请求（默认 JSON、`--json` 或 `--format json`）会将宿主自动落盘的 JSON 响应恢复为 stdout JSON，并清理本次临时文件，上传请求同样适用。真实文件下载显式使用 `--output`；该模式以及 `--jq`、`--page-all`、非 JSON 格式、标准输入请求、帮助和 dry-run 保留宿主原始行为。
 
 初始化成功后进入[开发阶段路由](../SKILL.md#开发阶段路由)，实现完成后按[发布与交付](release.md)处理。
+
+升级 CLI 后若 check 报缺声明，按报错列出的全部函数、字段与补写示例一次补全，再 check/deploy；交付告知见[交付结果](release.md#交付结果)。
+
+## 工程目录与构建模式
+
+新建工程只有 workspace；恢复工程先读 base-database.jsonc，不凭安装了 Page SDK 判断布局。
+
+| 内容 | workspace（template.version 2） | 存量 classic（version 1 或合法旧配置省略 template） |
+| --- | --- | --- |
+| 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/ |
+| 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/README.md

@@ -1,5 +1,7 @@
 # {{Site name}}
 
+> classic 存量工程参考。新建请使用 `base-database-cli init`；classic 继续支持 check、deploy、pull、dev。
+
 > {{One sentence describing who this site helps and what they can do}}
 
 <!-- Template note: Write this README in the language of the user's original site-building request when it is Chinese, Japanese, or English; otherwise use English. Translate the headings and prose using the supported section names in the lark-base-database Skill. Replace every {{...}} placeholder before publishing. Remove this comment and any lines that do not apply. Describe only features that were implemented and verified. -->

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

@@ -3,6 +3,6 @@
 Place each Database Function in `database-functions/<functionId>/`:
 
 - `main.sql`: Write a query using the supported Database Function syntax. Refer to parameters as `$1`, `$2`, and so on.
-- `meta.json`: Declare `name`, `description`, and the parameter contract. Omit `meta` or `meta.params` when the query has no parameters.
+- `meta.json`: Declare `name`, `description`, and `meta.params` in `$1`, `$2` order. Each parameter needs `name`, `kind` and `description`, plus an optional `enum` for fixed options. Page calls use `{parameterName: value}`, matching the frozen declaration. Omit `meta` or `meta.params` when the query has no parameters.
 
-Database Functions read Base data. Use `server-functions/functions/` for writes. See the `lark-base-database` Skill's `database-function.md` for parameter, response, Catalog, and SQL dialect contracts.
+Database Functions read Base data. Use `mutations/` for fixed single-table writes and `server-functions/functions/` for business validation or orchestration; see the Skill reference `mutations.md#写入方式选择`. See the `lark-base-database` Skill's `database-function.md` for parameter, response, Catalog, and SQL dialect contracts.

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

@@ -11,9 +11,9 @@
 `spec.json` 示例（替换真实 table / field ID）：
 
 ```json
-{"table":{"table_id":"tblTasks"},"operation":"update","params":[{"kind":"RECORD_ID"},{"kind":"TEXT","max_length":100}],"precondition":{"conjunction":"and","conditions":[{"field_id":"rec_id","operator":"is","param":1}]},"set":{"fldTitle":{"param":2}},"returning":["rec_id","fldTitle"]}
+{"table":{"table_id":"tblTasks"},"operation":"update","params":[{"name":"taskId","kind":"RECORD_ID","description":"要改名的任务记录 ID；先调用任务列表函数取 record_id"},{"name":"title","kind":"TEXT","max_length":100,"description":"新的任务标题，最多 100 字"}],"precondition":{"conjunction":"and","conditions":[{"field_id":"rec_id","operator":"is","param":1}]},"set":{"fldTitle":{"param":2}},"returning":["rec_id","fldTitle"]}
 ```
 
-单条调用 `invokeDatabaseFunction('updateTitle', ['recA', '新标题'])`；批量调用 `invokeDatabaseMutationBatch('updateTitle', [['recA', '标题 A'], ['recB', '标题 B']])`。编号从 1 开始；一批最多 200 条。CLI deploy 自动校验、打包并更新 Function，pull 保留声明。
+单条调用 `invokeDatabaseFunction('updateTitle', { taskId: 'recA', title: '新标题' })`；批量调用 `invokeDatabaseMutationBatch('updateTitle', [{ taskId: 'recA', title: '标题 A' }, { taskId: 'recB', title: '标题 B' }])`。编号从 1 开始；一批最多 200 条。`spec.params` 每项必须写 `name` 和 `description`，固定选项可写 `enum`；外部 Agent 按 `name` 传对象。CLI deploy 自动校验、打包并更新 Function，pull 保留声明。
 
 Mutation 负责基础单表写入；create 不带 precondition，其他操作通过 precondition 指定记录 ID。需要服务端业务校验、计算或编排时使用 FaaS。字段、附件、权限边界和完整协议见已安装的 lark-base-database Skill 的 `references/mutations.md`。

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

@@ -17,18 +17,19 @@ Optional AI Function example components use the same language selection for thei
 The application runs in a BaseApp iframe. It does not hold login credentials or call business domains directly. `src/lib/database-runtime.ts` is the single entry point for communication with the host, using `@lark-base-open/base-site-channel/runtime`:
 
 - `fetch` / `invokeHttp`: The parent page proxies business HTTP requests from its own origin. Business paths must start with a single `/`.
-- `invokeDatabaseFunction(functionId, params)`: Calls `POST /space/api/bitable/site/v1/:token/invoke_function/:function_id` through the unified gateway with a `{"params": ...}` body.
+- This bundled classic reference helper uses named inputs. Classic projects reusing it must explicitly set `"functionInputs": "named"` in `base-database.jsonc`; omission keeps the positional default. The input declaration rules are maintained in the installed building Skill’s `references/workspace-migration.md#classic-输入声明`.
+- `invokeDatabaseFunction(functionId, params)`: Calls `POST /space/api/bitable/site/v1/:token/functions/:function_id/invoke` through the unified gateway with a `{"params": {...}}` body. SQL and Mutation use named objects (zero parameters: `{}`); batches use `{"batch":[{"params":{...}}]}`.
 - `src/lib/database-function-inputs.generated.ts`: The CLI generates Page input types from Database Function and FaaS metadata during `check` and Preview `deploy`. Do not edit this file. Page compilation checks Function IDs, query parameter order, and required FaaS fields and enum values. Callers still declare response types and validate them at runtime.
 - `resolveDatabaseContext()`: Resolves the app token and `prod` or `preview` environment. Host-provided context takes precedence; otherwise it infers values from the artifact path through `getDatabaseContext()`. Use this asynchronous function in business code.
 - `getDatabaseContext()`: Synchronous artifact-path inference for fallback use only.
-- `callSiteAIFunction({ functionKey, capability, variables?, messages?, input? })`: Calls the configured AI Function and returns a discriminated result with `type: 'text' | 'image_task' | 'video_task'`. Poll media tasks by task ID and render by `result.type`.
-- `invokeSiteAIFunctionStream({ functionKey, messages, variables? })`: Streams text or image understanding results. It provides subscribable updates and a `destroy()` method. Consume both `delta.reasoningContent` and `delta.content` and render them separately. See `src/examples/ai-function/TextStreamOperation.tsx`.
+- `callSiteAIFunction({ functionKey, capability, params?, messages?, input? })`: Calls the configured AI Function and returns a discriminated result with `type: 'text' | 'image_task' | 'video_task'`. Poll media tasks by task ID and render by `result.type`.
+- `invokeSiteAIFunctionStream({ functionKey, messages, params? })`: Streams text or image understanding results. It provides subscribable updates and a `destroy()` method. Consume both `delta.reasoningContent` and `delta.content` and render them separately. See `src/examples/ai-function/TextStreamOperation.tsx`.
 - `createSiteAIFunctionTask(params)` / `getSiteAIFunctionTask(functionKey, taskId)`: Submit and poll image or video generation tasks.
 - `siteRuntime`: Reports lifecycle events through `ready()` and `reportLoadFailed()`.
 
 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 `variables` 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. 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`.
 
 ## Request identity and CSRF
 

package/templates/database-starter/page/src/examples/ai-function/TextStreamOperation.tsx

@@ -21,8 +21,8 @@ import { splitAIStreamDelta } from './ai-delta'
 export interface TextStreamOperationProps {
   // functionKey 指向后台配置好的 text/vision AI Function。
   functionKey: string
-  // variables 渲染 AI Function System Prompt 里的 {{var}} 占位符（可选）。
-  variables?: Record<string, unknown>
+  // params 渲染 AI Function System Prompt 里的 {{var}} 占位符（可选）。
+  params?: Record<string, unknown>
   title?: string
 }
 
@@ -50,7 +50,7 @@ export function parseAnswerItems(answer: string): string[] {
 
 function useTextStream(
   functionKey: string,
-  variables: Record<string, unknown> | undefined,
+  params: Record<string, unknown> | undefined,
   unavailableMessage: string,
 ) {
   const streamRef = useRef<SiteAIFunctionStreamHandle | null>(null)
@@ -79,7 +79,7 @@ function useTextStream(
     const stream = invokeSiteAIFunctionStream({
       functionKey,
       messages,
-      ...(variables ? { variables } : {}),
+      ...(params ? { params } : {}),
     })
     stream.onMessage((delta) => {
       const { answer, reasoning } = splitAIStreamDelta(delta)
@@ -110,13 +110,13 @@ function useTextStream(
 /** 文本流式业务操作示例组件。 */
 export function TextStreamOperation({
   functionKey,
-  variables,
+  params,
   title,
 }: TextStreamOperationProps) {
   const i18n = AI_FUNCTION_COPY[useUiLanguage()].text
   const { ask, state, stop } = useTextStream(
     functionKey,
-    variables,
+    params,
     i18n.unavailable,
   )
   const [draft, setDraft] = useState('')

package/templates/database-starter/page/src/lib/attachment-image.tsx

@@ -57,12 +57,14 @@ export function AttachmentImage({
     error: string
     localError?: 'loadFailed' | 'decodeFailed'
   }>({ key: '', url: '', error: '' })
-  const { tableId, fieldId, recordId, fileToken } = attachment
+  const { tableId, fieldId, recordId, fileToken, name, mimeType } = attachment
   const key = JSON.stringify([
     tableId,
     fieldId,
     recordId,
     fileToken,
+    name,
+    mimeType,
     size,
     attempt,
   ])
@@ -89,9 +91,11 @@ export function AttachmentImage({
     if (!visible) return
     const controller = new AbortController()
     let url = ''
-    fetchAttachmentCover({ tableId, fieldId, recordId, fileToken }, size, {
-      signal: controller.signal,
-    })
+    fetchAttachmentCover(
+      { tableId, fieldId, recordId, fileToken, name, mimeType },
+      size,
+      { signal: controller.signal },
+    )
       .then((blob) => {
         if (controller.signal.aborted) return
         url = URL.createObjectURL(blob)
@@ -111,7 +115,17 @@ export function AttachmentImage({
       controller.abort()
       if (url) URL.revokeObjectURL(url)
     }
-  }, [visible, key, tableId, fieldId, recordId, fileToken, size])
+  }, [
+    visible,
+    key,
+    tableId,
+    fieldId,
+    recordId,
+    fileToken,
+    name,
+    mimeType,
+    size,
+  ])
 
   const current = image.key === key ? image : undefined
   return (

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

@@ -3,10 +3,12 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 const getRuntimeContext = vi.fn()
 const siteRuntimeFetch = vi.fn()
 const invokeHttp = vi.fn()
+const openLink = vi.fn()
 
 vi.mock('@lark-base-open/base-site-channel/runtime', () => ({
   fetch: siteRuntimeFetch,
   invokeHttp,
+  openLink,
   siteRuntime: { getRuntimeContext },
 }))
 
@@ -27,6 +29,7 @@ beforeEach(() => {
   getRuntimeContext.mockReset()
   siteRuntimeFetch.mockReset()
   invokeHttp.mockReset()
+  openLink.mockReset()
   vi.stubGlobal('location', {
     ancestorOrigins: ['https://ancestor.example'],
     pathname: '/app/pathToken/',
@@ -50,9 +53,11 @@ describe('fetchAttachmentCover', () => {
     )
     const controller = new AbortController()
     const { fetchAttachmentCover } = await loadDatabaseRuntime()
-    const blob = await fetchAttachmentCover(attachmentRef, 480, {
-      signal: controller.signal,
-    })
+    const blob = await fetchAttachmentCover(
+      { ...attachmentRef, name: 'historical.svg', mimeType: 'image/svg+xml' },
+      480,
+      { signal: controller.signal },
+    )
     expect(new Uint8Array(await blob.arrayBuffer())).toEqual(
       new Uint8Array([0, 128, 255]),
     )
@@ -87,12 +92,77 @@ describe('fetchAttachmentCover', () => {
         }),
       )
       const { fetchAttachmentCover } = await loadDatabaseRuntime()
-      await expect(fetchAttachmentCover(attachmentRef)).rejects.toThrow(
-        `HTTP ${status}, LogID test-log`,
+      await expect(
+        fetchAttachmentCover({ ...attachmentRef, name: 'drawing.svg' }),
+      ).rejects.toThrow(`HTTP ${status}, LogID test-log`)
+      expect(invokeHttp).toHaveBeenCalledTimes(1)
+    },
+  )
+  it.each([
+    { code: 90002006, name: 'drawing.svg', expectedCode: '90002005' },
+    { code: '90002006', name: 'DRAWING.SVG', expectedCode: '90002005' },
+    {
+      code: 90002006,
+      mimeType: 'IMAGE/SVG+XML; charset=utf-8',
+      expectedCode: '90002005',
+    },
+  ])(
+    'classifies a cover error using only available file metadata: %j',
+    async ({ code, name, mimeType, expectedCode }) => {
+      const body = { code, message: 'Cover service error', data: null }
+      invokeHttp.mockResolvedValue(
+        new Response(JSON.stringify(body), {
+          status: 202,
+          headers: {
+            'content-type': 'application/json',
+            'x-tt-logid': 'cover-log',
+          },
+        }),
       )
+      const { fetchAttachmentCover } = await loadDatabaseRuntime()
+      await expect(
+        fetchAttachmentCover({ ...attachmentRef, name, mimeType }),
+      ).rejects.toMatchObject({
+        code: expectedCode,
+        originalCode: String(code),
+        cause: body,
+        logId: 'cover-log',
+        message: expect.stringContaining(
+          `code ${expectedCode}, LogID cover-log`,
+        ),
+      })
       expect(invokeHttp).toHaveBeenCalledTimes(1)
     },
   )
+  it('preserves business errors from unsuccessful HTTP responses', async () => {
+    const body = { code: 800008201, message: 'Forbidden', data: null }
+    invokeHttp.mockResolvedValue(
+      new Response(JSON.stringify(body), {
+        status: 403,
+        headers: { 'content-type': 'application/json' },
+      }),
+    )
+    const { fetchAttachmentCover } = await loadDatabaseRuntime()
+    await expect(
+      fetchAttachmentCover({ ...attachmentRef, name: 'drawing.svg' }),
+    ).rejects.toThrow('HTTP 403')
+  })
+  it.each([
+    { name: 'animation.gif', code: 90002006 },
+    { name: undefined, code: 90002006 },
+    { name: 'drawing.svg', code: 90002005 },
+  ])('keeps other cover failures unchanged: %j', async ({ name, code }) => {
+    invokeHttp.mockResolvedValue(
+      new Response(JSON.stringify({ code, message: 'Cover service error' }), {
+        status: 202,
+        headers: { 'content-type': 'application/json' },
+      }),
+    )
+    const { fetchAttachmentCover } = await loadDatabaseRuntime()
+    await expect(
+      fetchAttachmentCover({ ...attachmentRef, name }),
+    ).rejects.toThrow('The host did not return a valid image')
+  })
   it('rejects non-image and empty responses', async () => {
     const { fetchAttachmentCover } = await loadDatabaseRuntime()
     for (const response of [
@@ -273,3 +343,52 @@ describe('fetchAttachmentDownloadUrl', () => {
     })
   })
 })
+
+describe('openAttachmentDownload', () => {
+  const context = {
+    env: 'prod',
+    gatewayOrigin: '',
+    token: 'siteToken',
+  } as const
+  const signedUrl = 'https://download.example/authcode/?code=signed'
+
+  it('opens a fresh signed URL through the host instead of navigating the iframe', async () => {
+    siteRuntimeFetch.mockResolvedValue(
+      new Response(JSON.stringify({ code: 0, data: { url: signedUrl } })),
+    )
+    openLink.mockResolvedValue({ opened: true })
+    const { openAttachmentDownload } = await loadDatabaseRuntime()
+
+    await expect(
+      openAttachmentDownload(context, attachmentRef),
+    ).resolves.toBeUndefined()
+    expect(siteRuntimeFetch).toHaveBeenCalledTimes(1)
+    expect(openLink).toHaveBeenCalledOnce()
+    expect(openLink).toHaveBeenCalledWith(signedUrl)
+  })
+
+  it('does not report success when the host refuses to open the link', async () => {
+    siteRuntimeFetch.mockResolvedValue(
+      new Response(JSON.stringify({ code: 0, data: { url: signedUrl } })),
+    )
+    openLink.mockResolvedValue({ opened: false })
+    const { openAttachmentDownload } = await loadDatabaseRuntime()
+
+    await expect(
+      openAttachmentDownload(context, attachmentRef),
+    ).rejects.toThrow('The host did not open the attachment download link')
+    expect(openLink).toHaveBeenCalledWith(signedUrl)
+  })
+
+  it('does not open a link when the attachment service fails', async () => {
+    siteRuntimeFetch.mockResolvedValue(
+      new Response(JSON.stringify({ code: 800008201 }), { status: 403 }),
+    )
+    const { openAttachmentDownload } = await loadDatabaseRuntime()
+
+    await expect(
+      openAttachmentDownload(context, attachmentRef),
+    ).rejects.toThrow('Attachment service could not provide a download URL')
+    expect(openLink).not.toHaveBeenCalled()
+  })
+})

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

@@ -75,7 +75,7 @@ describe('buildDatabaseInvokeFunctionPath', () => {
         { env: 'prod', gatewayOrigin: '', token: 'bascnDemo' },
         'list_tasks',
       ),
-    ).toBe('/space/api/bitable/site/v1/bascnDemo/invoke_function/list_tasks')
+    ).toBe('/space/api/bitable/site/v1/bascnDemo/functions/list_tasks/invoke')
   })
 
   it('adds the preview env query for draft artifacts', () => {
@@ -85,7 +85,7 @@ describe('buildDatabaseInvokeFunctionPath', () => {
         'list-tasks',
       ),
     ).toBe(
-      '/space/api/bitable/site/v1/bascnDemo/invoke_function/list-tasks?env=preview',
+      '/space/api/bitable/site/v1/bascnDemo/functions/list-tasks/invoke?env=preview',
     )
   })