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

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

@@ -7,7 +7,7 @@
 - [FaaS 开发](#faas-开发)：目录、handler 与 context
 - [远程调用与写入链路设计](#远程调用与写入链路设计)：依赖、一致性与重试
 - [下游错误归一化](#下游错误归一化)：业务结果与诊断
-- [应用记录 写入协议](#应用记录-写入协议)：请求、响应与部分成功
+- [应用记录写入协议](#应用记录写入协议)：请求、响应与部分成功
 - [创建实现示例](#创建实现示例)：固定操作示例
 - [Base 读写协议](#base-读写协议)：字段格式与集合更新
 
@@ -106,7 +106,7 @@ function parseCreateTask(value: unknown): CreateTaskInput {
 
 ### 下游错误归一化
 
-FaaS 调用 Base OpenAPI 或其他 应用 Function 时，把当前 operation 的业务结果与下游诊断分开：
+FaaS 调用 Base OpenAPI 或其他应用 Function 时，把当前 operation 的业务结果与下游诊断分开：
 
 - 顶层 `code` 和 `msg` 表达稳定、面向调用方的业务语义，不直接使用上游错误码，也不把技术细节拼进 `msg`。
 - 成功或部分成功的业务结果保留在 `data`；仅在失败或部分成功时，把失败步骤放入 `data.errors`。
@@ -159,7 +159,7 @@ FaaS 使用 `context.fetch` 调用固定的批量写入路由；只使用线上
 |---|---|
 | Online | `https://open.feishu.cn` |
 
-#### 应用记录 写入协议
+#### 应用记录写入协议
 
 FaaS 只使用以下五个固定路由，均为 `POST`，请求头为
 `Content-Type: application/json; charset=utf-8`：
@@ -175,7 +175,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 +490,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 +510,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。结论注明证据层级：实现已核对、运行效果已验证、未验证。截图只证明其对应的页面、尺寸和状态；没有运行证据时不声称交互或视觉通过，也不为消除“未验证”自行扩大检查。有明确问题时修复对应实现，其余工作继续主流程。

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

@@ -1,20 +1,20 @@
 # 原生通知集成
 
-需求包含原生 workflow 向使用者发送 应用 业务通知时读取。通知应属于用户明确要求的流程；先确认接收人范围、触发条件和业务动作。workflow JSON 按[原生能力路由](base-capability-routing.md)读取当前 CLI 文档，不推测 steps 协议。
+需求包含原生 workflow 向使用者发送应用业务通知时读取。通知应属于用户明确要求的流程；先确认接收人范围、触发条件和业务动作。workflow JSON 按[原生能力路由](base-capability-routing.md)读取当前 CLI 文档，不推测 steps 协议。
 
 ## 入口策略
 
-按用户明确要求优先判定，默认保持 应用 业务对象的操作入口：
+按用户明确要求优先判定，默认保持应用业务对象的操作入口：
 
 | 策略 | 条件 | 入口要求 |
 | --- | --- | --- |
-| `base_action` | 用户明确要求进入多维表格 | 可使用 Base URL 或 `recordLink`，不称为 应用 入口 |
+| `base_action` | 用户明确要求进入多维表格 | 可使用 Base URL 或 `recordLink`，不称为应用入口 |
 | `informational` | 用户明确要求纯展示、无需点击入口 | 可用 `btn_list=[]`，记录该要求；说明平台仍可能提供默认 Base 跳转 |
-| `site_action` | 其余与 应用 业务对象关联的通知 | 显式 `openLink`，进入 Page 已实现的业务路由并定位对象 |
+| `site_action` | 其余与应用业务对象关联的通知 | 显式 `openLink`，进入 Page 已实现的业务路由并定位对象 |
 
-正文已包含业务信息，不构成选择 informational 的依据。访客通知默认进入该登记详情，考试通知进入相应考试详情或答题页；这些是规则示例，不改变用户明确的入口要求。不能用 应用 首页冒充对象详情。
+正文已包含业务信息，不构成选择 informational 的依据。访客通知默认进入该登记详情，考试通知进入相应考试详情或答题页；这些是规则示例，不改变用户明确的入口要求。不能用应用首页冒充对象详情。
 
-`site_action` 使用本次 deploy 返回的顶层 `baseAppUrl`，保留已有查询参数，增加 Page 实际实现的功能定位参数与 workflow 上下文中的最小稳定对象标识。不能使用内部 `staticUrl`、Base URL/recordLink、管理后台或根据 应用 appToken 猜测地址。
+`site_action` 使用本次 deploy 返回的顶层 `baseAppUrl`，保留已有查询参数，增加 Page 实际实现的功能定位参数与 workflow 上下文中的最小稳定对象标识。不能使用内部 `staticUrl`、Base URL/recordLink、管理后台或根据应用 appToken 猜测地址。
 
 `btn_list=[]` 仅表示没有显式按钮，不保证整卡不可点击。用户要求任何点击都不能进入 Base 时，先发现可满足要求的方案；没有相应能力则报告限制，不用 informational 规避要求。
 
@@ -24,7 +24,7 @@
 2. 新 workflow 延后到 Preview 发布成功、且新建 Base 示例验证通过后创建，避免示例记录触发真实通知。当前 CLI 的新建 workflow 默认禁用；创建前仍检查当前 `+workflow-create --help`，传入稳定的本次 `client_token`。
 3. 取得最终 `baseAppUrl` 后构造完整定义并 create，再 get 核验。已有 workflow 先 get 当前定义和使用范围；正在服务生产用户的流程按[生产入口切换](#生产入口切换)保留原链接，其他流程只修改本次授权字段，用完整 read-modify-write update 后 get。不把旧样例或部分响应当完整配置。
 4. 逐个核对通知动作的入口策略、按钮链接、功能参数、对象标识及状态。site_action 必须定位到真实业务路由；其他策略需有明确需求依据。
-5. 按下表决定启停，必要时启用后再次 get。记录实际结果后返回[发布与交付](release.md)，不能把 应用 发布成功等同通知完成。
+5. 按下表决定启停，必要时启用后再次 get。记录实际结果后返回[发布与交付](release.md)，不能把应用发布成功等同通知完成。
 
 ## 状态与失败处理
 
@@ -43,6 +43,6 @@
 
 应用 Prod 发布成功后，使用本次返回的生产 `baseAppUrl`，按 Preview 清单逐一 get → 必要的完整 update → get。site_action 只替换环境入口，保留功能定位参数、动态对象参数、其他步骤和启停状态；最终链接不含 `mode=edit`。已有链接正确时仍回读核对，不做无变化写入。其他策略保留入口意图并复核状态。
 
-已有生产 应用 的 Preview 迭代不得把正在服务生产用户的 workflow 链接改为 owner-only Preview。先核对原链接与使用范围：保留生产入口，将新 Preview 的功能参数列入待切换清单；需要独立通知测试时，仅在用户授权的隔离测试流程中执行。
+已有生产应用的 Preview 迭代不得把正在服务生产用户的 workflow 链接改为 owner-only Preview。先核对原链接与使用范围：保留生产入口，将新 Preview 的功能参数列入待切换清单；需要独立通知测试时，仅在用户授权的隔离测试流程中执行。
 
-任一切换失败时分别报告 应用 发布与通知切换状态；修复后只恢复失败步骤。发布 应用 不会自动迁移外部 workflow，也不授权发送额外测试通知。
+任一切换失败时分别报告应用发布与通知切换状态；修复后只恢复失败步骤。发布应用不会自动迁移外部 workflow，也不授权发送额外测试通知。

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

@@ -25,7 +25,7 @@ README 不放客户真实数据、凭证、token 或内部调试日志。CLI 在
 
 ## 发布前
 
-确认工程与 应用 一致并保留需求外 Function。涉及视觉的变更按[前端设计指导](frontend-design-guide.md#交付前自检)检查；涉及通知先按[通知集成](notifications.md)确定路由、资源范围和启停策略。
+确认工程与应用一致并保留需求外 Function。涉及视觉的变更按[前端设计指南](frontend-design-guide.md#交付前自检)检查；涉及通知先按[通知集成](notifications.md)确定路由、资源范围和启停策略。
 
 实现完成后，在项目根目录使用唯一受支持的本地检查入口：
 
@@ -47,13 +47,13 @@ base-database-cli check --json
 base-database-cli deploy
 ```
 
-CLI 负责 Function metadata、全量查询校验、必要依赖安装、Page/FaaS build、归档、Functions 全量更新、Artifact 上传与源码回读、Preview 发布和轮询。查询校验失败时不会继续构建；依赖指纹未变且 node_modules 有效时可跳过安装，但仍 build。安装选项仅在有相应排障依据时使用，不通过跳过校验掩盖失败。
+CLI 负责 Function metadata、全量查询校验、必要依赖安装、Page/FaaS build、归档、Functions 全量更新、Artifact 上传与源码回读、Preview 发布和轮询。查询校验失败时不会继续构建；依赖指纹未变且 node_modules 有效时可跳过安装，但仍 build。安装选项仅在有相应排障依据时使用，不通过跳过校验掩盖失败。本地没有 `ai/` 声明时 deploy 不调用 AI Function 接口，未涉及 AI 的应用不需要开通 AI Function；需要让本次发布完全不动 AI Function 时显式加 `--skip-ai-functions`，并在交付报告中说明 AI Function 未同步且未验证（见[诊断与验收](verification.md)）。
 
 等待命令完成，进程仍在运行不代表失败，不重复启动部署。只有发布成功响应中的顶层 `baseAppUrl` 是可信交付入口，制品大小、SHA-256 和 publish ID 用于追溯。不能用历史 URL、管理后台、Catalog 或内部 `staticUrl` 替代缺失入口。
 
 发布成功后按顺序处理：
 
-1. 本次创建新 Base：完成下述示例数据验证；复用已有 Base 或修改 应用 不擅自写示例记录。
+1. 本次创建新 Base：完成下述示例数据验证；复用已有 Base 或修改应用不擅自写示例记录。
 2. 本次涉及原生通知：完成[通知入口与状态收尾](notifications.md)，保留原有启停状态。
 3. 汇总已验证范围、业务成果和未完成项，交付 Preview 并等待体验。
 
@@ -63,13 +63,13 @@ CLI 负责 Function metadata、全量查询校验、必要依赖安装、Page/Fa
 
 ## 从零建站示例数据验收
 
-本节只适用于本次创建了新 Base 的从零建站；复用已有 Base、修改已有 应用 时不得擅自添加示例记录。先设计小而完整的非敏感示例，覆盖核心对象、典型状态和必要关联，在可见业务主字段使用稳定的“示例”标记，不新增仅用于播种的字段。构造记录 payload 前读取当前 lark-base 的 CellValue 协议，不能直接复用 FaaS 下游请求的字段格式；两条链路可能有不同的输入归一化。
+本节只适用于本次创建了新 Base 的从零建站；复用已有 Base、修改已有应用时不得擅自添加示例记录。先设计小而完整的非敏感示例，覆盖核心对象、典型状态和必要关联，在可见业务主字段使用稳定的“示例”标记，不新增仅用于播种的字段。构造记录 payload 前读取当前 lark-base 的 CellValue 协议，不能直接复用 FaaS 下游请求的字段格式；两条链路可能有不同的输入归一化。
 
 示例数据使用 lark-cli 的输入契约。`+record-batch-create --help` 提供常用格式，完整类型与日期时间支持形态按当前 lark-base 的 CellValue 文档核对；文档位置通过 `lark-cli skills read lark-base` 的路由查找。下表区分两条链路，执行前仍核对安装版本的协议与真实字段：
 
-| 字段 | 开发期 lark-cli 写入 | FaaS 应用记录 写入 |
+| 字段 | 开发期 lark-cli 写入 | FaaS 应用记录写入 |
 | --- | --- | --- |
-| 单选 | `["待处理"]`，数组最多一项 | `"待处理"`，合法选项名字符串 |
+| 单选 | `"待处理"`，选项名字符串（字段 `multiple=false`） | `"待处理"`，合法选项名字符串 |
 | 多选 | `["标签一", "标签二"]` | 同为选项名数组 |
 | 人员 | `[{"id":"ou_..."}]`，由当前 CLI 通讯录查询取得 open_id | `[{"id":"User.user_id"}]`，由 starter 人员选择器的 `User.user_id` 取得 |
 | 日期时间 | 按当前 lark-base CellValue 协议确认支持形态 | 按[FaaS CellValue](faas.md#base-读写协议)格式提交 |
@@ -77,12 +77,12 @@ CLI 负责 Function metadata、全量查询校验、必要依赖安装、Page/Fa
 两条写入链路的格式不能直接互用，也不能仅替换 ID 前缀。最小 CLI 请求示例（字段名、选项和 ID 均需替换为真实查询结果）：
 
 ```json
-{"create_records":[{"任务名称":"示例：准备评审","状态":["待处理"],"负责人":[{"id":"ou_example"}]}]}
+{"create_records":[{"任务名称":"示例：准备评审","状态":"待处理","负责人":[{"id":"ou_example"}]}]}
 ```
 
 1. 从 `catalog.json` 读取真实 `baseToken`、table ID、字段类型和选项。先通过项目路由执行 `base-database-cli lark-cli -- base +field-list --base-token <base-token> --table-id <table-id>` 核对可写字段，再使用 `base-database-cli lark-cli -- base +record-batch-create --base-token <base-token> --table-id <table-id> --json '<payload>'` 写入已经设计的示例数据。当前环境提供等价的 Base Database CLI 命令时只替换命令前缀，不改变 `lark-cli` shortcut、参数或 payload；没有项目级路由时才直接执行同名 `lark-cli base +... --as user`。只写存储字段，单批不超过 200 条，不写 formula、lookup、系统字段或附件。
 2. `--json` 使用 `{"create_records":[{...}]}`；成功必须返回与请求数量一致的 `record_id_list`，并检查可选 `ignored_fields`。多表或有关联记录时按真实依赖串行写入，后续关联只使用前一步返回的 record ID。
-3. 存在列表、详情、看板、统计等业务数据展示时，通过项目路由调用页面实际使用的 Database Function，而不是用 `+record-list` 代替展示链路验收：`base-database-cli lark-cli -- api POST /open-apis/base/v3/sites/<app-token>/invoke_function/<function-id> --params '{"env":"preview"}' --data '{"params":[...]}' --json`。检查 Function 顶层业务码与 ResultJSON，并确认刚写入的示例记录、关系和统计真实可见。
+3. 存在列表、详情、看板、统计等业务数据展示时，通过项目路由调用页面实际使用的 Database Function，而不是用 `+record-list` 代替展示链路验收：`base-database-cli lark-cli -- api POST /open-apis/base/v3/sites/<app-token>/invoke_function/<function-id> --params '{"env":"preview"}' --data '{"params":[...]}' --json`。CLI 输出外层是 lark-cli 的 `ok`/`data`：`ok:true` 时 `data` 才是 Function 的 `{code,msg,data}` 信封，非零业务码会变成 `ok:false` 并在 `error` 中给出；判定方式见[开发期与运行态输出](development.md#开发期与运行态输出)。检查 Function 顶层业务码与 ResultJSON，并确认刚写入的示例记录、关系和统计真实可见。
 4. 重复验证或修复后重试前，先用同一 Database Function 按稳定示例标记或已返回的 record ID 确认当前状态，只补写缺失数据。创建结果未知时禁止盲目重试，避免生成重复记录。
 5. `lark-cli` 写入失败、返回记录数不符、Database Function 返回非零业务码、响应结构不符合契约，或查询不到已确认写入的数据，都视为示例数据闭环未完成。保存脱敏错误和 LogID；写入问题检查 Catalog、字段、CellValue、关联 ID 和权限，查询问题检查查询语句、参数及响应解析。实现问题修复后重新 `deploy`，再从本节第 1 步验证。
 6. 只有认证、权限或平台服务存在证据充分的外部阻塞时才标记 `blocked`；不得声称示例数据或整体从零建站已完成。示例写入与 Database Function 回读均通过后，才进入通知 workflow 收尾并向用户交付 Preview。
@@ -97,9 +97,9 @@ CLI 负责 Function metadata、全量查询校验、必要依赖安装、Page/Fa
 base-database-cli deploy --production --yes
 ```
 
-CLI 读取 `.base-database-cli/state/preview.json`，校验 应用 appToken、Artifact SHA-256 与工作区输入指纹，发布同一份制品，不重建或上传替代品。缺少 Preview 记录、旧回执缺少指纹或未经过 README 校验、制品或源码/配置/文件结构变化时，重新生成 Preview 并取得针对新制品的确认。`--yes` 只是向 CLI 传递已有授权。
+CLI 读取 `.base-database-cli/state/preview.json`，校验应用 appToken、Artifact SHA-256 与工作区输入指纹，发布同一份制品，不重建或上传替代品。缺少 Preview 记录、旧回执缺少指纹或未经过 README 校验、制品或源码/配置/文件结构变化时，重新生成 Preview 并取得针对新制品的确认。`--yes` 只是向 CLI 传递已有授权。
 
-Prod 发布不会自动更新 Base workflow。存在通知集成时，按 Preview 留存的清单逐个完成[生产入口切换](notifications.md#生产入口切换)。切换失败则明确报告“Prod 已发布，但通知入口切换未完成”，保存失败对象与证据；不重复发布 应用 来掩盖外部配置失败。
+Prod 发布不会自动更新 Base workflow。存在通知集成时，按 Preview 留存的清单逐个完成[生产入口切换](notifications.md#生产入口切换)。切换失败则明确报告“Prod 已发布，但通知入口切换未完成”，保存失败对象与证据；不重复发布应用来掩盖外部配置失败。
 
 ## 交付结果
 

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

@@ -1,6 +1,6 @@
 # Base Database 工程质量
 
-本文汇总业务系统、数据、后端与前端的稳定设计原则。具体平台命令见[工程与环境](workspace.md)，Page 协议见[Page 开发](development.md)，基础写入见[Mutation](mutations.md#写入方式选择)，FaaS 写入协议见[FaaS](faas.md)，视觉设计见[前端设计指导](frontend-design-guide.md)。
+本文汇总业务系统、数据、后端与前端的稳定设计原则。具体平台命令见[工程与环境](workspace.md)，Page 协议见[Page 开发](development.md)，基础写入见[Mutation](mutations.md#写入方式选择)，FaaS 写入协议见[FaaS](faas.md)，视觉设计见[前端设计指南](frontend-design-guide.md)。
 
 ## 业务与数据设计
 
@@ -17,7 +17,7 @@
 
 - Database Function 查询、分页、聚合与结果合并按[Database Function](database-function.md)；公式和 lookup 只承载需要长期显示在 Base 中的派生结果，避免重复保存易漂移数据。
 - FaaS 写入的一致性、调用依赖、部分成功与重试按[FaaS 协议](faas.md#远程调用与写入链路设计)；Mutation 的结果见[调用与结果](mutations.md#调用与结果)。
-- 读写权限分别按[权限设计](permission-design.md)；布局、控件与交互状态按[前端设计指导](frontend-design-guide.md)。
+- 读写权限分别按[权限设计](permission-design.md)；布局、控件与交互状态按[前端设计指南](frontend-design-guide.md)。
 
 ## 工程与交付
 

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

@@ -4,7 +4,7 @@
 
 ## 确定范围
 
-记录目标 应用、环境、工程来源、出错动作和预期结果。优先复用已有工程与日志；资源不明时按[工程与环境](workspace.md)定位。区分构建/查询校验、发布、Page 加载、Function 执行、原生配置及权限问题，再读取对应协议。
+记录目标应用、环境、工程来源、出错动作和预期结果。优先复用已有工程与日志；资源不明时按[工程与环境](workspace.md)定位。区分构建/查询校验、发布、Page 加载、Function 执行、原生配置及权限问题，再读取对应协议。
 
 | 失败阶段 | 首先检查 | 恢复边界 |
 | --- | --- | --- |
@@ -18,7 +18,7 @@
 
 ## 发布任务查询
 
-部署输出已给出 publish ID，但等待超时或进程中断时，在该 应用 的工程目录执行：
+部署输出已给出 publish ID，但等待超时或进程中断时，在该应用的工程目录执行：
 
 ```bash
 base-database-cli deployments status <publish-id>
@@ -27,7 +27,7 @@ base-database-cli deployments status <publish-id> --wait
 
 首条查询一次，`--wait` 轮询至成功或失败/超时。命令也接受第二个位置参数作为工程目录，并读取其中的 `base-database.jsonc`。publish ID 来自本次部署输出或已确认属于该任务的记录，不能以历史回执中的其他 ID 代替。
 
-状态 `0/1` 表示处理中，`10` 表示成功，`20` 表示失败。查询成功不等于发布成功，按 status 判断；成功后使用返回的 `baseAppUrl`。失败、未知状态或再次超时先保存证据，再决定修复，不自动再次 deploy。没有 publish ID 时先检查已有输出和任务记录，不通过创建新发布寻找结果。
+返回的 `statusText` 为 `pending`、`processing`、`succeeded`、`failed` 或 `unknown`，对应数字 `status` 的 `0`、`1`、`10`、`20`。查询成功不等于发布成功，按 `statusText` 判断；成功后使用返回的 `baseAppUrl`。失败、未知状态或再次超时先保存证据，再决定修复，不自动再次 deploy。没有 publish ID 时先检查已有输出和任务记录，不通过创建新发布寻找结果。
 
 ## 旧工程与 CSRF 排查
 
@@ -42,11 +42,13 @@ Page 不读取宿主 Cookie、不手写 CSRF Header，也不通过直连业务
 
 ## 验证方法
 
+通过 `base-database-cli lark-cli -- api ... --json` 调用 Function 时，输出外层是 lark-cli 的 `ok`/`data`；`ok:true` 时 `data` 才是 Function 的 `{code,msg,data}` 信封，非零业务码会以 `ok:false` 加 `error` 返回。按[开发期与运行态输出](development.md#开发期与运行态输出)逐层判定，不把外层 `ok` 当作业务成功，也不因缺少顶层 `code` 判定协议不符。
+
 静态检查、构建、查询编译、部署成功分别证明对应阶段，不证明完整业务链路。新建 Base 的常规验证或发布后补齐示例数据，先完整读取并执行[示例数据验收](release.md#从零建站示例数据验收)，其中包含 CLI 写入格式和页面 Database Function 回读的实际路径；用户明确要求运行态验收时可以追加本次范围内的只读 Database Function 调用和可用浏览器检查。
 
 `base-database-cli check` 只覆盖项目结构、Database Function/FaaS metadata、依赖锁与 Page/FaaS 本地构建，不调用远端 `ai-functions validate`，也不校验 `ai/<functionKey>/meta.json` 的配置合法性；即使 `check` 通过，也只能报告 Page/FaaS 本地可编译，不能声称 AI Function 配置已验证。每个本地 AI Function 都要单独执行 `ai-functions validate <functionKey>`，得到 `is_success: true` 才算完成静态校验；缺少认证/model_profiles 时报告未验证项并继续。
 
-`deploy` 默认在 `postArtifactMeta` 之后按本地 `ai/` 全集调用一次全量覆盖同步；仅当当前进程环境变量 `BASE_SITE_SKIP_AI_FUNCTION_SYNC=1` 时会跳过该同步（用于内部环境的分阶段上线或回滚）。设置该标志后，报告本次 deploy 只发布了 Page/Database Function/FaaS，AI Function 未同步且未验证；恢复到原状态前不要基于 Preview 结论宣布 AI Function 已上线。
+`deploy` 按本地 `ai/` 全集同步 AI Function；空 `ai/` 时自动跳过，不调 AI Function 接口，未涉及 AI 的应用无需开通。需要让本次发布完全不动 AI Function 时加 `--skip-ai-functions`（Preview、Prod 均适用），并在交付或验收报告中说明 AI Function 未同步且未验证，不宣布其已上线。
 
 写入验收先确认目标、测试数据和用户授权，尤其已有 Base、业务通知和不可逆操作。不得仅为测试而创建生产业务记录或外发消息。用户要求的写入验证完成后，清理仍遵守同一资源操作的授权要求。
 

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

@@ -30,12 +30,13 @@ profile 决定账号与品牌，`--env` 决定运行环境。profile 缺失、
 
 ## 环境与依赖
 
-公开 CLI 只使用 `online` 环境；`init`、`pull` 等支持环境参数的命令显式传 `--env online`，`deploy` 不接受该参数。托管运行时使用宿主已安装的 `base-database-cli` 与唯一默认环境，不重新安装公开 CLI。CLI、OpenAPI、Accounts、应用 和 Page runtime 必须处于同一环境；原生资源操作始终使用 `--as user`。
+公开 CLI 只使用 `online` 环境；`init`、`pull` 等支持环境参数的命令显式传 `--env online`，`deploy` 不接受该参数。托管运行时使用宿主已安装的 `base-database-cli` 与唯一默认环境，不重新安装公开 CLI。CLI、OpenAPI、Accounts、应用和 Page runtime 必须处于同一环境；原生资源操作始终使用 `--as user`。
 
 首次使用 `lark-cli` 时读取当前入口的 `--help`，本会话复用已确认的命令能力；不只按版本号判断，也不将云电脑等宿主认证环境等同于设置了 `BASE_SITE_BUILDER_*` 的 Builder。
 
 | 能力 | 使用方式与缺失时处理 |
 | --- | --- |
+| `lark-cli` 可执行文件 | 公开环境缺失时执行 `npx @larksuite/cli@latest install`，其他安装方式见 [github.com/larksuite/cli](https://github.com/larksuite/cli)；托管环境缺失时报告环境阻塞，不自行安装 |
 | `api`、本任务需要的 `base` 命令 | 业务所需能力；按当前帮助和协议执行，真实认证、权限或接口错误按失败阶段处理 |
 | `config` / `auth` | 本地账号管理能力。宿主提供认证时不补建 `default` profile；宿主缺少管理命令但通过 `LARKSUITE_CLI_PROFILE` 选择托管凭证时保留该环境变量，不传宿主禁止的 `--profile` 参数，由真实业务请求校验 profile，不回退账号 |
 | `skills read` | 可选的文档入口。存在时读取 `lark-base` 并沿路由找 reference；不存在时直接读取环境提供的 lark-base 文件与相应命令帮助，后续不反复尝试该入口 |
@@ -59,31 +60,32 @@ base-database-cli context . --summary --json
 | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
 | `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-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 模式仍执行表中的恢复路径。
+上述四种来源与宿主工程恢复协议一致。`binding` 还必须有非空 `BASE_SITE_BUILDER_BASE_TOKEN`，应用名称与描述从当前需求确定。宿主变量存在但取值不在表中、必需 token 缺失或工程与宿主状态矛盾时，报告恢复条件不满足，不创建新资源掩盖问题。会话历史未恢复但工程有效时，先读取现有工程继续；没有工程的合法 binding 模式仍执行表中的恢复路径。
 
-非托管环境：已有工程直接增量修改；只有远端 应用 时，在空目录执行 `base-database-cli pull . --app-token <app-token> --env online`；确认为新建时才 init。保留用户未提交内容，不能以恢复工程为由覆盖非空目录。
+非托管环境：已有工程直接增量修改；只有远端应用时，在空目录执行 `base-database-cli pull . --app-token <app-token> --env online`；确认为新建时才 init。保留用户未提交内容，不能以恢复工程为由覆盖非空目录。
 
 ## 需求与 Base 定位
 
-明确 应用 名称、一句客观描述、使用者、核心对象及关系、状态流转、页面任务和一条端到端验收路径。描述优先采用用户原文，未提供时根据需求生成使用对象与核心用途，不写营销文案、实现细节或发布状态。
+明确应用名称、一句客观描述、使用者、核心对象及关系、状态流转、页面任务和一条端到端验收路径。描述优先采用用户原文，未提供时根据需求生成使用对象与核心用途，不写营销文案、实现细节或发布状态。
 
 用户未指定已有 Base 时，从零设计完整 schema；描述业务表和字段不代表这些资源已经存在。用户指定已有 Base 时，可信 token 直接使用，链接先用 `lark-cli base +url-resolve --url '<url>' --as user`，名称先用 `+title-resolve --title '<keyword>' --as user`；无法唯一定位时再请用户补充，不要求用户重复提供已有信息。
 
-**当前 init 将所选 Base 的全部表绑定到 应用，没有选择部分表的参数。** 复用前只读确认所有表与权限边界；从零建模也只在目标 Base 中建立可全部绑定的业务表。若无关或敏感表使全表绑定不可接受，停止初始化并说明当前限制，按用户决定调整数据范围；不擅自复制、删表或宣称页面隐藏能收缩绑定权限。访问判定见[权限设计](permission-design.md)。
+**当前 init 将所选 Base 的全部表绑定到应用，没有选择部分表的参数。** 复用前只读确认所有表与权限边界；从零建模也只在目标 Base 中建立可全部绑定的业务表。若无关或敏感表使全表绑定不可接受，停止初始化并说明当前限制，按用户决定调整数据范围；不擅自复制、删表或宣称页面隐藏能收缩绑定权限。访问判定见[权限设计](permission-design.md)。
 
 已有 Base 初始化只读取表结构，不修改 schema。Catalog 缺少业务必需结构时，只在用户已授权的修改范围内补齐；否则报告缺口和可实现范围。
 
 ## 初始化
 
-初始化前检查 `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_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 前，按已确认的文档入口读取字段规范：支持 `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 后再按原顺序创建其余字段。
+编写 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 后再按原顺序创建其余字段。
 
+- 用户所在地或需求明确了时区时，`init --schema` 追加 `--time-zone <IANA 时区>`（例如 `Asia/Tokyo`）；未指定时由服务端按租户默认时区创建。
 - 首个字段成为表的主字段，优先采用可读的文本标识；其他类型先核对主字段限制。
 - 单选和多选都用 `select`，多选显式设置 `"multiple": true`，选项按字段规范声明。
 - `link` 字段必须提供 `link_table`，且名称与本次 Schema 中的目标表完全一致；自关联和跨表关联会在所有表创建后补建，不需要按关联依赖调整表顺序。
@@ -131,7 +133,7 @@ base-database-cli init . \
   --schema ./base-schema.json
 ```
 
-托管环境 已有 应用 场景执行：
+托管环境 已有应用场景执行：
 
 ```bash
 base-database-cli init . \
@@ -153,9 +155,9 @@ base-database-cli init . \
   --base-token basxxxxxxxx
 ```
 
-托管环境 复用已有 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、表、字段和记录。
+该命令调用只读 Base 接口获取 Base 信息并分页列出全部表。未指定 `--app-token` 时，通过应用创建接口的 `baseBindings` 绑定这些表；指定时，通过目标应用的 `bind_base` 绑定这些表。最后从目标应用获取 Catalog。它不会创建或修改 Base、表、字段和记录。
 
 两种路径必须且只能传入 `--schema` 或 `--base-token` 之一，并始终传入非空 `--description`。公开 CLI 的 `--env` 默认且只支持 `online`；托管环境 使用已配置的默认环境。建表顺序与等待由 CLI 管理。
 
@@ -201,7 +203,7 @@ base-database-cli lark-cli -- api GET /open-apis/base/v3/sites/<app-token>/catal
 
 ## 开发期调用边界
 
-项目级 `base-database-cli lark-cli -- ...` 用于追加 binding、应用 控制面诊断，以及新建 Base 的示例数据写入和 Database Function 回读验证；需在含 `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 保留宿主原始行为。