metabase-modular-embedding-version-upgrade

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Execution contract

执行约定

Follow the workflow steps in order — do not skip any step. Create the checklist first, then execute each step and explicitly mark it done with evidence. Each step's output feeds into the next, so skipping steps produces wrong migrations.

If you cannot complete a step due to missing info or tool failure, you must:

record the step as ❌ blocked,
explain exactly what is missing / what failed,
stop (do not proceed to later steps).

请按顺序执行工作流程步骤——请勿跳过任何步骤。首先创建检查清单，然后执行每个步骤并明确标记完成状态及相关依据。每个步骤的输出会作为下一个步骤的输入，因此跳过步骤会导致错误的迁移结果。

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

将该步骤标记为 ❌ 受阻，
准确说明缺失的信息或故障原因，
停止操作（请勿继续后续步骤）。

Required output structure

要求的输出结构

Your response should contain these sections in this order:

Step 0: Upgrade Plan Checklist
Step 1 Results: Project Scan
Step 2 Results: d.ts Diff / Target Docs (primary or fallback)
Step 3: Change Catalog
Step 4: Per-File Migration (one subsection per file)
Step 5: Typecheck Validation
Step 6: Final Summary

Each step section should end with a status line:

```
Status: ✅ complete
```
or
```
Status: ❌ blocked
```

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

步骤0：升级计划检查清单
步骤1结果：项目扫描
步骤2结果：d.ts差异/目标文档（主路径或备用路径）
步骤3：变更目录
步骤4：逐文件迁移（每个文件对应一个子部分）
步骤5：类型检查验证
步骤6：最终总结

每个步骤部分末尾应包含状态行：

```
Status: ✅ complete
```
或
```
Status: ❌ blocked
```

Evidence requirements

依据要求

Step 1: list every matched file path and the matching grep lines (SDK imports or Modular embedding API calls/script tags). Full file analysis happens in Step 4.
Step 2 (primary path): show the diff output between d.ts files. (hybrid/fallback path): list each fetched URL + confirm files are loaded in context. Do not analyze or resolve types here — that's Step 3's job.
Step 3: the structured change catalog — every changed/removed/added symbol with its fully resolved concrete type.
Step 4: per file — SDK/Modular embedding usage found (components, props, config options, callbacks, data flows), which catalog entries affect this file, invalid usages found, exact diffs applied.
Step 5: the exact command run and error summary if any remain.

步骤1：列出所有匹配的文件路径及对应的grep匹配行（SDK导入或模块化嵌入API调用/脚本标签）。完整的文件分析在步骤4中进行。
步骤2（主路径）：展示d.ts文件之间的差异输出。（混合/备用路径）：列出每个获取的URL并确认文件已加载到上下文环境中。请勿在此处分析或解析类型——这是步骤3的工作。
步骤3：结构化的变更目录——每个已变更/已移除/已添加的符号及其完全解析的具体类型。
步骤4：逐文件——找到的SDK/模块化嵌入用法（组件、属性、配置选项、回调函数、数据流），哪些目录条目影响该文件，发现的无效用法，应用的具体差异。
步骤5：执行的具体命令及（若有）错误摘要。

Performance

性能

The workflow is designed as a pipeline that maximizes parallelism:

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

In Claude Code, use parallel tool calls or

run_in_background: true

for sub-agents.

Do not parse repo branches, commits, PRs, or issues — they're noisy and irrelevant to version diffing.

该工作流程设计为最大化并行性的流水线：

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

在Claude Code中，对子代理使用并行工具调用或

run_in_background: true

。

请勿解析仓库分支、提交记录、PR或问题——这些内容杂乱且与版本差异无关。

Tool-call round budget for Steps 1+2

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

Steps 1+2 must complete in 3 tool-call rounds.

Round 1 — discovery (all concurrent, single message):

Grep for
```
@metabase/embedding-sdk-react
```
imports (returns file paths — do not read files yet)

Glob for lock files (

yarn.lock

pnpm-lock.yaml

package-lock.json

)

Read
```
package.json
```
(for current version)

npm view @metabase/embedding-sdk-react version

(if target not specified by user)

All four tool calls in ONE message.

Round 2 —

prepare.sh

+ fetch docs (concurrent):

bash

bash <skill-path>/scripts/prepare.sh {CURRENT} {TARGET} --sdk

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

第1轮——发现阶段（所有操作并发，单条消息）：

搜索
```
@metabase/embedding-sdk-react
```
导入语句（返回文件路径——暂不读取文件）

匹配锁文件（

yarn.lock

pnpm-lock.yaml

package-lock.json

）

读取
```
package.json
```
（获取当前版本）

npm view @metabase/embedding-sdk-react version

（若用户未指定目标版本）

以上四个工具调用放在同一条消息中。

第2轮——

prepare.sh

+ 获取文档（并发）：

bash

bash <skill-path>/scripts/prepare.sh {CURRENT} {TARGET} --sdk

or for Modular embedding (embed.js):

或针对模块化嵌入（embed.js）：

bash <skill-path>/scripts/prepare.sh {CURRENT} {TARGET} --embedjs

Always pass `--sdk` or `--embedjs` to indicate the embedding type. The script does: npm pack both versions (SDK only), check d.ts, and fetch+truncate changelog. It outputs `SDK_TMPDIR` and d.ts availability.

In the same message, fetch `llms-embedding-full.txt` for both the current and target versions (see "Allowed documentation sources" for URL format).

**Round 3** — `read-sources.sh` (single Bash call — reference data only, no project files):
```bash
bash <skill-path>/scripts/read-sources.sh {SDK_TMPDIR}

Dumps SDK reference data (d.ts diff or raw d.ts, changelog) to stdout. Does not read project files — those are read one by one in Step 4.

After Round 3, output Step 1 Results (file list from grep) + Step 2 Results + Step 3 Change Catalog with zero additional tool calls. Do not treat Step 3 as a separate thinking phase — produce it inline right after the data is loaded.

bash <skill-path>/scripts/prepare.sh {CURRENT} {TARGET} --embedjs

始终传递`--sdk`或`--embedjs`以指明嵌入类型。该脚本会执行：npm打包两个版本（仅SDK），检查d.ts，获取并截断变更日志。输出`SDK_TMPDIR`和d.ts可用性。

在同一条消息中，获取当前版本和目标版本的`llms-embedding-full.txt`（请查看“允许的文档来源”了解URL格式）。

**第3轮**——`read-sources.sh`（单次Bash调用——仅参考数据，不涉及项目文件）：
```bash
bash <skill-path>/scripts/read-sources.sh {SDK_TMPDIR}

将SDK参考数据（d.ts差异或原始d.ts、变更日志）输出到标准输出。不读取项目文件——这些文件会在步骤4中逐个读取。

第3轮完成后，输出步骤1结果（来自grep的文件列表）+ 步骤2结果 + 步骤3变更目录，无需额外工具调用。请勿将步骤3视为单独的思考阶段——数据加载完成后直接生成该内容。

Scope

范围

This skill handles upgrades for:

```
@metabase/embedding-sdk-react
```
(React SDK, v52+) — uses primary or fallback path
Modular embedding via embed.js (v56+) — always uses fallback path (no npm types available)
- v56–v57: docs are at
```
embedded-analytics-js.md
```
- v58+: docs split into
```
components.md
```
  ,
```
appearance.md
```
  ,
```
authentication.md
```

本技能处理以下升级场景：

```
@metabase/embedding-sdk-react
```
（React SDK，v52+）——使用主路径或备用路径
通过embed.js实现的模块化嵌入（v56+）——始终使用备用路径（无npm类型可用）
- v56–v57：文档位于
```
embedded-analytics-js.md
```
- v58+：文档拆分为
```
components.md
```
  ,
```
appearance.md
```
  ,
```
authentication.md
```

What this skill does not handle

本技能不处理的场景

Migrating between different embedding technologies

不同嵌入技术之间的迁移

Allowed documentation sources

允许的文档来源

Fetch the version-specific

llms-embedding-full.txt

using this URL:

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

The version in the URL uses the format

v0.58

(normalize: strip leading

0.

, drop patch — e.g.,

0.58.1

→

→ URL uses

v0.58

). This single file contains all embedding documentation for that version, optimized for LLM consumption.

Other constraints:

No GitHub PRs/issues or npm pages
Do not follow changelog links to GitHub or guess URLs

使用以下URL获取特定版本的

llms-embedding-full.txt

：

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

URL中的版本格式为

v0.58

（标准化：去除前导的

或

0.

，移除补丁版本——例如

0.58.1

→

→ URL使用

v0.58

）。该文件包含该版本的所有嵌入文档，已针对LLM进行优化。

其他限制：

不允许使用GitHub PR/问题或npm页面
请勿跟随变更日志链接跳转到GitHub或猜测URL

Detecting versions

版本检测

Do all version detection in Round 1 (see tool-call round budget) — not as a separate pre-step.

Current version: read from the project's
```
package.json
```
(check
```
dependencies
```
and
```
devDependencies
```
) for
```
@metabase/embedding-sdk-react
```
. In monorepos, also check workspace-level
```
package.json
```
files.
Target version:
- If user specifies, use it.
- Otherwise run
```
npm view @metabase/embedding-sdk-react version
```
  — include this in Round 1's concurrent tool calls.
Package manager: detect from lock files —
```
yarn.lock
```
→ yarn,
```
pnpm-lock.yaml
```
→ pnpm,
```
package-lock.json
```
→ npm. Use the matching install command in Step 4 (e.g.,
```
yarn install
```
,
```
pnpm install
```
).

If package not present OR user is upgrading Modular embedding (embed.js):

Ask the user for the current and target Metabase instance versions. Modular embedding (embed.js) is served from the Metabase instance, so its version matches the instance version. In Claude Code, use the AskUserQuestion tool for this.
Mark Step 0 ❌ blocked until answered.

所有版本检测在第1轮完成（请查看工具调用轮次预算）——不作为单独的前置步骤。

当前版本：从项目的
```
package.json
```
（检查
```
dependencies
```
和
```
devDependencies
```
）中读取
```
@metabase/embedding-sdk-react
```
的版本。在单体仓库中，还需检查工作区级别的
```
package.json
```
文件。
目标版本：
- 若用户指定，则使用该版本。
- 否则运行
```
npm view @metabase/embedding-sdk-react version
```
  ——将此操作包含在第1轮的并发工具调用中。
包管理器：通过锁文件检测——
```
yarn.lock
```
→ yarn，
```
pnpm-lock.yaml
```
→ pnpm，
```
package-lock.json
```
→ npm。在步骤4中使用匹配的安装命令（例如
```
yarn install
```
,
```
pnpm install
```
）。

若包不存在或用户正在升级模块化嵌入（embed.js）：

询问用户当前和目标Metabase实例版本。模块化嵌入（embed.js）由Metabase实例提供服务，因此其版本与实例版本一致。在Claude Code中，使用AskUserQuestion工具完成此操作。
将步骤0标记为 ❌ 受阻，直至用户答复。

Multi-version hops

跨版本跳跃

When the upgrade spans a major structural boundary (e.g., v0.54 → v0.58 crosses the auth config change at v0.55 AND the doc layout change at v0.58), handle it as a single migration to the target version — do not do intermediate upgrades. However, during Step 3, check the auth config evolution section and account for every breaking change along the path. For example, v0.52 → v0.58 means the auth config changed shape (v0.55) AND gained

jwtProviderUri

(v0.58) — both changes need to be reflected in the migration.

当升级跨越主要结构边界时（例如v0.54 → v0.58跨越了v0.55的认证配置变更以及v0.58的文档布局变更），将其作为一次迁移到目标版本的操作——无需进行中间版本升级。但在步骤3中，需检查认证配置演变部分，并考虑路径上的每一项破坏性变更。例如，v0.52 → v0.58意味着认证配置的结构发生了变化（v0.55）并且新增了

jwtProviderUri

（v0.58）——这两项变更都需要在迁移中体现。

Pre-workflow steps

工作流前置步骤

Upgrade Plan Checklist (required before any other work)

升级计划检查清单（开始任何工作前必须完成）

Create a checklist to track progress. In Claude Code, use TaskCreate/TaskUpdate tools:

Step 1: Scan project usage
Step 2: Extract d.ts diff or fetch docs
Step 3: Build change catalog
Step 4: Per-file migrate (one sub-task per file)
Step 5: Typecheck and fix
Step 6: Final summary

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

步骤1：扫描项目用法
步骤2：提取d.ts差异或获取文档
步骤3：构建变更目录
步骤4：逐文件迁移（每个文件对应一个子任务）
步骤5：类型检查与修复
步骤6：最终总结

Path Selection

路径选择

Determine which path to use:

If upgrading
```
@metabase/embedding-sdk-react
```
→ attempt primary path (d.ts diff), with fallback if d.ts unavailable (determined during Step 2)
If upgrading Modular embedding (embed.js) → fallback path (skip d.ts extraction entirely)

确定要使用的路径：

若升级
```
@metabase/embedding-sdk-react
```
→ 尝试主路径（d.ts差异），若d.ts不可用则使用备用路径（在步骤2中确定）
若升级模块化嵌入（embed.js） → 备用路径（完全跳过d.ts提取）

Workflow

工作流程

Step 1: Scan the project code

步骤1：扫描项目代码

Keep scan results in the main context (not delegated to a sub-agent) — Step 3 needs them for cross-referencing.

For SDK upgrades (
@metabase/embedding-sdk-react
):

Step 1 happens in Round 1 — grep only, no file reading.

Grep for all imports from
```
@metabase/embedding-sdk-react
```
. This returns file paths + matching import lines.
Also detect the package manager (glob for lock files).
Output: a file list with the SDK imports visible from grep output.

For Modular embedding (embed.js) upgrades:

There is no npm package to grep. Instead, search the codebase for:
- Metabase embed
```
<script>
```
  tags (e.g., patterns like
```
metabase.js
```
  ,
```
embed.js
```
  ,
```
embedding-sdk
```
  , or the Metabase instance URL)
- Any JS calls to Metabase embedding APIs (e.g.,
```
MetabaseEmbed
```
  ,
```
Metabase.embed
```
  ,
```
window.MetabaseEmbed
```
  ,
```
initMetabase
```
  , component init calls)
Output: a file list with the matching grep lines.

将扫描结果保存在主上下文中（不委托给子代理）——步骤3需要这些结果进行交叉引用。

针对SDK升级（
@metabase/embedding-sdk-react
）：

步骤1在第1轮完成——仅执行grep搜索，不读取文件。

搜索所有来自
```
@metabase/embedding-sdk-react
```
的导入语句。返回文件路径+匹配的导入行。
同时检测包管理器（匹配锁文件）。
输出：包含SDK导入语句的文件列表（来自grep输出）。

针对模块化嵌入（embed.js）升级：

没有npm包可供搜索。相反，在代码库中搜索：
- Metabase嵌入
```
<script>
```
  标签（例如
```
metabase.js
```
  ,
```
embed.js
```
  ,
```
embedding-sdk
```
  或Metabase实例URL等模式）
- 任何对Metabase嵌入API的JS调用（例如
```
MetabaseEmbed
```
  ,
```
Metabase.embed
```
  ,
```
window.MetabaseEmbed
```
  ,
```
initMetabase
```
  , 组件初始化调用）
输出：包含匹配grep行的文件列表。

Step 2: Extract API changes

步骤2：提取API变更

Run

prepare.sh

in Round 2 (see round budget). The script outputs:

```
SDK_TMPDIR
```
— temp directory with both SDK packages (pass this to
```
read-sources.sh
```
in Round 3)
```
current_dts=yes/no
```
,
```
target_dts=yes/no
```
— d.ts availability (for informational output)
```
DTS_DIFF_PATH
```
— d.ts diff file (if both versions have d.ts)
```
CURRENT_DTS_PATH
```
/
```
TARGET_DTS_PATH
```
— raw d.ts paths (hybrid mode only)

You don't need to read these files manually —

read-sources.sh

handles it.

在第2轮运行

prepare.sh

（请查看轮次预算）。该脚本输出：

```
SDK_TMPDIR
```
——包含两个SDK包的临时目录（将其传递给第3轮的
```
read-sources.sh
```
）
```
current_dts=yes/no
```
,
```
target_dts=yes/no
```
——d.ts可用性（用于信息输出）
```
DTS_DIFF_PATH
```
——d.ts差异文件（若两个版本都有d.ts）
```
CURRENT_DTS_PATH
```
/
```
TARGET_DTS_PATH
```
——原始d.ts路径（仅混合模式）

您无需手动读取这些文件——

read-sources.sh

会处理它们。

Step 3: Build change catalog (after Steps 1–2 are ✅ complete)

步骤3：构建变更目录（步骤1–2完成✅后）

Scope: only catalog changes that affect symbols visible in Step 1's grep output. For example, if the grep shows imports of

MetabaseProvider

InteractiveQuestion

, and

CollectionBrowser

, only catalog changes to those components and their props/types/callbacks. Skip changes to components the project doesn't import.

From the d.ts diff, docs comparison, and changelog, extract changes into a catalog:

Removed exports/props/types
Renamed symbols (old name → new name)
Type-changed props — resolve every type alias to its concrete type. Do not stop at alias names — aliases can stay the same while the underlying type changes. For example,
```
SdkCollectionId
```
may have been
```
number
```
in the current version but
```
number | "personal" | "root" | "tenant" | SdkEntityId
```
in the target.
Signature-changed functions/callbacks (arity, argument types, return types)
Added props/exports (only for components in Step 1's grep output, for informational output)
Deprecated APIs (with recommended replacements)
Auth config changes — pay special attention. The changelog and docs contain the specifics. Look for: type renames,
```
fetchRequestToken
```
signature changes, and new properties like
```
jwtProviderUri
```
.

范围：仅记录影响步骤1中grep输出可见符号的变更。例如，若grep显示导入了

MetabaseProvider

、

InteractiveQuestion

和

CollectionBrowser

，则仅记录这些组件及其属性/类型/回调函数的变更。跳过项目未导入的组件的变更。

从d.ts差异、文档对比和变更日志中提取变更并整理为目录：

已移除的导出/属性/类型
已重命名的符号（旧名称→新名称）
类型变更的属性——将每个类型别名解析为其具体类型。不要停留在别名名称上——别名可能保持不变但底层类型已变更。例如，
```
SdkCollectionId
```
在当前版本中可能是
```
number
```
，但在目标版本中是
```
number | "personal" | "root" | "tenant" | SdkEntityId
```
。
签名变更的函数/回调函数（参数数量、参数类型、返回类型）
已添加的属性/导出（仅针对步骤1中grep输出的组件，用于信息输出）
已废弃的API（含推荐替代方案）
认证配置变更——需特别注意。变更日志和文档中包含具体细节。查找：类型重命名、
```
fetchRequestToken
```
签名变更以及新增属性如
```
jwtProviderUri
```
。

Catalog format

目录格式

undefined

undefined

Change Catalog (v0.54 → v0.58)

变更目录（v0.54 → v0.58）

fetchRequestToken

Change: signature changed
Old:
```
(url: string) => Promise<any>
```

New:

() => Promise<{jwt: string}>

(resolved from

MetabaseFetchRequestTokenFn

)

Severity: 🔴 Breaking

变更：签名变更
旧：
```
(url: string) => Promise<any>
```

新：

() => Promise<{jwt: string}>

（从

MetabaseFetchRequestTokenFn

解析）

严重程度：🔴 破坏性

SdkCollectionId (type widening)

SdkCollectionId（类型拓宽）

Change: type widened
Old:
```
number
```

New:

number | "personal" | "root" | "tenant" | SdkEntityId

Affects: any prop/callback param typed as
```
SdkCollectionId
```
, including
```
item.id
```
in CollectionBrowser callbacks
Severity: 🔴 Breaking for code storing in
```
number
```
-typed variables

变更：类型拓宽
旧：
```
number
```

新：

number | "personal" | "root" | "tenant" | SdkEntityId

影响：所有类型为
```
SdkCollectionId
```
的属性/回调参数，包括CollectionBrowser回调中的
```
item.id
```
严重程度：🔴 对存储在
```
number
```
类型变量中的代码具有破坏性

SdkDashboardId (type widening)

SdkDashboardId（类型拓宽）

Change: type widened
Old:
```
number
```
New:
```
number | string | SdkEntityId
```
Affects: any prop/callback param typed as
```
SdkDashboardId
```
Severity: 🔴 Breaking for code storing in
```
number
```
-typed variables

变更：类型拓宽
旧：
```
number
```
新：
```
number | string | SdkEntityId
```
影响：所有类型为
```
SdkDashboardId
```
的属性/回调参数
严重程度：🔴 对存储在
```
number
```
类型变量中的代码具有破坏性

jwtProviderUri

Change: new property added to
```
MetabaseProvider
```
authConfig
Severity: 🟢 Info — can replace manual
```
fetchRequestToken
```

变更：
```
MetabaseProvider
```
的authConfig新增属性
严重程度：🟢 信息——可替代手动
```
fetchRequestToken
```

questionHeight

Change: new optional prop on
```
StaticQuestion
```
Severity: 🟢 Info


The catalog is the input for Step 4. It must include fully resolved concrete types — Step 4 sub-agents need them to assess compatibility without re-reading the d.ts.

变更：
```
StaticQuestion
```
新增可选属性
严重程度：🟢 信息


该目录是步骤4的输入。必须包含完全解析的具体类型——步骤4的子代理需要这些类型来评估兼容性，无需重新读取d.ts。

Step 4: Per-file migrate (parallel)

步骤4：逐文件迁移（并行）

Each project file is analyzed and fixed independently against the change catalog. This is the main parallelization point.

Before per-file work: update package.json version and install dependencies. Also update Metabase instance version in docker files if present (docker-compose.yml, Dockerfile, .env). These are done once, not per-file.

Per-file task (for each file from the Step 1 file list):

For each file, a single pass that combines read + analysis + fix:

Read the file — this is the first time the file content is loaded. Extract SDK components, hooks, types, props used, dot-subcomponents (e.g.,
```
<InteractiveQuestion.Title />
```
,
```
<InteractiveQuestion.FilterBar />
```
), and callback data flows.
Match catalog entries — which changes from the catalog affect this file's usage?
Validate current usage against target API — even if there are no breaking changes between the two versions, the file may already be using invalid prop names, wrong attribute names, non-existent component names, or incorrect signatures. Compare every usage in the file against the target version's API (d.ts or docs) and flag anything that doesn't match. This catches pre-existing errors that the upgrade won't fix automatically — especially common in JS-only projects and EmbedJS integrations where there's no typechecker to catch mistakes.
Deep analysis — for each catalog match or invalid usage:
- Compare the file's current usage against the catalog's target type
- For callback props: trace where callback parameter fields flow in THIS file (state setters, variables, API calls, route params). Check if the receiving type is compatible with the target's potentially widened type. For example, if
```
onClick: (item) => setSelectedId(item.id)
```
  and the catalog says
```
item.id
```
  widened from
```
number
```
  to
```
SdkCollectionId
```
  , and
```
setSelectedId
```
  is
```
useState<number>
```
  , flag it as breaking.
Apply fixes — edit the file to migrate all breaking changes and correct any invalid usages.
Report — output what was found and changed for this file.

Parallelization strategy:

≤ 10 files: process all in the main agent — read each file, match catalog, fix, move to next.
> 10 files: batch files into 3–5 sub-agents (evenly split). Each sub-agent receives its file paths and the full change catalog, reads each file, applies fixes, and reports. In Claude Code, launch with
```
run_in_background: true
```
.

每个项目文件都会根据变更目录独立进行分析和修复。这是主要的并行化点。

逐文件工作前： 更新package.json版本并安装依赖。若存在docker文件（docker-compose.yml、Dockerfile、.env），同时更新Metabase实例版本。这些操作仅执行一次，无需逐文件进行。

逐文件任务（针对步骤1文件列表中的每个文件）：

对每个文件执行单次遍历，结合读取+分析+修复：

读取文件——这是首次加载文件内容。提取使用的SDK组件、钩子、类型、属性、点分组件（例如
```
<InteractiveQuestion.Title />
```
,
```
<InteractiveQuestion.FilterBar />
```
）以及回调数据流。
匹配目录条目——目录中的哪些变更会影响该文件的用法？
验证当前用法与目标API的兼容性——即使两个版本之间没有破坏性变更，文件可能已经在使用无效的属性名称、错误的属性名、不存在的组件名称或不正确的签名。将文件中的每个用法与目标版本的API（d.ts或文档）进行比较，并标记所有不匹配的内容。这可以捕获升级无法自动修复的预先存在的错误——在纯JS项目和EmbedJS集成中尤为常见，因为这些项目没有类型检查器来发现错误。
深度分析——针对每个目录匹配项或无效用法：
- 将文件的当前用法与目录中的目标类型进行比较
- 对于回调属性：跟踪回调参数字段在该文件中的流向（状态设置器、变量、API调用、路由参数）。检查接收类型是否与目标可能拓宽的类型兼容。例如，若
```
onClick: (item) => setSelectedId(item.id)
```
  且目录显示
```
item.id
```
  从
```
number
```
  拓宽为
```
SdkCollectionId
```
  ，而
```
setSelectedId
```
  是
```
useState<number>
```
  ，则标记为破坏性变更。
应用修复——编辑文件以迁移所有破坏性变更并纠正任何无效用法。
报告——输出该文件中发现的问题及所做的变更。

并行化策略：

≤10个文件：在主代理中处理所有文件——读取每个文件、匹配目录、修复、处理下一个文件。
>10个文件：将文件分批分配给3–5个子代理（均匀拆分）。每个子代理接收其文件路径和完整变更目录，读取每个文件、应用修复并报告。在Claude Code中，使用
```
run_in_background: true
```
启动子代理。

Per-file output example

逐文件输出示例

undefined

undefined

src/components/CollectionPage.tsx

Catalog matches:

目录匹配项：

SdkCollectionId type widening → affects
```
onClick
```
callback
(no other catalog entries match this file)

SdkCollectionId类型拓宽 → 影响
```
onClick
```
回调
（无其他目录条目匹配该文件）

Analysis:

分析：

onClick: (item) => setSelectedId(item.id)

```
item.id
```
is now
```
SdkCollectionId
```
(number | "personal" | "root" | "tenant" | SdkEntityId)

setSelectedId

useState<number | undefined>[1]

🔴 BREAKING: string variants won't fit
```
number
```
state

```
onClick: (item) => setSelectedId(item.id)
```
- ```
item.id
```
  现在是
```
SdkCollectionId
```
  （number | "personal" | "root" | "tenant" | SdkEntityId）
- ```
setSelectedId
```
  是
```
useState<number | undefined>[1]
```
- 🔴 破坏性：字符串变体无法适配
```
number
```
  类型状态

Fix applied:

应用的修复：

Widened state:

useState<number | undefined>

→

useState<SdkCollectionId | undefined>

Added import:

import type { SdkCollectionId } from '@metabase/embedding-sdk-react'

Status: ✅ complete

undefined

拓宽状态类型：

useState<number | undefined>

→

useState<SdkCollectionId | undefined>

添加导入：

import type { SdkCollectionId } from '@metabase/embedding-sdk-react'

Status: ✅ complete

undefined

Step 5: Validate typecheck (batch fix)

步骤5：验证类型检查（批量修复）

For SDK upgrades (TypeScript projects):

Run typecheck once — run the project's typecheck command (e.g.,
```
npm run typecheck
```
,
```
tsc --noEmit
```
, or the equivalent for the project's build tool).
Analyze ALL errors at once — read the full error output and categorize every SDK-related error by root cause (e.g., "removed prop", "changed type signature", "renamed export"). Errors that share a root cause get fixed together.
Look up expected types — for each distinct failing symbol, search
```
node_modules/@metabase/embedding-sdk-react/dist/index.d.ts
```
to understand the target type. Do all lookups before making any fixes — this prevents back-and-forth between reading and editing.
Apply ALL fixes in one batch — fix every error across all files before re-running typecheck. In Claude Code, issue all Edit calls in a single message where possible.
Verify with one final typecheck run — re-run the typecheck command. If new errors appear (e.g., a fix introduced a secondary issue), apply another batch and re-run. If errors remain after 3 batch rounds, mark Step 5 ❌ blocked and report which errors could not be resolved.

For SDK upgrades (plain JavaScript projects):

No typechecker available. Instead, manually review each change from Step 4 against the target SDK's API:
- Verify function signatures match (argument count, return types)
- Verify prop names and values match the target version's expectations
- Check for renamed imports or removed exports
Mark Step 5 ✅ complete with a note that validation was manual (no TypeScript).

For Modular embedding (embed.js) upgrades:

There are no npm types to typecheck. Instead:
- If the project uses TypeScript, run the typecheck command to catch any general TS errors introduced by the migration.
- If the project is plain JavaScript, skip typechecking. Instead, manually review that all changed embed configuration objects match the target version's documented options.
Mark Step 5 ✅ complete with a note on which validation was performed.

针对SDK升级（TypeScript项目）：

运行一次类型检查——执行项目的类型检查命令（例如
```
npm run typecheck
```
,
```
tsc --noEmit
```
或项目构建工具的等效命令）。
一次性分析所有错误——读取完整的错误输出，并按根本原因对所有SDK相关错误进行分类（例如“已移除属性”、“类型签名变更”、“导出重命名”）。具有相同根本原因的错误将一起修复。
查找预期类型——针对每个不同的失败符号，搜索
```
node_modules/@metabase/embedding-sdk-react/dist/index.d.ts
```
以了解目标类型。在进行任何修复前完成所有查找——这可以避免在读取和编辑之间来回操作。
一次性应用所有修复——在重新运行类型检查前修复所有文件中的所有错误。在Claude Code中，尽可能在单条消息中发出所有编辑调用。
通过最终一次类型检查运行验证——重新运行类型检查命令。若出现新错误（例如修复引入了次要问题），则应用另一批修复并重新运行。若经过3批修复后仍有错误，则将步骤5标记为 ❌ 受阻并报告无法解决的错误。

针对SDK升级（纯JavaScript项目）：

无类型检查器可用。取而代之，手动对照目标SDK的API检查步骤4中的每个变更：
- 验证函数签名是否匹配（参数数量、返回类型）
- 验证属性名称和值是否符合目标版本的预期
- 检查是否有重命名的导入或已移除的导出
将步骤5标记为 ✅ 完成，并注明验证为手动进行（无TypeScript）。

针对模块化嵌入（embed.js）升级：

无npm类型可用于类型检查。取而代之：
- 若项目使用TypeScript，运行类型检查命令以捕获迁移引入的任何常规TS错误。
- 若项目是纯JavaScript，跳过类型检查。取而代之，手动检查所有变更的嵌入配置对象是否与目标版本的文档选项匹配。
将步骤5标记为 ✅ 完成，并注明执行的验证类型。

Step 6: Output summary

步骤6：输出总结

Organize into these sections:

1. Breaking changes fixed — list each breaking change with severity and what was done:

🔴 Breaking (would cause build/runtime errors): e.g., "Migrated
```
fetchRequestToken
```
from 1-arg to 0-arg signature"
🟡 Deprecation (works now, will break later): e.g., "
```
appearance
```
prop renamed to
```
theme
```
— updated"

2. Deprecation warnings — APIs that still work but are marked deprecated in the target version. Include the recommended replacement so the user can plan future changes.

3. New features available — relevant new APIs or options in the target version that the project could benefit from (e.g.,

jwtProviderUri

replacing manual

fetchRequestToken

). Keep brief — just flag them, don't advocate.

4. Instance requirements — minimum Metabase instance version needed for the target SDK version. If the project has docker-compose or similar files, note whether the instance version was also updated.

5. Technical details — path used (primary d.ts diff / hybrid / fallback docs), versions upgraded (from → to), package manager used.

整理为以下部分：

1. 已修复的破坏性变更——列出每个破坏性变更及其严重程度和处理方式：

🔴 破坏性（会导致构建/运行时错误）：例如“将
```
fetchRequestToken
```
从1参数签名迁移为0参数签名”
🟡 废弃（当前可用，未来会失效）：例如“
```
appearance
```
属性重命名为
```
theme
```
——已更新”

2. 废弃警告——在目标版本中已标记为废弃但仍可用的API。包含推荐替代方案，以便用户规划未来变更。

3. 可用的新功能——目标版本中与项目相关的新API或选项（例如

jwtProviderUri

替代手动

fetchRequestToken

）。保持简洁——仅标记这些功能，无需推荐。

4. 实例要求——目标SDK版本所需的最低Metabase实例版本。若项目有docker-compose或类似文件，注明实例版本是否已更新。

5. 技术细节——使用的路径（主d.ts差异/混合/备用文档）、升级的版本（从→到）、使用的包管理器。

Retry policy

重试策略

URL fetches:

If fetching
```
llms-embedding-full.txt
```
returns 404, the version's docs may not exist — skip silently.
For other errors (5xx, timeout, network): retry once immediately. If still failing, mark that step ❌ blocked and stop.

npm pack:

If
```
npm pack
```
fails for a version, the version likely doesn't exist on npm. Mark as ❌ blocked and inform the user.

URL获取：

若获取
```
llms-embedding-full.txt
```
返回404，该版本的文档可能不存在——静默跳过。
对于其他错误（5xx、超时、网络问题）：立即重试一次。若仍失败，则将该步骤标记为 ❌ 受阻并停止。

npm打包：

若某个版本的
```
npm pack
```
失败，该版本可能在npm上不存在。标记为 ❌ 受阻并通知用户。