Cloudflare Workers 的 Codex 规则

将此内容添加为 AGENTS.md 或 Codex 系统提示片段。Cloudflare Workers 运行在 V8 隔离运行时上——而不是 Node.js——因此代理需要明确的护栏，以避免生成在本地开发中静默失败但在部署时崩溃的代码。

为什么这些规则

• 不要使用 process.env 是 AI 代理最常犯的 Cloudflare Workers 错误。在 Node.js 和 Next.js 代码库上训练的代理默认会使用 process.env.MY_SECRET。在 Workers 上，这在运行时是 undefined——绑定通过 env 参数传入，而不是进程环境。
• 使用 ctx.waitUntil() 处理副作用 可以防止一类微妙的数丢失错误。Workers 一旦返回 Response 就会终止隔离。任何在响应发送后执行的 await 如果没有 waitUntil 包裹，都会被静默丢弃，导致分析事件丢失、日志写入失败或数据库更新不完整。

适用场景

• Cloudflare Workers API、边缘中间件、基于 Hono 的 Workers 路由器、带有 D1/KV/R2 绑定的 Workers。

不适用场景

• Cloudflare Pages Functions（运行时类似，但使用不同的基于文件的路由约定）或通过 nodejs_compat 标志启用完整 Node.js API 并故意部署到 Node.js 的项目。