用途
该技能面向使用 @metabase/embedding-sdk-react 的任务，包括首次接入配置、嵌入仪表盘、主题定制以及插件相关操作。其核心目标是引导完成从零到可运行嵌入代码的完整流程。
主要能力
- 实例检测：通过 /api/session/properties 读取版本标签，区分 OSS（v0.X.Y）与 Enterprise（v1.X.Y），并解析主版本号。若主版本低于 49，则提示 Embedding SDK 需要 Metabase 49+ 并停止。
- 密钥与配置管理：要求用户在项目根目录创建并 gitignore 的 .env.metabase 文件中填写 METABASE_INSTANCE_URL 与 METABASE_ADMIN_API_KEY，且明确该文件仅用于本技能内的管理任务，不得被应用运行时代码引用。
- 启用 Embedding SDK：通过 PUT /api/setting/enable-embedding-sdk 自动开启；若失败（如 403），提示用户在管理面板手动开启。
- 仪表盘发现：调用 /api/search?models=dashboard&archived=false 与 /api/automagic-dashboards/database/1/candidates，过滤 Usage analytics 集合、降低 Sample Database 优先级，列出最多 5 个相关仪表盘或候选表，等待用户选择；若选择表，则生成并保存 X-ray 仪表盘。
- 文档获取：按主版本拉取 https://www.metabase.com/docs/v0.<MAJOR>/llms.txt，为空时回退到 latest 版本，作为属性名、认证配置、安装命令与破坏性变更的权威参考。
- JWT SSO 认证：从 Metabase 管理后台获取 Embedding secret key，要求仅保存在服务端环境变量 METABASE_JWT_SECRET 中，并按用户后端框架（Next.js API route、Express、Fastify 等）搭建最小 JWT 签名端点。
- SDK 安装：检查 package.json 中是否已有 @metabase/embedding-sdk-react，未安装则按 llms.txt 的安装命令执行，已安装则校验主版本是否匹配。
- 嵌入代码生成：直接在用户项目中写入或就地编辑文件，遵循 JWT SSO only、实例 URL 从环境变量读取、仪表盘 ID 以内联字面量硬编码、密钥仅限服务端等约定。
- 主题配置：检查应用现有样式（CSS 变量、Tailwind 配置或主题文件），在 MetabaseProvider 上设置 theme，至少对齐 colors.brand、colors.background 与 fontFamily。
使用方式
技能按步骤推进，要求一次只做一步，向用户提问时只输出问题本身，不解释后续步骤或实现细节。关键约束包括：必须先获得 API 密钥才能进行任何操作；没有密钥时不得检测版本、拉取 llms.txt、安装包或写代码；任何 Metabase API 调用返回 401 时应立即停止并索要密钥；不得猜测或预填实例 URL；不得要求用户在聊天中粘贴密钥。
适用场景
适用于需要将 Metabase 仪表盘嵌入 React 应用的开发任务，尤其是首次接入、认证配置、SDK 安装、嵌入代码生成与主题对齐等场景。
限制
- Embedding SDK 要求 Metabase 49 及以上版本。
- Enterprise 实例（v1.X.Y）必须使用完整 JWT SSO 嵌入，不得回退到 guest embedding 或仅 OSS 的认证路径。
- 不得生成 apiKey、METABASE_API_KEY、api-key 或 x-api-key，即使作为占位符也不行，除非用户明确要求并知晓安全风险。
- 仪表盘 ID 不得通过环境变量、配置对象或辅助函数间接引用。
- JWT 密钥不得出现在浏览器可访问的环境变量或前端代码中。
- 不拉取 llms-embedding-full.txt（体积过大）。
- 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。