@lark-base-open/base-database-cli 1.0.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-base-open/base-database-cli",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "CLI and Agent Skill for building database applications on Lark Base.",
   "type": "module",
   "bin": {
@@ -11,7 +11,6 @@
     "config-schema.json",
     "skills/lark-base-database/SKILL.md",
     "skills/lark-base-database/references",
-    "!skills/lark-base-database/references/frontend-design-guide.md",
     "templates",
     "README.md",
     "CHANGELOG.md",
@@ -29,10 +28,11 @@
     "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\" \"scripts/**/*.{js,mjs,ts,tsx}\" \"templates/**/*.{js,mjs,ts,tsx}\"",
     "check": "tsc -p tsconfig.json --noEmit",
     "validate": "pnpm format:check && pnpm check && node scripts/validate.mjs",
-    "test": "tsx --test test/**/*.test.ts",
+    "test": "tsx --test test/**/*.test.ts && npm run test:behavior-harness",
     "install:skill": "pnpm build && node dist/cli.js skill install",
     "prepack": "pnpm build && pnpm validate && pnpm test && pnpm validate:starter-dependencies",
-    "validate:starter-dependencies": "node scripts/check-starter-dependencies.mjs"
+    "validate:starter-dependencies": "node scripts/check-starter-dependencies.mjs",
+    "test:behavior-harness": "node scripts/skill-behavior-eval/run-tests.mjs"
   },
   "dependencies": {
     "ajv": "8.17.1",
@@ -41,11 +41,13 @@
     "crc-32": "1.2.2",
     "jsonc-parser": "3.3.1",
     "npm": "10.9.2",
+    "semver": "7.7.3",
     "yauzl": "3.2.0"
   },
   "devDependencies": {
     "@types/archiver": "8.0.0",
     "@types/node": "24.1.0",
+    "@types/semver": "7.7.1",
     "@types/yauzl": "2.10.3",
     "prettier": "3.6.2",
     "tsx": "4.23.1",

package/skills/lark-base-database/SKILL.md

@@ -1,307 +1,107 @@
 ---
 name: lark-base-database
-description: 当用户希望以飞书多维表格为业务数据后端，从零或基于已有 Base 搭建、修改、发布、验收或排查数据库业务应用时使用。通过 lark-cli 建模、读取和查询原生 Base 能力，并实现 Catalog、Base SQL、FaaS、Page 和发布链路；无法确认某项能力时也必须使用本 Skill 先完成能力发现。
+description: 使用飞书多维表格作为业务数据后端，创建、修改、恢复、发布、验收或排查 Base Database 业务系统。适用于 Base Database 的 Page、SQL Function、FaaS 和原生 Base 集成；仅操作多维表格资源时使用 lark-base。
+metadata:
+  compatibility: 需要 Node.js 20.19+、npm/npx、lark-cli 及目标平台访问权限；优先使用本机安装的 Base Database CLI，托管环境使用宿主提供的 CLI。
 ---
 
 # Lark Base Database
 
-基于飞书多维表格实现数据模型、SQL 查询、FaaS 业务操作和应用页面。工程初始化与发布统一使用 `npx @lark-base-open/base-database-cli`；原生多维表格能力的发现与配置使用 `lark-cli base +...`。本 Skill 提供从需求建模到发布交付的完整主流程。
+将业务需求实现为基于真实 Base 数据、可维护且可验证的 应用。先选择任务路径，再读取所需协议；不要在任务开始时读取全部 reference。同一文件在首次进入相关阶段时读取，内容或任务范围变化后再补读。
 
-## 开始任务
+CLI 使用 `--app-token`、配置字段 `appToken`、`base-database.jsonc` 和 `.base-database-cli/state/`，不读取旧配置或旧状态，不接受旧参数。服务端 `/sites/` 路径、SDK 的 `siteToken` 和宿主 `BASE_SITE_BUILDER_*` 环境变量保持原协议；将宿主提供的应用 token 传给 `--app-token`，不改造外部协议。
 
-本文面向数据库应用开发；Base 承载业务数据，应用组织页面、Functions 与发布版本。
-CLI 使用 `--app-token`、配置字段 `appToken`、`base-database.jsonc` 和 `.base-database-cli/state/`，不读取旧配置或旧状态，不接受旧参数。服务端 `/sites/` 路径、SDK 的 `siteToken` 和宿主 `BASE_SITE_BUILDER_*` 环境变量保持原协议；将宿主提供的应用 token 传给 `--app-token`，不要改造外部协议。
+账号选择遵守[工程与环境的 profile 约定](references/workspace.md#账号选择)；直接调用原生 lark-cli 时也使用同一个 profile。
+`lark-cli` 的账号管理和文档命令按环境提供，不是所有宿主的必备能力；首次选择入口及缺少命令时按[环境与依赖](references/workspace.md#环境与依赖)处理。
 
-- **新建系统**：自动判定 Base 来源，不向用户展示来源选择题。Prompt 未明确指定已有 Base 时默认从零创建；明确指定已有 Base 时复用该 Base。随后按本文 1～6 步执行。
-- **修改系统**：先一次性获取应用、binding、Catalog、源码和发布状态，再执行受影响阶段；保留需求外内容和用户未提交修改。
-- **设计或评审**：读取 [风格手册](references/style-guide.md)，只分析和输出，不创建资源或发布。
+### 公开 CLI 版本预检
 
-开始先一次性完整读取本文、[代码开发手册](references/development.md)、[风格手册](references/style-guide.md)、[权限与访问设计](references/permission-design.md)、[SQL Function 专项](references/sql-function.md) 和 [发布与验收](references/release.md)。托管 Builder 必须先读取 `BASE_SITE_BUILDER_WORKSPACE_SOURCE`，该值由宿主判定，Agent 不得自行猜测应当 init、pull 还是直接修改。非托管环境没有该变量时，才按用户请求判断新建或修改流程。需求包含本文无法确认、或不明显属于 Page/SQL/FaaS 的能力时，还必须读取[原生 Base 能力发现与路由](references/base-capability-routing.md)。新建流程默认从零设计 Base schema；只有 Prompt 明确指定已有 Base 时，才取得其 Base token 并由 `init` 读取全部表。随后都以应用 Catalog 为准执行开发。
+本节的全局安装特指 `npm root -g` 对应的 CLI 包目录；不能仅凭 PATH 中存在同名命令就认定满足更新条件。
 
-需求涉及附件的上传、展示、下载或删除时，还必须读取[文件传输](references/file-transfer.md)——上传、展示、写单元格走三条不同的路，不要按普通字段推断。
+仅本地公开 CLI：每个会话首次业务操作前，优先确认本机 `base-database-cli` 入口及其 `--help`。已有全局安装时用已核实的全局入口执行 `check-update --json --skill-dir "<当前读取的 lark-base-database 目录>"`；仅通过 npx 使用时沿用已选版本的完整包名入口。使用实际 Skill 加载路径，不猜测默认 Agent 目录。业务命令复用本次确认的入口。
 
-正常开发只使用 SQL Function 专项明确列出的支持集。需要判断支持集之外的 SQL 语法是否可用、评审或排查 SQL，或者处理 SQL 编译与运行兼容失败时，再完整读取 [Base SQL 不支持能力](references/base-sql-unsupported.md)。
+仅托管 Builder（设置了 `BASE_SITE_BUILDER_WORKSPACE_SOURCE` 或 `BASE_SITE_BUILDER_SITE_TOKEN`）及 CI 跳过更新检查；其他环境正常检查。检查失败不阻塞任务。
 
-仅 `BASE_SITE_BUILDER_WORKSPACE_SOURCE=empty` 或明确的新建流程执行一次 `init` 和一次 `deploy`。`init --schema` 负责创建 Base 和全部表；`init --base-token` 只读已有 Base，不创建或修改表。宿主未提供应用时，`init` 创建新应用；托管 empty 模式必须额外传入 `--app-token "$BASE_SITE_BUILDER_SITE_TOKEN"`，把目标 Base 绑定到该已有应用，不得创建另一个应用。两种入口都会获取 Catalog 并生成 starter。`deploy` 负责依赖安装、production build、归档、SQL 编译校验、Functions 更新、Artifact 上传、源码回读、Preview 发布和状态轮询。项目级 `base-database-cli lark-cli -- ...` 用于修改流程中追加 Table binding、排查应用控制面请求，以及从零搭建应用在 Preview 发布后写入示例记录和调用 SQL Function 回读；其他原生 Base 能力发现和配置直接使用 `lark-cli base +...`。
+- `status=current|unavailable|skipped`：不向用户播报更新检查，继续任务。
+- `status=available`：先确认上述全局入口可用；不可用时按下文说明更新限制并继续任务。可用时说明当前版本和可更新版本，以及会同步已安装的用户级 Lark Base Database Skill，再询问是否升级。拒绝后继续已安装版，本会话不再询问；不要自动执行 npm 或更新命令。
+- 确认全局安装入口且用户同意后，执行 `base-database-cli update --version <返回的 latest 精确版本> --skill-dir "<当前 Skill 目录>" --yes`，成功后重新读取该目录的 SKILL.md 和所需 references。升级会现场查找 Codex、Claude、通用 Agent 用户目录中已安装的本 Skill，并同步这些副本及显式传入的当前目录；不扫描项目或历史自定义目录，不补装已删除的副本。
+- `update` 只允许从全局安装的 CLI 执行，不从 npx 临时副本或项目副本执行，也不移除来源检查。全局命令的 PATH 异常时，通过 `npm root -g` 确认 `@lark-base-open/base-database-cli/dist/cli.js` 的实际位置，用 Node 执行该入口并核对版本。没有全局安装时说明更新限制，继续 npx 业务调用；只有用户明确要求全局安装时才进入安装流程，不将更新确认自动扩展为新建全局安装。
+- `skill.status=mismatch`：简短提示当前 Skill 与 CLI 来自不同版本，可通过本次执行预检的同一 CLI 入口运行 `skill install --dir "<当前 Skill 的父目录>" --force` 同步后重读；不因版本号不同中断业务或自动覆盖。`unknown` 表示未找到有效记录，不推断一致，也不阻塞。
+- 更新失败时按实际结果反馈。`skill-update-failed` 表示 CLI 已更新，但部分 Skill 未同步；说明 `installed` 中的成功目录和 `failed` 中的失败目录，按每项 `repair` 参数数组修复后重读，不宣称整体升级成功，不自动降级或反复重试。
+- 首次使用先确认当前调用入口支持 `check-update`（读取其 `--help`）；旧 CLI 没有该子命令时跳过预检，继续业务，不为预检自动升级。
+- 非托管环境优先使用本机已安装的 `base-database-cli`。已知全局安装存在但 PATH 异常时，使用确认过的可执行路径；不自动修改 shell 配置。没有可用本地入口时，回退 `npx @lark-base-open/base-database-cli`；需要固定版本时使用 `npx @lark-base-open/base-database-cli@<已确认的精确版本>`。不猜 npm scope，不全盘搜索或反复安装。托管环境始终使用宿主入口，不走公开包回退。
 
-每个阶段先完整获取所需上下文，再连续完成该阶段。实现每个 Page/FaaS operation 前，先在内部规划中列出远程调用、每个调用的已知输入和响应依赖，不额外创建设计文件。能在一个 SQL Function 内完成的关联读取先合并；输入已经确定且无响应依赖的读取或请求同时启动，只在业务正确性、平台顺序或后一步确实需要前一步响应时串行。
+## 任务路由
 
-## 无法确认能力时的强制路由
+| 用户任务 | 执行路径 | 主要命令 | 进入阶段前读取 |
+| --- | --- | --- | --- |
+| 新建系统 | 明确需求与访问模型 → 确定 Base 来源 → 初始化 → 开发 → Preview 交付 | `init` → `deploy` | [工程与环境](references/workspace.md)、[权限设计](references/permission-design.md) |
+| 修改已有系统 | 确认现有工程 → 判断影响范围 → 增量修改 → 验证与交付 | 按影响范围修改，必要时 `deploy` | [工程与环境](references/workspace.md)，再读取受影响的协议 |
+| 恢复远端工程 | 确认本地状态和 应用 → 恢复源码与 Catalog → 继续原任务 | 按来源选择 `pull` 或 `init` | [工程与环境](references/workspace.md) |
+| 设计或评审 | 按评审范围分析并输出，不创建资源或发布 | 只读分析 | [工程质量](references/style-guide.md)，涉及权限、SQL 或视觉时读取对应专项 |
+| 排查故障 | 收集证据 → 定位失败阶段 → 按用户要求诊断或修复 | `deployments status`、`doctor` 或项目级 `lark-cli -- ...` | [诊断与验收](references/verification.md)，再读取失败链路的协议 |
+| 补齐新建 Base 的示例数据 | 读取字段与人员 → CLI 写入 → 页面 SQL 回读 → 交付 | `lark-cli -- base +record-batch-create`，再按协议调用 SQL | [示例数据验收](references/release.md#从零建站示例数据验收)，即使 Preview 已发布也先读此节 |
+| 专项验收 | 确定检查范围 → 执行已授权检查 → 报告证据与未验证项 | 按契约调用 SQL 或执行已授权检查 | [诊断与验收](references/verification.md) |
+| 发布当前工程或已验证版本 | 检查工程、制品及授权 → 发布 → 必要收尾 → 交付 | `deploy`；确认后 `deploy --production --yes` | [发布与交付](references/release.md) |
 
-不要因为本文、Base Database CLI 或现有 Catalog 没有描述某项能力，就直接判断“多维表格不支持”或把需求降级。遇到以下任一情况，先执行[原生 Base 能力发现与路由](references/base-capability-routing.md)：
+表格和 references 的示例默认使用本机 `base-database-cli`；需要回退时只替换命令前缀，保留其余参数。托管环境使用宿主 CLI。完整参数见对应 reference。
 
-- 无法确认需求应由 Page、SQL Function、FaaS 还是原生 Base 实现；
-- 需求涉及表和字段以外的能力，如视图、表单、仪表盘、工作流、提醒、通知、角色或高级权限；
-- 准备把某项需求标记为不支持、能力缺口或本期无法实现；
-- 数据库应用的文档、CLI 或运行时没有对应入口，但该需求可能属于多维表格本体。
+新建默认创建 Base；用户明确指定已有 Base 时复用，不额外询问数据来源选择题。只有目标资源、数据所有权、权限或核心流程存在实质歧义时才询问。用户提供的工程、技术选择和已明确授权在后续步骤中持续有效。
 
-能力查询使用 `lark-cli base --help`、对应 shortcut 的 `--help`，以及目标 Base 的只读 list/get 命令；当前环境提供 `lark-base` Skill 时同时读取并遵守它。查询后按证据选择实现归属：原生 Base 已支持则通过 `lark-cli base +...` 配置；数据库应用开发链路已支持则使用 Page/SQL/FaaS；两边各承担一部分时组合实现。只有完成查询仍无法找到入口，才能记录缺口，并区分“原生能力不支持”“当前 lark-cli 未暴露该能力”和“权限或环境阻塞”，附上实际查询过的命令与结果。
+## 开发阶段路由
 
-## 危险操作确认
+| 需要完成的工作 | 必读协议 |
+| --- | --- |
+| 首次实现页面、整体视觉改版或视觉评审 | [前端设计风格指导](references/frontend-design-guide.md)；一方托管与三方搭建统一适用 |
+| 修改布局、颜色、排版或控件样式 | 上述设计指导的相关章节，沿用现有设计系统；与视觉无关的修改不重读 |
+| Page runtime、组件接入或 Function 调用 | [Page 开发](references/development.md) |
+| SQL 查询、参数和结果解析 | [SQL Function](references/sql-function.md) |
+| 判断 SQL 支持集之外的形态或处理兼容错误 | [SQL 能力边界](references/base-sql-unsupported.md) |
+| FaaS 输入 Schema、写入、一致性和下游错误 | [FaaS 与记录协议](references/faas.md) |
+| 附件上传、展示、下载、追加或移除 | [文件传输](references/file-transfer.md)，实现前核对目标环境能力 |
+| 发布后的应用能力 Skill 安装或修复 | [应用能力 Skill](references/database-capability-skill.md) |
+| binding、身份过滤、角色或数据可见性 | [权限设计](references/permission-design.md) |
+| 自动化、表单、仪表盘等原生能力，或能力归属不明 | [原生 Base 能力路由](references/base-capability-routing.md) |
+| 原生 workflow 通知与站内入口 | [通知集成](references/notifications.md) |
 
-危险操作一律使用“Agent 文字询问 → 用户文字回复”的两阶段确认，不依赖按钮、卡片、默认选项或隐式授权。危险操作包括：删除或不可恢复地覆盖 Base、应用、表、字段、业务记录、Function 或 binding；关闭 workflow、高级权限或改变已有角色权限；发布 Prod；以及其他可能造成不可逆外部影响的动作。常规工程文件增量修改、只读查询、非破坏性配置和 Preview 发布不属于此范围。
+新建或整体改版先在内部规划中确定视觉方案，再实现设计变量和组件。业务建模与通用工程取舍按[工程质量](references/style-guide.md)执行；默认不创建额外设计文件，用户要求文档时按要求交付。
 
-1. 当前 turn 只用文字说明拟操作对象、影响范围、不可逆结果和将执行的具体动作，并明确要求用户用文字确认；说明后必须立即结束本轮，不得调用对应的写入、删除、关闭或发布工具。
-2. 只有用户在后续消息中针对同一对象给出明确肯定答复，才执行该危险操作。任务开始时的“全部完成”“帮我搭建并发布”等笼统指令不能代替这次确认；Preview 交付后用户明确回复“部署正式版”可以作为本次 Prod 发布确认。
-3. 用户拒绝、改变对象、缩小或扩大范围，或回复仍有歧义时，不执行原动作；按新范围重新说明并再次等待文字确认。
-4. 确认只授权已说明的对象和动作。执行目标、影响范围或 payload 发生变化时，必须重新确认，不得沿用旧确认。
+## 关键约束
 
-## 平台不变量
+1. 应用 资源与发布优先使用本机 `base-database-cli`；原生 Base 配置使用 `lark-cli base +...`。托管环境使用宿主提供的 CLI，不切换环境。命令选择与工程恢复见[工程与环境](references/workspace.md)。
+2. Base 是业务数据事实源，`catalog.json` 是已绑定表的 schema 事实源。表、字段、ID、类型、选项和关系来自真实结果，不由名称或建模输入猜测。
+3. **权限边界**：应用 以 owner 身份访问 Base。访问者可调用已发布的 Function，也可使用已绑定表的平台写入通道；页面显隐和 FaaS 校验不能封闭所有写入路径。可信访问者身份通过 SQL `CURRENT_USER_ID()` 获取。绑定与权限设计必须遵守[权限边界](references/permission-design.md)。
+4. Page 读取走 SQL Function，写入走 FaaS。SQL Function 必须引用至少一个已绑定 Catalog 真实表；纯常量与无表依赖计算在 Page/FaaS 处理。输入只能进入声明的业务参数，不能决定 SQL、URL、method、Base token、table ID、字段名、Function ID 或凭证。
+5. SQL 与 FaaS 的参数、返回值不同。Page 使用 `invokeDatabaseFunction<TData>`，`TData` 只描述顶层 `data`，不二次解包；协议见[Page 开发](references/development.md#function-调用契约)。FaaS 批量写入的部分成功与重试边界见[记录协议](references/faas.md#应用记录-写入协议)。
+6. 修改保留需求外源码、Base schema、metadata、bindings 和 Function。Functions 更新为全量覆盖，不能以只提交本次新增 Function 的方式更新已有 应用。
+7. 保留 starter 的 `createArgusCsrfPlugin()`、ready 上报及宿主组件接入。附件能力取决于目标环境的父页面、FaaS runtime 和服务端协议；按[文件传输](references/file-transfer.md)实现，不以模拟成功代替真实能力。
+8. **交付边界**：常规发布先 Preview。新建 Base 的示例记录必须写入真实 Base，并用页面实际调用的 SQL Function 回读；不以静态 fixture、`localStorage` 或页面自动播种代替。之后完成相关通知配置并报告 `agentGuide` 中的本应用 Skill 安装结果，再交付；自动安装不构成业务调用或 Prod 发布授权。完整顺序只在[发布与交付](references/release.md)维护。
 
-1. 公开 CLI 只使用 `online` 环境，并显式传入 `--env online`；内部托管运行时使用宿主提供的唯一默认环境。CLI、OpenAPI、Accounts、应用管理后台和 Page 运行时必须保持同一环境，并始终使用 `--as user` 身份。
-2. 托管 Builder 严格按 `snapshot|artifact|empty` 分支执行；只有 empty 分支进入新建顺序。非托管新建顺序为自动判定 Base 来源 → 默认从零设计完整 schema，或按 Prompt 明确指定的已有 Base 取得 token → CLI `init` → 读取 Catalog并开发 → CLI `deploy` Preview。从零搭建应用还必须在交付 Preview 前完成 `lark-cli` 写入示例数据、页面 SQL Function 回读的真实数据闭环。用户确认效果后回复“部署正式版”，再执行 CLI `deploy --production --yes`。
-3. 优先缩短用户首次体验时间。代码完成后尽快发布 Preview 并交给用户体验，以用户反馈驱动后续迭代。
-4. Base 是业务事实源，`catalog.json` 是已绑定表的 schema 事实源。表名、字段名、ID、类型和选项以 Catalog 为准。
-5. Base 读取使用 SQL Function；每个 SQL Function 必须引用至少一个已绑定 Catalog 真实表，纯常量、纯参数或不依赖真实表的派生表/CTE 查询在 Page/FaaS 中用代码处理。由 Page 主动发起的记录创建、更新和删除，通过 FaaS 调用目标环境的三个固定批量写入路由；附件追加和移除使用两条专用增量路由，受[文件传输](references/file-transfer.md)中的能力与并发边界约束。Page 不传 Base token；FaaS 写入的路径参数固定取 `catalog.json` 中该表的 `tables[].baseToken` 与 table ID，这两个值是工程常量，请求由 FaaS runtime 识别后转成服务端回调，由服务端校验表绑定关系并以应用所有者 身份落库。同表每批创建、更新或删除 1～200 条记录。批量更新和删除会跳过不存在的记录，以 `code: 0` 和 `data.record_not_found` 返回部分成功结果；FaaS 必须保留已完成与未找到的记录，不得误判为下游协议异常或自动整体重试。从零搭建应用的示例数据在 Preview 发布后通过 `lark-cli base +record-batch-create` 写入真实 Base，再调用页面实际使用的 SQL Function 回读；不得用 Page 自动播种、静态 fixture、`localStorage` 或 mock 代替真实记录。环境地址、鉴权机制及完整请求和响应协议见[代码开发手册](references/development.md#应用记录写入协议)。
-6. Page 和 FaaS 只调用固定 operation。用户输入不能决定 SQL、URL、method、Base token、table ID、字段名、Function ID 或平台凭证。
-7. Functions 更新是全量覆盖。修改已有应用时保留需求外 Function；删除 Base、表、字段、Function、binding 或应用必须遵守[危险操作确认](#危险操作确认)，先完成 Agent 询问与用户回复两阶段文字确认。
-8. Preview 是常规发布的强制前置流程。从零搭建应用发布成功后先按[示例数据验收](#从零搭建应用示例数据验收)完成窄范围运行态验证，再展示命令返回的顶层 `baseAppUrl` 和限制并停止；其他场景发布成功后立即交付并停止。管理后台 URL、旧 Preview URL 和发布平台静态资源 `staticUrl` 都不向用户展示。只有用户体验后明确回复“部署正式版”，才发布 Prod。
-9. 浏览器 SDK 的 `invokeFunction<TData>` 对 SQL 和 FaaS 都只返回一层 `{data,code,msg}`；`TData` 只描述当前 operation 约定的顶层 `data`，不得套入 FaaS handler 的返回类型或二次解包。
-10. FaaS 写入先确定一致性、部分成功和重试语义，再按已确认的业务要求设计最短远程调用链；不通过堆叠请求模拟 Base 不具备的事务能力。
-11. FaaS 下游失败使用稳定业务码和 `data.errors` 白名单诊断分层返回；保留安全的上游 `code`、`msg`、LogID 和失败步骤，不透传完整请求、响应、headers、stack 或凭证。具体协议见[代码开发手册](references/development.md#下游错误归一化)。
-12. 新建应用必须提供非空 `description`。优先使用用户原文；用户未提供时，根据已确认需求生成一句客观描述，概括使用对象和核心用途，不写营销口号、实现细节、目标环境或 Preview/Prod 发布状态。
-13. 创建或修改 Page 时，必须保留 starter 中的 `createArgusCsrfPlugin()` 配置；不得复制插件实现或手写 `x-secsdk-csrf-token`。旧应用需升级 JSSDK 并重新构建发布。
-14. 原生 workflow 为本应用发送通知时，按固定优先级确定每个 `LarkMessageAction` 的入口策略：用户明确要求进入多维表格时使用 `base_action`；用户明确要求通知纯展示、无需任何点击入口时才使用 `informational`；其他所有与应用业务对象关联的通知一律使用 `site_action`。不得因为通知正文已包含业务信息、用户未指定跳转目标或原生 workflow 更容易跳 Base，就推断为 `informational`。访客登记后通知被访人属于 `site_action`，即使正文已包含访客姓名、公司和来访事由，也必须提供进入当前访客登记详情的显式入口。`site_action` 必须提供显式 `openLink` 按钮，指向与通知业务动作对应的应用内功能路由，并使用 workflow 上下文中的最小稳定标识直接定位目标对象；Page 必须先实现该路由，考试通知同理进入对应考试或答题页，而不是应用首页。CLI 返回的顶层 `baseAppUrl` 是唯一可信用户入口；禁止使用发布平台静态资源 `staticUrl`、Base `recordLink`、Base URL、应用管理后台 URL 或根据应用 token 猜测的地址。新 workflow 延后到 Preview 发布成功后创建，取得命令返回的顶层 `baseAppUrl` 后直接在 `+workflow-create` 中写入最终应用链接，再执行 `+workflow-enable` 和 `+workflow-get`；只有修改已有 workflow 才执行 `+workflow-get` → 完整 read-modify-write `+workflow-update` → `+workflow-enable` → `+workflow-get`。`informational` 可以使用 `btn_list=[]`，但必须记录用户明确要求纯展示的原文；空按钮不代表通知不可点击，也不能证明它不会沿平台默认行为跳转 Base。任一应用路由、对象标识、最终链接或回读不满足约束时，立即执行 `+workflow-disable`，并把交付标记为 partial 或 blocked；不得降级成 `informational` 或宣称通知完成。CLI 发布应用不会自动修改 Base workflow；Preview 和 Prod 每次发布后都必须显式完成对应环境的通知入口收尾。
+## 外部操作与授权
 
-## 1. 理解需求并判定 Base 来源
+只读查询、已授权的工程修改、非破坏性配置和 Preview 发布可连续完成。只在动作缺少必要授权时请求确认，不重复询问已明确的目标和动作。
 
-明确应用名称、应用描述、用户角色、核心对象、对象关系、状态流转、页面任务和一条可验收的端到端路径。应用描述用一句话概括使用对象和核心用途；通常只使用一个 Base。同时按[权限与访问设计](references/permission-design.md)回答访问模型三问——谁能打开应用、门内谁能看什么、谁能做什么；后续 binding 范围、SQL Function 和写入链路的设计都受该访问模型约束。
+删除或不可恢复地覆盖资源、业务记录、Function 或 binding，关闭 workflow/高级权限、改变已有角色权限，以及 Prod 发布前，确认用户授权覆盖具体目标、动作和实质影响。缺少授权时，先准备可审阅的对象和影响说明，提出确认请求后等待用户明确回复；等待期间不得调用该动作对应的外部变更工具。默认选项、超时、登录授权和工具提示本身不构成该业务动作的授权。
 
-不要询问用户选择数据来源，也不要展示“从零创建”与“使用已有 Base”的选项。按 Prompt 自动路由：
+非文字确认只有在宿主文档明确声明单次业务动作确认机制、且其回执绑定具体目标、动作、实质影响和用户确认结果时才可采用；生产发布还须绑定本次 Preview 制品。没有该契约时，不推断卡片点击或工具执行审批具有相同效力。当前 Builder 未声明这类业务确认机制，因而仅接受用户针对本次动作的明确文字回复；device-flow 登录授权不能代替业务确认。
 
-- **默认从零创建 Base**：Prompt 未明确指定已有 Base 时，直接根据需求设计完整 schema，每类核心对象一张表，再执行 `init --schema`。用户描述需要哪些业务表或字段属于建模需求，不代表存在已有 Base。
-- **使用已有 Base**：仅当 Prompt 明确提供 Base token、Base 链接，或明确要求基于某个已有 Base 搭建时进入该路径。优先从 Prompt 解析 token；若明确指定了已有 Base 但无法取得 token，只补问 Base token，不再询问来源选择。随后执行 `init --base-token`。`init` 会只读列出该 Base 的全部表、创建并绑定新应用、获取 Catalog；不得先复制 Base，也不得在初始化阶段创建、删除或修改已有表和字段。
+Prod 还要求用户已体验本次 Preview 并明确同意发布同一制品。“部署正式版”是有效表达的示例，不是唯一口令；任务开始时笼统的“搭建并发布”不能代替本次制品确认。目标、制品或实质影响变化时重新确认；无影响的格式变化不使已有授权失效。
 
-已有 Base 路径不根据 prompt 猜测字段，默认将该 Base 的全部表绑定到新应用；绑定全部表不代表页面需要暴露全部数据。初始化后先把 `catalog.json` 与用户需求逐项映射，确定需求实际使用的表、字段、关系和选项，再设计相应的页面与 operation。若 Catalog 缺少完成需求所必需的数据结构，先向用户说明缺口并取得修改 Base 的明确授权；未授权时按现有 Catalog 实现可支持范围。
+workflow 启停及失败补偿按[通知集成](references/notifications.md#状态与失败处理)执行；不得以验证失败为理由未经授权关闭用户已有 workflow。通知接收人、触发条件和外发行为应属于用户明确要求的业务流程，不能从泛化建站请求自行增加。
 
-例如 Todo 系统：
+## 完成条件
 
-```text
-应用名称：Todo 管理
-应用描述：供个人集中创建、跟踪和完成日常任务
-对象：任务
-状态：待处理 → 进行中 → 已完成
-页面：任务列表、创建任务、任务详情
-查询：listTasks、getTask
-写入：createTask、updateTaskStatus
-验收：创建任务 → SQL 查到记录 → 更新状态 → SQL 查到新状态
-```
+完成条件由当前任务决定，不能把“发布成功”当作“整体完成”。常规 Preview 交付后等待用户体验；用户继续要求修改、排障或验收时进入相应路径，不受上一轮停止条件限制。
 
-常用 Field JSON：
+- **完成**：本次约定的交付项已完成，验证范围与证据明确。
+- **部分完成**：已有成果可交付，但某些功能、验证或外部配置未完成，逐项列出。
+- **阻塞**：必需步骤受认证、权限、平台能力或缺失输入等外部条件限制，记录阻塞及恢复条件。
 
-| 业务数据         | Field JSON                                                                       |
-| ---------------- | -------------------------------------------------------------------------------- |
-| 标题、备注、电话 | `{"type":"text","name":"标题"}`                                                  |
-| 数量、金额       | `{"type":"number","name":"金额"}`                                                |
-| 单选状态         | `{"type":"select","name":"状态","multiple":false,"options":[{"name":"待处理"}]}` |
-| 多标签           | `{"type":"select","name":"标签","multiple":true,"options":[{"name":"高优"}]}`    |
-| 日期时间         | `{"type":"datetime","name":"截止时间","style":{"format":"yyyy-MM-dd HH:mm"}}`    |
-| 布尔值           | `{"type":"checkbox","name":"已完成"}`                                            |
-| 表间关系         | `{"type":"link","name":"关联任务","link_table":"任务"}`                          |
-| 审计字段         | `created_at`、`updated_at`、`created_by`、`updated_by`                           |
-| 附件             | `{"type":"attachment","name":"附件"}`；读写见[文件传输](references/file-transfer.md) |
+默认交付访问链接、业务变更、体验步骤、实际验证结果和影响使用的限制。仅使用发布命令返回的顶层 `baseAppUrl` 作为应用访问入口；不猜测地址或展示内部静态资源 `staticUrl`。技术清单与诊断信息按研发、排障或审计需要提供；不输出凭证，也不要求普通业务用户检查协议字段。
 
-`datetime.style.format` 使用 Base 支持的固定枚举；当前可配置格式最多显示到分钟，底层时间值仍可保留秒级精度。
+## 术语
 
-首个字段是表的主字段。公式和 lookup 是只读派生字段，只在结果需要长期展示在 Base 时使用。
-
-## 2. 初始化数据库应用
-
-初始化前检查 `BASE_SITE_BUILDER_SITE_TOKEN`。变量非空表示宿主已经创建目标应用：使用 Sandbox 已安装的 `base-database-cli` 可执行文件，并在本节的 `init` 命令中追加 `--app-token "$BASE_SITE_BUILDER_SITE_TOKEN"`。该模式仍按需求创建或复用 Base，但只调用已有应用的 `bind_base` 和 `catalog`，不会调用应用创建接口。不要手写 `base-database.jsonc`、不要绕过 CLI 拼装低层 `lark-cli` 请求，也不要用新应用掩盖绑定失败。
-
-### 从零创建 Base
-
-把全部表写入一个 schema 文件。这个文件是 `init` 的输入，不是平台请求缓存：
-
-```json
-{
-  "tables": [
-    {
-      "name": "任务",
-      "fields": [
-        { "type": "text", "name": "任务名称" },
-        {
-          "type": "select",
-          "name": "状态",
-          "multiple": false,
-          "options": [
-            { "name": "待处理" },
-            { "name": "进行中" },
-            { "name": "已完成" }
-          ]
-        },
-        {
-          "type": "datetime",
-          "name": "截止时间",
-          "style": { "format": "yyyy-MM-dd HH:mm" }
-        },
-        { "type": "text", "name": "备注" }
-      ]
-    }
-  ]
-}
-```
-
-在项目目录执行初始化命令：
-
-```bash
-npx @lark-base-open/base-database-cli init . \
-  --env online \
-  --name 'Todo 管理' \
-  --description '供个人集中创建、跟踪和完成日常任务' \
-  --schema ./base-schema.json
-```
-
-托管 Sandbox 已有应用场景执行：
-
-```bash
-base-database-cli init . \
-  --name 'Todo 管理' \
-  --description '供个人集中创建、跟踪和完成日常任务' \
-  --schema ./base-schema.json \
-  --app-token "$BASE_SITE_BUILDER_SITE_TOKEN"
-```
-
-### 使用已有 Base
-
-取得已有 Base 的 `bas...` token 后执行：
-
-```bash
-npx @lark-base-open/base-database-cli init . \
-  --env online \
-  --name 'Todo 管理' \
-  --description '供个人集中创建、跟踪和完成日常任务' \
-  --base-token basxxxxxxxx
-```
-
-托管 Sandbox 复用已有 Base 与已有应用时，同样改用 `base-database-cli init` 并追加 `--app-token "$BASE_SITE_BUILDER_SITE_TOKEN"`。
-
-该命令调用只读 Base 接口获取 Base 信息并分页列出全部表。未指定 `--app-token` 时，通过应用创建接口的 `baseBindings` 绑定这些表；指定时，通过目标应用的 `bind_base` 绑定这些表。最后从目标应用获取 Catalog。它不会创建或修改 Base、表、字段和记录。
-
-两种路径必须且只能传入 `--schema` 或 `--base-token` 之一，并始终传入非空 `--description`。公开 CLI 的 `--env` 默认且只支持 `online`；托管 Sandbox 使用内部运行时的默认环境。从零路径连续建表会串行等待 2 秒。
-
-成功结果的 `baseSource` 和 `databaseSource` 分别为 `created` 或 `existing`；新建资源位于 `created`，复用资源位于 `reused`，同时列出表、应用、binding 和工程文件。开始开发前确认以下产物：
-
-```text
-base-database.jsonc      # 应用 token 与 Base binding
-base-schema.json     # 仅从零路径存在，是本次建库输入
-catalog.json         # 已绑定数据表的真实 schema
-page/                # React 页面
-sql/                 # SQL Functions
-server-functions/    # 服务端 FaaS Functions
-.base-database-cli/      # 被 Git 忽略的 CLI 本地状态与临时制品
-```
-
-只从 `catalog.json` 读取表名、字段名、ID、选项和 SQL 类型，不根据建表输入猜测 Catalog 结果。
-
-### 应用控制面调试
-
-除修改已有应用时追加 Table binding 外，正常应用开发不直接调用项目级 `base-database-cli lark-cli -- ...`。仅排查应用控制面接口、授权或 LogID 时，进入包含 `base-database.jsonc` 的项目根目录执行：
-
-```bash
-npx @lark-base-open/base-database-cli lark-cli -- \
-  api GET /open-apis/base/v3/sites/list \
-  --params '{"pageSize":1}' --json
-```
-
-该命令校验当前目录的项目配置，并在线上环境原样运行后续参数；`api` 和 `base` 命令自动使用 `--as user`。它不是原生 Base 业务能力的唯一入口；能力发现与配置按[原生 Base 能力发现与路由](references/base-capability-routing.md)直接执行 `lark-cli base +...`。
-
-## 3. 开发
-
-读取 `catalog.json` 和 starter 源码，确定 operation 的固定输入与输出，然后在 `sql/`、`server-functions/` 和 `page/` 中完整实现 SQL、服务端 FaaS Functions 和 Page；不创建额外的 operation 设计文件。保持以下边界：
-
-- Page 读取 Base 使用 SQL Function；
-- Page 写入使用 FaaS；
-- 示例数据写入与业务写入实现分离：示例数据只用于发布后初始化真实 Base，不要求为了播种额外创建 FaaS Function；页面业务写入仍使用 FaaS；
-- SQL 和 FaaS 调用都使用 `params`，但 SQL 是按 `$1`、`$2` 排列的数组，FaaS 是传给 handler `rawParams` 的业务对象；
-- 页面不直接调用 Base records OpenAPI；
-- 附件上传走 `siteRuntime.uploadAttachment()`；缩略图用 `buildAttachmentCoverUrl(context, ref)`，下载用 `fetchAttachmentDownloadUrl(context, ref)`，业务代码只提供业务坐标、不自己拼 `extra`；追加/移除附件经 FaaS 调 `append_attachments` / `remove_attachments` 增量路由，`batch_update` 只用于整格置空或明确重设。目标环境须已支持该链路；服务端仍有并发覆盖窗口，append 不去重、不幂等，超时后保留已上传 token 并核对，不自动重提或重新上传。详见[文件传输](references/file-transfer.md)。
-
-实现代码前，对每个首屏加载和用户动作做一次远程调用拓扑检查：
-
-1. 列出 SQL Function、FaaS Function、`context.fetch` 和写入 OpenAPI 调用，并标记每个调用在 operation 开始时已经具备的输入。
-2. 如果后一个 SQL 的参数只是前一个 SQL 返回的关联 ID，先把关系下推到同一个 SQL Function；这种数据库内部关系不是保留两次远程调用的理由。
-3. 如果多个无副作用读取的输入均已确定，先创建全部 Promise，再在共同消费结果的位置一次 `await Promise.all(...)`；不要按代码书写顺序连续等待。
-4. 只有按需加载、权限或失败语义隔离、结果规模明显放大、SQL 方言无法表达，或后一步确实依赖前一步业务判断时才拆分，并在实现或交付说明中记录原因。
-
-从零搭建应用在实现阶段同时设计一组小而完整的示例数据，覆盖默认展示需要的核心对象、典型状态和必要关联。示例值必须非敏感、可被用户识别，并在业务主字段中使用稳定的“示例”标记；不为示例数据额外污染 schema。存在列表、详情、看板、统计或其他业务数据展示时，Page 必须调用真实 SQL Function 查询 Base 并渲染结果，不能把示例数组硬编码在 Page、FaaS、`localStorage` 或 fallback mock 中。页面加载时不得静默自动播种，避免多用户访问或刷新产生重复记录。
-
-代码完成后进入 Preview 发布；依赖安装、production build 和服务端 SQL 校验由 `deploy` 统一执行。
-
-## 4. 发布 Preview
-
-在包含 `base-database.jsonc` 的目录执行唯一的发布命令：
-
-```bash
-npx @lark-base-open/base-database-cli deploy
-```
-
-`deploy` 通常需要约 30 秒到 1 分钟，中间不显示阶段进度。等待该命令返回最终结果；依赖安装、构建、校验和发布均由 CLI 内部完成。
-
-### 从零搭建应用示例数据验收
-
-本节只适用于本次创建了新 Base 的从零搭建应用；复用已有 Base、修改已有应用时不得擅自添加示例记录。
-
-1. 从 `catalog.json` 读取真实 `baseToken`、table ID、字段类型和选项。先通过项目路由执行 `npx @lark-base-open/base-database-cli lark-cli -- base +field-list --base-token <base-token> --table-id <table-id>` 核对可写字段，再使用 `npx @lark-base-open/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. 存在列表、详情、看板、统计等业务数据展示时，通过项目路由调用页面实际使用的 SQL Function，而不是用 `+record-list` 代替展示链路验收：`npx @lark-base-open/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，并确认刚写入的示例记录、关系和统计真实可见。
-4. 重复验证或修复后重试前，先用同一 SQL Function 按稳定示例标记或已返回的 record ID 确认当前状态，只补写缺失数据。创建结果未知时禁止盲目重试，避免生成重复记录。
-5. `lark-cli` 写入失败、返回记录数不符、SQL Function 返回非零业务码、响应结构不符合契约，或查询不到已确认写入的数据，都视为示例数据闭环未完成。保存脱敏错误和 LogID；写入问题检查 Catalog、字段、CellValue、关联 ID 和权限，查询问题检查 SQL、参数及响应解析。实现问题修复后重新 `deploy`，再从本节第 1 步验证。
-6. 只有认证、权限或平台服务存在证据充分的外部阻塞时才标记 `blocked`；不得声称示例数据或整体从零搭建应用已完成。示例写入与 SQL 回读均通过后，才进入通知 workflow 收尾并向用户交付 Preview。
-
-该闭环不需要浏览器，也不替代用户对 Page 真实写入流程、交互状态和 UI 的 E2E 验收，更不构成 Prod 发布授权。不得读取、输出或代填用户凭证。
-
-非从零场景，或从零场景完成上述闭环后，只把命令返回的顶层 `baseAppUrl` 交给用户，提示用户在飞书登录态继续体验页面，然后立即停止。不要展示管理后台 URL、旧 Preview URL 或内部静态资源 `staticUrl`；除上述闭环外，不要打开浏览器或直调 SQL/FaaS 做运行态验收。
-
-本次存在原生通知 workflow 时，示例数据验收通过后再按入口策略完成发布收尾，避免示例记录触发面向真实接收人的通知。`site_action` 只使用本次 `deploy` 返回的顶层 `baseAppUrl`：新 workflow 此时才执行 `+workflow-create`，一次性保留该 URL 的 `mode=edit` 等既有查询参数，并加入 Page 已实现的功能定位参数和 workflow 中的目标对象标识，再启用并回读；已有 workflow 才先 `+workflow-get`，用完整定义执行 `+workflow-update`，随后启用并回读。不得使用内部静态资源 `staticUrl`、`recordLink`、Base URL、管理后台 URL 或猜测的 Preview URL。`informational` 必须有用户明确要求纯展示的原文，并回读确认没有按钮；`base_action` 必须有用户明确要求进入多维表格的原文。回读时逐个核对本次创建或修改的 `LarkMessageAction`，并在交付清单记录 workflow ID、入口策略、按钮字段路径和环境无关的功能定位参数。任一配置或回读不满足约束时立即执行 `+workflow-disable`，并把交付标记为 partial 或 blocked，不得报告通知或整体系统已完成。完成原生配置后再向用户交付 Preview 并停止；这不授权继续调用 Function 或发布 Prod。
-
-### 部署后自动安装应用 Skill
-
-每次 Preview / Prod 发布成功后，CLI 会从模板生成本应用专属 Skill，自动安装到当前执行用户的 `$CODEX_HOME/skills`（未配置时为 `~/.codex/skills`）；同一应用和平台环境使用固定目录，每次部署更新生成的 `SKILL.md`，不覆盖其他 Skill 或附加文件。无需再询问用户是否安装，也不要自行重复安装。
-
-交付时读取 `agentGuide.skill` 和 `agentGuide.message`：安装成功后简短告知用户“已安装/更新本应用 Skill，后续可直接让 Agent 使用本应用能力”，并给出 `$<skill.name>`。客户端尚未刷新 Skill 列表时提示开启新会话。Preview 同时说明 Skill 发现的是正式版，不代表本次 Preview；不得因为安装成功就自动执行发现、业务写入或 Prod 发布。
-
-安装失败不改变已经成功的发布结果。单独报告原因；需要修复安装时读取[应用能力 Skill](references/database-capability-skill.md)，不要重新部署掩盖安装失败。托管环境的执行用户目录不等于终端用户电脑，不能把沙箱内安装描述成已安装到用户本机。
-
-## 5. 等待用户体验
-
-此前任务中的“搭建并发布”不包含 Prod 授权。用户没有明确回复“部署正式版”时，不继续调用接口、修改代码或发布。
-
-## 6. 发布 Prod
-
-用户体验后明确回复“部署正式版”，才执行：
-
-```bash
-npx @lark-base-open/base-database-cli deploy --production --yes
-```
-
-该命令读取 `.base-database-cli/state/preview.json`，校验本地 Artifact SHA-256 和生成 Preview 时记录的工作区输入指纹后，直接把同一份已验证制品发布到 Prod，不重新构建或上传。没有 Preview 记录、应用 token 不匹配、回执缺少输入指纹、Artifact 变化或 Preview 之后源码/配置/文件结构发生变化时停止，重新执行普通 `deploy` 并等待用户验证新的 Preview。
-
-Prod 发布应用本身不会自动更新 Base workflow。只要本次应用存在通知业务入口，无论当前链接看起来是否已正确，Prod 发布成功后都必须使用命令返回的顶层 `baseAppUrl`，按 Preview 交付清单逐个更新 workflow：只替换环境入口，逐字保留功能定位参数、动态对象参数、其他步骤和启用状态，然后回读确认所有应用 `openLink` 都以生产 `baseAppUrl` 为基础，且不再包含 `mode=edit`。任一 workflow 更新或回读失败时，必须明确报告“Prod 已发布，但通知入口切换未完成”，保留失败证据且不得把整体 Prod 交付报告为完成；不得通过重新发布 Prod 掩盖外部配置失败。
-
-正式发布后只交付生产 `baseAppUrl` 作为访问 URL，并附页面/表/operation 清单、用户已确认的 Preview，以及 FaaS 运行时等仍存在的平台限制。若本次需求涉及附件而目标环境尚未开通该能力，按[文件传输](references/file-transfer.md)的门禁把它记为平台限制。
-
-## 修改已有数据库应用
-
-托管 Builder 必须按宿主变量执行：
-
-- `snapshot`：完整工程已经恢复；禁止 `init` 和 `pull`，读取 `base-database.jsonc`、`catalog.json` 与现有源码后只实现需求差异。
-- `artifact`：第一项工程操作固定为 `base-database-cli pull . --app-token "$BASE_SITE_BUILDER_SITE_TOKEN"`；pull 失败立即停止，禁止退回 `init`。成功后读取工程并增量修改。
-- `empty`：仅用于应用没有源码且没有 Base binding 的新建流程；执行一次带 `--app-token` 的 `init`，不得创建另一个应用。
-
-修改已有应用时需要使用当前已绑定 Base 中的新 Table，不重新执行 `init` 或 `pull`。先用 `lark-cli base +table-list/get` 的真实返回取得 Table ID，再在项目根目录执行：
-
-```bash
-npx @lark-base-open/base-database-cli lark-cli -- api POST /open-apis/base/v3/sites/Prjxxxxxxxx/bind_base --data '{"baseToken":"basxxxxxxxx","tableIds":["tbl_new"]}' --json
-npx @lark-base-open/base-database-cli lark-cli -- api GET /open-apis/base/v3/sites/Prjxxxxxxxx/catalog --json
-```
-
-`bind_base` 只向同一 Base 追加并去重 Table ID，不覆盖原绑定。成功后把 Catalog 返回 envelope 的 `data` 对象写入 `catalog.json`，并在 `base-database.jsonc` 保留原 binding 的前提下把新 ID 合并进 `tableIds`。删除本地 Table ID 不会触发远程解绑；解绑须另行调用 unbind 接口并先完成[危险操作确认](#危险操作确认)。
-
-故障恢复时若宿主明确说明 Pi Session 未恢复，但 Workspace 已恢复有效工程，禁止 `init` 和 `pull`，先读取当前工程再继续本轮需求。所有修改流程都要保护需求外源码、Base schema、应用元信息 和 bindings；完成后重新执行 CLI `deploy`，等待用户确认 Preview，再发布 Prod。
-
-## 失败与交付
-
-环境、授权、生产数据边界或关键平台协议不可用时，停在受影响阶段，一次性汇总目标环境、method/path、脱敏响应和 LogID/Edge request ID。发布状态成功但访问 URL 返回 404/5xx 时，同时保留 URL、HTTP 状态和响应 LogID；不要猜替代协议、改写 URL、回退正式环境或用新资源掩盖错误。
-
-Preview 交付至少包含顶层 `baseAppUrl`、业务页面和 operation 清单、发布制品摘要，以及仍存在的平台限制。从零搭建应用还要列出示例数据覆盖的核心对象、实际执行的写入命令、查询 Function 和验证结果；未完成时明确标记 `blocked`，不能省略。托管页面由用户在飞书登录态下体验；管理后台 URL、旧 Preview URL 和内部静态资源 `staticUrl` 不向用户展示。
+- **应用 appToken**：应用标识；协议字段 `appToken`、FaaS 的 `projectId` 与示例中的工程常量 `PROJECT_ID` 在相应入口指向该应用，不是 Base token。`PROJECT_ID` 由示例调用方定义，不是 starter 提供的标识。
+- **Catalog**：已绑定数据表的 schema；本地快照为 `catalog.json`，更新从 应用 catalog 接口获取。Base 的业务记录不保存在 Catalog。
+- **operation**：业务动作及其固定输入输出契约，例如查询任务或审批申请；不是任意 URL/SQL 的代理。
+- **一方/三方**：分别指托管 Builder 与外部 Agent 搭建。两者使用同一设计原则，仅 CLI、环境和工程恢复来源不同。

package/skills/lark-base-database/references/base-capability-routing.md

@@ -1,6 +1,6 @@
 # 原生 Base 能力发现与路由
 
-当 `lark-base-database` 无法确认某项功能时，使用本流程查询飞书多维表格本体能力。不要从 数据库应用开发文档未提及、Catalog 未展示或记忆中的旧版 CLI 推导“不支持”。
+当 `lark-base-database` 无法确认某项功能时，使用本流程查询飞书多维表格本体能力。不要从 Base Database 文档未提及、Catalog 未展示或记忆中的旧版 CLI 推导“不支持”。
 
 ## 触发条件
 
@@ -8,7 +8,7 @@
 
 - 选择 Page、SQL Function、FaaS 或原生 Base 的实现归属；
 - 删除、简化或降级一项用户需求；
-- 声称多维表格、数据库应用开发链路或 `lark-cli` 不支持某项能力；
+- 声称多维表格、Base Database 或 `lark-cli` 不支持某项能力；
 - 用 FaaS 模拟定时触发、记录变化触发、提醒、通知、权限控制等 Base 本体行为。
 
 ## 查询顺序
@@ -17,7 +17,7 @@
 2. 运行 `lark-cli base --help`，从当前安装版本的 shortcut 列表查找相关资源；不要依赖旧版命令记忆。
 3. 对候选命令运行 `lark-cli base +<shortcut> --help`，确认它支持 list/get/create/update/enable 等哪些动作、需要哪些 ID 和 JSON。
 4. 已有 Base 先解析真实 `base_token`，再用只读命令确认资源和现状。优先从 `+base-block-list` 看 Base 内资源，再进入对应的 list/get；表、字段、视图和其他资源 ID 必须来自真实返回。
-5. 当前环境提供 `lark-base` Skill 时，读取其快速路由和对应 reference 后再构造复杂 JSON。不得猜 workflow steps、dashboard data config、role config、字段或记录 CellValue。
+5. 优先通过 `lark-cli skills read lark-base` 获取当前版本路由和对应 reference；命令不可用时读取环境中的 lark-base。构造复杂 JSON 前确认当前协议。不得猜 workflow steps、dashboard data config、role config、字段或记录 CellValue。
 
 最小发现命令：
 
@@ -53,29 +53,21 @@ lark-cli base +<resource-list-or-get> ... --as user
 
 查询完成后只选择以下一种结论：
 
-1. **原生 Base 实现**：能力由多维表格本体提供。通过 `lark-cli base +...` 配置，应用只提供需要的交互页面。
-2. **数据库应用实现**：能力属于页面交互、SQL 读取或由 Page 主动发起的即时业务写入，按 Page/SQL/FaaS 边界实现。
+1. **原生 Base 实现**：能力由多维表格本体提供。通过 `lark-cli base +...` 配置，应用 只提供需要的交互页面。
+2. **Base Database 实现**：能力属于页面交互、SQL 读取或由 Page 主动发起的即时业务写入，按 Page/SQL/FaaS 边界实现。
 3. **组合实现**：例如 Page/FaaS 创建记录，原生 workflow 监听记录并通知；分别配置并独立验收两段链路。
 4. **已证实的缺口或阻塞**：找不到当前 CLI 入口、命令明确不支持，或遇到权限或环境阻塞。准确描述为“当前 `lark-cli` 未暴露”“原生能力明确不支持”或“当前身份无权限”，不要互相替代。
 
-组合实现中的通知必须保持入口意图一致。创建 workflow 前逐个把 `LarkMessageAction` 归入以下一种策略：
+## 执行边界
 
-| 入口策略 | 适用场景 | 必须满足 |
-| --- | --- | --- |
-| `site_action` | 除下列两个明确授权场景外，所有与应用业务对象关联的通知 | Page 先实现真实功能路由；通知提供显式 `openLink`，使用发布返回的 `baseAppUrl`、功能定位参数和最小稳定对象标识 |
-| `informational` | 用户明确要求通知纯展示、无需任何点击入口 | `btn_list=[]`；记录用户原文，并披露原生通知仍可能沿平台默认行为跳转 Base |
-| `base_action` | 用户明确要求从通知进入多维表格 | 只在该明确要求下使用 Base `recordLink` 或 Base URL，不得描述成应用入口 |
+已在当前版本明确记录的限制，正常开发按对应协议处理，不重复查询相同能力。用户要求验证新能力、CLI 版本变化或新证据与文档冲突时再发现；原生能力存在不代表 应用 运行时代码可以直接调用其接口。
 
-不得因为通知正文已经包含业务信息或用户未指定跳转目标，就推断为 `informational`。访客登记后通知被访人固定属于 `site_action`：Page 必须提供当前登记详情路由，消息按钮必须进入该路由；即使通知正文已包含访客姓名、公司和来访事由也不例外。`lark-base` workflow 文档里的 `$.<trigger>.recordLink` 是通用 Base 记录链接示例，不适用于 `site_action`。此类 `LarkMessageAction.data.btn_list[].btn_action=openLink` 必须进入与通知动作对应、由 Page 已实现的站内功能，并通过查询参数携带直接定位目标业务对象所需的最小稳定标识。例如考试发布通知应进入该考试的详情或答题状态，而不是应用首页。`base-database-cli deploy` 返回的 `baseAppUrl` 是当前环境唯一可信的用户入口；不得使用内部静态资源 `staticUrl`、`recordLink`、Base URL、应用 `managementUrl`，也不得根据应用 token 自行拼接 Preview/Prod 地址。
+能力发现默认只读。用户要求的非破坏性原生配置可在取得真实 ID 后执行；已有资源的变更需在授权范围内。复杂 create/update 先读当前命令的 help 与 reference：完整替换使用可信现状做 read-modify-write，delta 只提交目标变更。读回必要结果，保留启停状态。授权规则见[主流程](../SKILL.md#外部操作与授权)。
 
-`btn_list=[]` 只说明没有显式按钮，不代表原生通知不可点击，也不能证明通知整卡不会沿平台默认行为跳转 Base。当前暴露的 workflow 配置没有关闭该默认入口的字段。用户要求任何点击都不得进入 Base 时，原生 `LarkMessageAction` 不能直接视为满足要求；继续执行能力发现，若找不到可完全控制链接的通知方案，则记录为平台阻塞，不能用 `informational` 绕过要求。
+涉及 应用 通知时，读取[通知集成](notifications.md)决定入口与状态；不得把原生通知样例的 recordLink 当作 应用 业务入口。
 
-新 `site_action` workflow 在 Preview 发布前不创建。Preview 发布后基于命令返回的顶层 `baseAppUrl`、代码中已经存在的功能定位参数和 workflow 上下文中的对象标识，一次性构造最终按钮链接，直接执行 `+workflow-create`、`+workflow-enable` 和 `+workflow-get`。只有修改已有 workflow 时才先读取完整定义，只替换按钮链接，再执行全量 `+workflow-update` 和回读。不得发明页面未实现的功能，也不得使用内部静态资源 `staticUrl`。Prod 发布不会触发 Base workflow 自动迁移；发布后必须按记录逐个更新已有 workflow，只替换为 Prod 命令返回的顶层 `baseAppUrl`，保留功能定位参数、动态对象参数、其他步骤和启用状态。
+## 发现结束与交付
 
-能力发现默认只读。新建系统中，用户要求的非破坏性原生 Base 配置属于应用开发范围，可在 `init` 返回真实 Base token 后执行；基于已有 Base 时，创建或修改原生配置前先确认它在用户授权的修改范围内。删除资源、关闭 workflow、关闭高级权限或改变已有角色权限时，必须按[危险操作确认](../SKILL.md#危险操作确认)先用当前 turn 的文字说明对象和影响，结束本轮，并在用户后续明确回复后再执行。
+候选命令、相关 reference 与必要只读查询已确认能力归属后，进入实现，不反复扫描整个资源目录。没有入口或权限不足时，记录查询过的命令、当前版本与证据，区分 CLI 未暴露、平台明确不支持和环境/权限阻塞。
 
-复杂 create/update 必须遵守对应 shortcut 的 `--help` 和 `lark-base` reference。更新要求完整配置时先 get，再 read-modify-write；支持 delta update 时提交最小合法 payload。完成写入后使用 list/get 回读，workflow 等有启停状态的资源还要核对实际状态。应用通知要逐个回读 `LarkMessageAction`：`site_action` 核对每个业务 `openLink` 最终使用当前发布环境返回的 `baseAppUrl`，并指向通知对应的真实功能及目标对象，而不是应用首页、Base 或管理后台；`informational` 和 `base_action` 分别核对存在用户明确要求纯展示或进入多维表格的原文。任一链接、对象标识、入口策略或回读不一致时立即执行 `+workflow-disable`，并把交付标记为 partial 或 blocked；不得把应用发布成功等同于整体交付完成。Prod 阶段还要确认应用链接不再包含 `mode=edit`。
-
-## 交付证据
-
-交付时把原生 Base 配置纳入资源和验收清单，至少报告资源类型、名称、真实 ID、启用状态和它与应用的衔接点。若记录缺口，附上实际查询过的命令、当前 CLI 版本或帮助输出结论，以及阻塞属于平台、CLI 覆盖还是权限；不得只写“Skill 没提到”或“没找到”。
+交付原生配置时记录资源 ID、实际状态及它与 应用 的衔接点；配置成功不等于通知或业务链路已经验收。

package/skills/lark-base-database/references/base-sql-unsupported.md

@@ -1,6 +1,6 @@
-# Base SQL 不支持能力
+# Base SQL 能力边界
 
-仅在判断支持集之外的 SQL 语法、评审或排查 SQL，或者处理 SQL 编译与运行兼容失败时读取。以下能力不写入 `main.sql`：
+仅在判断支持集之外的 SQL 语法、评审或排查 SQL，或者处理 SQL 编译与运行兼容失败时读取。本文件是当前生成与兼容策略：明确不支持的协议不使用；“默认不生成”“支持不统一”属于保守生成边界，不据此声称平台整体不支持。已知限制正常开发直接遵守，只有版本或验证证据变化时复核。以下形态不写入常规 `main.sql`：
 
 ## Stored Query 与分页