effect-ts

Effect-TS

概述

提供工作流、模式和最佳实践，帮助构建基于 Effect 的 TypeScript 程序，并重点介绍错误、依赖项、资源、运行时执行、生成器、架构、测试、平台模块、Sink/Stream 处理和 Effect AI。

主要文档和 API 来源：

• https://effect.website/llms.txt（面向大模型的主题索引）
• https://effect.website/docs
• https://effect.website/docs/platform
• https://effect.website/docs/ai/introduction
• https://effect.website/docs/additional-resources/api-reference
• https://tim-smart.github.io/effect-io-ai/（精简 API 列表）

进行内部查询时，可以使用 effect-docs MCP 搜索和获取 API 参考：https://github.com/tim-smart/effect-mcp。

渐进式披露

1. 从 references/docs-index.md 开始，查找相关主题。
2. 阅读一份与任务相关的主要指南。
3. 仅在需要时阅读一份相关指南（用于处理测试、运行时或可观测性等横切问题）。
4. 避免加载无关参考资料。

快速分流

• 如果需要核心 Effect 数据类型或组合子，请打开 references/core-usage.md。
• 如果需要更广泛的数据类型选择（DateTime、BigDecimal、HashSet、Redacted），请打开 references/data-types-advanced.md。
• 如果需要相等性、顺序或哈希语义，请打开 references/behavior-traits.md。
• 如果任务涉及错误建模或类型化失败，请打开 references/error-management.md。
• 如果需要错误处理工具（沙箱、Cause、错误通道转换），请打开 references/error-tooling.md。
• 如果涉及服务或依赖项，请打开 references/dependency-management.md。
• 如果涉及层的构建或测试连接，请打开 references/layer-patterns.md。
• 如果涉及资源生命周期，请打开 references/resource-management.md。
• 如果涉及运行 Effect 或运行时选择，请打开 references/runtime-execution.md。
• 如果涉及 fiber 或并发原语，请打开 references/concurrency.md。
• 如果涉及中断、监督或 fiber 引用，请打开 references/concurrency-advanced.md。
• 如果涉及调度或重复执行，请打开 references/scheduling.md。
• 如果涉及重试、退避或调度组合，请打开 references/scheduling-retry.md。
• 如果涉及流、队列、发布订阅或 STM，请打开 references/streams-queues-stm.md。
• 如果涉及 HTTP 客户端或外部 API，请打开 references/http-client.md。
• 如果涉及 HTTP 服务端或 API 定义，请打开 references/http-server.md。
• 如果涉及请求批处理或数据加载器，请打开 references/request-resolver.md。
• 如果涉及缓存或记忆化，请打开 references/caching.md。
• 如果涉及配置或配置提供程序，请打开 references/configuration.md。
• 如果涉及高级配置或脱敏，请打开 references/configuration-advanced.md。
• 如果涉及日志、指标或追踪，请打开 references/observability.md。
• 如果需要具体的日志记录器、指标、追踪设置或导出器，请打开 references/observability-examples.md。
• 如果需要连接日志、指标或追踪层，请打开 references/observability-wiring.md。
• 如果需要提升顺序执行或分支逻辑的可读性，请打开 references/generators.md。
• 如果需要运行时验证或解码，请打开 references/schema.md。
• 如果涉及使用 reducer 消费流的模式，请打开 references/sink.md。
• 如果需要在测试中使用确定性时间，请打开 references/testing.md。
• 如果需要更全面的测试服务，请打开 references/testing-stack.md。
• 如果涉及命令、文件、路径、终端或键值模块，请打开 references/platform-primitives.md。
• 如果涉及通过 Effect AI 实现 LLM 工作流、规划或工具使用，请打开 references/ai.md。
• 如果涉及对包体积有限制的运行时，请打开 references/micro.md。
• 如果涉及从 Promise/async 迁移，请打开 references/migration-async.md。
• 如果需要了解版本控制或签名变更，请打开 references/versioning.md。
• 如果遇到常见陷阱或运行时错误，请打开 references/troubleshooting.md。
• 如果需要检查结果或进行调试，请打开 references/exit-cause.md。
• 如果需要根据 llms.txt 查找文档与指南的对应关系，请打开 references/docs-index.md。

核心工作流

1. 明确边界和 IO；将核心逻辑保留为 Effect 值。
2. 选择风格：简单组合使用管道；顺序逻辑使用 Effect.gen。
3. 明确建模错误：为预期错误指定类型；将缺陷视为意外失败。
4. 使用服务、标签和层为依赖项建模；让接口不受构造细节影响。
5. 打开或关闭资源时，使用 Scope 管理资源生命周期。
6. 通过层提供环境，并仅在程序边界运行 Effect。
7. 对于平台或基础设施代码，将副作用放在专用适配器中，并向领域代码提供类型化服务。
8. 对于 Agent 任务，简要说明错误、并发和运行时选择的理由。

输出标准

• 展示导入语句和最精简的可运行示例。
• 优先使用 barrel 导入（from "effect" / from "@effect/platform"），而不是深层模块路径。
• 使用函数式组合更清晰时，使用 effect 中的 pipe。
• 明确展示依赖关系图（服务、层、上下文标签）。
• 包含错误通道类型，并指出预期错误与缺陷错误。
• 避免在库中运行 effect；在入口点或测试中展示运行时用法。
• 优先提供可在当前 Effect 主版本下编译的示例。

Agent 质量检查清单

• 有助于设计决策时，注明目标形态为 Effect<A, E, R>。
• 明确区分预期错误（E）与缺陷。
• 指出提供层的位置，以及调用 run* 的位置。
• 对于并发代码，说明有界或无界行为，以及关闭策略。
• 对于边界解码，展示 Schema 的用法，以及处理失败的位置。
• 对于测试，注明提供了哪些测试服务（TestContext、TestClock、实时覆盖项）。
• 对于文档中的不确定之处，在最终确定 API 前查阅 references/docs-index.md 和源文档。

参考资料

• 从 references/docs-index.md 开始，快速选择相关指南。
• 大多数代码任务默认参考 references/core-usage.md、references/error-management.md 和 references/dependency-management.md。
• 对于边界和集成工作，使用平台/运行时参考资料（references/platform-primitives.md、references/runtime-execution.md）。
• 对于验证和调试，使用测试/诊断参考资料（references/testing.md、references/testing-stack.md、references/troubleshooting.md）。