模块化嵌入版本升级

工程开发 社区

技能解读

当前原文的自动摘译,尚未人工审校。

执行合同

按顺序执行工作流程步骤 - 不要跳过任何步骤。首先创建清单,然后执行每个步骤并用证据明确标记其已完成。每个步骤的输出都会输入到下一个步骤,因此跳过步骤会产生错误的迁移。如果由于缺少信息或工具故障而无法完成某个步骤,您必须:将该步骤记录为“已阻止”,准确解释缺少的内容/失败的内容,停止(不要继续执行后续步骤)。

所需的输出结构

您的回复应按以下顺序包含以下部分: 步骤 0:升级计划清单 步骤 1 结果:项目扫描 步骤 2 结果:d.ts 差异/目标文档(主要或后备) 步骤 3:更改目录

证据要求

第 1 步:列出每个匹配的文件路径和匹配的 grep 行(SDK 导入或模块化嵌入 API 调用/脚本标记)。完整文件分析发生在步骤 4 中。步骤 2(主路径):显示 d.ts 文件之间的差异输出。 (混合/后备路径):列出每个获取的 URL + 确认文件已加载到上下文中。不要在这里分析或解析类型——这是第 3 步的工作。第 3 步:结构化更改目录 - 每个更改/删除/添加的符号及其完全解析的具体类型。

性能

工作流程被设计为最大化并行性的管道:在 Claude Code 中,使用并行工具调用或run_in_background: true 作为子代理。不要解析存储库分支、提交、PR 或问题——它们很吵闹并且与版本比较无关。

步骤 1+2 的工具调用回合预算

步骤 1+2 必须在 3 轮工具调用中完成。第 1 轮 — 发现(所有并发,单个消息):Grep 用于 @metabase/embedding-sdk-react 导入(返回文件路径 - 尚未读取文件) Glob 锁定文件(yarn.lock、pnpm-lock.yaml、package-lock.json)读取package.json(适用于当前版本)

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
工程开发
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@metabase · 未声明许可证
上下文用量评级
较高消耗
接入复杂程度
需手动接入
是否需要外部接口密钥
不需要
兼容的系统
Docker
运行环境要求
Docker
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
  • 读取环境变量
网络行为
允许外网请求
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

01
第一步:扫描项目码

将扫描结果保留在主上下文中(不委托给子代理)——第 3 步需要它们进行交叉引用。对于 SDK 升级 (`@metabase/embedding-sdk-react`):第 1 步发生在第 1 轮中 — 仅 grep,不读取文件。 Grep 查找来自`@metabase/embedding-sdk-react`的所有导入。这将返回文件路径+匹配的导入行。还要检测包管理器(锁定文件的 glob)。

02
第 2 步:提取 API 更改

在第 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 diff 文件(如果两个版本都有 d.ts) `CURRENT_DTS_PATH` / `TARGET_DTS_PATH` — 原始 d.ts 路径(仅限混合模式)

03
步骤 3:构建变更目录(步骤 1-2 完成后)

范围:仅影响步骤 1 的 grep 输出中可见符号的目录更改。例如,如果 grep 显示 `MetabaseProvider`、`InteractiveQuestion` 和 `CollectionBrowser` 的导入,则仅对这些组件及其 props/types/callbacks 进行目录更改。跳过对项目未导入的组件的更改。从 d.ts diff、文档比较和更改日志中,将更改提取到目录中:

04
第 4 步:按文件迁移(并行)

每个项目文件都会根据变更目录进行独立分析和修复。这是主要的并行化点。在每个文件工作之前:更新 package.json 版本并安装依赖项。还要更新 docker 文件中的元数据库实例版本(如果存在)(docker-compose.yml、Dockerfile、.env)。这些操作只需完成一次,而不是针对每个文件。每个文件任务(对于步骤 1 文件列表中的每个文件):对于每个文件,结合读取 + 分析 + 修复的单遍:

05
第 5 步:验证类型检查(批量修复)

对于 SDK 升级(TypeScript 项目):运行一次类型检查 - 运行项目的类型检查命令(例如,`npm run typecheck`、`tsc --noEmit` 或项目构建工具的等效命令)。立即分析所有错误 - 读取完整的错误输出,并按根本原因对每个 SDK 相关错误进行分类(例如,“删除的 prop”、“更改的类型签名”、“重命名的导出”)。具有共同根本原因的错误会一起修复。

06
第 6 步:输出摘要

分为以下部分: 1. 已修复重大更改 - 列出每个重大更改的严重性和所做的操作: 🔴 重大更改(会导致构建/运行时错误):例如,“将 `fetchRequestToken` 从 1-arg 签名迁移到 0-arg 签名” 🟡 弃用(现在有效,稍后会破坏):例如,“`appearance` 属性重命名为`theme` — 已更新” 2. 弃用警告 — 仍然有效但在目标版本中被标记为弃用的 API。包括建议的替换,以便用户可以计划未来的更改。

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。