1. 从cloudflare-os这个名字说起它到底想解决什么问题第一次看到cloudflare-os这个仓库名我下意识以为 Cloudflare 官方出了个操作系统。点进去才发现它跟内核、发行版这些概念没有半点关系——这是一个把 Cloudflare Workers 当作运行时底座在上面搭出一整套 AI Agent 编排能力的开源项目。名字里的 os 更接近面向 Agent 的操作层这个含义而不是传统意义上的操作系统。这个定位其实挺聪明的。过去一年我接触过不少 AI Agent 项目绝大多数都卡在同一个地方本地跑得好好的一旦要部署成随时能访问、能定时触发、能接第三方回调的服务就得自己折腾服务器、容器、反向代理、证书、进程守护这一整套东西。对个人开发者和小团队来说这些运维成本往往比 Agent 逻辑本身还高。cloudflare-os的思路是直接把这些脏活累活交给 Workers 平台开发者只关心我的 Agent 要做什么。它适合谁我梳理了一下大概三类人用起来最舒服已经写过一点 Worker、想往 AI 方向延伸的前端或全栈开发者手里有一堆零散的 AI 能力比如几个不同厂商的模型接口想统一编排成一个能对话、能调工具的助手想快速验证 Agent 产品形态、又不想先买服务器的人。不适合谁如果你的 Agent 需要长时间占用 GPU、需要跑本地大模型、需要访问内网数据库那 Workers 这套无服务器模型会让你很难受。它的强项是轻量、事件驱动、全球边缘分发不是重计算。关键词里出现了pnpm、wrangler、Cloudflare Workers、AI、ai agent这些词基本可以确认这个项目的技术栈轮廓用 pnpm 做包管理用 wrangler 做本地开发和部署核心业务是 AI Agent。下面我就按环境准备 → 核心机制 → 编排设计 → 踩坑排查这条线把我在类似项目里趟过的路完整讲一遍。2. 环境准备pnpm 和 wrangler 这两关必须先过2.1 为什么这个项目大概率用 pnpm 而不是 npm热搜词里pnpm相关的一大堆什么pnpm下载失败pnpm离线安装pnpm 不是内部或外部命令说明很多人在第一步就卡住了。先解释一下为什么这类项目偏爱 pnpm。Workers 项目的依赖树通常不深但 monorepo 场景很常见——一个仓库里放 Worker 入口、共享的工具函数、Agent 的提示词模板、类型定义等好几个包。npm 在这种场景下会把同一个依赖在每个子包里重复安装一遍磁盘占用和安装时间都很难看pnpm 用硬链接加内容寻址存储同一份依赖在全局只存一份子包通过符号链接引用。我第一次把一个三包的 monorepo 从 npm 切到 pnpmnode_modules体积从 480MB 掉到 120MB 左右pnpm install从 40 多秒降到 12 秒。另一个隐性好处是 pnpm 对幽灵依赖的约束更严。npm 的扁平化安装会让你的代码能 import 到没在package.json里声明的包本地能跑、CI 上炸掉。pnpm 默认不允许这种访问逼你把依赖写清楚。Agent 项目经常要引各种 SDK这个约束能帮你提前发现隐患。2.2 pnpm 装不上的几种典型情况和对应解法pnpm 不是内部或外部命令这个报错本质是系统 PATH 里找不到 pnpm 的可执行文件。分情况处理情况一根本没装。Node 16.13 以上自带了 corepack最省事的做法是corepack enable corepack prepare pnpmlatest --activatecorepack 是 Node 官方出的包管理器版本管理工具它会根据项目package.json里的packageManager字段自动切换 pnpm 版本。我强烈建议在项目里显式写上这个字段{ packageManager: pnpm9.1.0 }这样团队里每个人、每台 CI 机器用的都是同一个 pnpm 版本避免我这能跑你那不能跑的扯皮。情况二装了但 PATH 没生效。Windows 上用 npm 全局装完 pnpm 后经常要重开一个终端才认。如果重开还不行检查npm config get prefix输出的目录有没有加进系统环境变量。macOS/Linux 上如果是用独立脚本装的pnpm 默认落在~/.local/share/pnpm需要手动加进.zshrc或.bashrc。情况三公司网络装不上。热搜里pnpm下载失败pnpm离线安装多半是这种情况。可行的做法是配置镜像源pnpm config set registry https://registry.npmmirror.com如果连镜像都访问不了就得走离线包在一台能联网的机器上pnpm store path找到存储目录把整个 store 拷到目标机器再pnpm install --offline。注意 store 的路径和 pnpm 版本要对应跨大版本拷贝经常出问题。提示不要用npm install -g pnpm和 corepack 混用两者装的 pnpm 可能版本冲突导致pnpm -v输出和实际用的不一致。选一种方式坚持到底。2.3 wrangler 的登录与本地开发wrangler 是 Cloudflare 官方的 CLI负责本地起 dev server、管理 secrets、部署。装好 pnpm 之后pnpm add -D wrangler pnpm wrangler loginlogin会拉起浏览器走一次授权。这里有个坑如果你在无头环境比如远程开发机里操作浏览器拉不起来得用wrangler login --browserfalse拿到一个链接在本地浏览器打开后把回调的 token 贴回去。本地开发用pnpm wrangler dev它会在本地起一个模拟 Workers 运行时的环境。默认是本地模式不消耗线上配额加--remote才是连真实边缘节点跑。我一般开发阶段用本地模式联调第三方回调比如 webhook时才切 remote因为本地模式的 URL 外部访问不到。3. Workers 作为 Agent 运行时的真实能力边界3.1 为什么 Agent 逻辑适合放在边缘传统做法是把 Agent 服务跑在一台常驻服务器上用 Express 或 FastAPI 起个 HTTP 服务。这套东西的问题在于Agent 的请求模式是突发性的可能一整天没人用也可能某一分钟涌进来几十个对话。常驻服务器要么一直开着浪费钱要么冷启动慢。Workers 的模型是按请求计费、按需拉起。一个对话请求进来平台在离用户最近的节点起一个隔离的运行时实例处理完就回收。对 Agent 这种请求-响应为主的负载这个模型非常契合。而且边缘节点离用户近网络往返延迟低对话首字节时间能明显改善。但要注意 Workers 的运行时有几条硬约束直接决定了你的 Agent 架构约束项具体限制对 Agent 设计的影响单次请求 CPU 时间免费版 10ms付费版可到 30s长推理、大循环要拆成多步或用队列内存128MB不能把大模型权重、大文件塞进内存无持久化文件系统只有临时空间状态必须放 KV、D1、R2 或 Durable Objects出站请求有子请求数量限制一次对话里别疯狂调外部 API我第一次把 Agent 往 Workers 上搬时最大的认知冲击是没有全局变量可以依赖。本地写 Node 服务时习惯用一个模块级变量缓存对话上下文到了 Workers 里每个请求可能是全新实例那个变量随时会没。所有需要跨请求保留的东西必须显式落到存储里。3.2 对话状态到底该放哪这是cloudflare-os这类项目最核心的设计决策之一。Cloudflare 提供了几种存储选错了后期改起来很痛苦KV最终一致的键值存储读快写慢适合放配置、提示词模板、静态知识。D1基于 SQLite 的关系库适合放用户表、对话历史这种需要查询和事务的数据。R2对象存储适合放上传的文件、生成的图片、日志归档。Durable Objects强一致的单点对象适合放一个会话的实时状态。我的经验是对话的实时上下文用 Durable Objects历史归档用 D1。原因是 Agent 对话经常需要读-改-写同一个会话状态比如往消息列表里追加一条、更新工具调用结果KV 的最终一致性会导致并发写入时丢消息。Durable Objects 保证同一个会话的所有请求都路由到同一个实例天然串行化不会打架。代价是 Durable Objects 的计费模型和普通 Worker 不一样它按对象存活时长和请求数双重计费。如果会话结束后对象不及时释放账单会悄悄涨。我一般会在会话空闲一段时间后主动调用state.storage.deleteAll()并让对象进入休眠。3.3 冷启动与首字节延迟的实测感受很多人担心 Workers 冷启动。我实测下来纯 JS 的 Worker 冷启动通常在个位数毫秒基本无感。但一旦你的 Worker 里 import 了一堆体积大的 SDK冷启动会明显变慢。有个项目我一开始把整个某 AI SDK 全量引入冷启动飙到 200ms 以上后来改成只引需要的子模块配合打包工具的 tree-shaking回到 30ms 以内。对 Agent 来说真正的延迟大头不是冷启动而是模型推理本身。所以优化重点应该放在减少不必要的串行调用上。比如系统提示词、用户画像、历史摘要这几块数据能并行取的就用Promise.all一起取别一个 await 接一个 await。4. 把多个 AI 能力编排成一个 Agent 的实操思路4.1 先想清楚一个 Agent还是多个 Agent 协作热搜里多ai协作ai agent搭建出现频率很高说明大家都在琢磨怎么把多个模型或工具串起来。我的建议是能用单 Agent 加工具调用解决的别急着上多 Agent。多 Agent 协作听起来很美实际落地时通信开销、状态同步、错误传播这三座大山很难翻。我做过一个研究员 写手 审校三 Agent 的项目光是把研究员的中间结论准确传给写手就调了两天提示词。后来发现用单个 Agent 加三个工具搜索工具、写作工具、审校工具效果差不多代码量少一半。什么时候真的需要多 Agent当子任务之间上下文差异极大、需要不同模型、或者需要独立并行时。比如一个负责代码生成的 Agent 用擅长代码的模型一个负责文案的用擅长中文的模型这种分工是合理的。4.2 工具调用的注册与路由设计Agent 的核心能力来自工具。在 Workers 里注册工具我习惯用一个显式的注册表const tools { search: { description: 根据关键词搜索资料, parameters: { query: string }, handler: async ({ query }, env) { // 调用搜索服务 return results; } }, calculate: { description: 执行数学计算, parameters: { expression: string }, handler: async ({ expression }) { return eval(expression); // 生产环境务必换成安全求值 } } };把工具的description和parameters写清楚直接决定模型能不能正确选择工具。我踩过的坑是description 写得太笼统比如处理数据模型根本不知道什么时候该调它。改成把 CSV 格式的字符串解析成 JSON 数组输入必须是合法 CSV之后调用准确率肉眼可见地上升。路由部分收到模型返回的工具调用请求后按名字查表执行把结果作为新消息追加回对话再让模型继续。这个循环要设一个最大轮数上限否则模型可能陷入调工具 → 不满意 → 再调的死循环把 CPU 时间烧光。4.3 提示词在边缘环境下的组织方式提示词不要硬编码在业务逻辑里。我一般把提示词抽成独立的模块或放到 KV 里好处是改提示词不用重新部署。对于需要 A/B 测试的场景可以在 KV 里存多个版本按用户 ID 哈希分流。系统提示词的结构我通常分四段角色定义、能力边界、输出格式要求、few-shot 示例。其中能力边界这段最容易被忽略但恰恰最重要——明确告诉模型你不能做什么能大幅减少乱调工具、乱承诺的情况。5. 部署上线后才会暴露的那些坑5.1 环境变量与密钥管理本地开发时习惯把 API Key 写在.env里但 Workers 没有传统的.env加载机制。正确做法是用wrangler secret putpnpm wrangler secret put OPENAI_API_KEY它会提示你输入值加密存到平台侧。本地开发时在wrangler.toml里配置[vars]放非敏感变量敏感的在.dev.vars文件里放一份供本地wrangler dev读取。注意.dev.vars一定要加进.gitignore我见过不止一个项目把密钥提交上去了。注意wrangler.toml里的[vars]是明文会随代码一起进版本库任何密钥都不要放这里。5.2 超时与重试的正确姿势Agent 调用外部模型接口网络抖动是常态。但 Workers 里做重试要小心重试会消耗额外的子请求配额和 CPU 时间。我的做法是只对幂等的 GET 类请求和明确的 5xx 错误重试且最多两次用指数退避。对于模型调用这种可能已经产生费用的请求重试前要确认对方接口是否幂等否则可能重复计费。超时设置上给外部请求设一个比 Worker 自身 CPU 限制更短的超时比如 8 秒。这样即使外部服务卡住你的 Worker 也能及时返回一个友好的错误而不是被平台直接掐断。5.3 日志与可观测性Workers 的日志默认在wrangler tail里实时看但生产环境不能靠这个。我一般接一个日志服务把关键事件请求进入、模型调用、工具执行、错误结构化打出去。字段包括 traceId、用户标识、耗时、token 用量。有了这些排查为什么这次对话答非所问才有依据。token 用量这块特别值得单独统计。Agent 项目烧钱往往不是因为用户多而是因为某条路径下提示词膨胀、历史消息没截断单次请求 token 数失控。我给自己定了个规则单次对话的输入 token 超过某个阈值就告警回头去查是哪段上下文没控制住。6. 我在类似项目里总结的几条硬经验第一条先把最小闭环跑通再谈架构。我见过太多人一上来就设计多 Agent、多存储、消息队列结果两周过去连用户发一句话、模型回一句话都没跑通。正确的顺序是一个 Worker、一个模型调用、一个内存里的对话数组跑通然后加持久化然后加工具最后才考虑多 Agent。第二条pnpm 的 lockfile 一定要提交。pnpm-lock.yaml是保证团队和 CI 环境一致的关键。有人觉得它体积大就 gitignore 掉结果不同机器装出来的依赖版本不一致出现各种玄学 bug。第三条给 Agent 设一个兜底回复。模型调用失败、工具超时、达到最大轮数这些情况都要有明确的用户可见反馈而不是让请求挂在那里转圈。用户体验上一句我暂时没想好换个说法再试试远好过一个 500 错误页。第四条成本监控要前置。Workers 的免费额度对个人开发够用但一旦接入付费模型成本曲线可能很陡。上线前先估算单次对话平均多少 token、多少工具调用、多少存储读写乘以预期日活看看月成本能不能接受。我有个项目就是上线三天后发现成本超预期十倍回头才发现是历史消息没做截断。第五条别忽视类型系统。Agent 项目里到处是 JSON 结构——模型返回、工具参数、存储记录。用 TypeScript 把这些结构定义清楚配合运行时校验比如 zod能在编译期和运行期各挡掉一批错误。纯 JS 写 Agent后期改一个字段名能让你找半天。这套东西说起来不复杂但每一条都是真金白银换来的。cloudflare-os这个方向的价值就在于它把边缘运行时 AI 编排这个组合的门槛降下来了让个人开发者也能用很低的成本跑起一个像样的 Agent 服务。剩下的就是把这些工程细节一个个抠扎实。 
长河君 · 2026/10/28 12:08:26 · 阅读 1.2k 基于Cloudflare Workers的AI Agent编排实战：pnpm与wrangler环境搭建及核心机制
1. 从cloudflare-os这个名字说起它到底想解决什么问题第一次看到cloudflare-os这个仓库名我下意识以为 Cloudflare 官方出了个操作系统。点进去才发现它跟内核、发行版这些概念没有半点关系——这是一个把 Cloudflare Workers 当作运行时底座在上面搭出一整套 AI Agent 编排能力的开源项目。名字里的 os 更接近面向 Agent 的操作层这个含义而不是传统意义上的操作系统。这个定位其实挺聪明的。过去一年我接触过不少 AI Agent 项目绝大多数都卡在同一个地方本地跑得好好的一旦要部署成随时能访问、能定时触发、能接第三方回调的服务就得自己折腾服务器、容器、反向代理、证书、进程守护这一整套东西。对个人开发者和小团队来说这些运维成本往往比 Agent 逻辑本身还高。cloudflare-os的思路是直接把这些脏活累活交给 Workers 平台开发者只关心我的 Agent 要做什么。它适合谁我梳理了一下大概三类人用起来最舒服已经写过一点 Worker、想往 AI 方向延伸的前端或全栈开发者手里有一堆零散的 AI 能力比如几个不同厂商的模型接口想统一编排成一个能对话、能调工具的助手想快速验证 Agent 产品形态、又不想先买服务器的人。不适合谁如果你的 Agent 需要长时间占用 GPU、需要跑本地大模型、需要访问内网数据库那 Workers 这套无服务器模型会让你很难受。它的强项是轻量、事件驱动、全球边缘分发不是重计算。关键词里出现了pnpm、wrangler、Cloudflare Workers、AI、ai agent这些词基本可以确认这个项目的技术栈轮廓用 pnpm 做包管理用 wrangler 做本地开发和部署核心业务是 AI Agent。下面我就按环境准备 → 核心机制 → 编排设计 → 踩坑排查这条线把我在类似项目里趟过的路完整讲一遍。2. 环境准备pnpm 和 wrangler 这两关必须先过2.1 为什么这个项目大概率用 pnpm 而不是 npm热搜词里pnpm相关的一大堆什么pnpm下载失败pnpm离线安装pnpm 不是内部或外部命令说明很多人在第一步就卡住了。先解释一下为什么这类项目偏爱 pnpm。Workers 项目的依赖树通常不深但 monorepo 场景很常见——一个仓库里放 Worker 入口、共享的工具函数、Agent 的提示词模板、类型定义等好几个包。npm 在这种场景下会把同一个依赖在每个子包里重复安装一遍磁盘占用和安装时间都很难看pnpm 用硬链接加内容寻址存储同一份依赖在全局只存一份子包通过符号链接引用。我第一次把一个三包的 monorepo 从 npm 切到 pnpmnode_modules体积从 480MB 掉到 120MB 左右pnpm install从 40 多秒降到 12 秒。另一个隐性好处是 pnpm 对幽灵依赖的约束更严。npm 的扁平化安装会让你的代码能 import 到没在package.json里声明的包本地能跑、CI 上炸掉。pnpm 默认不允许这种访问逼你把依赖写清楚。Agent 项目经常要引各种 SDK这个约束能帮你提前发现隐患。2.2 pnpm 装不上的几种典型情况和对应解法pnpm 不是内部或外部命令这个报错本质是系统 PATH 里找不到 pnpm 的可执行文件。分情况处理情况一根本没装。Node 16.13 以上自带了 corepack最省事的做法是corepack enable corepack prepare pnpmlatest --activatecorepack 是 Node 官方出的包管理器版本管理工具它会根据项目package.json里的packageManager字段自动切换 pnpm 版本。我强烈建议在项目里显式写上这个字段{ packageManager: pnpm9.1.0 }这样团队里每个人、每台 CI 机器用的都是同一个 pnpm 版本避免我这能跑你那不能跑的扯皮。情况二装了但 PATH 没生效。Windows 上用 npm 全局装完 pnpm 后经常要重开一个终端才认。如果重开还不行检查npm config get prefix输出的目录有没有加进系统环境变量。macOS/Linux 上如果是用独立脚本装的pnpm 默认落在~/.local/share/pnpm需要手动加进.zshrc或.bashrc。情况三公司网络装不上。热搜里pnpm下载失败pnpm离线安装多半是这种情况。可行的做法是配置镜像源pnpm config set registry https://registry.npmmirror.com如果连镜像都访问不了就得走离线包在一台能联网的机器上pnpm store path找到存储目录把整个 store 拷到目标机器再pnpm install --offline。注意 store 的路径和 pnpm 版本要对应跨大版本拷贝经常出问题。提示不要用npm install -g pnpm和 corepack 混用两者装的 pnpm 可能版本冲突导致pnpm -v输出和实际用的不一致。选一种方式坚持到底。2.3 wrangler 的登录与本地开发wrangler 是 Cloudflare 官方的 CLI负责本地起 dev server、管理 secrets、部署。装好 pnpm 之后pnpm add -D wrangler pnpm wrangler loginlogin会拉起浏览器走一次授权。这里有个坑如果你在无头环境比如远程开发机里操作浏览器拉不起来得用wrangler login --browserfalse拿到一个链接在本地浏览器打开后把回调的 token 贴回去。本地开发用pnpm wrangler dev它会在本地起一个模拟 Workers 运行时的环境。默认是本地模式不消耗线上配额加--remote才是连真实边缘节点跑。我一般开发阶段用本地模式联调第三方回调比如 webhook时才切 remote因为本地模式的 URL 外部访问不到。3. Workers 作为 Agent 运行时的真实能力边界3.1 为什么 Agent 逻辑适合放在边缘传统做法是把 Agent 服务跑在一台常驻服务器上用 Express 或 FastAPI 起个 HTTP 服务。这套东西的问题在于Agent 的请求模式是突发性的可能一整天没人用也可能某一分钟涌进来几十个对话。常驻服务器要么一直开着浪费钱要么冷启动慢。Workers 的模型是按请求计费、按需拉起。一个对话请求进来平台在离用户最近的节点起一个隔离的运行时实例处理完就回收。对 Agent 这种请求-响应为主的负载这个模型非常契合。而且边缘节点离用户近网络往返延迟低对话首字节时间能明显改善。但要注意 Workers 的运行时有几条硬约束直接决定了你的 Agent 架构约束项具体限制对 Agent 设计的影响单次请求 CPU 时间免费版 10ms付费版可到 30s长推理、大循环要拆成多步或用队列内存128MB不能把大模型权重、大文件塞进内存无持久化文件系统只有临时空间状态必须放 KV、D1、R2 或 Durable Objects出站请求有子请求数量限制一次对话里别疯狂调外部 API我第一次把 Agent 往 Workers 上搬时最大的认知冲击是没有全局变量可以依赖。本地写 Node 服务时习惯用一个模块级变量缓存对话上下文到了 Workers 里每个请求可能是全新实例那个变量随时会没。所有需要跨请求保留的东西必须显式落到存储里。3.2 对话状态到底该放哪这是cloudflare-os这类项目最核心的设计决策之一。Cloudflare 提供了几种存储选错了后期改起来很痛苦KV最终一致的键值存储读快写慢适合放配置、提示词模板、静态知识。D1基于 SQLite 的关系库适合放用户表、对话历史这种需要查询和事务的数据。R2对象存储适合放上传的文件、生成的图片、日志归档。Durable Objects强一致的单点对象适合放一个会话的实时状态。我的经验是对话的实时上下文用 Durable Objects历史归档用 D1。原因是 Agent 对话经常需要读-改-写同一个会话状态比如往消息列表里追加一条、更新工具调用结果KV 的最终一致性会导致并发写入时丢消息。Durable Objects 保证同一个会话的所有请求都路由到同一个实例天然串行化不会打架。代价是 Durable Objects 的计费模型和普通 Worker 不一样它按对象存活时长和请求数双重计费。如果会话结束后对象不及时释放账单会悄悄涨。我一般会在会话空闲一段时间后主动调用state.storage.deleteAll()并让对象进入休眠。3.3 冷启动与首字节延迟的实测感受很多人担心 Workers 冷启动。我实测下来纯 JS 的 Worker 冷启动通常在个位数毫秒基本无感。但一旦你的 Worker 里 import 了一堆体积大的 SDK冷启动会明显变慢。有个项目我一开始把整个某 AI SDK 全量引入冷启动飙到 200ms 以上后来改成只引需要的子模块配合打包工具的 tree-shaking回到 30ms 以内。对 Agent 来说真正的延迟大头不是冷启动而是模型推理本身。所以优化重点应该放在减少不必要的串行调用上。比如系统提示词、用户画像、历史摘要这几块数据能并行取的就用Promise.all一起取别一个 await 接一个 await。4. 把多个 AI 能力编排成一个 Agent 的实操思路4.1 先想清楚一个 Agent还是多个 Agent 协作热搜里多ai协作ai agent搭建出现频率很高说明大家都在琢磨怎么把多个模型或工具串起来。我的建议是能用单 Agent 加工具调用解决的别急着上多 Agent。多 Agent 协作听起来很美实际落地时通信开销、状态同步、错误传播这三座大山很难翻。我做过一个研究员 写手 审校三 Agent 的项目光是把研究员的中间结论准确传给写手就调了两天提示词。后来发现用单个 Agent 加三个工具搜索工具、写作工具、审校工具效果差不多代码量少一半。什么时候真的需要多 Agent当子任务之间上下文差异极大、需要不同模型、或者需要独立并行时。比如一个负责代码生成的 Agent 用擅长代码的模型一个负责文案的用擅长中文的模型这种分工是合理的。4.2 工具调用的注册与路由设计Agent 的核心能力来自工具。在 Workers 里注册工具我习惯用一个显式的注册表const tools { search: { description: 根据关键词搜索资料, parameters: { query: string }, handler: async ({ query }, env) { // 调用搜索服务 return results; } }, calculate: { description: 执行数学计算, parameters: { expression: string }, handler: async ({ expression }) { return eval(expression); // 生产环境务必换成安全求值 } } };把工具的description和parameters写清楚直接决定模型能不能正确选择工具。我踩过的坑是description 写得太笼统比如处理数据模型根本不知道什么时候该调它。改成把 CSV 格式的字符串解析成 JSON 数组输入必须是合法 CSV之后调用准确率肉眼可见地上升。路由部分收到模型返回的工具调用请求后按名字查表执行把结果作为新消息追加回对话再让模型继续。这个循环要设一个最大轮数上限否则模型可能陷入调工具 → 不满意 → 再调的死循环把 CPU 时间烧光。4.3 提示词在边缘环境下的组织方式提示词不要硬编码在业务逻辑里。我一般把提示词抽成独立的模块或放到 KV 里好处是改提示词不用重新部署。对于需要 A/B 测试的场景可以在 KV 里存多个版本按用户 ID 哈希分流。系统提示词的结构我通常分四段角色定义、能力边界、输出格式要求、few-shot 示例。其中能力边界这段最容易被忽略但恰恰最重要——明确告诉模型你不能做什么能大幅减少乱调工具、乱承诺的情况。5. 部署上线后才会暴露的那些坑5.1 环境变量与密钥管理本地开发时习惯把 API Key 写在.env里但 Workers 没有传统的.env加载机制。正确做法是用wrangler secret putpnpm wrangler secret put OPENAI_API_KEY它会提示你输入值加密存到平台侧。本地开发时在wrangler.toml里配置[vars]放非敏感变量敏感的在.dev.vars文件里放一份供本地wrangler dev读取。注意.dev.vars一定要加进.gitignore我见过不止一个项目把密钥提交上去了。注意wrangler.toml里的[vars]是明文会随代码一起进版本库任何密钥都不要放这里。5.2 超时与重试的正确姿势Agent 调用外部模型接口网络抖动是常态。但 Workers 里做重试要小心重试会消耗额外的子请求配额和 CPU 时间。我的做法是只对幂等的 GET 类请求和明确的 5xx 错误重试且最多两次用指数退避。对于模型调用这种可能已经产生费用的请求重试前要确认对方接口是否幂等否则可能重复计费。超时设置上给外部请求设一个比 Worker 自身 CPU 限制更短的超时比如 8 秒。这样即使外部服务卡住你的 Worker 也能及时返回一个友好的错误而不是被平台直接掐断。5.3 日志与可观测性Workers 的日志默认在wrangler tail里实时看但生产环境不能靠这个。我一般接一个日志服务把关键事件请求进入、模型调用、工具执行、错误结构化打出去。字段包括 traceId、用户标识、耗时、token 用量。有了这些排查为什么这次对话答非所问才有依据。token 用量这块特别值得单独统计。Agent 项目烧钱往往不是因为用户多而是因为某条路径下提示词膨胀、历史消息没截断单次请求 token 数失控。我给自己定了个规则单次对话的输入 token 超过某个阈值就告警回头去查是哪段上下文没控制住。6. 我在类似项目里总结的几条硬经验第一条先把最小闭环跑通再谈架构。我见过太多人一上来就设计多 Agent、多存储、消息队列结果两周过去连用户发一句话、模型回一句话都没跑通。正确的顺序是一个 Worker、一个模型调用、一个内存里的对话数组跑通然后加持久化然后加工具最后才考虑多 Agent。第二条pnpm 的 lockfile 一定要提交。pnpm-lock.yaml是保证团队和 CI 环境一致的关键。有人觉得它体积大就 gitignore 掉结果不同机器装出来的依赖版本不一致出现各种玄学 bug。第三条给 Agent 设一个兜底回复。模型调用失败、工具超时、达到最大轮数这些情况都要有明确的用户可见反馈而不是让请求挂在那里转圈。用户体验上一句我暂时没想好换个说法再试试远好过一个 500 错误页。第四条成本监控要前置。Workers 的免费额度对个人开发够用但一旦接入付费模型成本曲线可能很陡。上线前先估算单次对话平均多少 token、多少工具调用、多少存储读写乘以预期日活看看月成本能不能接受。我有个项目就是上线三天后发现成本超预期十倍回头才发现是历史消息没做截断。第五条别忽视类型系统。Agent 项目里到处是 JSON 结构——模型返回、工具参数、存储记录。用 TypeScript 把这些结构定义清楚配合运行时校验比如 zod能在编译期和运行期各挡掉一批错误。纯 JS 写 Agent后期改一个字段名能让你找半天。这套东西说起来不复杂但每一条都是真金白银换来的。cloudflare-os这个方向的价值就在于它把边缘运行时 AI 编排这个组合的门槛降下来了让个人开发者也能用很低的成本跑起一个像样的 Agent 服务。剩下的就是把这些工程细节一个个抠扎实。