1. 从 Promise 到 Effect为什么模型调用需要 Schema.Class 与 Layer如果你写过调用大模型 API 的 TypeScript 代码大概率写过这样的函数从环境变量读 API Key拼一个 fetch 请求解析 JSON把结果返回。单文件跑起来没问题但当项目里出现第三个模型供应商、第五个调用点时问题就来了——Key 散落在各处、错误类型全是 unknown、超时和取消没人管、测试时得手动 mock 全局 fetch。Effect-ts 这套框架解决的正是这类工程化问题。它用一个EffectA, E, R三元组把「成功值、错误类型、依赖服务」绑在类型签名里编译器会盯着你有没有漏掉某条错误路径、有没有忘记提供某个依赖。而 TaoToken 提供的统一 Key 与 API 通道恰好适合作为这套模式里的一个 Service你只需要声明一个Context.Service标签用Layer.effect把 HTTP 调用封装进去业务代码里yield*一下就能拿到模型返回Key 从哪来、超时怎么处理、错误怎么归类全部收敛在一个 Layer 里。这篇内容面向已经会写 TypeScript、但对 Effect-ts 还停留在「看得懂 import 但不敢改」阶段的开发者。我会把 Schema.Class、Context.Service、Layer、Effect.fn 四个模式拆开讲每个都配可复制的代码最后用 TaoToken 的 API 通道串成一个能本地跑通的模型调用示例。你不需要先精通函数式编程跟着敲一遍就能理解每个抽象在解决什么问题。先说清楚 TaoToken 在这里扮演的角色它是一个兼容 OpenAI 风格接口的统一通道官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。你拿到一个 Key 之后就可以用同一个 Base URL 调用不同模型省去为每个供应商维护一套配置的麻烦。下面的代码里我会把它封装成一个ModelClientService用 Layer 管理它的生命周期。在动手之前先明确四个模式各自的位置Schema.Class 负责「数据长什么样」Context.Service 负责「这个能力叫什么名字」Layer 负责「这个名字背后是谁来实现」Effect.fn 负责「把一段异步逻辑包装成可追踪、可组合的 Effect」。四者串起来就是一条从配置读取到模型调用的完整链路。2. TaoToken 前置准备拿到 Key 与 Base URL在写 Effect 代码之前得先把外部依赖准备好。这一步不复杂但有几个细节容易踩坑我按顺序说。首先是账号与 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key。创建时建议给它起一个能看出用途的名字比如effect-demo-local这样以后在控制台里排查哪个 Key 在跑量会方便很多。Key 只在创建时完整显示一次复制后先存到本地临时文件别直接贴进聊天窗口或提交到 Git。拿到 Key 之后你需要确认两件事Base URL 和 Model ID。Base URL 用 https://taotoken.net/api 注意这里不带任何查询参数SDK 会自动在它后面拼/v1/chat/completions这类路径。Model ID 则取决于你想调用的模型可以在 https://taotoken.net/doc 的模型列表里查也可以直接在 https://taotoken.net/console 的模型对话页面里试。本文示例统一用一个通用对话模型 ID你替换成自己账号下可用的即可。接下来是环境变量。Effect-ts 的 Config 模块可以直接从环境变量读配置所以我把 Key 和 Base URL 都放进.env或 shell 环境里。本地开发时我习惯在项目根目录建一个.env文件内容大致是这样TAOTOKEN_API_KEYsk-你的实际Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELgpt-4o-mini注意.env一定要加进.gitignore。我见过有人把 Key 提交到公开仓库几分钟内就被扫走刷量这个坑没必要踩。如果你用 Node.js 20 以上可以用node --env-file.env直接加载不需要额外装 dotenv。然后是项目初始化。新建一个目录装三个依赖mkdir effect-taotoken-demo cd effect-taotoken-demo npm init -y npm install effect npm install -D typescript tsx types/node npx tsc --init --target ES2022 --module NodeNext --moduleResolution NodeNext --stricteffect是主包tsx用来直接跑 TypeScript 文件省去编译步骤。tsconfig.json里建议把strict打开因为 Effect-ts 的类型推导在严格模式下才最准确关掉 strict 反而会遇到一些莫名其妙的类型报错。最后确认一下网络出口。TaoToken 的 API 是标准 HTTPS 接口只要你的运行环境能正常访问外网 HTTPS 即可不需要任何额外配置。如果你在公司内网确认代理设置走的是系统环境变量Node.js 的 fetch 会自动读取。准备到这里就够了。下面进入代码部分我会先定义 Schema.Class再声明 Context.Service然后用 Layer 把 TaoToken 的调用封装进去。3. 可复制配置Schema.Class、Context.Service 与 Layer 三件套这一节是全文的核心我会把四个模式的代码完整写出来你可以直接复制到src/main.ts里跑。为了让你看清每个部分的边界我按「数据定义 → 服务声明 → 实现绑定 → 业务包装」的顺序来。3.1 Schema.Class 定义请求与响应结构先定义模型调用的输入输出。Schema.Class 的好处是它同时给你编译时类型和运行时校验外部数据进来时不会带着脏字段一路往下传。import { Schema } from effect // 单条消息 export class ChatMessage extends Schema.ClassChatMessage(ChatMessage)({ role: Schema.Literal(system, user, assistant), content: Schema.NonEmptyString, }) {} // 请求体 export class ChatRequest extends Schema.ClassChatRequest(ChatRequest)({ model: Schema.NonEmptyString, messages: Schema.Array(ChatMessage), temperature: Schema.optionalWith(Schema.Number, { default: () 0.7 }), }) {} // 响应里我们只关心需要的字段 export class ChatChoice extends Schema.ClassChatChoice(ChatChoice)({ index: Schema.Number, message: ChatMessage, }) {} export class ChatResponse extends Schema.ClassChatResponse(ChatResponse)({ id: Schema.String, model: Schema.String, choices: Schema.Array(ChatChoice), }) {}注意Schema.ClassChatMessage(ChatMessage)这个双写模式尖括号里是 TypeScript 类型参数括号里的字符串是运行时标识符。Schema 校验失败时错误信息里会带上ChatMessage这个名字方便定位是哪个结构出的问题。Schema.NonEmptyString会在运行时检查字符串 trim 后长度大于 0比裸string多一层保护。3.2 Context.Service 声明模型客户端标签接下来声明一个服务标签代表「能发模型请求的东西」。这里用Context.Service而不是低阶的Context.Tag因为它自带layer静态属性的类型约束配合 Layer 更顺手。import { Context, Effect, Layer } from effect export class ModelClient extends Context.Service ModelClient, { readonly chat: (req: ChatRequest) Effect.EffectChatResponse, ModelError } ()(app/ModelClient) {}Context.ServiceSelf, Value的两个类型参数Self是标签自身的类型Value是运行时实际拿到的对象类型。yield* ModelClient时编译器推导出的类型就是Value那个结构。括号里的app/ModelClient是运行时容器里的唯一键建议用命名空间前缀避免冲突。3.3 定义错误类型Effect 的错误是显式类型所以先定义模型调用可能抛出的错误。用Schema.TaggedError可以让错误也带上结构化数据。import { Schema } from effect export class ModelError extends Schema.TaggedErrorModelError()( ModelError, { reason: Schema.Literal(network, auth, rate_limit, parse, unknown), message: Schema.String, status: Schema.optional(Schema.Number), } ) {}reason用字面量联合调用方可以catchTag或按 reason 分支处理。auth对应 401rate_limit对应 429parse对应响应体解析失败network对应 fetch 本身抛错。3.4 Layer.effect 绑定 TaoToken 实现现在把标签绑定到具体实现。这里读环境变量、拼请求、解析响应全部封装在一个 Layer 里。import { Config, Effect, Layer, Redacted } from effect export const ModelClientLive Layer.effect( ModelClient, Effect.gen(function* () { const apiKey yield* Config.redacted(TAOTOKEN_API_KEY) const baseUrl yield* Config.string(TAOTOKEN_BASE_URL).pipe( Config.withDefault(https://taotoken.net/api) ) const chat (req: ChatRequest) Effect.gen(function* () { const body yield* Schema.encode(ChatRequest)(req) const response yield* Effect.tryPromise({ try: () fetch(${baseUrl}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${Redacted.value(apiKey)}, }, body: JSON.stringify(body), }), catch: (cause) new ModelError({ reason: network, message: fetch failed: ${String(cause)}, }), }) if (!response.ok) { const text yield* Effect.promise(() response.text()) const reason response.status 401 ? auth : response.status 429 ? rate_limit : unknown return yield* new ModelError({ reason, message: text.slice(0, 200), status: response.status, }) } const json yield* Effect.tryPromise({ try: () response.json(), catch: () new ModelError({ reason: parse, message: invalid JSON body }), }) return yield* Schema.decodeUnknown(ChatResponse)(json).pipe( Effect.mapError( (issue) new ModelError({ reason: parse, message: schema mismatch: ${issue.message}, }) ) ) }) return { chat } }) )几个关键点。Config.redacted读出来的 Key 是Redactedstring类型打印时不会泄露明文用的时候要Redacted.value解包。Schema.encode(ChatRequest)把类实例转成普通对象因为JSON.stringify对类实例只会序列化自有属性虽然这里能work但显式 encode 更稳。Effect.tryPromise把 fetch 的 Promise 桥接进 Effect 世界catch返回的是 typed error不是 unknown。3.5 Effect.fn 包装业务逻辑最后用Effect.fn把一段业务逻辑命名包装方便追踪和复用。export const askOnce Effect.fn(askOnce)(function* (prompt: string) { const client yield* ModelClient const res yield* client.chat( new ChatRequest({ model: process.env.TAOTOKEN_MODEL ?? gpt-4o-mini, messages: [new ChatMessage({ role: user, content: prompt })], }) ) return res.choices[0]?.message.content ?? })Effect.fn(askOnce)给这个 Effect 一个可读名字日志和追踪里能看到askOnce出现在调用链中。yield* ModelClient从容器里取服务编译器会检查你有没有在最终 Layer 里提供它。3.6 组装 Layer 并运行把上面的部分拼起来用Layer.provide把实现喂给业务再用ManagedRuntime或Effect.runPromise跑起来。import { Effect, Layer } from effect const AppLayer ModelClientLive const program Effect.gen(function* () { const answer yield* askOnce(用一句话解释 Effect-ts 的 Layer 是什么) console.log(模型返回:, answer) }) Effect.runPromise(program.pipe(Effect.provide(AppLayer))).catch((err) { console.error(运行失败:, err) })如果你有多个 Service用Layer.mergeAll(A, B, C)合并即可。Layer.provide的作用是「用某个 Layer 的产出去填另一个 Layer 的依赖」填完之后依赖就从类型里消失了。4. 验证请求本地跑通与成功结果代码写完了现在跑起来验证。这一步我会给出完整命令和预期输出你对照着看。先确认环境变量已加载。如果你用tsx可以这样跑TAOTOKEN_API_KEYsk-你的Key \ TAOTOKEN_BASE_URLhttps://taotoken.net/api \ TAOTOKEN_MODELgpt-4o-mini \ npx tsx src/main.ts或者用node --env-file.env配合编译后的 JS。跑通的话终端会打印类似模型返回: Effect-ts 的 Layer 是一个可组合的依赖注入描述它声明了「产出什么服务、可能出什么错、依赖哪些其他服务」运行时按依赖顺序解析并构建。如果模型返回内容和你预期不同先别急着改代码用 curl 单独验证一下 Key 和 Base URL 是否可用curl -s https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] } | head -c 500curl 能返回正常 JSON说明通道没问题问题在 Effect 代码里curl 也报错那就是 Key 或模型 ID 的问题。这个二分法能帮你快速定位。再验证一下 Schema 校验是否生效。故意传一个空 contentconst bad new ChatMessage({ role: user, content: })TypeScript 编译期不会拦你因为NonEmptyString的 brand 在构造时不一定触发但运行时Schema.decodeUnknown会抛 ParseError。你可以在chat函数里加一行yield* Schema.decode(ChatMessage)(req.messages[0])来强制校验。验证 Layer 依赖是否完整有个小技巧把Effect.runPromise(program)里的Effect.provide(AppLayer)删掉编译器会报ModelClient未提供。这就是 Effect-ts 相比手动传参的价值——依赖缺失在编译期就暴露不用等到运行时。最后验证错误分支。把 Key 改成一个错误值再跑应该看到运行失败: ModelError: { reason: auth, message: ..., status: 401 }这说明Effect.tryPromise的 catch 和!response.ok分支都正常工作。错误类型是结构化的调用方可以按 reason 做不同处理比如 auth 错误提示用户重新配置 Keyrate_limit 错误做退避重试。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节列出我实际遇到过的几类报错以及对应的排查路径。每条都给出真实错误信息和修复方式。401 Unauthorized / invalid api key。最常见原因是 Key 没读到或读错了。先确认Config.redacted(TAOTOKEN_API_KEY)读的环境变量名和你设置的一致大小写敏感。如果用的是.env文件确认加载方式正确——tsx不会自动读.env得用node --env-file或手动process.env。还有一种情况是 Key 复制时带了首尾空格Redacted.value解出来带空格请求头就非法了。修复在 Layer 里加.trim()或者创建 Key 时仔细复制。local proxy failed / ECONNREFUSED。这个报错通常出现在你本地设置了 HTTP 代理但代理进程没起来。Node.js 的 fetch 会读HTTP_PROXY/HTTPS_PROXY环境变量。如果你不需要代理把这两个变量清掉再跑unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy如果你确实需要走代理确认代理地址和端口正确且代理进程在运行。注意 TaoToken 的 API 是标准 HTTPS不需要特殊网络配置。Cannot read properties of undefined (reading choices)。这个报错说明response.json()返回的结构和ChatResponse不匹配但你在解析前就访问了choices。根因通常是 API 返回了错误结构比如{ error: {...} }而你的代码没检查response.ok就直接解析。修复确保!response.ok分支在解析前返回并且用Schema.decodeUnknown(ChatResponse)做结构校验校验失败会走parse错误分支而不是崩溃。OAuth / token expired。如果你用的是某些需要 OAuth 的模型通道可能会遇到 token 过期。TaoToken 的 API Key 是长期有效的不存在 OAuth 刷新问题。如果你在代码里混用了其他供应商的 OAuth 逻辑确认请求头用的是Authorization: Bearer apiKey而不是Bearer oauthToken。两者格式一样但来源不同混用会 401。Schema decode 报 ParseError 但字段看起来没问题。检查Schema.optionalWith的默认值写法。Schema.optionalWith(Schema.Number, { default: () 0.7 })在字段缺失时给默认值但如果字段存在且为null它不会用默认值会报错。如果 API 可能返回null用Schema.NullOr(Schema.Number)包一层。Layer 依赖循环。如果你把两个互相依赖的 Service 用Layer.provide连起来编译器会报类型错误因为R参数无法收敛到never。修复把共享的依赖抽成第三个 Layer两边都 provide 它而不是互相 provide。排查时有个通用思路先用 curl 验证外部通道再用最小 Effect 程序验证 Layer 组装最后才怀疑业务逻辑。大部分问题出在前两步。6. 把模型调用沉淀为可组合的 Layer下一步怎么走到这里你已经有了一个能跑的模型调用 Service。但真正的工程化落地是把这套模式扩展到多个 Service 并组合起来。我给你几条实际可走的路径。第一条路径是加缓存。模型调用有成本同样的 prompt 没必要重复请求。你可以写一个CacheService用Context.Service声明用Layer.effect实现一个内存 Map 或 Redis 客户端然后在askOnce里yield* CacheService先查缓存。Layer 的组合让这件事很自然Layer.mergeAll(ModelClientLive, CacheLive)之后两个服务都能在业务代码里yield*。第二条路径是加重试与退避。Effect-ts 内置了Effect.retry和Schedule你可以给client.chat包一层const resilientChat (req: ChatRequest) client.chat(req).pipe( Effect.retry({ while: (e) e.reason rate_limit || e.reason network, schedule: Schedule.exponential(500 millis).pipe( Schedule.compose(Schedule.recurs(3)) ), }) )这样 429 和网络错误会自动重试三次指数退避。注意while条件只对可重试的错误生效auth 错误不会重试避免无意义请求。第三条路径是把配置也做成 Layer。现在TAOTOKEN_MODEL是直接读process.env更规范的做法是定义一个AppConfigService用Config.all组合多个配置项再用Layer.effect提供。这样测试时可以轻松替换成固定配置不用改环境变量。如果你打算长期在项目里用这套模式建议把ModelClient、CacheService、AppConfig都放在独立的services/目录每个文件导出一个Layer最后在一个app-layer.ts里用Layer.mergeAll汇总。业务代码只依赖Context.Service标签不依赖具体实现测试时用Layer.succeed提供 mock 即可。关于 TaoToken 的进一步用法模型对话页面在 https://taotoken.net/model-chat 接入文档在 https://taotoken.net/doc API Key 管理在 https://taotoken.net/api-keys 。如果你要把这套模式用到长期编码或 Agent 场景可以看看 Coding Planhttps://taotoken.net/coding-plan 。Claude Code 相关的接入配置在 https://taotoken.net/claude-code 。最后留一个我踩过的坑Effect.fn包装的函数在递归调用时如果递归深度很大注意Effect.sleep的调度点会累积。我在一个轮询场景里递归了 60 次每次 sleep 2 秒整体耗时符合预期但如果你需要更精细的控制用Effect.iterate或Schedule替代手写递归会更清晰。 Effect-ts 四大核心模式详解：Schema.Class、Context、Layer、Effect.fn 与 TaoToken 统一接入
1. 从 Promise 到 Effect为什么模型调用需要 Schema.Class 与 Layer如果你写过调用大模型 API 的 TypeScript 代码大概率写过这样的函数从环境变量读 API Key拼一个 fetch 请求解析 JSON把结果返回。单文件跑起来没问题但当项目里出现第三个模型供应商、第五个调用点时问题就来了——Key 散落在各处、错误类型全是 unknown、超时和取消没人管、测试时得手动 mock 全局 fetch。Effect-ts 这套框架解决的正是这类工程化问题。它用一个EffectA, E, R三元组把「成功值、错误类型、依赖服务」绑在类型签名里编译器会盯着你有没有漏掉某条错误路径、有没有忘记提供某个依赖。而 TaoToken 提供的统一 Key 与 API 通道恰好适合作为这套模式里的一个 Service你只需要声明一个Context.Service标签用Layer.effect把 HTTP 调用封装进去业务代码里yield*一下就能拿到模型返回Key 从哪来、超时怎么处理、错误怎么归类全部收敛在一个 Layer 里。这篇内容面向已经会写 TypeScript、但对 Effect-ts 还停留在「看得懂 import 但不敢改」阶段的开发者。我会把 Schema.Class、Context.Service、Layer、Effect.fn 四个模式拆开讲每个都配可复制的代码最后用 TaoToken 的 API 通道串成一个能本地跑通的模型调用示例。你不需要先精通函数式编程跟着敲一遍就能理解每个抽象在解决什么问题。先说清楚 TaoToken 在这里扮演的角色它是一个兼容 OpenAI 风格接口的统一通道官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。你拿到一个 Key 之后就可以用同一个 Base URL 调用不同模型省去为每个供应商维护一套配置的麻烦。下面的代码里我会把它封装成一个ModelClientService用 Layer 管理它的生命周期。在动手之前先明确四个模式各自的位置Schema.Class 负责「数据长什么样」Context.Service 负责「这个能力叫什么名字」Layer 负责「这个名字背后是谁来实现」Effect.fn 负责「把一段异步逻辑包装成可追踪、可组合的 Effect」。四者串起来就是一条从配置读取到模型调用的完整链路。2. TaoToken 前置准备拿到 Key 与 Base URL在写 Effect 代码之前得先把外部依赖准备好。这一步不复杂但有几个细节容易踩坑我按顺序说。首先是账号与 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key。创建时建议给它起一个能看出用途的名字比如effect-demo-local这样以后在控制台里排查哪个 Key 在跑量会方便很多。Key 只在创建时完整显示一次复制后先存到本地临时文件别直接贴进聊天窗口或提交到 Git。拿到 Key 之后你需要确认两件事Base URL 和 Model ID。Base URL 用 https://taotoken.net/api 注意这里不带任何查询参数SDK 会自动在它后面拼/v1/chat/completions这类路径。Model ID 则取决于你想调用的模型可以在 https://taotoken.net/doc 的模型列表里查也可以直接在 https://taotoken.net/console 的模型对话页面里试。本文示例统一用一个通用对话模型 ID你替换成自己账号下可用的即可。接下来是环境变量。Effect-ts 的 Config 模块可以直接从环境变量读配置所以我把 Key 和 Base URL 都放进.env或 shell 环境里。本地开发时我习惯在项目根目录建一个.env文件内容大致是这样TAOTOKEN_API_KEYsk-你的实际Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELgpt-4o-mini注意.env一定要加进.gitignore。我见过有人把 Key 提交到公开仓库几分钟内就被扫走刷量这个坑没必要踩。如果你用 Node.js 20 以上可以用node --env-file.env直接加载不需要额外装 dotenv。然后是项目初始化。新建一个目录装三个依赖mkdir effect-taotoken-demo cd effect-taotoken-demo npm init -y npm install effect npm install -D typescript tsx types/node npx tsc --init --target ES2022 --module NodeNext --moduleResolution NodeNext --stricteffect是主包tsx用来直接跑 TypeScript 文件省去编译步骤。tsconfig.json里建议把strict打开因为 Effect-ts 的类型推导在严格模式下才最准确关掉 strict 反而会遇到一些莫名其妙的类型报错。最后确认一下网络出口。TaoToken 的 API 是标准 HTTPS 接口只要你的运行环境能正常访问外网 HTTPS 即可不需要任何额外配置。如果你在公司内网确认代理设置走的是系统环境变量Node.js 的 fetch 会自动读取。准备到这里就够了。下面进入代码部分我会先定义 Schema.Class再声明 Context.Service然后用 Layer 把 TaoToken 的调用封装进去。3. 可复制配置Schema.Class、Context.Service 与 Layer 三件套这一节是全文的核心我会把四个模式的代码完整写出来你可以直接复制到src/main.ts里跑。为了让你看清每个部分的边界我按「数据定义 → 服务声明 → 实现绑定 → 业务包装」的顺序来。3.1 Schema.Class 定义请求与响应结构先定义模型调用的输入输出。Schema.Class 的好处是它同时给你编译时类型和运行时校验外部数据进来时不会带着脏字段一路往下传。import { Schema } from effect // 单条消息 export class ChatMessage extends Schema.ClassChatMessage(ChatMessage)({ role: Schema.Literal(system, user, assistant), content: Schema.NonEmptyString, }) {} // 请求体 export class ChatRequest extends Schema.ClassChatRequest(ChatRequest)({ model: Schema.NonEmptyString, messages: Schema.Array(ChatMessage), temperature: Schema.optionalWith(Schema.Number, { default: () 0.7 }), }) {} // 响应里我们只关心需要的字段 export class ChatChoice extends Schema.ClassChatChoice(ChatChoice)({ index: Schema.Number, message: ChatMessage, }) {} export class ChatResponse extends Schema.ClassChatResponse(ChatResponse)({ id: Schema.String, model: Schema.String, choices: Schema.Array(ChatChoice), }) {}注意Schema.ClassChatMessage(ChatMessage)这个双写模式尖括号里是 TypeScript 类型参数括号里的字符串是运行时标识符。Schema 校验失败时错误信息里会带上ChatMessage这个名字方便定位是哪个结构出的问题。Schema.NonEmptyString会在运行时检查字符串 trim 后长度大于 0比裸string多一层保护。3.2 Context.Service 声明模型客户端标签接下来声明一个服务标签代表「能发模型请求的东西」。这里用Context.Service而不是低阶的Context.Tag因为它自带layer静态属性的类型约束配合 Layer 更顺手。import { Context, Effect, Layer } from effect export class ModelClient extends Context.Service ModelClient, { readonly chat: (req: ChatRequest) Effect.EffectChatResponse, ModelError } ()(app/ModelClient) {}Context.ServiceSelf, Value的两个类型参数Self是标签自身的类型Value是运行时实际拿到的对象类型。yield* ModelClient时编译器推导出的类型就是Value那个结构。括号里的app/ModelClient是运行时容器里的唯一键建议用命名空间前缀避免冲突。3.3 定义错误类型Effect 的错误是显式类型所以先定义模型调用可能抛出的错误。用Schema.TaggedError可以让错误也带上结构化数据。import { Schema } from effect export class ModelError extends Schema.TaggedErrorModelError()( ModelError, { reason: Schema.Literal(network, auth, rate_limit, parse, unknown), message: Schema.String, status: Schema.optional(Schema.Number), } ) {}reason用字面量联合调用方可以catchTag或按 reason 分支处理。auth对应 401rate_limit对应 429parse对应响应体解析失败network对应 fetch 本身抛错。3.4 Layer.effect 绑定 TaoToken 实现现在把标签绑定到具体实现。这里读环境变量、拼请求、解析响应全部封装在一个 Layer 里。import { Config, Effect, Layer, Redacted } from effect export const ModelClientLive Layer.effect( ModelClient, Effect.gen(function* () { const apiKey yield* Config.redacted(TAOTOKEN_API_KEY) const baseUrl yield* Config.string(TAOTOKEN_BASE_URL).pipe( Config.withDefault(https://taotoken.net/api) ) const chat (req: ChatRequest) Effect.gen(function* () { const body yield* Schema.encode(ChatRequest)(req) const response yield* Effect.tryPromise({ try: () fetch(${baseUrl}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${Redacted.value(apiKey)}, }, body: JSON.stringify(body), }), catch: (cause) new ModelError({ reason: network, message: fetch failed: ${String(cause)}, }), }) if (!response.ok) { const text yield* Effect.promise(() response.text()) const reason response.status 401 ? auth : response.status 429 ? rate_limit : unknown return yield* new ModelError({ reason, message: text.slice(0, 200), status: response.status, }) } const json yield* Effect.tryPromise({ try: () response.json(), catch: () new ModelError({ reason: parse, message: invalid JSON body }), }) return yield* Schema.decodeUnknown(ChatResponse)(json).pipe( Effect.mapError( (issue) new ModelError({ reason: parse, message: schema mismatch: ${issue.message}, }) ) ) }) return { chat } }) )几个关键点。Config.redacted读出来的 Key 是Redactedstring类型打印时不会泄露明文用的时候要Redacted.value解包。Schema.encode(ChatRequest)把类实例转成普通对象因为JSON.stringify对类实例只会序列化自有属性虽然这里能work但显式 encode 更稳。Effect.tryPromise把 fetch 的 Promise 桥接进 Effect 世界catch返回的是 typed error不是 unknown。3.5 Effect.fn 包装业务逻辑最后用Effect.fn把一段业务逻辑命名包装方便追踪和复用。export const askOnce Effect.fn(askOnce)(function* (prompt: string) { const client yield* ModelClient const res yield* client.chat( new ChatRequest({ model: process.env.TAOTOKEN_MODEL ?? gpt-4o-mini, messages: [new ChatMessage({ role: user, content: prompt })], }) ) return res.choices[0]?.message.content ?? })Effect.fn(askOnce)给这个 Effect 一个可读名字日志和追踪里能看到askOnce出现在调用链中。yield* ModelClient从容器里取服务编译器会检查你有没有在最终 Layer 里提供它。3.6 组装 Layer 并运行把上面的部分拼起来用Layer.provide把实现喂给业务再用ManagedRuntime或Effect.runPromise跑起来。import { Effect, Layer } from effect const AppLayer ModelClientLive const program Effect.gen(function* () { const answer yield* askOnce(用一句话解释 Effect-ts 的 Layer 是什么) console.log(模型返回:, answer) }) Effect.runPromise(program.pipe(Effect.provide(AppLayer))).catch((err) { console.error(运行失败:, err) })如果你有多个 Service用Layer.mergeAll(A, B, C)合并即可。Layer.provide的作用是「用某个 Layer 的产出去填另一个 Layer 的依赖」填完之后依赖就从类型里消失了。4. 验证请求本地跑通与成功结果代码写完了现在跑起来验证。这一步我会给出完整命令和预期输出你对照着看。先确认环境变量已加载。如果你用tsx可以这样跑TAOTOKEN_API_KEYsk-你的Key \ TAOTOKEN_BASE_URLhttps://taotoken.net/api \ TAOTOKEN_MODELgpt-4o-mini \ npx tsx src/main.ts或者用node --env-file.env配合编译后的 JS。跑通的话终端会打印类似模型返回: Effect-ts 的 Layer 是一个可组合的依赖注入描述它声明了「产出什么服务、可能出什么错、依赖哪些其他服务」运行时按依赖顺序解析并构建。如果模型返回内容和你预期不同先别急着改代码用 curl 单独验证一下 Key 和 Base URL 是否可用curl -s https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] } | head -c 500curl 能返回正常 JSON说明通道没问题问题在 Effect 代码里curl 也报错那就是 Key 或模型 ID 的问题。这个二分法能帮你快速定位。再验证一下 Schema 校验是否生效。故意传一个空 contentconst bad new ChatMessage({ role: user, content: })TypeScript 编译期不会拦你因为NonEmptyString的 brand 在构造时不一定触发但运行时Schema.decodeUnknown会抛 ParseError。你可以在chat函数里加一行yield* Schema.decode(ChatMessage)(req.messages[0])来强制校验。验证 Layer 依赖是否完整有个小技巧把Effect.runPromise(program)里的Effect.provide(AppLayer)删掉编译器会报ModelClient未提供。这就是 Effect-ts 相比手动传参的价值——依赖缺失在编译期就暴露不用等到运行时。最后验证错误分支。把 Key 改成一个错误值再跑应该看到运行失败: ModelError: { reason: auth, message: ..., status: 401 }这说明Effect.tryPromise的 catch 和!response.ok分支都正常工作。错误类型是结构化的调用方可以按 reason 做不同处理比如 auth 错误提示用户重新配置 Keyrate_limit 错误做退避重试。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节列出我实际遇到过的几类报错以及对应的排查路径。每条都给出真实错误信息和修复方式。401 Unauthorized / invalid api key。最常见原因是 Key 没读到或读错了。先确认Config.redacted(TAOTOKEN_API_KEY)读的环境变量名和你设置的一致大小写敏感。如果用的是.env文件确认加载方式正确——tsx不会自动读.env得用node --env-file或手动process.env。还有一种情况是 Key 复制时带了首尾空格Redacted.value解出来带空格请求头就非法了。修复在 Layer 里加.trim()或者创建 Key 时仔细复制。local proxy failed / ECONNREFUSED。这个报错通常出现在你本地设置了 HTTP 代理但代理进程没起来。Node.js 的 fetch 会读HTTP_PROXY/HTTPS_PROXY环境变量。如果你不需要代理把这两个变量清掉再跑unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy如果你确实需要走代理确认代理地址和端口正确且代理进程在运行。注意 TaoToken 的 API 是标准 HTTPS不需要特殊网络配置。Cannot read properties of undefined (reading choices)。这个报错说明response.json()返回的结构和ChatResponse不匹配但你在解析前就访问了choices。根因通常是 API 返回了错误结构比如{ error: {...} }而你的代码没检查response.ok就直接解析。修复确保!response.ok分支在解析前返回并且用Schema.decodeUnknown(ChatResponse)做结构校验校验失败会走parse错误分支而不是崩溃。OAuth / token expired。如果你用的是某些需要 OAuth 的模型通道可能会遇到 token 过期。TaoToken 的 API Key 是长期有效的不存在 OAuth 刷新问题。如果你在代码里混用了其他供应商的 OAuth 逻辑确认请求头用的是Authorization: Bearer apiKey而不是Bearer oauthToken。两者格式一样但来源不同混用会 401。Schema decode 报 ParseError 但字段看起来没问题。检查Schema.optionalWith的默认值写法。Schema.optionalWith(Schema.Number, { default: () 0.7 })在字段缺失时给默认值但如果字段存在且为null它不会用默认值会报错。如果 API 可能返回null用Schema.NullOr(Schema.Number)包一层。Layer 依赖循环。如果你把两个互相依赖的 Service 用Layer.provide连起来编译器会报类型错误因为R参数无法收敛到never。修复把共享的依赖抽成第三个 Layer两边都 provide 它而不是互相 provide。排查时有个通用思路先用 curl 验证外部通道再用最小 Effect 程序验证 Layer 组装最后才怀疑业务逻辑。大部分问题出在前两步。6. 把模型调用沉淀为可组合的 Layer下一步怎么走到这里你已经有了一个能跑的模型调用 Service。但真正的工程化落地是把这套模式扩展到多个 Service 并组合起来。我给你几条实际可走的路径。第一条路径是加缓存。模型调用有成本同样的 prompt 没必要重复请求。你可以写一个CacheService用Context.Service声明用Layer.effect实现一个内存 Map 或 Redis 客户端然后在askOnce里yield* CacheService先查缓存。Layer 的组合让这件事很自然Layer.mergeAll(ModelClientLive, CacheLive)之后两个服务都能在业务代码里yield*。第二条路径是加重试与退避。Effect-ts 内置了Effect.retry和Schedule你可以给client.chat包一层const resilientChat (req: ChatRequest) client.chat(req).pipe( Effect.retry({ while: (e) e.reason rate_limit || e.reason network, schedule: Schedule.exponential(500 millis).pipe( Schedule.compose(Schedule.recurs(3)) ), }) )这样 429 和网络错误会自动重试三次指数退避。注意while条件只对可重试的错误生效auth 错误不会重试避免无意义请求。第三条路径是把配置也做成 Layer。现在TAOTOKEN_MODEL是直接读process.env更规范的做法是定义一个AppConfigService用Config.all组合多个配置项再用Layer.effect提供。这样测试时可以轻松替换成固定配置不用改环境变量。如果你打算长期在项目里用这套模式建议把ModelClient、CacheService、AppConfig都放在独立的services/目录每个文件导出一个Layer最后在一个app-layer.ts里用Layer.mergeAll汇总。业务代码只依赖Context.Service标签不依赖具体实现测试时用Layer.succeed提供 mock 即可。关于 TaoToken 的进一步用法模型对话页面在 https://taotoken.net/model-chat 接入文档在 https://taotoken.net/doc API Key 管理在 https://taotoken.net/api-keys 。如果你要把这套模式用到长期编码或 Agent 场景可以看看 Coding Planhttps://taotoken.net/coding-plan 。Claude Code 相关的接入配置在 https://taotoken.net/claude-code 。最后留一个我踩过的坑Effect.fn包装的函数在递归调用时如果递归深度很大注意Effect.sleep的调度点会累积。我在一个轮询场景里递归了 60 次每次 sleep 2 秒整体耗时符合预期但如果你需要更精细的控制用Effect.iterate或Schedule替代手写递归会更清晰。