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

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## [1.4.3] - 2026-10-14
+
+### Changed
+
+- `dev` 长时间未连接到宿主页面时给出提示，不再静默等待。
+- `dev` 提示文案统一为英文。
+
+### Fixed
+
+- `pull` 后未修改直接 `check` 或 `deploy` 不再误报契约过期。
+
+## [1.4.2] - 2026-10-13
+
+### Added
+
+- 源码制品记录格式版本；`pull` 遇到由较新 CLI 发布的格式时，校验归档后提示所需 CLI 版本，不写入未识别内容。
+
+### Changed
+
+- 新建 workspace 工程使用 Base Database App SDK `0.1.0` 正式版。
+- Prod 发布回执改为提供 `skillCommand` 读取已发布站点 Skill，不再返回由函数发现结果推断的外部 Agent 函数清单与增删差异。
+
+### Fixed
+
+- AI Function 草稿读取、`pull` 恢复与部署前防丢失检查使用完整草稿列表，避免空 Skill 摘要阻断操作。
+- 函数全量覆盖删除已有函数时识别删除回执，并在同步与部署结果中返回 `deletedFunctionIds`。
+- Prod 发布后站点 Skill 暂不可获取时保留发布成功结果，并提示稍后重试读取。
+
+## [1.4.1] - 2026-10-13
+
+### Added
+
+- 新建应用使用 workspace 模板，提供 SDK Page 接入、ESM FaaS 与工程契约生成；新建 workspace 和契约生成需要 Node.js 22+。
+- 新增 `contracts generate`，生成函数 metadata、类型化 Page 客户端与隔离的工程契约。
+- 新增 `dev [directory]` 本地开发入口，支持持久化配对与 Page 热更新，并可显式启用 FaaS 变更后的整应用 Preview 部署。
+- 新增 `diagnostics [directory]`，按应用、环境和时间范围汇总本地诊断并标明数据来源覆盖情况。
+- 支持配置站点函数的外部 Agent 开放策略，并通过 `agent-tools skill install` 为站点成员安装已发布站点的业务 Skill。
+- 函数参数支持名称、描述和枚举声明，统一函数调用与 AI 参数契约。
+
+### Changed
+
+- CLI 机器输出统一使用 `--json`；`dev --json` 按行输出 JSON 事件，`deploy --json` 的标准输出不再混入构建日志。
+- classic 工程未声明输入模式时默认使用 positional；template v2 Page 与 SDK 客户端使用 named，classic 工程可通过 `functionInputs` 显式声明输入模式。
+- CLI 内置构建器更新至 1.0.6，统一本地构建与构建诊断。
+- FaaS 依赖包中未安装的可选依赖不再导致构建失败；构建结果通过 `stubbedModules` 列出这些模块，运行时实际加载时仍按 Node.js 行为报找不到模块。
+- 新建 workspace 工程使用 SDK `0.0.1-alpha.2`。
+- 构建缓存依据实际部署输入判定复用范围，排除 Agent 辅助软链等非部署输入。
+- 建站 Skill 明确开发者 Skill 与站点业务 Skill 的用途，并提供 workspace 迁移、SDK 接入和可直接转发给成员的业务能力交付指引。
+- 建站 Skill 补充固定记录写入的权限边界、按需 AI 能力和未知写入结果的核对要求。
+- 联网业务命令附带更新提示，更新检查失败会缓存，损坏的更新缓存不再阻断命令。
+
+### Fixed
+
+- 源码归档与 `pull` 保留工程契约及根目录 `base-app.config.ts`，恢复工程后不丢失构建和函数输入配置。
+- `dev` 准备 Page 契约时保留完整工程契约与根配置。
+- 修复 Windows 上的 starter TypeScript 构建入口与 `pull` 文件路径处理。
+- 附件下载通过宿主处理，避免页面直接访问下载地址失败。
+- 显式指定的账号 profile 传递到构建与契约生成链路。
+- `lark-cli -- api` 失败时保留原始错误信封与退出码。
+- 跳过 AI Function 同步时，函数开放策略校验与实际部署能力保持一致。
+- 函数参数或返回值中名为 `$ref`、`$id`、`tsType`、`tsEnumNames` 的业务字段可以正常生成契约，不再被误判为 Schema 关键字。
+- 缺少 SDK 时，`dev` 与 `contracts generate` 的安装提示给出与新建工程模板一致的精确版本，避免安装到不支持契约生成的版本。
+
+## [1.4.0] - 2026-10-09
+
+### Changed
+
+- 更新检查的单次等待上限调整为 5 秒；网络权限受限时，建站指引支持申请授权后重试一次，检查失败不阻断任务。
+- SQL 指引明确 `PERCENTILE_CONT` 在 BaseSQL 2.0 与 6.0 中均不支持，避免生成无法部署的查询。
+
+### Fixed
+
+- Windows 上可从官方 npm 安装的 `lark-cli.cmd` 定位同一安装目录中的原生 `lark-cli.exe`，并在原生程序尚未安装时提示初始化方式。
+- SVG 附件缺少封面时识别宿主返回的错误，避免把 HTTP 202 的错误响应误当作图片，并保留 LogID 供排查。
+
 ## [1.3.9] - 2026-10-08
 
 ### Changed

package/README.md

@@ -5,9 +5,9 @@ Skill 和配套 CLI，用于基于飞书多维表格创建、开发并发布数
 负责初始化 Base 与应用、生成项目、校验和构建 Functions，以及发布 Preview
 和正式版本。
 
-## 安装 CLI 和 Agent Skill
+## 安装 CLI 和开发者建站 Skill
 
-需要 Node.js 20.19 或更新版本，以及可用的 npm。首次安装到 Codex：
+CLI 与存量 classic 命令需要 Node.js 20.19+；新建 workspace、契约生成与 workspace 开发需要 Node.js 22+。需要可用的 npm。首次安装到 Codex：
 
 ```bash
 npm install -g @lark-base-open/base-database-cli@latest
@@ -20,7 +20,9 @@ base-database-cli install --target codex
 
 成功结果包含 CLI 版本、实际入口和 Skill 目录。PATH 不通时输出需加入的目录及可直接运行的 Node/CLI 参数；命令入口缺失时提示检查 npm 的 bin-links 配置。不修改 shell 配置、npm prefix 或 Node 安装。npm 失败时保留错误并停止后续步骤。重新加载 Skill 后，日常直接运行 `base-database-cli …`。
 
-已有全局 CLI、只需给另一个 Agent 安装 Skill 时：
+站点使用者要让外部 Agent 调用已发布业务函数时，使用 `agent-tools skill install --site <站点链接或 token>`；它安装站点 Skill。`skill install` 安装用于搭建、修改和发布应用的开发者 Skill。
+
+已有全局 CLI、只需给另一个开发者 Agent 安装建站 Skill 时：
 
 ```bash
 base-database-cli skill install --target claude
@@ -44,7 +46,7 @@ base-database-cli update --version 1.0.1 --skill-dir "/Users/alice/.codex/skills
 
 npm 的权限、网络和环境错误直接报告，不预先探测或自动修复用户环境，也不覆盖用户的 npm engine-strict 配置。CLI 升级成功但部分 Skill 失败时返回 `skill-update-failed`，分别列出成功目录、失败目录及各自的修复参数；继续处理其他目录，不自动整体回滚。切换 npm/Node 环境后，应使用该环境中的全局 CLI。
 
-CLI 版本来自包内 `package.json`；每份 Skill 的 `base-database-version.json` 记录其来源版本；用户目录下 `.base-database-cli/update-state.json` 仅缓存 registry、latest 和 checkedAt，24 小时有效。查询与全局安装使用相同的 npm 全局配置，忽略项目级 registry；在线查询总预算 3 秒；缓存不可写不影响检查。CI 和托管 Builder 跳过公开更新。
+CLI 版本来自包内 `package.json`；每份 Skill 的 `base-database-version.json` 记录其来源版本；用户目录下 `.base-database-cli/update-state.json` 按状态区分成功查询与 `unavailable`：成功结果缓存 24 小时，失败结果缓存 1 小时，负缓存有效期间不再发起查询。查询与全局安装使用相同的 npm 全局配置，忽略项目级 registry；手动 `check-update` 在线查询总预算 5 秒，`doctor`、`init`、`pull`、`deploy` 等业务命令的更新查询预算为 500 ms，有新版时在输出附带 `update` 字段（普通文本错误在 stderr 附带该字段）；检查失败与缓存不可写不影响业务结果。CI 跳过公开更新。
 
 ## 创建、恢复并发布数据库应用
 
@@ -54,7 +56,7 @@ CLI 版本来自包内 `package.json`；每份 Skill 的 `base-database-version.
 base-database-cli context . --summary --json
 ```
 
-`context` 只读取本地配置、Catalog、Function metadata 和 init/Preview 回执。摘要保留环境、资源数量、readiness 与建议的下一步，不输出本地路径、fingerprint 值或逐项资源；排障时去掉 `--summary` 可读取完整快照。Preview freshness 只跟踪 `base-database.jsonc`、Page、Database Function、FaaS 和 AI Function 等部署输入，README、workflow 定义及验收材料不会触发无效重发。缺少 `base-database.jsonc` 时返回 `project.status=uninitialized`，不会报 project-not-found。该命令不读取认证凭证或环境变量值，不调用远端 API，也不执行 `doctor`、`check`、构建或发布；默认输出已经是 JSON，`--json` 用于显式声明机器读取。
+`context` 只读取本地配置、Catalog、Function metadata 和 init/Preview 回执。摘要保留环境、资源数量、readiness 与建议的下一步，不输出本地路径、fingerprint 值或逐项资源；排障时去掉 `--summary` 可读取完整快照。Preview freshness 的输入范围见[制品指纹](skills/lark-base-database/references/release.md#制品指纹)，README 属于部署输入。缺少 `base-database.jsonc` 时返回 `project.status=uninitialized`，不会报 project-not-found。该命令不读取认证凭证或环境变量值，不调用远端 API，也不执行 `doctor`、`check`、构建或发布；默认输出已经是 JSON，`--json` 用于显式声明机器读取。
 
 ### 复用 lark-cli profile
 
@@ -76,9 +78,15 @@ base-database-cli --profile my-lark init ./todo-database \
 
 不存在的 profile 会报错，不回退或自动创建。已选 profile 与环境注入的凭证、
 AUTH_PROXY 等更高优先级凭证来源同时存在时会报冲突，避免静默换账号；
-没有选择 profile 的托管环境继续使用宿主凭证，不保存 `larkProfile`。
+已配置认证代理且没有选择 profile 时继续使用代理提供的凭证，不保存 `larkProfile`。
 跨设备时须在目标设备配置并授权对应 profile，不能复制凭证。
 
+### workspace 工程
+
+init 仅生成 workspace（`init`），classic 仅保留存量兼容。根 npm workspace 包含 page + server，Page 入口调用 SDK startBaseApp，FaaS 源码使用 ESM；本地 check 与云端直接调用同源平台构建器，先类型检查再生成 CJS 与 build-manifest.json。先执行 `contracts generate`，再执行 `check --json`；生成代码位于 page/src/generated 与 server/generated。
+
+workspace 使用 starter 模板指定的 SDK 精确正式版本与根 lockfile。classic 继续兼容；由 coding agent 按[工程迁移指南](skills/lark-base-database/references/workspace-migration.md)修改并验证，本地通过后仍须完成 Preview 验收。
+
 ### 新建数据库应用
 
 新建工程时，`init` 支持两种 Base 来源。需要从零建数据模型时，Agent 根据 Skill 写出完整 `base-schema.json`，再用一条命令创建 Base、全部 table、应用与 binding，并生成 hello-world 工程和 Catalog：
@@ -125,11 +133,11 @@ base-database-cli init ./todo-database \
   --env online
 ```
 
-生成项目的 `page/`、`server-functions/`、`database-functions/` 直接位于项目根目录；`base-database.jsonc` 和 `catalog.json` 也保留在根目录。`server-functions/` 是服务端 FaaS Functions 的源码与构建工作区。CLI 的 Preview 状态和发布临时制品统一写入被 Git 忽略的 `.base-database-cli/state/`。
+生成项目的 `page/`、`server/`、`database-functions/` 直接位于项目根目录；`base-database.jsonc` 和 `catalog.json` 也保留在根目录。`server/` 是 workspace 的服务端 FaaS 源码与构建工作区；classic 路径按[工程目录](skills/lark-base-database/references/workspace.md#工程目录与构建模式)选择。CLI 的 Preview 状态和发布临时制品统一写入被 Git 忽略的 `.base-database-cli/state/`。
 
 ### 恢复并修改已有数据库应用
 
-已有数据库应用存在源码制品时，使用 `pull` 恢复可编辑工程，不要重新执行 `init`。目标目录必须为空；CLI 会下载当前 `page/`、`server-functions/` 和 `database-functions/` 源码，读取应用 Catalog，并重建 `base-database.jsonc` 与 `catalog.json`，不会创建或修改 Base、应用元信息和 binding：
+已有数据库应用存在源码制品时，使用 `pull` 恢复可编辑工程，不要重新执行 `init`。目标目录必须为空；CLI 会按制品模板布局下载 Page、FaaS 和 Database Function 源码（见[工程目录](skills/lark-base-database/references/workspace.md#工程目录与构建模式)），读取应用 Catalog，并重建 `base-database.jsonc` 与 `catalog.json`，不会创建或修改 Base、应用元信息和 binding：
 
 旧制品中的 `sql/` 会在恢复时迁移为 `database-functions/`。本地旧工程仍可直接检查和发布，但不能同时保留两个目录。
 
@@ -143,7 +151,7 @@ base-database-cli pull ./todo-database \
 
 ### 发布 Preview 和正式版本
 
-新建流程是 `init → 开发 → check → deploy`；修改已有数据库应用时是 `pull → 修改 → check → deploy`。Agent 在每个阶段一次性获取所需上下文，根据 Catalog 完整实现 Page、Database Function 和 FaaS，通过项目级本地检查后发布 Preview：
+新建流程是 `init → 开发 → contracts generate → check → deploy`；修改已有数据库应用时是 `pull → 修改 → 按契约需要 generate → check → deploy`。Agent 在每个阶段一次性获取所需上下文，根据 Catalog 完整实现 Page、Database Function 和 FaaS，通过项目级本地检查后发布 Preview：
 
 ```bash
 cd todo-database
@@ -151,7 +159,7 @@ base-database-cli check --json
 base-database-cli deploy
 ```
 
-部署结果只返回当前环境用户可访问的顶层 `baseAppUrl`。Agent 把链接交给用户后停止；用户体验并明确回复“部署正式版”后，把同一制品发布到 Prod：
+部署结果只返回当前环境用户可访问的顶层 `baseAppUrl`。Agent 按[发布与交付](skills/lark-base-database/references/release.md#交付结果)完成示例回读、约定通知与开放能力 handoff 后交付链接；用户体验并同意发布同一 Preview 制品后，将其发布到 Prod，确认不限固定口令：
 
 ```bash
 base-database-cli deploy --production --yes
@@ -180,9 +188,10 @@ profile 且 lark-cli 尚未配置时，才自动启动首次 `config init --new`
 不存在时直接报错，不创建或覆盖配置。
 
 CLI 明确报告 scope 权限不足时，使用同一 profile 重新执行 `auth login`；若错误另有应用权限开通或额外 scope 的处理要求，按错误提示处理。正常业务调用不增加权限探测。
-`doctor` 复用登录状态中的 scope 列表检查上述三个用户权限，缺少时列出 `missing_scopes` 并提示重新登录；未返回 scope 列表时报告 `unavailable`，托管授权报告 `host_managed`。此项不代替应用侧权限开通检查。
+`doctor` 复用登录状态中的 scope 列表检查上述三个用户权限，缺少时列出 `missing_scopes` 并提示重新登录；未返回 scope 列表时报告 `unavailable`，认证代理报告 `host_managed`。此项不代替应用侧权限开通检查。
 
 Base Database CLI 按 `PATH` 顺序选择第一个可识别的 `lark-cli`。可通过 `BASE_DATABASE_LARK_CLI_PATH` 指定已确认的可执行文件绝对路径；显式路径优先于 PATH。
+Windows 上安装官方 npm 包时，CLI 会将 `lark-cli.cmd` 解析为同一安装目录下的原生 `bin/lark-cli.exe` 后执行；显式路径也可直接指向该 `.exe`。原生程序不在 npm tarball 内，而是由官方安装脚本下载；若尚未落盘，先在终端运行该安装入口的 `lark-cli --version` 完成初始化，再重试。其他 `.cmd` 包装文件不作为可执行入口。
 
 宿主入口缺少 `config` 且未选择 profile 时，CLI 保留宿主认证上下文，不生成虚构的本地 profile；指定 profile 却无法核验时仍报错。缺少 `auth` 时，`doctor` 和 `auth whoami` 使用当前用户只读接口核验身份，`doctor` 还检查应用列表接口；认证失败和权限错误不会按命令缺失跳过。宿主登录、退出仍由宿主提供，不模拟成功。Skill 文档命令 `skills read` 缺失时可直接读取已安装文件，不影响业务执行。
 
@@ -206,6 +215,12 @@ Base Database CLI 按 `PATH` 顺序选择第一个可识别的 `lark-cli`。可
 }
 ```
 
+新建工程记录 `template: { "name": "database-starter", "version": 2 }`。缺少该字段的老工程按版本 1 读取，不改写配置；未知名称、版本或非法结构会报错，需核对工程模板并使用支持它的 CLI。
+
+`init`、`check`、`deploy` 会维护根目录 `AGENTS.md` 的 `base-app` 标记段落，记录模板和已安装 SDK 的版本、文档位置。已存在的 `CLAUDE.md` 会获得同标记的引用段落；标记外内容保持原样。设置 `managedAgentDocs: false` 可退出；删除标记也会退出，但需要保留 `.base-database-cli/state/managed-agent-docs.json` 这一工程本地记录。SDK 更新提示读取 npm registry，带检查时间，查询最多 2 秒，离线静默跳过，不自动升级依赖。
+
+`check` 对 `page/src` 中直接使用 `window.open` 或 JSX `target="_blank"`、且未调用 channel 的 `installLinkGuard` 的工程给出警告。沙箱内这类链接会被浏览器拦截；将 `@lark-base-open/base-site-channel` 升级到 >= 0.1.5，并在入口导入、调用 `installLinkGuard()`。警告不影响检查退出码或部署。
+
 `deploy` 会在发布前应用合法的 Base binding。目前只支持一个 Base；多个不同 `baseToken` 会停止发布并提示删除多余 binding。无法解析或暂不支持类型的单个 binding 会输出警告并建议修正 `base-database.jsonc`。
 
 ## CLI 命令
@@ -226,15 +241,15 @@ base-database-cli deployments status
 base-database-cli lark-cli -- <arguments...>
 ```
 
-`check` 用于开发期本地检查：验证工程配置、页面标题、Function metadata 和输入 Schema，先从 Database Function/FaaS metadata 生成 Page Function 输入类型，再使用 CLI 内置 npm 按依赖指纹准备 Page/FaaS 依赖并运行两者的 build（starter 的 build 包含类型检查）。默认目录为当前目录；`--no-install` 要求依赖已存在，`--force-install` 强制重装，两者不能同时使用。
+`check` 的依赖准备、契约核对、CONTRACT_STALE 恢复和无 SDK classic 自动生成条件统一见[本地检查与契约生成](skills/lark-base-database/references/development.md#本地检查与契约生成)。
 
 成功的 Page 和 FaaS build 会分别按源码、lock、Node/npm、平台和构建环境指纹缓存在 `.base-database-cli/state/check-build/`。输入未变化时后续 `check` 直接复用对应结果；只有一侧失败时，修复重试会保留并复用另一侧的成功结果。`--force-build` 忽略这份构建缓存，`--force-install` 会同时重新安装并重新构建；`deploy` 仍执行完整 build，不复用本地 `check` 的构建结果。
 
-使用 `--json` 时，成功或失败的 stdout 都是单个 JSON 文档，报告 `schemaVersion` 为 `2`；成功结果的 `functions["database-functions"]` 和 `functions["server-functions"]` 分别计数两类本地 Function。构建日志在失败时收敛到 `error.diagnostics`；失败结果还提供稳定的 `error.code`、`error.stage`、阶段状态和 `nextActions`，`cache.pageBuild` / `cache.faasBuild` 使用 `hit`、`miss`、`not_run` 单独表达缓存状态，不改变 `checks.*=passed` 的成功语义。不加该参数时保留面向终端的实时 npm/build 输出和文本错误。命令会更新 `page/src/lib/database-function-inputs.generated.ts`、生成本地缓存和构建输出，不调用应用 API、不修改 binding、不上传或发布，也不改写初始化和 Preview 回执。结果中的 `sqlValidation.status=not_run` 表示服务端查询语法、Catalog 与绑定校验未执行；本地通过不代表查询语句或业务运行态已通过。
+使用 `--json` 时，成功或失败的 stdout 都是单个 JSON 文档，报告 `schemaVersion` 为 `2`；成功结果的 `functions["database-functions"]` 和 `functions["server-functions"]` 分别计数两类本地 Function。构建日志在失败时收敛到 `error.diagnostics`；失败结果还提供稳定的 `error.code`、`error.stage`、阶段状态和 `nextActions`，`cache.pageBuild` / `cache.faasBuild` 使用 `hit`、`miss`、`not_run` 单独表达缓存状态，不改变 `checks.*=passed` 的成功语义。不加该参数时保留面向终端的实时 npm/build 输出和文本错误。命令生成本地缓存和构建输出；输入类型是否自动更新按[本地检查与契约生成](skills/lark-base-database/references/development.md#本地检查与契约生成)判定，不调用应用 API、不修改 binding、不上传或发布，也不改写初始化和 Preview 回执。结果中的 `sqlValidation.status=not_run` 表示服务端查询语法、Catalog 与绑定校验未执行；本地通过不代表查询语句或业务运行态已通过。
 
-`deploy` 在一次调用内先生成 Function metadata 并完成全部查询校验，通过后再检查依赖指纹、执行必要的依赖安装、Page/FaaS build、archive、Functions sync、Artifact upload、Preview publish 和状态轮询。CLI 会汇总全部未通过的 Database Function 后一次性报错；存在任一查询校验失败时不会安装依赖或执行 build。依赖指纹未变化且对应 `node_modules` 仍存在时，默认跳过该子项目的 `npm ci`；`--force-install` 强制重装，`--no-install` 无条件跳过安装。build 仍会在每次 Preview deploy 中执行；`check` 不替代发布门禁。FaaS 子项目必须保留可通过 `npm run build` 执行的构建脚本。
+`deploy` 发布 Preview 时先解析账号环境、获取目标应用依赖策略并校验 package.json 来源，失败时不安装。策略通过后安装依赖，再提取 SDK 契约、校验声明与查询，之后构建和发布；查询校验失败不会继续 build，但依赖可能已安装。依赖指纹未变化且 node_modules 有效时可跳过 npm ci；`--force-install` 强制重装，`--no-install` 要求依赖已就绪。AI 与其他 Functions 的发布顺序及错误边界见[发布参考](skills/lark-base-database/references/release.md#function-发布顺序与错误边界)。
 
-本地存在 `ai/<functionKey>/meta.json` 声明时，`deploy` 还会把本地 AI Function 全集全量覆盖同步到草稿版本；本地没有 `ai/` 声明时不调用任何 AI Function 接口（返回 `no_local_ai_functions` 跳过原因），不涉及 AI 能力的应用无需开通 AI Function。`--skip-ai-functions` 显式跳过本次 AI Function 同步，Page/Database Function/FaaS 仍正常发布，成功结果中带 `aiFunctionsSkipped: true`；使用该参数发布后，远端 AI Function 与本次制品的对应关系需要自行确认并在交付说明中标注。
+Preview deploy 使用一次统一 PUT 覆盖 sql/edge/mutation；本地存在 `ai/<functionKey>/meta.json` 且未 skip 时，在同一批次加入 AI 全集。本地没有 AI 声明时保留远端 AI，本地缺少远端 AI key 时拒绝覆盖，删除须显式执行 `ai-functions sync`。配置使用 `config.input_schema`，`ai-functions list/get` 默认读取 preview，`pull` 将草稿 spec 写回本地。`--skip-ai-functions` 显式跳过本次 AI Function 同步，Page/Database Function/FaaS 仍正常发布，成功结果中带 `aiFunctionsSkipped: true`；使用该参数发布后，远端 AI Function 与本次制品的对应关系需要自行确认并在交付说明中标注。
 
 FaaS 中静态引用的 `process.env` 变量通过 `environment-variables` 命令管理。定义由 Preview 和 Prod 共享，两套值独立保存；Config 查询时明文返回，Secret 只返回脱敏值。`declare` 创建共享定义并默认拒绝覆盖同名但元数据不同的定义；确认影响后可用 `--force` 修改。声明必须显式传入 `--target`、`--type`，并用 `--required` 或 `--optional` 表明是否必填；`set` 和 `clear` 也必须显式指定目标环境。`set` 只接受 `--value-stdin`，CLI 不提供把值放入进程参数的 `--value`。保存后需重新发布才生效，保存动作不会自动发布。
 
@@ -247,3 +262,92 @@ base-database-cli lark-cli -- \
   api GET /open-apis/base/v3/sites/list \
   --params '{"pageSize":1}' --json
 ```
+
+### 本地诊断与 Function 契约
+
+此版本提供以下能力；旧 CLI 若没有这些子命令，可以继续原有手写 meta 和 check/deploy 流程。
+
+```bash
+base-database-cli diagnostics . --json
+base-database-cli contracts generate .
+base-database-cli contracts generate . --runtime-only
+```
+
+诊断只汇总本地 check/build/deploy 结果、响应 LogID 和显式导入的记录，不查询平台历史日志。
+时间窗口最长 24 小时；JSON 同时返回 `records`、`coverage`、`warnings` 与 `complete:false`。
+人读摘要也展示来源覆盖；无记录不代表没有错误。
+公开诊断 Schema 的 platform 仅包含 online / pre / internal / null；其他平台名称投影为 internal，内部构建变体可扩展自己的枚举。
+浏览器记录强制标记 `evidence:browser`，未知应用/环境保留 null，不自动归属当前应用。
+时间必须是带时区的 RFC3339。
+本地流在 `.base-database-cli/state/diagnostics/events.ndjson`，轮转保留最多三份 5MiB 文件。
+
+新的 FaaS 可在 `server/functions/<id>/index.ts`（classic 路径见[工程目录](skills/lark-base-database/references/workspace.md#工程目录与构建模式)） 从 SDK `/server` 导入
+`defineFunction`，并从同目录 `contract.ts` 导入独立的 input/output：
+
+```ts
+// contract.ts
+import { z } from 'zod';
+export const input = z.object({ title: z.string().min(1).describe('新任务的标题') });
+export const output = z.object({ id: z.string() });
+
+// index.ts（独立文件）
+import { defineFunction } from '@lark-base-open/base-database-app-sdk/server';
+import { input, output } from './contract.js';
+export default defineFunction({ input, output, handler: async () => ({ id: 'example' }) });
+```
+
+生成器需要 Node.js 22+，目前隔离白名单支持项目中精确锁定并已安装的 Zod（验证版本 4.6.5，
+workspace 根 lock / classic 服务端 lock 必须与安装版本一致）；其他 Standard Schema 写法仍可运行，
+生成能力不可确认时降为 unknown/runtime-only 并警告。CLI 不安装或升级 SDK/Zod，不执行业务
+index/handler；contract 仅允许 Schema 常量、类型声明、`zod` 的 `z` import 以及同类
+`./contracts/` 模块。业务 import、顶层副作用、自定义回调和不支持的表达式会降级。
+通过 AST 检查的图在清空环境的受限子进程转换，限时 5 秒、堆 128MiB、输出 256KiB；
+这用于防止意外副作用，不是执行任意恶意 JavaScript 的安全沙箱。
+
+显式 `contracts generate` 更新 meta 的生成区、服务端 contracts.generated.json（路径见[工程目录](skills/lark-base-database/references/workspace.md#工程目录与构建模式)）
+和 `page/src/generated/functions.ts`。check/deploy 比较当前输入、元数据和客户端，过期则要求重新生成；
+不静默覆盖契约。源码、业务依赖、lock 或构建环境变化都会使生成结果失效。
+生成的 `functions.<id>` 校验网关外层 code，并且只解一层 data；SQL/Mutation 输出保持 unknown。
+SDK `FunctionInputMap` 通过模块扩充保留输入约束；类型不替代运行时校验，也不证明远端契约匹配。
+
+后端不支持的 Schema 规则保留在本地完整契约，发现元数据省略 inputSchema 并警告，不删除规则后
+假称完整契约。发现 FG 关闭时显式使用 `--runtime-only`，CLI 不切换身份、不启用 FG，也不自动重试发布。
+旧手写 FaaS inputSchema 校验保持原样。远端构建与运行环境仍须具备该 SDK 的兼容支持。
+
+workspace 迁移中的 helper 检查只处理已核验 hash 的原模板；定制 helper、无法解析的引用和修改过的生成文件列为冲突，
+存在冲突时整批不写入。迁移保留原 helper 路径作为 SDK 再导出，将静态引用与测试 mock 引用迁往 SDK，
+同时生成 FunctionInputMap 扩充。完整 workspace 迁移还会搬迁服务端目录、安装已发布 SDK 并统一依赖锁；按 Skill 的 workspace 迁移说明检查 dry-run，确认后 apply。
+
+### 本地开发（Preview）
+
+`base-database-cli dev` 启动本地 Vite 并输出宿主开发地址。地址形态为 `/baseapp/dev/<siteToken>/<port>#t=<配对令牌>`，基于 Catalog 的 baseAppUrl；可显式 `--host-origin https://<实际宿主域名>` 切换宿主 origin。
+用 CLI 输出的完整链接打开；复制地址栏链接给别人会自动打开线上版本。若弹出或地址栏出现访问本地网络/本机设备请求，请允许后点重试。配对通过后显示常驻“本地调试中”提示条，请核对 Base/表与写入范围。CLI 不创建、续租或关闭服务端开发会话。
+`home`、`new`、`static`、`dev` 为宿主保留段，不能作为应用 token；旧 `/baseapp/<siteToken>/dev/<port>` 不再兼容。
+服务仅监听 `127.0.0.1:43100–43109`，显式 `--port` 被占用时失败；默认在白名单中选择。
+`dev --json` 每行输出一个 JSON 事件。`dev.listening` 表示服务已监听；`dev.ready` 仅在 SDK lifecycle 成功且匹配 `localOrigin` 时发出，不能替代 agent-browser 的顶层宿主身份与权限验收。远端 Agent 还需要用户浏览器机器上的端口转发。
+
+FaaS 变化默认只本地构建；构建分流统一见[工程目录与构建模式](skills/lark-base-database/references/workspace.md#工程目录与构建模式)。
+显式 `--deploy-preview` 才允许在启动时及后续 FaaS 变化后修改共享 draft 并发布**完整应用** preview，输出真实发布粒度和耗时，保留其他 Function。
+SQL、Mutation、绑定或依赖变化会暂停本轮自动发布，需另行检查并显式 `deploy`，之后重新启动 dev。
+发布异常保留回执且停止自动写入；已知 publishId 用 `deployments status <publishId> --wait` 核对，不自动重复 publish。
+同机同应用使用本地锁；跨机器没有 CAS，推荐独立测试应用。退出关闭 Vite、停止监听、取消构建并释放本地发布锁。
+
+配对令牌保存在项目 `.base-database-cli/state/dev-pairing-token`（权限 600），dev 重启保持不变；`dev --reset-pairing` 重新生成后须用新的 CLI 链接打开。令牌仅通过环境变量传给 Vite 子进程；`--json` 的地址已打码，完整地址只在人类可读输出显示。state 目录已由模板 gitignore 和上传打包规则排除。旧 SDK 不支持配对时须先升级工程 SDK。
+
+协议常量的唯一源为 SDK 的 `development-pairing.json`；本仓 `src/development-pairing.generated.ts` 由 `node scripts/sync-development-pairing.mjs` 生成，集成验证用 `--check` 比较，独立检出可用 `BASE_APP_PAIRING_SOURCE` 指定 SDK JSON 路径。
+
+### 开发与契约补充契约
+
+工程目录、依赖位置与平台/传统构建分流统一见[工程目录与构建模式](skills/lark-base-database/references/workspace.md#工程目录与构建模式)。
+
+`dev` 要求 page 已安装支持配对的 SDK。缺失时按 CLI 报错给出的安装命令执行，版本与新建工程模板一致。
+
+check/preview deploy 先准备依赖，再提取和比较契约，且在任何远端写入之前；`--no-install` 缺依赖时报告依赖错误。server/contract 修改后先 `contracts generate` 再 `check`。契约子进程只屏蔽 fetch/WebSocket 并限制文件系统访问；不隔离 node:net/node:http/dns，不是恶意任意 JavaScript 的安全沙箱。
+
+开发/生产统一直接导入配置，没有 dev 虚拟入口。HMR 不触发重新配对；标签隐藏不销毁 iframe，focus 和30秒轮询复查编辑权限。权限查询超时/网关失败暂停业务并保留配对令牌，可点击重试。冷启动握手等待30秒，超时保留iframe等待迟到握手，不将超时等同本地网络权限被拒。
+
+协议检查已接入 test。相邻 SDK 检出或 BASE_APP_PAIRING_SOURCE 存在时检查权威源；独立检出的 CI 校验随提交固定的 SDK 协议快照 scripts/development-protocol-source.json 与生成物一致。更新协议时从权威 SDK 运行同步脚本，它同时刷新快照；跨仓验收仍须指定实际 SDK 源。宿主与 SDK 的能力要求由 channel 包统一提供。
+
+### classic 工程迁移
+
+classic 迁移由 coding agent 按[工程迁移指南](skills/lark-base-database/references/workspace-migration.md)执行；CLI 只做确定性校验。输入模式遵循[工程输入声明](skills/lark-base-database/references/workspace-migration.md#classic-输入声明)，归档与 pull 保留该声明。