技能介绍

你在解决什么问题

在 TypeScript 里引入 Effect 后，业务代码往往卡在三件事：大模型生成的 API 名和签名不对（尤其是 v3 与 v4 beta 混用）、错误与依赖边界不清晰（E 通道、R 需求、Scope 资源谁管）、以及 在库内部就 runPromise 导致测试和组合性崩掉。本技能把官方文档、LLM 纠偏表和推荐工作流收成一套可执行的写作规范，而不是再讲一遍「Effect 是什么」。

技能如何工作

先判版本：从 package.json 区分 v3.x（Context.Tag、Effect.catchAll、Data.TaggedError）与 v4.x（Context.Service、Effect.catch、Schema.TaggedErrorClass）；不清楚时向用户确认，存量默认 v3、新项目可倾向 v4。
API 护栏：对照文档核对每一个符号；常见幻觉包括把缓存写成 Effect.cachedWithTTL（应为 Cache.make）、从 @effect/schema 导入（v3.10+ 应从 effect 桶导入）、把 fiber 说成 cancelled（应为 interrupted）等；v3/v4 各有独立纠错表。
渐进阅读：按任务只打开对应 reference（错误建模、DI/Layer、重试调度、并发、Stream、Schema、HTTP、可观测性、迁移等），避免一次性塞满上下文。
核心工作流：划定 IO 边界 → 用 Effect.gen（v4 命名函数优先 Effect.fn）写顺序逻辑 → 显式建模错误与 Layer → 资源用 Effect.scoped + acquireRelease → 仅在程序边缘 NodeRuntime.runMain / ManagedRuntime 运行。
起步 API 集：约 20 个官方推荐组合（Effect.succeed/fail、Effect.all、Effect.catchTag、Effect.provide 等），输出前走 Agent Quality Checklist（导入来源、版本语法、yield* 抛错、run* 不在库内等）。

适用边界与注意点

技能不替代官方文档：主站 effect.website/docs、llms.txt / llms-full.txt、API 索引 tim-smart effect-io-ai 仍是权威来源；v4 迁移见 effect-smol 与 LLMS.md。
v4 beta 曾短暂使用 ServiceMap，2026-04-07 已改回 Context；若资料里出现旧名，按当前 Context API 理解。
HTTP API、OTLP、Schema 解析等子系统在 v4 有对象式 endpoint 定义、默认 defect 行为等差异，写服务端代码前应对照 http / observability 类 reference，勿照搬 v3 管道写法。

截图预览

使用场景

在存量服务里用 Effect 写带超时与退避重试的 HTTP 调用，需按 package.json 选用 v3 或 v4 的错误处理 API，并对照文档避免 Cache、Schema 等幻觉符号。
让 AI 生成 Effect.gen 与 Layer 组装代码前，先锁定 v3（Context.Tag）或 v4（Context.Service），防止同一 PR 里混用 catchAll 与 catch。
为 Node CLI 或 HTTP 服务写入口：用 NodeRuntime.runMain，把打开的文件、数据库连接放进 acquireRelease，并用 Effect.scoped 保证退出时释放。
把 async/await 业务迁到 Effect：把可预期失败建模进 E 通道，用 catchTag 分支处理；库代码只返回 Effect，在应用最外层再 runPromise。

适合人员

维护公司内 Effect v3 生产代码、需要审查 AI 补丁里并发、重试与错误 API 是否写错的后端工程师
正在试点 Effect v4 beta 新项目、要按 effect-smol 与 LLMS.md 统一 Context.Service 与 Schema.TaggedErrorClass 语法的 Tech Lead
在 Express 或 Hono 里嵌入 Effect、只能在中间件边界用 ManagedRuntime 执行、不能把 runPromise 散进业务模块的集成开发工程师
编写对外发布的 Effect 工具库、要求核心逻辑无 run*、依赖经 Tag/Layer 注入且资源用 Scope 管理的 TypeScript 库维护者

Effect TypeScript 工程指南