effect-v4

Effect v4

CLI、@composio/cli-keyring 和 @composio/json-schema-to-effect-schema 均基于 Effect v4 运行。以下所有说明都以迁移后的源代码为依据，而非对 v3 的记忆。

精确版本矩阵

effect、@effect/platform-bun 和 @effect/vitest 固定为完全相同的精确版本 4.0.3——绝不使用 ^、@next，也不允许各软件包的版本不匹配。@effect/cli 和 @effect/platform 已不再作为依赖存在；它们的功能已整合到 effect 和 effect/* 中。完整矩阵（也包括 typescript、vitest）请参阅 versions.json。

接下来阅读

• references/core-patterns.md — 服务、层、类型化错误、Schema、如何在 Effect.gen 和 Effect.fn 之间选择、使用 Option 组合器代替 isSome 三元表达式、在测试中使用 TestClock 驱动时间（fork、adjust 直到 fiber 稳定，再 join），而非使用 it.live，以及 v3→v4 重命名对照表（标注为历史内容，供识别过时模式时参考）。
• references/cli-surface.md — effect/cli：Command、Flag、Argument、GlobalFlag、CliConfig、自定义 CliOutput.Formatter，以及 runner 的双重打印规则。
• references/upgrade-workflow.md — 升级到更新版本的操作步骤。

这些参考文档中的代码摘录均为来自真实且当前可编译的仓库文件的短引文（每处摘录均标明文件路径），并非独立示例。经过编译检查的权威依据始终是所引用的文件本身；如果文件与参考文档不一致，请以文件为准并修正参考文档。

必须遵守的事项

• 效果值使用 Effect.gen(function* () {...})——这是主要形式，包括具名模块常量；参数化辅助函数使用 (params) => Effect.gen(...)。Effect.fn(...) 是函数形式，其效果会携带堆栈帧注解（可选的名称字符串会为每次调用添加一个追踪 span），适用于服务成员和组合器回调，以便在错误报告中追溯来源。所有形式都会在每次执行时重新运行其主体。请参阅 core-patterns 中的“Effect.gen 与 Effect.fn”。
• 使用 Context.Service 定义服务，并显式定义 static readonly Default/layer 层，该层使用 Layer.succeed/Layer.effect/Layer.provide 构建。v4 不会自动为你生成层。
• 使用 Schema.TaggedError（或在不需要 Schema 字段时使用普通的 Data.TaggedError）对预期失败进行建模，并使用 Effect.catchTag/catchTags/Match 进行恢复，绝不手动比较 _tag 字符串。
• 使用 Effect.tryPromise({ try, catch }) 包装可能失败的 Promise；Effect.promise 会将拒绝转为 defect。在 Effect 工作流中不得使用 async/await 或 try/catch——ESLint 会在 ts/packages/cli/src 中禁止它们。
• 在依据 ts/vendor/effect（只读的源码参照——绝不编辑或从中导入）和已安装的 [email protected] 类型定义验证之前，必须假定记忆中的每个 v3 软件包名称和 API 都不正确。源代码可能领先于已发布的软件包；编译器是兼容性关卡。

验证

pnpm typecheck
pnpm --filter @composio/cli test

编辑此技能或其说明后，运行 pnpm validate:agent-skills 和 pnpm validate:skill-routing，并使用固定的软件包版本编译此技能以及 typescript-testing/references/effect-v4-cli.md 中的 TypeScript 代码块：

node .agents/skills/effect-v4/scripts/check-examples.mjs

引用仓库文件且导入无法解析的代码块，其 fence 信息字符串应包含 no-check。