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