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

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

@@ -1,8 +1,8 @@
 ---
 name: lark-base-database
-description: 使用飞书多维表格作为业务数据后端，创建、修改、恢复、发布、验收或排查 Base Database 业务系统。适用于 Base Database 的 Page、SQL Function、FaaS 和原生 Base 集成；仅操作多维表格资源时使用 lark-base。
+description: 使用飞书多维表格作为业务数据后端，创建、修改、恢复、发布、验收或排查 Base Database 业务系统。适用于 Base Database 的 Page、Database Function、Mutation、FaaS 和原生 Base 集成；仅操作多维表格资源时使用 lark-base。
 metadata:
-  compatibility: 需要 Node.js 20.19+、npm/npx、lark-cli 及目标平台访问权限；托管环境使用宿主提供的 CLI。
+  compatibility: 需要 Node.js 20.19+、npm/npx、lark-cli 及目标平台访问权限；优先使用本机安装的 Base Database CLI，托管环境使用宿主提供的 CLI。
 ---
 
 # Lark Base Database
@@ -12,69 +12,85 @@ metadata:
 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#环境与依赖)处理。
 
-### 公开 CLI 版本预检
-
-本节的全局安装特指 `npm root -g` 对应的 CLI 包目录；不能仅凭 PATH 中存在同名命令就认定满足更新条件。
+### Base Database 权限不足时重新授权
 
-仅本地公开 CLI：每个会话首次业务操作前，先确认本次使用的 CLI 入口及其 `--help`。已有全局安装时用已核实的全局入口执行 `check-update --json --skill-dir "<当前读取的 lark-base-database 目录>"`；仅通过 npx 使用时沿用已选版本的完整包名入口。使用实际 Skill 加载路径，不猜测默认 Agent 目录。
+CLI 明确报告 `app_scope_not_applied`、`missing_scopes` 等 scope 权限不足错误时，向用户说明原因，并使用本任务已选定的 CLI 入口和同一 profile 执行 `base-database-cli auth login`，申请构建应用所需的权限。若错误另有应用权限开通或额外 scope 的处理要求，按错误提示处理。用户完成授权后只重试原命令一次；仍失败时停止并保留原错误，不循环授权。其他错误按其原因处理。
 
-仅托管 Builder（设置了 `BASE_SITE_BUILDER_WORKSPACE_SOURCE` 或 `BASE_SITE_BUILDER_SITE_TOKEN`）及 CI 跳过更新检查；其他环境正常检查。检查失败不阻塞任务。
+### 公开 CLI 版本预检
 
-- `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 没有该子命令时跳过预检，继续业务，不为预检自动升级。
-- 非托管环境没有全局命令时，使用 `npx @lark-base-open/base-database-cli` 调用；需要固定版本时使用 `npx @lark-base-open/base-database-cli@<已确认的精确版本>`。不猜 npm scope，不全盘搜索或反复安装。已知全局安装存在但 PATH 异常时，可使用确认过的可执行路径；不自动修改 shell 配置。
+本地使用 `@lark-base-open/base-database-cli` 时，在本会话首次业务操作前按[工程与环境](references/workspace.md#公开-cli-版本预检)确认入口与版本；托管 Builder 和 CI 跳过。预检失败或旧 CLI 不支持时继续当前任务，升级及覆盖 Skill 须取得相应授权。
 
 ## 任务路由
 
-| 用户任务 | 执行路径 | 主要命令 | 进入阶段前读取 |
-| --- | --- | --- | --- |
-| 新建系统 | 明确需求与访问模型 → 确定 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 来源 → 初始化 → 开发 → Preview 交付 | `init` → `deploy`                                         | [工程与环境](references/workspace.md)、[权限设计](references/permission-design.md)        |
+| 修改已有系统             | 确认现有工程 → 判断影响范围 → 增量修改 → 验证与交付                | 按影响范围修改，必要时 `deploy`                           | [工程与环境](references/workspace.md)，再读取受影响的协议                                 |
+| 恢复远端工程             | 确认本地状态和 应用 → 恢复源码与 Catalog → 继续原任务              | 按来源选择 `pull` 或 `init`                               | [工程与环境](references/workspace.md)                                                     |
+| 设计或评审               | 按评审范围分析并输出，不创建资源或发布                             | 只读分析                                                  | [工程质量](references/style-guide.md)，涉及权限、查询或视觉时读取对应专项                 |
+| 排查故障                 | 收集证据 → 定位失败阶段 → 按用户要求诊断或修复                     | `deployments status`、`doctor` 或项目级 `lark-cli -- ...` | [诊断与验收](references/verification.md)，再读取失败链路的协议                            |
+| 补齐新建 Base 的示例数据 | 读取字段与人员 → CLI 写入 → 页面 Database Function 回读 → 交付                   | `lark-cli -- base +record-batch-create`，再按协议调用 Database Function | [示例数据验收](references/release.md#从零建站示例数据验收)，即使 Preview 已发布也先读此节 |
+| 专项验收                 | 确定检查范围 → 执行已授权检查 → 报告证据与未验证项                 | 按契约调用 Database Function 或执行已授权检查                           | [诊断与验收](references/verification.md)                                                  |
+| 发布当前工程或已验证版本 | 检查工程、制品及授权 → 发布 → 必要收尾 → 交付                      | `deploy`；确认后 `deploy --production --yes`              | [发布与交付](references/release.md)                                                       |
 
-表中命令均指 `npx @lark-base-open/base-database-cli` 的子命令；托管环境使用宿主 CLI。完整参数见对应 reference。
+表格和 references 的示例默认使用本机 `base-database-cli`；需要回退时只替换命令前缀，保留其余参数。托管环境使用宿主 CLI。完整参数见对应 reference。
 
 新建默认创建 Base；用户明确指定已有 Base 时复用，不额外询问数据来源选择题。只有目标资源、数据所有权、权限或核心流程存在实质歧义时才询问。用户提供的工程、技术选择和已明确授权在后续步骤中持续有效。
 
 ## 开发阶段路由
 
-| 需要完成的工作 | 必读协议 |
-| --- | --- |
-| 首次实现页面、整体视觉改版或视觉评审 | [前端设计风格指导](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) |
-
-新建或整体改版先在内部规划中确定视觉方案，再实现设计变量和组件。业务建模与通用工程取舍按[工程质量](references/style-guide.md)执行；默认不创建额外设计文件，用户要求文档时按要求交付。
+| 需要完成的工作                                        | 必读协议                                                                                |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| 首次实现页面、整体视觉改版或视觉评审                  | [前端设计风格指导](references/frontend-design-guide.md)     |
+| 修改布局、颜色、排版或控件样式                        | 上述设计指导的相关章节，沿用现有设计系统；与视觉无关的修改不重读                        |
+| Page runtime、组件接入或 Function 调用                | [Page 开发](references/development.md)                                                  |
+| 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)                                              |
+| 日期表单、到期日、事件时间或时间筛选                  | [日期与时区](references/development.md#日期与时区)                                      |
+| 判断查询支持集之外的形态或处理兼容错误               | [查询能力边界](references/database-function-limitations.md)                                      |
+| FaaS 引用自定义环境变量，或用户要求查询、配置环境变量或第三方凭证            | [第三方 Agent 环境变量](references/environment-variables.md)                           |
+| FaaS 输入 Schema、写入、一致性和下游错误              | [FaaS 与记录协议](references/faas.md)                                                   |
+| 为 Page 或 FaaS 添加、升级第三方 npm 依赖             | [Page 开发中的依赖策略](references/development.md#第三方依赖策略)                       |
+| 附件上传、展示、下载、追加或移除                      | [文件传输](references/file-transfer.md)，实现前核对目标环境能力                         |
+| binding、身份过滤、角色或数据可见性                   | [权限设计](references/permission-design.md)                                             |
+| 自动化、表单、仪表盘等原生能力，或能力归属不明        | [原生 Base 能力路由](references/base-capability-routing.md)                             |
+| 原生 workflow 通知与站内入口                          | [通知集成](references/notifications.md)                                                 |
+| 固定单表的基础创建、更新、删除、附件增量或批量写入 | [Mutation Function](references/mutations.md) |
+
+新建或整体改版先在内部规划中确定视觉方案，再实现设计变量和组件。业务建模与通用工程取舍按[工程质量](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/`。`deploy` 时空 `ai/` 会跳过 AI Function 同步（`no_local_ai_functions`），本地全集非空时按全量覆盖写入草稿；`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 接口并先取得用户授权。
 
 ## 关键约束
 
-1. 应用 资源与发布使用 `npx @lark-base-open/base-database-cli`；原生 Base 配置使用 `lark-cli base +...`。托管环境使用宿主提供的 CLI，不切换环境。命令选择与工程恢复见[工程与环境](references/workspace.md)。
+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)维护。
+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 真实表；纯常量与无表依赖计算在 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 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#第三方依赖策略)。
+10. **交付边界**：常规发布先 Preview。新建 Base 的示例记录必须写入真实 Base，并用页面实际调用的 Database Function 回读；不以静态 fixture、`localStorage` 或页面自动播种代替。之后完成相关通知配置再交付。完整顺序只在[发布与交付](references/release.md)维护。
 
 ## 外部操作与授权
 
@@ -82,7 +98,7 @@ CLI 使用 `--app-token`、配置字段 `appToken`、`base-database.jsonc` 和 `
 
 删除或不可恢复地覆盖资源、业务记录、Function 或 binding，关闭 workflow/高级权限、改变已有角色权限，以及 Prod 发布前，确认用户授权覆盖具体目标、动作和实质影响。缺少授权时，先准备可审阅的对象和影响说明，提出确认请求后等待用户明确回复；等待期间不得调用该动作对应的外部变更工具。默认选项、超时、登录授权和工具提示本身不构成该业务动作的授权。
 
-非文字确认只有在宿主文档明确声明单次业务动作确认机制、且其回执绑定具体目标、动作、实质影响和用户确认结果时才可采用；生产发布还须绑定本次 Preview 制品。没有该契约时，不推断卡片点击或工具执行审批具有相同效力。当前 Builder 未声明这类业务确认机制，因而仅接受用户针对本次动作的明确文字回复；device-flow 登录授权不能代替业务确认。
+非文字确认只有在宿主文档明确声明单次业务动作确认机制、且其回执绑定具体目标、动作、实质影响和用户确认结果时才可采用；生产发布还须绑定本次 Preview 制品。没有该契约时，不推断卡片点击或工具执行审批具有相同效力。没有明确的业务确认契约时，只接受用户针对本次动作的明确文字回复；device-flow 登录授权不能代替业务确认。
 
 Prod 还要求用户已体验本次 Preview 并明确同意发布同一制品。“部署正式版”是有效表达的示例，不是唯一口令；任务开始时笼统的“搭建并发布”不能代替本次制品确认。目标、制品或实质影响变化时重新确认；无影响的格式变化不使已有授权失效。
 
@@ -92,15 +108,16 @@ workflow 启停及失败补偿按[通知集成](references/notifications.md#状
 
 完成条件由当前任务决定，不能把“发布成功”当作“整体完成”。常规 Preview 交付后等待用户体验；用户继续要求修改、排障或验收时进入相应路径，不受上一轮停止条件限制。
 
-- **完成**：本次约定的交付项已完成，验证范围与证据明确。
-- **部分完成**：已有成果可交付，但某些功能、验证或外部配置未完成，逐项列出。
+- **完成**：约定功能已实现，约定验证已通过；其他未执行的验证明确列出。
+- **部分完成**：已有成果可交付，但存在已知功能缺失、违反需求的实现、平台不支持的要求，或约定验证、外部配置未完成；即使 Preview 发布成功，也逐项列出缺口。
 - **阻塞**：必需步骤受认证、权限、平台能力或缺失输入等外部条件限制，记录阻塞及恢复条件。
 
 默认交付访问链接、业务变更、体验步骤、实际验证结果和影响使用的限制。仅使用发布命令返回的顶层 `baseAppUrl` 作为应用访问入口；不猜测地址或展示内部静态资源 `staticUrl`。技术清单与诊断信息按研发、排障或审计需要提供；不输出凭证，也不要求普通业务用户检查协议字段。
 
 ## 术语
 
+- **Database Function**：通过固定查询语句读取 Base 数据的函数；查询定义位于 `database-functions/<functionId>/main.sql`。
 - **应用 appToken**：应用标识；协议字段 `appToken`、FaaS 的 `projectId` 与示例中的工程常量 `PROJECT_ID` 在相应入口指向该应用，不是 Base token。`PROJECT_ID` 由示例调用方定义，不是 starter 提供的标识。
 - **Catalog**：已绑定数据表的 schema；本地快照为 `catalog.json`，更新从 应用 catalog 接口获取。Base 的业务记录不保存在 Catalog。
-- **operation**：业务动作及其固定输入输出契约，例如查询任务或审批申请；不是任意 URL/SQL 的代理。
-- **一方/三方**：分别指托管 Builder 与外部 Agent 搭建。两者使用同一设计原则，仅 CLI、环境和工程恢复来源不同。
+- **operation**：业务动作及其固定输入输出契约，例如查询任务或审批申请；不是任意 URL 或查询语句的代理。
+- **托管环境**：平台提供 CLI、登录态或工程的建站环境；使用其已提供的入口。自行安装 CLI 的本地环境按公开安装流程执行。