Cloudflare Agents 实战基于 Durable Objects 的断点续传流式 AI 聊天Resumable Streaming Chat【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agentsResumable Streaming Chat 是 agents 仓库中一个开箱即恢复的实时流式 AI 聊天示例在长回答生成过程中刷新页面、断开网络或重连 WebSocket流会从断开的位置精确接续已生成的所有内容连同中间状态一起原样保留。本文以 examples/resumable-stream-chat/README.md 为主线结合AIChatAgent、useAgentChat、Durable Objects SQLite 与 CF_AGENT 协议源码讲清断点续传的完整链路并给出可复制的服务端与客户端实现。读完本文你将掌握用AIChatAgent在服务端零配置获得自动续传能力用useAgentChat在客户端自动完成流检测、ACK 与缓冲区块重放理解CF_AGENT_STREAM_RESUMING / ACK / REQUEST协议握手以及如何在流式响应中携带持久化与瞬态两类 typed data parts。示例概览它解决什么问题长回答生成中最常见的体验断裂是中途断连用户滚动页面刷新、网络抖动、WebSocket 超时已生成的内容丢失必须重新提问。该示例的核心能力是可续传流式输出Resumable streaming发起一条长回答后刷新页面流会从上次中断的位置精确接续自动重连Automatic reconnectionWebSocket 自动重连无需用户任何操作消息持久化Message persistence聊天历史通过useAgentChat在断连与刷新后完整保留缓冲区块重放Buffered chunk replay断连期间服务端生成的所有 chunk 在重连时一次性回放。需要区分两个概念本示例演示的是客户端断线重连恢复client reconnect recoveryDurable Object 驱逐恢复eviction recovery对AIChatAgent而言默认自动开启但本示例不会在模型调用进行中强制驱逐 DO。若想验证驱逐发生时流仍在飞行的场景参见 experimental/forever-chat。快速开始按 README 的三步即可本地运行复制环境模板并填写密钥cp .env.example .env在仓库根目录安装依赖npm install启动开发服务器npm start运行依赖说明以当前仓库源码为准package.json 中start脚本实际执行vite dev由cloudflare/vite-plugin驱动的本地开发服务器。模型调用并非直连 OpenAI而是通过 Workers AI 绑定服务端 src/server.ts 使用createWorkersAI({ binding: this.env.AI })wrangler.jsonc 中配置ai: { binding: AI, remote: true }使本地开发也能远程访问 Workers AIREADME 中OPENAI_API_KEY对应环境模板的密钥配置模型标识符为cf/moonshotai/kimi-k2.7-code。启动后进入聊天界面发送一条消息在回答进行中刷新页面——你会看到连接状态短暂变为 Disconnected 后自动恢复 Connected流从断点继续而不是重新开始。断点续传的完整原理协议握手与缓冲重放README 的核心论断是The server usesAIChatAgentwithstreamText— nothing special is needed. Resumability is built into the agent protocol. 续传能力内建于 Agent 协议层服务端无需任何额外代码。完整链路如下流式进行中所有 chunk 自动持久化到 Durable Objects SQLite断连时模型调用在服务端继续执行新产生的 chunk 持续写入缓冲重连时客户端请求恢复 → 服务端发送恢复通知 → 客户端 ACK → 重放全部缓冲区块 → 继续接收实时块。CF_AGENT 线协议中的恢复消息协议消息类型定义在 packages/agents/src/chat/wire-types.ts 的MessageType枚举中与恢复流程直接相关的是消息类型方向作用CF_AGENT_STREAM_RESUME_REQUEST客户端→服务端客户端在消息处理器就绪后主动请求恢复检查CF_AGENT_STREAM_RESUMING服务端→客户端客户端连接时存在活跃流通知有流可恢复CF_AGENT_STREAM_RESUME_ACK客户端→服务端客户端确认恢复通知并请求重放 chunkCF_AGENT_STREAM_RESUME_NONE服务端→客户端客户端请求恢复但该连接没有活跃流CF_AGENT_STREAM_PENDING服务端→客户端轮次已被接受但流尚未开始排队/等待 MCP/模型延迟提示重连客户端继续等待避免误判为无流其中CF_AGENT_STREAM_RESUMING携带id被恢复流的 request IDreplay相关字段定义在OutgoingMessage中重放的 chunk 会带上replay: true标记以及replayComplete信号用于客户端区分历史回放与实时到达。客户端自动处理的三步README 明确说明客户端 src/client.tsx 的useAgentChat自动处理检测重连时的活跃流通过 WebSocket 通道监听CF_AGENT_STREAM_RESUMING向服务端发送 ACK对每个恢复请求 ID 回CF_AGENT_STREAM_RESUME_ACK接收全部缓冲区块并继续流重放块一次性批处理应用到消息列表随后继续渲染实时到达的块。从源码看这一逻辑由 packages/agents/src/chat/ws-chat-transport.ts 中的_resumeResolver收到CF_AGENT_STREAM_RESUMING时由handleStreamResuming调用与_resumeNoneResolver收到CF_AGENT_STREAM_RESUME_NONE时调用实现CF_AGENT_STREAM_PENDING则通过_onStreamPending扩展探针超时避免流启动前的慢窗口排队/MCP/模型延迟被误判为无流。在 packages/agents/src/chat/react.tsx 中useAgentChat维护fallbackAckedResumeRequestIdsRef去重集合确保同一个恢复请求只 ACK 一次防止缓冲区块被重复重放对应 issue #1733 的修复。服务端持久化细节resumable-streaming.md 的 Under the Hood 一节给出了AIChatAgent服务端的关键实现事实构造时为流 chunk 与元数据创建 SQLite 表每个流拥有唯一 ID 并追踪 chunk 索引chunk 每 10 条批量刷写一次 SQLite性能优化收到CF_AGENT_STREAM_RESUME_REQUEST时检查活跃流并回复CF_AGENT_STREAM_RESUMING恢复时清理超过 5 分钟的陈旧流流缓冲与最终助手消息在同一事务中删除cutover完成后的轮次不会留下残留崩溃遗留的缓冲在下一次流启动时回收——已完成流立即清理被遗弃的飞行中流在 1 小时内无新 chunk 则回收。replay标志的意义重放的 chunk 带replay: true客户端据此在渲染前一次性批量应用全部重放块避免中间状态如 Thinking... 提示在回放过程中闪烁而实时流中 chunk 逐步到达React 自然渲染每个中间状态。服务端实现解读AIChatAgent typed data partssrc/server.ts 定义了ResumableStreamingChat extends AIChatAgent重写onChatMessage()。它同时演示了三种data parts附加在消息文本旁的类型化 JSON 块模式data-sources—对账更新同一type id的写入原地替换旧数据searching→found用于搜索来源这类状态推进data-thinking—瞬态状态标记transient: true不会持久化进message.partsdata-usage—持久化元数据token 数与延迟数据刷新后依然保留。核心代码骨架如下const stream createUIMessageStream({ execute: async ({ writer }) { const result streamText({ model: workersai(modelId, { sessionAffinity: this.sessionAffinity // 稳定会话亲和 }), messages: await convertToModelMessages(this.messages) }); // 先把 LLM 流合并进 UI 消息流后续 writer.write() 与正文交织为同一条消息 writer.merge(result.toUIMessageStream()); //>type ChatMessage UIMessage unknown, { sources: SourcesData; thinking: ThinkingData; usage: UsageData; } ;从而让sourcesPart.data等访问获得完整类型推断无需手动断言。配置清单README 的配置表及源码佐证变量说明OPENAI_API_KEYOpenAI API 密钥见上文运行依赖说明实际模型走 Workers AI 绑定工程配置层面wrangler.jsonc 是续传能力的基础{ ai: { binding: AI, remote: true }, compatibility_date: 2026-06-11, compatibility_flags: [nodejs_compat], assets: { not_found_handling: single-page-application, run_worker_first: [/agents/*] }, durable_objects: { bindings: [ { class_name: ResumableStreamingChat, name: ResumableStreamingChat } ] }, main: src/server.ts, migrations: [ { new_sqlite_classes: [ResumableStreamingChat], tag: v1 } ], name: resumable-stream-chat }durable_objects.bindings将聊天 Agent 声明为 DO 类绑定每个用户会话对应一个 DO 实例name: demo即实例名migrations.new_sqlite_classes为 DO 创建内置 SQLite 存储——chunk 缓冲与消息历史的持久化容器ai.remote: true允许本地vite dev时远程访问 Workers AIassets.not_found_handling: single-page-applicationrun_worker_first: [/agents/*]保证 SPA 路由与 Agent 路由互不干扰。技术栈见 package.jsonCloudflare Workers Durable Objects运行时、React Tailwind CSS KumoUI、Vercel AI SDKai包 v7配 workers-ai-provider模型层、Vite cloudflare/vite-plugin构建。测试验证协议行为有据可查仓库中 packages/ai-chat/e2e/chat.spec.ts 用真实 WebSocket 端到端验证了续传协议resume mid-stream 用例连接慢速 Agent发送消息后 600ms 中途断开Agent 每 400ms 发一个 chunk随后重连并断言收到了CF_AGENT_STREAM_RESUMING在对其回CF_AGENT_STREAM_RESUME_ACK后收到了带replay语义的重放 chunkgotResumeChunks trueno resume after completion 用例等待回答完整结束后重连断言不会收到CF_AGENT_STREAM_RESUMING——已完成的轮次不产生续传服务端在同一事务中已删除缓冲。另有 packages/ai-chat/e2e/resume-none.spec.ts 覆盖CF_AGENT_STREAM_RESUME_NONE分支以及 packages/ai-chat/src/react-tests/use-agent-chat.test.tsx 中同一 socket 对重复CF_AGENT_STREAM_RESUMING只 ACK 一次的单元测试。这些用例共同印证断点续传不是示例代码的取巧而是 Agent 协议层的稳定能力。生产实践要点默认即续传resume: true是useAgentChat的默认值流式响应在重连时自动恢复对短回答等不需要续传的场景可显式关闭resume: false。取消语义默认cancelOnClientAbort: false——浏览器导航或 React 组件卸载导致的通用流 abort 只做本地清理不会中断服务端轮次显式调用stop()才会真正取消服务端轮次。若你的应用想让客户端生命周期拥有服务端生命周期如按请求计费、节省 token 的场景可显式cancelOnClientAbort: true但无论该选项如何stop()始终是服务端级取消。Durable Object 驱逐恢复AIChatAgent的每个轮次都在可恢复 fiber 中执行驱逐恢复默认开启本示例不主动制造驱逐若需验证模型调用进行中 DO 被驱逐的恢复路径参考 experimental/forever-chat。更多协议与 API 细节可进一步阅读 docs/agents/resumable-streaming.md本文 Under the Hood 部分的事实来源、docs/agents/chat-agents.mdAIChatAgent与useAgentChat完整参考以及 docs/agents/client-tools-continuation.md客户端工具执行与自动续接。【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考