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

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

@@ -11,26 +11,60 @@ profile 决定账号与品牌，`--env` 决定运行环境。profile 缺失、
 
 新建、恢复或修改工程前读取。只读设计与评审不执行本文件中的资源变更。
 
+### 公开 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 跳过更新检查；其他环境正常检查。检查失败不阻塞任务。
+
+- `status=current|unavailable|skipped`：不向用户播报更新检查，继续任务。
+- `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 的 `--help` 和 `doctor`，不猜测参数、不循环重装。原生 Base 的复杂操作优先使用当前二进制内置文档：`lark-cli skills read lark-base`，再按其路由读取 reference；旧版本没有 `skills read` 时使用环境提供的 lark-base 与命令帮助。只有发生认证、身份或 scope 错误时才读取 lark-shared 并恢复原身份，不主动重登或切换 bot。
+首次使用 `lark-cli` 时读取当前入口的 `--help`，本会话复用已确认的命令能力；不只按版本号判断，也不将云电脑等宿主认证环境等同于设置了 `BASE_SITE_BUILDER_*` 的 Builder。
+
+| 能力 | 使用方式与缺失时处理 |
+| --- | --- |
+| `api`、本任务需要的 `base` 命令 | 业务所需能力；按当前帮助和协议执行，真实认证、权限或接口错误按失败阶段处理 |
+| `config` / `auth` | 本地账号管理能力。宿主提供认证时不补建 `default` profile；宿主缺少管理命令但通过 `LARKSUITE_CLI_PROFILE` 选择托管凭证时保留该环境变量，不传宿主禁止的 `--profile` 参数，由真实业务请求校验 profile，不回退账号 |
+| `skills read` | 可选的文档入口。存在时读取 `lark-base` 并沿路由找 reference；不存在时直接读取环境提供的 lark-base 文件与相应命令帮助，后续不反复尝试该入口 |
+| `doctor` | 排障入口，不是每次业务操作的必经步骤。先区分管理命令缺失与实际接口失败；旧版 CLI 因缺少管理命令无法继续时报告兼容性阻塞，不伪造配置、认证回执或修改已安装 CLI 来绕过 |
+
+自动选择失败时，仅使用当前环境已确认的可执行文件绝对路径设置 `BASE_DATABASE_LARK_CLI_PATH`；不全盘搜索、循环重装或替换宿主认证。只有发生真实认证、身份或 scope 错误时才读取 lark-shared 并恢复原身份，不主动重登或切换 bot。
 
 ## 先选择工程来源
 
+需要确认当前本地工程状态时，先执行一次只读快照：
+
+```bash
+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 | 复用宿主 应用，不创建另一 应用 |
+| 来源       | 第一项工程操作                                                                                                                                                       | 约束                                                                              |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `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 模式仍执行表中的恢复路径。
 
-非托管环境：已有工程直接增量修改；只有远端 应用 时，在空目录执行 `npx @lark-base-open/base-database-cli pull . --app-token <app-token> --env online`；确认为新建时才 init。保留用户未提交内容，不能以恢复工程为由覆盖非空目录。
+非托管环境：已有工程直接增量修改；只有远端 应用 时，在空目录执行 `base-database-cli pull . --app-token <app-token> --env online`；确认为新建时才 init。保留用户未提交内容，不能以恢复工程为由覆盖非空目录。
 
 ## 需求与 Base 定位
 
@@ -44,17 +78,17 @@ profile 决定账号与品牌，`--env` 决定运行环境。profile 缺失、
 
 ## 初始化
 
-初始化前检查 `BASE_SITE_BUILDER_SITE_TOKEN`。变量非空表示宿主已经创建目标 应用：使用 Sandbox 已安装的 `base-database-cli` 可执行文件，并在本节的 `init` 命令中追加 `--app-token "$BASE_SITE_BUILDER_SITE_TOKEN"`。该模式仍按需求创建或复用 Base，会更新已有 应用 的名称和描述，再调用 `bind_base` 和 `catalog`，不会调用 应用 create。不要手写 `base-database.jsonc`、不要绕过 CLI 拼装低层 `lark-cli` 请求，也不要用新 应用 掩盖绑定失败。
+初始化前检查 `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 前，先读取当前 lark-cli 的字段规范：`lark-cli skills read lark-base references/lark-base-field-schema.md`。该入口不存在时通过 `lark-cli base +table-create --help` 和 lark-base 路由查找当前版本对应规范；不要猜测属性。`tables[].fields` 与 `lark-cli base +base-create/+table-create --fields` 的字段数组同构，init 原样传递这些定义。
+编写 schema 前，按已确认的文档入口读取字段规范：支持 `skills read` 时执行 `lark-cli skills read lark-base references/lark-base-field-schema.md`；否则直接读取环境中 lark-base 的对应 reference，并用 `lark-cli base +table-create --help` 核对当前命令契约，不再尝试已知缺失的入口。不要猜测属性。`tables[].fields` 使用与 `lark-cli base +base-create/+table-create --fields` 相同的字段定义；init 会先创建每张表的主字段，取得全部真实表 ID 后再按原顺序创建其余字段。
 
 - 首个字段成为表的主字段，优先采用可读的文本标识；其他类型先核对主字段限制。
 - 单选和多选都用 `select`，多选显式设置 `"multiple": true`，选项按字段规范声明。
-- `link` 字段必须提供 `link_table`，引用真实目标表；按目标表依赖安排建表顺序。
+- `link` 字段必须提供 `link_table`，且名称与本次 Schema 中的目标表完全一致；自关联和跨表关联会在所有表创建后补建，不需要按关联依赖调整表顺序。
 - `datetime.style.format` 使用当前 Base 支持的固定枚举，不能自行增加秒级展示格式；底层时间精度与展示格式分别处理。
-- 创建字段的 schema、SQL 类型与记录 CellValue 是不同协议，不互相替代。
+- 创建字段的 schema、查询类型与记录 CellValue 是不同协议，不互相替代。
 
 把全部表写入一个 schema 文件。这个文件是 `init` 的输入，不是平台请求缓存：
 
@@ -90,14 +124,14 @@ profile 决定账号与品牌，`--env` 决定运行环境。profile 缺失、
 在项目目录执行初始化命令：
 
 ```bash
-npx @lark-base-open/base-database-cli init . \
+base-database-cli init . \
   --env online \
   --name 'Todo 管理' \
   --description '供个人集中创建、跟踪和完成日常任务' \
   --schema ./base-schema.json
 ```
 
-托管 Sandbox 已有 应用 场景执行：
+托管环境 已有 应用 场景执行：
 
 ```bash
 base-database-cli init . \
@@ -112,18 +146,18 @@ base-database-cli init . \
 取得已有 Base 的 `bas...` token 后执行：
 
 ```bash
-npx @lark-base-open/base-database-cli init . \
+base-database-cli init . \
   --env online \
   --name 'Todo 管理' \
   --description '供个人集中创建、跟踪和完成日常任务' \
   --base-token basxxxxxxxx
 ```
 
-托管 Sandbox 复用已有 Base 与已有 应用 时，同样改用 `base-database-cli init` 并追加 `--app-token "$BASE_SITE_BUILDER_SITE_TOKEN"`。
+托管环境 复用已有 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`；托管 Sandbox 使用内部运行时的默认环境。建表顺序与等待由 CLI 管理。
+两种路径必须且只能传入 `--schema` 或 `--base-token` 之一，并始终传入非空 `--description`。公开 CLI 的 `--env` 默认且只支持 `online`；托管环境 使用已配置的默认环境。建表顺序与等待由 CLI 管理。
 
 成功结果的 `baseSource` 和 `databaseSource` 分别为 `created` 或 `existing`；新建资源位于 `created`，复用资源位于 `reused`，同时列出表、应用、binding 和工程文件。开始开发前确认以下产物：
 
@@ -132,12 +166,25 @@ base-database.jsonc      # 应用 appToken 与 Base binding
 base-schema.json     # 仅从零路径存在，是本次建库输入
 catalog.json         # 已绑定数据表的真实 schema
 page/                # React 页面
-sql/                 # SQL Functions
+database-functions/                 # Database Functions
+mutations/           # 基础写入声明
 server-functions/    # 服务端 FaaS Functions
 .base-database-cli/      # 被 Git 忽略的 CLI 本地状态与临时制品
 ```
 
-只从 `catalog.json` 读取表名、字段名、ID、选项和 SQL 类型，不根据建表输入猜测 Catalog 结果。
+旧工程中的 `sql/` 可继续执行 `check` 和 `deploy`，但不要与 `database-functions/` 同时存在。`pull` 恢复旧制品时会把 `sql/` 迁移为 `database-functions/`；新增和修改 Function 使用新目录。
+
+只从 `catalog.json` 读取表名、字段名、ID、选项和查询类型，不根据建表输入猜测 Catalog 结果。
+
+### 初始化失败与阶段回执
+
+`--schema` 路径会在首个远端创建前校验整份 schema；按返回的字段路径修正。本地预检通过不代表权限、配额或服务端语义检查通过。
+
+首次写入前，CLI 创建 `.base-database-cli/state/init.json`，持续记录已确认的资源 ID 和步骤结果。初始化失败或中断时保留该回执；`partial` 表示部分写入已成功，`unknown` 或残留的 `running` 表示结果尚未确认。
+
+字段创建仅在完整逐项结果明确标记失败项 `retryable=true` 时自动做有限退避，并且只重发该失败字段；已创建项不会重发，后续 `not_attempted` 项在失败字段成功后继续。不要在外层再次自动重跑 `init`；限次耗尽、`retryable=false` 或结果未知时按回执状态处理。
+
+普通 `init` 发现已有回执时会停止。回执中没有 `unknown` 或写入中的 `running` 时，可用原命令和原参数追加 `--resume`；CLI 先核对环境、profile、计划摘要及真实资源 ID，再跳过已确认步骤并补齐尚未开始或有完整逐项结果的字段。任一参数变化、资源漂移、未知写入或不完整字段结果都会在恢复写入前停止。恢复不按名称认领资源、不自动删除或整体回滚；需要放弃原计划时保留原回执，在新的空目录按已确认的 Base/应用重新初始化。
 
 ## 增量修改与追加绑定
 
@@ -146,14 +193,16 @@ server-functions/    # 服务端 FaaS Functions
 需要绑定同一 Base 中的新表时，不重新执行 init 或 pull。先从 `lark-cli base +table-list/get` 的真实结果取得 ID，再在项目根目录执行：
 
 ```bash
-npx @lark-base-open/base-database-cli lark-cli -- api POST /open-apis/base/v3/sites/<app-token>/bind_base --data '{"baseToken":"<base-token>","tableIds":["<table-id>"]}' --json
-npx @lark-base-open/base-database-cli lark-cli -- api GET /open-apis/base/v3/sites/<app-token>/catalog --json
+base-database-cli lark-cli -- api POST /open-apis/base/v3/sites/<app-token>/bind_base --data '{"baseToken":"<base-token>","tableIds":["<table-id>"]}' --json
+base-database-cli lark-cli -- api GET /open-apis/base/v3/sites/<app-token>/catalog --json
 ```
 
 `bind_base` 只向同一 Base 追加并去重 Table ID，不覆盖原绑定。将 Catalog 返回 envelope 的 `data` 对象写入 `catalog.json`；在 `base-database.jsonc` 保留原 binding 并合并新 `tableIds`。删除本地 ID 不会触发远程解绑；真实解绑遵守[外部操作与授权](../SKILL.md#外部操作与授权)。
 
 ## 开发期调用边界
 
-项目级 `npx @lark-base-open/base-database-cli lark-cli -- ...` 用于追加 binding、应用 控制面诊断，以及新建 Base 的示例数据写入和 SQL 验证；需在含 `base-database.jsonc` 的目录执行。其他原生 Base 发现和配置直接使用 `lark-cli base +...`。这些 CLI 操作不进入 Page/FaaS 运行时代码。
+项目级 `base-database-cli lark-cli -- ...` 用于追加 binding、应用 控制面诊断，以及新建 Base 的示例数据写入和 Database Function 回读验证；需在含 `base-database.jsonc` 的目录执行。其他原生 Base 发现和配置直接使用 `lark-cli base +...`。这些 CLI 操作不进入 Page/FaaS 运行时代码。
+
+普通 `api` 请求（默认 JSON、`--json` 或 `--format json`）会将宿主自动落盘的 JSON 响应恢复为 stdout JSON，并清理本次临时文件，上传请求同样适用。真实文件下载显式使用 `--output`；该模式以及 `--jq`、`--page-all`、非 JSON 格式、标准输入请求、帮助和 dry-run 保留宿主原始行为。
 
 初始化成功后进入[开发阶段路由](../SKILL.md#开发阶段路由)，实现完成后按[发布与交付](release.md)处理。

package/templates/database-starter/README.md

@@ -1,11 +1,41 @@
-# 数据库应用工程
+# {{Site name}}
 
-本目录包含 Page、SQL Function 和服务端 FaaS Function 源码。服务端函数的源码与构建工作区是 `server-functions/`。业务与运行时契约以已安装的 `lark-base-database` Skill references 为准。
+> {{One sentence describing who this site helps and what they can do}}
 
-Page 和 Server Functions 是独立 npm 工程，各自维护 `package.json` 和 `package-lock.json`。可用脚本以各自的 `package.json` 为准。从包含 `base-database.jsonc` 的项目根目录发布：
+<!-- 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. -->
+
+## Background
+
+- **Target users**: {{Who will use this site}}
+- **Use cases**: {{When they will use it}}
+- **Problem to solve**: {{Summarize the original request}}
+
+## Requested features
+
+1. {{Core feature from the original request}}
+2. {{Another core feature from the original request}}
+
+## Implemented capabilities
+
+| User or role | Capability | Action and visible result |
+| ------------ | ---------- | ------------------------- |
+| {{User or role}} | {{Feature name}} | {{What users can actually do and see}} |
+
+## Status and limitations
+
+- **Verified**: {{Checks completed and their results}}
+- **Unverified or unavailable**: {{Requested behavior and current limitations; write None if there are none}}
+- **Demo entry**: Use the `baseAppUrl` delivered with this release. Do not pin a temporary Preview URL here.
+
+## Local project
+
+This directory contains Page, Database Function, Mutation declarations, and server-side FaaS Function source code. AI Function declarations, when used, live in `ai/`. Page and Server Functions are separate npm projects with their own `package.json` and `package-lock.json` files. The source and build workspace for server functions is `server-functions/`. Follow the installed `lark-base-database` Skill references for business and runtime contracts.
+
+Run checks and deployment from the project root containing `base-database.jsonc`:
 
 ```bash
+base-database-cli check --json
 base-database-cli deploy
 ```
 
-Server Functions 的 `build` 脚本名称是平台 FaaS 镜像打包 ABI。生成内容位于被 Git 忽略的 `dist/`。
+The CLI generates Page input types from Function metadata. Do not edit generated files by hand. Server Functions must keep a working `npm run build` script; generated output belongs in the Git-ignored `dist/` directory.

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

@@ -0,0 +1,8 @@
+# Database Functions
+
+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.
+
+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.

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

@@ -0,0 +1,19 @@
+# Mutation Functions
+
+每个声明能完整表达的固定业务写入放在 `<functionId>/meta.json` 和 `<functionId>/spec.json`。表和字段必须来自根目录 `catalog.json`。
+
+`meta.json` 示例：
+
+```json
+{"name":"更新标题"}
+```
+
+`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"]}
+```
+
+单条调用 `invokeDatabaseFunction('updateTitle', ['recA', '新标题'])`；批量调用 `invokeDatabaseMutationBatch('updateTitle', [['recA', '标题 A'], ['recB', '标题 B']])`。编号从 1 开始；一批最多 200 条。CLI deploy 自动校验、打包并更新 Function，pull 保留声明。
+
+Mutation 负责基础单表写入；create 不带 precondition，其他操作通过 precondition 指定记录 ID。需要服务端业务校验、计算或编排时使用 FaaS。字段、附件、权限边界和完整协议见已安装的 lark-base-database Skill 的 `references/mutations.md`。

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

@@ -1,29 +1,35 @@
 # Page
 
-React + TypeScript + Vite 页面工程。依赖版本、样式库和脚本只以本目录 `package.json` 为准。
+React + TypeScript + Vite page project. This directory's `package.json` defines its dependencies, styling libraries, and scripts.
 
-`invokeDatabaseFunction`、响应结构和 Base 读写边界见 `lark-base-database` Skill 的 `development.md`。
+See the `lark-base-database` Skill's `development.md` for `invokeDatabaseFunction`, response shapes, and Base read and write boundaries.
 
-`vite.config.ts` 中的相对路径配置是应用部署约束。
+The relative path setting in `vite.config.ts` is required for deployment.
 
-## 运行态通信
+## Built-in component language
 
-应用产物运行在 BaseApp 页面的 iframe 中，不持有登录凭证，也不直连业务域名。
-`src/lib/database-runtime.ts` 是与宿主通信的唯一入口，基于
-`@lark-base-open/base-site-channel/runtime` 提供：
+The placeholder `App.tsx` page and the included user selector, account menu, edit button, page state, and attachment image components provide fixed Chinese, English, and Japanese interface text without a translation service. They resolve the language from the host Runtime Context locale, then the browser language, then English. The Page does not pass a language prop. When the host switches language and reloads the Page, they resolve it again. The starter HTML initially uses `lang="en"`; the resolved language updates that attribute. Replace the placeholder page before delivery. Application-specific text and runtime service errors remain the application's responsibility.
 
-- `fetch` / `invokeHttp`：业务 HTTP 经父页面同源代发，URL 只能是以单个 `/` 开头的相对路径
-- `invokeDatabaseFunction(functionId, params)`：Function 调用，打统一网关的
-  `POST /space/api/bitable/site/v1/:token/invoke_function/:function_id`，请求体为 `{"params": ...}`
-- `resolveDatabaseContext()`：解析应用 token 与 `prod` / `preview` 环境，**宿主下发优先**，
-  宿主未提供时回退 `getDatabaseContext()` 的产物路径推断；业务代码用这个异步版本
-- `getDatabaseContext()`：同步的产物路径推断，仅作兜底，不要在业务代码里直接依赖
-- `siteRuntime`：`ready()` 与 `reportLoadFailed()` 生命周期上报
+Optional AI Function example components use the same language selection for their built-in text. See `src/examples/ai-function/README.md` before reusing or moving them.
 
-不要在业务代码里直接使用 `postMessage`、raw Channel Client 或直连业务域名的 `fetch`。
+## Runtime communication
 
-## CSRF 防护
+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`:
 
-`vite.config.ts` 通过 `@lark-base-open/base-site-js/vite` 提供的
-`createArgusCsrfPlugin()` 启用 CSRF 防护。修改配置时必须保留该插件，不得复制
-插件实现或手写 CSRF Header。
+- `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.
+- `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`.
+- `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`.
+
+## Request identity and CSRF
+
+The parent page proxies business HTTP requests and handles identity and CSRF. The Page must not inject a CSRF script, read host cookies, or set a CSRF header itself. See the `lark-base-database` Skill's `verification.md` for migration and request troubleshooting.

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

@@ -8,8 +8,7 @@
       "name": "page",
       "version": "0.0.0",
       "dependencies": {
-        "@lark-base-open/base-site-channel": "https://lf3-static.bytednsdoc.com/obj/eden-cn/vlseh7bfnuhps/@lark-base-open-base-site-channel-0.0.1-alpha.35.tgz",
-        "@lark-base-open/base-site-js": "https://lf3-static.bytednsdoc.com/obj/eden-cn/jjjpceh7nulojvhj/@lark-base-open-base-site-js-0.0.1-alpha.25.tgz",
+        "@lark-base-open/base-site-channel": "0.1.3",
         "@radix-ui/react-slot": "^1.3.0",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
@@ -25,7 +24,7 @@
         "@types/react-dom": "^19.2.3",
         "@vitejs/plugin-react": "^6.0.3",
         "oxlint": "^1.42.0",
-        "prettier": "^3.7.4",
+        "prettier": "3.6.2",
         "tailwindcss": "^4.3.2",
         "typescript": "~7.0.2",
         "vite": "^8.1.4",
@@ -120,20 +119,13 @@
       }
     },
     "node_modules/@lark-base-open/base-site-channel": {
-      "version": "0.0.1-alpha.35",
-      "resolved": "https://lf3-static.bytednsdoc.com/obj/eden-cn/vlseh7bfnuhps/@lark-base-open-base-site-channel-0.0.1-alpha.35.tgz",
-      "integrity": "sha512-GzpLpH4cZavVv54GghWwhg1ztZOnwPpLrkCkByqhJWtfWPiFjjKlwXeKHIa5PR+HPoOeTHuKtyhwUpRkoj0M0A==",
-      "license": "ISC",
+      "version": "0.1.3",
+      "resolved": "https://registry.npmjs.org/@lark-base-open/base-site-channel/-/base-site-channel-0.1.3.tgz",
+      "integrity": "sha512-wdc8zRkAX2P7pwBkyoun7oHrUP95xYCgAhhwsq4cUOg7ozIf9Em1DQken7kUeMc58pzDM5ONroWavoa1/oQiEg==",
       "dependencies": {
         "lodash-es": "^4.17.21"
       }
     },
-    "node_modules/@lark-base-open/base-site-js": {
-      "version": "0.0.1-alpha.25",
-      "resolved": "https://lf3-static.bytednsdoc.com/obj/eden-cn/jjjpceh7nulojvhj/@lark-base-open-base-site-js-0.0.1-alpha.25.tgz",
-      "integrity": "sha512-FtdohEY5YrYIRGxL/FIU8dSQ4326nf7QDZHEZm1HE59RIBAvlkPnqZlE+8AuvQZ+3KL+vmg6ZPmxONlghFyhbw==",
-      "license": "ISC"
-    },
     "node_modules/@napi-rs/wasm-runtime": {
       "version": "1.1.6",
       "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.6.tgz",
@@ -2254,9 +2246,9 @@
       }
     },
     "node_modules/prettier": {
-      "version": "3.9.5",
-      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.9.5.tgz",
-      "integrity": "sha512-/FVl766LpUfB5vXgCYOYa0MeV/441Ia99AeICQIQFTY/Nw0roZwULcXpku5i1/m5kt/baz+s4Zogspd839HSMg==",
+      "version": "3.6.2",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.6.2.tgz",
+      "integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==",
       "dev": true,
       "license": "MIT",
       "bin": {

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

@@ -18,8 +18,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@lark-base-open/base-site-channel": "https://lf3-static.bytednsdoc.com/obj/eden-cn/vlseh7bfnuhps/@lark-base-open-base-site-channel-0.0.1-alpha.35.tgz",
-    "@lark-base-open/base-site-js": "https://lf3-static.bytednsdoc.com/obj/eden-cn/jjjpceh7nulojvhj/@lark-base-open-base-site-js-0.0.1-alpha.25.tgz",
+    "@lark-base-open/base-site-channel": "0.1.3",
     "@radix-ui/react-slot": "^1.3.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -35,7 +34,7 @@
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.3",
     "oxlint": "^1.42.0",
-    "prettier": "^3.7.4",
+    "prettier": "3.6.2",
     "tailwindcss": "^4.3.2",
     "typescript": "~7.0.2",
     "vite": "^8.1.4",

package/templates/database-starter/page/src/App.tsx

@@ -1,4 +1,25 @@
+import { useUiLanguage, type UiLanguage } from './lib/ui-language'
+
+const APP_COPY = {
+  en: {
+    heading: 'Start with a real business workflow',
+    description:
+      'Build the interface with page components. Read Base data through Database Functions and write through FaaS Functions. Replace this starter content before delivery.',
+  },
+  zh: {
+    heading: '从真实业务任务开始构建',
+    description:
+      '使用页面组件承载交互，通过 Database Function 读取 Base 数据、通过 FaaS Function 写入，并在交付前替换这段起始内容。',
+  },
+  ja: {
+    heading: '実際の業務フローから構築を始めましょう',
+    description:
+      'ページコンポーネントで操作画面を作成します。Base データは Database Function で読み込み、FaaS Function で書き込みます。公開前にこの初期コンテンツを置き換えてください。',
+  },
+} satisfies Record<UiLanguage, { heading: string; description: string }>
+
 export default function App() {
+  const copy = APP_COPY[useUiLanguage()]
   return (
     <main className="flex min-h-screen items-center justify-center bg-background px-6 py-12 text-foreground">
       <section className="w-full max-w-2xl rounded-3xl border border-border bg-card p-8 shadow-sm sm:p-12">
@@ -6,11 +27,10 @@ export default function App() {
           Base Database
         </p>
         <h1 className="mt-4 text-3xl font-semibold tracking-tight text-balance sm:text-5xl">
-          从真实业务任务开始构建
+          {copy.heading}
         </h1>
         <p className="mt-5 max-w-xl text-base leading-7 text-muted-foreground sm:text-lg">
-          使用页面组件承载交互，通过受控 Function 连接 Base SQL 与
-          FaaS，并在交付前替换这段起始内容。
+          {copy.description}
         </p>
       </section>
     </main>

package/templates/database-starter/page/src/components/UserSelectorEditor/index.tsx

@@ -9,6 +9,7 @@ import React, {
 } from 'react'
 
 import { cn } from '../../lib/cn'
+import { useUiLanguage, type UiLanguage } from '../../lib/ui-language'
 import UserSelectorPanel, {
   type User,
   type UserSelectorAction,
@@ -38,6 +39,31 @@ export interface UserSelectorEditorProps {
   onBlur?: FocusEventHandler<HTMLButtonElement>
 }
 
+const USER_SELECTOR_EDITOR_COPY = {
+  en: {
+    clearSelected: 'Clear selected members',
+    removeMember: (name: string) => `Remove member ${name}`,
+    selectMembers: 'Select members',
+  },
+  zh: {
+    clearSelected: '清除已选成员',
+    removeMember: (name: string) => `移除成员 ${name}`,
+    selectMembers: '选择成员',
+  },
+  ja: {
+    clearSelected: '選択したメンバーをクリア',
+    removeMember: (name: string) => `メンバー ${name} を削除`,
+    selectMembers: 'メンバーを選択',
+  },
+} satisfies Record<
+  UiLanguage,
+  {
+    clearSelected: string
+    removeMember: (name: string) => string
+    selectMembers: string
+  }
+>
+
 /**
  * 展示受控成员值，并闭环管理 UserSelectorPanel 的打开、关闭与值回传。
  */
@@ -61,6 +87,8 @@ export default function UserSelectorEditor(
     onFocus,
     onBlur,
   } = props
+  const uiLanguage = useUiLanguage()
+  const i18n = USER_SELECTOR_EDITOR_COPY[uiLanguage]
   const [open, setOpen] = useState(false)
   const rootRef = useRef<HTMLDivElement>(null)
   const panelOpen = open
@@ -175,8 +203,8 @@ export default function UserSelectorEditor(
                   <button
                     aria-label={
                       isMultiple
-                        ? `移除成员 ${selectedUser.name}`
-                        : '清除已选成员'
+                        ? i18n.removeMember(selectedUser.name)
+                        : i18n.clearSelected
                     }
                     className="relative ml-0 flex size-3.5 shrink-0 cursor-pointer items-center justify-center rounded-sm border-0 bg-transparent p-0 !text-[#646a73] outline-none hover:!text-[#0442d2]"
                     onClick={(event) => {
@@ -214,7 +242,7 @@ export default function UserSelectorEditor(
               ))
             ) : (
               <button
-                aria-label="选择成员"
+                aria-label={i18n.selectMembers}
                 aria-expanded={panelOpen}
                 aria-haspopup="listbox"
                 className="flex h-full min-w-0 flex-1 items-center gap-1 border-0 bg-transparent p-0 text-left text-inherit outline-none"
@@ -223,7 +251,7 @@ export default function UserSelectorEditor(
                 type="button"
               >
                 <span className="min-w-0 flex-1 truncate text-[#8f959e]">
-                  选择成员
+                  {i18n.selectMembers}
                 </span>
               </button>
             )}