metabase-modular-embedding-to-modular-embedding-sdk-upgrade

执行契约

请按顺序执行工作流步骤，不要跳过任何步骤。先创建检查清单，然后逐项执行并明确标记为已完成，同时提供证据。每个步骤的输出都会供下一步使用，因此跳过步骤会导致迁移错误。

如果因信息缺失或工具故障而无法完成某一步，必须：

1. 将该步骤记录为 ❌ blocked，
2. 明确说明缺少什么／发生了什么故障，
3. 停止（不要继续后续步骤）。

必需的输出结构

回复应按以下顺序包含这些部分：

1. 步骤 0：先决条件检查
2. 步骤 0.1：迁移计划检查清单
3. 步骤 1：项目扫描
4. 步骤 2：目标 SDK API
5. 步骤 3：迁移映射
6. 步骤 4：已应用的代码更改
7. 步骤 5：类型检查验证
8. 步骤 6：最终总结

每个步骤部分都应以状态行结尾：

• Status: ✅ complete 或 Status: ❌ blocked

证据要求

• 步骤 0：检测到的 React（依赖项和版本）、Metabase 实例版本、目标 SDK 版本、包管理器。
• 步骤 1：所有使用 Modular embedding 的文件（Web Components、metabaseConfig、embed.js 脚本标签），并附上匹配的 grep 行。
• 步骤 2：确认已在上下文中加载 d.ts。列出导出的组件、其 props，以及 MetabaseProvider 配置类型。
• 步骤 3：结构化迁移映射——每个 Web Component 对应的 React 组件及其 prop 转换、身份验证配置映射，以及移除 embed.js 的计划。
• 步骤 4：逐个文件说明更改内容和应用的确切 diff。
• 步骤 5：实际运行的确切类型检查命令，以及仍存在的错误摘要（如有）。

凭据安全

此迁移涉及的代码可能包含 API 密钥、JWT 或身份验证配置值（例如 window.metabaseConfig）。规则：

• 切勿输出字面形式的秘密值——如果发现代码中硬编码的 API 密钥、令牌或秘密，应通过变量名或文件位置引用（例如“config.js:12 中的密钥”），绝不可复述其值。
• 在代码 diff 和摘要中，使用变量引用，而非其解析后的值。
• 如果发现硬编码的秘密，请告知用户，并建议在迁移过程中将其移至环境变量。

性能

此工作流设计为流水线：

Round 1 (grep+glob+pkg) ──► Round 2 (prepare.sh) ──► Round 3 (read-sources.sh) ──► Step 3 (mapping, inline)
                                                                                          │
                                                                                    Step 4 per-file:
                                                                                     ├── Convert FileA
                                                                                     ├── Convert FileB
                                                                                     └── Convert FileC
                                                                                           │
                                                                                     Step 5 (typecheck) ──► Step 6

在 Claude Code 中，使用并行工具调用，或为子 Agent 设置 run_in_background: true。

不要解析仓库分支、提交、PR 或 issue——这些内容会造成干扰，且无关紧要。

步骤 1 和 2 的工具调用轮次预算

步骤 1 和 2 必须在 3 轮工具调用内完成。

第 1 轮——发现（全部并发，在同一条消息中）：

• 在 *.{jsx,tsx,js,ts} 文件中 grep metabase-dashboard、metabase-question、metabase-browser
• grep window.metabaseConfig
• grep /app/embed.js（查找脚本标签）
• 读取 package.json（确认 React 依赖项并检测包管理器）
• 查找锁文件（yarn.lock、pnpm-lock.yaml、package-lock.json）
• npm view @metabase/embedding-sdk-react version（如果用户未指定目标版本）

所有工具调用都在同一条消息中发出。

第 2 轮——prepare.sh + 获取文档（并发）：

bash <skill-path>/scripts/prepare.sh {TARGET_VERSION}

下载目标 SDK npm 包并解压。输出 SDK_TMPDIR 和 d.ts 是否可用。

在同一条消息中，获取目标版本的 llms-embedding-full.txt（URL 格式见“允许的文档来源”）。

第 3 轮——read-sources.sh（单次 Bash 调用）：

bash <skill-path>/scripts/read-sources.sh {SDK_TMPDIR}

将目标 SDK 的 d.ts 类型定义输出到 stdout。

第 3 轮之后，输出步骤 1 结果 + 步骤 2 结果 + 步骤 3 迁移映射，不再进行任何工具调用。数据加载后立即内联生成步骤 3。

适用范围

此技能用于将 React 应用中使用的 Modular embedding（基于 Web Components）转换为 Modular embedding SDK（@metabase/embedding-sdk-react）。项目必须已经是 React 应用，且在 JSX/TSX 文件中使用了 Modular embedding Web Components。

如果项目并非基于 React，则此技能不适用。如果项目使用的是 iframe，而非 Web Components，请改用 metabase-full-app-to-modular-embedding-upgrade 技能。

此技能处理的内容

• 将 JSX/TSX 中的 <metabase-dashboard>、<metabase-question>、<metabase-browser> Web Components 替换为对应的 SDK React 组件
• 安装 @metabase/embedding-sdk-react npm 包
• 在 React 组件树的适当层级添加 <MetabaseProvider>
• 将 window.metabaseConfig 转换为 MetabaseProvider 配置属性
• 移除 embed.js <script> 标签（通常位于 index.html 或 HTML 入口文件中）
• 移除 window.metabaseConfig 赋值语句
• 将 HTML 属性命名（kebab-case）转换为 React 属性命名（camelCase）

此技能不处理的内容

• 在纯 HTML/模板中使用 Modular embedding Web Components 的非 React 项目

允许使用的文档来源

使用此 URL 获取特定版本的 llms-embedding-full.txt：

https://www.metabase.com/docs/v0.{VERSION}/llms-embedding-full.txt

URL 中的版本格式为 v0.58（规范化：去掉前导 v 或 0.，省略补丁版本号，例如 0.58.1 → 58 → URL 使用 v0.58）。此单个文件包含该版本的全部嵌入文档，并针对 LLM 阅读进行了优化。

其他限制：

• 不得使用 GitHub PR/issue 或 npm 页面
• 不得跳转到 GitHub 上的变更日志链接，也不得猜测 URL

检测版本

在第 1 轮中完成所有版本检测。

• Metabase 实例版本：搜索 Docker 镜像标签（metabase/metabase:v、metabase/metabase-enterprise:v）、METABASE_VERSION 或环境文件中的版本引用。如果未检测到，则使用 AskUserQuestion。
• 目标 SDK 版本：
  • 如果用户指定了版本，则使用该版本。
  • 否则，根据 Metabase 实例版本确定匹配的 SDK 版本（两者使用相同的版本方案：Metabase v0.58 → SDK 0.58.x）。运行 npm view @metabase/embedding-sdk-react version，以查找最新的匹配版本。
• 包管理器：根据锁文件检测，例如 yarn.lock → yarn，pnpm-lock.yaml → pnpm，package-lock.json → npm。

工作流前准备

迁移计划检查清单

创建检查清单以跟踪进度。在 Claude Code 中，使用 TaskCreate/TaskUpdate 工具：

• 步骤 0：先决条件检查
• 步骤 1：扫描 Modular embedding 用法
• 步骤 2：获取目标 SDK API
• 步骤 3：构建迁移映射
• 步骤 4：应用代码更改（每个文件创建一个子任务）
• 步骤 5：类型检查并修复问题
• 步骤 6：最终总结

工作流

步骤 0：先决条件检查

开始前进行验证：

1. React 依赖项：检查 package.json 的 dependencies 或 devDependencies 中是否包含 react。如果不存在，则标记为 ❌ 受阻——此技能仅适用于 React 项目。
2. JSX/TSX 中的 Web Components：确认第 1 轮的 grep 结果显示 .jsx、.tsx、.js 或 .ts 文件中使用了 <metabase-*（而非仅在纯 HTML 中）。如果 Web Components 仅出现在纯 HTML 文件中，则标记为 ❌ 受阻——此技能要求 React 中已经使用 Web Components。
3. Metabase 实例版本：检测版本或询问用户（参见上文“检测版本”部分）。
4. 目标 SDK 版本：按照“检测版本”中的说明确定。
5. 包管理器：根据锁文件检测。

步骤 1：扫描 Modular 嵌入用法

步骤 1 在第 1 轮进行——仅 grep，不读取文件。

并行 grep 以下模式：

• 在 *.{jsx,tsx,js,ts} 文件中查找 <metabase-dashboard——仪表板 Web 组件
• 在 *.{jsx,tsx,js,ts} 文件中查找 <metabase-question——问题 Web 组件
• 在 *.{jsx,tsx,js,ts} 文件中查找 <metabase-browser——集合浏览器 Web 组件
• 查找 window.metabaseConfig——全局配置赋值（可能位于 index.html 或 JS/TS 文件中）
• 查找 /app/embed.js——embed.js 脚本标签（通常位于 index.html 中）

这会返回文件路径和匹配行。暂时不要读取项目文件——这将在步骤 4 中进行。

输出：按类别分组的文件列表：

Web components (JSX/TSX):
  - src/pages/Dashboard.tsx:15 — <metabase-dashboard dashboard-id="123">
  - src/pages/Analytics.tsx:22 — <metabase-question question-id="456">
Config:
  - public/index.html:8 — window.metabaseConfig = { ... }
Script tag:
  - public/index.html:12 — <script defer src="...embed.js"></script>

步骤 2：获取目标 SDK API

在第 2 轮运行 prepare.sh（参见轮次预算）。然后在第 3 轮运行 read-sources.sh，将 d.ts 加载到上下文中。

如果 d.ts 可用，从中提取：

• 所有导出的 React 组件（例如 MetabaseProvider、仪表板/问题/集合组件）
• 它们的属性类型（解析为具体类型，而不只是别名名称）
• MetabaseProvider 配置类型（它接受哪些字段）
• 身份验证配置类型

第 2 轮获取的嵌入文档（llms-embedding-full.txt）可补充组件用法、配置选项和迁移指南。结合 d.ts 使用，全面了解相关信息。

如果 d.ts 不可用（0.52.0 之前的 SDK 版本不会提供单个 index.d.ts），则以嵌入文档作为主要 API 参考。如果 d.ts 和文档都不可用，则将步骤 2 标记为 ❌ blocked。

步骤 3：构建迁移映射（步骤 1–2 均 ✅ 完成后）

范围：仅映射步骤 1 扫描中实际发现的组件和配置。

生成涵盖以下内容的映射：

组件映射

对于步骤 1 中发现的每个 Web 组件，根据 d.ts 找出对应的 SDK React 组件。将属性映射为 props：

## Migration Mapping

### <metabase-dashboard> → {SDK dashboard component from d.ts}
- `dashboard-id` → `dashboardId` (camelCase)
- `with-title` → `withTitle` (boolean prop)
- `drills` → check d.ts for equivalent prop name
- Other attributes → map to corresponding React props from d.ts

### <metabase-question> → {SDK question component from d.ts}
- `question-id` → `questionId` (camelCase)
- Other attributes → map from d.ts

### <metabase-browser> → {SDK collection component from d.ts}
- `initial-collection` → check d.ts for prop name
- Other attributes → map from d.ts

对于每个映射，将目标 prop 类型解析为具体类型。如果某个属性没有对应的 SDK 项，则注明“已移除（SDK 不支持）”或“需要采用替代方案”。

身份验证配置映射

将 window.metabaseConfig 字段映射到 MetabaseProvider 配置：

### Auth & Config
- window.metabaseConfig.instanceUrl → config.metabaseInstanceUrl (check d.ts for exact field name)
- window.metabaseConfig.jwtProviderUri → authConfig.jwtProviderUri or authConfig.authProviderUri or config.authProviderUri (check d.ts — the field was renamed from `jwtProviderUri` to `authProviderUri` in some versions)
- window.metabaseConfig.locale → locale prop or config field (check d.ts)

d.ts 是字段名称的权威来源——不要猜测。如果 window.metabaseConfig 中的字段在 SDK 配置类型中没有对应项，请注明。

MetabaseProvider 的放置位置

确定应在何处添加 <MetabaseProvider>：

• 找出包含所有 Modular 嵌入 Web 组件的最高公共祖先组件
• 通常是应用根组件（App.tsx、App.jsx 或同等组件）
• provider 必须包裹所有 SDK 组件；但如果组件仅位于某个子树中，就不应不必要地包裹整个应用

移除计划

• embed.js <script> 标签：找出文件及要移除的确切代码
• window.metabaseConfig 赋值：找出文件及要移除的确切代码

步骤 4：应用代码更改

开始逐文件处理之前：

1. 安装 SDK 包：

   {package-manager} add @metabase/embedding-sdk-react@{TARGET_VERSION}
   

2. 移除 embed.js <script> 标签
3. 移除 window.metabaseConfig 赋值
4. 在确定的位置添加 <MetabaseProvider> 包装器，并使用迁移后的配置

逐文件任务（对每个包含 Web 组件的文件）：

1. 读取文件——首次加载文件内容。
2. 匹配映射条目——确认此文件中的 Web 组件及其当前属性。
3. 转换每个 Web 组件：
   • 将 Web 组件标签替换为 SDK React 组件
   • 将 HTML 属性（kebab-case）转换为 React props（camelCase）
   • 将字符串属性值转换为适当的 JS 类型（例如，"false" → {false}、"123" → {123}）
   • 添加 SDK 组件的导入语句
4. 报告——输出所做的更改。

并行化策略：

• ≤ 10 个文件：由主 Agent 处理全部文件。
• > 10 个文件：分配给 3–5 个子 Agent。每个子 Agent 接收其文件路径和完整的迁移映射。

类型转换规则

将 HTML 属性值转换为 React 属性时：

• 字符串 "true" / "false" → 布尔值 {true} / {false}
• 数字字符串 "123" → 数字 {123}
• JSX 中已有的模板表达式（例如 {dashboardId}）→ 保持原样
• 静态字符串 ID → 如果 d.ts 属性类型接受字符串，则保持为字符串；否则进行转换

步骤 5：类型检查验证

1. 运行类型检查 — npm run typecheck、tsc --noEmit 或项目的等效命令。
2. 分析错误 — 按根本原因对 SDK 相关错误进行分类。
3. 查找预期类型 — 在已安装的 node_modules/@metabase/embedding-sdk-react/dist/index.d.ts 中搜索每个报错的符号。
4. 批量修复 — 在重新运行类型检查前应用所有修复。
5. 验证 — 重新运行类型检查。如果 3 轮后仍有错误，标记为 ❌ 受阻。

如果项目未使用 TypeScript，请根据 d.ts 手动检查每项更改，确认属性名称和类型匹配。将步骤 5 标记为 ✅，并注明验证是手动完成的。

步骤 6：输出摘要

整理为以下部分：

1. 已应用的更改 — 列出所有已修改的文件，并用一句话说明每项更改。

2. 组件映射 — 表格列出每个旧版 Web 组件 → 新版 React 组件：

| File | Old | New | Props Changed |
|---|---|---|---|
| src/Dashboard.tsx | <metabase-dashboard dashboard-id="1"> | <InteractiveDashboard dashboardId={1} /> | dashboard-id → dashboardId |

3. 身份验证迁移 — 说明如何将 window.metabaseConfig 转换为 MetabaseProvider 配置。

4. 已移除的产物 — embed.js 脚本标签、window.metabaseConfig 及任何无用代码。

5. 新功能 — 简要说明现在可用、但 Modular embedding 中没有的 SDK 功能（例如 React hooks、类型化回调、InteractiveQuestion.FilterBar 等子组件）。

6. 实例要求 — 所需的最低 Metabase 实例版本。Metabase 实例版本必须与 SDK 版本匹配（例如，SDK 0.58.x 要求 Metabase v0.58+）。

重试策略

文档获取：

• 如果获取 llms-embedding-full.txt 时返回 404，请验证 Metabase 版本号并重试。如果仍然失败，则在没有文档的情况下继续（d.ts 是主要依据）。

npm pack：

• 如果针对目标版本运行 npm pack 失败，则该版本可能不存在于 npm 上。标记为 ❌ 受阻并告知用户。

npm install：

• 如果由于 peer dependency 冲突导致软件包安装失败，请尝试使用 --legacy-peer-deps（npm）或等效选项。向用户报告冲突。