databricks-apps

Databricks Apps 开发

首先：使用父级 databricks-core skill 获取 CLI 基础知识、身份验证和配置文件选择方法。

包管理器——在执行以下任何安装或命令之前，先确定包管理器：

Databricks Apps 官方仅支持 npm 和 pnpm。

1. 按以下优先级确定项目的包管理器：项目说明 → package.json 中的 packageManager 字段 → 锁文件（pnpm-lock.yaml → pnpm，package-lock.json → npm）。
2. 如果信号冲突，或检测到不受支持的包管理器（yarn、bun 等），请停止并先询问用户要使用哪个包管理器。
3. 只有在无法确定包管理器时，才默认使用 pnpm。

在此 skill 及其指南中，将 <pm> 替换为已确定的包管理器，用于安装和运行包脚本（<pm> install、<pm> run typegen）。

<pm> 是文档占位符，不是 shell 变量——请将其替换为实际值，不要直接输入。

这真的是 Databricks App 吗？ 不要假设展示数据只能通过 App 实现。对于简单的“带几个图表的仪表板”，如果没有特定的 App 需求，托管式 AI/BI（Lakeview）仪表板是更简单的选择 → 使用 databricks-aibi-dashboards skill，而不是本 skill。只有当用户需要 AI/BI 无法提供的功能（定制交互或组件、回写、嵌入式或受身份验证限制的工作流、App 中的 Genie/聊天界面），或明确要求开发 App 时，才选择自定义 Databricks App。如果确实无法判断，请同时说明两种方案（托管式 AI/BI 仪表板与自定义 App），让用户自行选择，而不是默认开发 App。一旦确定应使用 App，本 skill 可以优先采用基于 App 的仪表板；databricks-app-design 则涵盖如何出色地构建它。

数据 UI 设计（所有展示数据的 App 均必须遵循）：确认用户需要的是自定义代码 App（而非托管式 AI/BI 仪表板——见上文）后，只要 App 展示任何数据——KPI/概览页面、报告、图表、表格、查询结果，或对话式/聊天/Genie 自然语言助手——就必须同时使用 databricks-app-design skill，确定布局、图表、KPI、语义颜色、必需状态和 AI 结果可信度，并将这些要求映射到 AppKit 组件。聊天/Genie App 也包括在内，不仅限于静态数据视图——如有疑问，请使用该 skill。

构建可部署到 Databricks Apps 平台的 App。

各阶段必读内容

阶段	继续之前请阅读
搭建脚手架	⚠️ 停止 — 搭建脚手架之前，请先查看状态存储指南并完成下方的数据访问决策关卡。 父级 databricks-core 技能（身份验证、数据仓库发现）；然后运行 databricks apps manifest + databricks apps init，并使用 --features 和 --set（见下方 AppKit 部分）
编写 SQL 查询	SQL 查询指南
编写 UI 组件	前端指南
使用 useAnalyticsQuery	AppKit SDK
查询受治理的 UC Metric View	Metric Views 指南
添加 API 端点	自定义端点指南
使用 Lakebase（OLTP 数据库）	Lakebase 指南
添加 Genie 聊天 / Genie 驱动的应用	Genie 指南 — 按照下方的 Genie Agent 工作流操作
使用 Model Serving（ML 推理）	Model Serving 指南
生成或编辑图像（文本转图像、图像转图像）	图像生成指南
托管 AI Agent（可使用工具的聊天机器人，测试版）	Agents 指南 — 从 @databricks/appkit/beta 导入
类型化数据契约（原型优先设计）	Proto-First 指南 和 Plugin Contracts
管理 UC Volumes 中的文件	文件指南
从应用触发 / 监控 Lakeflow Jobs	作业指南
平台规则（权限、部署、限制）	平台指南 — 所有应用（包括 AppKit）都必须阅读
非 AppKit 应用（Streamlit、FastAPI、Flask、Gradio、Next.js 等）	其他框架

通用指南

• 应用名称：平台应用资源名称最多可包含 30 个小写字母、数字和连字符（不能包含下划线）。对于使用 databricks apps init 创建的 AppKit 项目，基本名称需控制在 26 个字符以内，因为其开发工作流会添加 dev- 前缀。DABs 不会添加此前缀。
• 验证：部署前运行 databricks apps validate --profile <PROFILE>。
• 冒烟测试（仅限 AppKit）：运行验证前，务必先更新 tests/smoke.spec.ts 中的选择器。默认模板会检查标题“Minimal Databricks App”和文本“hello world”——在你的自定义应用中，这些检查必定失败。请参阅测试指南。
• 冒烟测试选择器：仅使用 Playwright 定位器 API——getByRole、getByText、getByPlaceholder、getByLabel。Playwright 中不存在 getByLabelText（它是 React Testing Library 的方法），运行时会抛出 TypeError。请参阅测试指南或运行 npx playwright codegen。
• 冒烟测试数据：确保结果集低于 1 MB 的分析事件负载上限。返回数千行的查询会导致 INVALID_REQUEST: Event exceeds max size of 1048576 bytes 和 net::ERR_ABORTED，使所有断言的 UI 元素都无法出现。请使用 LIMIT 或聚合查询（例如 COUNT(*) GROUP BY status）——切勿直接输出原始数据行。
• AppKit 版本：切勿覆盖 package.json 中的 @databricks/appkit 或 @databricks/appkit-ui 版本——databricks apps init 会设置正确的版本。除非用户明确要求，否则不要安装这两个包的其他版本。如果需要其他版本，请使用 databricks apps init --version <version> 重新搭建项目。
• 身份验证：由父级 databricks-core 技能处理。
• AppKit API 范围：在编写调用 AppKit API（createApp、插件形状、useAnalyticsQuery、useMetricView 等）的代码前，运行 npx @databricks/appkit docs <section>，并使用实际签名。训练数据中的 API 形状可能已过时；只要编造一个签名，验证期间的 tsc --noEmit 就会失败。文档随已安装的 AppKit 一同提供，是权威来源。
• TypeScript 类型断言：切勿使用 as unknown as <T> 双重断言——appkit lint 会强制执行 no-double-type-assertion，任何一处违规都会导致整个验证步骤失败。请改用 Zod 缩小类型范围（z.infer<typeof schema>）、运行时类型守卫或带类型的映射函数。如果查询结果需要重新整形，请通过 queryKey 类型为行模式指定类型，而不是进行类型断言。

项目结构（运行 databricks apps init --features analytics 后）

• client/src/App.tsx — React 主组件（从这里开始）
• config/queries/*.sql — SQL 查询文件（queryKey = 不含 .sql 的文件名）
• config/metric-views/definitions.json — 受治理的 UC Metric View 绑定（可选；请参阅 Metric Views）
• server/server.ts — 后端入口（onPluginsReady + Express 路由）
• tests/smoke.spec.ts — 冒烟测试（⚠️ 务必为你的应用更新选择器）
• client/src/appKitTypes.d.ts — 自动生成的类型（<pm> run typegen）

项目结构（运行 databricks apps init --features lakebase 后）

• server/server.ts — 使用 Lakebase 连接池和 Express 路由的后端
• client/src/App.tsx — React 前端
• app.yaml — 包含 database 资源声明的清单
• package.json — 包含 @databricks/lakebase 依赖项
• 注意：没有 config/queries/ — Lakebase 应用会在 Express 路由中使用 appkit.lakebase.query()，而不是 SQL 文件

数据发现

在编写任何 SQL 之前，先使用父级 databricks-core 技能探索数据——按关键词搜索 information_schema，然后对所需的表批量运行 discover-schema。请勿跳过此步骤。

状态存储指南（在决策关卡之前评估）：

如果用户的应用描述涉及存储或持久化数据——表单、CRUD 操作、用户提交的内容、订单、待办事项或其他用户生成的内容——则该应用可能需要 Lakebase 数据库。

1. 询问用户应用是否需要持久化存储（Lakebase），然后再搭建脚手架。请勿擅自添加 Lakebase。
2. 如果用户确认，询问是否要复用现有的 Lakebase 项目，还是创建新项目（与下方的 Genie 流程相同）——切勿擅自创建。使用 databricks-lakebase 技能获取分支和数据库资源名称：
   • **复用：**使用 databricks postgres list-projects 列出项目，然后运行 list-branches / list-databases，让用户选择项目、分支和数据库；确认应用将拥有哪个架构（新建或专用架构可避免服务主体所有权冲突）。
   • **创建：**创建新项目（系统会自动预配 production 分支和 databricks_postgres 数据库）。
3. 使用 --features lakebase 搭建脚手架，并传入 --set lakebase.postgres.branch=<BRANCH_NAME> --set lakebase.postgres.database=<DATABASE_NAME>。
4. 如果应用还会读取 Unity Catalog 表，请继续执行下方的数据访问决策关卡，以确定是添加 --features analytics，还是使用 Lakebase 同步表。

除非用户明确要求持久化写回存储，否则请勿为分析、仪表板或可视化应用添加 Lakebase。只读数据展示、筛选器和偏好设置都不需要数据库。

开发工作流（按此顺序执行）

数据访问决策关卡（搭建脚手架前必须完成）：

如果应用会读取 Unity Catalog / lakehouse 表，必须向用户展示以下对比并请他们选择。不得跳过，也不得替他们选择。

	(A) Lakebase 同步表	(B) Analytics
速度	亚秒级响应	需要几秒
最适合	全文搜索、输入提示、自动补全、实时查询、运营类应用	仪表板、图表、聚合、KPI、筛选查询、浏览
工作方式	将数据从 Delta 同步到 Lakebase Postgres	在读取时对 SQL 仓库运行查询

展示表格后，给出简短建议。对于大多数只读应用，默认建议使用 Analytics (B)——适用于仪表板、图表、筛选查询、浏览和聚合。只有当应用需要为全文搜索、输入提示／自动补全、按 ID 实时查询或运营数据服务提供亚秒级延迟时，才建议使用 Lakebase 同步表 (A)。注意：提示词中的“搜索”或“筛选”通常指 SQL WHERE 子句（Analytics），而非全文搜索（Lakebase）。最终决定始终由用户做出。

用户选择后：

• (A) Lakebase 同步表 → 使用 --features lakebase 搭建脚手架。完整工作流请参阅 Lakebase 指南。
• (B) Analytics → 使用 --features analytics 搭建脚手架。在 Analytics 中，如果数据是受治理的 UC Metric View（预定义的语义度量／维度），则通过 metric-view 路径查询——请参阅 Metric Views——否则编写 config/queries/ SQL。
• 两者都选 → 如果应用需要这两种模式，则使用 --features analytics,lakebase 搭建脚手架。
• 如果应用不读取 Unity Catalog 数据（纯 CRUD、Genie、Model Serving），则跳过此关卡，并使用适当的 --features 标志搭建脚手架。

Analytics 应用（--features analytics）：

1. 在 config/queries/ 中创建 SQL 文件
2. 运行 <pm> run typegen — 确认所有查询都显示 ✓
3. 阅读 client/src/appKitTypes.d.ts 以查看生成的类型
4. 然后使用生成的类型编写 App.tsx
5. 更新 tests/smoke.spec.ts 选择器
6. 运行 databricks apps validate --profile <PROFILE>

不要在运行 typegen 之前编写 UI 代码——类型尚不存在，会浪费时间处理编译错误。

Lakebase 应用（--features lakebase）：无需 SQL 文件或 typegen。请参阅 Lakebase 指南中的 onPluginsReady 模式：在启动时初始化架构，在 server/server.ts 中注册 Express 路由，然后构建 React 前端。

何时使用什么

完成上述决策关卡后，请使用以下路由表：

• 读取分析数据 → 在图表／表格中显示：使用带有 queryKey 属性的可视化组件
• 读取分析数据 → 自定义显示（KPI、卡片）：使用 useAnalyticsQuery Hook
• 读取分析数据 → 显示前需要计算：仍使用 useAnalyticsQuery，在客户端转换数据
• 读取受治理的 UC Metric View（语义层）：使用 useMetricView Hook 和 config/metric-views/definitions.json——参见 Metric Views
• 低延迟读取 Lakehouse 数据（查找、搜索、目录）：使用 Lakebase 同步表——参见 Lakebase Guide
• 读取／写入持久化数据（用户、订单、CRUD 状态）：通过 onPluginsReady 中的 Express 路由使用 Lakebase——参见 Lakebase Guide
• 针对表的自然语言查询界面（Genie）：使用 genie() 插件——参见 Genie Guide
• 调用 ML 模型端点：使用 serving() 插件——参见 Model Serving Guide
• 调用基础模型／UC 模型服务（system.ai.*）：声明 uc_securable（MODEL_SERVICE）资源，并在 /ai-gateway/mlflow/v1 上调用服务名称——参见 Unity Catalog model services 和 databricks-unity-gateway 技能（不要使用 serving()，它接受的是 serving-endpoint 名称）
• 根据提示词生成或编辑图像：使用流式 Express 路由（或用于聊天 UI 的 agents 工具）和原生 fetch，调用支持图像的 Foundation Model——参见 Image Generation Guide
• 会 调用工具（SQL、文件、Genie、MCP）、委派任务给子 Agent，或流式传输带有人类审批环节的多轮聊天的 AI Agent：使用 agents() 插件（从 @databricks/appkit/beta 导入，beta）——参见 Agents Guide
• 从应用触发或监控 Lakeflow Job：使用 jobs() 插件——参见 Jobs Guide
• ⚠️ 绝不要添加用于对仓库运行 SELECT 查询的自定义端点——始终使用 config/queries/ 中的 SQL 文件
• ⚠️ 绝不要将 useAnalyticsQuery 用于 Lakebase 数据——它只查询 SQL 仓库

框架

AppKit（推荐）

TypeScript／React 框架，提供类型安全的 SQL 查询和内置组件。

官方文档——所有 API 详情的权威来源。使用已安装的 @databricks/appkit 包中的项目本地 appkit CLI：

npx @databricks/appkit docs                            # ← ALWAYS start here to see available pages
npx @databricks/appkit docs <query>                    # view a section by name or doc path
npx @databricks/appkit docs --full                     # full index with all API entries
npx @databricks/appkit docs "appkit-ui API reference"   # example: section by name
npx @databricks/appkit docs ./docs/plugins/analytics.md  # example: specific doc file

不要猜测文档路径。 请先不带参数运行，再从索引中选择。<query> 参数既接受索引中的章节名称，也接受文件路径。文档是组件属性、Hook 签名和服务端 API 的权威依据；技能文件仅介绍反模式和注意事项。

应用清单与脚手架

用于搭建脚手架的 Agent 工作流：先获取清单，再构建 init 命令。

1. 获取清单（描述插件及其资源的 JSON 架构）：

   databricks apps manifest --profile <PROFILE>
   # See plugins available in a specific AppKit version:
   databricks apps manifest --version <VERSION> --profile <PROFILE>
   # Custom template:
   databricks apps manifest --template <GIT_URL> --profile <PROFILE>
   

   输出内容定义了：
   • 插件：每个插件都有一个键（用于 --features 的插件 ID），以及 requiredByTemplate 和 resources。
   • requiredByTemplate：如果为 true，该插件对此模板来说是必需的——不要将其添加到 --features（它会自动包含）；但仍须通过 --set 提供该插件的所有必需资源。如果为 false 或未设置，该插件为可选插件——仅当用户的提示词表明他们需要此功能（例如分析／SQL）时，才将其添加到 --features，然后通过 --set 提供其必需资源。
   • 资源：每个插件都有 resources.required 和 resources.optional（数组）。每个条目都有 resourceKey 和 fields（对象：字段名称 → 描述／环境变量）。对于所包含的每个插件的每个必需资源字段，使用 --set <plugin>.<resourceKey>.<field>=<value>。
2. 搭建脚手架（仅使用 Databricks CLI）：

   databricks apps init --name <NAME> --features <plugin1>,<plugin2> \
     --set <plugin1>.<resourceKey>.<field>=<value> \
     --set <plugin2>.<resourceKey>.<field>=<value> \
     --description "<DESC>" --run none --profile <PROFILE>
   # --run none: skip auto-run after scaffolding (review code first)
   # With custom template:
   databricks apps init --template <GIT_URL> --name <NAME> --features ... --set ... --profile <PROFILE>
   

   可选使用 --version <VERSION> 指定目标 AppKit 版本。
   • 必需项：--name、--profile。名称：最多 26 个字符，仅限小写字母、数字和连字符。仅当用户需要可选插件（requiredByTemplate: false 或未设置该字段的插件）时，才使用 --features；不得在 --features 中列出必需插件。
   • 资源：对于（1）所有 requiredByTemplate: true 的插件，以及（2）你添加到 --features 的任何可选插件，使用 --set 传入每个必需资源（resources.required 中的每个字段）。仅在用户提出要求时，才为 resources.optional 添加 --set。
   • 发现资源：使用父级 databricks-core 技能解析 ID（例如，warehouse：databricks warehouses list --profile <PROFILE> 或 databricks experimental aitools tools get-default-warehouse --profile <PROFILE>）。

切勿猜测插件名称、资源键或属性名称——始终从 databricks apps manifest 输出中获取。示例：如果清单显示插件 analytics 有一个必需资源 resourceKey: "sql-warehouse"，且 fields: { "id": ... }，则包含 --set analytics.sql-warehouse.id=<ID>。

**执行身份（身份验证模式）**要求 databricks CLI >= v1.20.0（首个支持 auth-mode 功能的版本；v1.19.0 或更早版本不支持）。不支持该功能的 CLI 中不存在这些标志；所有资源都会绑定到服务主体，且不得使用下列标志。默认情况下，所有资源仍绑定到服务主体（SP），省略这些标志所产生的输出与之前完全相同。

• --auth-mode obo|sp 设置应用级默认模式。sp 为默认值。--auth-mode obo 仅适用于可以代表用户运行的资源；无法代表用户运行的资源（例如 secret、Lakebase）仍使用 SP，CLI 会打印一条列出这些资源的说明。--auth-mode both 在应用级别无效。
• --set <plugin>.<resourceKey>.authMode=obo|sp|both 设置单个资源的身份，并覆盖应用级默认模式。both 仅在此处按资源设置时有效。
• 对无法以 OBO 方式运行的资源显式设置 authMode 属于错误（CLI 会指出资源并说明如何修正）。
• 交互式身份验证提示（Service principal / On behalf of user / Mixed）仅在完全交互式流程中出现。传入 --features 或 --set 时，不会出现提示，默认使用 SP。

各模式会生成的内容，以及 databricks apps validate 的 OBO 检查，详见平台指南。默认使用 SP；仅当应用必须强制执行查看用户自身的权限时，才选择 OBO（行级或按用户的数据访问）。混合模式很常见，例如，分析仓库使用 OBO，而作业使用 SP。

脚手架规则协议——databricks apps manifest 可能会在模板级别（顶层 scaffolding.rules）和各个插件上（plugins[].scaffolding.rules）输出 scaffolding.rules。每个规则块都包含 must / should / never 数组，其中是简短的指令字符串。按以下方式使用：

1. 收集 — 对最终 --features 列表中的每个插件，以及每个 requiredByTemplate: true 的插件，读取 plugins[].scaffolding.rules。将这些规则与模板顶层的 scaffolding.rules 合并为一个工作集，并标注来源（模板或 <plugin>）。
2. 优先级 — 清单中的规则优先于本技能内置的指令。若清单未涉及某个主题，则以本技能的内容作为最低要求。
3. 阶段顺序 — 文本以 Before init 开头的规则必须在执行 databricks apps init 前完成。以 After init 开头的规则必须在初始化完成后执行（例如迁移、类型生成、连通性检查）。没有阶段前缀的规则在整个脚手架搭建／开发循环中均适用。
4. 冲突检测 — 如果插件的 must 规则与模板的 never 规则针对同一目标相互矛盾（反之亦然），请停止并询问用户应遵循哪条规则，然后再继续。不要默默自行选择。同一操作上的 must 与 never 视为冲突；should 仅供参考，不会阻止操作。
5. 报告 — 在运行 databricks apps init 前，向用户展示合并后的工作集，按阶段（Before init / After init / Always）和严重程度（must / should / never）分组，明确列出当前生效的约束。

阅读 AppKit 概览，了解项目结构、工作流和实现前检查清单。

Genie Agent 工作流 — 用户想要构建由 Genie 驱动的应用时，不要一开始就询问 Genie Space ID。应按以下步骤操作：

1. 询问应用应查询哪些 Unity Catalog 表（完整限定名称：catalog.schema.table）。
2. 询问是复用现有 Genie 空间，还是创建新的空间。
3. 如果要创建：先查找仓库，然后使用 databricks genie create-space 创建空间（语法和序列化空间格式请参见 Genie 指南）。
4. 如果要复用：使用 databricks genie list-spaces --profile <PROFILE> 查找现有空间，并让用户选择。
5. 搭建脚手架或将空间 ID 接入应用 — 从 databricks apps manifest 推导 --set 键。

阅读 Genie 指南，了解配置、SSE 端点和前端集成。

常见脚手架搭建错误

# ❌ WRONG: name is NOT a positional argument
databricks apps init --features analytics my-app-name
# → "unknown command" error

# ✅ CORRECT: use --name flag
databricks apps init --name my-app-name --features analytics --set "..." --profile <PROFILE>

目录命名

databricks apps init 会创建与应用名称对应的 kebab-case 目录。 应用名称必须为小写，且只能包含连字符（≤26 个字符）。

其他框架（Streamlit、FastAPI、Flask、Gradio、Dash、Next.js 等）

Databricks Apps 支持任何可作为 HTTP 服务运行的框架。LLM 已熟悉这些框架，难点在于与 Databricks 平台集成。

构建任何非 AppKit 应用前，请阅读 其他框架指南。 该指南介绍端口／主机配置、app.yaml 和 databricks.yml 设置、依赖管理、网络配置，以及各框架特有的注意事项。

部署后验证

部署后，验证应用是否正在运行：

databricks apps get <app-name> --profile <PROFILE> -o json   # Check app_status.state: RUNNING; the `url` field is the app's URL
databricks apps logs <app-name> --follow --profile <PROFILE>  # Stream live logs (Ctrl+C to stop)

注意： databricks apps logs 需要 OAuth 身份验证，不能与 PAT 配合使用。若使用 PAT 身份验证，请使用 databricks apps get 检查状态。