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

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

@@ -1,6 +1,12 @@
 # Database Function 能力边界
 
-仅在判断支持集之外的查询语法、评审或排查查询语句，或者处理查询编译与运行兼容失败时读取。本文件是当前生成与兼容策略：明确不支持的协议不使用；“默认不生成”“支持不统一”属于保守生成边界，不据此声称平台整体不支持。已知限制正常开发直接遵守，只有版本或验证证据变化时复核。以下形态不写入常规 `main.sql`：
+在判断查询能力或处理编译与运行期错误时，以服务端诊断及[目录生成的错误与替代写法](base-sql-errors.generated.md)为事实源。这里保留参数协议和生成原则，不维护第二份函数或语法支持清单。
+
+## 判断与默认路径
+
+原则：先确认业务要保留的结果语义，再选择查询形式。判定时按诊断的位置、语义码和 Catalog 类型定位问题；默认采用生成参考中与当前条件匹配、已有验证的形式，并逐项核对其前提。
+
+例外：目录没有等价 SQL、前提不成立或改写会改变空值、行数及排序时，转到[SQL 外实现放在哪](../SKILL.md#sql-外实现放在哪)选择消费结果的实现位置。单个组合失败不代表组成它的所有能力都不可用；版本或运行环境不一致时，保留诊断和 LogID，先核对事实源。
 
 ## Stored Query 与分页
 
@@ -8,39 +14,16 @@
 - 不把 `OPTION`、`USER`、`CHAT`、`FILE`、`LOCATION`、`URL` 等对象类型声明为业务参数；参数只使用六种基础类型及其一维数组，允许的 null 位置以生成的 Schema 为准。
 - 不通过移除服务端筛选、读取固定前 N 条后在 Page 分页来声称完整分页或全量导出。
 
-## 查询结构与引用
-
-- 查询结构：`INSERT`、`UPDATE`、`DELETE`、`MERGE`、递归 CTE、嵌套 CTE、`LATERAL`，以及右侧会展开为多个 FROM item 的右深嵌套 JOIN。`SELECT *`、`table.*` 默认不生成，保持输出列稳定。`UNION`、`INTERSECT`、`EXCEPT`（可带 `ALL`）可用，但各分支对应列的类型必须完全相同。
-- 无真实表依赖查询：`SELECT 1`、`SELECT $1`、仅 `FROM (SELECT 1) AS x`、仅常量 CTE 或仅 `UNNEST(...)` 的查询。绑定 Base 的 Database Function 必须直接或经由派生表/CTE 引用至少一个 Catalog 真实表，否则运行时可能因查询未引用可路由表而无法确定数据上下文。与 Base 数据无关的常量在 Page/FaaS 中用代码返回。
-- 分组：`GROUP BY` 超过 5 项；需要更多展示列时拆成聚合查询与明细查询后在 Page/FaaS 合并。
-- JOIN：`NATURAL JOIN`、`FULL JOIN ... USING`、JOIN group alias、`LEFT JOIN UNNEST(...)`、`INNER JOIN UNNEST(...)`、含 `GROUP BY` 或聚合函数的派生表 JOIN，以及单条查询超过 10 个 JOIN。`RIGHT JOIN`、`FULL JOIN`、`JOIN ... USING` 可用，常规生成仍优先 `INNER` / `LEFT JOIN`。
-- 列成员：禁止 `table_alias.user_field.id` 和 `"人员字段".id`；UDT 列只使用 PostgreSQL 括号语法 `(table_alias.user_field).id` 或 `("人员字段").id`，`UNNEST` 后的 range alias 成员仍写 `u.id`。
-- 派生对象：把 `USER`、`CHAT`、`FILE`、`URL` 完整对象投影到派生表后再 JOIN。静态校验可能接受该形态，实际执行仍可能返回查询不受支持的错误。
-
-## 类型、表达式与字段操作
-
-- 类型与表达式：`CURRENT_DATE`、`DATE` 类型、`NOW()`，数字转 `TEXT`（`x::text`）、列值转 `TIMESTAMP` / `INTERVAL`（这两种转换只接受字符串字面量），以及固定支持集之外的函数调用。可用的显式转换是 `::int`、`::bigint`、`::float8`、`::numeric`、`::bool`。
-- 非 PostgreSQL 写法不支持：`DATE_FORMAT` 改用 `TO_CHAR(ts, 'YYYY-MM')`，`ENDS_WITH` 改用 `LIKE '%x'`，单参数 `ARRAY_LENGTH(arr)` 改用 `ARRAY_LENGTH(arr, 1)` 或 `CARDINALITY(arr)`，`ROUND(x, n)` 改用 `ROUND(x::numeric, n)`，对小数取模 `x % n` 不支持。
-- `||`、`CONCAT` 两侧都必须是 `TEXT`，不会把数字隐式转为文本；`COALESCE`、`NULLIF`、集合运算只在 `INT` 与 `DOUBLE` 之间统一为 `DOUBLE`，其他类型要先写成同类型。
-- 条件聚合：不要写 `SUM/AVG(CASE WHEN ... THEN 1 ELSE 0 END)`；改用 `SUM(CASE WHEN ... THEN 1.0 ELSE 0.0 END)`。
-- `ILIKE`、`NOT ILIKE`：字段支持不统一，正常查询使用 `LIKE`、`NOT LIKE`。
-- 相关标量子查询在 WHERE、投影、HAVING、ORDER BY 中均不支持；先在派生表按关联键 GROUP BY，再 JOIN 回外层（复杂组合应拆成两个 Database Function）。非相关子查询只使用已校验的形态，不将这一限制泛化为所有子查询都不可用。
-- 子查询表达式：`EXISTS` 在投影、`ORDER BY`、`OR` / `CASE` 下的形态默认不生成；相关子查询的非等值关联（例如 `inner.t < outer.t`）。改用派生表 JOIN，或用单独 Database Function 查询后在 Page/FaaS 合并。`WHERE` 中的 `IN` / `NOT IN` / `EXISTS` 子查询和等值相关子查询可用。
-- 聚合与窗口函数：`PERCENTILE_CONT` / `PERCENTILE_DISC`、`MEDIAN`、`WITHIN GROUP`、聚合内 `ORDER BY`；带 `ORDER BY` 的聚合窗口（逐行累计）、`CURRENT ROW` 或有界的窗口范围、未写整分区范围的 `LAST_VALUE`；`STDDEV` / `VARIANCE` 作为窗口函数。`STDDEV`、`VARIANCE` 作为普通聚合可用，`ROW_NUMBER`、`RANK` 等排名窗口可用。
-- 字符串函数：`LENGTH`、`CHAR_LENGTH`、`LEFT`、`RIGHT`、`SUBSTRING`、`LPAD`、`RPAD`、`TRIM` / `LTRIM` / `RTRIM`、`SPLIT` / `SPLIT_PART`、`REGEXP` / `RLIKE` / `REGEXP_REPLACE`；`STRPOS` / `POSITION` 取具体位置（只能与 0 或 1 比较，用于判断是否包含）。`REPLACE` 可用。
-- 数字函数：`POWER`、`SQRT`、`LOG`、`EXP`、`TRUNC`；`MOD` 的参数不是整数。
-- 日期函数：`DATEDIFF`、`AGE`，以及其他未列入支持集的时间间隔函数；月、季、年单位的 `INTERVAL`；`EXTRACT` / `DATE_PART` 的 `dow`、`doy`、`week`、`quarter`；`DATE_PART('epoch', ts)`（改写为 `EXTRACT(EPOCH FROM ts)`）；`DATE_TRUNC` 截到时、分、秒，以及 `DATE_TRUNC` 结果再参与比较、相减或 `EXTRACT`。
-- `rec_id`、`TEXT`、Phone：顺序比较、`BETWEEN`、`NOT BETWEEN`。文本日期字符串不能用 `<`、`<=`、`>`、`>=` 做范围筛选；需要日期范围时把字段建成 DateTime/TIMESTAMP，或改用 Text 支持的 `=`、`IN`、`LIKE` 后在 Page/FaaS 中判断范围。
-- Checkbox：`IN`、顺序比较、`BETWEEN`、`NOT BETWEEN`。
-- DateTime：`IN`、`NOT IN`、`LIKE`、`ILIKE`。
-- SingleSelect：与 TEXT、`.name` 或 `.id` 等成员标量之间的隐式比较，顺序比较、`BETWEEN`、`LIKE`、`ILIKE`，以及与 `''` 空字符串比较；动态选项名筛选显式使用 `.name` 和 `TEXT` 参数。
-- MultiSelect：`LIKE`。
-
-- 参数化数组成员判断仅支持 `TEXT表达式 = ANY($n)`，且 `$n` 声明为 `TEXT[]`。其他类型先用同类型标量参数展开为等值条件；不要用 `IN ($n)` 展开数组参数。
-
-## 不要误判为整体不支持
-
-- `LIKE $1` 本身可用，参数携带 `%`；复合查询失败时分别检查参数 kind 与错误节点，不因单条失败就判定参数化 `LIMIT/OFFSET` 不支持。
-- OPTION 与同类型 OPTION 可以直接比较；与固定选项名或 `TEXT` 参数比较时必须显式访问 `.name` 或 `.id`。其他 UDT 同样不能和其成员标量隐式比较。
-- 参数化 `LIMIT $n` / `OFFSET $n` 可用；页面输入不能直接决定返回规模，确需动态条数时由 Page/FaaS 先校验为非负整数并限制最大值。
-- 支持集内的 `CASE`、`COALESCE`、`INNER JOIN`、`LEFT JOIN`、`CROSS JOIN`、非递归顶层 CTE、派生标量列、`FROM` 子查询、`WHERE` 中的 `IN` / `EXISTS` 子查询、逗号连接或 `CROSS JOIN` 形态的 `UNNEST`、`TIMESTAMP` 字面量、固定时长的 `INTERVAL`、`EXTRACT`、`TO_CHAR`、时间间隔运算、`ARRAY_AGG`、`STRING_AGG`、排名窗口、`CEIL` 和 `FLOOR` 可以使用；某个复合查询失败时先按错误节点缩小，不把这些能力整体降级。
+## 查询生成边界
+
+默认逐列投影，保持输出 Schema 稳定；连接的每一侧使用明确的表或带别名的派生表，分阶段表达复杂查询。常规生成优先简单连接、顶层查询与带别名的派生表，而不是依靠深层组合表达全部业务逻辑。确需复杂组合时，依据生成参考和目标环境验证决定，而不将生成偏好当作平台能力结论。
+
+Database Function 需要 Catalog 中真实表依赖，以确定数据上下文；与 Base 数据无关的计算按[SQL 外实现放在哪](../SKILL.md#sql-外实现放在哪)处理。动态返回规模由调用方校验为非负整数并限制最大值；服务端资源预算以诊断中的实际限制为准。
+
+## 按位置取值
+
+先明确分区、排序、并列值与空分区的业务含义，再查[生成参考中的修复策略](base-sql-errors.generated.md)。默认只采用满足前提的已验证形式；没有等价形式时沿用[SQL 外实现选择原则](../SKILL.md#sql-外实现放在哪)。
+
+## NULL 与数值边界
+
+改写前明确空值、空集合、数值精度和错误行为是否属于结果契约。默认保留业务所需语义，并按[生成参考的前提与验证说明](base-sql-errors.generated.md)选择修法；防护写法会改变错误行为时，先确认业务接受该变化。需要 SQL 外处理的部分统一按[实现位置原则](../SKILL.md#sql-外实现放在哪)决定，不把截断结果或丢失空值的结果当作等价替代。

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，已包含 % 的关键词" },
@@ -151,7 +166,11 @@ WHERE f."分组" = ANY($1)
 LIMIT 30
 ```
 
-对应参数声明为 `{"kind":"TEXT[]"}`，例如调用 `params: [["重点", "普通"]]`。左侧必须是 `TEXT`，右侧必须是一维 `TEXT[]` 位置参数；其他元素类型的参数化 `ANY` 尚不支持。空数组不会选中记录；整个数组为 `null`，或没有匹配且数组含 `null` 时，表达式为 `null`，`WHERE` 不选中该行。不要把 `IN ($1)` 当作数组展开，也不要对标量字段直接使用 `<@`。显式 `ARRAY[字段] <@ $1` 是数组包含判断，与 `ANY` 在含 `null` 时的布尔结果不同。
+对应参数声明为 `{"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":[]}`。
 
@@ -159,45 +178,24 @@ Database Function 的 `inputSchema` 由 CLI 根据参数顺序与 kind 生成固
 
 ## 查询约束
 
-只编写只读 `SELECT`，页面输入只能进入位置参数。查询使用以下支持集：
+只编写只读 `SELECT`，页面输入只能进入位置参数。具体能力、拒绝条件与修法以[目录生成的错误与替代写法](base-sql-errors.generated.md)为准；生成原则见[能力边界](database-function-limitations.md#查询生成边界)。
 
 - 每条查询的最终查询计划必须引用至少一个 Catalog 中的真实表，用于 Project 执行时选择可路由的表依赖。根 `FROM` 可以是带别名的 `FROM (SELECT ...) AS alias` 派生表，但该派生表或它依赖的 CTE 必须读取真实表。
-- 不要用 Database Function 实现纯常量、纯参数、仅 `FROM (SELECT ...)`、仅 CTE 常量或仅 `UNNEST(...)` 的查询；这些查询没有真实表依赖，会在绑定 Base 的 Validate 或 Execute 阶段失败。与 Base 数据无关的常量在 Page/FaaS 中用代码返回。
-- 查询结构使用显式投影、`WHERE`、`GROUP BY`、`HAVING`、`ORDER BY`；不使用 `SELECT *` 或 `table.*`。`GROUP BY` 最多 5 项。
-- 连接使用 `INNER JOIN`、`LEFT JOIN`、`CROSS JOIN` 或逗号连接。每个 JOIN 的右侧保持为一个表或一个带别名的派生表；`UNNEST` 只能写成逗号连接或 `CROSS JOIN UNNEST(...)`，禁止生成 `LEFT JOIN UNNEST` 或 `INNER JOIN UNNEST`。不要把含 `GROUP BY`、`COUNT`、`SUM`、`AVG`、`MIN` 或 `MAX` 的聚合派生表再 `JOIN` 回主表。单条查询的 JOIN 总数不超过 10。
-- 非递归顶层 CTE 可用；正常建站优先用带别名的 `FROM (SELECT ...) AS alias`，不要写递归 CTE 或嵌套 CTE。
-- 子查询优先作为带别名的 `FROM` 派生表使用，外层通过派生表输出列名引用结果。成员判断可以直接写 `WHERE x IN (SELECT ...)`、`NOT IN`、`EXISTS`、`NOT EXISTS`；相关子查询只使用等值关联（`inner.k = outer.k`）。投影、`ORDER BY`、`OR` 或 `CASE` 之下的标量子查询和 `EXISTS` 默认不生成，需要时拆成派生表或单独查询。
+- 默认逐列投影并使用 `AS snake_case`，保持输出 Schema 稳定；连接的每一侧保持为一个表或带别名的派生表。常规生成优先简单连接、顶层查询和带别名的派生表，复杂组合依据生成参考及验证结果决定。
+- 子查询优先作为带别名的 `FROM` 派生表使用，外层通过输出列名引用结果。需要其他形态时先核对业务语义与生成参考，不把默认生成偏好当作支持清单。
 - 列表使用有界 `LIMIT` 和稳定排序；排序值可能重复时最后按 `rec_id` 排序。不把截断结果的前端分页视为完整分页或全量导出。
-- 返回字段逐列列出并使用 `AS snake_case`。
+- 文本排序与比较按 Base 文本规则：中文按拼音顺序，区分大小写。需要固定业务顺序时用 `CASE` 映射。
+- 产品写入的空字符串读取为 `null`，筛选空文本用 `IS NULL`，不要写 `= ''`。
 - 搜索写 `field LIKE $1`，由参数携带 `%`。
-- `IN (..., NULL)` / `NOT IN (..., NULL)` 保留三值逻辑：未命中但列表含 NULL 时结果为 NULL，WHERE 不选中该行。字符串 `a || b` 任一侧为 NULL 时结果为 NULL；`CONCAT(a,b)` 则跳过 NULL。
-- UDT 只与相同 UDT 类型直接比较；UDT 与成员标量之间没有隐式比较。OPTION 展示名筛选写 `(option_field).name = $n` / `IN (...)`，ID 筛选写 `(option_field).id = $n`；不要写 `option_field = $n`，也不要把 OPTION 或其成员与 `''` 比较。
-- 当前访问者使用 `CURRENT_USER_ID()`，不由页面传入用户 ID。
-- UDT 列成员统一使用 PostgreSQL 复合类型括号语法：无表别名写 `("负责人").id`、`("链接").link`，带表别名写 `(t."负责人").id`。FILE 可写 `("附件").token`、`.name`、`.mime_type`、`.size`；不再使用 `"字段".member` 或 `t."字段".member`。多值对象需要逐元素读取时写 `FROM 表 AS t, UNNEST(t."人员") AS u`，range alias 成员仍写 `u.id`。
-- 不把 `USER`、`CHAT`、`FILE`、`URL` 完整对象投影到派生表后再 JOIN；需要身份过滤时在对象字段所在的真实表查询中直接比较标量子字段。权限关系的实现边界按[权限设计](permission-design.md#读路径database-function-就是策略面)。
-- 集合字段只使用 PostgreSQL 数组运算符：`@>`（包含）、`<@`（被包含）、`&&`（有交集）。不要生成 `ARRAY_CONTAINS` 或 `ARRAY_OVERLAP`。单值关联的 `sqlType` 是 `TEXT`，按文本标量使用 `=`、`IN`、`NOT IN`、`LIKE`、`NOT LIKE`，不要对它使用数组运算符。只有业务本来就是 INNER/逐元素明细语义时，才通过逗号连接或 `CROSS JOIN UNNEST(...)` 展开；展开会过滤空集合主表行，不能替代 `LEFT JOIN UNNEST`。
-- 条件分支：`CASE WHEN bool_expr THEN value ... ELSE value END` 与 `CASE expr WHEN value THEN ... END` 都可用，各分支结果类型一致（`INT` 与 `DOUBLE` 会统一为 `DOUBLE`）。空值兜底可用 `COALESCE(x, fallback)` / `NULLIF`，参数类型必须完全相同，`INT` 与 `DOUBLE` 混用时先写成同类型，例如 `COALESCE(x, 0.0)`。
-- 时间条件使用 Catalog 中确认为 `TIMESTAMP` 的字段和 `TIMESTAMP` 位置参数；当前时间使用 `CURRENT_TIMESTAMP`。查询结果固定为 Base 执行时区下的 `YYYY-MM-DD HH:mm:ss.SSS` 字符串。`EXTRACT(EPOCH FROM timestamp_expr)` 返回保留小数秒的 `DOUBLE`；明确只需整数秒时再写 `::bigint`。不要对 `TEXT` 日期字符串使用顺序比较；若业务必须做日期范围筛选，把 Base 字段建成 DateTime/TIMESTAMP。
-- 时间格式化与分桶：按月、按天展示写 `TO_CHAR(ts, 'YYYY-MM')`，格式只使用 `YYYY`、`MM`、`DD`、`HH24`、`MI`、`SS` 及分隔符；按天、周、月、季、年分组也可写 `DATE_TRUNC('month', ts)`，其结果只用于投影、`GROUP BY`、`ORDER BY`，不再参与比较或运算。时间偏移使用固定时长的 `INTERVAL`（毫秒到周），不使用月、年单位；需要按自然月计算的范围由 Page/FaaS 算好边界后作为 `TIMESTAMP` 参数传入。`EXTRACT` / `DATE_PART` 返回 `DOUBLE`。
-- 聚合函数使用 `COUNT(*)`、`COUNT(expr)`、`SUM(NUMBER)`、`AVG(NUMBER)`、`MIN(scalar)`、`MAX(scalar)`；`ARRAY_AGG(expr)` 可用但默认少生成。聚合结果需要回填到列表行时，拆成列表查询、聚合查询和必要的明细查询，在 Page/FaaS 按稳定业务键合并。
-- 条件计数、通过率等聚合写 `SUM(CASE WHEN cond THEN 1.0 ELSE 0.0 END)`；不要生成 `SUM/AVG(CASE WHEN cond THEN 1 ELSE 0 END)`。行数统计用 `COUNT(*)` / `COUNT(expr)`。
-- 窗口函数可用：`ROW_NUMBER`、`RANK`、`DENSE_RANK`、`PERCENT_RANK`、`CUME_DIST`、`NTILE(n)`、`LAG` / `LEAD`、`FIRST_VALUE`，以及 `COUNT` / `SUM` / `AVG` / `MIN` / `MAX` 作为整个分区的汇总。“每组最新一条”写派生表 `ROW_NUMBER() OVER (PARTITION BY k ORDER BY t DESC, rec_id DESC) AS rn`，外层 `WHERE rn = 1`。窗口只支持整个分区的计算范围：带 `ORDER BY` 的聚合窗口（逐行累计）、`ROWS/RANGE BETWEEN ... CURRENT ROW` 等范围不支持，累计值在 Page/FaaS 中计算；`LAST_VALUE` 只能配合 `ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING`。
-- 字符串函数使用 `LOWER(TEXT)`、`UPPER(TEXT)`、`CONCAT(TEXT, ...)`、`CONCAT_WS(sep, TEXT, ...)`、`REPLACE`、`STARTS_WITH`，拼接也可写 `||`（两侧都是 `TEXT`）。包含判断写 `STRPOS(text, 'x') > 0`，结尾匹配写 `text LIKE '%x'`；`STRPOS` 只能与 0 或 1 比较，不能取具体位置。`LENGTH`、`LEFT`、`RIGHT`、`SUBSTRING`、`LPAD`、`RPAD`、`TRIM` / `LTRIM` / `RTRIM` 和正则函数不支持，长度、截取、去空白、拆分在 Page/FaaS 中处理。
-- 数字计算使用 `+`、`-`、`*`、`/`、`%` / `MOD`（仅整数）、`ABS`、`CEIL`、`FLOOR`、`ROUND(x)`；保留 n 位小数写 `ROUND(x::numeric, n)`，不写 `ROUND(x, n)`。两个整数相除按 PostgreSQL 做整数除法（`7 / 2 = 3`，`COUNT(a) / COUNT(*)` 也是整数除法），比例、通过率写 `COUNT(a)::float8 / COUNT(*)` 或 `SUM(CASE WHEN cond THEN 1.0 ELSE 0.0 END) / COUNT(*)`。
-
-字段筛选使用以下支持形态：
-
-| 字段类型 | 支持的筛选形态 |
-|---|---|
-| `rec_id`、`TEXT`、Phone | `=`、`IN`、`NOT IN`、`LIKE`、`NOT LIKE` |
-| `INT`、`DOUBLE` | `=`、`IN`、`NOT IN`、`<`、`<=`、`>`、`>=`、`BETWEEN` |
-| `BOOL` | `= TRUE`、`= FALSE` |
-| `TIMESTAMP` | 与 `TIMESTAMP` 参数使用 `=`、`!=`、`<`、`<=`、`>`、`>=`、`BETWEEN` |
-| `OPTION` | 显式比较 `.name` 或 `.id`；整个 OPTION 只与 OPTION 比较 |
-| `AUTONUMBER` | `.sequence` 做数值比较、排序和计算；`.number` 做文本展示或等值筛选 |
-| 单值关联（Catalog `sqlType.kind = TEXT`） | 按 `TEXT` 使用 `=`、`IN`、`NOT IN`、`LIKE`、`NOT LIKE` |
-| 多选、多值关联等集合（Catalog `sqlType.kind = ARRAY`） | 只使用 `@>`、`<@`、`&&`；UDT 数组先显式访问 `.id` / `.name` 成员数组 |
-| `USER`、`CHAT`、`FILE`、`URL` | 使用括号语法比较已声明的标量子字段；FILE 为 `.token/.name/.mime_type/.size`，URL 为 `.text/.link`；多值对象只有逐元素明细语义才展开 |
+- 当前访问者使用 `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`。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)，而不是从字段名称推断。示例演示参数和结果消费，不作为完整能力清单。
 
 条件聚合示例：
 
@@ -286,7 +284,7 @@ ORDER BY o."订单号" DESC, o.rec_id DESC
 LIMIT 20
 ```
 
-如果没有真实目标表可 JOIN，又必须保留空集合主表行，拆成主表查询与明细展开查询，并在 Page/FaaS 里按主表 `rec_id` 左合并。拆分后的输入若在开始时已经确定，应并发调用；不要用 `CROSS JOIN UNNEST` 冒充 LEFT 语义。
+如果没有真实目标表可 JOIN，又需要保留空集合主表行，先核对[生成参考中的语义前提](base-sql-errors.generated.md)；没有等价形式时按[SQL 外实现选择原则](../SKILL.md#sql-外实现放在哪)处理。拆分后的输入若在开始时已经确定，应并发调用。
 
 搜索、筛选、关联和聚合尽量在查询中完成。没有关系、不同步消费或需要隔离失败语义的结果集可以拆分；拆分后的输入若在开始时已经确定，应并发调用。
 
@@ -303,7 +301,7 @@ await invokeDatabaseFunction<{ rows: unknown[] }>(
 )
 ```
 
-FaaS handler 内部使用 context，projectId 为当前 应用 的工程常量：
+FaaS handler 内部使用 context，projectId 为当前应用的工程常量：
 
 ```ts
 await context.invokeFunction({
@@ -329,12 +327,11 @@ await context.invokeFunction({
         "record_id": "recxxx",
         "title": "准备评审",
         "status": "待处理",
-        "due_at": 1784311200000
+        "due_at": "2026-07-18 10:00:00.000"
       }
     ],
     "columns": [],
     "row_count": 1,
-    "fxdb_version": "...",
     "log_id": "..."
   },
   "code": 0,

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

@@ -86,7 +86,9 @@ metadata 只声明输入，因此生成文件只约束调用参数。调用结
 
 ## Page 调用
 
-默认 Page 的 `page/index.html` 需要把 `<title>` 设置为本次生成的 应用 名称，不留空。
+外链由页面 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`。悬浮控件仅在正式环境向服务端判定有管理权限的访问者提供「编辑应用」入口。
 
@@ -233,7 +235,7 @@ AI 与 Base 数据组合时保持既有边界：先用 Database Function 读取
 | Page `invokeDatabaseFunction` | 检查一次顶层 `code`，再校验 operation 的 `data`                                   |
 | Database Function             | `data` 为 ResultJSON，包含 rows 等查询信息                                        |
 | FaaS handler                  | 返回 `{data,code,msg}`，data 为业务结果，不再由 Page 二次解包                     |
-| FaaS 下游记录写入             | 检查下游 envelope 和各 batch 的结果语义，见[FaaS 协议](faas.md#应用记录-写入协议) |
+| FaaS 下游记录写入             | 检查下游 envelope 和各 batch 的结果语义，见[FaaS 协议](faas.md#应用记录写入协议) |
 
 不要把 SDK 的 `code===0` 套在 CLI 外层，也不要将 CLI 外层的 data 当作 handler 业务数据。raw API 的命令封装与业务响应按当前 lark-cli reference 分别解析。
 

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

@@ -7,12 +7,14 @@
 - [FaaS 开发](#faas-开发)：目录、handler 与 context
 - [远程调用与写入链路设计](#远程调用与写入链路设计)：依赖、一致性与重试
 - [下游错误归一化](#下游错误归一化)：业务结果与诊断
-- [应用记录 写入协议](#应用记录-写入协议)：请求、响应与部分成功
+- [应用记录写入协议](#应用记录写入协议)：请求、响应与部分成功
 - [创建实现示例](#创建实现示例)：固定操作示例
 - [Base 读写协议](#base-读写协议)：字段格式与集合更新
 
 ## 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",
@@ -106,7 +108,7 @@ function parseCreateTask(value: unknown): CreateTaskInput {
 
 ### 下游错误归一化
 
-FaaS 调用 Base OpenAPI 或其他 应用 Function 时，把当前 operation 的业务结果与下游诊断分开：
+FaaS 调用 Base OpenAPI 或其他应用 Function 时，把当前 operation 的业务结果与下游诊断分开：
 
 - 顶层 `code` 和 `msg` 表达稳定、面向调用方的业务语义，不直接使用上游错误码，也不把技术细节拼进 `msg`。
 - 成功或部分成功的业务结果保留在 `data`；仅在失败或部分成功时，把失败步骤放入 `data.errors`。
@@ -159,7 +161,7 @@ FaaS 使用 `context.fetch` 调用固定的批量写入路由；只使用线上
 |---|---|
 | Online | `https://open.feishu.cn` |
 
-#### 应用记录 写入协议
+#### 应用记录写入协议
 
 FaaS 只使用以下五个固定路由，均为 `POST`，请求头为
 `Content-Type: application/json; charset=utf-8`：
@@ -175,7 +177,7 @@ POST /open-apis/bitable/v1/apps/:base_token/tables/:table_id/remove_attachments
 后两条是附件字段专用的增量路由（注意不在 `records/` 段下）：请求只提交本次增删的
 `file_token`，服务端读取、合并后整格提交，保留读到的其它附件及宽高；不保证原子性或去重。目标环境必须已部署对应 FaaS runtime 和服务端能力，不能仅凭 Skill 存在就判定可用。何时使用增量路由或整格写入，见[文件传输](file-transfer.md#写单元格)。Mutation 的声明、参数和返回结构见[附件写入](mutations.md#附件写入)；这里的原始路由响应不能直接套用于 Page 调用 Mutation。
 
-路径首个参数是 **Base token，不是 应用 appToken**：取 `catalog.json` 中该表的
+路径首个参数是 **Base token，不是应用 appToken**：取 `catalog.json` 中该表的
 `tables[].baseToken`，与 table ID 一起作为 Function 内的工程常量。应用 appToken 只用于
 `context.invokeFunction` 的 `projectId`，两者不要混用。
 
@@ -490,7 +492,7 @@ const result: unknown = await context.invokeFunction({
 
 ## Base 读写协议
 
-同一个字段在创建 schema、Database Function 读取和 FaaS 应用记录 写入时使用三套不同但相关的数据结构。下表只适用于 FaaS 固定 batch 与附件增量路由；开发期 lark-cli 示例数据使用[发布手册中的独立输入契约](release.md#从零建站示例数据验收)。
+同一个字段在创建 schema、Database Function 读取和 FaaS 应用记录写入时使用三套不同但相关的数据结构。下表只适用于 FaaS 固定 batch 与附件增量路由；开发期 lark-cli 示例数据使用[发布手册中的独立输入契约](release.md#从零建站示例数据验收)。
 
 | Field JSON | Database Function 读取 | FaaS 应用记录 CellValue |
 |---|---|---|
@@ -510,7 +512,7 @@ const result: unknown = await context.invokeFunction({
 
 写入时 `null` 清空字段，`[]` 表示空集合，省略字段表示不修改。选项名、用户/群 ID 和关联 record ID 必须来自真实数据。日期与时间的转换见[日期与时区](development.md#日期与时区)。
 
-应用 行写入只使用 [应用记录 写入协议](#应用记录-写入协议)中的固定路由。
+应用行写入只使用 [应用记录写入协议](#应用记录写入协议)中的固定路由。
 
 创建一行或多行时，`create_records` 中每一项是字段到 cell value 的映射，不同记录可以填写不同字段：
 

package/skills/lark-base-database/references/file-transfer.md

@@ -1,6 +1,6 @@
 # 文件传输
 
-实现附件能力时，先读取操作路由和公共约束，再读取当前操作章节。本文说明 Page 如何编排附件流程；基础挂载/移除见[Mutation 附件写入](mutations.md#附件写入)，需业务校验或编排时见[FaaS 与记录协议](faas.md#应用记录-写入协议)，查询类型见[Database Function](database-function.md#查询类型与结果值)。不因仅需展示附件而实现上传或写入功能。
+实现附件能力时，先读取操作路由和公共约束，再读取当前操作章节。本文说明 Page 如何编排附件流程；基础挂载/移除见[Mutation 附件写入](mutations.md#附件写入)，需业务校验或编排时见[FaaS 与记录协议](faas.md#应用记录写入协议)，查询类型见[Database Function](database-function.md#查询类型与结果值)。不因仅需展示附件而实现上传或写入功能。
 
 ## 操作路由
 

package/skills/lark-base-database/references/frontend-design-guide.md

@@ -1,53 +1,183 @@
-# 前端设计入口
+# 前端设计指南
 
-首次实现页面、整体视觉改版或视觉评审前读取本文件，并按下述路由继续读取所需文件。不同运行环境使用同一设计原则。局部视觉修改只读相关章节并沿用现有设计；仅修改数据逻辑时不重做视觉方案。
+用于首次实现页面、视觉改版和设计评审。本文件包含所需设计规则，无需继续读取其他设计文档或组件参考源码。目标是让页面任务清楚、比例协调、控件精致，并通过复用减少搭建工作。
 
-## 边界
+## 1. 按任务范围设计
 
-使用主 Skill 已取得的用户目标、页面任务、数据模式与契约、品牌、现有工程和宿主约束。设计环节不新增提问、问卷、风格选择或确认节点；主 Skill 原有需求澄清、权限、授权、工程、验收与交付行为不变。不因设计分类补造业务目标、页面、指标或操作。
+用户明确要求、正式品牌及现有应用规范优先；starter 占位页、组件库演示页、本轮刚生成的样式和未处理的库默认外观都不算应用规范。使用主流程已经取得的目标、内容、数据模式和工程约束；设计环节不增加需求问答、风格确认或业务规则。
 
-用户明确的设计要求优先于默认审美。修改已有应用时优先保留设计系统。主 Skill 的数据和运行协议、结果真实性、可访问性要求不被场景 Prompt 覆盖；通用工程与安全要求见[工程质量](style-guide.md)，日期值和时区转换见[日期与时区](development.md#日期与时区)。所有场景继承通用规范的数据模式规则；统计口径与业务状态由业务定义决定，设计仅负责表达。
+- 新建或整体改版：确定页面主次、主题、字体和控件基准，直接落实到共享样式及组件。
+- 新增页面：复用应用规范，只决定新页面的内容组织。局部修改只处理受影响的布局或变体；纯数据逻辑修改不触发设计工作。
+- 只实现当前用到的组件和状态。默认不额外创建设计文档、token 清单或选择报告，不为应用预建完整组件库。
 
-## 读取顺序
+## 2. 先组织内容，再决定装饰
 
-1. 新建或整体改版：读取[通用设计规范](design/foundations.md)，识别已有产品身份、全站设计基础和每个页面的主要任务，确定构图与字体。**首次实现或本次调整交互控件时，在决定尺寸、表面、颜色或选择组件库之前，读取[控件设计](design/components.md)、[A/B/C 配方与选择](design/control-recipes.md)及[组件索引](design/components/index.md)。**已有规范可继承，但仍需先读配方核对；本轮刚生成的样式及未经处理的库默认外观不算已有规范。需要新定或调整配色时读[组件主题](design/theme.md)。
-2. 按下表读取当前页面适用的一份主场景规范。一个应用可有多种页面模式；不要把六份场景文件全部加载，也不要把一个页面的主题扩散到全站。
-3. 局部修改：读取通用规范相关章节与受影响的场景章节，继承已有 token、组件和布局；涉及控件外观时同样按第 1 步读取对应组件参考。纯文案或纯数据逻辑修改不触发组件配方读取。
-4. 实现后按[设计自检与按需评审](design/review.md)核对本次修改的代码与已有产物，再回到主 Skill 原有流程。本入口不触发浏览器、逐页遍历、截图或新增运行态验收；用户或主流程要求的专项验收沿用其范围与方法。
+根据当前页面的主要任务分配注意力和空间，不按行业名称套模板：
 
-| 页面主要任务 | 继续读取 | 不要误用到 |
+| 页面任务 | 优先组织 |
+| --- | --- |
+| 业务操作 | 当前对象、必要输入、列表/表格/日历和下一步；统计与说明作辅助 |
+| 数据分析 | 关键读数、趋势与比较、异常及必要明细；范围与单位清楚 |
+| 内容展示 | 品牌、素材和阅读顺序；按内容形成画廊、目录或连续叙事 |
+| 活动参与 | 活动对象、参与路径和当前资格；次数、库存、结果状态与数据模式一致，不能参与、提交中、未知结果、已到账分别表达 |
+| 成果叙事 | 每段有当前数据支持，示例成果不冒充真实业绩；节奏服务叙事，滚动后内容不消失 |
+
+同一应用可包含不同页面。混合或模糊任务按已知内容组织，保持共用视觉语言，不新增分类问答。不同任务的结构差异来自内容，不靠随机换色或固定“四个 KPI + 两张图”制造设计。
+
+业务系统的美感优先来自对齐、文字层级、合适的信息密度和稳定的操作位置。列表、日历、输入等工作区应占据主要空间；普通统计用紧凑摘要，需要处理的异常才局部突出。避免大摘要卡、多行说明和高工具栏把核心内容挤到首屏之外。
+
+下面是内容顺序的起点，只使用任务实际需要的部分：
+
+| 具体页面 | 建议组织 |
+| --- | --- |
+| 列表、台账 | 页头与新增动作 → 搜索/筛选 → 记录与行操作 → 分页；批量动作在选中后突出 |
+| 编辑、设置 | 标题 → 按含义分组的字段 → 保存/取消；短字段有真实关联时并排，长输入独占一行 |
+| 排班、计划 | 紧凑摘要 → 范围与筛选 → 日历/人员网格；避免两排高指标卡把日历推到首屏之外 |
+| 创作、快速记录 | 必要对象选择与输入 → 提交 → 可辨产物；快捷示例用轻量文字行，不逐条套大卡片 |
+| 看板、报告 | 看板便于扫描和比较；报告按结论与证据连续阅读，不因有数字就补齐筛选器与指标卡 |
+
+### 页面默认直接排版，卡片按用途添加
+
+**普通业务页从“一个页面背景 + 透明布局容器”开始。** 列表、编辑、设置、详情、排班与创作页的页头、筛选、字段组、工具栏直接排在页面上；不包整页卡片，也不把每个区块分别包成卡片。页面可直接用白色或协调的浅色背景，不必先铺灰底再垫白板。
+
+- `main`、`section`、Grid/Flex 容器负责宽度、间距与对齐，默认不带卡片底色、圆角、外框或投影。不要把 `Card` 当通用布局组件。白色圆角底板即使无边框、无阴影，也仍是卡片。
+- 卡片只用于确实需要独立边界的内容单元，例如可整体选择的方案、可预览的作品，或需与相邻内容区分的分析模块。**有标题、属于一个分组、包含按钮或需要留白，都不足以成为加卡片的理由。** Dashboard 也不自动给每个模块套卡片。
+- 加卡片前判断：去掉底板后，对象边界、选择关系或阅读是否真的变得不清楚？留白、对齐、局部分隔已能表达时直接排版。这个判断在实现时完成，不输出额外设计报告。
+- 输入框、表格/日历网格、菜单、弹窗和抽屉保留自身必要表面与边界；它们的存在不要求外面再包一层卡片。确需使用的普通内容卡默认无描边、无投影，避免同一内容重复套壳。
+- 新建时替换 starter 的占位外壳；其中 `max-w-2xl rounded-3xl border bg-card … shadow-sm` 等示例组合不作为页面模板沿用。检查已有页面时，删除多余外壳的表面样式及重复内边距，保留必要布局；仅调淡灰边或去掉阴影不算去掉底板。
+
+例如“一个输入区 + 三条快捷示例”：页面下直接排两列，输入保留自己的边界，示例使用文字行与 hover/focus 反馈。不要形成“灰色页面 → 白色大面板 → 输入区卡片 / 示例卡片”的层级。
+
+页头、工具栏和内容共用对齐线，靠面积、字体和间距突出主任务。同排同级、同结构卡片统一列宽、内边距和高度，并对齐标题、数值及动作；用共享槽位处理长标题，不逐卡补 margin 或空话。间距以 4px 基数、8px 节奏为起点，组内小于组间；窄屏堆叠后释放无用留白。图片保持可辨比例，缺图用紧凑回退，不以巨大色块或 emoji 冒充素材；品牌图片、字体或特效加载失败时页面仍可理解与操作。
+
+### 页面尺寸与组件空间不足时的处理
+
+表格、日历和工作台利用扣除导航与边距后的可用宽度；长文、单列表单和专注输入区可局部限宽。检查根节点和父容器的固定宽度、嵌套 `max-width` 与大 padding，避免全屏只铺背景、内容始终挤在中间。
+
+宽屏增加有效列宽、比较空间或合适列数，不等比放大所有控件。**所有区域按自身可用宽度适配**，包括页头、导航、工具栏、表单、卡片、表格、日历和弹层；扣除侧栏、相邻区域及内边距后放不下，就需要重排。宽屏里的窄面板、长文本、项目增多和文字放大也会触发拥挤，不能只处理手机断点。
+
+常规桌面页边距可从 24–32px、窄屏 16px 起；控件组间距约 8px、字段组 16px、区块 24–32px。沿用工程断点，必要时依据容器宽度调整。侧栏后的主区可用 `flex: 1; min-width: 0`，网格用流式轨道；不要用 `100vw` 绕过侧栏和宿主宽度。
+
+先分清哪些内容可收缩、可换行、必须保留可读尺寸。长标题和说明自然换行；图标与短操作标签不被挤成逐字竖排。`min-width: 0` 用于可收缩内容，`nowrap` / `flex-shrink: 0` 只用于需保持完整的局部元素，并给父容器提供换行或折叠方案，不全局套用。文本换行后容器随内容增高；不用缩小字号、固定高度或 `overflow: hidden` 掩盖溢出。次要长文本需要省略时提供可达的完整查看方式，关键金额、日期和操作保持可读。
+
+| 区域 | 空间不足时 |
+| --- | --- |
+| 页头、导航 | 限制品牌与账号区占宽，去掉无用副标题、装饰徽标；导航独占一行或收进菜单，保留当前页标识与所有入口 |
+| 工具栏、筛选、操作组 | 整组换行或堆叠，输入保留可用宽度；主动作可达，次要动作可收进“更多”，筛选条件折叠后仍有状态提示与展开入口 |
+| 表单、卡片、详情 | 减少列数，空间不足时改单列；长字段标签可换行。并排同结构内容用共享槽位对齐，堆叠后按内容自然增高 |
+| 表格、日历、弹层 | 必须保持二维关系时只在所属区域滚动，不挤扁单元内容；弹层受可用宽高限制，长内容内部滚动，关闭和提交动作始终可达 |
+
+响应式处理后不得出现文字重叠、单字竖排、不可达操作或整页意外横向滚动；折叠的业务内容和操作保留可达入口。
+
+## 3. 共用配色与字体
+
+已有规范可用就直接继承。缺少规范时，自主选定一套实际值，写入现有主题、CSS 类或组件变体并在页面调用；不逐页重新取值。
+
+**配色按角色分工**：业务界面以协调的中性面为主体，选择一个主动作色及其前景；错误、警告、成功使用独立语义色。没有品牌色时按产品内容选色，颜色不与 A/B/C 配方绑定。普通指标不一项一种颜色，状态色只标记相关状态或异常，不顺带染满整张卡片；图表需要分类色时保持映射与图例一致。默认浅色，已有主题或明确需求支持暗色时沿用，不为单主题任务新增切换器。
+
+常规业务控件与摘要使用平面样式，不叠加彩色渐变、彩边、投影、光晕和图标底板。图标默认跟随文字或当前状态，不逐项配彩色方块；渐变只在明确的品牌素材或内容表达中局部使用。主动作、真实异常和普通统计有不同强调程度，避免同屏多个高饱和实底按钮争夺注意力。
+
+主次文字在实际背景上均须清楚，浅色标签配清楚的深色文字，亮色按钮不默认配白字。历史、已完成记录仍保留必要可读性，不给整行或整张日历统一降低 opacity。hover、轻量选中面从现有主题派生；把颜色映射到工程的页面/内容/浮层、文字、`input`、`ring` 等角色，Portal 也继承主题。例如选定紫色主动作色后，菜单和选中日期沿用同一色，不为弹层另配一套颜色。主题变量若保存的是 HSL 片段，先拼成完整颜色再赋给组件；弹层经 Portal 挂到 `body` 时，把同一组变量映射到 Portal 根节点，否则弹层会丢失主题。
+
+**字体**：沿用工程可用字体；无品牌字体时采用系统字体栈。下面是常规中文业务页的起点，选定后统一使用，品牌展示可调整整组比例：
+
+| 角色 | 字号/行高 | 字重 |
 | --- | --- | --- |
-| 录入、编辑、处理、审批、排班、批量操作 | [业务操作](design/scenes/business-operations.md) | 纯品牌展示或阅读型报告 |
-| 扫描指标、比较、筛选、监控、定位异常 | [数据看板](design/scenes/dashboard.md) | 主要用于处理记录的列表 |
-| 线性阅读结论及证据、形成分析理解 | [分析报告](design/scenes/analysis-report.md) | 高频筛选监控界面 |
-| 展示业绩、活动成果、讲述数据故事 | [战报](design/scenes/campaign-report.md) | 日常业务操作、审慎分析报告 |
-| 品牌介绍、门户、产品浏览与目录 | [品牌展示](design/scenes/brand-showcase.md) | 因含“产品”二字就套用到管理后台 |
-| 节庆促销、领券、邀请、抽奖等活动参与 | [节庆活动](design/scenes/festive-campaign.md) | 活动配置、营销后台 |
+| 页面标题 | 24/32px | 600 |
+| 区块标题 | 16/24px | 600 |
+| 正文、列表值 | 14/22px | 400 |
+| 标签、表头 | 14/20px | 500 |
+| 辅助文字 | 12/18px | 400 |
+| 指标数值 | 28/36px | 600 |
+
+字重使用字体实际支持的值。正文和必要说明保持对比度，不把所有次要文字降为极浅灰；中文强调不用默认斜体或负字距。数字与单位靠近并对齐，需要比较的数值用 `tabular-nums`，表格数值右对齐。长内容通过换行或布局处理，不逐条缩字。
+
+页面标题与正文同属一套字体，标签和正文可以同字号，通过位置、字重和间距区分。品牌首屏或报告封面可单独扩展较大的标题角色，局部使用，不放大全站导航和控件。长中文标题保留足够行高；数字单位以正文级字号紧邻数值，不靠空格手工对齐。只使用当前可用字体，不为普通工具页增加字体下载步骤。
+
+## 4. 控件采用一套基准
+
+优先复用工程中可靠的组件及主题接口。新建基准时按任务选择下表；目标不明确用 A。应用内保持一个基础配方，必要时增加紧凑/触控尺寸变体，不逐页换配方。
+
+| 规格 | A 常规 | B 密集操作 | C 舒展输入 |
+| --- | --- | --- | --- |
+| 适用 | 常规表单、列表 | 连续处理记录、多筛选、排班 | 少字段、需要较大输入空间 |
+| 单行最小高度 | 36px | 32px | 40px |
+| 控件字号/行高 | 14/20px | 13/20px | 14/20px |
+| 水平内边距 | 12px | 10px | 14px |
+| 圆角 | 6px | 4px | 10px |
+| 输入常态 | 干净表面、1px 轻描边 | 轻填充、透明边框占位 | 轻填充、透明边框占位 |
+
+表中数值是起点，调整时保持整组比例。按钮字重 500、输入值 400；常规图标从 16px 起，图文间距 6px。B 的 13px 只用于密集控件，不把全站正文同步缩小；触控命中区通常至少 44×44px，可扩展命中范围。
+
+- 一个操作组突出当前主动作：主题实底主按钮、轻填充次按钮、透明文字按钮。多个并列动作按当前任务分主次，不给每个动作分配一种鲜艳实底色；危险色仅表示真实危险，发布、生成等普通动作不借用警告色。清空和取消保持较轻层级。
+- **普通按钮和输入默认无投影**，避免灰底、灰边、阴影叠加。输入表面干净、边界可辨，浮层可用必要轻投影。
+- 同密度按钮、输入和选择触发器等高；图标、前后缀与文字分槽对齐。状态变化不改变几何占位或让相邻内容跳动。
+- 普通输入聚焦在原位置用单层细边界表达，通常从 1px 变色开始；不叠加 border、outline 与 ring。组合输入由一个外壳画边界，内部按钮仍有可辨的键盘位置。不得全局移除焦点样式。
+
+采用 `border-box`，透明边框也保留占位；尺寸以最小高度处理，长按钮文字调整操作组或换行，不硬裁。主按钮 hover 轻微改变原有色，次按钮用浅填充与清楚文字，文字按钮保留稳定命中区；不在 hover 时加大字重、描边或阴影。图标按钮居中并提供可访问名称；金额、步进等组合输入由一个外壳容纳前后缀和按钮，不在内部重复画框。
+
+选中、展开和焦点分别表达：已有值不代表持续聚焦，选中项可用轻填充与勾选；键盘移动项有自己的位置提示。loading 时保留按钮宽度并阻止重复提交；disabled 保留标签可读性，不响应操作。清理默认样式应在共享组件内完成，避免每个页面追加一组覆盖类。
+
+## 5. 展开面板也是组件的一部分
+
+下拉、日期、时间与菜单须同时处理触发器和展开面板，面板、选项及选中/禁用/焦点状态继承当前主题，Portal 也不能丢失配色。
+
+**本地、mock、不发布和省开发时间都不能成为使用未经设计的系统弹层的理由。** 除用户明确要求或平台硬约束外，不用浏览器原生 `select`、日期/时间弹层作为可见选择界面。先复用现有可主题化组件；缺失时按工程依赖规则采用成熟实现，不为统一外观重写完整日历、定位或焦点管理内核。补充组件时优先选择与现有 React、Tailwind、CVA 兼容的无头原语或轻量实现（如 Popover、Listbox、日历类组件），不引入第二套完整组件库或另一套 CSS 体系；只加当前用到的组件。默认组件栈与 starter 一致：Radix 无头原语（`@radix-ui/react-popover`、`@radix-ui/react-select`）负责弹层、定位与焦点，`react-day-picker` 负责日历；把工程主题变量映射到这些组件的 className，不为它们另写一套颜色。
+
+| 组件 | 当前用到时保留 |
+| --- | --- |
+| 下拉、多选 | 当前值、选项层级、选中与禁用、必要的搜索/清空；长列表局部滚动，长标签不撑破布局 |
+| 日期、时间 | 清楚的值格式、切换、选中与必要禁用状态；边界、精度、时段来自业务，遵循主流程日期协议 |
+| 菜单、弹窗、抽屉 | 正确定位、关闭与焦点恢复；面板不越出视口，模态交互保留焦点约束 |
+
+### 面板的具体起点
+
+下面的参数用于缺少现成规范时，映射到成熟组件的样式接口，不要求新建实现：
+
+- **下拉与操作菜单**：触发器与输入同高；面板与触发器保持约 4–8px 间距，内边距 4–6px，选项高度从 32–36px 起。单选面板通常不窄于触发器，操作菜单按内容确定宽度；长列表局部滚动并受视口约束。hover 用轻填充，选中可加勾选，禁用项不能点击；空结果给简短提示，不展示虚构选项。
+- **搜索多选**：选项状态与触发器中的值同步；长值可摘要为“已选 N 项”并提供可达的查看/移除入口，不无限增加触发器高度。搜索无匹配与没有任何选项分别表达，清空遵循业务允许的行为。
+- **日期与时间**：单月日历可从约 304–336px 宽、日期格 32–36px 高起，星期与日期七列对齐，月份和前后月操作同排。今天、选中、键盘位置和禁用分别表达；今天不能覆盖选中状态。月份切换、选择和清空真实更新值，范围选择按业务需要采用成熟范围组件。日期值的解析、时区和提交格式遵循[日期与时区](development.md#日期与时区)。固定时段用同主题列表，自由时间输入沿用业务精度，不擅自改成预设时段。
+- **弹窗与抽屉**：标题、内容和动作有共同边距，常规内边距可从 20–24px 起；高度限制在视口内，长内容内部滚动，动作可达。紧凑确认窗不套整页表单宽度，抽屉按详情内容分配宽度；窄屏保留边距或使用合适的全屏变体。
+
+保留成熟组件的键盘和触屏行为。面板内搜索融入面板，不额外画输入框；点击搜索时不新增矩形框、底线或整行填充。鼠标展开默认不自动聚焦搜索；键盘进入仍有局部可辨的焦点提示。
+
+键盘可打开并移动选项、确认选择、用 Escape 关闭，关闭后焦点合理返回；日期支持跨月导航。鼠标点击搜索用插入光标表达位置，键盘进入可用搜索图标旁的短标记提示，不全局删除 `focus-visible`。状态不能仅靠颜色；浮层渲染到页面外时也必须继承主题。
+
+Textarea 设置 `resize: none`，隐藏右下角拖拽斜线；随内容增高至合理上限后内部滚动，预填、粘贴和窄屏换行后仍能编辑完整内容。
+
+字段有明确标签，placeholder 只给示例。错误恢复后去掉相应错误，正常字段不补“已填写”、成功勾选或空帮助行；真实保存与校验结果区别表达。按任务处理加载、空、失败、禁用和提交状态，失败保留输入，提交防重复，不增加假等待或假成功。筛选、分页与切换实际改变内容，数值限制由业务提供。
+
+复选、单选、开关、分段、标签、分页与进度沿用同一文字、颜色和状态规则，不强行使用按钮高度。分段选中用轻底色或底部指示，标签表示状态或筛选条件，不能让每个状态都像按钮；移除动作可辨。进度只在有实际分母时显示，分页反映真实页码与可用动作。
 
-## 模糊与混合场景
+## 6. 文案、身份与内容
 
-按用户明确要求 → 页面主要任务与交互 → 内容和数据形态 → 行业风格选择的顺序判断。行业关键词只辅助视觉方向，不单独决定页面类别。
+页面头默认只放标题、必要范围和动作。只有缺少文字会影响当前选择、输入、读数或后果理解，且标题、控件、图例尚未表达时，才就近补充说明；不要把功能清单搬成副标题。
 
-- 已有系统：继承设计，处理本次范围；不重新随机选择风格。
-- 主要任务明确、分类模糊：自主选择最接近的模式，采用其中有依据的规则。
-- 多任务并存：按主要任务选一份场景，共享全站基础。次任务涉及主场景未覆盖的组织或交互时，仅补读对应章节，如操作页中的筛选图表读看板的图表/交互章节，报告内的编辑表单读业务操作的表单章节；不叠加完整主题。单个数字不触发看板路由，零值、比较与阶段语义直接遵守通用规范。
-- 无法明确匹配或信息不足：只使用通用规范，由已知内容组织布局；不默认套后台、Hero 或看板，不向用户追加设计澄清。
-- 主 Skill 后续获得新信息时，只重新判断受影响部分。
+- 删除“查看各门店班次分布，点击班次查看详情”等操作复述；图例和坐标已说明时间与指标时，不重复补一句。必要的单位、不同统计口径和错误恢复信息保留。
+- 不默认添加“演示环境 / Mock 数据 / 操作仅保存在本地”等横幅或页脚，通常在交付时说明；可能让人误认真实付款、奖励等结果时，就近保留最小辨识信息。不得改写用户录入内容来追求简洁。
+- 正式名称与 Logo 沿用。没有 Logo 的业务工具默认用文字名称，不自动生成“彩色首字方块 + 阴影 + 功能口号”，不另造品牌名。顶部不堆叠技术底座标识、功能口号及无当前任务用途的徽标。功能图标沿用同套风格，AI 功能不默认加机器人或星光。
+- 不为凑版面增加 KPI、素材或进度。图表服务比较：趋势用线、数量用条、精确值用表；零值不画非零长度，缺失不当零，变化须有比较依据。数据模式与统计口径沿用主流程。
 
-例如营销系统：经营总览可走看板，活动配置与线索管理走业务操作，面向参与者的活动页走节庆活动，复盘按阅读目标选分析报告或战报。“营销”不是整站使用节庆主题的理由。
+用删掉说明后的页面检验必要性：字段名和按钮已表达“排班需求 → 生成草稿”，无需再介绍系统如何结合营业时间、休假和工时限制；但限制会导致本次提交失败且界面尚未告知时，应在相关字段旁保留。图表已有“近 7 个月”坐标与系列图例时，删除重复副标题；不同筛选口径仍需标明。同一指标的数值、比例和徽标只保留有额外信息的表达，不为装饰重复强调。按钮直接写“保存修改”“生成草稿”等实际结果，不用泛化的“开启高效体验”。
 
-## 实现链路
+业务内容承担视觉重点：素材预览应能辨认产物，结果缺图时展示名称、类型与真实状态；不要用机器人图标和重复标题填满预览。
 
-页面构图与信息主次 → 应用共用的主题、字体规范 → 本次需要的控件规范 → 共享样式与组件实现 → 页面复用并连接业务能力 → 按 review 自检，再进入主 Skill 的验证与交付。已有应用从现行规范出发，只补足任务涉及的缺项；这是一组实现依赖，不新增主 Skill 的外部流程节点。
+### 业务界面默认静止
 
-“先定规范”要落成可复用的具体选择：文本角色的字号/字重/行高、控件的尺寸/表面/层级/状态，以及页面的宽度、重排和容器规则。普通业务页默认直接在页面上组织标题、工具栏、表单/列表/日历，不先垫一张卡片；布局分组无可见外壳。有独立用途才使用内容卡，普通内容卡默认无描边、无投影，必要输入边界与数据网格独立处理，具体见[直接排版与容器规则](design/composition.md#普通业务页直接排版)。不能只列候选范围或写一句“保持一致”后逐页自由取值。直接使用工程的 token、样式、组件和变体表达；同一应用同一角色复用同一规则，有明确用途时才扩展变体。只定义当前需要的部分，不预建完整设计系统。
+卡片、指标、Logo、AI 入口及告警不使用循环跳动、上下漂浮、缩放呼吸、光晕闪烁或流动渐变；包括 `animate-bounce`、`animate-pulse`、`animate-ping` 及同类自定义动画。告警用稳定的文字、语义色和图标表达。卡片 hover 不抬升或缩放，不给静态内容加数字滚动、逐项入场或装饰轮播。
 
-控件配方按用户要求和已有规范优先，再匹配任务密度；通用或不明确时 A，密集操作优先 B，明确舒展输入优先 C。应用内保持同一基础，配色独立决定，不按页面随机换 A/B/C；具体规格和例外见配方文件。
+动效只响应用户操作，或表示真实进行中的任务。hover/focus、展开和关闭可用短促过渡（约 100–180ms），不改变布局占位；加载指示限定在实际忙碌的按钮或区域，完成或失败后立即停止。首屏内容直接可用，数据刷新保留布局与已有内容，避免整块反复卸载造成闪跳。尊重 `prefers-reduced-motion`，减少动效时仍保留清楚的文字和状态反馈。
 
-任务出现下拉、日期、时间、菜单等控件时，从[组件索引](design/components/index.md)读取对应的 UI/UX 规格；首次实现或替换该类组件时继续读取相应源码和调用示例。已有可靠组件可以适配，不要求复制参考实现或引入另一套库。**本地演示、mock 数据、不发布、工期或实现成本，都不是把这些组件降级为浏览器默认弹层的理由**；除非用户明确要求原生控件，或现有平台有不可绕开的原生约束，否则应使用工程已有可主题化组件，缺失时适配本参考的最小实现。检查真实调用及展开面板，不以只读了配方、只修改按钮或只美化触发器替代完整落实。按需读本次用到的类型，不加载整个组件库。
+## 交付前自检
 
-设计决策直接落实到主题、组件和代码；默认不额外创建设计文件、不输出 Seed 或分类表要求用户确认。只在用户要求方案文档时单独交付。现有组件、包管理器、CSS 体系和平台接入按主 Skill 保留。Page starter 当前使用 React、Tailwind、Radix Slot、CVA 与 lucide-react；优先复用已有组件和交互原语。需要新的可主题化弹层时，可选适合现有工程的无头原语；日期可用成熟日历组件与 Popover 组合。组件参考源码用于适配，不要求复制整套代码或引入第二套完整组件库。
+在主流程已有检查中核对本次涉及的实现：
 
-统一可读性、行为和同站语言，保留任务所需的结构差异。需要构图或组件关系的正向参考时，只读[设计示例](design/examples.md)中对应任务的段落；示例不是固定皮肤或模块清单。副标题默认不生成；品牌标记、控件外观与布局按通用规范落实。实现符合规范与实际美观分别判断，代码自检不等于视觉或运行态通过。
+1. 工作区获得主要空间，摘要紧凑；颜色按动作、状态和数据含义分工，没有逐卡换色或装饰叠加。
+2. 检查本次页面的外壳及区块容器：仅为布局分组添加的卡片表面已移除，包括无边无影的白色圆角底板；必要控件边界保留。
+3. 页面实际使用共用控件及主题；核对页面调用中不再有 `select`、`input[type=date]`、`input[type=time]` 或其封装作为可见选择界面，本地、mock、不发布不构成豁免；确属用户要求或平台硬约束时记录依据。
+4. 没有重复功能说明、装饰性占位 Logo、无用徽标、双重焦点或“已填写”补句。
+5. 根节点及本次涉及的导航、工具栏、表单、内容区和弹层按可用空间收缩或重排；长值、窄容器下不重叠、不逐字竖排、不裁掉必要内容，操作始终可达。
+6. 字体、必要边界、状态和交互清楚，真实内容与长值没有被布局隐藏。
+7. 本次实现的动画和过渡符合上文用途，没有循环跳动、呼吸光晕、hover 位移或重复入场；加载反馈随真实任务结束。
 
-完成设计实现后回到主 Skill 的[发布与交付](release.md)；用户要求专项视觉验收时按[诊断与验收](verification.md)确定范围。此设计入口本身不新增浏览器巡检。
+设计指南不额外启动浏览器巡检、逐页截图或多轮美化流程。检查范围与方法沿用用户任务和主 Skill。结论注明证据层级：实现已核对、运行效果已验证、未验证。截图只证明其对应的页面、尺寸和状态；没有运行证据时不声称交互或视觉通过，也不为消除“未验证”自行扩大检查。有明确问题时修复对应实现，其余工作继续主流程。