effect-ts

Effect 4

根据项目本地架构、最相关的参考资料，以及与目标已安装软件包相匹配的源代码，应用 Effect 4 语义。

工作流

不要仅因某个文件导入了 effect 就启用此工作流。对于非平凡的 Effect 工作：

1. 确认目标软件包或工作区，以及其确切安装的 effect 和相关 @effect/* 版本。如果 effect 不是 4.x，请停止，因为此技能不适用。对于 3.x，请告知用户改用 v3 技能： npx skills add PaulRBerg/agent-skills#shelved --skill effect-ts-v3。
2. 确认版本同步：每个 @effect/* 软件包的版本都必须与已安装的 effect 版本完全一致。发现不匹配时应报告，而不是试图绕过问题编写代码。
3. 检查相邻的服务、层、错误、模式、运行时边界和测试。项目本地惯例决定组织方式，已安装软件包的证据决定 API 事实。
4. 阅读 references/critical-rules.md，然后只阅读下方与任务相关的参考资料。
5. 编辑前，针对目标工作区可见的软件包安装，核实所有不确定的导入、签名或行为。不要凭记忆套用 v3 名称。许多名称已更改或移除。
6. 实施与项目一致的最小模式，并运行覆盖已更改语义的最小范围测试或类型检查。

证据顺序

使用目标工作区的清单和锁文件来确定版本。优先顺序如下：

1. 已安装软件包的 src/、README、测试和变更日志。
2. 未随软件包提供源代码时，查阅其生成的声明文件。
3. 匹配的官方软件包或源代码标签。

对于单体仓库源代码、测试或跨软件包搜索，请运行 scripts/effect-source.sh。该脚本会将 Effect-TS/effect 的克隆缓存固定在最新发行版；每 24 小时最多获取一次，否则重用缓存，并打印 path= 和 release=。当 release 与已安装的 effect 版本不同时，不要切换检出状态，直接读取匹配的标签：git -C <path> grep <pattern> effect@<version> -- packages/ 或 git -C <path> show effect@<version>:<file>。切勿编辑缓存。

不要仅为获取文档而安装或更新依赖。不要信任 v3 示例或与目标已安装版本不匹配的源代码。如果无法核实确切行为，请停止，不要猜测。

以前的 @effect/platform、@effect/rpc、@effect/cli、@effect/cluster 及相关模块现已包含在 effect 中，位于 effect/http、effect/http-api、effect/rpc、effect/cli、effect/ai、effect/sql、effect/schema、effect/reactivity 和 effect/workflow 等子路径下。请检查已安装的 package.json 中的 exports，以确认确切范围。这些模块标记为 @stability unstable，可能在次要版本中发生破坏性变更。不存在 effect/unstable/* 兼容路径。平台、驱动程序和提供方仍使用独立软件包：@effect/platform-*、@effect/sql-*、@effect/ai-*、@effect/atom-*、@effect/opentelemetry 和 @effect/vitest。这些软件包中的模块也标记为 @stability unstable。

从 4.0.2 起，每个模块和可直接导入的导出项都会声明 @stability。依赖某个 API 前请检查对应标签。stable 遵循严格的语义化版本规则。effect/graphql 等 experimental 模块，以及 effect/net 的部分内容，可能在补丁版本中发生破坏性变更。一些根模块也标记为 unstable，例如 Arbitrary、Crypto、FileSystem 和 Path。

Reference Router

任务	参考资料
Services、Layers、Context.Service、fn	references/services-layers.md
配置提供程序和机密	references/config.md
Schema、JSON Schema、编码后的错误／模型	references/schema-jsonschema.md
@effect/vitest、时钟、fiber、重试	references/testing.md
资源、调度、refs、并发	references/runtime.md
流和背压	references/streams.md
模式匹配和标记联合	references/pattern-matching.md
effect/ai 和 @effect/ai-*	references/ai.md
effect/sql 和 @effect/sql-*	references/sql.md
Next.js / @prb/effect-next	references/next-js.md
Effect Atom（effect/reactivity、@effect/atom-*）	references/effect-atom.md
可空边界处的 Option	references/option-null.md

对于 effect/http、effect/http-api、effect/rpc、effect/cli、集合工具、弃用项或构造函数查询，请直接检查已安装的软件包源码，而不要加载本地 API 清单。

边界

• 除非 Effect 边界能带来明确的依赖、可测试性、资源安全或错误模型方面的收益，否则应让纯辅助函数、常量和路径操作保持纯函数。
• 除非用户要求重新设计，否则应保留现有领域外观层以及服务／运行时边界。
• 在 IO 边界处，优先使用类型化失败和作用域资源。仅在需要编码或边界验证时，才选择基于 Schema 的错误／模型。
• 不要仅为替换一个小型平台调用而扩大环境要求。

对于变更，完成工作需要确保代码符合本地 Effect 架构、选定的参考资料，以及必要时查阅的已安装源码，并执行能够覆盖变更语义的最小范围测试／类型检查。只读工作需要提供支持结论的证据。已验证修改后，以 ### ⚡ Effect — ✅ change complete 结束；只读工作则以 ### ⚡ Effect — 🔎 reviewed, no files written 结束，并用一句话说明所用的边界或模式，再附上 ### 🧪 Verification 和精确的限定范围命令／结果。如果所需验证尚未完成，则使用 ### ⚡ Effect — ⛔ blocked。仅在存在不阻塞工作的注意事项时添加 ### ⚠️ Limitation。切勿修饰类型化错误、Schema 消息、日志、测试、生成的 JSON／API 响应或命令输出。