Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

前言

为什么是这本书

Cloudflare 的官方文档很全,几十篇 API 参考、各种 guides、若干 concepts。但翻完一圈,你会发现一个问题:它告诉你每件零件的用法,没告诉你装一台机器的顺序。

Agent 是什么、AIChatAgent 是什么、McpAgent 是什么、Workflow 是什么、subAgent() 又是什么 —— 单看每篇都能理解,合在一起就开始迷糊:这些东西到底是什么关系?我现在要做一个“能聊天还能改我代码的 agent“,从哪儿开始?中间什么时候该引入 Workflow,什么时候该用 sub-agent,什么时候该上 Container?

这本书想回答的就是这个问题。

我们不打算把所有 API 重讲一遍 —— Cloudflare Agents 官方文档的完整中文翻译就在本书附录 B,需要查参考的时候直接跳过去就好。我们要做的是:沿着一条真实的项目演进路线,从最小的“会回话“开始,一步步加东西,直到你手上有一个能对接 GitHub、能开 PR、能跑测试的 coding agent。

每加一项能力,我们都会停下来问三个问题:

  1. 想要什么? 具体到一个用户场景。
  2. Cloudflare 自家有现成的吗? 用哪个,为什么。
  3. 如果没有,2026 年 4 月生态里的最佳做法是什么?

走完十章,你不仅会用 Cloudflare Agents,还会知道什么时候不该用它。

这本书的最终产物

跟着十章做下来,你会得到一个叫 agent-coder 的项目。它的核心能力清单:

  • 接受用户的自然语言指令(HTTP / WebSocket 都行)
  • 流式输出,可在 Workers AI / Anthropic / OpenAI 之间切换
  • 每个会话独立持久化,刷新页面记忆不丢
  • 调用工具读写代码、查 GitHub
  • 关键操作走 human-in-the-loop 确认
  • 加载可复用的 Skills(代码评审、lint 修复)
  • 在沙箱容器里执行任意命令(npm install、pytest)
  • 把生成的产物落到 R2 持久化
  • 接到 issue 后自己规划、改代码、跑测试、开 PR
  • 通过 GitHub App 安全集成,token 短时效、可吊销
  • 上线带限流、可观测、灰度

部署目标全部在 Cloudflare 上:Workers + Durable Objects + Containers + R2 + Workers AI + Workflows。月成本可控制在 0(免费额度)到几十美元(中等使用量)。

你应该会什么

  • TypeScript 基础
  • HTTP / WebSocket 的概念
  • Git / GitHub 的常规用法
  • 大致明白 LLM、prompt、tool calling 是什么(不需要懂背后的原理)

完全不熟 Cloudflare Workers / Durable Objects 也没关系,需要的概念我们会现讲。但如果你完全没用过 Cloudflare,建议先花 20 分钟跟着官方 quick start 跑一个 hello world Worker,回来再继续。

怎么读

按顺序读。 每一章的代码都是上一章的增量。第 6 章的 container 配置依赖第 4 章的工具结构,第 8 章的 Workflow 用了第 5 章的 Skill —— 跳读会很难拼回来。

每章末尾有“下一章预告“,告诉你下一步要解决什么问题。如果某个问题你暂时不关心(比如你不打算上线,可以跳过第 10 章),也可以挑着读,但提前知道你跳过了什么。

代码块都标了文件路径(如 // src/agent.ts),按提示放就行。完整的项目代码见 https://github.com/<your-handle>/agent-coder(占位,根据自己情况替换)。

关于中文翻译

本书附录 B 是 Cloudflare Agents 官方文档的完整中文翻译,共 76 篇,按官方目录组织(快速开始 / MCP / API 参考 / 核心概念 / 实践指南 / 平台等)。每章末尾的“延伸阅读“都会直接链到对应的中文页。

翻译以官方英文文档为准,如果发现翻译与英文有出入,以英文版为准 —— 但如果你只是想快速理解某个概念,中文版足够用。

关于成本与时间

这本书里所有能在免费额度内跑通的功能,都用免费的方案。第 1-5 章 完全免费(Workers AI 有免费额度、Durable Objects SQLite 免费层够用)。第 6 章起 涉及 Containers 和外部 API key,需要少量预算(预计 $5-20 即可走完整本书)。

跟着代码走完,大约需要 8-12 小时。如果你想真的吃透 —— 在每一章的“边界与坑“部分动手验证一遍 —— 大概要 20 小时。

一个提醒

LLM 和 agent 框架进化得非常快。本书写于 2026 年 4 月。如果你在更晚的时间读到它,某些 API 可能已经更新。判断方法:

  • 文中的 model id(如 claude-sonnet-4-6)和 SDK 版本(如 ai@^4)如果失效,去对应文档查最新的
  • Cloudflare 平台的核心抽象(Agent、Durable Object、Workflow)非常稳定,核心思路适用很久

好,我们开始。