Cloudflare Agents 示例工程化规范基于 examples 清理清单的全栈 Agent 示例构建与维护指南【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents本指南以仓库examples/目录中的清理检查清单examples/TODO.md及其配套约定文档examples/AGENTS.md为核心系统梳理 Cloudflare Agents SDK 示例应用full-stack 与 server-only应遵循的工程规范从前后端形态选择、Vite 插件配置、类型声明生成到环境变量治理、SPA 路由回退与 Kumo UI 迁移。读完本文你将掌握一套可复制的示例工程基线能独立把一个 Agent 能力MCP、邮件、Workflow、x402 支付等组织成结构统一、开箱即跑的教学级示例。一、背景为什么 examples 需要一个清理清单examples/是 Cloudflare Agents SDK 的学习材料区目录下的 examples/AGENTS.md 开篇即定义其定位每个示例应是自包含的演示应用聚焦单一特性或概念如 MCP 服务器、邮件路由、Workflow面向用户、保持简单清晰一致唯一的例外是playground/它是覆盖 SDK 全功能的厨房水槽式大杂烩展示。随着示例数量增长一次集中审计暴露了一批系统性问题被逐项记录在 examples/TODO.md 中。该清单恰好浓缩了示例工程化的全部关键维度维度核心问题文档完整性每个示例必须有 README说明演示什么、如何运行前后端形态多数示例应是全栈前端 后端协议类示例可保持 server-only构建工具链全栈示例必须使用cloudflare/vite-plugin类型声明通过wrangler types生成env.d.ts不得手写密钥治理统一使用.env/.env.example禁止提交真实密钥路由回退带客户端路由的全栈应用需配置 SPA fallbackUI 体系全栈示例统一迁移到 Kumo 组件 Tailwind以下各节将逐一展开这些规范并给出仓库中的真实配置作为证据。二、示例形态全栈优先server-only 需有明确理由清单中的 Add frontend Vite plugin 一项确立了示例形态的决策原则大多数示例应当是 full-stack前端 后端使用户能pnpm run start后直接在浏览器里看到功能在运行而不是只读服务端日志。仓库中已经完成的迁移印证了这一原则email-agent/— 补上了完整的 Email Service 演示 UIx402/— 从纯 Worker 示例迁移为 React Kumo 前端提供 Fetch Pay 界面x402-mcp/— 从内联 HTML 迁移到 React Kumo用useAgent替换了裸 WebSocketmcp-worker/— 增加了 MCP 工具测试前端。与此同时清单明确保留了几类server-only特例以服务器搭建本身为教学重点时聚焦的 server-only MCP 示例应保持最小化examples/AGENTS.md。例如mcp-elicitation/保留为 server-only 的 Legacy Elicitation 示例mcp-elicitation-mrtr/增加为 server-only 的 Stateless Elicitation 示例mcp-server/恢复为原始传输层raw transport的 server-only 示例。原因是这些协议的 elicitation 行为必须由 MCP 客户端来触发加前端反而会遮蔽概念。从实际配置看server-only 示例如 examples/mcp-server/wrangler.jsonc 直接以src/index.ts为入口且不含assets配置而全栈示例如 examples/email-agent/wrangler.jsonc 则以src/server.ts为 Worker 入口并附带 assets 配置。判断一个示例该走哪种形态就看前端是否有助于理解该特性。三、全栈示例的目录结构基线examples/AGENTS.md 给出了两种可复制的目录骨架。全栈示例必须包含example-name/ package.json # name、dependencies、scripts vite.config.ts # 必须使用 cloudflare/vite-plugin wrangler.jsonc # Workers 配置jsonc而非 toml tsconfig.json # 必须 extends agents/tsconfig index.html # Vite 入口 README.md # 演示什么、如何运行 public/ favicon.ico # Cloudflare favicon src/ server.ts # Worker 入口 client.tsx # React 客户端入口 styles.css # Kumo Tailwind 引入server-only 示例的最小骨架则更精简package.json、wrangler.jsonc、tsconfig.json、README.md加一个src/index.ts。值得注意的规范点脚本命名约定全栈示例使用start而非dev作为开发服务器脚本。以 examples/email-agent/package.json 为例{ scripts: { start: vite dev, deploy: vite build wrangler deploy, types: wrangler types env.d.ts --include-runtime false } }依赖最小化共享依赖react、vite、wrangler、cloudflare/vite-plugin等放在仓库根package.json示例自身的package.json只添加与演示特性强相关的依赖。仍以 examples/email-agent/package.json 为例它仅额外声明了postal-mime邮件解析与 Kumo 相关包体现了教学材料要保持精简的原则。四、Vite 插件全栈示例的工具链硬性要求清单中有一个尚未勾选的遗留项cross-domain/目前只使用了vitejs/plugin-react需要补上cloudflare/vite-plugin。查看该示例的实际配置 examples/cross-domain/vite.config.tsimport react from vitejs/plugin-react; import { defineConfig } from vite; export default defineConfig({ plugins: [react()] });而 examples/AGENTS.md 要求的标准全栈配置是四个插件齐备import { cloudflare } from cloudflare/vite-plugin; import tailwindcss from tailwindcss/vite; import react from vitejs/plugin-react; import agents from agents/vite; import { defineConfig } from vite; export default defineConfig({ plugins: [agents(), react(), cloudflare(), tailwindcss()] });仓库中已迁移的示例如 examples/x402/vite.config.ts正是这一标准配置。各插件职责如下agents()来自agents/vite处理 TC39 装饰器转换Oxc 目前尚不支持装饰器。凡是使用callable()等装饰器的示例必须包含它即便示例未用装饰器包含它也是安全的react()React 客户端编译。框架特定示例如vue-chat/演示非 React 客户端可用对应框架插件替换但不能仅为贴合默认壳而引入 React 专属 UI 依赖cloudflare()Cloudflare Workers 集成负责本地开发与构建时把 Worker 与前端资产绑定tailwindcss()Tailwind 样式编译配合 Kumo 主题使用。从仓库结构看cross-domain/与codemode/等目录虽然带了vite.config.ts但未接cloudflare/vite-plugin这正是 examples/AGENTS.md 末尾Known issues to clean up点名的已知问题也是 TODO 清单中 Vite 插件修复项要解决的目标。五、wrangler.jsonc 配置要点examples/AGENTS.md 对wrangler.jsonc有明确约定这与 TODO 清单的 SPA routing 审计直接相关使用wrangler.jsonc而非.toml包含$schema: ./node_modules/wrangler/config-schema.json——注意该路径相对于示例根目录这样既能在 pnpm workspace 内解析也能在示例被单独拷贝安装时解析compatibility_date: 2026-06-11compatibility_flags: [nodejs_compat]——仓库中绝大多数示例均遵循此版本如 examples/tictactoe/wrangler.jsonc全栈应用若带客户端路由需配置assets: { not_found_handling: single-page-application }使用run_worker_first把 API/Agent 路径优先路由到 Worker不要在 assets 中设置directory——Vite 插件会处理该字段。关于 SPA fallback 的取舍examples/workflows/wrangler.jsonc 是一个正面范例{ name: workflows-demo, main: src/server.ts, compatibility_date: 2026-06-11, compatibility_flags: [nodejs_compat], assets: { not_found_handling: single-page-application, run_worker_first: [/agents/*] }, ... }而 examples/email-agent/wrangler.jsonc 则展示了run_worker_first的扩展用法assets: { not_found_handling: single-page-application, run_worker_first: [/agents/*, /api/*] }TODO 清单中对codemode/、github-webhook/、workflows/的审计要求正是围绕这一配置展开的。反例是tictactoe/——它没有客户端路由因此无需 SPA fallback清单中该项已勾选确认。判断是否需要 SPA fallback 的方法很直接查看客户端是否使用了react-router之类的前端路由。若使用则必须配置not_found_handling: single-page-application否则用户刷新或直接访问子路由时会命中 404同时用run_worker_first明确哪些路径应优先交给 Worker 处理如/agents/*的 Agent 通信端点避免静态资源与 Worker 路由冲突。六、类型声明env.d.ts 与 wrangler typesTODO 清单的 Type declarations 与 Missing env.d.ts 两项规范了环境变量的类型生成流程每个示例需要env.d.ts通过pnpm exec wrangler types生成不得手写bindings 变更后需重新生成examples/AGENTS.md文件名约定从worker-configuration.d.ts统一改为env.d.tsx402/、x402-mcp/已完成重命名并重新生成生成命令带--include-runtime false标志只生成绑定类型、不含运行时类型见上文示例 scripts 中的types: wrangler types env.d.ts --include-runtime false。清单中a2a/仍待生成env.d.ts而email-agent/、mcp-worker-authenticated/已生成。把wrangler types纳入示例的types脚本是保证 bindingsDurable Object、AI binding、Workflow、发送邮件等类型与实际配置保持一致的标准做法。七、密钥治理.env.example 统一标准TODO 清单 Secrets examples 项的结论是在.env/.env.example上标准化。已完成迁移的示例包括github-webhook/、mcp-client/、playground/、resumable-stream-chat/、tictactoe/。其用法模板见 examples/github-webhook/.env.example# GitHub webhook secret - set this to the same value you configure in GitHub GITHUB_WEBHOOK_SECRETyour-webhook-secret-here配套约定examples/AGENTS.md需要密钥的示例必须在仓库中包含.env.example展示所需键名绝不提交真实密钥实际密钥放本地.env被.gitignore忽略。例如 GitHub webhook 示例的密钥必须与 GitHub 仓库中配置的 webhook secret 一致。八、UI 体系迁移Kumo TailwindTODO 清单最后一节是 Kumo 迁移目标是把示例 UI 统一到 Kumo 组件与 Tailwind 体系。已完成迁移的包括mcp/从 Hello World 升级为完整 Kumo 工具测试器、mcp-client/从自定义 CSS 迁移到 Kumo并用callable替换agentFetch、mcp-worker/、x402/、x402-mcp/等。mcp-elicitation/与mcp-elicitation-mrtr/则有意保持 server-onlyelicitation 需要 MCP 客户端配合不强制迁移。examples/AGENTS.md 给出的 Kumo 集成规范包括使用 Kumo 组件Button、Surface、Text、Badge、Empty等替代手写 HTML图标使用phosphor-icons/react颜色使用 Kumo 语义 tokentext-kumo-default、bg-kumo-base、border-kumo-line而非裸 Tailwind 色值暗色模式基于data-mode属性不使用dark:Tailwind 变体Text组件不接受className需要自定义类时用span包裹每个全栈示例必须包含PoweredByCloudflare页脚徽标、暗色模式切换组件ModeToggleWebSocket 类示例还需连接状态指示器ConnectionIndicator每个示例页面顶部应有解释性信息卡Explainer section说明该演示展示什么、如何使用。src/styles.css的引入方式examples/AGENTS.mdimport tailwindcss; import cloudflare/kumo/styles/tailwind; /* Tailwind ignores node_modules by default, so we source Kumo for class extraction. */ source ../node_modules/cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx};其中source路径相对src/styles.css指向示例自身的node_modules这保证无论在 pnpm workspace 内每个包有自己的带符号链接的 node_modules还是示例被单独拷贝安装时都能正确解析——不要使用../../../node_modules这类相对 monorepo 根部的写法。对带聊天界面的示例使用useAgentChat或useChatAGENTS.md 还强制要求按数组顺序渲染message.parts的完整回合形态助手文本用streamdown渲染、reasoning 部分用独立弱化块、工具调用要同时渲染输入/输出/错误output-error时展示part.errorText并避免在流式期间出现空气泡。九、示例 README 的五要素模板每个示例都必须有 READMEexamples/AGENTS.md 给出了精简模板一句话说明该示例演示什么如何运行全栈示例pnpm install pnpm run startserver-only 示例pnpm install pnpm run dev需要的环境变量关键模式的代码片段相关示例的链接。TODO 清单中resumable-stream-chat/与x402/的 README 补全已勾选完成。这一模板保证了所有示例文档的可扫描性方便搜索引擎与阅读者快速定位到需要的示例。十、总结从清理清单到工程基线回顾 examples/TODO.md 的六类待办它们共同指向一套可执行的示例工程基线形态决策默认全栈协议教学类可 server-only 并保持最小工具链统一全栈示例必须agents()react()cloudflare()tailwindcss()四插件齐备类型与配置自洽wrangler.jsonc用 jsonc schema、固定兼容日期与nodejs_compatenv.d.ts由wrangler types生成安全默认密钥只进.env/.env.example路由正确性客户端路由示例配置 SPA fallback run_worker_first无路由则不需要UI 一致性Kumo Tailwind、PoweredByCloudflare、暗色切换、信息卡是标配。这套基线已在仓库数十个示例a2a/、channels/、agents-as-tools/、voice-agent/、webmcp/等中大规模落地examples/AGENTS.md 与 examples/TODO.md 即是它的宪法与督办台账。无论你是要新增一个示例、还是把某个早期实验examples/next/下的坐标式 PR 堆栈移入主目录先对照上述清单逐项检查就能交付结构统一、开箱即跑的高质量学习示例。【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考