effect-v3-to-v4

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Effect v3 to v4 Migration

Effect v3 迁移至 v4

Drive an Effect v3 → v4 migration from the generated migration reference that ships in the Effect repo. Every rename, removal, and signature change is answered by upstream data — do not guess replacements.

基于Effect仓库中提供的迁移参考文档，完成Effect v3 → v4的迁移工作。所有重命名、移除和签名变更都以上游数据为准——请勿自行猜测替代方案。

Workflow

工作流程

Work through these steps in order; each one is detailed in the section named.

Set up and validate the local checkouts — two shallow clones; verify any pre-existing
```
.repos/effect
```
before trusting it. See Setup: Local Checkouts.
Read
MIGRATION.md
and
```
ls .repos/effect/migration/
```
for the background and guide index. See Reading Order.
Migrate
package.json
— remove consolidated packages, align every remaining Effect package on one v4 version. Do this before type-checking, or the first run drowns in unresolved-import noise from packages that no longer exist. See Repo-Level Changes.
Run the project's type-check (e.g.
```
tsc --noEmit
```
) to get the initial error inventory.
Iterate until the type-check is clean. For each error, resolve the API through the lookup discipline — search
```
migration/v3-to-v4.md
```
for the symbol, escalate per Reading Order — then fix the call site, delegating per-file fixes to sub-agents per Delegating to Sub-Agents. Never silence an error instead of resolving it; see Hard Prohibitions.
Finish — type-check clean; run tests and report their outcome honestly (not a gate); write the final summary. See Done Condition.

按顺序完成以下步骤，每个步骤的详细说明见对应章节：

设置并验证本地检出 —— 创建两个浅克隆；在使用之前，验证已存在的
```
.repos/effect
```
是否可用。详见设置：本地检出。
阅读
MIGRATION.md
和查看
ls .repos/effect/migration/
以获取背景信息和指南索引。详见阅读顺序。
迁移
package.json
—— 移除合并后的包，将所有剩余的Effect包统一对齐到同一个v4版本。在类型检查之前完成此操作，否则首次运行会因已不存在的包产生大量未解析导入的报错。详见仓库级变更。
运行项目的类型检查（例如
```
tsc --noEmit
```
）以获取初始错误清单。
迭代直到类型检查通过。对于每个错误，通过查找规则解析API——在
```
migration/v3-to-v4.md
```
中搜索符号，按照阅读顺序逐步排查——然后修复调用位置，根据委托给子代理将每个文件的修复工作委托给子代理。切勿通过忽略错误来解决问题；详见严格禁令。
完成 —— 类型检查通过；运行测试并如实报告结果（不作为通关条件）；撰写最终总结。详见完成条件。

Setup: Local Checkouts

设置：本地检出

The migration is driven from two shallow, single-branch clones of the canonical Effect repo:

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
```
). Contains
```
MIGRATION.md
```
, the
```
migration/
```
guides, and the v4 source.
```
.repos/effect-v3
```
— v3 (
```
v3
```
branch). Escalation-only reference for old semantics.

Each clone is independently re-runnable and separately deletable. Do not use

git worktree

to share one clone between branches.

迁移工作基于两个规范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

在分支之间共享同一个克隆。

Validate an existing checkout before trusting it

使用前验证现有检出

./.repos/effect

may already exist, cloned from the archived

Effect-TS/effect-smol

repo by older setup instructions. That checkout is dead: it is stale and does not contain

migration/v3-to-v4.md

. Verify before using:

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

If the origin points at

effect-smol

, or the version is not

4.x

, delete the directory and re-clone as above.

.repos/effect

可能已存在，是通过旧版设置说明从归档的

Effect-TS/effect-smol

仓库克隆而来。该检出已失效：内容过时且不包含

migration/v3-to-v4.md

。使用前请验证：

git -C .repos/effect remote get-url origin   # 必须指向规范的Effect-TS/effect仓库
node -p "require('./.repos/effect/packages/effect/package.json').version"   # 版本必须为4.x

如果源指向

effect-smol

，或者版本不是

4.x

，请删除该目录并按照上述步骤重新克隆。

Reading Order

阅读顺序

Front-load
MIGRATION.md
once (
```
.repos/effect/MIGRATION.md
```
).
migration/v3-to-v4.md
— the first stop for every API. The generated reference covers every removed or changed API. Search it (see below); never read it whole.
A per-topic guide (
```
.repos/effect/migration/*.md
```
) when the mapping implies a rewrite rather than a rename — e.g.
```
Context.Tag
```
→
```
Context.Service
```
is a structural change, not a symbol swap. Reach these on demand from the
```
MIGRATION.md
```
index, not front-loaded.
v4 source (
```
.repos/effect/packages/*/src/
```
, including
```
unstable/
```
) to confirm a replacement's real signature before writing code against it.
v3 source (
```
.repos/effect-v3
```
) as escalation only — for when unsure about the old v3 semantics.

先完整阅读一次
MIGRATION.md
（
```
.repos/effect/MIGRATION.md
```
）。
migration/v3-to-v4.md
—— 所有API查询的第一站。生成的参考文档涵盖了所有已移除或变更的API。搜索该文档（见下文）；切勿通篇阅读。
主题指南（
```
.repos/effect/migration/*.md
```
）—— 当映射涉及重写而非重命名时使用，例如
```
Context.Tag
```
→
```
Context.Service
```
是结构性变更，而非符号替换。从
```
MIGRATION.md
```
索引按需访问这些指南，无需提前阅读。
v4源码（
```
.repos/effect/packages/*/src/
```
，包括
```
unstable/
```
）—— 在编写代码前确认替代方案的真实签名。
v3源码（
```
.repos/effect-v3
```
）—— 仅在不确定旧版v3语义时作为升级参考。

Never Read the Reference Doc Whole

切勿通篇阅读参考文档

This is the single most important rule in this skill.

migration/v3-to-v4.md

is ~16,000 lines / ~350k tokens. Reading it in one pass blows the context window and takes the migration with it.

Always search it and read only matched lines plus surrounding context. The file has four sections — Import Map, No Counterpart Imports, Removed Modules, and API Reference (one

### `<v3 module path>`

heading per module). Entries are grep-able one-liners of the form

- `Old.symbol` -> `New.symbol`: <rationale>

, and removals are explicit

-> `none`

entries with a stated alternative.

Concrete recipes:

undefined

这是本技能中最重要的规则。

migration/v3-to-v4.md

约有16000行 / 350k个标记。一次性通篇阅读会超出上下文窗口，导致迁移工作受阻。

始终搜索该文档，仅阅读匹配行及其上下文。该文档分为四个部分——导入映射、无对应导入、已移除模块和API参考（每个模块对应一个

### `<v3 module path>`

标题）。条目为可通过grep查找的单行内容，格式为

- `Old.symbol` -> `New.symbol`: <rationale>

，移除的条目会明确标记为

-> `none`

并说明替代方案。

具体操作示例：

undefined

Look up a specific v3 symbol

查找特定的v3符号

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

rg -n -A 40 '^###

@effect/platform/FileSystem

' .repos/effect/migration/v3-to-v4.md

Resolve a v3 import path in the Import Map

在导入映射中查找v3导入路径

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


Look up APIs as you encounter them, one search at a time. A miss in the Import Map is not a dead end — check the **Removed Modules** and **No Counterpart Imports** sections before concluding anything.

rg -n '^### `@effect/cluster/' .repos/effect/migration/v3-to-v4.md


遇到API时逐个查找，每次搜索一个。如果在导入映射中未找到，不要就此放弃——在得出结论前先检查**已移除模块**和**无对应导入**部分。

Repo-Level Changes

仓库级变更

Faithful per-API lookup alone still yields a broken

package.json

. Handle these once, up front:

Package consolidation.
```
@effect/platform
```
,
```
@effect/rpc
```
,
```
@effect/cluster
```
, and others merged into the core
```
effect
```
package — remove them from
```
package.json
```
and rewrite their imports per the Import Map. Packages that remain separate (
```
@effect/platform-*
```
,
```
@effect/sql-*
```
,
```
@effect/ai-*
```
,
```
@effect/opentelemetry
```
,
```
@effect/vitest
```
, …) stay as dependencies.
Version alignment. All Effect ecosystem packages share one version number in v4. Every remaining
```
effect
```
/
```
@effect/*
```
dependency must be on the same matching version.
Unstable modules. Some functionality only exists under
```
effect/unstable/*
```
import paths (e.g.
```
effect/unstable/http
```
,
```
effect/unstable/rpc
```
). These are correct v4 imports — use them where the reference maps to them; they may receive breaking changes in minor releases.

仅依赖API查找仍会导致

package.json

出现问题。请先一次性处理以下变更：

包合并。
```
@effect/platform
```
、
```
@effect/rpc
```
、
```
@effect/cluster
```
等已合并到核心
```
effect
```
包中——从
```
package.json
```
中移除它们，并根据导入映射重写其导入语句。仍保持独立的包（
```
@effect/platform-*
```
、
```
@effect/sql-*
```
、
```
@effect/ai-*
```
、
```
@effect/opentelemetry
```
、
```
@effect/vitest
```
等）继续作为依赖保留。
版本对齐。v4版本中所有Effect生态系统包共享同一个版本号。所有剩余的
```
effect
```
/
```
@effect/*
```
依赖必须使用相同的匹配版本。
不稳定模块。部分功能仅存在于
```
effect/unstable/*
```
导入路径下（例如
```
effect/unstable/http
```
、
```
effect/unstable/rpc
```
）。这些是正确的v4导入语句——当参考文档指向这些路径时使用它们；它们可能在小版本更新中发生破坏性变更。

Delegating to Sub-Agents

委托给子代理

Per-file migration work is context-hungry; do it in sub-agents so the main session's context survives the whole migration.

Spawn one sub-agent per file (or per module), giving it the specific v3 symbols to resolve in that file.
The sub-agent returns the edit and the mappings it used; the main session keeps the error inventory and the running summary.
Sub-agents inherit the same lookup discipline (Reading Order, the
```
rg
```
recipes) and Hard Prohibitions.
The reference doc is never read whole in a sub-agent either — a blown sub-agent context still costs the migration that file.

每个文件的迁移工作需要大量上下文；请使用子代理完成，以便主会话的上下文在整个迁移过程中得以保留。

为每个文件（或模块）生成一个子代理，向其提供该文件中需要解析的特定v3符号。
子代理返回编辑内容和使用的映射关系；主会话保留错误清单和运行摘要。
子代理继承相同的查找规则（阅读顺序、
```
rg
```
操作示例）和严格禁令。
子代理同样不得通篇阅读参考文档——子代理上下文溢出仍会导致该文件的迁移工作失败。

Hard Prohibitions

严格禁令

Never reintroduce a v3-shaped compatibility layer. Writing a
```
v3-compat.ts
```
that re-exports old names makes type errors vanish and permanently freezes the codebase between versions. Migrate call sites to the v4 API.
No
any
, no
as
casts to silence a post-migration type error. Such an error is usually evidence the replacement has a different shape; casting deletes that information. Go back to the reference or the v4 source.
No invented APIs. Every replacement must trace to the reference doc, a topic guide, or the v4 source.

切勿重新引入v3兼容层。编写
```
v3-compat.ts
```
重新导出旧名称会使类型错误消失，并永久将代码库冻结在两个版本之间。将调用位置迁移到v4 API。
禁止使用
any
或
as
类型断言来掩盖迁移后的类型错误。此类错误通常表明替代方案的结构不同；类型断言会删除该信息。请返回参考文档或v4源码查找解决方案。
禁止自创API。所有替代方案必须可追溯到参考文档、主题指南或v4源码。

Done Condition

完成条件

The project type-checks against v4. A v4 migration is fundamentally a type-level exercise; unresolved imports and changed signatures surface there and nowhere else. Run the project's type-check (e.g.

tsc --noEmit

) until clean.

Running the test suite is recommended, and its outcome must be reported honestly — but it is not a gate. A repo mid-migration often has tests that cannot run for unrelated reasons; do not weaken tests to make them pass.

The final summary must state: the type-check result, the test result (or why tests were not run), every constructed replacement, and any gaps that were reported rather than bridged.

项目针对v4版本类型检查通过。v4迁移本质上是类型层面的操作；未解析的导入和变更的签名会在此处显现，不会在其他地方出现。运行项目的类型检查（例如

tsc --noEmit

）直到无错误。

建议运行测试套件，并且必须如实报告测试结果——但这不是通关条件。迁移中的仓库通常会因无关原因导致测试无法运行；请勿修改测试使其通过。

最终总结必须说明：类型检查结果、测试结果（或无法运行测试的原因）、所有构建的替代方案，以及已报告但未解决的问题。