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

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

@@ -1,6 +1,9 @@
 # Mutation Function
 
-Mutation 是固定单表的基础写入声明。读取继续用 Database Function；写入使用 `mutations/<functionId>/{meta.json,spec.json}`，Page 只传位置参数。表、可写字段、固定值和记录 ID 参数来源由发布者声明，不能由调用者扩展。写入方式按下节选择。
+Page 先按[Function 调用契约](development.md#function-调用契约)选择调用形态。下文 Page 正例为命名路由：workspace 用 SDK，命名 classic 用工程 helper；位置 classic 的单次/批量正例见[存量 Mutation 调用](legacy-development.md#mutation-调用)。外部 Agent 统一传命名对象。
+
+
+Mutation 是固定单表的基础写入声明。读取继续用 Database Function；写入使用 `mutations/<functionId>/{meta.json,spec.json}`，命名路由 Page 与外部 Agent 按参数 `name` 传对象。表、可写字段、固定值和记录 ID 参数来源由发布者声明，不能由调用者扩展。写入方式按下节选择。
 
 CLI 的 `deploy` 自动校验、打包并注册声明，`pull` 恢复 `mutations/`。全部类型共享 Function ID 和最多 200 个 Function 的限制。保存成功不代表写入一定成功，调用后仍需检查错误与部分完成结果。
 
@@ -25,11 +28,13 @@ CLI 的 `deploy` 自动校验、打包并注册声明，`pull` 恢复 `mutations
 
 Mutation 不声明角色；调用仍需通过应用统一准入。记录 ID 仅限定操作范围，不代表记录归属或行权限校验。
 
-`spec.json` 中 `param` 是 **从 1 开始的位置编号**。记录条件的 `param: 2` 表示从第 2 个参数读取 ID，和“修改两条”没有关系。目标参数必须是必填的单值 `RECORD_ID`，不能设置 `list: true`；多条记录通过 `batch` 逐条传参。
+`spec.params[]` 的 name/description 规则见[平台检查与提示](agent-tool-design.md#平台检查与提示)。可选 `enum` 声明固定选项，值的 JSON 类型与 `kind` 一致（`TEXT`、`USER_ID`、`GROUP_ID`、`RECORD_ID` 为字符串，`INT` 为整数，`DOUBLE` 为数字，`BOOL` 为布尔），`list: true` 时约束每个元素，其他 `kind` 不能声明 `enum`。`enum` 非空、不重复、不含 `null`、最多 100 项，保存时服务端按 `set` 绑定字段的选项校验。写声明前先读[面向 Agent 的函数与参数设计](agent-tool-design.md)。
+
+`spec.json` 中 `param` 是 **从 1 开始的位置编号**，指向 `spec.params[]` 的声明顺序。记录条件的 `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。
+每个参数声明显式 `name`，与服务端冻结声明一致；Page 用名称传值，`param` 编号仍用于声明内部引用。可选参数传 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` 等部分结果。
 
@@ -41,7 +46,7 @@ Mutation 不声明角色；调用仍需通过应用统一准入。记录 ID 仅
 
 `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。
+当前 `precondition` 只定位记录，不读取记录做业务预检，不支持其他字段、多个条件、嵌套 `groups`、`or` 或其他操作符。需要服务端检查归属、状态或其他业务条件时使用 FaaS。
 
 不支持省略 ID 按条件修改或删除。可先通过 Database Function 查询 ID，再调用 Mutation；查询结果不保证写入时状态仍相同。
 
@@ -53,7 +58,7 @@ Mutation 不声明角色；调用仍需通过应用统一准入。记录 ID 仅
 {
   "table":{"table_id":"tblTasks"},
   "operation":"create",
-  "params":[{"kind":"TEXT","max_length":100}],
+  "params":[{"name":"title","kind":"TEXT","max_length":100,"description":"新任务的标题，最多 100 字"}],
   "set":{
     "fldTitle":{"param":1},
     "fldStatus":{"const":"待处理"},
@@ -64,10 +69,10 @@ Mutation 不声明角色；调用仍需通过应用统一准入。记录 ID 仅
 }
 ```
 
-调用单条：`{"params":["准备评审"]}`。创建多条、每条内容不同：
+Page 与外部 Agent 调用单条：`{"params":{"title":"准备评审"}}`。Page 创建多条、每条内容不同：
 
 ```json
-{"batch":[{"params":["准备评审"]},{"params":["补充文档"]}]}
+{"batch":[{"params":{"title":"准备评审"}},{"params":{"title":"补充文档"}}]}
 ```
 
 ## 多条记录设置相同值
@@ -78,17 +83,17 @@ Mutation 不声明角色；调用仍需通过应用统一准入。记录 ID 仅
 {
   "table":{"table_id":"tblTasks"},
   "operation":"update",
-  "params":[{"kind":"TEXT"},{"kind":"RECORD_ID"}],
+  "params":[{"name":"title","kind":"TEXT","description":"统一设置的新标题文本"},{"name":"taskId","kind":"RECORD_ID","description":"要改名的任务记录 ID；先调用任务列表函数取 record_id"}],
   "precondition":{"conjunction":"and","conditions":[{"field_id":"rec_id","operator":"is","param":2}]},
   "set":{"fldTitle":{"param":1}},
   "returning":["rec_id","fldTitle"]
 }
 ```
 
-调用：
+Page 调用：
 
 ```json
-{"batch":[{"params":["统一标题","recA"]},{"params":["统一标题","recB"]}]}
+{"batch":[{"params":{"title":"统一标题","taskId":"recA"}},{"params":{"title":"统一标题","taskId":"recB"}}]}
 ```
 
 每组的第 2 个参数都是单个记录 ID。
@@ -98,7 +103,7 @@ Mutation 不声明角色；调用仍需通过应用统一准入。记录 ID 仅
 复用上例声明，分别传入每条记录的标题和 ID：
 
 ```json
-{"batch":[{"params":["标题 A","recA"]},{"params":["标题 B","recB"]}]}
+{"batch":[{"params":{"title":"标题 A","taskId":"recA"}},{"params":{"title":"标题 B","taskId":"recB"}}]}
 ```
 
 批量模式按同一个声明解释每组参数，每组操作一条记录。同一请求最多 200 组，不允许重复目标 ID。`batch` 与顶层 `params` 互斥，不支持在一批中混合不同表、操作或 Function。
@@ -109,13 +114,13 @@ Mutation 不声明角色；调用仍需通过应用统一准入。记录 ID 仅
 {
   "table":{"table_id":"tblTasks"},
   "operation":"delete",
-  "params":[{"kind":"RECORD_ID"}],
+  "params":[{"name":"taskId","kind":"RECORD_ID","description":"要删除的任务记录 ID；先调用任务列表函数取 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。
+Page 调用：`{"batch":[{"params":{"taskId":"recA"}},{"params":{"taskId":"recB"}}]}`。delete 不接受 `set`，返回只能包含 record ID。
 
 ## 附件写入
 
@@ -131,7 +136,7 @@ Mutation 不声明角色；调用仍需通过应用统一准入。记录 ID 仅
 
 将上传返回的 `fileToken` 映射为 `file_token`；非图片只传 token，图片附本地读取的原始宽高，见[图片宽高](file-transfer.md#图片宽高)。
 
-`{"kind":"ATTACHMENT"}` 接收一个对象，`{"kind":"ATTACHMENT","list":true}` 接收对象数组。附件 `const` 使用数组，例如 `{"const":[{"file_token":"fileNew"}]}`。以下示例使用列表参数。
+`{"kind":"ATTACHMENT"}` 接收一个对象，`{"name":"attachments","kind":"ATTACHMENT","list":true}` 接收对象数组。附件 `const` 使用数组，例如 `{"const":[{"file_token":"fileNew"}]}`。以下示例使用列表参数。
 
 | 操作 | 声明与语义 |
 | --- | --- |
@@ -156,8 +161,8 @@ Mutation 不声明角色；调用仍需通过应用统一准入。记录 ID 仅
   "table":{"table_id":"tblTasks"},
   "operation":"append_attachments",
   "params":[
-    {"kind":"RECORD_ID"},
-    {"kind":"ATTACHMENT","list":true,"max_items":50}
+    {"name":"taskId","kind":"RECORD_ID","description":"目标任务记录 ID；先调用任务列表函数取 record_id"},
+    {"name":"files","kind":"ATTACHMENT","list":true,"max_items":50,"description":"已上传附件的 file_token 与图片宽高列表"}
   ],
   "precondition":{"conjunction":"and","conditions":[{"field_id":"rec_id","operator":"is","param":1}]},
   "set":{"fldFiles":{"param":2}},
@@ -168,13 +173,13 @@ Mutation 不声明角色；调用仍需通过应用统一准入。记录 ID 仅
 继续上传示例中的 `newAttachment`，Page 传记录 ID 和本次新增列表：
 
 ```ts
-const result = await invokeDatabaseFunction('appendTaskAttachments', ['recA', [newAttachment]])
+const result = await invokeDatabaseFunction('appendTaskAttachments', { taskId: 'recA', files: [newAttachment] })
 ```
 
-对应调用 JSON 为：
+对应 Page 调用 JSON 为：
 
 ```json
-{"params":["recA",[{"file_token":"fileNew","image_width":640,"image_height":480}]]}
+{"params":{"taskId":"recA","files":[{"file_token":"fileNew","image_width":640,"image_height":480}]}}
 ```
 
 假设原单元格已有 `fileOld`，成功响应是本次操作后的完整列表：
@@ -209,8 +214,8 @@ Page 检查一次顶层 `code`；成功后从 `data.records` 找到对应 `rec_i
   "table":{"table_id":"tblTasks"},
   "operation":"remove_attachments",
   "params":[
-    {"kind":"RECORD_ID"},
-    {"kind":"ATTACHMENT","list":true,"max_items":50}
+    {"name":"taskId","kind":"RECORD_ID","description":"目标任务记录 ID；先调用任务列表函数取 record_id"},
+    {"name":"files","kind":"ATTACHMENT","list":true,"max_items":50,"description":"已上传附件的 file_token 与图片宽高列表"}
   ],
   "precondition":{"conjunction":"and","conditions":[{"field_id":"rec_id","operator":"is","param":1}]},
   "set":{"fldFiles":{"param":2}},
@@ -221,13 +226,13 @@ Page 检查一次顶层 `code`；成功后从 `data.records` 找到对应 `rec_i
 Page 只提交待移除 token；若来自 Database Function 的附件对象，将其 `token` 填入 `file_token`：
 
 ```ts
-const result = await invokeDatabaseFunction('removeTaskAttachments', ['recA', [{ file_token: 'fileNew' }]])
+const result = await invokeDatabaseFunction('removeTaskAttachments', { taskId: 'recA', files: [{ file_token: 'fileNew' }] })
 ```
 
-对应调用 JSON 与移除 `fileNew` 后的成功响应：
+对应 Page 调用 JSON 与移除 `fileNew` 后的成功响应：
 
 ```json
-{"params":["recA",[{"file_token":"fileNew"}]]}
+{"params":{"taskId":"recA","files":[{"file_token":"fileNew"}]}}
 ```
 
 ```json
@@ -250,6 +255,7 @@ const result = await invokeDatabaseFunction('removeTaskAttachments', ['recA', [{
 
 Page 结果类型与检查（单次、批量共用）：
 
+<!-- example: mutation-result -->
 ```ts
 type MutationResult = {
   record_ids: string[]
@@ -270,8 +276,9 @@ function assertComplete(result: MutationResult) {
 
 Page 一组参数调用（对应上文 `renameTasks`，一组参数修改一条记录）：
 
+<!-- example: mutation-single -->
 ```ts
-const result = await invokeDatabaseFunction<MutationResult>('renameTasks', ['统一标题', 'recA'])
+const result = await invokeDatabaseFunction<MutationResult>('renameTasks', { title: '统一标题', taskId: 'recA' })
 if (result.code !== 0) throw new Error(result.msg || '写入失败')
 if (!result.data) throw new Error('写入结果缺失，请刷新核对')
 assertComplete(result.data)
@@ -279,17 +286,19 @@ assertComplete(result.data)
 
 Page 多组参数调用（对应上文 `createTask`，每组创建一条记录）：
 
+<!-- example: mutation-batch -->
 ```ts
-const result = await invokeDatabaseMutationBatch<MutationResult>('createTask', [['准备评审'], ['补充文档']])
+const result = await invokeDatabaseMutationBatch<MutationResult>('createTask', [{ title: '准备评审' }, { title: '补充文档' }])
 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` 中的部分结果，不重复解包。
+workspace 从已安装 SDK `/page` 导入两个 helper，并按包内 docs 核对 API；classic 按[helper 契约与导入](legacy-development.md#function-调用契约)选择实际形态。返回 `{code, data?, msg?}`。先检查顶层业务码，再检查 `data` 中的部分结果，不重复解包。
 
-CLI 调用沿用项目级路由：
+CLI 调用使用项目级路由，按[调用站点函数](agent-tools.md#调用站点函数)先读取函数说明，再按参数名传对象：
 
 ```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
+base-database-cli lark-cli -- api GET '/open-apis/base/v3/sites/<app-token>/functions/<function-id>' --params '{"env":"preview","includeInternal":true}' --json
+base-database-cli lark-cli -- api POST '/open-apis/base/v3/sites/<app-token>/functions/<function-id>/invoke' --params '{"env":"preview","includeInternal":true}' --data '{"batch":[{"params":{"title":"准备评审"}},{"params":{"title":"补充文档"}}]}' --json
 ```

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

@@ -43,6 +43,6 @@
 
 应用 Prod 发布成功后，使用本次返回的生产 `baseAppUrl`，按 Preview 清单逐一 get → 必要的完整 update → get。site_action 只替换环境入口，保留功能定位参数、动态对象参数、其他步骤和启停状态；最终链接不含 `mode=edit`。已有链接正确时仍回读核对，不做无变化写入。其他策略保留入口意图并复核状态。
 
-已有生产应用的 Preview 迭代不得把正在服务生产用户的 workflow 链接改为 owner-only Preview。先核对原链接与使用范围：保留生产入口，将新 Preview 的功能参数列入待切换清单；需要独立通知测试时，仅在用户授权的隔离测试流程中执行。
+已有生产应用的 Preview 迭代不得把正在服务生产用户的 workflow 链接改为 仅管理者可访问的 Preview（准入见[权限设计](permission-design.md#preview-与-prod-准入)）。先核对原链接与使用范围：保留生产入口，将新 Preview 的功能参数列入待切换清单；需要独立通知测试时，仅在用户授权的隔离测试流程中执行。
 
 任一切换失败时分别报告应用发布与通知切换状态；修复后只恢复失败步骤。发布应用不会自动迁移外部 workflow，也不授权发送额外测试通知。

package/skills/lark-base-database/references/permission-design.md

@@ -8,9 +8,9 @@
 
 应用在飞书里是一篇多维表格文档。当前平台的权限事实：
 
-- **应用访问准入**：能打开 Prod 应用的人 = 对这篇应用文档有阅读权限的人。范围由文档分享设置决定，掌握在用户手里，应用代码无法收窄它。Preview 环境只有应用 owner 本人能访问。Prod/Preview 是发布态，与 CLI 的部署环境分别判定。
+- **应用访问准入**：能打开 Prod 应用的人 = 对这篇应用文档有阅读权限的人。范围由文档分享设置决定，掌握在用户手里，应用代码无法收窄它。Preview 准入按[Preview 与 Prod 准入](#preview-与-prod-准入)判定。Prod/Preview 是发布态，与 CLI 的部署环境分别判定。
 - **数据访问以 owner 身份执行**：应用读写 Base 数据一律以应用 owner 的身份进行，访问者本人对底层 Base 有没有协作权限不参与判定。底表的原生高级权限（行列权限）不约束应用访问者的读取——原生权限管的是直接打开多维表格的人，应用是另一个入口，两边要分别设计；应用内的读取范围由 Database Function 自己写了什么决定。
-- **调用边界**：访问者可绕过 UI 调用已发布 Function。Mutation 固定表、操作、字段和值来源，不声明或执行角色规则，调用沿用应用统一准入；自定义角色与统一行列权限后续接入。配套服务端已关闭三个浏览器直接记录 CRUD 入口；受 FaaS ticket 保护的记录与附件回调保留兼容，必须逐个审查已发布 FaaS 的固定输入与校验。UI 显隐、路由守卫和前端校验只是体验，不是边界。
+- **调用边界**：访问者可绕过 UI 调用已发布 Function。Mutation 固定表、操作、字段和值来源，不声明或执行角色规则，调用沿用应用统一准入；自定义角色与统一行列权限后续接入。配套服务端已关闭三个浏览器直接记录 CRUD 入口；FaaS 通过[固定记录写入路由](faas.md#应用记录写入协议)写入，不受 Mutation 声明约束，须在 FaaS 内校验输入与调用者身份。UI 显隐、路由守卫和前端校验只是体验，不是边界。
 - **可信身份**：Database Function 使用服务端注入的 `CURRENT_USER_ID()`；Mutation 的 `current_user` 同样由服务端注入，可用于写入人员字段。两者都不能由调用参数覆盖。Page/FaaS 的业务参数不能自报可信身份；FaaS 通过固定 Database Function 检查身份。
 - **FaaS 不是更高权限**：FaaS 与 Page 的数据读写权限完全相同。
 
@@ -32,7 +32,7 @@
 
 **判定**：对每张要 bind 的表问——它最敏感的字段被分享范围内任何人读到、最关键的记录被任何人改掉或删掉，业务能否接受？
 
-**设计目标与当前限制**：绑定范围应只包含业务可接受暴露的表。当前 CLI init 会绑定目标 Base 全部表，不支持选表初始化；执行前按[工程与环境](workspace.md#需求与-base-定位)核对范围。不能将“只绑定必要表”当成现有 CLI 参数。读判定不通过时，重新选择可整体绑定的数据范围；当前 init 不支持在同一 Base 内仅将敏感字段分表后排除绑定。写判定不通过时，审查每个已发布 Mutation/FaaS：是否固定表和字段、是否核验可信身份、是否允许修改角色来源。不能暴露通用 patch 或动态路由。部署到尚未关闭浏览器 CRUD 的旧服务端时，仍存在绕过声明的直接写入风险，不能仅凭 CLI 版本承诺已经收口。
+**设计目标与当前限制**：绑定范围应只包含业务可接受暴露的表。当前 CLI init 会绑定目标 Base 全部表，不支持选表初始化；执行前按[工程与环境](workspace.md#需求与-base-定位)核对范围。不能将“只绑定必要表”当成现有 CLI 参数。读判定不通过时，重新选择可整体绑定的数据范围；当前 init 不支持在同一 Base 内仅将敏感字段分表后排除绑定。写判定不通过时，审查每个已发布 Mutation/FaaS：是否固定表和字段、是否核验可信身份、是否允许修改角色来源。不能暴露通用 patch 或动态路由。
 
 ## 读路径：Database Function 就是策略面
 
@@ -122,11 +122,17 @@ FaaS 调用 Database Function 与写入的协议见[FaaS 协议](faas.md#faas-
 - bind 了敏感表，靠「页面没做那个功能」当保护。
 - 以为底表开了高级权限，应用访问者也随之受约束。
 - FaaS 校验的依据是页面传入的 user id、角色或 isAdmin 标记。
-- 把「还在 Preview、没人看得到」当作暂缓权限设计的理由——Preview 的 owner-only 是环境属性，发布 Prod 不会自动带来任何权限。
+- 把「还在 Preview、没人看得到」当作暂缓权限设计的理由——Preview 的管理者准入是环境属性，发布 Prod 不会自动带来任何权限。
 
 ## 交付与验收
 
 - 交付说明中包含访问模型结论：分享面假设、按人/按角色的可见性设计，以及写敏感表的残余风险（如有）。
 - 对外分发或扩大分享范围前，提醒用户核对应用文档的分享设置——该设置决定访问准入，不能由页面代码代替。
-- 角色化行为在 Preview 无法由 owner 之外的人验证（Preview 仅 owner 可访问，`CURRENT_USER_ID()` 恒为 owner）；多角色验收在 Prod 环境用真实账号完成，交付时说明这一限制。
+- Preview 可验证已授权管理者的行为，不能据此证明普通成员/访客的行为；身份和覆盖边界见[Preview 与 Prod 准入](#preview-与-prod-准入)。普通成员多角色验收在已授权的 Prod 任务中用真实账号完成。
 - 修改原生 Base 角色或高级权限、删除 binding 属于危险操作，按 [Skill 主流程](../SKILL.md#外部操作与授权)核对具体目标和影响范围的授权。
+
+## Preview 与 Prod 准入
+
+Page 的应用读取/Function 调用与 OpenAPI 的 Function 发现/调用，在 Preview 均要求应用 Owner 或 Site ADMIN；普通 EDITOR/VIEWER 不因此获得 Preview 准入。Prod 允许 Owner 或具备任一有效 Site 角色的成员进入，具体分享与成员范围由用户配置。宿主“可编辑”状态不能由角色名称自行推断，要以平台回执为准。
+
+调用者身份取服务端认证上下文：`CURRENT_USER_ID()` 和 Mutation current_user 对应该实际调用者，不固定为 Owner；底层 Base 数据访问仍按上文 owner 权限执行，不能混淆身份过滤与数据访问凭证。OpenAPI 另受开放能力/exclude 策略影响（见[站点 Skill](agent-tools.md#判定)），Page 不受该发现过滤；这不改变 Preview 的管理者准入要求。Owner 单账号通过不证明 ADMIN 或普通成员的业务权限正确。

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

@@ -4,7 +4,7 @@
 
 ## 站点 README
 
-新建站点时，先从用户原始建站 Prompt 的主要自然语言确定 README 语言：支持中文、日文、英文；其他语言或无法判断主要语言时使用英文。用户明确指定 README 使用这三种语言之一时按其指定语言填写；指定其他语言时仍使用英文。初始化生成的项目根目录 `README.md` 是英文模板，须按选定语言改写全部面向人的标题与正文，替换全部 `{{...}}` 占位内容；命令、路径和代码标识符保留原样。修改已有站点时沿用现有 README 语言，除非用户明确要求切换。README 是生成时确定的源码文档，不随 Site 运行时的宿主或浏览器语言变化。
+新建站点时，先从用户原始建站 Prompt 的主要自然语言确定 README 语言：支持中文、日文、英文；其他语言或无法判断主要语言时使用英文。用户明确指定 README 使用这三种语言之一时按其指定语言填写；指定其他语言时仍使用英文。读取初始化生成的项目根目录 `README.md`，按选定语言重写业务标题与正文、清理 hello 示例，并移除实际存在的占位内容；命令、路径和代码标识符保留原样。修改已有站点时沿用现有 README 语言，除非用户明确要求切换。README 是生成时确定的源码文档，不随 Site 运行时的宿主或浏览器语言变化。
 
 四个必要章节使用下表中所选语言的标题；CLI 接受这三组标题，并只检查结构、占位符和章节是否非空，不判断正文语言或业务描述是否属实：
 
@@ -23,6 +23,10 @@
 
 README 不放客户真实数据、凭证、token 或内部调试日志。CLI 在本地 `check` 和部署前检查 README 是普通文件、已删除模板占位内容且包含非空的必要业务章节；未通过时不会上传。通过后将 README 放入 `site.zip` 的根路径，远端 `pull` 可恢复。Prod 复用 Preview 的同一制品，不重新打包上传；调用 `deploy --production` 前也要核对 README，若需修改则先更新并重新发布 Preview，再取得针对新制品的确认。README 是源码制品的一部分，不会自动显示在站点页面上。
 
+## 制品指纹
+
+README、源码、配置和部署依赖属于 Preview 制品输入，变化后先重发 Preview 再确认 Prod。workflow 定义及独立验收材料不作为部署输入；它们仍须按任务约定完成，不能据未纳入指纹省略验收。
+
 ## 发布前
 
 确认工程与应用一致并保留需求外 Function。涉及视觉的变更按[前端设计指南](frontend-design-guide.md#交付前自检)检查；涉及通知先按[通知集成](notifications.md)确定路由、资源范围和启停策略。
@@ -33,9 +37,9 @@ README 不放客户真实数据、凭证、token 或内部调试日志。CLI 在
 base-database-cli check --json
 ```
 
-该命令先按本地 Database Function/Mutation/FaaS metadata 更新 Page Function 输入类型，再可能安装 Page/FaaS 依赖并写入本地构建输出；不要手改生成类型，不要猜测 `node_modules` 路径或分别运行子项目安装命令。`--json` 保证成功和失败都返回一个结构化 JSON 文档；成功结果用 `functions["database-functions"]`、`functions["mutation-functions"]` 和 `functions["server-functions"]` 计数。失败时按 `error.stage`、`error.diagnostics` 和 `nextActions` 修复一次，再重新运行同一命令。成功的 Page/FaaS 构建会分开缓存，重试只重建输入变化或上次失败的一侧，不要为了重试默认添加 `--force-build`。它不调用应用 API、不发布，也不执行服务端查询语法、Catalog/binding 或业务运行态验证；这些仍由 `deploy` 及后续验收完成。
+check 的依赖准备、契约核对、`CONTRACT_STALE` 恢复和无 SDK classic 自动生成条件统一见[本地检查与契约生成](development.md#本地检查与契约生成)。该命令只做本地验证，不替代服务端查询校验或真实运行态验收。
 
-依赖安装使用 CLI 随包固定的 npm，不受宿主 PATH 中 npm 版本影响。CLI 在安装前获取目标应用的服务端依赖策略，并校验最终制品范围内全部 `package.json`；受限来源、非法 manifest 或策略查询失败时不会安装、构建或上传。添加依赖时的查询与判断见[第三方依赖策略](development.md#第三方依赖策略)。安装失败时保留子项目路径、npm 版本与原始错误：lock 不一致先核对本次 `package.json` 变更，按 CLI 错误提示修复该子项目的 lock 并检查差异，再重试一次；网络或权限错误先解决对应原因。不要盲删 lock、循环切换 npm 版本，也不要用 `--no-install` 掩盖安装失败；重试仍失败时保留证据并定位原因，不自动报告部署成功。
+依赖安装使用 CLI 随包固定的 npm，不受宿主 PATH 中 npm 版本影响。Preview deploy 在安装前获取目标应用的服务端依赖策略，并校验最终制品范围内全部 `package.json`；受限来源、非法 manifest 或策略查询失败时不会安装、构建或上传。添加依赖时的查询与判断见[第三方依赖策略](development.md#第三方依赖策略)。安装失败时保留子项目路径、npm 版本与原始错误：lock 不一致先核对本次 `package.json` 变更，按 CLI 错误提示修复该子项目的 lock 并检查差异，再重试一次；网络或权限错误先解决对应原因。不要盲删 lock、循环切换 npm 版本，也不要用 `--no-install` 掩盖安装失败；重试仍失败时保留证据并定位原因，不自动报告部署成功。
 
 ## Preview
 
@@ -47,7 +51,7 @@ base-database-cli check --json
 base-database-cli deploy
 ```
 
-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)）。
+CLI 先解析账号环境、查询依赖策略并校验 package.json 来源，再安装依赖、提取 SDK 契约、检查声明与查询、构建 Page/FaaS、归档和发布。安装仍早于依赖 SDK 的契约提取；查询校验失败不继续构建。Function 同步与失败恢复按[发布顺序与错误边界](#function-发布顺序与错误边界)处理。
 
 等待命令完成，进程仍在运行不代表失败，不重复启动部署。只有发布成功响应中的顶层 `baseAppUrl` 是可信交付入口，制品大小、SHA-256 和 publish ID 用于追溯。不能用历史 URL、管理后台、Catalog 或内部 `staticUrl` 替代缺失入口。
 
@@ -82,22 +86,32 @@ CLI 负责 Function metadata、全量查询校验、必要依赖安装、Page/Fa
 
 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`。CLI 输出外层是 lark-cli 的 `ok`/`data`：`ok:true` 时 `data` 才是 Function 的 `{code,msg,data}` 信封，非零业务码会变成 `ok:false` 并在 `error` 中给出；判定方式见[开发期与运行态输出](development.md#开发期与运行态输出)。检查 Function 顶层业务码与 ResultJSON，并确认刚写入的示例记录、关系和统计真实可见。
+3. 存在列表、详情、看板、统计等业务数据展示时，通过项目路由调用页面实际使用的 Database Function，而不是用 `+record-list` 代替展示链路验收：先 `base-database-cli lark-cli -- api GET /open-apis/base/v3/sites/<app-token>/functions/<function-id> --params '{"env":"preview","includeInternal":true}' --json` 读取 `inputSchema` 与 `requestExample`，再按参数名调用 `base-database-cli lark-cli -- api POST /open-apis/base/v3/sites/<app-token>/functions/<function-id>/invoke --params '{"env":"preview","includeInternal":true}' --data '{"params":{...}}' --json`，规则见[调用站点函数](agent-tools.md#调用站点函数)。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。
 
 该闭环不需要浏览器，也不替代用户对 Page 真实写入流程、交互状态和 UI 的 E2E 验收，更不构成 Prod 发布授权。不得读取、输出或代填用户凭证。
 
+## Function 发布顺序与错误边界
+
+Preview 将 sql/edge/mutation 与本地非空且未跳过的 ai 放入同一次 `/functions` PUT；PUT 成功后才同步 agent-tools 策略、上传 Artifact 并发布 Preview。不先单独同步 AI。空 ai/ 或 `--skip-ai-functions` 不声明 ai kind，保留远端 AI；交付时说明 AI 未同步及未验证。
+
+Prod 提升已完成的 Preview，不重新执行 Function PUT，不单独同步 AI，也不重新构建或上传制品。`--skip-ai-functions` 不会把尚未生成的新 Preview 混入 Prod。
+
+这些步骤不是跨 Base 绑定、Function、策略、Artifact 与发布的事务。Function PUT 前可能已经更新 Base 绑定，之后的步骤也可能部分完成。确定的校验或 feature gate 错误按原因修正；超时、断网或结果未知先通过已有发布 ID、绑定与 Function 只读查询核对已执行状态，再决定下一步，不能据此断言远端状态未变更或盲目重跑写入。普通建站不需要额外执行 `ai-functions sync`；该显式命令会独立全量覆盖草稿，包括空集合删除，须有对应授权。
+
 ## Prod
 
+发布前按[外部 Agent 工具策略](agent-tools.md)核对开放清单。
+
 用户体验本次 Preview 并明确授权发布同一制品后执行；授权判定见[主流程](../SKILL.md#外部操作与授权)。
 
 ```bash
 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 记录缺失或与当前工程不一致时，重新生成 Preview 并取得确认。`--yes` 只是向 CLI 传递已有授权。
 
 Prod 发布不会自动更新 Base workflow。存在通知集成时，按 Preview 留存的清单逐个完成[生产入口切换](notifications.md#生产入口切换)。切换失败则明确报告“Prod 已发布，但通知入口切换未完成”，保存失败对象与证据；不重复发布应用来掩盖外部配置失败。
 
@@ -105,9 +119,10 @@ Prod 发布不会自动更新 Base workflow。存在通知集成时，按 Previe
 
 默认按用户使用顺序交付，内容以本次实际完成和验证的范围为准：
 
-1. **状态与入口**：说明是 Preview 还是已获授权的 Prod，以及完成、部分完成或阻塞状态。访问链接只使用本次成功发布的 CLI 返回的 `baseAppUrl`；发布未成功或入口缺失时不猜测链接。`staticUrl`、制品地址和 Builder iframe 地址仅用于内部预览与追溯。
+1. **状态与入口**：说明是 Preview 还是已获授权的 Prod，以及完成、部分完成或阻塞状态。访问链接只使用本次成功发布的 CLI 返回的 `baseAppUrl`；发布未成功或入口缺失时不猜测链接。`staticUrl` 和制品地址仅用于内部预览与追溯。
 2. **业务结果与体验**：列出本次实现的功能或变更，以及用户可直接执行的体验步骤。新建 Base 的示例数据说明覆盖的业务对象和页面 Database Function 回读结果；复用或修改已有应用时不声称添加了示例数据。
 3. **验证与待处理项**：逐项说明实际通过的检查及其范围；未执行的页面交互、角色权限或生产验证标为未验证。失败、结果未知、通知未完成时，给出具体影响和下一步，不把 Preview 发布成功等同于整个任务完成。
+4. **本地 Agent 的业务用法**：Prod 发布后，按 `nextAction.externalAgent.skillCommand` 读取站点 Skill 中 SKILL.md 的函数清单，用业务语言补充“可用能力”，只写清单中实际存在的能力，不从本地源码臆测。将 `nextAction.externalAgent.handoff.markdown` 完整原样附上，保留全部文字、换行和 Markdown 格式；不改写或删节。Skill 暂不可获取时说明情况并省略能力清单，不影响发布成功。Preview 交付只附引导，说明正式版发布后外部 Agent 才能安装使用。后续追问可简短回答或指向已给出的交付内容。本地安装或 Prod 发布仍遵循各自授权条件，不因展示交付块而自动执行。
 
 命令、Function ID、制品摘要和 workflow 清单保留为可追溯证据，按研发或排障需要展示，不要求业务用户检查 header 或 SDK 协议。
 

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

@@ -9,11 +9,11 @@
 | 失败阶段 | 首先检查 | 恢复边界 |
 | --- | --- | --- |
 | 命令或认证 | 当前版本、help、身份与具体授权错误 | 按当前 CLI 文档恢复原身份，不自动切 bot |
-| 初始化/恢复 | 已创建资源、宿主来源、配置和本地文件 | 创建结果未知先确认现状，不以重跑 init 掩盖失败 |
+| 初始化/恢复 | 已创建资源、工程来源、配置和本地文件 | 创建结果未知先确认现状，不以重跑 init 掩盖失败 |
 | 查询校验 | Catalog、参数声明、失败节点与支持集 | 缩小到具体错误，不通过猜参数类型绕过 |
 | 构建 | Page/FaaS 编译错误、依赖与模板调用契约 | 修复实现，不伪造类型让错误协议编译通过 |
 | 发布 | publish ID、真实状态、制品与返回入口 | 使用[发布任务查询](#发布任务查询)确认现状，不盲目启动第二次发布 |
-| Page/Function | HTTP 状态、业务码、输入输出与 invoke LogID | 按 [Page](development.md)、[Database Function](database-function.md)、[Mutation](mutations.md)、[FaaS](faas.md) 分层定位；旧工程或 CSRF 失败按[专项检查](#旧工程与-csrf-排查)处理 |
+| Page/Function | HTTP 状态、业务码、输入输出与 invoke LogID | 按 [Page](development.md)、[Database Function](database-function.md)、[Mutation](mutations.md)、[FaaS](faas.md) 分层定位 |
 | 通知与原生配置 | 目标资源完整定义、入口、状态与失败节点 | 按[通知状态](notifications.md#状态与失败处理)保留授权范围 |
 
 ## 发布任务查询
@@ -29,30 +29,39 @@ base-database-cli deployments status <publish-id> --wait
 
 返回的 `statusText` 为 `pending`、`processing`、`succeeded`、`failed` 或 `unknown`，对应数字 `status` 的 `0`、`1`、`10`、`20`。查询成功不等于发布成功，按 `statusText` 判断；成功后使用返回的 `baseAppUrl`。失败、未知状态或再次超时先保存证据，再决定修复，不自动再次 deploy。没有 publish ID 时先检查已有输出和任务记录，不通过创建新发布寻找结果。
 
-## 旧工程与 CSRF 排查
+## 验证方法
 
-更新 CLI 或 Skill 不会自动改写已有工程；`pull` 恢复的是应用保存的源码，可能仍包含旧依赖和构建配置。
+通过 `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` 判定协议不符。
 
-1. 迁移旧工程时，先确认业务 HTTP、Function 和附件调用均通过 `page/src/lib/database-runtime.ts` 接入 `@lark-base-open/base-site-channel/runtime`，按当前 starter 补齐宿主接入，保留业务逻辑。
-2. 移除 `page/vite.config.ts` 中来自 `@lark-base-open/base-site-js/vite` 的导入和 `createArgusCsrfPlugin()`，确认没有其他旧 SDK 引用后删除 `page/package.json` 中的 `@lark-base-open/base-site-js` 并更新锁文件。清理旧工程自行复制的 Argus 注入代码或 HTML 脚本，构建配置以当前 starter 为准。
-3. 请求失败时，区分 Page 到父页面的代理通信、父页面实际发出的请求和 FaaS 下游失败，核对登录、资源权限、业务参数、HTTP/业务码与 LogID。业务请求的身份与 CSRF 处理属于宿主；单独的 403 不足以判定为 CSRF，也不是向 Page 补装旧 SDK 或注入 CSRF 脚本的依据。
-4. 修改后重新安装依赖、构建并发布 Preview，在实际宿主页面中按授权范围复验受影响的读取、写入和附件调用。没有运行态条件时报告本地验证结果和待验证项；Prod 仍需针对新制品确认。
+静态检查、构建、查询编译、部署成功分别证明对应阶段，不证明完整业务链路。新建 Base 的常规验证或发布后补齐示例数据，先完整读取并执行[示例数据验收](release.md#从零建站示例数据验收)，其中包含 CLI 写入格式和页面 Database Function 回读的实际路径；用户明确要求运行态验收时可以追加本次范围内的只读 Database Function 调用和可用浏览器检查。
 
-Page 不读取宿主 Cookie、不手写 CSRF Header，也不通过直连业务域名绕过宿主。宿主请求仍失败时保留脱敏证据继续定位，不把构建通过当作运行态验证通过。
+AI 与其他 Function 的 Preview/Prod 发布顺序、skip 行为和错误恢复统一见[发布参考](release.md#function-发布顺序与错误边界)。`ai-functions validate` 是编辑期可选自检。
 
-## 验证方法
+写入验收先确认目标、测试数据和用户授权，尤其已有 Base、业务通知和不可逆操作。不得仅为测试而创建生产业务记录或外发消息。用户要求的写入验证完成后，清理仍遵守同一资源操作的授权要求。
 
-通过 `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` 判定协议不符。
+浏览器不可用、没有必要登录态或 Preview 不支持多角色时，报告未验证项和恢复条件，不索取或输出原始 Cookie/Token。Preview 的可用角色与身份见[Preview 与 Prod 准入](permission-design.md#preview-与-prod-准入)，单账号通过不能作为多角色权限验收；普通成员检查需在已授权的 Prod 任务中进行。
 
-静态检查、构建、查询编译、部署成功分别证明对应阶段，不证明完整业务链路。新建 Base 的常规验证或发布后补齐示例数据，先完整读取并执行[示例数据验收](release.md#从零建站示例数据验收)，其中包含 CLI 写入格式和页面 Database Function 回读的实际路径；用户明确要求运行态验收时可以追加本次范围内的只读 Database Function 调用和可用浏览器检查。
+## AI 验收判定
 
-`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 时报告未验证项并继续。
+AI Function 调试至少有三种互不等价的「成功」，不能互相替代地报告：
 
-`deploy` 按本地 `ai/` 全集同步 AI Function；空 `ai/` 时自动跳过，不调 AI Function 接口，未涉及 AI 的应用无需开通。需要让本次发布完全不动 AI Function 时加 `--skip-ai-functions`（Preview、Prod 均适用），并在交付或验收报告中说明 AI Function 未同步且未验证，不宣布其已上线。
+- **配置校验成功**：deploy 内配置校验通过，或可选的 `ai-functions validate` 返回 data 中的 `valid === true` 且 `results` 各项 `code === 0`，只证明 `meta.json` 合法，不代表能跑通。
+- **运行态调用成功**：接口能返回文本或 `taskId`，证明 Function 存在、未 `disabled`、鉴权与模型链路初步可用。CLI 对 text/vision 返回聚合文本。
+- **UI 流式成功**：页面 `onMessage` 多次收到增量并实时渲染，证明 SDK 回调与业务组件的增量显示已接通。
 
-写入验收先确认目标、测试数据和用户授权，尤其已有 Base、业务通知和不可逆操作。不得仅为测试而创建生产业务记录或外发消息。用户要求的写入验证完成后，清理仍遵守同一资源操作的授权要求。
+尤其对文本 AI Function：CLI 聚合返回成功或超时，都**不能**直接判断页面 SSE 是否正常。页面选择 `invokeSiteAIFunctionStream` 时，用真实页面验证多次 `onMessage` 增量和单次 `onDone`，错误时为 `onError` 且无 `onDone`；选择 `callSiteAIFunction` 聚合时，验证得到 `{type:'text'}` 和完整 `content`。媒体能力用 task 接口验证终态。
+
+普通建站未做运行态检查时列为未验证；用户要求验收时按所选调用方式验证 Preview。Prod 是否验证按用户诉求决定。
+
+读取 `ai-functions validate --json` 的 stdout 时，CLI 直接输出 data 对象；按下面的判定读取（不再解一层 data）：
 
-浏览器不可用、没有必要登录态或 Preview 不支持多角色时，报告未验证项和恢复条件，不索取或输出原始 Cookie/Token。Preview 仅 owner 可访问，不能将 owner 单账号通过作为多角色权限验收；生产账号检查需在已授权的生产任务中进行。
+<!-- example: ai-validation-result -->
+```js
+const data = JSON.parse(stdout);
+const configurationValid = data.valid === true &&
+  Array.isArray(data.results) &&
+  data.results.every(result => result != null && result.code === 0);
+```
 
 ## 重试与失败证据
 
@@ -61,3 +70,33 @@ Page 不读取宿主 Cookie、不手写 CSRF Header，也不通过直连业务
 保存环境、应用、阶段、必要的 method/path、publish ID、HTTP/业务码、脱敏摘要与 LogID/Edge request ID；访问 URL 返回 404/5xx 时保存真实 URL 和响应证据。不记录凭证、完整 headers、堆栈或与问题无关的数据，不猜替代域名或回退其他环境。
 
 输出本次检查范围、证据、定位结论、已修复项和未验证项。证据不足时区分推断与已确认事实；按[完成条件](../SKILL.md#完成条件)报告状态。
+
+
+## agent-browser 预览验证工作流
+
+需要开发自检、复现页面问题或执行约定的运行态验收时，用 agent-browser 驱动真实 Chrome 打开 Preview。先读取工程 AGENTS.md 的平台段落，API 用法按实际安装 SDK 的 docs；无 SDK 的工程按[老模板参考](development.md#老模板参考)。此流程只编排浏览器取证。
+
+1. 运行 `base-database-cli check --json`，通过后运行 `base-database-cli deploy`，取成功结果中的完整 `baseAppUrl`，不拼接 token 或使用静态制品地址。已有待验 Preview 时直接使用其回执。旧 CLI 尚无 `dev` 命令时继续使用此流程；使用 dev 前先检查本机 `--help` 是否支持。
+2. 先用 `agent-browser --help` 核对可用命令，选择独立 session 和已获授权的 Chrome profile；打开返回的宿主地址，让页面在宿主 iframe 中运行。需要登录时由用户在该 profile 完成，不导出登录态。
+3. 保存初始 snapshot，按本次验收目标操作页面，等待可观察的加载结果；读取控制台、未捕获异常及网络请求，保存截图。网络观察应在复现前开始；宿主代发的请求需同时观察顶层页面，不只看 iframe。
+4. 将错误与本次动作关联，记录应用、Preview 环境、回执制品版本、时间、错误码和可得的 requestId/logid；区分构建错误、宿主拒绝、Function 业务错误和浏览器限制。HTTP 200 不代替业务结果成功，截图不代替数据回读。
+5. 修复后重跑受影响路径并保留前后证据；不把未执行项写成通过。写入和外部副作用仅在已授权验收范围内执行，结果未知先回读。
+
+以下 `preview_url` 是从本次 deploy 返回值取得的完整 URL，`evidence` 是本次证据目录：
+
+```bash
+mkdir -p "$evidence"
+agent-browser --session base-app-verify open "$preview_url"
+agent-browser --session base-app-verify snapshot -i
+# 先开启观察，再复现，避免漏掉首次操作产生的信号：
+agent-browser --session base-app-verify console --json
+agent-browser --session base-app-verify errors --json
+agent-browser --session base-app-verify network requests --json
+# 按 snapshot 中的实际 ref 操作，复现目标问题后采集：
+agent-browser --session base-app-verify console --json
+agent-browser --session base-app-verify errors --json
+agent-browser --session base-app-verify network requests --json
+agent-browser --session base-app-verify screenshot "$evidence/preview.png"
+```
+
+外链弹窗验证需使用未设置 `--disable-popup-blocking` 的真实 Chrome；不要通过关闭浏览器保护来制造成功。只保存脱敏后的诊断摘要，不落盘 cookie、Authorization 或其他凭据；网络详情及 HAR 可能包含这些数据，不能直接作为共享证据。

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

@@ -0,0 +1,86 @@
+# 工程迁移
+
+当用户选择把存量 classic 工程迁到 workspace，或需要核对自定义 helper 的输入契约时阅读。迁移由 coding agent 审阅并修改工程，CLI 负责配置、契约、类型与构建校验，不改写用户代码。classic 可继续开发和发布；迁移不是普通 check/deploy 的前置条件。
+
+## 迁移范围与目标
+
+先确认本次目标：只明确 classic 的输入声明，还是完整迁到 workspace。沿用用户已给出的迁移授权；尚未授权时说明目录、依赖和调用方变化后确认。操作前用工程 Git 提交或外部备份保存可恢复版本；不要覆盖未归档的用户改动。
+
+workspace 的目录、锁文件及构建模式以[工程目录与构建模式](workspace.md#工程目录与构建模式)为准。目标使用根 workspaces 管理 page 与 server、根 lockfile、已发布兼容的 App SDK。保留 appToken、bindings、larkProfile、catalog、SQL/Mutation/AI 定义及业务源码，不创建新的远端应用或 Base。Node 22+ 用于 workspace 与契约生成。
+
+## classic 输入声明
+
+输入模式只由工程合同决定，不检查 helper 的内容、位置或 SDK 安装情况：
+
+- workspace（template.version 2）及 SDK codegen 生成的 client 使用 named。
+- classic 显式声明 `functionInputs: "named"` 或 `"positional"` 时按声明生成其 Page/helper 类型。
+- classic 未声明时默认使用 positional。
+
+SDK client 的命名映射与 classic helper 映射分开生成；安装 SDK 不会改变 classic 的显式声明或默认模式。声明只选择类型，**不改变实际请求**。随 CLI 包提供的 classic 参考 helper 使用命名参数协议；引用该 helper 的 classic 工程必须在 `base-database.jsonc` 显式声明 `functionInputs: "named"`。其他自定义命名 helper 同样需要该声明；位置数组调用者使用 positional 或省略声明。归档与 pull 保留此工程合同，账号、应用标识、绑定及环境由恢复目标重建。workspace 不能声明 positional。
+
+coding agent 修改调用协议时，核对 helper、全部调用方和服务端冻结参数；必要时使用不联网请求替身确认最终 URL 与请求体。不以看到某个字符串或导入来推断业务行为。旧 `/invoke_function/<id>` 的 SQL/Mutation 使用位置数组；统一 `/functions/<id>/invoke` 使用名称对象；FaaS 以自身契约为准。
+
+该声明与输入协议的关系是唯一判定说明；页面示例及生成模块见 [Function 调用契约](development.md#function-调用契约)。
+
+## 逐步迁移
+
+1. 盘点 package.json、锁文件、页面入口、helper 的自定义行为、全部 Function 调用和服务端入口。记录当前 check 与业务行为，不把已有失败归为迁移引入。
+2. 将 `server-functions/` 迁到 `server/`，保留每个函数的 index.ts/meta.json 及依赖。对照当前 workspace starter 的根/page/server 清单整合 workspaces、脚本、TypeScript 配置。不要直接覆盖业务 package.json；检查自定义 pre/post 脚本。仅保留根 lockfile，使用工程选定 registry 安装并生成根锁，再以 npm ci 验证可复现。审核新增/升级依赖，不改成浮动版本来消除冲突。
+3. 在配置中设置 `template: {"name":"database-starter","version":2}`。移除 classic 的 positional 声明，或显式设 named；其他身份/绑定字段保持业务含义。不要只改 template 而留下 server-functions 或子目录锁文件。
+4. 安装已发布兼容的 SDK，并阅读已安装包文档。按 [dev 页面 bootstrap](development.md#dev-页面-bootstrap) 接入启动、providers、ready/dispose，保留唯一 React 挂载点。SDK 缺失/不支持时报告具体依赖阻塞，不复制另一版本的内部实现。
+5. 逐调用核对参数名、返回信封和错误处理，按下面示例把旧位置数组改为命名对象。检查别名、转导出、回调与动态导入，不能只搜索直接调用。自定义 helper 中的业务扩展迁到独立模块；确定所有消费者已适配后才移除 helper 或改用 SDK 导出。附件与 AI 分别遵循[文件传输](file-transfer.md)、[AI Function](ai-function.md)，不要复制 classic 专用实现进 workspace。
+6. 服务端传统 handler 可以保留；使用 defineFunction 时按 [FaaS](faas.md) 定义输入/输出与参数 description。编辑 contract.ts 等源文件，不手改生成的 meta 契约或 Page 类型。
+7. 执行下文校验；失败时保留诊断，修复后重跑相关检查。需要撤回时从本次保存的 Git/备份恢复并复查差异；CLI 不提供自动回滚。未经发布授权不执行远端写入。
+
+## 改前与改后
+
+假设已核实 searchTasks 的冻结声明只有参数 status。SQL 内 `$1` 表示声明顺序，不等于统一路由接受位置数组。
+
+改前（已确认使用旧路由的 classic）：
+
+<!-- example: migration-positional -->
+```ts
+import { invokeDatabaseFunction } from './lib/database-runtime';
+const result = await invokeDatabaseFunction<{ rows: unknown[] }>('searchTasks', ['进行中']);
+if (result.code !== 0 || !result.data) throw new Error(result.msg);
+export const rows = result.data.rows;
+```
+
+改后先确认已安装 SDK 的类型扩展协议。对于只导出输入映射的生成模块，在独立源码 `page/src/function-inputs.ts` 连接 SDK；不改生成文件，不复制一份参数定义。已有生成客户端提供同一扩充时核对后复用，避免冲突。
+
+<!-- example: migration-input-augmentation -->
+```ts
+import type { DatabaseFunctionInputMap as GeneratedInputs } from './generated/function-inputs';
+import '@lark-base-open/base-database-app-sdk/page';
+declare module '@lark-base-open/base-database-app-sdk/page' {
+  interface DatabaseFunctionInputMap extends GeneratedInputs {}
+}
+```
+
+改后（workspace SDK，加载上述扩充）：
+
+<!-- example: migration-named -->
+```ts
+import type {} from './function-inputs';
+import { invokeDatabaseFunction } from '@lark-base-open/base-database-app-sdk/page';
+const result = await invokeDatabaseFunction<{ rows: unknown[] }>('searchTasks', { status: '进行中' });
+if (result.code !== 0 || !result.data) throw new Error(result.msg);
+export const rows = result.data.rows;
+```
+
+多参数逐项对照已发布名称；SQL 数组参数作为对应属性的数组值，不把整个 params 写成数组。可选、nullable、enum 不因换路由而丢弃。部分完成与未知写入遵循[结果与错误](agent-tool-design.md#结果与错误)，不能为迁移重试已写入的业务操作。
+
+## 迁移后校验
+
+在工程根运行，全部退出 0 才算本地迁移通过：
+
+```sh
+npm ci
+base-database-cli contracts generate
+npm run check --workspace page
+base-database-cli check --json
+```
+
+`contracts generate` 必须成功，生成文件与实际调用方一同审阅；`check --json` 必须成功且各检查项无 failed，不能只看 JSON 可解析。CONTRACT_STALE 先重新生成后核对源变更；非法 functionInputs 按配置错误修正；布局冲突按真实目录与锁修复，不能删除 template 绕过校验。check 的职责和先后顺序见[本地检查与契约生成](development.md#本地检查与契约生成)。
+
+编译通过不证明请求行为正确。用请求替身覆盖迁移过的输入/输出分支，随后在已有授权范围内按[发布与交付](release.md)部署并验收同一 Preview。未完成运行态验收时交接明确“本地通过，Preview 待验收”，不宣称业务迁移完成。