Cloudflare 的最新更新与改进。
您现在可以直接从仪表板注册 Cloudflare One 虚拟 Appliance 并生成其许可证密钥，而无需联系您的账户团队。
这对现有的用于配置虚拟 Appliance 的 API 和 Terraform 自助服务工作流进行了补充。硬件 Appliance 继续使用现有的账户团队履行工作流。
有关详细信息，请参阅配置 Cloudflare One 虚拟 Appliance。
Wrangler 配置文件中全新的声明式 exports 字段取代了用于管理 Durable Object 类生命周期的命令式 migrations 数组。您无需再编写带有唯一标签的有序迁移步骤列表，而是声明 Worker 导出的每个 Durable Object 类，Cloudflare 会将其与已部署的内容进行对比，以确定需要创建、重命名还是删除哪些 Durable Object 状态。
在使用旧版迁移时，将 ChatRoom 重命名为 Room 需要保留这两个标记的步骤：
{
"migrations": [
{ "tag": "v1", "new_sqlite_classes": ["ChatRoom"] },
{
"tag": "v2",
"renamed_classes": [{ "from": "ChatRoom", "to": "Room" }],
},
],
}而使用 exports，您只需将 Room 声明为当前类，并将 ChatRoom 标记为已重命名：
{
"exports": {
"ChatRoom": {
"type": "durable-object",
"state": "renamed",
"renamed_to": "Room",
},
"Room": { "type": "durable-object", "storage": "sqlite" },
},
}每个条目都以类名作为键。state 字段承载生命周期（默认为 created——活动类——以及墓碑（tombstone）状态 deleted、renamed、transferred，和用于跨 Worker 传输的接收状态 expecting-transfer）。
与旧版 migrations 数组相比的关键改进：
exports 映射是唯一的真实数据源——无需维护 v1、v2、v3 条目的历史链。使用旧版 migrations 数组的现有 Workers 仍可照常工作，无需任何更改。要过渡到 exports，请参阅迁移指南。在单个 Worker 中，exports 和 migrations 是互斥的。
欲了解完整的参考信息，请参阅 Durable Object 类导出。
我们已经发布了 @cloudflare/workers-types ↗ 的第 5 版。此版本简化了该包，使其仅公开最新的运行时类型。
我们仍然建议您使用 wrangler types 为您的 Worker 生成类型，但如果您想直接使用该包，您可以使用您选择的包管理器进行安装：
npm i -D @cloudflare/workers-types@latestyarn add -D @cloudflare/workers-types@latestpnpm add -D @cloudflare/workers-types@latestbun add -d @cloudflare/workers-types@latest该包现在公开了两个入口点：
@cloudflare/workers-types 反映了最新的兼容性日期，使用最新的稳定兼容性标志。@cloudflare/workers-types/experimental 反映了处于实验性兼容性标志之下的 API。删除了带有日期的入口点，例如 @cloudflare/workers-types/2022-11-30 和 @cloudflare/workers-types/2023-03-01。借助 Wrangler v4 中的运行时类型生成功能，您可以使用 wrangler types 命令来生成这些类型，以创建锁定到您的 Worker 兼容日期的类型。
有关更多信息，请参阅 TypeScript 语言支持。
当您将数据源连接到您的 AI Search 实例时，AI Search 会运行同步作业以使您的索引与您的内容保持最新。您现在可以直接从 Wrangler 管理这些作业。
例如，您可以使用 jobs create 命令从您的 CI/CD 或自动化流水线触发同步作业，以便在推送更改时刷新索引：
wrangler ai-search jobs create my-instance这将创建一个异步同步作业，该作业会检查数据源中的更改，并发送新增、修改或删除的文件以进行索引。 以下命令可用：
| 命令 | 说明 |
|---|---|
wrangler ai-search jobs create |
触发新的同步作业 |
wrangler ai-search jobs list |
列出实例的同步作业 |
wrangler ai-search jobs get |
获取作业详情 |
wrangler ai-search jobs cancel |
取消正在运行的作业 |
wrangler ai-search jobs logs |
查看作业的日志条目 |
所有命令都接受 --namespace/-n（默认为 default）和 --json，以输出自动化和 AI 代理可以直接解析的结构化数据。list 和 logs 命令还支持用于分页的 --page 和 --per-page，并且除非您传递 -y/--force，否则 cancel 会提示确认。
有关完整的用法详细信息，请参阅 AI Search Wrangler 命令文档。
您的源站可以通过返回 Vary ↗ 响应标头，为同一个 URL 提供不同的响应 —— 例如根据 Accept-Language 提供不同的语言，或者根据 Accept 提供不同的格式。Cloudflare 的缓存现在直接在 缓存规则（Cache Rules） 中遵循该标头，因此同一个 URL 可以保存多个缓存版本，并且每个请求都与正确的版本进行匹配。以前必须绕过缓存以保持正确性的内容现在可以被缓存，遵循标准的 HTTP 缓存行为 ↗。
您的源站现在通过在其 Vary 响应中列出哪些请求标头重要来决定它们，而您则控制 Cloudflare 如何处理每一个。当您使用缓存规则启用了 Vary 且响应包含 Vary 标头时，列出的请求标头将成为缓存键的一部分。
对于您的源站变化所依赖的每个标头，选择以下三个操作之一：
| 操作 | 行为 | 最适用于 |
|---|---|---|
normalize |
在匹配之前将等效的标头值转换为相同的缓存键值，折叠冗余版本。 | 大多数 Accept、Accept-Language 和 Accept-Encoding 用例。 |
passthrough |
使用原始标头值选择缓存版本，并将其不作修改地转发到源站。 | 当标头值中逐字节的差异应当创建新版本时。 |
bypass |
只要此标头名称出现在源站的 Vary 响应中，就绕过缓存。 |
按用户的值，或包含太多可能值以至于无法安全缓存的标头。 |
normalize 将语义上等效的标头视为一个版本。例如，Accept-Language: en-US, fr;q=0.8 和 Accept-Language: fr;q=0.8, en-GB 都解析为相同的缓存键，因此您可以从缓存而非源站提供更多请求的服务。Vary，您完全可以在缓存规则（Cache Rules）中配置该行为。Vary: * 像 RFC 9110 要求的那样继续绕过缓存。缓存规则中的 Vary 适用于所有计划（免费版、专业版、商业版和企业版）。对于 Workers 子请求中的每个请求控制，请使用 cf.vary 属性。
在 Cloudflare 仪表板 ↗ 的 Cache（缓存） > Cache Rules（缓存规则） 下配置 Vary，或通过 Rulesets API 进行配置。要了解 Vary 如何影响缓存键以及每个操作的工作原理，请参阅 Vary 和 缓存规则 Vary 设置。
Cloudflare 已更新 Logpush 数据集：
AppliedMaxTTL 和 UpstreamRecordTTLs。Warnings。CacheLockWaitedMs。有关每个数据集的完整字段定义，请参阅 Logpush 数据集。
除了 CIDR 路由之外，您现在还可以向 Cloudflare Mesh 节点添加主机名路由。
Requests wiki.internal.local
Returns a token IP, then rewrites the destination to the real private IP.
100.80.0.0/16Forwards traffic to the host on the local network
wiki.internal.local · 10.0.0.50
您可以通过将主机名的流量引导到 Mesh 节点来代替管理 IP 范围：
wiki.internal.local）—— 通过名称访问内部应用程序，这在它具有未知或临时 IP 时非常有用。在 Mesh 上，您不需要运行 DNS 服务器；只需节点上的本地 hosts 文件条目即可，或者您可以使用 Gateway 解析器策略进行 split DNS。www.example.com）—— 通过该节点路由该主机名的流量，并经由该节点的公共 IP 出站。有关设置步骤、先决条件和 DNS 选项，请参阅主机名路由。
Wrangler CLI 现在支持身份验证配置文件（auth profiles）：命名登录，您可以将其范围限制为特定的 Cloudflare 账户，并根据您正在工作的目录自动在它们之间进行切换。
配置文件（profile）是绑定到目录的命名 OAuth 登录。在该目录及其子目录中运行的命令将使用匹配的账户 —— 这样您就可以在账户之间切换，而无需重新运行 wrangler login。
当您在代理机构工作时，使用配置文件为每个客户保留单独的登录，或者将暂存（staging）和生产（production）环境分隔到不同的账户中。在您的 Wrangler 配置文件 中将配置文件与 account_id 配对，这样命令就不会访问到错误的账户。
# 为每个账户创建一个配置文件，选择它能访问的账户
wrangler auth create client-a
wrangler auth activate client-a ~/clients/client-a
wrangler auth create client-b
wrangler auth activate client-b ~/clients/client-b使用 --profile 标志以特定配置文件运行单个命令：
wrangler deploy --profile personal在 CI 和其他自动化环境中，CLOUDFLARE_API_TOKEN 仍然优先于所有配置文件。
有关设置、解析顺序和完整命令参考，请参阅身份验证配置文件（Authentication profiles）。
A new GA release for the Linux Cloudflare One Client is now available on the stable releases downloads page.
This package is the same release as 2026.6.822.0, with a fix for our RPM package. Previously the repository served a single build to every OS version, so an install could pull a dependency that isn't available on that release. The repository now serves the correct build for each operating system version, so installs automatically pull the dependencies that version requires. Debian and Ubuntu were not affected.
If you installed version 2026.6.822.0 on an RPM-based distribution, we recommend refreshing your repository configuration:
sudo curl -fsSL https://pkg.cloudflareclient.com/cloudflare-warp-ascii.repo | sudo tee /etc/yum.repos.d/cloudflare-warp.repo
sudo dnf clean all
sudo dnf install cloudflare-warp
Access 现在在登录后将用户重定向回应用程序时，能够正确保留 URL 片段（fragment）字符（/、?、=、&、;）。以前，这些字符是使用 encodeURIComponent 进行编码的，这会破坏单页应用程序（SPA）使用的基于片段的路由。
例如，像 https://app.example.com/#/dashboard?tab=settings&view=advanced 这样的 SPA URL 以前在登录后会重定向到一个损坏的 URL。这现在已得到正确处理。
如果您的 SPA 用户在通过 Access 进行身份验证后遇到导航损坏的问题，此修复将解决该问题，而无需进行任何配置更改。
Access for Infrastructure 现在支持使用 YubiKey PIV 密钥对 SSH 连接实施独立多因素身份验证（MFA）。这为 SSH 访问添加了基于硬件的第二因素，确保仅凭受损的设备会话不足以访问您的服务器。
通过针对每个应用程序和每个策略的配置，您可以对敏感用户名（例如 root）强制执行 PIV 密钥身份验证，同时对其他用户名应用不同的要求。您还可以设置 MFA 会话时长，以控制用户必须重新进行身份验证的频率。
用户通过应用程序启动器注册其 YubiKey PIV 密钥。有关注册说明和 SSH 客户端设置，请参阅为基础设施应用程序注册 PIV 密钥。
有关设置说明，请参阅为基础设施应用程序强制执行 MFA。
并非所有 AI 流量都是相同的。现在，所有客户（包括使用免费计划的客户）都可以根据 AI 爬虫在您网站上的实际行为来对其进行管理。Cloudflare 将 AI 流量归类为三种行为，您可以对其进行独立控制：搜索 (Search)、代理 (Agent) 和训练 (Training)。这可以让您保留为您带来读者和收入的自动化流量，同时屏蔽那些只获取您内容的流量。
每种行为都对应一个真实的用例。Search（搜索） 涵盖了对您的内容进行索引以便稍后回答相关问题的爬虫，您可以期望从中获得引流流量或其他公平的补偿。Agent（代理） 涵盖代表个人实时操作的自动化活动，例如聊天获取机器人和浏览器使用代理。Training（训练） 涵盖获取您的内容以训练或微调模型的爬虫。对于每个预设，您可以选择在所有页面上屏蔽、仅在展示广告的页面上屏蔽，或选择不屏蔽。
自 2026 年 9 月 15 日起，新接入 Cloudflare 的域将获得更新的默认值：被归类为“Training（训练）”或“Agent（代理）”的机器人在显示广告的页面上将被屏蔽，而Search（搜索） 将保持允许状态。届时，结合了搜索和训练的通用爬虫将受到新的“Block Training（屏蔽训练）”默认值的影响。所有客户都可以在 9 月 15 日之前的任何时间选择退出新的默认值 ↗。
随着 2026 年内容独立日（Content Independence Day 2026）的到来，Enterprise Bot Management 客户获得了两个全新工具，使机器人流量更容易被查看和分析：BotBase（Cloudflare 跟踪的每个机器人的可搜索目录）以及 Attribution Business Insights（显示每个爬虫为您的业务带来的价值的仪表板）。
BotBase 是 Cloudflare 所有已知机器人和代理的目录，可直接在仪表板中访问。它显示了 Cloudflare 如何根据行为对每个机器人进行分类——Search、Agent、Training，以及其他类别（例如 Transact、Data Collection、SEO 和 Ads Verification）——以便您了解特定爬虫访问您的原因。您可以搜索和筛选完整的目录，将您自己的流量筛选到单个机器人以调查其在您的区域 (zone) 上的活动，并复制任何机器人的检测 ID 以在安全规则 (Security rules) 中对其进行精准定位。BotBase 中每个被跟踪的机器人也会发布在 Cloudflare Radar 的机器人和代理目录 ↗中。
Attribution Business Insights 专为内容所有者和业务决策者设计，使他们无需阅读规则语法即可了解哪些机器人对业务有益或有害。该仪表板会报告整个网站和每个机器人运营商在过去 24 小时、7 天或 30 天内的抓取与引流比例——将公司抓取您内容的频率与其实际引流回来的访问者数量进行对比。每个运营商都贴有 Cloudflare 更新的分类标签，以及“已允许 (Allowed)”、“已屏蔽 (Blocked)”或“部分屏蔽 (Partially blocked)”的操作状态，让利益相关者能够共享并一目了然地查看到达您网站的 AI 流量。
Containers 现在支持 Google Artifact Registry ↗ 镜像。配置凭据后，您可以在 Wrangler 配置中使用完全限定的 Google Artifact Registry 镜像引用，而无需先将镜像推送到 Cloudflare Registry。
使用 --gar-email 提供服务账户电子邮件，并通过 stdin 用管道传输服务账户 JSON 密钥：
cat <PATH_TO_KEY> | npx wrangler containers registries configure <REGION>-docker.pkg.dev --gar-email=<SERVICE_ACCOUNT_EMAIL> --secret-name=<SECRET_NAME>{
"$schema": "./node_modules/wrangler/config-schema.json",
"containers": [
{
"image": "<REGION>-docker.pkg.dev/<PROJECT_ID>/<REPOSITORY>/<IMAGE>:<TAG>"
}
]
}# 示例: us-central1-docker.pkg.dev/my-project/my-repo/my-image:latest
[[containers]]
image = "<REGION>-docker.pkg.dev/<PROJECT_ID>/<REPOSITORY>/<IMAGE>:<TAG>"仅支持 *-docker.pkg.dev 主机。要配置凭据，请参阅使用私有 Google Artifact Registry 镜像。
欲了解更多信息，请参阅镜像管理。
Images 绑定（binding）现在按唯一转换计费，这与已用于基于 URL 转换的计费模型一致。在同一个日历月内对相同源图像和参数组合的重复请求仅计算一次。
在此之前，无论图像或参数是否唯一，对绑定的每次调用都被计为一次单独的转换。有了这项改进，您可以在热点路径上调用绑定，而无需为每个单独的请求付费。
对 .info() 的调用不再计费。
欲了解更多信息，请参阅 Images 定价和 Images 绑定文档。
我们大幅提升了 Vectorize 预写日志（WAL） ↗的吞吐量。因此，向量变更变为可查询的端到端延迟显著降低：中位延迟从 2 分钟降至 30 秒以内，p99 延迟从 5 分钟降至 2 分钟以内。
这意味着插入、upsert 和删除操作将更快地反映在查询结果中，提升语义搜索、推荐和检索增强生成（RAG）工作负载的数据新鲜度。您无需更改代码或配置即可受益于此改进。
有关更多信息，请参阅 Vectorize 文档。
此版本增加了针对 Fortinet FortiSandbox 中路径遍历缺陷（CVE-2026-39813）的针对性覆盖，并将 Anomaly:Header:User-Agent - Fake Bing or MSN Bot 规则操作从阻断转换为已禁用。
主要发现
| 规则集 | 规则 ID | 旧版规则 ID | 描述 | 先前操作 | 新操作 | 注释 |
|---|---|---|---|---|---|---|
| Cloudflare 托管规则集 | 无 | Fortinet FortiSandbox - Path Traversal - CVE:CVE-2026-39813 | 记录 | 阻断 | 这是新的检测。 | |
| Cloudflare 托管规则集 | 无 | Anomaly:Header:User-Agent - Fake Bing or MSN Bot | 已启用 | 已禁用 | 我们将此规则的操作从阻断更改为已禁用。 |
您现在可以为 Cloudflare Gateway 防火墙策略和 Zero Trust 列表分配细粒度的资源作用域角色。管理员可以委派对特定策略类型或列表管理的访问权限，而无需授予账户范围或产品范围的控制权。
当您添加成员或创建权限策略时，现在可以使用以下资源作用域角色：
| 角色 | 说明 |
|---|---|
| Zero Trust Gateway Firewall Policies Admin | 可以查看和编辑所有 Gateway 防火墙策略，包括 DNS、HTTP 和网络策略。 |
| Zero Trust Gateway DNS Policies Admin | 可以查看和编辑 Gateway DNS 策略。 |
| Zero Trust Gateway HTTP Policies Admin | 可以查看和编辑 Gateway HTTP 策略。 |
| Zero Trust Gateway Network Policies Admin | 可以查看和编辑 Gateway 网络策略。 |
| Zero Trust Gateway Egress Policies Admin | 可以查看和编辑 Gateway 出口策略。 |
| Zero Trust Gateway Resolver Policies Admin | 可以查看和编辑 Gateway 解析器策略。 |
| Zero Trust Gateway Policies Admin | 可以查看和编辑所有 Gateway 策略。 |
| Zero Trust Gateway Policies Read | 可以查看所有 Gateway 策略。 |
| Zero Trust Gateway Read Only | 可以查看所有 Gateway 资源。 |
| Zero Trust DNS Locations Admin | 可以查看和编辑 DNS 位置。 |
| Zero Trust Proxy Endpoints Admin | 可以查看和编辑 Gateway 代理端点。 |
| Zero Trust Account Lists Admin | 可以查看和编辑所有 Gateway 和 Access 列表。 |
| Zero Trust Account Lists Read | 可以查看所有 Gateway 和 Access 列表。 |
这些角色允许您：
您现在还可以分配 资源作用域角色。这些角色是对现有账户级别角色的补充，允许您授予对特定资源（例如单个 Gateway 策略或 Cloudflare One 列表）的访问权限。现有的账户级别角色继续有效。 拥有 Cloudflare Gateway 或 Cloudflare Zero Trust 角色的成员将保留对所有 Gateway 资源的完全访问权限。这确保了与现有自动化和 API 令牌的向后兼容性。
Cloudflare Logpush 现在支持防火墙事件作为账户范围数据集。在账户级别配置一个 Logpush 任务，即可接收账户中每个区域的防火墙事件，而无需为每个区域单独创建和维护任务。
该数据集包含一个新的 ZoneName 字段，以便您在下游管道中处理日志时识别每个事件来自哪个区域。
firewall_events 数据集，可通过 Logpush API 或 Cloudflare 仪表板进行配置。ZoneName 字段。您现在可以使用 Workers 指标（Metrics）选项卡中新增的 Memory Usage（内存使用情况） 图表，监控您的 Workers 和 Durable Objects 在多次调用中消耗了多少内存，图表按 P50、P90、P99 和 P999 百分位数进行了细分。
内存使用情况测量的是每次调用时的 V8 isolate 内存，受限于 每个 isolate 128 MB 的限制 —— 单个 isolate 可以处理许多并发请求并在它们之间共享内存。
使用内存使用情况图表可以：
Exceeded Memory（超出内存）错误之前，发现可能表明存在内存泄漏的渐进式内存增加。对于 Durable Objects，内存使用情况反映了对象保存的内存中状态（类属性、缓存、活动的 WebSocket 连接），该状态在多次调用之间保持不变，直到对象被休眠或逐出。在逐出、休眠或崩溃时，此状态不会保留，因此请将任何重要内容持久化保存到存储中。
要查看内存使用情况，请打开您的 Worker ↗ 或 Durable Object 命名空间 ↗ 的 Metrics（指标） 选项卡。对于 Durable Objects，您可以按 DO ID 或名称进行过滤，以深入查看特定对象的内存使用情况。您还可以通过 GraphQL Analytics API 使用 workersInvocationsAdaptive 数据集以编程方式查询内存使用情况 —— 从 quantiles.memoryUsageBytesP50 到 quantiles.memoryUsageBytesP999 的字段以字节为单位返回百分位数。
对于本地内存调试，您还可以使用 DevTools 剖析内存以获取堆快照并识别导致高内存占用的特定对象。
A new GA release for the Windows Cloudflare One Client is now available on the stable releases downloads page.
This release introduces multiple features from our previous beta release into stable release, including:
Additional Changes and improvements
api.devices.cloudflare.com SNI, where previously both zero-trust-client.cloudflareclient.com and notifications.cloudflareclient.com were used. Review Cloudflare One Client with firewall to ensure systems that rely on SNI inspection do not block the API traffic. The behavior of previous client versions is unaffected.${serial_number}, ${device_uuid}) in the Subject Alternative Name field. Previously only the Common Name field accepted variables, which broke posture rules that pinned identity to a SAN entry.Known issues
A new GA release for the macOS Cloudflare One Client is now available on the stable releases downloads page.
This release introduces multiple features from our previous beta release into stable release, including:
Additional Changes and improvements
api.devices.cloudflare.com SNI, where previously both zero-trust-client.cloudflareclient.com and notifications.cloudflareclient.com were used. Review Cloudflare One Client with firewall to ensure systems that rely on SNI inspection do not block the API traffic. The behavior of previous client versions is unaffected.${serial_number}, ${device_uuid}) in the Subject Alternative Name field. Previously only the Common Name field accepted variables, which broke posture rules that pinned identity to a SAN entry.Known issues
A new GA release for the Linux Cloudflare One Client is now available on the stable releases downloads page.
This release introduces multiple features from our previous beta release into stable release, including:
Additional changes and improvements
api.devices.cloudflare.com SNI, where previously both zero-trust-client.cloudflareclient.com and notifications.cloudflareclient.com were used. Review Cloudflare One Client with firewall to ensure systems that rely on SNI inspection do not block the API traffic. The behavior of previous client versions is unaffected.${serial_number}, ${device_uuid}) in the Subject Alternative Name field. Previously only the Common Name field accepted variables, which broke posture rules that pinned identity to a SAN entry.For RHEL deployments, this release introduces a dependency on the Extra Packages for Enterprise Linux repository (EPEL). The EPEL repository provides packages that support the captive portal detection’s in-app browser authentication and system tray icon. See Getting started with EPEL for instructions on enabling EPEL.
Known issues
Workers fetch() 请求现在支持 cf.vary 请求选项。使用 cf.vary 可以控制 Cloudflare 如何为单个子请求缓存具有 Vary 标头的源服务器响应。
export default {
async fetch(request) {
return fetch(request, {
cf: {
vary: {
default: { action: "bypass" },
headers: {
accept: {
action: "normalize",
media_types: ["text/html", "application/json"],
},
"accept-language": {
action: "normalize",
languages: ["en", "fr", "de"],
},
},
},
},
});
},
};export default {
async fetch(request): Promise<Response> {
return fetch(request, {
cf: {
vary: {
default: { action: "bypass" },
headers: {
accept: {
action: "normalize",
media_types: ["text/html", "application/json"],
},
"accept-language": {
action: "normalize",
languages: ["en", "fr", "de"],
},
},
},
},
});
},
} satisfies ExportedHandler;有关更多信息，请参阅 cf.vary。
Agents SDK ↗ 的最新版本使得在后台运行长时间工作、通过一个入口点驱动轮次以及让聊天 agent 在部署、驱逐和重新连接期间保持正常工作变得更加容易。
此版本添加了一等的独立（后台）子 agent 运行（具有实时进度和持久里程碑）、单个 runTurn 轮次准入入口点，以及大量的恢复和可靠性修复，这些修复继续将 @cloudflare/think 和 @cloudflare/ai-chat 收敛到同一个模型上。
runAgentTool 现在可以派发一个子 agent，而不会阻塞调用轮次。独立的运行会立即返回一个句柄，并由一个持久的、在驱逐中存活的骨干（backbone）所拥有，而不是在派发轮次结束时被放弃。
class OrdersAgent extends Think {
async startImport(input) {
// Fire-and-forget, or wire a durable completion callback
// (by method name, like schedule()):
await this.runAgentTool(ImportAgent, {
input,
detached: { onFinish: "onImportDone", maxBudgetMs: 60 * 60 * 1000 },
});
}
// result.status: "completed" | "error" | "aborted" | "interrupted"
async onImportDone(run, result) {}
}class OrdersAgent extends Think {
async startImport(input) {
// Fire-and-forget, or wire a durable completion callback
// (by method name, like schedule()):
await this.runAgentTool(ImportAgent, {
input,
detached: { onFinish: "onImportDone", maxBudgetMs: 60 * 60 * 1000 },
});
}
// result.status: "completed" | "error" | "aborted" | "interrupted"
async onImportDone(run, result) {}
}亮点：
maxBudgetMs 上限（默认 24 小时）和 cancelAgentTool(runId) 可以防止被放弃的运行永远占用并发槽位。detached: { notify: true } 允许已完成的后台运行将消息注入回聊天中，以便模型对结果做出反应 —— 无需手动连接 onFinish。子 agent 还可以报告运行中进度，这些进度会通过它们自己的轮次流返回到父级连接的客户端：
// Inside the child sub-agent:
await this.reportProgress({
fraction: 0.6,
phase: "deploying",
message: "Generating menu page…",
});// Inside the child sub-agent:
await this.reportProgress({
fraction: 0.6,
phase: "deploying",
message: "Generating menu page…",
});进度通过 useAgentToolEvents 呈现在 AgentToolRunState.progress 上，因此后台运行托盘（tray）可以渲染实时进度条而无需深入查看，并且最新快照会被持久化以便在驱逐后进行检查。命名一个 milestone（里程碑）会将一个信号提升为持久的、可重放的行，并且 detached: { onMilestones } 可以将里程碑呈现为合成聊天消息（对于简单的状态行使用 "narrate"，或者使用 "react" 来驱动模型轮次）。
@cloudflare/think 添加了一个公共 runTurn(options) 外观（facade），将轮次准入统一在单个 mode 后面：
await this.runTurn({ mode: "wait", messages }); // saveMessages / continueLastTurn
await this.runTurn({ mode: "submit", messages }); // durable submitMessages
await this.runTurn({ mode: "stream", messages }); // chat()await this.runTurn({ mode: "wait", messages }); // saveMessages / continueLastTurn
await this.runTurn({ mode: "submit", messages }); // durable submitMessages
await this.runTurn({ mode: "stream", messages }); // chat()stream 模式接受数组和函数输入以匹配 wait 模式，所有入口点现在都通过共享的内部准入路径进行路由，该路径在之前可能导致死锁的嵌套阻塞准入上会抛出清晰的错误。
此版本的很大一部分继续强化恢复，并将 @cloudflare/think 和 @cloudflare/ai-chat 收敛到同一个模型上：
AIChatAgent 可以通过选择启用的 chatStreamStallTimeoutMs 看门狗检测并从挂起的模型/传输流中恢复。启用 chatRecovery 后，停滞将路由到部署或驱逐使用的相同有界恢复机制中；否则，它会作为终端流错误显现，以便清除加载指示器。AIChatAgent 现在在重新进入推理之前会修复带有已死服务器工具调用的脚本（与 @cloudflare/think 保持一致），因此恢复的轮次不再因 AI_MissingToolResultsError 而失败。可重写的 repairInterruptedToolPart(part) Hook 允许应用程序自定义修复后的形状。status 卡住的问题，因此 UI 现在会渲染进行中的轮次，而不是卡在 ready。AIChatAgent 现在会将恢复状态回放到在恢复途中连接的客户端，因此 useAgentChat 的 isRecovering 会立即反映进行中的恢复，而不是显得冻结。AgentClient、useAgent 和 useAgentChat 上的 connectionError / onConnectionError 暴露它们。interrupted（中断）放弃（对于 @cloudflare/think 和 AIChatAgent 皆是如此）。AIChatAgent 中的结构化行大小压缩。agents/chat/react 入口暴露了 useAgentChat、传输辅助函数和共享线缆（wire）类型，具有用于服务器权威脚本存储的 syncMessagesToServer。@cloudflare/think/react and @cloudflare/ai-chat/react 现在只是它的薄包装器。ai 同级依赖。 根 agents and @cloudflare/codemode 运行时不再引用 AI SDK 类型，因此它们可以在不安装 ai / zod 的情况下打包；特定于 AI 的入口点在导入时仍然需要同级依赖。just-bash 同样移动到了仅由 skills bash 运行器使用的可选同级依赖中。DynamicWorkerExecutor 超时时间从 30 秒增加到 60 秒，每次运行后现在会销毁动态加载的 Worker 及其 RPC 存根（stub）（修复了不稳定的隔离区关闭断言），连接器导入已被清理，并且外部 MCP 工具调用上下文会被传递给 openApiMcpServer 请求回调。fullStream 响应（并在使用 textStream 时发出警告）。McpAgent 服务器到客户端的请求现在可以从不继承 agent 异步上下文的回调中发送，包括通过 Worker Loader RPC 到达的回调。action() / getActions()）和统一的通道表面（configureChannels()、deliverNotice()）奠定了基础。两者都是实验性的，它们的 API 可能会发生变化，因此我们目前不建议依赖它们。要更新到最新版本：
npm i agents@latest @cloudflare/think@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/voice@latestyarn add agents@latest @cloudflare/think@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/voice@latestpnpm add agents@latest @cloudflare/think@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/voice@latestbun add agents@latest @cloudflare/think@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/voice@latest有关更多信息，请参阅 Think 文档、Code Mode 文档和 Agents 文档。