effect-v3-to-v4

Effect v3 到 v4 迁移

根据 Effect 仓库随附的生成式迁移参考资料，执行 Effect v3 → v4 迁移。每项重命名、移除和签名变更都能通过上游数据查明——不要猜测替代方案。

工作流

按顺序完成以下步骤；每个步骤的详细说明见相应章节。

1. 设置并验证本地检出 — 两个浅克隆；在信任任何现有的 .repos/effect 之前，先验证它。参见 设置：本地检出。
2. 阅读 MIGRATION.md 并查看 ls .repos/effect/migration/，了解背景和指南索引。参见 阅读顺序。
3. 迁移 package.json — 移除已合并的包，并确保所有保留的 Effect 包使用同一个 v4 版本。务必在类型检查之前完成，否则首次运行会被已不存在的包所导致的未解析导入错误淹没。参见 仓库级变更。
4. 运行项目的类型检查（例如 tsc --noEmit），获取初始错误清单。
5. 反复处理，直到类型检查通过。 对于每个错误，按照查找规范解析 API——在 migration/v3-to-v4.md 中搜索符号，并根据 阅读顺序 逐级查证——然后修复调用处；按文件将修复工作委派给子 Agent，参见 委派给子 Agent。切勿通过屏蔽错误来代替解决错误；参见 严格禁止事项。
6. 收尾 — 类型检查通过；运行测试并如实报告结果（测试不是门槛）；撰写最终总结。参见 完成条件。

设置：本地检出

迁移基于 Effect 官方仓库的两个浅克隆、单分支克隆进行：

git clone --depth 1 --single-branch https://github.com/Effect-TS/effect .repos/effect
git clone --depth 1 --single-branch --branch v3 https://github.com/Effect-TS/effect .repos/effect-v3

• .repos/effect — v4（main）。包含 MIGRATION.md、migration/ 指南和 v4 源码。
• .repos/effect-v3 — v3（v3 分支）。仅在需要进一步查证时用作旧语义的参考。

每个克隆都可以单独重复运行，也可以单独删除。不要使用 git worktree 在同一个克隆间共享不同分支。

信任现有检出前先进行验证

./.repos/effect 可能已经存在，且是根据旧设置说明从已弃用的 Effect-TS/effect-smol 仓库克隆的。该检出已过时，不包含 migration/v3-to-v4.md。使用前请验证：

git -C .repos/effect remote get-url origin   # must be the canonical Effect-TS/effect repo
node -p "require('./.repos/effect/packages/effect/package.json').version"   # must be 4.x

如果远程源指向 effect-smol，或者版本不是 4.x，请删除该目录并按上述步骤重新克隆。

阅读顺序

1. 预先完整阅读一次 MIGRATION.md（.repos/effect/MIGRATION.md）。
2. migration/v3-to-v4.md — 每个 API 的首要查找位置。 生成式参考涵盖了所有已移除或已变更的 API。搜索该文件（见下文）；切勿从头到尾阅读。
3. 按主题划分的指南（.repos/effect/migration/*.md）：当映射表明需要重写而非重命名时阅读，例如，Context.Tag → Context.Service 是结构性变更，不是简单的符号替换。根据需要从 MIGRATION.md 的索引查找这些指南，不要预先通读。
4. v4 源码（.repos/effect/packages/*/src/）：在据此编写代码前，确认替代 API 的实际签名。
5. v3 源码（.repos/effect-v3）仅用于进一步查证——在不确定旧版 v3 语义时使用。

切勿通读整份参考文档

这是本技能中最重要的一条规则。 migration/v3-to-v4.md 约有 17,000 行／35 万个 token。一次性通读会耗尽上下文窗口，并拖垮整个迁移。

务必搜索该文件，只阅读匹配行及其周边上下文。该文件分为四个部分——导入映射、无对应项的导入、已移除的模块和 API 参考（每个模块对应一个 ### `<v3 module path>` 标题）。条目均为可通过 grep 搜索的单行格式 - `Old.symbol` -> `New.symbol`: <rationale>；移除项会以 -> `none` 明确列出，并说明替代方案。

具体示例：

# Look up a specific v3 symbol
rg -n 'AnthropicTokenizer\.layer' .repos/effect/migration/v3-to-v4.md

# Read a whole module's section via its heading
rg -n -A 40 '^### `@effect/platform/FileSystem`' .repos/effect/migration/v3-to-v4.md

# Resolve a v3 import path in the Import Map
rg -n '^@effect/platform/FileSystem ' .repos/effect/migration/v3-to-v4.md

# List every module section for a package
rg -n '^### `@effect/cluster/' .repos/effect/migration/v3-to-v4.md

遇到 API 时逐个搜索查找。若在导入映射中找不到，不要就此止步——得出结论前，请先检查 已移除的模块 和 无对应项的导入 两个部分。

仓库级更改

仅按 API 忠实地查找仍会导致 package.json 损坏。请提前一次性处理以下事项：

• 合并软件包。 @effect/platform、@effect/rpc、@effect/cluster 等已合并到核心 effect 软件包中。从 package.json 中移除它们，并根据导入映射重写其导入。仍保持独立的软件包（@effect/platform-*、@effect/sql-*、@effect/ai-*、@effect/opentelemetry、@effect/atom-*、@effect/vitest 等）仍作为依赖保留。已合并的 v3 软件包（包括 @effect/sql 和 @effect/cli）的 npm latest 标签仍指向 0.x；应移除它们，而不是将所有内容都升级到 latest。
• 版本对齐。 目标版本为当前稳定的 latest 4.x 版本。v4 中所有 Effect 生态系统软件包共用同一个版本号，因此每个剩余的 effect / @effect/* 依赖都必须使用相同且匹配的版本。
• 模块路径与稳定性。 GA 导入使用 effect/http、effect/rpc 和 effect/ai/LanguageModel 等路径。稳定性由 JSDoc 标签声明，而不是由导入路径中的片段声明：@stability unstable API 可能在次要版本中收到破坏性更改，@stability experimental API 可能在补丁版本中收到破坏性更改。 如果迁移的代码针对的是使用 effect/unstable/<module> 导入的 beta 或 RC 版本，请移除 unstable 片段（例如，effect/unstable/http → effect/http）。旧路径没有兼容性导出；移动模块不会使其 API 变得稳定。

委派给子 Agent

逐文件迁移非常耗费上下文；请交由子 Agent 处理，以便主会话在整个迁移过程中保留上下文。

• 每个文件（或每个模块）启动一个子 Agent，并告知它该文件中需要解析的具体 v3 符号。
• 子 Agent 返回所做的编辑和使用的映射；主会话保留错误清单和进行中的摘要。
• 子 Agent 遵循相同的查找规范（阅读顺序、rg 配方）和严格禁止事项。
• 子 Agent 也不得完整读取参考文档；子 Agent 上下文耗尽，同样会影响该文件的迁移。

严格禁止事项

• 切勿重新引入 v3 风格的兼容层。 编写重新导出旧名称的 v3-compat.ts 会让类型错误消失，并永久将代码库冻结在两个版本之间。应将调用点迁移到 v4 API。
• 不要使用 any 或 as 类型断言来消除迁移后的类型错误。 这类错误通常表明替代项的结构有所不同；类型断言会抹去这些信息。请返回参考文档或 v4 源码查证。
• 不要臆造 API。 每个替代项都必须有据可查，来源可以是参考文档、主题指南或 v4 源码。

完成条件

项目能够通过针对 v4 的类型检查。 v4 迁移本质上是类型层面的工作；未解决的导入和签名变更会在类型检查中显现，其他地方不会。运行项目的类型检查（例如 tsc --noEmit），直到检查通过。

建议运行测试套件，并且必须如实报告测试结果——但测试并非门槛。仓库处于迁移过程中时，测试可能因无关原因无法运行；不要为了让测试通过而削弱测试。

最终摘要必须说明：类型检查结果、测试结果（或未运行测试的原因）、每个构造的替代项，以及所有已报告但未进行兼容处理的缺口。