@lark-base-open/base-database-cli 1.6.0 → 1.7.0

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

@@ -4,7 +4,7 @@
 
 ## 站点 README
 
-新建站点时，先从用户原始建站 Prompt 的主要自然语言确定 README 语言：支持中文、日文、英文；其他语言或无法判断主要语言时使用英文。用户明确指定 README 使用这三种语言之一时按其指定语言填写；指定其他语言时仍使用英文。读取初始化生成的项目根目录 `README.md`，按选定语言重写业务标题与正文、清理 hello 示例，并移除实际存在的占位内容；命令、路径和代码标识符保留原样。修改已有站点时沿用现有 README 语言，除非用户明确要求切换。README 是生成时确定的源码文档，不随 Site 运行时的宿主或浏览器语言变化。
+新建站点时，先从用户原始建站 Prompt 的主要自然语言确定 README 语言：支持中文、日文、英文；其他语言或无法判断主要语言时使用英文。用户明确指定 README 使用这三种语言之一时按其指定语言填写；指定其他语言时仍使用英文。读取初始化生成的项目根目录 `README.md`，按选定语言重写业务标题与正文，并移除实际存在的占位内容；不需要的问候 Function 按[清理初始化示例](workspace.md#清理初始化示例)处理。命令、路径和代码标识符保留原样。修改已有站点时沿用现有 README 语言，除非用户明确要求切换。README 是生成时确定的源码文档，不随 Site 运行时的宿主或浏览器语言变化。
 
 四个必要章节使用下表中所选语言的标题；CLI 接受这三组标题，并只检查结构、占位符和章节是否非空，不判断正文语言或业务描述是否属实：
 

package/skills/lark-base-database/references/style-guide.md

@@ -6,7 +6,7 @@
 
 1. 先明确用户、目标、核心流程、状态变化和失败路径，再设计表与页面。
 2. 具有独立生命周期、权限或统计需求的业务事实使用独立表，并明确数据所有权、归档和追溯要求。
-3. 每张表有可读主字段；存在独立生命周期时设计状态，存在责任分配时设计负责人，按业务与审计需求配置时间、标识和关系。
+3. 每张表有可读主字段；存在独立生命周期时设计状态，存在责任分配时设计负责人，按业务与审计需求配置时间、标识和关系。底表也会被 Base 协作者直接打开浏览，表结构按[底表设计](base-table-design.md)执行。
 4. 状态使用受控单选并定义合法转换；关系、金额、日期、人员使用对应 Base 字段。
 5. 页面围绕用户任务组织，不按表机械生成 CRUD。
 6. 每个 operation 定义固定输入、输出、权限、失败语义和影响范围。

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

@@ -17,7 +17,7 @@ CLI/存量 classic 使用 Node.js 20.19+；新建 workspace 与契约生成使
 
 `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`。
+公开 CLI 只使用 `online` 环境；`init`、`pull` 等支持环境参数的命令显式传 `--env online`，`deploy` 不接受该参数。CLI、OpenAPI、Accounts、应用和 Page runtime 必须处于同一环境；原生资源操作默认使用 `--as user`；以机器人（bot）身份搭建时按 [bot 建站与交接](collaborator-handoff.md) 显式声明身份。
 
 首次使用 `lark-cli` 时读取当前入口的 `--help`，本会话复用已确认的命令能力；不只按版本号判断。
 
@@ -103,12 +103,14 @@ CLI 自动保存 init、pull 和提交成功后的草稿基线。`REMOTE_SOURCE_
 
 ### 从零创建 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 后再按原顺序创建其余字段。
+编写 schema 前，按已确认的文档入口读取字段规范：先执行 `lark-cli skills list lark-base/references` 获取当前 reference 路径列表，再用 `lark-cli skills read <reference-path>` 读取其中的字段定义文档；`<reference-path>` 使用列表返回的完整路径，不猜测或固定文件名。命令不可用时，直接读取环境中 lark-base 的对应 reference，并用 `lark-cli base +table-create --help` 核对当前命令契约，不再尝试已知缺失的入口。不要猜测属性。`tables[].fields` 使用与 `lark-cli base +base-create/+table-create --fields` 相同的字段定义；init 会先创建每张表的主字段，取得全部真实表 ID 后再按原顺序创建其余字段。
 
 - 用户所在地或需求明确了时区时，`init --schema` 追加 `--time-zone <IANA 时区>`（例如 `Asia/Tokyo`）；未指定时由服务端按租户默认时区创建。
+- 表结构先按[底表设计](base-table-design.md)完成两层设计。
 - 首个字段成为表的主字段，优先采用可读的文本标识；其他类型先核对主字段限制。
 - 单选和多选都用 `select`，多选显式设置 `"multiple": true`，选项按字段规范声明。
 - `link` 字段必须提供 `link_table`，且名称与本次 Schema 中的目标表完全一致；自关联和跨表关联会在所有表创建后补建，不需要按关联依赖调整表顺序。
+- Schema 包含 `formula` 或 `lookup` 时，编写表达式或引用条件前先读取当前 lark-base 中对应类型的指南；字段结构校验不能代替该步骤。
 - `datetime.style.format` 使用当前 Base 支持的固定枚举，不能自行增加秒级展示格式；底层时间精度与展示格式分别处理。
 - 创建字段的 schema、查询类型与记录 CellValue 是不同协议，不互相替代。
 
@@ -126,9 +128,9 @@ CLI 自动保存 init、pull 和提交成功后的草稿基线。`REMOTE_SOURCE_
           "name": "状态",
           "multiple": false,
           "options": [
-            { "name": "待处理" },
-            { "name": "进行中" },
-            { "name": "已完成" }
+            { "name": "待处理", "hue": "Gray" },
+            { "name": "进行中", "hue": "Blue" },
+            { "name": "已完成", "hue": "Green" }
           ]
         },
         {
@@ -191,6 +193,17 @@ package-lock.json    # 唯一根依赖锁
 
 只从 `catalog.json` 读取表名、字段名、ID、选项和查询类型，不根据建表输入猜测 Catalog 结果。
 
+### 清理初始化示例
+
+初始化生成的 `server/functions/hello/` 是问候示例。业务不使用它时，在首次生成契约和 check 前删除整个目录，包括 `index.ts`、`contract.ts`、`meta.json`，不要只删除文件后留下空目录。在项目根目录执行：
+
+<!-- example: remove-starter-hello -->
+```bash
+node -e "require('node:fs').rmSync('server/functions/hello', { recursive: true, force: true })"
+```
+
+该命令也可清理逐文件删除后留下的空目录；已改为业务用途的 hello 和其他需求外 Function 保留。同步移除页面中实际存在的示例调用，再按[Check 与契约生成](development.md#check-与契约生成)生成契约并检查。CLI 仍将非完整的 Function 目录视为错误，不会把残缺声明静默排除。
+
 ### 初始化失败与阶段回执
 
 `--schema` 路径会在首个远端创建前校验整份 schema；按返回的字段路径修正。本地预检通过不代表权限、配额或服务端语义检查通过。

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

@@ -20,6 +20,6 @@ workspace 工程结构。
 
 ## Local project
 
-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`。
+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 报错给出的恢复步骤处理，保留当前 SDK 版本，升级需用户授权。依赖准备与 contracts generate 的选项见随 CLI Skill 的 development.md「Check 与契约生成」；生成后运行 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.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==",
+      "version": "0.4.2",
+      "resolved": "https://registry.npmjs.org/@lark-base-open/base-database-app-sdk/-/base-database-app-sdk-0.4.2.tgz",
+      "integrity": "sha512-owQolTJLCN6yPtu/o0LNO+E82nZ0r1fYLXfo+cnMjcyasFJdEgPRW4YcUuY/4+jiRXNxX0s3yG53k0s11vLFAQ==",
       "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.3.2",
+        "@lark-base-open/base-database-app-sdk": "0.4.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.3.2",
+        "@lark-base-open/base-database-app-sdk": "0.4.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.3.2",
+    "@lark-base-open/base-database-app-sdk": "0.4.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.3.2",
+    "@lark-base-open/base-database-app-sdk": "0.4.2",
     "zod": "4.6.5"
   },
   "devDependencies": {