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

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

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

package/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 保留宿主原始行为。
 

package/templates/database-starter/gitignore

@@ -1,3 +1,10 @@
 node_modules/
 dist/
 .base-database-cli/
+.base-database-response-*/
+.env
+.env.*
+.npmrc
+.yarnrc
+.yarnrc.yml
+.pnpmrc

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

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

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

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

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

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

package/templates/database-starter/page/src/components/floating-button/assets/toast-close.svg

@@ -0,0 +1,3 @@
+<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M13.5043 13.5042C13.7646 13.2439 13.7665 12.8237 13.5062 12.5633L8.94298 8.00013L13.5061 3.43697C13.7665 3.17662 13.7646 2.7564 13.5043 2.49605C13.2439 2.2357 12.8237 2.23382 12.5633 2.49416C12.303 2.75451 8.00017 7.05732 8.00017 7.05732L3.43697 2.49413C3.17662 2.23378 2.7564 2.23566 2.49605 2.49601C2.2357 2.75636 2.23381 3.17658 2.49416 3.43693L7.05736 8.00013L2.49413 12.5634C2.23378 12.8237 2.23566 13.2439 2.49601 13.5043C2.75636 13.7646 3.17659 13.7665 3.43693 13.5062L8.00017 8.94294L12.5634 13.5061C12.8237 13.7665 13.2439 13.7646 13.5043 13.5042Z" fill="#646A73"/>
+</svg>

package/templates/database-starter/page/src/components/floating-button/assets/toast-info.svg

@@ -0,0 +1,5 @@
+<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+<circle cx="8.00008" cy="8.00033" r="7.33333" fill="#1456F0"/>
+<path d="M8 5.33333C8.36819 5.33333 8.66667 5.03486 8.66667 4.66667C8.66667 4.29848 8.36819 4 8 4C7.63181 4 7.33333 4.29848 7.33333 4.66667C7.33333 5.03486 7.63181 5.33333 8 5.33333Z" fill="white"/>
+<path d="M7.33333 6C6.96514 6 6.66667 6.29848 6.66667 6.66667C6.66667 7.03486 6.96514 7.33333 7.33333 7.33333V10H6.66667C6.29848 10 6 10.2985 6 10.6667C6 11.0349 6.29848 11.3333 6.66667 11.3333H9.33333C9.70152 11.3333 10 11.0349 10 10.6667C10 10.2985 9.70152 10 9.33333 10H8.66667V6.66667C8.66667 6.29848 8.36819 6 8 6H7.33333Z" fill="white"/>
+</svg>

package/templates/database-starter/page/src/components/floating-button/assets/tooltip-caret.svg

@@ -0,0 +1,3 @@
+<svg width="24" height="6" viewBox="0 0 24 6" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M8.4383 1.99309L11.2526 5.15916C11.6504 5.60668 12.3496 5.60668 12.7474 5.15916L15.5617 1.99309C16.6886 0.725344 18.3038 0 20 0L12 0L4 0C5.69619 0 7.31142 0.725345 8.4383 1.99309Z" fill="#1F2329"/>
+</svg>