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

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

@@ -1,40 +1,29 @@
 ---
 name: lark-base-database
-description: 使用飞书多维表格作为业务数据后端，创建、修改、恢复、发布、验收或排查 Base Database 业务系统。适用于 Base Database 的 Page、Database Function、Mutation、FaaS 和原生 Base 集成；仅操作多维表格资源时使用 lark-base。
+description: 以飞书多维表格为业务数据后端，规划、搭建、修改、恢复、发布、验收或排查带页面与业务逻辑的 Base Database 网站、工作台或管理系统；支持从零或基于已有 Base 建站。仅管理多维表格的表、字段、记录、视图时使用 lark-base。
 metadata:
-  compatibility: 需要 Node.js 20.19+、npm/npx、lark-cli 及目标平台访问权限；优先使用本机安装的 Base Database CLI，托管环境使用宿主提供的 CLI。
+  compatibility: CLI/存量 classic 需要 Node.js 20.19+；新建 workspace 与契约生成需要 Node.js 22+；需要 npm/npx、lark-cli 及目标平台访问权限；优先使用本机安装的 Base Database CLI。
 ---
 
 # Lark Base Database
 
 将业务需求实现为基于真实 Base 数据、可维护且可验证的应用。先选择任务路径，再读取所需协议；不要在任务开始时读取全部 reference。同一文件在首次进入相关阶段时读取，内容或任务范围变化后再补读。
 
-CLI 使用 `--app-token`、配置字段 `appToken`、`base-database.jsonc` 和 `.base-database-cli/state/`，不读取旧配置或旧状态，不接受旧参数。服务端 `/sites/` 路径、SDK 的 `siteToken` 和宿主 `BASE_SITE_BUILDER_*` 环境变量保持原协议；将宿主提供的应用 token 传给 `--app-token`，不改造外部协议。
+本 Skill 面向开发者 Agent，用于搭建、修改和发布应用；`skill install` 安装这份随 CLI 分发的开发者 Skill。让外部 Agent 使用某个已发布站点的业务功能时，使用 `agent-tools skill install` 安装该站点的 Skill，见[外部 Agent 工具策略](references/agent-tools.md#安装到本地-agent)。
+
+新建 init 仅生成 workspace；存量 classic 的 SDK 接入和工程迁移按[工程与环境](references/workspace.md)与[Page 开发](references/development.md)执行。工程迁移按[迁移指南](references/workspace-migration.md)由 coding agent 执行；`dev` 仅在用户选择时使用。
 
 账号选择遵守[工程与环境的 profile 约定](references/workspace.md#账号选择)；直接调用原生 lark-cli 时也使用同一个 profile。
 `lark-cli` 的账号管理和文档命令按环境提供，不是所有宿主的必备能力；首次选择入口及缺少命令时按[环境与依赖](references/workspace.md#环境与依赖)处理。
 
-### 首次使用前的环境准备
-
-本地公开环境首次使用时，先确认依赖再进入任务路由；托管环境使用宿主已提供的 CLI 与凭证，跳过本节。
-
-1. 确认 `lark-cli` 与 `base-database-cli` 都可执行；任一缺失时按[环境与依赖](references/workspace.md#环境与依赖)中的安装命令或回退入口处理，不猜测包名或全盘搜索。
-2. 执行 `base-database-cli doctor`。返回未配置或未登录（`not_configured`、`token_missing`、`need_user_authorization`）时执行 `base-database-cli auth login`，由用户在浏览器完成授权后重新执行 `doctor`；`ok` 为 `true` 后再执行 `init`。`init`、`pull` 不会自动触发登录。
-
-### Base Database 权限不足时重新授权
-
-CLI 明确报告 `app_scope_not_applied`、`missing_scopes` 等 scope 权限不足错误时，向用户说明原因，并使用本任务已选定的 CLI 入口和同一 profile 执行 `base-database-cli auth login`，申请构建应用所需的权限。若错误另有应用权限开通或额外 scope 的处理要求，按错误提示处理。用户完成授权后只重试原命令一次；仍失败时停止并保留原错误，不循环授权。其他错误按其原因处理。AI Function 管理命令或 `deploy` 返回 `800004011`（`ai function feature is not enabled`）不是 scope 问题，`auth login` 无效；按[未开通 AI Function](references/ai-function.md#未开通-ai-function-时) 降级处理。
-
-### 公开 CLI 版本预检
-
-本地使用 `@lark-base-open/base-database-cli` 时，在本会话首次业务操作前按[工程与环境](references/workspace.md#公开-cli-版本预检)确认入口与版本；托管 Builder 和 CI 跳过。预检失败或旧 CLI 不支持时继续当前任务，升级及覆盖 Skill 须取得相应授权。
+开始前：本地公开环境首次使用时，按[环境与依赖](references/workspace.md#环境与依赖)确认 CLI、登录和版本。命令报告认证或 scope 错误时，按[认证与重新授权](references/workspace.md#认证与重新授权)处理，授权后只重试原命令一次。
 
 ## 任务路由
 
 | 用户任务                 | 执行路径                                                           | 主要命令                                                  | 进入阶段前读取                                                                            |
 | ------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
 | 新建系统                 | 明确需求与访问模型 → 确定 Base 来源 → 初始化 → 开发 → Preview 交付 | `init` → `deploy`                                         | [工程与环境](references/workspace.md)、[权限设计](references/permission-design.md)        |
-| 修改已有系统             | 确认现有工程 → 判断影响范围 → 增量修改 → 验证与交付                | 按影响范围修改，必要时 `deploy`                           | [工程与环境](references/workspace.md)，再读取受影响的协议                                 |
+| 修改已有系统             | 确认现有工程 → 判断影响范围 → 增量修改 → 验证与交付                | 按影响范围修改，必要时 `deploy`                           | [增量修改与追加绑定](references/workspace.md#增量修改与追加绑定)，再读取受影响的协议                                 |
 | 恢复远端工程             | 确认本地状态和应用 → 恢复源码与 Catalog → 继续原任务              | 按来源选择 `pull` 或 `init`                               | [工程与环境](references/workspace.md)                                                     |
 | 设计或评审               | 按评审范围分析并输出，不创建资源或发布                             | 只读分析                                                  | [工程质量](references/style-guide.md)，涉及权限、查询或视觉时读取对应专项                 |
 | 排查故障                 | 收集证据 → 定位失败阶段 → 按用户要求诊断或修复                     | `deployments status`、`doctor` 或项目级 `lark-cli -- ...` | [诊断与验收](references/verification.md)，再读取失败链路的协议                            |
@@ -42,22 +31,25 @@ CLI 明确报告 `app_scope_not_applied`、`missing_scopes` 等 scope 权限不
 | 专项验收                 | 确定检查范围 → 执行已授权检查 → 报告证据与未验证项                 | 按契约调用 Database Function 或执行已授权检查                           | [诊断与验收](references/verification.md)                                                  |
 | 发布当前工程或已验证版本 | 检查工程、制品及授权 → 发布 → 必要收尾 → 交付                      | `deploy`；确认后 `deploy --production --yes`              | [发布与交付](references/release.md)                                                       |
 
-表格和 references 的示例默认使用本机 `base-database-cli`；需要回退时只替换命令前缀，保留其余参数。托管环境使用宿主 CLI。完整参数见对应 reference。
+表格和 references 的示例默认使用本机 `base-database-cli`；需要回退时只替换命令前缀，保留其余参数。完整参数见对应 reference。
 
 新建默认创建 Base；用户明确指定已有 Base 时复用，不额外询问数据来源选择题。只有目标资源、数据所有权、权限或核心流程存在实质歧义时才询问。用户提供的工程、技术选择和已明确授权在后续步骤中持续有效。
 
 ## 开发阶段路由
 
-新增或修改 Database Function、Mutation、FaaS 时，按[函数能力描述](references/database-function.md#函数能力描述)维护可供站点助手发现的用途与调用影响。
+新增或修改 Database Function、Mutation、FaaS 时，先按[面向 Agent 的函数与参数设计](references/agent-tool-design.md)写函数说明和参数声明（`name`、`description`、可选 `enum`），使[外部 Agent](#术语) 能选对函数并填对参数；按[外部 Agent 工具策略](references/agent-tools.md)确定需要排除的内部函数。
 
 | 需要完成的工作                                        | 必读协议                                                                                |
 | ----------------------------------------------------- | --------------------------------------------------------------------------------------- |
 | 首次实现页面、整体视觉改版或视觉评审                  | [前端设计指南](references/frontend-design-guide.md)     |
 | 修改布局、颜色、排版或控件样式                        | 上述设计指导的相关章节，沿用现有设计系统；与视觉无关的修改不重读                        |
-| Page runtime、组件接入或 Function 调用                | [Page 开发](references/development.md)                                                  |
+| 本地 dev、Page runtime、组件接入或 Function 调用                | [Page 开发](references/development.md)；执行 dev 前须安装 SDK 且页面入口经 `startBaseApp` 启动，classic 旧工程先按该 reference 接入 SDK |
 | AI 对话、生成、分类、总结、文生图、文生视频或模型调用 | [AI Function](references/ai-function.md)，并结合 [Page 开发](references/development.md) |
 | AI Function 使用本地图片或 Base 附件作为参考图       | 同时读取 [AI Function](references/ai-function.md) 与 [文件传输](references/file-transfer.md)，先得到模型可访问的 URL 或 Data URL，再传入 `input.image` |
 | Database Function 查询、参数和结果解析                              | [Database Function](references/database-function.md)                                              |
+| 函数说明、参数 `name`/`description`/`enum` 声明，或处理 `functionHints` | [面向 Agent 的函数与参数设计](references/agent-tool-design.md) |
+| 通过 `lark-cli api` 发现、读取说明或调用已发布函数 | [调用站点函数](references/agent-tools.md#调用站点函数) |
+| 决定哪些函数不向外部 Agent 开放，或修改 `agent-tools.json` | [外部 Agent 工具策略](references/agent-tools.md) |
 | 日期表单、到期日、事件时间或时间筛选                  | [日期与时区](references/development.md#日期与时区)                                      |
 | 判断查询支持集之外的形态或处理兼容错误               | [查询能力边界](references/database-function-limitations.md)                                      |
 | FaaS 引用自定义环境变量，或用户要求查询、配置环境变量或第三方凭证            | [第三方 Agent 环境变量](references/environment-variables.md)                           |
@@ -71,33 +63,16 @@ CLI 明确报告 `app_scope_not_applied`、`missing_scopes` 等 scope 权限不
 
 新建或整体改版先在内部规划中确定视觉方案，再实现设计变量和组件。业务建模与通用工程取舍按[工程质量](references/style-guide.md)执行；默认不创建额外设计文件。新建站点或修改业务能力时，按[站点 README](references/release.md#站点-readme)维护随源码制品上传的项目说明；用户要求其他文档时按要求交付。
 
-AI 能力路由统一使用版本化托管的 AI Function。Page 从 `database-runtime` 导入 `callSiteAIFunction` 或 `invokeSiteAIFunctionStream`，并按 [AI Function](references/ai-function.md) 的能力类型选择聚合、流式或媒体任务调用。
-
-需要模型参与当前页面业务流程时，AI Function 是默认选择。例如点餐系统根据口味、预算、用餐人数和菜单生成点餐推荐，应建模为 AI Function，不创建 FaaS 模型代理。
-
-**AI Function 是按需可选能力，不是建站或发布的前置条件。** 用户需求未涉及 AI 对话、生成、分类、总结、文生图或文生视频时，不创建 `ai/` 目录、不调用任何 `ai-functions` 命令，也不要求或提示用户开通 AI 能力；普通 `deploy` 在空 `ai/` 时自动跳过 AI Function 同步，Page/Database Function/FaaS 照常发布，不因此阻塞。
-
-远端 AI Function 的恢复与保护由 CLI 完成，不需要 Agent 判断：`pull` 会把远端 AI Function 草稿写回 `ai/`（当前账号未开通时不落 `ai/`）；`deploy` 时空 `ai/` 会跳过 AI Function 同步（`no_local_ai_functions`），本地全集非空时先核对远端已有 key 都在本地，缺任何一个就拒绝发布而不是静默删除，通过后按全量覆盖写入草稿；需要让本次 deploy 完全跳过 AI Function 同步时使用显式参数 `deploy --skip-ai-functions`，并按[诊断与验收](references/verification.md)在报告中说明 AI Function 未同步、未验证。`ai-functions sync` 不管本地是否为空都立即全量覆盖，因此显式 `sync` 空集合会把远端 AI Function 全部删除。创建、配置、调用、调试 AI Function 的完整流程见 [AI Function](references/ai-function.md)。
-
-### 增量绑定新 Table
-
-修改已有应用时需要使用当前已绑定 Base 中的新 Table，不重新执行 `init` 或 `pull`。先用 `lark-cli base +table-list/get` 的真实返回取得 Table ID，再在项目根目录执行：
-
-```bash
-base-database-cli lark-cli -- api POST /open-apis/base/v3/sites/Prjxxxxxxxx/bind_base --data '{"baseToken":"basxxxxxxxx","tableIds":["tbl_new"]}' --json
-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 接口并先取得用户授权。
+恢复已有 AI Function 时先读[恢复协议](references/ai-function.md#恢复已有-ai-function)，配置与调用按[AI Function](references/ai-function.md)执行。AI 与其他函数的发布顺序、skip 行为、显式 sync 的删除边界及失败恢复统一见[发布参考](references/release.md#function-发布顺序与错误边界)。
 
 ## 关键约束
 
-1. 应用资源与发布优先使用本机 `base-database-cli`；原生 Base 配置使用 `lark-cli base +...`。托管环境使用宿主提供的 CLI，不切换环境。命令选择与工程恢复见[工程与环境](references/workspace.md)。
+1. 应用资源与发布优先使用本机 `base-database-cli`；原生 Base 配置使用 `lark-cli base +...`。命令选择与工程恢复见[工程与环境](references/workspace.md)。
 2. Base 是业务数据事实源，`catalog.json` 是已绑定表的 schema 事实源。表、字段、ID、类型、选项和关系来自真实结果，不由名称或建模输入猜测。
-3. **权限边界**：应用以 owner 身份访问 Base。访问者通过已发布 Function 使用业务能力；浏览器直接记录 CRUD 已关闭，固定写入由 Mutation 声明约束。FaaS ticket 内部记录回调保留兼容，需单独约束其输入。读取身份通过 Database Function 中的 `CURRENT_USER_ID()` 获取，Mutation 使用服务端 `current_user`。自定义角色和统一行列权限尚未接入。绑定与权限设计必须遵守[权限边界](references/permission-design.md)。
-4. Page 读取走 Database Function；普通单表创建、按记录 ID 更新和删除（含批量及附件写入）优先使用 Mutation；需要声明之外的服务端业务校验、计算或编排时使用 FaaS，边界见[写入方式选择](references/mutations.md#写入方式选择)。Database Function 必须引用至少一个已绑定 Catalog 真实表；纯常量与无表依赖计算按[SQL 外实现放在哪](#sql-外实现放在哪)选择位置。输入只能进入声明的业务参数，不能决定查询语句、URL、method、Base token、table ID、字段名、Function ID 或凭证。
+3. **权限边界**：应用以 owner 身份访问 Base。访问者通过已发布 Function 使用业务能力；浏览器直接记录 CRUD 已关闭，固定写入由 Mutation 声明约束。FaaS 通过[固定记录写入路由](references/faas.md#应用记录写入协议)写入，不受 Mutation 声明约束，须在 FaaS 内校验输入与调用者身份。读取身份通过 Database Function 中的 `CURRENT_USER_ID()` 获取，Mutation 使用服务端 `current_user`。自定义角色和统一行列权限尚未接入。绑定与权限设计必须遵守[权限边界](references/permission-design.md)。
+4. Page 读取走 Database Function；普通单表创建、按记录 ID 更新和删除（含批量及附件写入）优先使用 Mutation；需要声明之外的服务端业务校验、计算或编排时使用 FaaS，边界见[写入方式选择](references/mutations.md#写入方式选择)。Database Function 必须引用至少一个已绑定 Catalog 真实表；纯常量与无表依赖计算按[SQL 外实现放在哪](references/database-function-limitations.md#sql-外实现放在哪)选择位置。SQL 无法表达的计算，不得把查看者无权看到的明细发给 Page 处理，拿不准时放 FaaS。输入只能进入声明的业务参数，不能决定查询语句、URL、method、Base token、table ID、字段名、Function ID 或凭证。
 5. Database Function、Mutation 与 FaaS 的参数、返回值不同。Page 使用 `invokeDatabaseFunction<TData>`，`TData` 只描述顶层 `data`，不二次解包；协议见[Page 开发](references/development.md#function-调用契约)。部分成功与重试按 [Mutation 结果](references/mutations.md#调用与结果)或 [FaaS 记录协议](references/faas.md#应用记录写入协议)处理。
-6. AI 对话、生成、分类、总结、文生图或文生视频使用 Page 侧 AI Function 调用平台 AI 能力，不创建 FaaS 模型代理，不直连模型域名；需求不涉及 AI 时不创建 AI Function、不调用 AI 接口，也不把 AI Function 开通作为前置条件。完整契约见[AI Function](references/ai-function.md)。
+6. AI 对话、生成、分类、总结、文生图或文生视频，使用 Page 侧 AI Function，不建 FaaS 模型代理、不直连模型域名。AI 是按需能力：需求不涉及时不创建 `ai/`、不调用 `ai-functions` 命令，也不提示用户开通。详见 [AI Function](references/ai-function.md)。
 7. 修改保留需求外源码、Base schema、metadata、bindings 和 Function。Functions 更新为全量覆盖，不能以只提交本次新增 Function 的方式更新已有应用。
 8. 保留 starter 的 ready 上报及宿主组件接入。附件能力取决于目标环境的父页面、所选写入方式和服务端协议；按[文件传输](references/file-transfer.md)实现，不以模拟成功代替真实能力。
 9. 第三方 npm 依赖必须使用目标应用的服务端依赖策略判断；普通 registry 版本默认可用，受限来源只有被 `allowedValues` 中某条正则完整匹配时可用。详见[第三方依赖策略](references/development.md#第三方依赖策略)。
@@ -123,21 +98,12 @@ workflow 启停及失败补偿按[通知集成](references/notifications.md#状
 - **部分完成**：已有成果可交付，但存在已知功能缺失、违反需求的实现、平台不支持的要求，或约定验证、外部配置未完成；即使 Preview 发布成功，也逐项列出缺口。
 - **阻塞**：必需步骤受认证、权限、平台能力或缺失输入等外部条件限制，记录阻塞及恢复条件。
 
-默认交付访问链接、业务变更、体验步骤、实际验证结果和影响使用的限制。仅使用发布命令返回的顶层 `baseAppUrl` 作为应用访问入口；不猜测地址或展示内部静态资源 `staticUrl`。技术清单与诊断信息按研发、排障或审计需要提供；不输出凭证，也不要求普通业务用户检查协议字段。
+默认按[交付结果](references/release.md#交付结果)提供访问链接、业务变更、体验步骤、实际验证结果和影响使用的限制；有开放函数时一并介绍本地 Agent 业务用法与站点 Skill 安装方式。仅使用发布命令返回的顶层 `baseAppUrl` 作为应用访问入口；不猜测地址或展示内部静态资源 `staticUrl`。技术清单与诊断信息按研发、排障或审计需要提供；不输出凭证，也不要求普通业务用户检查协议字段。
 
 ## 术语
 
 - **Database Function**：通过固定查询语句读取 Base 数据的函数；查询定义位于 `database-functions/<functionId>/main.sql`。
-- **应用 appToken**：应用标识；协议字段 `appToken`、FaaS 的 `projectId` 与示例中的工程常量 `PROJECT_ID` 在相应入口指向该应用，不是 Base token。`PROJECT_ID` 由示例调用方定义，不是 starter 提供的标识。
+- **应用 appToken**：应用标识；协议字段 `appToken`、FaaS 的 `projectId` 与示例中的工程常量 `PROJECT_ID` 在相应入口指向该应用，不是 Base token。`PROJECT_ID` 由示例调用方定义，不是 starter 提供的标识。服务端路径 `/sites/<app-token>`、SDK 的 `siteToken` 都指同一个应用 token，原样使用，不改写外部协议。
 - **Catalog**：已绑定数据表的 schema；本地快照为 `catalog.json`，更新从应用 catalog 接口获取。Base 的业务记录不保存在 Catalog。
 - **operation**：业务动作及其固定输入输出契约，例如查询任务或审批申请；不是任意 URL 或查询语句的代理。
-- **托管环境**：平台提供 CLI、登录态或工程的建站环境；使用其已提供的入口。自行安装 CLI 的本地环境按公开安装流程执行。
-
-
-## SQL 外实现放在哪
-
-原则：SQL 无法等价表达时，在消费查询结果的代码中完成计算；选择位置首先看数据可见性，再看规模与复用需求。
-
-判定：只有计算仅影响查看者本就有权看到的行的展示、结果集小且无需跨页面复用时，才适合放在 Page。若计算需要查看者不应看到的明细、数据量大、需要跨页面复用或写回，则放在 FaaS（SQL 报错中的 “Edge Function” 即指 FaaS），并沿用既有身份、权限和参数边界；FaaS 仍需在服务端校验调用者权限，只返回允许公开的结果。不能先把无权查看的明细发给浏览器，再靠 Page 过滤或隐藏。
-
-默认：拿不准时选 FaaS。把应在服务端处理的计算放到 Page，可能泄露数据；多一道服务端调用通常更容易纠正。SQL 报错中的“SQL 外实现”不等于一律新建 FaaS，也不构成绕过现有权限模型的授权。
+- **外部 Agent**：不经过页面、通过 `lark-cli api` 发现并调用本站点已发布函数的 Agent，例如站点成员在对话或本地 Agent 中使用的助手。它看不到页面源码，只依据函数的 `name`、`description` 和服务端生成的参数说明判断何时调用、如何传参。

package/skills/lark-base-database/references/agent-tool-design.md

@@ -0,0 +1,181 @@
+# 面向 Agent 的函数与参数设计
+
+写或修改 Database Function、Mutation、FaaS 的函数说明和参数声明前读取本文；`check` 或 `deploy` 返回 `functionHints` 时回到本文自查。执行、权限与返回协议仍以 [Database Function](database-function.md)、[Mutation](mutations.md)、[FaaS](faas.md) 为准。
+
+[外部 Agent](../SKILL.md#术语) 看不到页面源码，只根据函数 `name`、`description` 和服务端按参数声明生成的 `inputSchema`、`parameters[]` 选择函数并填写参数。目标是调用者一次选对函数、一次填对参数。
+
+## 原则、判定与默认路径
+
+| 原则 | 判定 | 默认路径 | 例外 |
+| --- | --- | --- | --- |
+| 函数可区分 | 调用者能否在相邻函数间选对 | 函数 `description` 写用途、何时用、何时不用及改用哪个相邻函数 | 没有易混淆的相邻函数时写明适用边界，不列无关函数 |
+| 说明业务含义与来源 | 只看声明能否填出值 | `name` 稳定可读；`description` 写对象、单位、取值步骤与空值效果 | 不知道值从哪里来时请用户或作者补充，不猜函数 |
+| 固定选项结构化 | 选项是否由作者限定且固定 | 写标准 `enum`，Page 复用 CLI 生成的类型和选项常量 | 动态值用只读字典或查询函数取得，在 `description` 说明调用步骤；`DISTINCT` 只含已使用值，不代表全部选项 |
+| ID 与显示名分开 | 参数接受记录 ID 还是名称 | `description` 写先调哪个已开放函数、取哪个返回字段 | 同名多条时让用户选择，不用标题代替 ID |
+| 条件约束可判定 | 必填是否依赖另一个参数 | FaaS 用 `oneOf` 分支表达条件必填，每个顶层属性都有 `description` | 分支表达不清时拆成多个函数；跨字段业务关系（如日期先后）留给 handler 校验 |
+| 空值效果明确 | 缺失、`null`、空串是否同义 | 按真实执行语义说明；Mutation 可选参数缺失或 `null` 表示跳过写入 | 清空使用声明中明确的 `clear`，不把 `null` 写成清空 |
+| 错误可修复 | 调用者能否定位参数并判断是否已执行 | 未执行的错误返回非 0 码和按模板写的 `msg` | 已完成或已受理时遵循[结果与错误](#结果与错误) |
+
+## 平台检查与提示
+
+`check` 和 Preview `deploy` 在本地拒绝：SQL `meta.params[]`、Mutation `spec.params[]` 缺少 `name` 或 `description`、`name` 重复或不符合 `^[A-Za-z][A-Za-z0-9_]{0,63}$`；`enum` 为空、重复、含 `null` 或类型与参数 `kind` 不一致；FaaS `inputSchema` 顶层不是 `object`，或某个顶层属性缺少 `description`。保存到服务端时，有可证明的绑定域才会用当前 Catalog 检查 `enum` 是否在字段的选项范围内。
+
+函数级 `description` 缺失、为空白或去除首尾空白后少于 8 个字符只是提示；参数描述仍必须非空，少于 8 个字符只是提示，不阻断发布；平台不比较 `description` 与 `name`，也不判断自然语言质量。参数绑定关联记录或选项字段时，服务端在 `deploy` 结果的 `functionHints` 中提示补充取值方式。提示消失不代表语义正确，仍按下文自检。
+
+`enum_unchecked` 表示本次分析未取得足够的 Catalog 域证据，不表示声明的选项错误。例如 `$1 IS NULL OR 字段.name = $1` 的可选筛选会保守地不给域证明。默认核对真实字段选项、参数绑定与业务语义，保留正确的 `enum` 和查询；确有不一致时修正声明，不以消除提示为由改掉筛选或空值语义。
+
+服务端从参数声明生成命名对象 `inputSchema`；未声明 `enum` 的选项参数在有绑定证据时获得选项摘要前缀，记录 ID 参数的说明使用作者原文。作者写明业务含义和取值步骤，不手写 SQL 或 Mutation 的 Schema。
+
+## 函数说明：何时用、何时不用
+
+函数级 `description` 写四件事：用途、何时用、何时不用、此时改用哪个相邻函数。相邻函数指同站点中参数或用途相近、容易被误选的函数。
+
+反例：两个函数都只写“查询休假”，调用者无法区分。
+
+```json
+{"name":"listLeaveByIntent","description":"查询休假"}
+```
+
+正例：
+
+```json
+{"name":"listLeaveByIntent","description":"按休假意向筛选全部填报。用于“谁需要休假”这类按意向的问题；要看某个报备周期的全部填报时不用本函数，改用 listTeamLeave（只读）"}
+```
+
+## 示例
+
+示例 ID 为占位值，实际使用时以 Catalog 和真实查询结果替换。
+
+### 记录 ID 与分页（Database Function）
+
+反例：只有类型，调用者会猜标题、`null` 或分页单位。
+
+```json
+{"name":"listTeamLeave","description":"查看团队休假填报","meta":{"params":[{"name":"periodId","kind":"TEXT","description":"周期"},{"name":"offset","kind":"INT","description":"偏移"}]}}
+```
+
+正例：`meta.params` 的声明顺序对应 `$1`、`$2`。
+
+```json
+{"name":"listTeamLeave","description":"查看指定报备周期的团队休假填报；按意向筛选时改用 listLeaveByIntent（只读）","meta":{"params":[{"name":"periodId","kind":"TEXT","description":"报备周期记录ID；先调用 listPeriods，从返回 rows[].period_id 选择，不传周期标题；null 不表示全部"},{"name":"offset","kind":"INT","description":"跳过的记录数，第一页传 0，每页固定 200 条，下一页递增 200"}]}}
+```
+
+外部 Agent 的调用请求体：
+
+```json
+{"params":{"periodId":"recExample123","offset":0}}
+```
+
+### 固定选项写 enum
+
+`deploy` 结果的 `functionHints` 出现“绑定选项字段”（`bound to option field`）提示时，判断选项是否由作者限定且固定：固定则依据提示核实选项并写入 `enum`，再重新 `deploy`；会变化则不写 `enum`，在 `description` 写清获取有效值的步骤。提示标记 `truncated` 或域不完整时，先取得并核实作者所需的完整选项，不能把提示中的样本当作全部选项。
+
+反例：自然语言名单不能提供机器约束。
+
+```json
+{"name":"intentName","kind":"TEXT","description":"休假意向，只能是不休假或需要休假"}
+```
+
+正例：`enum` 必须在绑定字段的选项范围内，服务端照抄进 `inputSchema`；CLI 同时生成 Page 可引用的 `DatabaseFunctionParameterOptions` 常量。数组参数（`TEXT[]` 或 Mutation `list: true`）的 `enum` 约束每个元素。
+
+```json
+{"name":"intentName","kind":"TEXT","enum":["不休假","需要休假"],"description":"本次报备的休假意向，按用户明确选择填写"}
+```
+
+workspace 运行 `contracts generate`（声明变化后再生成）与 `check` 后，在 Page 的 src 目录直接引用生成文件，不另写一份选项：
+
+<!-- example: workspace-agent-inputs -->
+```ts
+import { invokeDatabaseFunction } from '@lark-base-open/base-database-app-sdk/page';
+import { DatabaseFunctionParameterOptions } from './generated/function-inputs';
+
+const intentOptions = DatabaseFunctionParameterOptions.listLeaveByIntent.intentName;
+type IntentName = (typeof intentOptions)[number];
+export const loadByIntent = (intentName: IntentName) =>
+  invokeDatabaseFunction('listLeaveByIntent', { intentName });
+```
+
+示例中的函数 ID 和参数名必须与本地声明一致。SQL 和 FaaS 的输入类型同时进入生成的 `DatabaseFunctionInputMap`；Mutation 可从同源选项常量取字面量联合类型，workspace 使用命名对象调用。classic 示例分支和参数形态统一按[Function 调用契约](development.md#function-调用契约)判定。
+
+### 属性说明与条件必填（FaaS）
+
+反例：属性没有说明，所有字段可选，无法区分创建与关闭。
+
+```json
+{"type":"object","properties":{"action":{"type":"string"},"title":{"type":"string"},"start":{"type":"string"},"periodId":{"type":"string"}},"additionalProperties":false}
+```
+
+正例：`oneOf` 的两个分支分别声明 create 与 close 的必填项；日期先后和最长天数由 handler 校验，`pattern` 只约束格式，不能证明日期有效。
+
+```json
+{
+  "type": "object",
+  "description": "创建报备周期或关闭已有周期",
+  "properties": {
+    "action": {"type": "string", "enum": ["create", "close"], "description": "create 创建周期；close 关闭指定周期的填报"},
+    "title": {"type": "string", "minLength": 1, "description": "create 时必填，报备周期的业务名称"},
+    "start": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "create 时必填，开始日期 YYYY-MM-DD，按站点时区解释"},
+    "end": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "create 时必填，结束日期不早于开始日期，单期最多 180 天"},
+    "periodId": {"type": "string", "description": "close 时必填；先调用 listPeriods，从 rows[].period_id 选择记录 ID"}
+  },
+  "required": ["action"],
+  "additionalProperties": false,
+  "oneOf": [
+    {"type": "object", "properties": {"action": {"type": "string", "enum": ["create"]}}, "required": ["title", "start", "end"]},
+    {"type": "object", "properties": {"action": {"type": "string", "enum": ["close"]}}, "required": ["periodId"]}
+  ]
+}
+```
+
+### 可选参数跳过写入（Mutation）
+
+反例：把 Mutation 参数的 `null` 写成清空。
+
+```json
+{"name":"remark","kind":"TEXT","required":false,"description":"填报备注，null 清空备注"}
+```
+
+正例：其余表、`set` 和 `precondition` 按 [Mutation](mutations.md) 声明。
+
+```json
+{"name":"remark","kind":"TEXT","required":false,"description":"填报备注；缺失或 null 跳过写入并保留原值；清空需使用作者提供的 clear 操作"}
+```
+
+```json
+{"params":{"recordId":"recExample123","remark":null}}
+```
+
+FaaS 底层记录接口的 `null` 清空语义不适用于 Mutation 参数。写入成功后仍检查 `record_not_found` 和 `ignored_fields`。
+
+## 结果与错误
+
+已写入部分记录或已受理任务时返回 `code=0`，在 data 中保留已完成 ID/任务 ID、状态、未完成步骤及恢复提示；code=0 不代表全部完成。确定未执行或全部失败时可返回非零业务码；结果未知时也可用非零码，但 msg 必须明确结果未知和先核对，不能声称未执行。未知结果先有限回读，不盲目重试。具体 FaaS 消费正例见[页面消费部分完成结果](faas.md#页面消费部分完成结果)。
+
+### FaaS 错误 msg
+
+平台错误默认使用固定英文段标签，无 locale 切换。作者业务错误正文不由平台翻译，可沿用业务语言；为方便 Agent 处理，建议使用下列英文段标签。参数、选项、权限或前置条件不满足而未执行时，返回非 0 `code`。外部 Agent 通过 `lark-cli api` 调用时只看到 `msg`，看不到 `data`。
+
+```text
+<Reason>. Parameter: <JSON Pointer> (received <redacted value>). Fix: <correction>; Candidates: <up to 3 values>. Executed: no. Retry: retry after fixing.
+```
+
+```json
+{"code":40001,"msg":"结束日期早于开始日期. Parameter: /params/end (received \"2027-01-10\"). Fix: 结束日期不早于 2027-02-20，单期最多 180 天. Executed: no. Retry: retry after fixing."}
+```
+
+- `msg` 原样到达调用方，整条不超过 500 字；只回显调用方本次传入的值（不超过 64 字），不写查询语句、堆栈或内部错误原文。
+- 作者可用任意非 0 业务码区分错误。外部调用入口的顶层码固定为平台的函数业务错误码，作者码放在 `data.error.upstream_code`；平台在 `msg` 末尾追加 `Business code:` 与 `LogID:`，作者不写 LogID。
+- 返回 500 或抛出未捕获异常时，调用方只看到固定的安全文案和 LogID。
+- 能用 `inputSchema` 表达的约束交给平台校验，handler 只写跨字段业务规则。
+
+## 写完自检
+
+1. 函数 `description` 写清用途、何时用、何时不用及改用哪个相邻函数。
+2. 每个参数（FaaS 为每个顶层属性）都有稳定的 `name` 和非空白 `description`。
+3. `description` 写清业务含义、单位与来源；收到过短提示后补充实质内容，不为凑长度写重复文字。
+4. 关联 ID 写明来源函数与返回字段；分页写明起点、步长与停止条件。
+5. 固定选项用 `enum` 且位于真实绑定字段的选项范围；动态取值写进 `description`，不以样本冒充全部选项。
+6. 条件必填用 `oneOf` 分支或拆分函数表达，跨字段业务规则由 handler 校验。
+7. 缺失、`null`、空串、空数组的效果写准确，Mutation 的跳过与 `clear` 分开。
+8. 未执行的错误按 msg 模板写清参数、修正与重试；部分写入或结果未知不让调用方自动重发。
+9. `check`/`deploy` 的错误先修复，`functionHints` 逐条按本文核对。

package/skills/lark-base-database/references/agent-tools.md

@@ -0,0 +1,101 @@
+# 外部 Agent 工具
+
+## 使用场景
+
+站点成员不打开页面，而是在飞书对话或自己的本地 Agent 中用自然语言，让 Agent 查询或操作站点数据。这类[外部 Agent](../SKILL.md#术语)默认可以使用本站点的全部 Database Function、Mutation、FaaS 和 AI Function；工程根目录可选的 `agent-tools.json` 声明其中哪些不向外部 Agent 开放。AI Function 的 key 也可写入 exclude。文件缺席或 `exclude` 为空时全部开放。
+
+## 判定
+
+原则：外部 Agent 替站点成员直接完成业务，开放的是能独立完成一件业务的函数。
+
+判定：函数只在页面流程或 FaaS 内部作为一个步骤使用，单独调用没有业务意义或会产生误导，例如提交前的校验、开发排查用的诊断查询，写入 `exclude`；成员能理解并直接使用的查询和写入保持开放。
+
+默认：拿不准时保持开放。误排除会让外部 Agent 缺少完成业务所需的能力；函数返回的数据是否允许成员看到，由权限设计决定，不由是否排除决定。
+
+例如任务管理站点：
+
+| 函数 | 用途 | 策略 |
+| --- | --- | --- |
+| `database-functions/listTasks` | 成员查看任务列表 | 开放 |
+| `mutations/createTask` | 成员新建任务 | 开放 |
+| `database-functions/checkTaskQuota` | 页面提交前校验成员的任务额度 | 排除 |
+| `database-functions/debugTaskStats` | 开发排查统计口径的诊断查询 | 排除 |
+
+```json
+{ "exclude": ["checkTaskQuota", "debugTaskStats"] }
+```
+
+`exclude` 中写函数目录名（functionId），必须是本工程已有的函数，且不能重复。`check` 与 `deploy` 使用同一校验函数和本地全部 Database Function、Mutation、FaaS、AI Function ID 集合，不因本次跳过 AI 同步而改变；不存在的 ID 均报 `AGENT_TOOLS_INVALID` 并列出合法 ID。当前声明仅支持 `exclude`，不支持 `include`。
+
+执行 `base-database-cli check` 校验声明，在 `agentTools.tools` 与 `agentTools.exclude` 中核对本地计划。准备跳过 AI 同步时，先执行 `base-database-cli check --skip-ai-functions`，再执行 `base-database-cli deploy --skip-ai-functions`：本地 AI ID 仍合法，但本次本地计划不包含这些 AI 的排除项，也不将其列入本地开放清单；两条命令均提示“AI Function 本次未同步，相关 agent-tools 配置未生效”。本地文件保留原声明，后续正常同步 AI 时排除项重新生效。跳过 AI 不解析其配置内容。
+
+远端已有 AI 仍按既有保留规则处理：策略接口整体替换 exclude，为避免意外重新开放函数，部署会查询远端 AI 清单，并继续提交其中已有 AI 的本地排除项；只有远端尚不存在的 AI 排除项被省略。该查询失败时继续沿用停止部署的规则，不猜测远端状态。本地计划不代表已发布开放清单。正式版开放能力以站点 Skill 中的函数清单为准；Prod 继续提升 Preview 快照，不重新读取本地策略。
+
+业务能力说明与安装引导统一按[交付结果](release.md#交付结果)。
+
+**exclude 不是权限控制**：Agent OpenAPI 默认对所有人隐藏并拒绝被排除的函数，不限制页面入口、旧入口与 FaaS 回调；站点管理者仅在显式携带 `includeInternal=true` 时可通过 OpenAPI 调试。敏感数据和业务访问控制按[权限设计](permission-design.md)在执行侧落实，不能靠排除隐藏。
+
+## 发布
+
+声明随 `site.zip` 保存，`pull` 恢复，并计入 Preview 制品的输入指纹；修改后须重新发布 Preview，再按原有流程确认 Prod。Preview 部署在更新函数后写入草稿开放策略，随后上传制品；Prod 提升已校验的 Preview 制品，不读取本地声明。
+
+策略写入失败会停止部署。旧服务端明确不支持该接口时，文件缺席且没有 exclude 的工程可继续部署并保留远端原策略；存在文件时需升级服务端或移除文件。
+
+策略写入与源码上传不是原子操作。中途失败时，草稿策略与远端源码包可能暂不一致；保留本地工程并核对失败阶段，不盲目重试结果未知的写入。此时从旧源码包 `pull` 后直接部署，可能把排除清单恢复为空，应先恢复预期声明再重新部署。
+
+## 调用站点函数
+
+外部 Agent 与验收时的命令行调用都使用原生 `lark-cli api`，不使用 `+site-func-*` 等 shortcut；本地工程内用 `base-database-cli lark-cli -- api` 加相同路径，沿用工程 profile。`env` 默认 `prod`；`preview` 的准入与 Page/OpenAPI 差异见[权限边界](permission-design.md#preview-与-prod-准入)。
+
+| 步骤 | 命令 | 读取 |
+| --- | --- | --- |
+| 发现 | `lark-cli api GET /open-apis/base/v3/sites/<app-token>/functions --params '{"env":"prod"}' --as user` | `functions[]` 的 `name`、`description`、`functionType`、`schemaStatus`、`statusHint`；`hasMore` 为 true 时带 `pageToken` 继续 |
+| 说明 | `lark-cli api GET /open-apis/base/v3/sites/<app-token>/functions/<function-id> --params '{"env":"prod"}' --as user` | `data.function` 的 `inputSchema`、`parameters[]`、`requestExample`、`replacePaths`、`callCommand`；Mutation 还读取 `outputSchema` 了解返回字段名称和类型 |
+| 调用 | 按 `callCommand`：`lark-cli api POST /open-apis/base/v3/sites/<app-token>/functions/<function-id>/invoke --params '{"env":"prod"}' --data @body.json --as user` | 顶层业务码与 `data` |
+
+原则：参数以服务端实时返回的说明为准，Skill、函数索引和历史会话不保存参数 Schema。仅站点管理者做开发期验证时可在列表、说明和调用的 `--params` 中显式加 `"includeInternal":true` 访问页面专用内部函数；外部 Agent 默认不带。
+
+判定与默认路径：
+
+- 调用前读取该函数的最新说明，按 `inputSchema` 构造 `{"params":{…}}`，参数按 `name` 传对象，不按位置传数组。`requestExample` 中 `replacePaths` 指向的值是占位，替换为真实值后再调用，不把示例 ID 当成真实记录。
+- `parameters[]` 中的 `reference` 表示参数是某张表的记录 ID，`valueHint` 是作者写的取值步骤，`optionSummary` 是有界的选项提示而非完整选项集合；取值按作者说明先调用相应只读函数，不从字段名或表名猜测调用顺序。
+- 写入类函数每次调用前重新读取说明；同一身份、站点、环境和版本下紧邻的只读调用可复用刚读到的说明，调用失败或说明变化后重新读取。
+
+`schemaStatus` 不是 `ready` 时：
+
+| 状态 | 处理 |
+| --- | --- |
+| `missing` | FaaS 未声明输入 Schema；按函数 `description` 判断，无法确定参数时停止并说明 |
+| `needs_upgrade` | 函数仍使用旧的位置参数声明，没有可用的参数说明；不猜值、不调用，告知用户需由函数作者升级 CLI、补齐参数 `name`/`description` 后重新发布，调用方升级或重试无效 |
+| `unavailable` | 函数依赖的字段或固定选项已变化，或在当前表结构下无法通过校验；按 `statusHint` 告知需作者修复后重新发布，不重试 |
+
+错误处理：
+
+- 业务码非 0 时 lark-cli 只输出 stderr 的错误信封，不输出 `data`。平台生成的 `error.message` 默认英文：开头为原因，`Parameter:` 给出相对请求体的 JSON Pointer（如 `/params/periodId`）和 `(received ...)`，`Fix:` 给出修正方式，`Candidates:` 最多 3 个候选，`Executed: no` 表示未执行，`Retry:` 给出重试条件，`LogID:` 位于末尾。按 `Fix:` 和 `Retry:` 处理；重试值为 `retry after fixing`、`do not retry`、`retry later`、`retry after publishing` 或 `retry after access is granted`，不表示自动重试。作者 name/description、收到值和 FaaS 业务错误正文保持原语言；FaaS 业务错误末尾由平台追加 `Business code:` 与 `LogID:`。
+- `code=9499`（Bad Request）通常是请求本身不合法：核对 `--params` 与 `--data` 是否为合法 JSON、参数值类型是否与 `inputSchema` 一致（数字不写成字符串、对象不写成 JSON 字符串）。
+- `code=0` 不等于全部完成：Mutation 检查 `record_not_found` 和 `ignored_fields`，任务查询检查 `data.status` 是否为 `failed`/`cancelled` 及 `errCode`/`errMessage`。
+- 写入或 AI 任务失败、超时或结果未知时不自动重发；先用只读函数核对实际结果，再决定是否需要用户确认后重试。权限不足不换路径绕过。
+
+## 安装到本地 Agent
+
+站点 Skill 提供这个已发布站点的业务函数发现与调用说明，供外部 Agent 使用。`agent-tools skill install` 安装它；`skill install` 安装用于开发和发布应用的通用 `lark-base-database` Skill，两者用途不同。
+
+Prod 交付回复中的业务能力说明与完整 handoff 按[交付结果](release.md#交付结果)提供；本节说明安装方式。
+
+判定：`installation.available` 表示正式版 Skill 当前可获取；Preview 或读取失败时为 false。安装接口固定取 `prod`，不支持安装 Preview，也不授予 Prod 发布或调用权限。
+
+默认路径：开发者使用 `nextAction.externalAgent.installation.command`；未取得该字段时，在包含 `base-database.jsonc` 的工程目录执行：
+
+```bash
+base-database-cli agent-tools skill install
+```
+
+Prod 成员安装命令由 CLI 交付块生成。完整交付条件与回复写法见[交付结果](release.md#交付结果)；不要自行拼装或改写成员消息。
+
+成员无需打开工程目录，可在任意目录执行 `base-database-cli agent-tools skill install --site <站点链接或 token>`。命令使用当前 lark-cli 用户登录态，返回的站点能力仍按该成员自己的访问权限决定。成员安装摘要存放在用户级 CLI 状态目录，不写入站点工程；摘要用于识别同名 Skill 的站点来源，不参与工程 Preview 过期判断。仅有 Preview 的站点不能用此命令安装。
+
+成员使用 `--site` 安装时，若目标目录中已有另一个站点的同名 Skill，安装器会按站点 token 哈希加短后缀并提示新名称；同一站点重装会覆盖其已记录的安装。未被 CLI 摘要识别的同名目录仍按普通已存在目录处理，用户可先核对目标再显式使用 `--force`。
+
+默认安装到 Codex；`--target codex|agents|claude|all` 与 `--dir <path>` 的目标目录语义同 `skill install`，`--dir` 指定 skills 根目录。站点更新后，成员重复执行 `--site` 安装命令即可更新同一站点已记录的安装；未被摘要识别的目录仍需核对目标，并在用户授权下使用 `--force`。工程安装（不带 `--site`）如目标目录已存在，无论是否保存过摘要，都须先核对目标，并在用户授权下加 `--force` 重新安装。
+
+安装成功后，先用 `skillCommand` 读取站点 Skill 的函数清单，再按[调用站点函数](#调用站点函数)让本地 Agent 读取一个真实只读函数的说明并实际调用一次，核对业务结果作为自检；无可用只读函数则说明自检未完成，不用写入或 AI 函数代替。本地文件写入、客户端发现、远端调用分别报告实际验证结果。