cloudflare-workers

Cloudflare Workers

Agent Skills™ 的一部分，由 googleadsagent.ai™ 提供

描述

Cloudflare Workers 提供全面的指导，帮助使用 Durable Objects、KV、R2、D1、AI 绑定和 Vectorize 构建边缘优先的应用程序。这项技能总结了真实 Workers 的生产实践经验，这些 Workers 为 googleadsagent.ai™ 提供支持，包括 buddy-agent（AI 编排）、buddy-brain（使用 D1/Vectorize 存储知识）和 blog-engine（在边缘生成静态内容）。

Workers 在 300 多个边缘节点的 V8 隔离区中运行，冷启动耗时不到 1 毫秒，且没有容器开销。这从根本上改变了应用程序架构：计算移至用户侧，状态存储在全球分布式存储中，而传统服务器概念（进程、线程、文件系统）不再适用。Agent 必须理解这些限制，才能生成正确且高性能的 Worker 代码。

Durable Objects 提供了 Workers 本身所缺少的有状态协调层。每个 Durable Object 实例都是单线程 Actor，具备事务性 SQLite 存储、WebSocket 支持和闹钟调度功能。将无状态 Workers 用于路由，将有状态 Durable Objects 用于协调，这种组合是所有非平凡边缘应用程序的基础模式。

适用场景

• 在 Cloudflare Workers 上构建无服务器 API
• 使用 Durable Objects 实现有状态协调
• 在 KV、R2、D1 或 Vectorize 中存储数据
• 使用 Workers AI 在边缘进行推理
• 部署架构类似于 googleadsagent.ai™ 的应用程序
• 从传统服务器架构迁移到边缘优先架构

工作原理

graph TD
    A[Client Request] --> B[Worker: Route + Auth]
    B --> C{Request Type}
    C -->|API| D[Durable Object: buddy-agent]
    C -->|Content| E[KV: Cached Pages]
    C -->|Upload| F[R2: Object Storage]
    C -->|Query| G[D1: SQLite Database]
    D --> H[Workers AI: Inference]
    D --> I[Vectorize: Embeddings]
    G --> J[buddy-brain: Knowledge Base]
    E --> K[blog-engine: Page Serving]
    H --> L[Response to Client]
    I --> L
    J --> L
    K --> L

Worker 充当无状态路由器。它对请求进行身份验证，确定合适的绑定，并将请求交给专用存储层或计算层处理。Durable Objects 负责需要强一致性的协调工作（会话、队列、速率限制）。

实现

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname.startsWith("/api/chat")) {
      const id = env.BUDDY_AGENT.idFromName("default");
      const agent = env.BUDDY_AGENT.get(id);
      return agent.fetch(request);
    }

    const cached = await env.PAGE_CACHE.get(url.pathname);
    if (cached) return new Response(cached, {
      headers: { "Content-Type": "text/html", "Cache-Control": "public, max-age=3600" },
    });

    return new Response("Not Found", { status: 404 });
  },
} satisfies ExportedHandler<Env>;

export class BuddyAgent extends DurableObject {
  async fetch(request: Request): Promise<Response> {
    const body = await request.json<{ message: string }>();

    const embedding = await this.env.AI.run("@cf/baai/bge-base-en-v1.5", {
      text: [body.message],
    });

    const similar = await this.env.VECTORIZE.query(embedding.data[0], {
      topK: 5,
      returnMetadata: "all",
    });

    const context = similar.matches.map(m => m.metadata?.text).join("\n");
    const response = await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
      messages: [
        { role: "system", content: `Context: ${context}` },
        { role: "user", content: body.message },
      ],
    });

    return Response.json({ reply: response.response });
  }
}

// wrangler.jsonc
{
  "name": "buddy-agent",
  "main": "src/index.ts",
  "compatibility_date": "2026-04-01",
  "durable_objects": {
    "bindings": [{ "name": "BUDDY_AGENT", "class_name": "BuddyAgent" }]
  },
  "kv_namespaces": [{ "binding": "PAGE_CACHE", "id": "abc123" }],
  "vectorize": [{ "binding": "VECTORIZE", "index_name": "buddy-brain" }],
  "ai": { "binding": "AI" }
}

最佳实践

• 切勿在 Workers 中使用全局可变状态——隔离区可能会在请求之间被回收
• 对大型响应使用流式传输，而不是将其缓冲到内存中（限制为 128MB）
• 使用 waitUntil() 执行不应阻塞响应的后台工作
• 固定 compatibility_date，并有计划地推进，不要自动推进
• 将 Durable Objects 放置在靠近主要用户群的位置，使用 locationHint
• 将密钥存储在 Wrangler secrets 中（wrangler secret put），切勿存储在 vars 中

平台兼容性

平台	支持情况	备注
Cursor	完全支持	集成 Wrangler CLI
VS Code	完全支持	提供 Cloudflare 扩展
Windsurf	完全支持	支持 Workers 感知型部署
Claude Code	完全支持	可使用 Shell 和 wrangler
Cline	完全支持	基于终端的开发
aider	部分支持	生成配置文件

相关技能

• 边缘渲染
• 可观测性
• 服务发现
• 沙箱加固

关键词

cloudflare-workers durable-objects kv r2 d1 workers-ai vectorize edge-computing serverless buddy-agent

---

© 2026 googleadsagent.ai™ | Agent Skills™ | MIT License