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

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

@@ -1,22 +1,22 @@
 # 文件传输
 
-实现附件能力时，先读取操作路由和公共约束，再读取当前操作章节。本文说明 Page 如何编排附件流程；请求体、响应结构和限制的唯一协议说明见[FaaS 与记录协议](faas.md#应用记录-写入协议)，SQL 类型见[SQL Function](sql-function.md#sql-类型与结果值)。不因仅需展示附件而实现上传或写入功能。
+实现附件能力时，先读取操作路由和公共约束，再读取当前操作章节。本文说明 Page 如何编排附件流程；基础挂载/移除见[Mutation 附件写入](mutations.md#附件写入)，需业务校验或编排时见[FaaS 与记录协议](faas.md#应用记录-写入协议)，查询类型见[Database Function](database-function.md#查询类型与结果值)。不因仅需展示附件而实现上传或写入功能。
 
 ## 操作路由
 
 | 目标 | 入口 | 必读章节 |
 | --- | --- | --- |
 | 上传文件字节 | `siteRuntime.uploadAttachment()` | [上传](#上传) |
-| 展示缩略图或大图 | `buildAttachmentCoverUrl(context, ref)` | [展示与下载](#展示与下载) |
+| 展示缩略图或大图 | `fetchAttachmentCover(ref, size)` | [展示与下载](#展示与下载) |
 | 下载原文件 | `fetchAttachmentDownloadUrl(context, ref)` | [展示与下载](#展示与下载) |
-| 将新文件挂载到单元格或移除引用 | Page 调 FaaS，使用附件增量路由 | [写单元格](#写单元格)和 FaaS 协议 |
-| 写入超时、结果不明 | 保留 token，通过固定 SQL 有界核对 | [超时与结果未知](#超时与结果未知) |
+| 将新文件挂载到单元格或移除引用 | 基础写入用 Mutation；业务校验与编排用 FaaS | [写单元格](#写单元格)和 [Mutation 附件写入](mutations.md#附件写入) |
+| 写入超时、结果不明 | 保留 token，通过固定 Database Function 有界核对 | [超时与结果未知](#超时与结果未知) |
 
 ## 公共约束
 
 - `file_token` 是附件资源标识，不是可直接访问的 URL，也不是登录凭证。临时下载链接携带授权信息，不持久化、不记录到日志或作为长期公开链接。
-- 表、字段 ID 来自 Catalog；已有附件的记录 ID、FILE.id（即 file_token）来自 SQL。上传成功返回的新 fileToken 供后续挂载使用。不能通过伪造位置声明获取其他附件。
-- 上传依赖父页面 `attachment.upload`；挂载还依赖目标环境的 FaaS runtime 和服务端增量路由。更新 starter 不证明平台已开通。能力不具备时报告具体限制，按用户决定调整需求，不猜网关或回退为旧列表整格覆盖。
+- 表、字段 ID 来自 Catalog；已有附件的记录 ID、FILE.token 来自 Database Function 查询结果。上传成功返回的新 fileToken 供后续挂载使用。不能通过伪造位置声明获取其他附件。
+- 上传依赖父页面 `attachment.upload`；Mutation 挂载依赖目标环境的附件操作和服务端增量路由，FaaS 挂载依赖对应 runtime 和服务端增量路由。更新 starter 不证明平台已开通。能力不具备时报告具体限制，按用户决定调整需求，不猜网关或回退为旧列表整格覆盖。
 - 上传校验应用权限与绑定关系。不要要求访客取得底层 Base 权限来绕过应用链路问题。
 - 上传成功只证明文件字节已提交，不证明附件已挂载；移除只删除单元格引用，不删除云盘文件，也不承诺释放 Base 附件计数。
 
@@ -33,7 +33,7 @@ baseToken/tableId 取自 Catalog；file 必须是 File。不传 fieldId，目标
 
 ### 图片宽高
 
-图片上传前从本地 File 解码读取原始宽高，不依赖上传结果中的可选 width/height，也不使用预览元素的 CSS 尺寸。服务端不会补齐省略的宽高，SQL 也不返回旧图片宽高。
+图片上传前从本地 File 解码读取原始宽高，不依赖上传结果中的可选 width/height，也不使用预览元素的 CSS 尺寸。服务端不会补齐省略的宽高，Database Function 也不返回旧图片宽高。
 
 ```ts
 async function readImageDimensions(file: File) {
@@ -56,7 +56,7 @@ async function readImageDimensions(file: File) {
 const dimensions = await readImageDimensions(file)
 const uploaded = await siteRuntime.uploadAttachment({ baseToken, tableId, file, onProgress })
 const newAttachment = { file_token: uploaded.fileToken, ...dimensions }
-// 经业务 FaaS 挂载 newAttachment，不合并页面旧附件列表。
+// 基础写入：新建记录时随 create Mutation 提交，已有记录通过 append_attachments 追加。
 ```
 
 非图片省略宽高；类型未知时先识别或提示用户，不能把可能的图片直接当非图片。图片解码失败或尺寸无效时停止上传和挂载，不伪造尺寸。
@@ -78,22 +78,22 @@ const context = await resolveDatabaseContext()
 const ref = { tableId, fieldId, recordId, fileToken }
 ```
 
-helper 负责生成 extra，其中 baseAppToken 将鉴权对象指向应用。业务代码不手工拼接 extra，也不移除该字段来尝试底表鉴权。不存在、错位或无权限的附件可能返回错误或无可展示内容。
+封面和下载 helper 负责生成 extra，其中 siteToken 和 siteEnv 指定应用及 Preview/正式环境，宿主校验其与当前页面一致。业务代码不手工拼接 extra，也不移除该字段来尝试底表鉴权。不存在、错位或无权限的附件可能返回错误或无可展示内容。
 
 | 操作 | helper 与结果 | 前置条件 |
 | --- | --- | --- |
-| 封面/大图 | `buildAttachmentCoverUrl(context, ref, 360)` 返回绝对 URL，交给 img | 需要有效应用、附件坐标和 gatewayOrigin；无法构造时返回空字符串 |
+| 封面/大图 | `await fetchAttachmentCover(ref, 360)` 返回 Blob | 需要支持 HTTP 二进制响应的宿主和完整附件坐标；不需要 iframe 推断 gatewayOrigin |
 | 原文件下载 | `await fetchAttachmentDownloadUrl(context, ref)` 返回临时链接 | 通过父页面代理取链接，不依赖封面 helper 的 gatewayOrigin |
 
-不能因为封面 URL 为空就禁用下载。下载失败应显示 helper 返回的错误；任何动作入口都不能静默无响应。
+不能因为封面加载失败就禁用下载。下载失败应显示 helper 返回的错误；任何动作入口都不能静默无响应。
 
-### 封面与重试
+### 缩略图和点击大图
 
-封面尺寸取服务端档位 120/360/720/1280，默认 360；列表可用 360，大图用 1280。除用户明确要求原文件画质外，展示不调用下载端点获取大体积原文件。
+基础取图入口是 starter `src/lib/database-runtime.ts` 的 `fetchAttachmentCover(ref, size, { signal })`，返回 Blob。图片由宿主以当前访问者身份请求，经通用 HTTP bridge 返回。调用方用 `URL.createObjectURL(blob)` 展示，替换或卸载时取消请求并 revoke。`size` 控制封面请求尺寸，默认 360、最大 1280，可按展示需求调整；页面显示尺寸由样式决定，大图仍是封面。
 
-封面异步生成；202/90002006 或 img 的 onError 不足以判定文件类型不支持。采用占位图或文件名，并按[工程质量](style-guide.md)设置有限重试：限定次数或总时长，仅在组件可见且仍挂载时调度，替换附件或卸载时取消；超过预算保留手动重试入口。具体预算由体验需求决定，不把某次样本耗时写成平台保证。
+React 页面可选用 `src/lib/attachment-image.tsx` 的 `AttachmentImage`。它内部调用同一取图函数，封装可见时加载、取消请求、手动重试和 Blob URL 释放；例如预览使用 `<AttachmentImage attachment={ref} alt={name} size={1280} />`。需要自定义展示时直接使用取图函数即可。
 
-重试封面可更新 cache-bust 参数，不重新上传文件。网关 origin 来自 runtime 的 ancestorOrigins/referrer 解析，无法取得时不猜域名。支持格式、生成耗时和有效期以目标环境表现为准。
+封面异步生成，保留占位和失败状态；自动重试按[工程质量](style-guide.md)设置有限预算，替换或卸载时取消。遇到 `HTTP_RESPONSE_TYPE_UNSUPPORTED` 或 `INVALID_HTTP_URL` 时，先核对是否使用当前 starter 的 helper、完整附件坐标和匹配的依赖版本。修正本地接入后重新构建并发布；接入正确但仍报错时，保留错误码与请求标识，报告平台能力限制并向平台支持反馈，不自行猜测域名或绕过代理。
 
 ### 原文件下载
 
@@ -103,21 +103,21 @@ helper 负责生成 extra，其中 baseAppToken 将鉴权对象指向应用。
 
 ## 写单元格
 
-普通追加/移除通过业务 FaaS 调用 append_attachments/remove_attachments，路径、JSON 和响应见[FaaS 协议](faas.md#应用记录-写入协议)。保持以下操作语义：
+按[写入方式选择](mutations.md#写入方式选择)确定是否需要 FaaS；基础追加/移除通过 `invokeDatabaseFunction` 调用 `append_attachments` / `remove_attachments` Mutation。声明、Page 参数和完整响应见[Mutation 附件写入](mutations.md#附件写入)。保持以下操作语义：
 
-- 追加只提交本次新增项；图片附带本地读取的宽高。正常追加不要求先查询旧列表，不依赖 SQL 重建旧图宽高。
-- 移除只提交目标 file_token，按 token 删除全部同名引用；SQL 的 id 须映射为 file_token。不要直接提交 SQL 返回对象。
-- 请求前过滤空字段数组和空记录映射，全空则本地短路。不能假定 append 空数组无副作用。
-- 成功后使用 data.attachments 更新本次操作的本地状态，不用立即 SQL 回读覆盖它；从库可能尚未同步。业务结果仍需处理 ignored_fields。
-- batch_update 仅用于明确的整格置空或重设；重设旧图无法从 SQL 补回宽高，不用于普通追加/移除。
+- 追加只提交本次新增项；图片附带本地读取的宽高。正常追加不要求先查询旧列表，不依赖 Database Function 重建旧图宽高。
+- 移除只提交目标 file_token，按 token 删除全部同名引用；Database Function 返回附件对象中的 `token`，调用 Mutation 时将该值填入 `file_token`。不要直接提交查询返回对象。
+- 没有新增或移除项时本地短路，批量只提交有改动的参数组。Mutation 拒绝空附件列表；FaaS 直调仍需过滤空字段数组和空记录映射，不能假定 append 空数组无副作用。
+- Mutation 成功后用 `data.records` 中对应记录/字段的完整附件列表更新本地状态，不立即调用 Database Function 回读覆盖它；查询结果可能尚未同步。FaaS 直调使用 `data.attachments`，并处理 `ignored_fields`；不要混用两种返回结构。
+- 新记录可通过 create Mutation 随记录提交附件；update 的整格写入只用于明确的替换或 clear 清空。重设旧图无法从 Database Function 补回宽高，不用于普通追加/移除。
 
-服务端仍是读取、合并、写回，不保证原子性、去重或并发不丢项。页面按单元格串行可减少本页交错，但不能保护多个访问者同时写入；不同记录或字段不应共用全局上传锁。严格并发一致性的需求须说明当前能力限制，不通过固定等待时间承诺安全。
+附件增量写入不保证原子性、去重或并发不丢项。页面按单元格串行可减少本页交错，但不能保护多个访问者同时写入；不同记录或字段不应共用全局上传锁。严格并发一致性的需求须说明当前能力限制，不通过固定等待时间承诺安全。
 
 ### 超时与结果未知
 
 页面区分上传中、已上传待挂载、挂载结果待确认，保留已有 fileToken 和图片宽高。append 与上传都不幂等，结果未知时不自动重提或重新上传。
 
-1. 使用固定 SQL Function 按记录核对目标 token。未立即读到不证明上一请求失败；读到也不保证不会被并发写入覆盖。
+1. 使用固定 Database Function 按记录核对目标 token。未立即读到不证明上一请求失败；读到也不保证不会被并发写入覆盖。
 2. 延迟后进行有限次数或有限时长的只读核对。仍不能确认时保留待确认状态并提示用户，不拿旧列表整格覆盖。
 3. 后续明确需要补挂时复用已有 token 与宽高，只处理已核对的目标，并说明可能重复引用和并发覆盖。没有可靠去重原语时不承诺只执行一次。
 
@@ -126,9 +126,9 @@ helper 负责生成 extra，其中 baseAppToken 将鉴权对象指向应用。
 | 条件/错误 | 处理 |
 | --- | --- |
 | INVALID_ATTACHMENT_TARGET | 区分文件类型/大小与应用绑定配置；修正对应输入，不重复发送同一错误请求 |
-| ATTACHMENT_UNAVAILABLE | 父页面不支持上传，报告环境能力限制 |
+| ATTACHMENT_UNAVAILABLE | 父页面不支持当前附件接口，报告环境能力限制 |
 | ATTACHMENT_UPLOAD_FAILED / STALLED | 显示进度或网络问题；检查是否已上传，不自动重传 |
-| 位置不匹配、403 或没有封面 | 核对坐标与应用鉴权；封面未就绪按有限重试处理 |
+| 位置不匹配或没有封面 | 核对坐标与应用鉴权；封面未就绪按有限重试处理 |
 | 下载操作无响应 | 核对代理错误及 iframe 下载设置；不因缺 gatewayOrigin 直接禁用下载 |
 | 单元格已满或出现 ignored_fields | 不报告全部成功；指出未写入项及原因 |
 | property.capture 字段 | 上传挂载可能被忽略；读取和移除按对应协议处理 |

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

@@ -1,97 +1,53 @@
-# 前端设计风格指导
+# 前端设计入口
 
-首次实现页面、整体视觉改版或视觉评审前完整读取；局部视觉修改读取相关章节并沿用现有设计系统。本文统一适用于一方托管和三方搭建，不依赖宿主身份或构建期注入。只修改数据逻辑时不重做视觉方案。
+首次实现页面、整体视觉改版或视觉评审前读取本文件，并按下述路由继续读取所需文件。不同运行环境使用同一设计原则。局部视觉修改只读相关章节并沿用现有设计；仅修改数据逻辑时不重做视觉方案。
 
-目标是让界面适合具体业务，并以一致的排版、组件、状态反馈和细节保持产品质量。用户已有品牌、设计稿与明确偏好优先；可访问性与安全要求见[工程质量](style-guide.md)。下列数值与选型是默认出发点，不是平台限制。
+## 边界
 
-## 设计方案
+使用主 Skill 已取得的用户目标、页面任务、数据模式与契约、品牌、现有工程和宿主约束。设计环节不新增提问、问卷、风格选择或确认节点；主 Skill 原有需求澄清、权限、授权、工程、验收与交付行为不变。不因设计分类补造业务目标、页面、指标或操作。
 
-先在内部规划中确定使用者、主要任务与业务特征，再作以下决策；默认不单独创建设计文档，用户要求时提供：
+用户明确的设计要求优先于默认审美。修改已有应用时优先保留设计系统。主 Skill 的数据和运行协议、结果真实性、可访问性要求不被场景 Prompt 覆盖；通用工程与安全要求见[工程质量](style-guide.md)，日期值和时区转换见[日期与时区](development.md#日期与时区)。所有场景继承通用规范的数据模式规则；统计口径与业务状态由业务定义决定，设计仅负责表达。
 
-1. **色彩**：定义页面背景、内容表面、主次文本、边框、品牌色和独立的成功/警告/危险色。以命名设计变量维护中性色阶，避免逐组件取色。
-2. **排版**：确定标题、正文、辅助文字的字号、字重、行高与数字格式。
-3. **布局与密度**：高频列表与工作台优先信息效率，表单与登记页优先阅读和输入空间；相同任务采用一致密度。
-4. **业务辨识度**：用业务内容、导航结构、品牌色或关键状态表达建立特征。需要视觉强调时集中在少数位置，不让装饰占用核心操作区域。
-5. **交互与动效**：确定控件状态、焦点、过渡时长和响应式策略，落实为可复用组件与设计变量。
+## 读取顺序
 
-方案应能解释如何服务当前任务。不要为了与其他应用不同而牺牲已有用户习惯，也不要仅替换 starter 文案就完成视觉交付。
+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 原有流程。本入口不触发浏览器、逐页遍历、截图或新增运行态验收；用户或主流程要求的专项验收沿用其范围与方法。
 
-## 场景与布局
-
-| 页面任务 | 布局重点 | 默认视觉取向 |
+| 页面主要任务 | 继续读取 | 不要误用到 |
 | --- | --- | --- |
-| 工作台 | 待办与关键结论前置，再展示快捷入口和动态 | 清晰、紧凑、可预期 |
-| 列表与台账 | 搜索筛选 → 数据 → 行内或批量动作 | 统一列对齐与行密度 |
-| 表单与登记 | 语义分组或分步，主操作始终可达 | 单列优先，适当留白 |
-| 详情 | 标题、状态、关键属性 → 分区内容 → 关联数据 | 稳定层级与对象定位 |
-| 看板与报表 | 指标结论 → 趋势与对比 → 明细 | 以读数为主，主题按使用环境选择 |
-| 门户与展示 | 品牌和核心内容前置 | 可用较大的标题、留白与非对称布局 |
-
-工具页不默认使用大幅 hero、装饰插画或营销式首屏。并列内容可用网格，顺序内容用步骤或时间轴，层级内容用分组；结构必须反映真实信息关系，不把所有区块放入同一种白色阴影卡片。
-
-## 排版与间距
-
-以下作为默认层级，按用户品牌、中文可读性及目标设备调整：
-
-| 层级 | 字号 | 字重 | 适用 |
-| --- | --- | --- | --- |
-| Display | 32–56px，使用 clamp | 700–800 | 表达页首屏或关键数字 |
-| Heading | 20–28px | 600–700 | 页面和区块标题 |
-| Card title | 15–17px | 600 | 卡片与表单分组 |
-| Body | 13–15px | 400 | 表格和正文；长正文可增大 |
-| Caption | 12px 起 | 400–500 | 辅助说明，不承载唯一关键信息 |
-
-- 层级由字号、字重、对比度和间距共同形成，不能只放大标题。行高以内容可读性为准。
-- 中文强调使用字重，不默认使用斜体或负字距。金额、编号和统计数字使用 `font-variant-numeric: tabular-nums`。
-- 默认系统字体栈；特殊字体经允许的依赖或资源打包进入产物，仅加载所需字重，不引入运行时外链字体 CDN。
-- 间距以 4px 基数和 8px 节奏组织；组间距大于组内间距。表格行高可从紧凑 40px、常规 48px、舒展 56px 选择，相同场景一致。
-
-## 表格、表单与按钮
-
-- 表格文本左对齐、数字右对齐；状态使用文字与语义色，不能只用颜色区分。操作列置于行尾，次要动作按需收纳。
-- 空值表达一致，例如“-”；长内容截断时提供键盘和触屏可用的完整查看方式，不仅依赖 hover。
-- 行分隔使用细线或斑马纹，避免冗余边框；列表同时设计加载、空、失败、部分数据和无权限状态。
-- 表单标签明确且与控件关联，占位符只提供示例。必填与错误提示一致，提交失败定位首个错误字段。
-- 主按钮、次按钮与文字按钮层级清晰，同一操作区域突出一个主要动作；危险动作写明对象和后果，不作为默认焦点。
-- 提交期间阻止重复操作；成功反馈对应真实业务结果，部分成功明确哪些操作需要继续处理。
-
-## 控件与组件体系
-
-控件应纳入本应用设计变量和状态体系，同时优先保留可靠交互与可访问性：
+| 录入、编辑、处理、审批、排班、批量操作 | [业务操作](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) | 活动配置、营销后台 |
 
-- 文本输入、textarea、checkbox、radio、range 等可用原生元素配统一边框、焦点和 accent-color。
-- 下拉、菜单、弹窗、Tooltip 等优先复用 starter 的组件模式，按需使用 Radix 无头原语、Tailwind token 与 CVA 变体。日期选择可使用 react-day-picker 配 Popover，不手写复杂日历或定位内核。
-- 移动端原生日期选择器等有明确体验收益时可以保留；同类使用场景保持一致。不要为视觉统一损害键盘或触屏体验。
-- 修改既有项目沿用组件库和主题；新建默认不为单个控件引入第二套完整组件库。确需替换时统一全站主题和设计变量。
-- 图标沿用 starter 的 lucide-react 线性风格，不混用不一致的图标库与 emoji。
+## 模糊与混合场景
 
-## 设计变量与主题
+按用户明确要求 → 页面主要任务与交互 → 内容和数据形态 → 行业风格选择的顺序判断。行业关键词只辅助视觉方向，不单独决定页面类别。
 
-颜色、字体层级、间距、圆角、阴影、控件高度、过渡时长收敛为 CSS variables 或现有主题 token，组件复用同一套值。禁止为了微小局部差异不断增加近似值。
+- 已有系统：继承设计，处理本次范围；不重新随机选择风格。
+- 主要任务明确、分类模糊：自主选择最接近的模式，采用其中有依据的规则。
+- 多任务并存：按主要任务选一份场景，共享全站基础。次任务涉及主场景未覆盖的组织或交互时，仅补读对应章节，如操作页中的筛选图表读看板的图表/交互章节，报告内的编辑表单读业务操作的表单章节；不叠加完整主题。单个数字不触发看板路由，零值、比较与阶段语义直接遵守通用规范。
+- 无法明确匹配或信息不足：只使用通用规范，由已知内容组织布局；不默认套后台、Hero 或看板，不向用户追加设计澄清。
+- 主 Skill 后续获得新信息时，只重新判断受影响部分。
 
-默认浅色主题；用户品牌或使用环境需要暗色时在 token 层实现。仅要求一种主题时不额外实现主题切换。确保文本、边框、焦点和各类状态在所选主题下可辨认；状态色不挪作无关装饰。
+例如营销系统：经营总览可走看板，活动配置与线索管理走业务操作，面向参与者的活动页走节庆活动，复盘按阅读目标选分析报告或战报。“营销”不是整站使用节庆主题的理由。
 
-## 响应式与动效
+## 实现链路
 
-- 保留 viewport 配置，使用流式宽度、max-width、fr、min 与 clamp，避免固定页面宽度。
-- 窄屏重新组织网格和导航；宽表放入独立横向滚动区域，页面整体不溢出。
-- 触控目标默认至少 44×44px；固定控件考虑安全区，hover 有触屏替代反馈。
-- 桌面高频业务保持信息密度，移动端保证核心任务可完成；不能仅缩小桌面页面。
-- 工具页面动效用于反馈和状态过渡，默认 150–250ms；表达页才按内容需要增加入场编排。统一缓动并尊重 prefers-reduced-motion。
+页面构图与信息主次 → 应用共用的主题、字体规范 → 本次需要的控件规范 → 共享样式与组件实现 → 页面复用并连接业务能力 → 按 review 自检，再进入主 Skill 的验证与交付。已有应用从现行规范出发，只补足任务涉及的缺项；这是一组实现依赖，不新增主 Skill 的外部流程节点。
 
-## 界面文案
+“先定规范”要落成可复用的具体选择：文本角色的字号/字重/行高、控件的尺寸/表面/层级/状态，以及页面的宽度、重排和容器规则。普通业务页默认直接在页面上组织标题、工具栏、表单/列表/日历，不先垫一张卡片；布局分组无可见外壳。有独立用途才使用内容卡，普通内容卡默认无描边、无投影，必要输入边界与数据网格独立处理，具体见[直接排版与容器规则](design/composition.md#普通业务页直接排版)。不能只列候选范围或写一句“保持一致”后逐页自由取值。直接使用工程的 token、样式、组件和变体表达；同一应用同一角色复用同一规则，有明确用途时才扩展变体。只定义当前需要的部分，不预建完整设计系统。
 
-按钮描述动作结果，例如“保存修改”“删除 3 条记录”。同一概念和动作全站同名。空状态说明内容和下一步，错误说明可恢复动作，不使用只有“出错了”的提示。
+控件配方按用户要求和已有规范优先，再匹配任务密度；通用或不明确时 A，密集操作优先 B，明确舒展输入优先 C。应用内保持同一基础，配色独立决定，不按页面随机换 A/B/C；具体规格和例外见配方文件。
 
-金额、日期和数字格式按业务及目标时区统一；不同时间精度有实际用途时可采用对应格式。页面不出现 SDK、SQL、binding、发布环境等与使用者任务无关的内部实现信息。避免营销口号、填充词、starter 残留文案及假成功状态。
+任务出现下拉、日期、时间、菜单等控件时，从[组件索引](design/components/index.md)读取对应的 UI/UX 规格；首次实现或替换该类组件时继续读取相应源码和调用示例。已有可靠组件可以适配，不要求复制参考实现或引入另一套库。**本地演示、mock 数据、不发布、工期或实现成本，都不是把这些组件降级为浏览器默认弹层的理由**；除非用户明确要求原生控件，或现有平台有不可绕开的原生约束，否则应使用工程已有可主题化组件，缺失时适配本参考的最小实现。检查真实调用及展开面板，不以只读了配方、只修改按钮或只美化触发器替代完整落实。按需读本次用到的类型，不加载整个组件库。
 
-## 交付前自检
+设计决策直接落实到主题、组件和代码；默认不额外创建设计文件、不输出 Seed 或分类表要求用户确认。只在用户要求方案文档时单独交付。现有组件、包管理器、CSS 体系和平台接入按主 Skill 保留。Page starter 当前使用 React、Tailwind、Radix Slot、CVA 与 lucide-react；优先复用已有组件和交互原语。需要新的可主题化弹层时，可选适合现有工程的无头原语；日期可用成熟日历组件与 Popover 组合。组件参考源码用于适配，不要求复制整套代码或引入第二套完整组件库。
 
-- 设计方案能在代码中对应到实际 token、排版、密度与组件，而不是仅有文字说明。
-- 首屏内容和主要动作适合当前业务，无无关 hero、装饰卡片或过量渐变。
-- 表格对齐、表单错误、按钮层级和日期数字格式一致；图表选择与比较任务匹配，避免无必要的 3D、仪表盘或过多饼图分类。
-- 焦点、键盘、弹窗、空态、错误和部分成功均有实现；关键文本对比度充分。
-- 桌面和窄屏核心任务可达，无页面级横向溢出；减少动效设置有效。
-- 用户提供的品牌和已有界面得到保留。未做浏览器验证的项目明确列为未验证，不将静态自检报告为真实交互通过。
+统一可读性、行为和同站语言，保留任务所需的结构差异。需要构图或组件关系的正向参考时，只读[设计示例](design/examples.md)中对应任务的段落；示例不是固定皮肤或模块清单。副标题默认不生成；品牌标记、控件外观与布局按通用规范落实。实现符合规范与实际美观分别判断，代码自检不等于视觉或运行态通过。
 
-完成实现后进入[发布与交付](release.md)；用户要求视觉验收时使用[诊断与验收](verification.md)规定的检查范围。
+完成设计实现后回到主 Skill 的[发布与交付](release.md)；用户要求专项视觉验收时按[诊断与验收](verification.md)确定范围。此设计入口本身不新增浏览器巡检。

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

@@ -0,0 +1,295 @@
+# Mutation Function
+
+Mutation 是固定单表的基础写入声明。读取继续用 Database Function；写入使用 `mutations/<functionId>/{meta.json,spec.json}`，Page 只传位置参数。表、可写字段、固定值和记录 ID 参数来源由发布者声明，不能由调用者扩展。写入方式按下节选择。
+
+CLI 的 `deploy` 自动校验、打包并注册声明，`pull` 恢复 `mutations/`。全部类型共享 Function ID 和最多 200 个 Function 的限制。保存成功不代表写入一定成功，调用后仍需检查错误与部分完成结果。
+
+## 写入方式选择
+
+**读取使用 Database Function；声明能完整表达的普通单表创建、按记录 ID 更新和删除（含批量及附件写入）优先使用 Mutation；需要声明之外的服务端业务校验、计算或编排时使用 FaaS。按业务动作选择，已有 FaaS 无需主动迁移。**
+
+| 业务要求 | 选择 |
+| --- | --- |
+| 固定单表、固定字段的创建，或按记录 ID 更新/删除；只需类型、缺失/null、长度、列表数量等声明内约束 | Mutation；支持一次改多个字段、批量记录和附件增量 |
+| 需要校验记录归属、当前状态、查重、非空白等业务规则，或基于旧值计算、跨表写入、多个业务写入存在依赖 | FaaS；按 [FaaS 协议](faas.md)实现 |
+
+例如修改指定任务的标题和状态、批量设置为完成属于基础写入；“只能修改自己的草稿”需要 FaaS。具体参数限制见[声明与参数](#声明与参数)。需要 FaaS 校验的动作不能另行暴露可绕过校验的 Mutation，也不经 FaaS 调用 Mutation。“上传文件 → 取得 token → Mutation 挂载”属于页面附件流程，本身不需要 FaaS；如需服务端业务校验再按上述边界选择。两条链路均不额外提供事务或 CAS。
+
+## 声明与参数
+
+`meta.json`：
+
+```json
+{"name":"创建任务","description":"提交一条待处理任务"}
+```
+
+Mutation 不声明角色；调用仍需通过应用统一准入。记录 ID 仅限定操作范围，不代表记录归属或行权限校验。
+
+`spec.json` 中 `param` 是 **从 1 开始的位置编号**。记录条件的 `param: 2` 表示从第 2 个参数读取 ID，和“修改两条”没有关系。目标参数必须是必填的单值 `RECORD_ID`，不能设置 `list: true`；多条记录通过 `batch` 逐条传参。
+
+支持 `TEXT / INT / DOUBLE / BOOL / TIMESTAMP / DURATION / USER_ID / GROUP_ID / RECORD_ID / ATTACHMENT`；`required` 默认 true，`list` 默认 false。`TEXT.max_length` 默认 100000，列表 `max_items` 默认 200。`required` 只拒绝缺失/null；TEXT 允许空字符串和纯空白，当前没有 `min_length`、正则或数字范围参数。不能额外传参、动态表/字段或任意 patch。
+
+可选参数传 null 或省略末尾位置表示不修改。文本传 `""` 写入空文本；多选及 `list:true` 的人员参数按完整数组替换，`[]` 清空，单人字段最多一个 ID。其他清空使用固定 `{ "clear": true }`；需要在一次保存中动态选择写入或清空日期时，当前声明无法直接表达，可使用 FaaS。
+
+`set` 每个字段只可选择一种来源：`const`、`param`、`current_user: true`、`now: true`、`clear: true`。人员参数使用内部数字 ID 字符串；调用者不能覆盖服务端注入的当前用户和时间。选项用 Catalog 中已有的选项名称，字段使用真实 field ID。附件的参数、整格替换与增量操作见[附件写入](#附件写入)。不要将公式、lookup、系统等不可写字段放入 `set`；调用后按下文检查 `ignored_fields` 等部分结果。
+
+电话、邮箱和超链接使用 `TEXT` 参数或字符串 `const`，支持 create/update、批量写入及 `clear`。电话传完整号码字符串。超链接传地址（如 `https://example.com`）或 `[展示文字](https://example.com)`，不传对象。`returning` 保留本次提交的字符串；超链接可通过原生 Base 记录接口回读。
+
+`TIMESTAMP` 参数接受毫秒整数或含时区的 RFC3339，保留毫秒精度。日期 `const` 使用含时区的字符串，例如 `{"const":"2026-09-15T08:00:00+08:00"}`，不要使用数字时间常量。`now` 使用服务端当前时间。验收日期写入时，通过 Database Function 回读核对实际时间，不能只检查 `returning`。
+
+## 记录范围
+
+`create` 不带 `precondition`。`update`、`delete`、`append_attachments`、`remove_attachments` 必须带 `precondition`，固定为 `conjunction: "and"`，`conditions` 中仅允许一个 `{"field_id":"rec_id","operator":"is","param":N}` 条件。`is` 表示等于单个记录 ID，每组参数只定位一条记录，不接受 ID 数组。
+
+当前 `precondition` 只定位记录，不读取记录做业务预检，不支持其他字段、多个条件、嵌套 `groups`、`or` 或其他操作符；旧 `record_id_param/record_ids_param`、`target` 和 `on_error` 也会在保存时被拒绝。需要服务端检查归属、状态或其他业务条件时使用 FaaS。
+
+不支持省略 ID 按条件修改或删除。可先通过 Database Function 查询 ID，再调用 Mutation；查询结果不保证写入时状态仍相同。
+
+## 创建单条与批量创建
+
+`mutations/createTask/spec.json` 示例；`tblTasks` / `fldTitle` 等替换成 Catalog 中的真实 ID。
+
+```json
+{
+  "table":{"table_id":"tblTasks"},
+  "operation":"create",
+  "params":[{"kind":"TEXT","max_length":100}],
+  "set":{
+    "fldTitle":{"param":1},
+    "fldStatus":{"const":"待处理"},
+    "fldOwner":{"current_user":true},
+    "fldCreatedAt":{"now":true}
+  },
+  "returning":["rec_id","fldTitle"]
+}
+```
+
+调用单条：`{"params":["准备评审"]}`。创建多条、每条内容不同：
+
+```json
+{"batch":[{"params":["准备评审"]},{"params":["补充文档"]}]}
+```
+
+## 多条记录设置相同值
+
+`mutations/renameTasks/spec.json`：
+
+```json
+{
+  "table":{"table_id":"tblTasks"},
+  "operation":"update",
+  "params":[{"kind":"TEXT"},{"kind":"RECORD_ID"}],
+  "precondition":{"conjunction":"and","conditions":[{"field_id":"rec_id","operator":"is","param":2}]},
+  "set":{"fldTitle":{"param":1}},
+  "returning":["rec_id","fldTitle"]
+}
+```
+
+调用：
+
+```json
+{"batch":[{"params":["统一标题","recA"]},{"params":["统一标题","recB"]}]}
+```
+
+每组的第 2 个参数都是单个记录 ID。
+
+## 多条记录设置不同值
+
+复用上例声明，分别传入每条记录的标题和 ID：
+
+```json
+{"batch":[{"params":["标题 A","recA"]},{"params":["标题 B","recB"]}]}
+```
+
+批量模式按同一个声明解释每组参数，每组操作一条记录。同一请求最多 200 组，不允许重复目标 ID。`batch` 与顶层 `params` 互斥，不支持在一批中混合不同表、操作或 Function。
+
+## 删除多条
+
+```json
+{
+  "table":{"table_id":"tblTasks"},
+  "operation":"delete",
+  "params":[{"kind":"RECORD_ID"}],
+  "precondition":{"conjunction":"and","conditions":[{"field_id":"rec_id","operator":"is","param":1}]},
+  "returning":["rec_id"]
+}
+```
+
+调用：`{"batch":[{"params":["recA"]},{"params":["recB"]}]}`。delete 不接受 `set`，返回只能包含 record ID。
+
+## 附件写入
+
+附件上传仍使用 [文件传输](file-transfer.md#上传) 中的 `siteRuntime.uploadAttachment()`；上传成功后复用已有 `fileToken` 和本地图片宽高调用 Mutation。基础追加使用 `append_attachments`，不先查询并重写旧列表。只有创建新记录时随记录提交附件，或业务明确要求替换整个单元格时，才使用 `create` / `update`。
+
+### 参数与操作边界
+
+`ATTACHMENT` 参数单项是附件对象，例如：
+
+```json
+{"file_token":"fileNew","image_width":640,"image_height":480}
+```
+
+将上传返回的 `fileToken` 映射为 `file_token`；非图片只传 token，图片附本地读取的原始宽高，见[图片宽高](file-transfer.md#图片宽高)。
+
+`{"kind":"ATTACHMENT"}` 接收一个对象，`{"kind":"ATTACHMENT","list":true}` 接收对象数组。附件 `const` 使用数组，例如 `{"const":[{"file_token":"fileNew"}]}`。以下示例使用列表参数。
+
+| 操作 | 声明与语义 |
+| --- | --- |
+| `create` | 附件字段的 `set` 使用 `param` 或 `const`，随新记录写入完整附件列表 |
+| `update` | 附件字段的 `set` 使用 `param` 或 `const`，替换整格；`{"clear":true}` 清空该字段 |
+| `append_attachments` / `remove_attachments` | `precondition` 与非空 `set` 必填，`set` 只包含附件字段，来源只允许 `param` / `const`；禁止 `clear`、`current_user`、`now` |
+
+增量操作的每个目标字段必须有非空附件列表。**一次调用跨 batch、目标记录和字段展开后，附件条目累计最多 50 个**；例如 2 个附件追加到 10 条记录计 20 个。同一文件可以用于不同目标，但每个目标都计数。记录批量限制同样生效。50 条仅是附件增量操作的请求限制；普通 create/update 仍遵守 Mutation 的列表预算与目标平台附件限制。
+
+### 追加已上传附件
+
+建立 `mutations/appendTaskAttachments/meta.json`：
+
+```json
+{"name":"追加任务附件"}
+```
+
+`mutations/appendTaskAttachments/spec.json`（ID 替换为 Catalog 中的真实值）：
+
+```json
+{
+  "table":{"table_id":"tblTasks"},
+  "operation":"append_attachments",
+  "params":[
+    {"kind":"RECORD_ID"},
+    {"kind":"ATTACHMENT","list":true,"max_items":50}
+  ],
+  "precondition":{"conjunction":"and","conditions":[{"field_id":"rec_id","operator":"is","param":1}]},
+  "set":{"fldFiles":{"param":2}},
+  "returning":["rec_id","fldFiles"]
+}
+```
+
+继续上传示例中的 `newAttachment`，Page 传记录 ID 和本次新增列表：
+
+```ts
+const result = await invokeDatabaseFunction('appendTaskAttachments', ['recA', [newAttachment]])
+```
+
+对应调用 JSON 为：
+
+```json
+{"params":["recA",[{"file_token":"fileNew","image_width":640,"image_height":480}]]}
+```
+
+假设原单元格已有 `fileOld`，成功响应是本次操作后的完整列表：
+
+```json
+{
+  "code":0,
+  "msg":"success",
+  "data":{
+    "record_ids":["recA"],
+    "records":[{
+      "rec_id":"recA",
+      "fldFiles":[
+        {"file_token":"fileOld","name":"需求.pdf","size":1200},
+        {"file_token":"fileNew","name":"设计.png","size":8000}
+      ]
+    }]
+  }
+}
+```
+
+Page 检查一次顶层 `code`；成功后从 `data.records` 找到对应 `rec_id`，用 `fldFiles` 更新本地附件列表。这里的 `returning` 是操作后的完整附件列表，包含保留下来的旧附件；旧数据的 `name` 可以为空字符串，`size` 可以为 0。不能把请求中的增量列表当成最终列表，也不能把 FaaS 原始路由的 `data.attachments` 当成 Mutation 响应。
+
+### 移除附件引用
+
+`meta.json` 沿用追加示例，将名称改为“移除任务附件”。
+
+`mutations/removeTaskAttachments/spec.json`：
+
+```json
+{
+  "table":{"table_id":"tblTasks"},
+  "operation":"remove_attachments",
+  "params":[
+    {"kind":"RECORD_ID"},
+    {"kind":"ATTACHMENT","list":true,"max_items":50}
+  ],
+  "precondition":{"conjunction":"and","conditions":[{"field_id":"rec_id","operator":"is","param":1}]},
+  "set":{"fldFiles":{"param":2}},
+  "returning":["rec_id","fldFiles"]
+}
+```
+
+Page 只提交待移除 token；若来自 Database Function 的附件对象，将其 `token` 填入 `file_token`：
+
+```ts
+const result = await invokeDatabaseFunction('removeTaskAttachments', ['recA', [{ file_token: 'fileNew' }]])
+```
+
+对应调用 JSON 与移除 `fileNew` 后的成功响应：
+
+```json
+{"params":["recA",[{"file_token":"fileNew"}]]}
+```
+
+```json
+{"code":0,"msg":"success","data":{"record_ids":["recA"],"records":[{"rec_id":"recA","fldFiles":[{"file_token":"fileOld","name":"需求.pdf","size":1200}]}]}}
+```
+
+移除仅删除单元格中的引用，不删除文件；移除后没有附件时返回该字段的空数组。多条记录使用 `invokeDatabaseMutationBatch`，每组传单个记录 ID，受上述附件总数限制。
+
+附件增量操作不保证原子性、并发不丢项或重试去重。部分结果的判断见[调用与结果](#调用与结果)。超时后保留 token 和宽高，按[结果未知的处理](file-transfer.md#超时与结果未知)做有限只读核对，不自动重传、重试或用旧列表整格覆盖。
+
+## 调用与结果
+
+响应 `code=0` 后仍须检查 `record_not_found` 和 `ignored_fields`：非空表示未全部完成，展示缺失记录或被忽略字段及原因。删除结果的 `record_ids` 可能包含未找到的 ID，不能仅按其长度统计成功数。`records` 不包含缺失记录或被忽略字段的请求值。非零业务错误、无说明的结果缺失、重复或陌生 ID 仍报错；超时或结果异常先只读核对，不自动重试整批。部分完成时也刷新数据，避免页面仍显示写入前的状态。批量调用不额外提供事务或 CAS。
+
+`returning` 仅允许 `rec_id` 和声明 `set` 中的字段。普通 create/update/delete 回显未被忽略字段的提交值（参数经过声明类型转换，常量保留原值），可选字段本次没提供时省略；append/remove 返回操作后的完整附件列表，见[附件写入](#附件写入)。普通 CRUD 的 `returning` 是提交值回显；需要最终存储值时在操作后重新查询。普通 CRUD 示例结果：
+
+```json
+{"code":0,"msg":"success","data":{"record_ids":["recA"],"records":[{"rec_id":"recA","fldTitle":"准备评审"}]}}
+```
+
+Page 结果类型与检查（单次、批量共用）：
+
+```ts
+type MutationResult = {
+  record_ids: string[]
+  record_not_found?: string[]
+  ignored_fields?: {id: string; name: string; reason: string}[]
+}
+function assertComplete(result: MutationResult) {
+  const missing = result.record_not_found ?? []
+  const ignored = result.ignored_fields ?? []
+  if (missing.length || ignored.length) {
+    throw new Error([
+      missing.length ? `记录不存在：${missing.join('、')}` : '',
+      ...ignored.map(field => `${field.name}：${field.reason}`),
+    ].filter(Boolean).join('；'))
+  }
+}
+```
+
+Page 一组参数调用（对应上文 `renameTasks`，一组参数修改一条记录）：
+
+```ts
+const result = await invokeDatabaseFunction<MutationResult>('renameTasks', ['统一标题', 'recA'])
+if (result.code !== 0) throw new Error(result.msg || '写入失败')
+if (!result.data) throw new Error('写入结果缺失，请刷新核对')
+assertComplete(result.data)
+```
+
+Page 多组参数调用（对应上文 `createTask`，每组创建一条记录）：
+
+```ts
+const result = await invokeDatabaseMutationBatch<MutationResult>('createTask', [['准备评审'], ['补充文档']])
+if (result.code !== 0) throw new Error(result.msg || '写入失败')
+if (!result.data) throw new Error('写入结果缺失，请刷新核对')
+assertComplete(result.data)
+```
+
+两个 helper 均来自 starter 的 `page/src/lib/database-runtime.ts`，返回 `{code, data?, msg?}`。先检查顶层业务码，再检查 `data` 中的部分结果，不重复解包。
+
+CLI 调用沿用项目级路由：
+
+```bash
+base-database-cli lark-cli -- api POST '/open-apis/base/v3/sites/<site-token>/invoke_function/<function-id>' --params '{"env":"preview"}' --data '{"batch":[{"params":["准备评审"]},{"params":["补充文档"]}]}' --json
+```