元数据库完整应用程序到模块化嵌入升级
- 作者仓库星标 19
- 作者仓库 agent-skills
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @metabase · 未声明许可证
- 上下文用量评级
- 较高消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- Docker
- 运行环境要求
- Node.js · Python · Docker
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 读取环境变量
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
始终向用户询问元数据库实例版本的问题 - 即使版本出现在 Docker 标签或环境变量中,也要与用户确认。 如果 v52 或更早版本则中止(v53 中引入了模块化嵌入)。
同时执行项目扫描和文档获取——它们是独立的。只要不存在依赖关系,就可以在单个消息中使用并行工具调用。 1a:获取目标版本文档 获取目标版本的 `llms-embedding-full.txt`(有关 URL 格式,请参阅“允许的文档源”)。这些文档是目标版本的 Web 组件属性、`window.metabaseConfig` 选项和 SSO 端点行为的权威来源。在步骤 2 中使用它们进行映射,而不是仅仅依赖于硬编码表。
使用步骤 1a 中获取的文档作为 Web 组件属性、`window.metabaseConfig` 选项和 SSO 端点行为的权威参考。下面的硬编码表是后备方案 - 如果文档描述了目标版本的附加属性或不同行为,则更喜欢文档。对于步骤 1 中找到的每个 iframe: 2a:解析 iframe URL 从 iframe `src` 属性提取(可以是模板表达式、变量或文字):
创建涵盖以下所有领域的完整的逐个文件变更计划。每次更改都应指定目标文件、旧代码和新代码。 3a:embed.js 脚本注入 - 每个应用程序仅一次目标:步骤 1e 中标识的布局/头文件位置:`<head>`内部(或尽可能靠近其他`<script>`标签)要添加的代码:
按此顺序应用步骤 3 中的所有更改(首先进行后端更改,以最小化出现问题的窗口): 第一:修改 SSO 端点以返回 JSON(步骤 3c)——这仅适用于后端 第二:将 `window.metabaseConfig` 分配和 embed.js 脚本标记添加到布局/头文件中(步骤 3b + 3a,在 embed.js 之前进行配置) 第三:将每个 iframe 替换为其 Web 组件(步骤 3d),一次一个文件
执行所有这些检查。检查 5a–5c 可以并行运行(都是独立的 grep 搜索)。检查 5d 和 5e 需要读取特定文件。每次检查都应该有明确的通过/失败结果。 5a:没有剩余的元数据库 iframe 使用 Grep 在所有项目文件中搜索 `<iframe` 和 `iframe`(不包括 `node_modules`、`.git`、锁定文件)。验证是否存在指向元数据库的完整应用程序/交互式嵌入 iframe。
将最终输出组织到以下部分: 应用的更改:列出每个修改的文件以及每个更改的一行描述 Web 组件映射:显示每个旧 iframe→新 Web 组件的表格 删除的参数:删除的完整应用程序 iframe 参数列表,并简要说明为什么它们不适用于模块化嵌入 主题配置:映射到 `window.metabaseConfig` 的任何主题/外观设置
## 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:
1. record the step as ❌ blocked,
2. explain exactly what is missing / what failed,
3. stop (do not proceed to later steps).
### Required output structure
Your response should contain these sections in this order:
1. **Step 0: Metabase Version Detection**
2. **Step 0.1: Migration Plan Checklist**
3. **Step 1: Project Scan**
4. **Step 2: iframe Analysis & Web Component Mapping**
5. **Step 3: Migration Plan**
6. **Step 4: Applied Code Changes**
7. **Step 5: Validation**
8. **Step 6: Final Summary**
Each step section should end with a status line:
- `Status: ✅ complete` or `Status: ❌ blocked`
Steps are sequential — do not start a step until the previous one is ✅ complete.
### Evidence requirements
- Step 0: Metabase version detected (source: Docker tag, env var, or user answer).
- Step 1: every matched file path, every iframe location, SSO endpoint, layout/head file, Metabase config variables.
- Step 2: per iframe — parsed URL, content type, ID, hash params, mapped web component with attributes.
- Step 3: the complete file-by-file change plan with exact old/new code.
- Step 4: per file — what was changed and exact diffs applied.
- Step 5: each validation check's pass/fail result with evidence.
## Architectural conformance
Follow the app's existing architecture, template engine, layout/partial system, code style, and route patterns. Do not switch paradigms (e.g., templates to inline HTML or vice versa). If the app has middleware for shared template variables, prefer that over duplicating across route handlers.
## Performance
- Maximize parallelism within each step. Use parallel Grep/Glob/Read calls in a single message wherever possible.
- Do not use sub-agents for project scanning — results need to stay in the main context for cross-referencing in later steps.
- Do not parse repo branches, commits, PRs, or issues.
## Scope
This skill converts Full App / Interactive embedding (iframe-based) to Modular embedding (web-component-based via `embed.js`).
**The consumer's app may be written in any backend language** (Node.js, Python, Ruby, PHP, Java, Go, .NET, etc.) with any template engine. Keep instructions language-agnostic unless a specific language is detected in Step 1.
### What this skill handles
- Replacing `<iframe>` elements pointing to Metabase with appropriate web components (e.g. `<metabase-question>`, `<metabase-dashboard>`)
- Adding the `embed.js` script tag (exactly once at app layout level)
- Adding `window.metabaseConfig` setup code (exactly once at app layout level)
- Modifying SSO/JWT endpoints to support modular embedding's JSON response format
- Mapping iframe URL customization parameters to theme config and component attributes
### What this skill does not handle
- Migrating from Static (signed/guest) embedding
## 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 `v` or `0.`, drop patch — e.g., `0.58.1` → `58` → 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
## AskUserQuestion triggers
Use AskUserQuestion and halt until answered if:
- The Metabase instance URL cannot be determined from project code or environment variables
- Always ask for the Metabase instance version — do not rely solely on code detection
- An iframe URL pattern does not match any known resource type (dashboard, question, collection, home)
- No SSO/JWT endpoint can be identified in the project
- No layout/head file can be identified (unclear where to inject embed.js)
- Multiple layout files exist and it is unclear which one(s) to use
- The backend language cannot be determined
- Multiple iframes specify different `locale` values (ask user which locale to set in `window.metabaseConfig`)
## Pre-workflow steps
### Migration Plan Checklist
Create a checklist to track progress. In Claude Code, use TaskCreate/TaskUpdate tools:
- Step 0: Detect Metabase version
- Step 1: Scan project + fetch target version docs
- Step 2: Analyze iframes and map to web components (using docs)
- Step 3: Plan migration changes
- Step 4: Apply code changes
- Step 5: Validate changes
- Step 6: Final summary
## Workflow
### Step 0: Detect Metabase instance version
Always AskUserQuestion for the Metabase instance version — even if a version appears in Docker tags or env vars, confirm it with the user. Abort if v52 or older (modular embedding was introduced in v53).
Then fetch `llms-embedding-full.txt` for the confirmed version (see "Allowed documentation sources" for URL format).
Before anything else, determine the Metabase version. Grep the project for Docker image tags (`metabase/metabase:v`, `metabase/metabase-enterprise:v`), `METABASE_VERSION`, or version references. If undetected, AskUserQuestion (options: `v52 or older`, `v53`, `v54–v58`, `v59+`). Abort if v52 or older (modular embedding not available — it was introduced in v53). Record the version — it controls `jwtProviderUri` placement in later steps.
### Step 1: Scan the project + fetch docs no sub-agent)
Perform the project scan and doc fetch concurrently — they are independent. Use parallel tool calls within a single message wherever there are no dependencies.
#### 1a: Fetch target version docs
Fetch `llms-embedding-full.txt` for the target version (see "Allowed documentation sources" for URL format). These docs are the authoritative source for web component attributes, `window.metabaseConfig` options, and SSO endpoint behavior for the target version. Use them in Step 2 for mapping instead of relying on hardcoded tables alone.
Launch this concurrently with the project scan steps below.
#### 1b: Identify backend language and framework
- Check for dependency/build files (`package.json`, `requirements.txt`, `Gemfile`, `pom.xml`, `go.mod`, `composer.json`, etc.).
- Identify the template engine and record the language and framework.
#### 1c: Find ALL Metabase iframes
Use Grep to search for all of these patterns (in parallel):
- `<iframe` in all template/HTML/JSX/view files
- `iframe` in all server-side code files (JS/TS/Python/Ruby/Go/Java/PHP) — catches iframes built via string concatenation or template literals
- `auth/sso` adjacent to `iframe` or `src` attributes. Note: the SSO URL may be constructed in a separate variable or function and passed to the iframe `src` — if the iframe `src` is a variable, trace its definition to check for `auth/sso`.
For each file with a match, read the entire file.
#### 1d: Find SSO/JWT authentication code
Use Grep to search for all of these patterns (in parallel):
- `/auth/sso`
- `/sso/metabase` or similar SSO route patterns
- `jwt.sign` or `jwt.encode` or `JWT` or `jsonwebtoken` or `PyJWT` or `jose`
- `JWT_SHARED_SECRET` or `METABASE_JWT_SHARED_SECRET`
- `return_to` (Metabase SSO redirect parameter)
- `redirect` near `auth/sso` (catches the SSO redirect logic)
For each matching file, read the entire file.
#### 1e: Find the layout/head file(s)
Find the single file (or common code path) where the HTML `<head>` section is defined — this is where `embed.js` and `window.metabaseConfig` will be injected.
Search for:
- `<head>` or `<!DOCTYPE` or `<html` in template/view files
- Layout/wrapper patterns: `include('head')`, `<%- include`, `{% extends`, `{% block`, `layout`, `base.html`, `_layout`, `application.html`
- If the app builds HTML via inline strings in server code (e.g., `res.send(...)`), identify where the `<head>` content is generated
#### 1f: Find Metabase configuration
Grep for `METABASE_` and `MB_` prefixed variables. Record every Metabase-related variable name and where it is read.
#### Output: Structured Project Inventory
Compile all findings into:
```
Backend: {language}, {framework}, {template engine}
Metabase config:
- Site URL variable: {name} (read at {file}:{line})
- Dashboard path variable: {name} (read at {file}:{line})
- JWT secret variable: {name} (read at {file}:{line})
- Other variables: ...
Layout/head file: {path}:{line range} (or "inline HTML in {file}:{line range}")
Iframes found: {count}
- {file}:{line} — {brief description}
- ...
SSO endpoint: {file}:{line} — {route} ({method})
```
### Step 2: Analyze iframes and map to web components (only after Step 1 ✅)
Use the documentation fetched in Step 1a as the authoritative reference for web component attributes, `window.metabaseConfig` options, and SSO endpoint behavior. The hardcoded tables below are fallbacks — if the docs describe additional attributes or different behavior for the target version, prefer the docs.
For each iframe found in Step 1:
#### 2a: Parse the iframe URL
Extract from the iframe `src` attribute (which may be a template expression, variable, or literal):
- **Metabase base URL**: may come from env var, constant, or be hardcoded
- **Resource path**: the path after the base URL, e.g., `/dashboard/1`, `/question/entity/abc123`, `/collection/5`
- **Resource type**: `dashboard`, `question`, `collection`, or `home` (if path is `/`)
- **Entity ID or numeric ID**: the resource identifier in the path.
- An ID may be:
- a numeric id, e.g. 123
- a numeric id + slug, e.g. 123-slug. You need to remove the slug completely; including the slug will prevent the resource from loading.
- an entity id — URLs with pattern `/{resource_type}/entity/{entity_id}` use entity IDs
- **URL hash/query parameters** used for UI customization (e.g., `#logo=false&top_nav=false`)
- **SSO wrapping**: whether the iframe goes through an SSO endpoint first (e.g., `/sso/metabase?return_to=...`)
#### 2b: Map content type to web component
| Full App iframe path pattern | Modular Web Component | Required Attribute |
|---|---|---|
| `/dashboard/{id}` or `/dashboard/entity/{entity_id}` | `<metabase-dashboard>` | `dashboard-id="{id or entity_id}"` |
| `/question/{id}` or `/question/entity/{entity_id}` | `<metabase-question>` | `question-id="{id or entity_id}"` |
| `/model/{id}` or `/model/entity/{entity_id}` | `<metabase-question>` | `question-id="{id or entity_id}"` |
| `/collection/{id}` or `/collection/entity/{entity_id}` | `<metabase-browser>` | `initial-collection="{id or entity_id}"` |
| `/` (Metabase home / root) | `<metabase-browser>` | `initial-collection="root"` |
If the iframe path is built dynamically from a variable, the web component attribute should use the same variable/expression.
If an iframe path does not match any known pattern → AskUserQuestion.
#### 2c: Map URL customization parameters
**Parameters to drop** (not applicable — modular web components do not include Metabase application chrome):
| Full App Parameter | Why it is dropped |
|---|---|
| `top_nav` | Web components have no Metabase top navigation bar |
| `side_nav` | Web components have no Metabase sidebar |
| `logo` | Web components have no Metabase or whitelabel logo |
| `search` | Web components have no Metabase search bar |
| `new_button` | No `+ New` button (use `with-new-question` / `with-new-dashboard` on `<metabase-browser>` if applicable) |
| `breadcrumbs` | Web components have no Metabase breadcrumbs |
**Parameters that map to web component attributes:**
| Full App Parameter | Modular Equivalent |
|---|---|
| `header=false` | `with-title="false"` on the component |
| `action_buttons=false` | `drills="false"` on the component |
**Parameters that map to `window.metabaseConfig`:**
| Full App Parameter | metabaseConfig Property |
|---|---|
| `locale={code}` | `locale: "{code}"` |
**Locale migration rules:**
- If one locale value is found across all iframes → add `locale: "{code}"` to `window.metabaseConfig` automatically
- If multiple different locale values are found across iframes → AskUserQuestion to let the user decide which single locale to set in `window.metabaseConfig` (modular embedding supports only one global locale)
#### 2d: Output Migration Mapping Table
For each iframe, output:
```
iframe #{n}: {file}:{line}
Old: {full iframe HTML or code}
Content type: {dashboard|question|collection|home}
ID: {static value or variable expression}
Dropped params: {list}
Mapped attributes: {list}
New: {exact replacement web component HTML}
```
### Step 3: Plan migration changes (only after Step 2 ✅)
Create a complete file-by-file change plan covering all areas below. Every change should be specified with the target file, the old code, and the new code.
#### 3a: embed.js script injection — exactly once per app
- **Target**: the layout/head file identified in Step 1e
- **Location**: inside `<head>` (or as close as possible to other `<script>` tags)
- **Code to add**:
```html
<script defer src="{METABASE_SITE_URL}/app/embed.js"></script>
```
- `{METABASE_SITE_URL}` should be rendered dynamically using the project's existing template expression syntax.
- If the Metabase URL variable is only available in specific routes, pass it to the layout via middleware or template context.
- Verify this will appear exactly once in the rendered HTML regardless of which page the user visits — if it loads twice, the SDK reinitializes and breaks auth state.
#### 3b: metabaseConfig — exactly once per app
Modular embedding reads its configuration from `window.metabaseConfig`. There is no `defineMetabaseConfig()` function — assign the config object directly.
- **Target**: same layout/head file as 3a
- **Location**: before the embed.js script tag (the config must be set before embed.js loads, otherwise the SDK has no config to read)
- **Code to add** (minimum — add auth fields only if the fetched docs list them for this version):
```html
<script>
window.metabaseConfig = {
instanceUrl: "{METABASE_SITE_URL}",
// Add auth fields here only if supported by the confirmed version's docs
};
</script>
```
- **Locale**: If a `locale` parameter was found on any iframe in Step 2c, add `locale: "{code}"` to the config object. If multiple iframes had different locale values, the user will have already been asked which one to use (per AskUserQuestion trigger).
- `instanceUrl` (and `jwtProviderUri` if supported) should be rendered dynamically using the project's template expression syntax.
- **Auth config fields**: Consult the docs fetched in Step 0 to determine which fields `window.metabaseConfig` supports for the confirmed version. For example, `jwtProviderUri` may or may not be available. If the docs list it, include it as a **full absolute URL** (e.g., `http://localhost:9090/sso/metabase`) — relative paths don't work. If the docs don't list it, the JWT Identity Provider URI must be configured in Metabase admin settings instead (see Step 3f).
- `window.metabaseConfig` should be set exactly once — if it appears in per-iframe code instead of the layout, each component will re-initialize the SDK.
#### 3c: SSO endpoint modification
The existing SSO endpoint currently redirects the browser to Metabase's `/auth/sso?jwt={token}&return_to={path}`.
For modular embedding, the embed.js SDK sends a fetch request to the JWT Identity Provider URI and expects a JSON response. The endpoint should be converted to return JSON only — do not keep a fallback to the old redirect-based auth flow.
This is a full migration, not a gradual one. The old iframe-based embedding is being completely replaced, so the redirect behavior is no longer needed.
Consult the auth docs fetched in Step 0 for the expected SSO endpoint response format for the confirmed version.
**Constraints:**
- Do not modify the JWT signing logic — only change how the response is delivered
- Remove the old redirect behavior entirely — the endpoint should only return JSON
- The JSON response body should be exactly `{ "jwt": "<token>" }` — no other fields, because the SDK parses this exact shape
- Remove any code that builds the redirect URL (e.g., `new URL("/auth/sso", ...)`, `searchParams.set("return_to", ...)`) as it is now dead code
#### 3d: iframe replacement plan
For each iframe from Step 2d's Migration Mapping Table:
- Specify: file path, exact old code to replace, exact new code
- The new web component should preserve any dynamic ID expressions from the original iframe URL
- If the iframe had explicit `width`/`height` attributes or inline `style`, apply them directly to the web component element (e.g., `<metabase-dashboard dashboard-id="1" style="width:800px;height:600px">`) — do not wrap in a `<div>`
- If the iframe was styled via CSS classes, apply those classes directly to the web component
- If the iframe was inside a container element with styles, keep that container
- Remove any server-side SSO URL construction that was used only for the iframe src (e.g., building `/sso/metabase?return_to=...`). But do not remove the SSO endpoint itself — it is still needed for modular embedding auth.
- If the iframe src was built via a server-side route handler that sends inline HTML (e.g., Express `res.send('<iframe ...')`), replace the iframe HTML within that handler's response string
#### 3e: Dead code removal
After replacing iframes and converting the SSO endpoint, identify and remove:
- Variables that built the iframe `src` URL (e.g., `iframeUrl`, `mbUrl`) if they are no longer used anywhere
- URL parameter/modifier strings that were appended to iframe URLs (e.g., `mods = "logo=false"`) if they are no longer referenced anywhere (check the SSO endpoint — if the redirect logic was removed, these strings may now be dead code too)
- Redirect-related code removed from the SSO endpoint (e.g., URL construction for `/auth/sso`, `return_to` parameter handling) — this is already handled as part of Step 3c
- Helper functions that constructed Metabase iframe URLs if they are no longer called
- Do not remove: the SSO endpoint itself, JWT signing function, environment variable reads, or any code that is used by other parts of the application
#### 3f: Metabase admin configuration notes (manual steps for the user)
List these as part of the plan — they will be included in the final summary:
1. **Enable modular embedding**: Admin > Embedding > toggle "Enable modular embedding"
2. **Configure CORS origins**: Admin > Embedding > Modular embedding > add the host app's domain (e.g., `http://localhost:9090`)
3. **Configure JWT Identity Provider URI**: Admin > Authentication > JWT > set to the full URL of the SSO endpoint (e.g., `http://localhost:9090/sso/metabase`). Check the fetched docs to determine whether this is required or optional for the confirmed version (it depends on whether `window.metabaseConfig` supports a JWT provider field).
4. **JWT shared secret**: No change needed — reuse the existing shared secret from Full App embedding setup
### Step 4: Apply code changes (only after Step 3 ✅)
Apply all changes from Step 3 in this order (backend changes first to minimize the window where things are broken):
1. **First**: Modify the SSO endpoint to return JSON (Step 3c) — this is backend-only
2. **Second**: Add `window.metabaseConfig` assignment and embed.js script tag to the layout/head file (Step 3b + 3a, config before embed.js)
3. **Third**: Replace each iframe with its web component (Step 3d), one file at a time
4. **Fourth**: Remove dead code (Step 3e)
**Constraints:**
- Use the Edit tool with precise `old_string` / `new_string` for every change
- Do not add new package dependencies — modular embedding requires only the embed.js script served by the Metabase instance
- Do not change environment variable names
- If a file requires multiple edits, apply them top-to-bottom to avoid offset issues
### Step 5: Validate changes (only after Step 4 ✅)
Perform all of these checks. Checks 5a–5c can run in parallel (all are independent grep searches). Check 5d and 5e require reading specific files. Each check should have an explicit pass/fail result.
#### 5a: No remaining Metabase iframes
Use Grep to search for `<iframe` and `iframe` across all project files (excluding `node_modules`, `.git`, lockfiles).
Verify that no Full App / Interactive Embedding iframes pointing to Metabase remain.
Non-Metabase iframes should be untouched. Also leave any guest embedding (formerly "static embedding") or public embedding iframes untouched — those use different URL patterns (e.g., `/embed/` or `/public/`) and are not part of this migration.
**Pass criteria**: zero Full App / Interactive Embedding iframes found (guest/public embed iframes are excluded).
#### 5b: embed.js appears exactly once
Use Grep to search for `/app/embed.js` across all project files (excluding `node_modules`, `.git`). This pattern is specific to Metabase's embed script URL and avoids false positives from other tools that may use a generic `embed.js` filename.
**Pass criteria**: exactly one occurrence in the layout/head file.
#### 5c: window.metabaseConfig is set exactly once
Use Grep to search for `window.metabaseConfig` across all project files (excluding `node_modules`, `.git`).
**Pass criteria**: exactly one occurrence (the assignment in the layout/head file).
#### 5d: SSO endpoint returns JSON only
Read the SSO endpoint file. Verify:
- The endpoint returns a JSON response with `{ jwt: token }`
- The old redirect logic (`res.redirect`, `new URL("/auth/sso", ...)`, `return_to`) has been fully removed
- No conditional check for `response=json` exists (since JSON is the only response format now)
**Pass criteria**: endpoint returns JSON only, no redirect fallback remains.
#### 5e: Spot-check modified files
Read each modified file and verify:
- Web components have required attributes (`dashboard-id`, `question-id`, or `initial-collection`)
- Template syntax is valid (no unclosed tags, correct expressions)
- Dead-code variables identified in Step 3e have been removed
**Pass criteria**: all checks pass.
If any check fails:
- Fix the issue immediately
- Re-run the specific check
- If unable to fix after 3 attempts, mark Step 5 ❌ blocked and report which check failed and why
### Step 6: Output summary
Organize the final output into these sections:
1. **Changes applied**: list every file modified and a one-line description of each change
2. **Web component mapping**: table showing each old iframe → new web component
3. **Dropped parameters**: list of Full App iframe parameters that were dropped, with brief explanation of why they don't apply to modular embedding
4. **Theme configuration**: any theme/appearance settings mapped into `window.metabaseConfig`
5. **Manual steps required** (Metabase admin configuration from Step 3f):
- Enable modular embedding
- Configure CORS origins
- Configure JWT Identity Provider URI
- Any other admin steps identified
6. **Behavioral differences the user should be aware of**:
- Users can no longer navigate between dashboards/questions/collections within a single embed (each web component is standalone)
- The Metabase application shell (nav, sidebar, search) is no longer present
- Any iframe parameters that could not be mapped
## Retry policy
**Doc fetching:**
- If fetching `llms-embedding-full.txt` returns 404, verify the Metabase version number and retry. If still failing, mark Step 1 ❌ blocked.
**Validation:**
- If any validation check in Step 5 fails after 3 fix attempts, mark Step 5 ❌ blocked and report which check failed and why.
- If AskUserQuestion is not answered, remain blocked on that step — do not guess or proceed with assumptions.
按说明文件中的顺序排列。
执行合同
所需的输出结构
证据要求
架构一致性
性能
文件/命令 -> Status: ✅ complete · Status: ❌ blocked · embed.js · <iframe> · <metabase-question> · <metabase-dashboard> · window.metabaseConfig · llms-embedding-full.txt
内容校验值 -> 44a5de7298fa
当前原文的自动摘译,尚未人工审校。
执行合同
按顺序执行工作流程步骤 - 不要跳过任何步骤。首先创建清单,然后执行每个步骤并用证据明确标记其已完成。每个步骤的输出都会输入到下一个步骤,因此跳过步骤会产生错误的迁移。如果由于缺少信息或工具故障而无法完成某个步骤,您必须:将该步骤记录为“已阻止”,准确解释缺少的内容/失败的内容,停止(不要继续执行后续步骤)。
所需的输出结构
您的回复应按以下顺序包含以下部分: 步骤 0:元数据库版本检测 步骤 0.1:迁移计划清单 步骤 1:项目扫描 步骤 2:iframe 分析和 Web 组件映射
证据要求
步骤 0:检测到元数据库版本(来源:Docker 标记、环境变量或用户答案)。第 1 步:每个匹配的文件路径、每个 iframe 位置、SSO 端点、布局/头文件、元数据库配置变量。第 2 步:每个 iframe — 解析的 URL、内容类型、ID、哈希参数、带有属性的映射 Web 组件。步骤 3:完整的逐个文件更改计划以及准确的旧/新代码。第 4 步:每个文件 — 更改了什么以及应用了确切的差异。
架构一致性
遵循应用程序现有的架构、模板引擎、布局/部分系统、代码风格和路由模式。不要切换范例(例如,将模板转换为内联 HTML,反之亦然)。如果应用程序具有用于共享模板变量的中间件,则更喜欢使用中间件而不是跨路由处理程序进行复制。
性能
最大化每个步骤内的并行性。尽可能在单个消息中使用并行 Grep/Glob/Read 调用。不要使用子代理进行项目扫描 - 结果需要保留在主要上下文中,以便在后续步骤中进行交叉引用。不要解析存储库分支、提交、PR 或问题。