SuperAPI AI 工具集

effect-v3-to-v4

编程与开发

查看项目

更新于 10-29 10:05

技能介绍

用途

本技能用于在代码库中执行 Effect v3 → v4 迁移,包括升级 effect 包以及任意 @effect/* 包跨越 v3/v4 边界。迁移由 Effect 仓库中随附的生成式迁移参考驱动:每一个重命名、移除和签名变化都由上游数据给出答案,不靠猜测替代项。

主要能力

  • 从两个浅克隆的官方 Effect 仓库驱动迁移:v4(main)包含 MIGRATION.md、migration/ 指南与 v4 源码;v3 分支仅作为旧语义的升级参考。
  • 提供按主题查找 API 的阅读顺序:先一次性阅读 MIGRATION.md;每个 API 首先查阅 migration/v3-to-v4.md(生成式参考,覆盖所有被移除或变更的 API);当映射意味着重写而非改名时(如 Context.Tag → Context.Service 属于结构性变化),按需查阅按主题的指南;写代码前用 v4 源码确认替代项的真实签名;仅在不确定旧 v3 语义时升级到 v3 源码。
  • 强调“绝不整篇阅读参考文档”:migration/v3-to-v4.md 约 16000 行、约 35 万 token,整读会耗尽上下文。提供可 grep 的查找配方,例如按符号搜索、按 ### \模块路径`` 标题读取整个模块章节、在 Import Map 中解析旧导入路径、列出某包的全部模块章节。
  • 处理仓库级变更:包合并(@effect/platform、@effect/rpc、@effect/cluster 等已并入核心 effect 包,需从 package.json 移除并按 Import Map 重写导入;@effect/platform-*、@effect/sql-*、@effect/ai-*、@effect/opentelemetry、@effect/vitest 等仍为独立依赖)、版本对齐(v4 中所有 Effect 生态包共享同一版本号)、不稳定模块(如 effect/unstable/http、effect/unstable/rpc 为正确的 v4 导入路径,可能在次版本中发生破坏性变更)。
  • 子代理委派:按文件或模块生成子代理,告知其需解析的具体 v3 符号;子代理返回修改及所用映射,主会话维护错误清单与滚动摘要;子代理同样遵守查找纪律与硬性禁令。

使用方式

  1. 设置并验证本地克隆:使用两条浅克隆命令获取 v4 与 v3 仓库;若 .repos/effect 已存在,需验证其 origin 指向官方 Effect-TS/effect 仓库且版本为 4.x,否则删除后重新克隆。
  2. 阅读 MIGRATION.md 并列出 .repos/effect/migration/ 目录以了解背景与指南索引。
  3. 先迁移 package.json:移除已合并的包,将剩余每个 Effect 包对齐到同一个 v4 版本;须在类型检查前完成,否则首次运行会被大量无法解析的导入错误淹没。
  4. 运行项目类型检查(如 tsc --noEmit)获得初始错误清单。
  5. 迭代直至类型检查通过:对每个错误按查找纪律解析 API(在 migration/v3-to-v4.md 中搜索符号,按阅读顺序升级),然后修复调用点;可按文件委派给子代理。绝不通过静默错误代替解析。
  6. 完成:类型检查通过;运行测试并如实报告结果(测试非门禁);撰写最终摘要,说明类型检查结果、测试结果(或未运行原因)、每个构造的替代项,以及被报告而非桥接的缺口。

适用场景

适用于需要将现有 Effect 代码库从 v3 升级到 v4、或跨 v3/v4 边界升级 effect 与 @effect/* 依赖的工程迁移任务,尤其是大型代码库中需要系统化、可追溯地处理大量 API 变化的情况。

限制

  • 迁移必须以上游迁移参考、主题指南或 v4 源码为依据,禁止编造 API。
  • 硬性禁令:不得重新引入 v3 形态的兼容层(如 re-export 旧名称的 v3-compat.ts);不得使用 any 或 as 强转来消除迁移后的类型错误;每个替代项都必须可追溯到参考文档、主题指南或 v4 源码。
  • 完成条件以类型检查通过为准;测试套件结果需如实报告,但不作为门禁,不得为通过测试而削弱测试。
  • 参考文档约 16000 行 / 约 35 万 token,必须搜索读取,不能整篇阅读。
  • .repos/effect 若由旧设置说明从已归档的 Effect-TS/effect-smol 克隆而来,则为失效检出(内容陈旧且不含 migration/v3-to-v4.md),使用前必须验证。
  • 不使用 git worktree 在分支间共享单个克隆;每个克隆可独立重跑、分别删除。