企业官网建设流程全解析

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 中。该清单恰好浓缩了示例工程化的全部关键维度：

以下各节将逐一展开这些规范，并给出仓库中的真实配置作为证据。

二、示例形态：全栈优先，server-only 需有明确理由

清单中的 "Add frontend + Vite plugin" 一项确立了示例形态的决策原则：大多数示例应当是 full-stack（前端 + 后端），使用户能pnpm run start后直接在浏览器里看到功能在运行，而不是只读服务端日志。

仓库中已经完成的迁移印证了这一原则：

• email-agent/— 补上了完整的 Email Service 演示 UI；
• x402/— 从纯 Worker 示例迁移为 React + Kumo 前端，提供 "Fetch & Pay" 界面；
• x402-mcp/— 从内联 HTML 迁移到 React + Kumo，用useAgent替换了裸 WebSocket；
• mcp-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.ts：

import 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-11"，compatibility_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 types

TODO 清单的 "Type declarations" 与 "Missing env.d.ts" 两项规范了环境变量的类型生成流程：

• 每个示例需要env.d.ts，通过pnpm exec wrangler types生成，不得手写，bindings 变更后需重新生成（examples/AGENTS.md）；
• 文件名约定从worker-configuration.d.ts统一改为env.d.ts（x402/、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脚本，是保证 bindings（Durable 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_SECRET=your-webhook-secret-here

配套约定（examples/AGENTS.md）：需要密钥的示例必须在仓库中包含.env.example展示所需键名，绝不提交真实密钥，实际密钥放本地.env（被.gitignore忽略）。例如 GitHub webhook 示例的密钥必须与 GitHub 仓库中配置的 webhook secret 一致。

八、UI 体系迁移：Kumo + Tailwind

TODO 清单最后一节是 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-only（elicitation 需要 MCP 客户端配合），不强制迁移。

examples/AGENTS.md 给出的 Kumo 集成规范包括：

• 使用 Kumo 组件（Button、Surface、Text、Badge、Empty等）替代手写 HTML；图标使用@phosphor-icons/react；颜色使用 Kumo 语义 token（text-kumo-default、bg-kumo-base、border-kumo-line），而非裸 Tailwind 色值；
• 暗色模式基于data-mode属性，不使用dark:Tailwind 变体；
• Text组件不接受className，需要自定义类时用<span>包裹；
• 每个全栈示例必须包含PoweredByCloudflare页脚徽标、暗色模式切换组件（ModeToggle），WebSocket 类示例还需连接状态指示器（ConnectionIndicator）；
• 每个示例页面顶部应有解释性信息卡（Explainer section），说明该演示展示什么、如何使用。

src/styles.css的引入方式（examples/AGENTS.md）：

@import "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或useChat），AGENTS.md 还强制要求按数组顺序渲染message.parts的完整回合形态：助手文本用streamdown渲染、reasoning 部分用独立弱化块、工具调用要同时渲染输入/输出/错误（output-error时展示part.errorText），并避免在流式期间出现空气泡。

九、示例 README 的五要素模板

每个示例都必须有 README，examples/AGENTS.md 给出了精简模板：

1. 一句话说明该示例演示什么；
2. 如何运行（全栈示例pnpm install && pnpm run start，server-only 示例pnpm install && pnpm run dev）；
3. 需要的环境变量；
4. 关键模式的代码片段；
5. 相关示例的链接。

TODO 清单中resumable-stream-chat/与x402/的 README 补全已勾选完成。这一模板保证了所有示例文档的"可扫描性"，方便搜索引擎与阅读者快速定位到需要的示例。

十、总结：从清理清单到工程基线

回顾 examples/TODO.md 的六类待办，它们共同指向一套可执行的示例工程基线：

1. 形态决策：默认全栈，协议教学类可 server-only 并保持最小；
2. 工具链统一：全栈示例必须agents()+react()+cloudflare()+tailwindcss()四插件齐备；
3. 类型与配置自洽：wrangler.jsonc用 jsonc + schema、固定兼容日期与nodejs_compat，env.d.ts由wrangler types生成；
4. 安全默认：密钥只进.env/.env.example；
5. 路由正确性：客户端路由示例配置 SPA fallback +run_worker_first，无路由则不需要；
6. 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