metabase-react-sdk-setup

将此 skill 用于任何涉及 @metabase/embedding-sdk-react 的任务，包括初始设置、嵌入仪表板、主题设置或插件。

沟通风格：简洁。一次只做一个步骤。向用户征求信息时，只输出问题，不要解释接下来的步骤、实现细节或计划要做什么。用户不需要路线图。

关键 — 开始做任何事情之前，必须先获取 API 密钥

第 1 步会向用户索要 Metabase URL 和 API 密钥。两者缺一不可。 在用户提供 API 密钥之前，不得检测 Metabase 版本、获取 llms.txt、安装软件包或编写任何代码。 没有 API 密钥时，不得尝试调用任何 Metabase API 端点，否则会返回 401，届时你只能猜测。 如果任何 Metabase API 调用返回 401，立即停止所有操作，并向用户索要 API 密钥。

第 1 步 — 获取 Metabase URL 和 API 密钥

开始之前，你需要 Metabase 实例 URL 和管理员 API 密钥。

.env.metabase 仅供此 skill 中的管理员任务使用（向 Metabase 发起 API 调用）。它不是应用的运行时配置。绝不要在用户的应用代码或构建配置中导入、读取或引用 .env.metabase。应用的实例 URL 应放在用户自己的 .env 文件中（例如 VITE_METABASE_URL、NEXT_PUBLIC_METABASE_URL）——在第 4 步中设置。

检查项目根目录中是否存在 .env.metabase，且其中是否已有非空的 METABASE_INSTANCE_URL 和 METABASE_ADMIN_API_KEY。如果都有，跳到第 2 步。

否则，创建该文件并将其加入 gitignore：

grep -qxF '.env.metabase' .gitignore 2>/dev/null || echo '.env.metabase' >> .gitignore
printf 'METABASE_INSTANCE_URL=\nMETABASE_ADMIN_API_KEY=\n' > .env.metabase

然后只输出以下消息——不要添加开场白，不要解释接下来要做什么，也不要提供实现细节：

我已在项目根目录创建 .env.metabase。请填写这两个值：

1. 将 METABASE_INSTANCE_URL 设为你的 Metabase URL（例如 http://localhost:3000）
2. 打开 {your URL}/admin/settings/authentication/api-keys，创建一个新的 API 密钥
3. 将该密钥设为 METABASE_ADMIN_API_KEY
4. 完成后告知我

不要猜测或假定实例 URL。不要预填 localhost:3000。不要让用户在聊天中粘贴密钥——密钥只能写入 .env.metabase。等待用户确认后，再继续第 2 步。

第 2 步 — 检测版本并发现仪表板

现在你已有 API 密钥，可以检测版本并查找仪表板。

2a — 检测版本

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/session/properties" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY" | grep -o '"tag":"[^"]*"'

从标签中解析版本类型和主版本号：

标签格式	版本类型	示例
v0.X.Y	OSS（社区版）	v0.60.1 → 主版本号 60，OSS
v1.X.Y	企业版（EE）	v1.60.1 → 主版本号 60，EE

如果主版本号小于 49，告知用户 Embedding SDK 要求 Metabase 49 或更高版本，然后停止。

如果标签以 v1. 开头，则该实例为 Enterprise Edition——使用完整的 JWT SSO 嵌入。 不要回退到访客嵌入或任何仅适用于 OSS 的身份验证方式。

记住主版本号——第 3 步会用到。

2b — 启用 Embedding SDK

自动启用 SDK，免得用户在管理面板中手动切换：

source .env.metabase && \
  curl -s -X PUT "$METABASE_INSTANCE_URL/api/setting/enable-embedding-sdk" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"value": true}'

如果此操作返回错误（例如 403），告知用户前往 <INSTANCE_URL>/admin/settings/embedding 手动启用，然后继续。

现在不要获取 llms.txt。 你需要先获取仪表板 ID。

2c — 查找仪表板和表格候选项

运行以下两项：

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/search?models=dashboard&archived=false" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY"

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/automagic-dashboards/database/1/candidates" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY"

筛选并确定结果优先级：

• 排除来自“Usage analytics”集合的所有仪表板——这些是 Metabase 内部管理仪表板，不是用户内容。
• 降低来自“Sample Database”的结果的优先级——优先选择用户自己的数据库和仪表板。
• 从每个类别中选出与用户请求最相关的前 5 个结果。不要列出所有结果。

按以下格式展示：

现有仪表板：

1. Sales Overview（ID 3）
2. Customer Analysis（ID 7） ...

或者，我可以用你的数据创建一个新仪表板： A. Orders 表 B. Products 表 ...

你想嵌入哪些？（例如“1 和 3”或“A”）

等待用户选择。如果用户选择了表格，则生成并保存 X-ray 仪表板：

source .env.metabase && \
  DASHBOARD=$(curl -s "$METABASE_INSTANCE_URL/api/automagic-dashboards/table/<TABLE_ID>" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY")

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/dashboard/save" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$DASHBOARD"

保存响应中包含已持久化的仪表板及真实的 id 字段。之后请使用这些 ID。

第 3 步 — 获取文档、设置身份验证并安装 SDK

进入此步骤前，你必须先获取真实的仪表板 ID。如果没有，请返回第 2 步。

现在使用第 2a 步中的主版本号获取带版本号的文档索引：

curl -s https://www.metabase.com/docs/v0.<MAJOR>/llms.txt

如果内容为空，则改用 https://www.metabase.com/docs/latest/llms.txt。其中包含此版本正确的属性名称、身份验证配置格式、SDK 安装命令和破坏性更改。不要获取 llms-embedding-full.txt（文件过大）。

3a — 设置 JWT SSO 身份验证（如果已完成则跳过）

按照 llms.txt 中的身份验证设置说明操作。具体来说：

• 从 Metabase 获取 JWT 签名密钥：Settings → Admin → Embedding → Embedding secret key
• 告诉用户将其保存为服务器端环境变量 METABASE_JWT_SECRET（仅限服务器端，切勿使用浏览器可访问的环境变量）
• 询问用户使用哪种后端框架（Next.js API 路由、Express、Fastify 等），并按照 llms.txt 中的模式搭建一个最简 JWT 签名端点

3b — 安装 SDK（如果已安装正确版本，则跳过）

检查用户的 package.json 中是否已包含 @metabase/embedding-sdk-react。

• 如果尚未安装：使用 llms.txt 中的安装命令（正确的 dist-tag 与实例主版本号相匹配）。
• 如果已安装：确认主版本号是否匹配。如不匹配，请发出警告并提供更新选项。

第 4 步 — 生成嵌入代码

所有 API 格式均以 llms.txt 为准。直接将文件写入用户的项目——直接编辑现有文件，不要在旁边创建新文件。

代码约定（优先于文档中的任何内容）

• 仅使用 JWT SSO：API 密钥授予管理员级访问权限，用于面向最终用户的嵌入并不安全。请使用服务器端 JWT 签名端点；MetabaseProvider 接收其 URL。切勿生成 apiKey、METABASE_API_KEY、api-key 或 x-api-key——即使是占位符也不行。只有用户明确提出要求并知晓安全风险时，才可例外。
• 从环境变量获取实例 URL：例如 Vite 使用 VITE_METABASE_URL，Next.js 使用 NEXT_PUBLIC_METABASE_URL。切勿硬编码。
• 将仪表板 ID 作为内联字面量：始终在 JSX 中直接硬编码仪表板 ID，例如 <InteractiveDashboard dashboardId={7} />。仪表板 ID 不是机密。切勿使用 import.meta.env.VITE_METABASE_DASHBOARD_*、环境变量、配置对象、parseDashboardId 助手函数，或任何间接方式来获取仪表板 ID。目标是生成简洁、精简的代码，让用户一看就能理解和调整。
• 密钥仅限服务器端使用：JWT 密钥绝不能出现在浏览器可访问的环境变量或前端代码中。

主题

生成嵌入代码后，检查用户的应用是否已有样式——查看 CSS 变量、Tailwind 配置或主题文件。设置 MetabaseProvider 上的 theme 属性，使其与应用的外观和风格一致。至少调整以下内容：

• colors.brand — 应用的主色／强调色
• colors.background — 与页面背景一致，避免嵌入内容在深色页面上显示成白色方块（或反之）
• fontFamily — 与应用的字体一致

完整的主题结构请参阅 llms.txt。保持精简——仅设置与 Metabase 默认值不同的值。