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

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

@@ -96,10 +96,25 @@ Database Function 只支持本文明确列出的只读查询语法和函数，
 | `ARRAY<T>` | `T[]`；例如 `OPTION[]` 的元素为 `{id, name}` |
 | nullable field | 原类型或 `null` |
 
+- 多值字段（含返回多值的公式、lookup）没有成员时返回 `[]`，字段值缺失时返回 `null`；`IS NULL` 只匹配后者。成员不含 `null`，部分来源为空时只返回有效成员。
+- 公式、lookup 返回的数组不与关联记录逐位对应；需要按来源记录对齐时，JOIN 关联表并按 `rec_id` 对应。
+- 查询中用 `ARRAY[...]` 构造的数组保留 `null` 元素。
+- `ARRAY_AGG` 跳过 `null` 输入，全部为 `null` 或没有输入时返回 `null`；不要依赖多个 `ARRAY_AGG` 按下标对应，需要对应时用 JOIN 或保持逐行查询。有序 `ARRAY_AGG(value ORDER BY key)` 还要求 TEXT 或数值输入可证明非 NULL（如 `WHERE value IS NOT NULL` 或非空 `COALESCE`）；其余形态限制见[生成参考的 OrderedArrayDomain](base-sql-errors.generated.md)。
+- `CARDINALITY` 对已准入的一维数组计数：空数组为 `0`，整体 NULL 为 `null`，NULL 元素计入长度；`ARRAY_LENGTH(array, 1)` 对空数组返回 `null`。
+- `ARRAY_SORT` 只接受一个可证明的一维载体：无 NULL 成员的常量数组、合法原生标量集合字段或有类型的整体 NULL 数组；元素限数值、TEXT、TIMESTAMP，不接受数组参数或未知派生载体。文本排序遵循 Base 文本规则。
+
 执行时区按显式请求时区、Base 设置、Base 默认 `Asia/Shanghai` 的优先级确定；未设置时区的 Base 也按默认时区解析 TIMESTAMP 参数并渲染返回值。`TO_CHAR` 和时间投影使用同一生效时区。
 
 日期表单回填与时间展示按[日期与时区](development.md#日期与时区)处理。
 
+## 函数能力描述
+
+站点助手通过 `lark-cli base +site-func-list` 发现 Database Function、Mutation 和 FaaS/Edge，以 `name` + `description` 判断何时调用。三类函数都在各自 `meta.json` 的顶层填写 `description`；`ai/<key>/meta.json` 不在此发现链路中，不适用本节校验。
+
+描述应让助手判断业务用途及调用影响。默认用一句话说明给谁用或何时用、读取或写入什么数据，并明确只读、写入或外部调用等副作用，例如「员工查看本人各周期订阅及转账状态（只读）」。描述要符合真实实现；不能代替权限控制或用重复函数名凑长度。
+
+CLI 要求 `description` 为字符串，trim 后非空且至少 8 个 Unicode 字符，与 trim 后的 `name` 不同；原始字符串（含首尾空白）最多 500 个 Unicode 字符。`check` 和 Preview `deploy` 在远端请求前列出所有不合格描述的文件路径，`context` 也会在 warnings 中列出；正式版发布提升的是已校验的 Preview 制品，不再检查本地描述。`pull` 保留历史源码并允许缺少描述；恢复后按实际业务补齐，再运行 `check`。
+
 ## Function 文件与参数
 
 ```text
@@ -108,7 +123,7 @@ database-functions/<functionId>/
 └── meta.json
 ```
 
-`main.sql` 只包含一条固定 `SELECT`。`meta.json` 包含非空 `name`、可选 `description` 和参数声明。
+`main.sql` 只包含一条固定 `SELECT`。`meta.json` 包含非空 `name`、必填 `description`（见[函数能力描述](#函数能力描述)）和参数声明。
 
 查询使用位置参数 `$1`、`$2`……；`meta.params` 按相同顺序声明：
 
@@ -123,7 +138,7 @@ LIMIT $3
 ```json
 {
   "name": "搜索任务",
-  "description": "按关键词和状态搜索任务",
+  "description": "成员按关键词和状态搜索任务列表（只读）",
   "meta": {
     "params": [
       { "kind": "TEXT", "description": "$1，已包含 % 的关键词" },
@@ -153,6 +168,10 @@ LIMIT 30
 
 对应参数声明为 `{"kind":"TEXT[]"}`，例如调用 `params: [["重点", "普通"]]`。本例左侧为 `TEXT`，右侧为一维 `TEXT[]` 位置参数；其他形态按[生成参考](base-sql-errors.generated.md)判定。空数组不会选中记录。数组含 `null` 时不保证 PostgreSQL 三值语义，具体结果与预处理规则见[NULL 与数值边界](database-function-limitations.md#null-与数值边界)。成员判断与数组展开的区别及修法以[生成参考](base-sql-errors.generated.md)为准。
 
+6.0 多选按名称筛选使用 `(多选字段).name @> $n`，将 `$n` 声明为 `TEXT[]`。数组作为一个参数传入，例如 `params: [["选项名"]]`，不拆成多个标量；空数组不要求任何选项，但仍只匹配多选值非 NULL 的行。整体 NULL 参数或含 NULL 成员的参数数组不匹配任何行。单个非 NULL 名称也可使用 `(多选字段).name @> ARRAY[$n]`，其中 `$n` 声明为 `TEXT`；该写法传 NULL 会被拒绝。
+
+上述多选名称筛选仅用于 6.0；2.0 的准入限制及处理方式见[生成参考](base-sql-errors.generated.md)，不能由原生多选集合之间的包含比较推断 `.name` 数组具有相同准入。
+
 无参数 Function 可以省略 `meta` 或 `meta.params`；归档统一补成 `{"params":[]}`。
 
 Database Function 的 `inputSchema` 由 CLI 根据参数顺序与 kind 生成固定长度数组 Schema，不在 Database Function 的 `meta.json` 中手写。FaaS 则必须显式声明，见[FaaS 开发](faas.md#faas-开发)。
@@ -165,11 +184,15 @@ Database Function 的 `inputSchema` 由 CLI 根据参数顺序与 kind 生成固
 - 默认逐列投影并使用 `AS snake_case`，保持输出 Schema 稳定；连接的每一侧保持为一个表或带别名的派生表。常规生成优先简单连接、顶层查询和带别名的派生表，复杂组合依据生成参考及验证结果决定。
 - 子查询优先作为带别名的 `FROM` 派生表使用，外层通过输出列名引用结果。需要其他形态时先核对业务语义与生成参考，不把默认生成偏好当作支持清单。
 - 列表使用有界 `LIMIT` 和稳定排序；排序值可能重复时最后按 `rec_id` 排序。不把截断结果的前端分页视为完整分页或全量导出。
+- 文本排序与比较按 Base 文本规则：中文按拼音顺序，区分大小写。需要固定业务顺序时用 `CASE` 映射。
+- 产品写入的空字符串读取为 `null`，筛选空文本用 `IS NULL`，不要写 `= ''`。
 - 搜索写 `field LIKE $1`，由参数携带 `%`。
 - 当前访问者使用 `CURRENT_USER_ID()`，不由页面传入用户 ID。权限关系的实现边界按[权限设计](permission-design.md#读路径database-function-就是策略面)。
-- UDT 列成员使用 PostgreSQL 复合类型括号语法：无表别名写 `("负责人").id`、`("链接").link`，带表别名写 `(t."负责人").id`。FILE 的成员为 `.token/.name/.mime_type/.size`；逐元素读取后的 range alias 成员写 `u.id`。
+- UDT 列成员使用 PostgreSQL 复合类型括号语法：无表别名写 `("负责人").id`、`("链接").link`，带表别名写 `(t."负责人").id`。FILE 的成员为 `.token/.name/.mime_type/.size`；逐元素读取后的 range alias 成员写 `u.id`。6.0 支持 USER 的 `.id IS NULL` / `.id IS NOT NULL`；2.0 按目标诊断判定。
 - 集合字段的 PostgreSQL 数组运算符含义为：`@>`（包含）、`<@`（被包含）、`&&`（有交集）。先用 Catalog 的 `sqlType` 区分标量与集合，再按生成参考判断操作是否适用；展开集合前确认业务是否允许改变主表行数。
 - 时间条件使用 Catalog 中确认为 `TIMESTAMP` 的字段和 `TIMESTAMP` 位置参数；当前时间使用 `CURRENT_TIMESTAMP`。查询结果固定为 Base 执行时区下的 `YYYY-MM-DD HH:mm:ss.SSS` 字符串。`EXTRACT(EPOCH FROM timestamp_expr)` 返回保留小数秒的 `DOUBLE`；明确只需整数秒时再写 `::bigint`。
+- 2.0 支持单参 `ROUND(float8)`，半值取偶；numeric 舍入半值远离零。双参 `ROUND` 的首参须可证明为 numeric，精度须为 -15…15 的静态整数；numeric 仍由 DOUBLE 承载，不保证任意十进制精度。
+- 2.0 支持 TEXT 参数的 `CONCAT_WS`：跳过 NULL 值，NULL 分隔符返回 NULL；`PERCENTILE_CONT(p) WITHIN GROUP (ORDER BY value)` 要求静态 `p` 在 0…1、单个数值排序表达式，按邻值插值；其余形态限制见[生成参考的 PercentileDomain](base-sql-errors.generated.md)。
 - 窗口、聚合、字符串、日期和数值计算先明确结果契约，再查[目录生成的修法与已验证 SQL](base-sql-errors.generated.md)。默认采用满足前提的形式；例外是没有等价 SQL 或改写改变所需语义，此时统一按[SQL 外实现放在哪](../SKILL.md#sql-外实现放在哪)选择实现位置。
 
 字段类型和成员来自 Catalog，输入按本节参数协议声明；适用的字段操作与修复路径查[生成参考](base-sql-errors.generated.md)，而不是从字段名称推断。示例演示参数和结果消费，不作为完整能力清单。

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

@@ -86,6 +86,8 @@ metadata 只声明输入，因此生成文件只约束调用参数。调用结
 
 ## Page 调用
 
+外链由页面 Runtime 统一接管，并经宿主安全检查后打开。默认直接使用 a 标签，程序化打开使用 `@lark-base-open/base-site-channel/runtime` 的 `openLink(url)`；保留 starter 启动时的 `installLinkGuard()` 接入。页面导航留在 iframe 内，不使用 location 跳出 iframe，也不依赖宿主放开 sandbox。
+
 默认 Page 的 `page/index.html` 需要把 `<title>` 设置为本次生成的应用名称，不留空。
 
 默认 Page 必须引用并渲染 `page/src/components/floating-button/index.tsx` 中的 `FloatingButton` 组件。该组件自行解析应用 token，不接受 `projectId`。悬浮控件仅在正式环境向服务端判定有管理权限的访问者提供「编辑应用」入口。

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

@@ -13,6 +13,8 @@
 
 ## FaaS 开发
 
+`meta.json` 的描述遵循[函数能力描述](database-function.md#函数能力描述)。
+
 第三方 Agent 配置 FaaS 的凭证或环境相关配置时，先读取[环境变量协议](environment-variables.md)。值仅由 FaaS 静态 `process.env.NAME` 或 `process.env['NAME']` 读取，不进入 Page、源码、配置、日志或函数返回值。动态 `process.env[key]`、解构和其他无法静态确定变量名的访问会阻止部署。
 
 每个 FaaS 业务动作的目录：
@@ -26,7 +28,7 @@ server-functions/functions/<functionId>/
 ```json
 {
   "name": "创建任务",
-  "description": "校验输入并创建一条任务记录",
+  "description": "成员创建任务时校验输入并写入一条任务记录",
   "inputSchema": {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "type": "object",

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

@@ -17,10 +17,10 @@ CLI 的 `deploy` 自动校验、打包并注册声明，`pull` 恢复 `mutations
 
 ## 声明与参数
 
-`meta.json`：
+`meta.json` 的描述遵循[函数能力描述](database-function.md#函数能力描述)：
 
 ```json
-{"name":"创建任务","description":"提交一条待处理任务"}
+{"name":"创建任务","description":"成员提交新任务时写入一条待处理任务记录"}
 ```
 
 Mutation 不声明角色；调用仍需通过应用统一准入。记录 ID 仅限定操作范围，不代表记录归属或行权限校验。
@@ -146,7 +146,7 @@ Mutation 不声明角色；调用仍需通过应用统一准入。记录 ID 仅
 建立 `mutations/appendTaskAttachments/meta.json`：
 
 ```json
-{"name":"追加任务附件"}
+{"name":"追加任务附件","description":"成员为指定任务追加已上传的附件，写入任务附件字段"}
 ```
 
 `mutations/appendTaskAttachments/spec.json`（ID 替换为 Catalog 中的真实值）：
@@ -200,7 +200,7 @@ Page 检查一次顶层 `code`；成功后从 `data.records` 找到对应 `rec_i
 
 ### 移除附件引用
 
-`meta.json` 沿用追加示例，将名称改为“移除任务附件”。
+`meta.json` 沿用追加示例，将名称改为“移除任务附件”，描述改为“成员移除指定任务中的附件，写入任务附件字段”。
 
 `mutations/removeTaskAttachments/spec.json`：
 

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

@@ -5,7 +5,7 @@
 `meta.json` 示例：
 
 ```json
-{"name":"更新标题"}
+{"name":"更新标题","description":"成员修改指定任务的标题，写入任务标题字段"}
 ```
 
 `spec.json` 示例（替换真实 table / field ID）：

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

@@ -8,7 +8,7 @@
       "name": "page",
       "version": "0.0.0",
       "dependencies": {
-        "@lark-base-open/base-site-channel": "0.1.4",
+        "@lark-base-open/base-site-channel": "0.1.5",
         "@radix-ui/react-slot": "^1.3.0",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
@@ -119,9 +119,9 @@
       }
     },
     "node_modules/@lark-base-open/base-site-channel": {
-      "version": "0.1.4",
-      "resolved": "https://registry.npmjs.org/@lark-base-open/base-site-channel/-/base-site-channel-0.1.4.tgz",
-      "integrity": "sha512-QBl60LoxLr2kNjCHxiuXtFxegSrMPA11P0IufjOkoonNEvZz3CfDtFwhO+EbkOZahANMRyxEq3DhdpFgEm5QDQ==",
+      "version": "0.1.5",
+      "resolved": "https://registry.npmjs.org/@lark-base-open/base-site-channel/-/base-site-channel-0.1.5.tgz",
+      "integrity": "sha512-us+Un3OIaDnFQ8QQH9xPbPeSkZiJDxYsUkfq40KYgTGHovZuBb4SiSTH9+C7tPz5SjyAoc0JCQFM14S4XARWVg==",
       "dependencies": {
         "lodash-es": "^4.17.21"
       }

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

@@ -18,7 +18,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@lark-base-open/base-site-channel": "0.1.4",
+    "@lark-base-open/base-site-channel": "0.1.5",
     "@radix-ui/react-slot": "^1.3.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

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

@@ -11,14 +11,12 @@ import tooltipCaretIcon from './assets/tooltip-caret.svg'
 import toastInfoIcon from './assets/toast-info.svg'
 import toastCloseIcon from './assets/toast-close.svg'
 import { fetchProjectMeta, type ProjectMeta } from './utils/project-meta'
-import {
-  getDatabaseContext,
-  resolveDatabaseContext,
-  siteRuntime,
-} from '../../lib/database-runtime'
+import { getDatabaseContext } from '../../lib/database-runtime'
+import { requestEditOrOpenManagement } from './utils/request-edit'
 import { useUiLanguage, type UiLanguage } from '../../lib/ui-language'
 
 interface FloatingButtonI18n {
+  openFailed: string
   editSite: string
   hidePanel: string
   hiddenConfirmation: string
@@ -31,7 +29,6 @@ interface TooltipPosition {
   arrowLeft: number
 }
 
-const BASE_DATABASE_OVERVIEW_URL = 'https://feishu.cn/base/site/detail/overview'
 const FLOATING_BUTTON_PAGE_GAP = 24
 const TOOLTIP_VIEWPORT_GAP = 8
 const HIDDEN_CONFIRMATION_MS = 3000
@@ -45,18 +42,21 @@ const EMPTY_PROJECT_META: ProjectMeta = {
 }
 const FLOATING_BUTTON_I18N: Record<UiLanguage, FloatingButtonI18n> = {
   en: {
+    openFailed: 'Unable to open the management page. Please try again.',
     editSite: 'Edit and manage your apps',
     hidePanel: 'Hide until next visit',
     hiddenConfirmation: 'Edit button hidden until you reopen the app',
     dismissNotification: 'Dismiss notification',
   },
   zh: {
+    openFailed: '无法打开管理页面，请重试',
     editSite: '编辑与管理应用',
     hidePanel: '隐藏面板',
     hiddenConfirmation: '编辑按钮已隐藏，直至下次重新打开应用',
     dismissNotification: '关闭提示',
   },
   ja: {
+    openFailed: '管理ページを開けませんでした。もう一度お試しください。',
     editSite: 'アプリを編集・管理',
     hidePanel: '次回のアクセスまで非表示',
     hiddenConfirmation:
@@ -70,6 +70,7 @@ const FLOATING_BUTTON_I18N: Record<UiLanguage, FloatingButtonI18n> = {
  */
 export function FloatingButton() {
   const [projectMeta, setProjectMeta] = useState<ProjectMeta | null>(null)
+  const [linkFailed, setLinkFailed] = useState(false)
   const [isHidden, setIsHidden] = useState(false)
   const [showHiddenConfirmation, setShowHiddenConfirmation] = useState(false)
   const [activeTooltip, setActiveTooltip] = useState<'edit' | 'hide' | null>(
@@ -148,14 +149,10 @@ export function FloatingButton() {
   }, [])
 
   // 编辑按钮走 site.v1 契约：应用发 request-edit，宿主切编辑态后广播 mode-changed。
-  // 应用被独立访问（无宿主）时事件无人消费，回落为打开 Site 管理页。
+  // 切换失败时管理页也经 OpenLink；宿主不可用或安全检查失败时显示错误。
   const requestEdit = useCallback(() => {
-    void siteRuntime.requestEdit().catch(async () => {
-      const { token } = await resolveDatabaseContext()
-      const url = new URL(BASE_DATABASE_OVERVIEW_URL)
-      url.searchParams.set('token', token)
-      openExternalUrl(url.toString())
-    })
+    setLinkFailed(false)
+    void requestEditOrOpenManagement().catch(() => setLinkFailed(true))
   }, [])
 
   if (!shouldShowEditButton) {
@@ -194,6 +191,14 @@ export function FloatingButton() {
       className="group fixed bottom-10 z-40 flex items-center"
       style={{ right: FLOATING_BUTTON_PAGE_GAP }}
     >
+      {linkFailed ? (
+        <div
+          role="alert"
+          className="absolute bottom-full right-0 mb-2 w-64 rounded bg-white p-3 text-sm text-red-700 shadow"
+        >
+          {i18n.openFailed}
+        </div>
+      ) : null}
       {activeTooltip ? (
         <div
           ref={tooltipRef}
@@ -266,11 +271,4 @@ export function FloatingButton() {
   )
 }
 
-/** 使用新标签页打开外部链接。
- * @param url 待打开的外部链接。
- */
-function openExternalUrl(url: string): void {
-  window.open(url, '_blank', 'noopener,noreferrer')
-}
-
 export default FloatingButton

package/templates/database-starter/page/src/components/floating-button/utils/request-edit.test.ts

@@ -0,0 +1,42 @@
+import { beforeEach, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  requestEdit: vi.fn(),
+  resolveDatabaseContext: vi.fn(),
+  openLink: vi.fn(),
+}))
+vi.mock('@lark-base-open/base-site-channel/runtime', () => ({
+  openLink: mocks.openLink,
+}))
+vi.mock('../../../lib/database-runtime', () => ({
+  siteRuntime: { requestEdit: mocks.requestEdit },
+  resolveDatabaseContext: mocks.resolveDatabaseContext,
+}))
+import { requestEditOrOpenManagement } from './request-edit'
+
+beforeEach(() => {
+  vi.resetAllMocks()
+  mocks.requestEdit.mockResolvedValue(undefined)
+  mocks.resolveDatabaseContext.mockResolvedValue({ token: 'site-example' })
+  mocks.openLink.mockResolvedValue({ opened: true })
+})
+it('switches edit mode without opening a new page', async () => {
+  await requestEditOrOpenManagement()
+  expect(mocks.openLink).not.toHaveBeenCalled()
+})
+it('routes management fallback through OpenLink', async () => {
+  mocks.requestEdit.mockRejectedValue(new Error('unavailable'))
+  await requestEditOrOpenManagement()
+  expect(mocks.openLink).toHaveBeenCalledWith(
+    'https://feishu.cn/base/site/detail/overview?token=site-example',
+  )
+})
+it.each([false, 'reject'])(
+  'propagates %s to visible component feedback',
+  async (outcome) => {
+    mocks.requestEdit.mockRejectedValue(new Error('unavailable'))
+    if (outcome === false) mocks.openLink.mockResolvedValue({ opened: false })
+    else mocks.openLink.mockRejectedValue(new Error('security unavailable'))
+    await expect(requestEditOrOpenManagement()).rejects.toThrow()
+  },
+)

package/templates/database-starter/page/src/components/floating-button/utils/request-edit.ts

@@ -0,0 +1,21 @@
+import { openLink } from '@lark-base-open/base-site-channel/runtime'
+import {
+  resolveDatabaseContext,
+  siteRuntime,
+} from '../../../lib/database-runtime'
+
+const BASE_DATABASE_OVERVIEW_URL = 'https://feishu.cn/base/site/detail/overview'
+
+/** 优先请求宿主切换编辑态；管理页链接同样交给宿主安全检查。 */
+export async function requestEditOrOpenManagement(): Promise<void> {
+  try {
+    await siteRuntime.requestEdit()
+    return
+  } catch {
+    const { token } = await resolveDatabaseContext()
+    const url = new URL(BASE_DATABASE_OVERVIEW_URL)
+    url.searchParams.set('token', token)
+    const result = await openLink(url.toString())
+    if (!result.opened) throw new Error('Management page was not opened')
+  }
+}

package/templates/database-starter/page/src/main.test.ts

@@ -0,0 +1,28 @@
+import { afterEach, expect, it, vi } from 'vitest'
+
+const calls = vi.hoisted(() => [] as string[])
+vi.mock('@lark-base-open/base-site-channel/runtime', () => ({
+  installLinkGuard: () => {
+    calls.push('guard')
+    return () => {}
+  },
+}))
+vi.mock('react-dom/client', () => ({
+  createRoot: () => ({ render: () => calls.push('render') }),
+}))
+vi.mock('./App', () => ({ default: () => null }))
+vi.mock('./components/database-runtime-ready', () => ({
+  DatabaseRuntimeReady: () => null,
+}))
+vi.mock('./lib/database-runtime', () => ({
+  siteRuntime: { reportLoadFailed: vi.fn() },
+}))
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+it('installs the link guard before rendering the page', async () => {
+  vi.stubGlobal('document', { getElementById: () => ({}) })
+  await import('./main')
+  expect(calls).toEqual(['guard', 'render'])
+})

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

@@ -1,3 +1,4 @@
+import { installLinkGuard } from '@lark-base-open/base-site-channel/runtime'
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
 import App from './App'
@@ -24,6 +25,7 @@ function bootstrapDatabaseApp(): void {
 }
 
 try {
+  installLinkGuard()
   bootstrapDatabaseApp()
 } catch (error) {
   // ready 之前的启动失败必须显式上报，否则宿主只能等到 ready 超时才展示错误态。