Cloudflare Computer

Cloudflare Computer 适配器将 @cloudflare/computer 的 Workspace 封装为 Flue 在 Cloudflare 目标上的沙箱。该工作区是一个持久化的、基于 SQLite 的虚拟文件系统，运行在智能体自有的 Durable Object 中。命令通过该包的 worker-shell 后端执行，这是一个在 Dynamic Worker 中运行的纯 bash shell，直接操作持久化文件系统，因此智能体可以获得 Flue 完整的标准工具集（bash/grep/glob/read/write/edit），无需替换，也无需容器。

@cloudflare/computer 是 Cloudflare 的早期预览版 —— 适合实验和原型开发，不适合生产环境。

快速开始

使用 Cloudflare Computer 蓝图为现有 Flue 项目添加持久化工作区沙箱能力。在终端或你选择的编码智能体中运行以下命令：

flue add sandbox cloudflare-computer

概述

该蓝图会在 <source-root>/sandboxes/cloudflare-computer.ts 创建适配器。Shell 命令不是在你的 Worker 中运行：适配器通过 Worker Loader 绑定创建一个 Dynamic Worker，并在其中运行纯 bash，操作持久化文件系统。该绑定目前处于测试阶段（需要你的 Cloudflare 账户获得访问权限），以及其 Dynamic Worker 所需的 experimental 兼容性标志，是 Wrangler 配置中需要添加的两项内容；无需 API 密钥或环境变量：

{
  "compatibility_flags": ["nodejs_compat", "experimental"],
  "worker_loaders": [{ "binding": "LOADER" }],
}

两行单行重导出完成了接线：项目的 cloudflare.ts 重导出 WorkspaceServiceProxy（shell 通过它回拨的本地环回），每个使用沙箱的智能体模块重导出生成的 workspaceHost 扩展，使其 Durable Object 托管工作区。

// flue-blueprint: sandbox/cloudflare-computer@1
import { Workspace, type WorkspaceOptions /* ... */ } from '@cloudflare/computer';
import { WorkerShellBackend } from '@cloudflare/computer/backends/worker-shell';
import { createGitClient } from '@cloudflare/computer/git';
import type { Sandbox, SandboxFactory /* ... */ } from '@flue/runtime';
import { extend, getDurableObjectIdentity } from '@flue/runtime/cloudflare';

/** 从每个智能体模块重导出：`export { workspaceHost as cloudflare } ...` */
export const workspaceHost = extend({
  base: (Base) =>
    class extends Base {
      /* ... 捕获 Durable Object 状态；暴露工作区存根 ... */
    },
});

/** 每个智能体实例一个持久化 Workspace，与沙箱共享。 */
export function getComputerWorkspace(options: GetComputerWorkspaceOptions): Workspace {
  /* ... 带缓存的构造：DO 存储 + git 客户端 + WorkerShellBackend ... */
}

export function getComputerSandbox(options: GetComputerWorkspaceOptions): SandboxFactory {
  return {
    async createSandbox(): Promise<ComputerSandboxEnv> {
      const workspace = getComputerWorkspace(options);
      await workspace.fs.mkdir('/workspace', { recursive: true });
      return { ...createWorkspaceSandbox(workspace, '/workspace'), workspace };
    },
    // 没有 `tools` 覆盖：exec() 在这里可以工作，因此框架的标准
    // 工具集（bash/grep/glob/read/write/edit）原样适用。
  };
}

在智能体内部将 worker_loaders 绑定传递给 getComputerSandbox(...)：

'use agent';
import { env } from 'cloudflare:workers';
import { useModel, useSandbox } from '@flue/runtime';
import { getComputerSandbox } from '../sandboxes/cloudflare-computer';

export { workspaceHost as cloudflare } from '../sandboxes/cloudflare-computer';

export function Assistant() {
  useModel('cloudflare/@cf/moonshotai/kimi-k2.6');
  useSandbox(getComputerSandbox({ loader: env.LOADER }));
  return '你使用标准文件和 shell 工具来探索和编辑你的持久化工作区。';
}

应用自有的数据注入和检查通过工作区的原生接口进行：getComputerWorkspace(...)（或 computerWorkspace(harness.sandbox)）暴露 workspace.git 用于克隆和提交，暴露 workspace.fs 用于带外读写，适配器的 workspace 选项可重塑生成的 WorkspaceOptions —— 只读 R2 挂载、defaultGitIdentity、观察者、附加后端。从你的项目适配器文件导入所有这些辅助工具，而不是从 @flue/runtime/cloudflare。

适用场景

当文件必须持久存储在智能体自有的 Durable Object 中，且可通过 shell 表达的工作能够满足智能体需求时，使用 Cloudflare Computer —— 无需配置容器，Dynamic Worker 之外没有冷启动。文件系统状态在 Durable Object 重启后依然存在，上限约为 10 GB（与 DO 的 SQLite 存储共享）。

它不是一个 Linux 机器：命令在 JavaScript shell 中运行，没有原生二进制文件或包管理器。这是适配器的默认配置，而非该包的上限 —— @cloudflare/computer 可以针对同一持久化文件注册额外的执行后端，包括其完整 Linux 的 CloudflareContainerBackend，通过适配器的 workspace 选项作为应用自有的配置进行添加。如果智能体的基本需求是语言工具链、原生工具或可写存储桶挂载，请改用 Cloudflare Sandbox（Containers）。

参见沙箱和在 Cloudflare 上部署。