Cloudflare Computer 介绍

Cloudflare Computer 是一个存在于 Durable Object 内的虚拟文件系统。Durable Object 将权威状态存储在 SQLite 中，并通过 `workspace.runtime` 提供一个可插拔的执行界面。目前有三种后端：

• Container：将 SQLite 状态以真实的 FUSE 挂载方式投影到沙箱容器中。沙箱端的守护进程（`computerd`）将状态挂载为文件系统，并通过 capnweb RPC 通道同步更改。支持完整的 Linux 用户空间、真实的二进制文件和真实的网络。
• Isolate shell：在动态 Worker 中运行 `just-bash`。它通过 Workers RPC 连接到权威的 Workspace，因此无需二次存储或同步往返。
• Isolate JavaScript：在全新的动态 Worker 中运行 ECMAScript 模块，支持结构化输入/结果、持久的相对导入、配置库、基于 Workspace 的 `node:fs/promises` 以及受信任的 `ws:git` 和 `ws:artifacts` 模块。

一个 Workspace 可以在稳定的 ID 下注册多个后端。`workspace.runtime.exec(source, { backend })` 是唯一的执行入口；所选后端决定了 `source` 是一个 shell 命令还是一个 ECMAScript 模块。后端在首次使用时才会进行连接。Workspace 也可以在不使用后端的情况下构建，仅为调用者提供文件系统。

重要提示：仅为预览版 此软件包仅作为预览版提供，用于收集反馈。API 不稳定，设计可能会发生变化。适合进行实验、探索和原型开发，目前不适用于生产环境。`docs/` 下的规范具有前瞻性，应将其视为设计意图，而非当前代码的描述。

使用方法

如果你想基于 Cloudflare Computer 进行开发，可安装 `@cloudflare/computer` 并遵循该软件包的 README，其中包含安装步骤、入口点映射以及文件系统和运行时界面的示例。若要提供反馈，请参阅 `CONTRIBUTING.md`。经批准的协作者应遵循 `COLLABORATORS.md` 中的设置、构建和测试说明。

示例

`examples/` 目录包含了可运行的公共界面示例。每个示例都是一个 Worker 工作区，并有各自的 README。

• `examples/container`：在容器内运行 `computerd`，挂载工作区，并通过 capnweb 与 Durable Object 进行通信。提供写入/读取/执行的 HTTP 界面。
• `examples/worker-shell`：与容器示例具有相同的 HTTP 界面，但 shell 在通过 `env.LOADER` 加载的动态 Worker 中运行 `just-bash`，无需容器。
• `examples/worker-javascript`：类似于 `worker-shell`，但 `exec` 在动态 Worker 中评估 ECMAScript 模块，而非运行 shell 命令。
• `examples/think`：一个 `@cloudflare/think` 聊天代理，将工作区作为其工作目录，可通过终端访问。
• `examples/think-compare-runtimes`：一个 Web UI，可同时在容器和 Worker 运行时上运行相同的代理任务。
• `examples/tutorial`：逐步构建示例，包含一个端点和一个代理，该代理在主机上编写 Markdown 食谱卡片，并在容器中运行 `pandoc` 生成 PDF。
• `examples/artifacts`：在工作区中生成一个 Worker 项目，并将其作为可克隆的仓库发布到 Cloudflare Artifacts。
• `examples/assets`：使用 Workers AI 将提示转换为图像，将其写入工作区，并通过 `@cloudflare/computer/assets` 返回可共享的链接。

仓库布局

该仓库是一个小型的单体仓库。每个软件包都有自己的 README，包含特定于该软件包的状态和使用说明。

• `packages/dofs (@cloudflare/dofs)`：基于 Durable Object SQLite 的虚拟文件系统、同步协议构建块以及适用于 Node 的 `@platformatic/vfs` 提供程序。
• `packages/rpc (@cloudflare/computer-rpc)`：capnweb 线路类型以及 Durable Object 和 `computerd` 之间共享的服务器/客户端辅助工具。
• `packages/computerd (@cloudflare/computerd)`：`computerd` 守护进程，一个 FUSE 挂载加上在沙箱容器内运行的 HTTP/WebSocket RPC 服务器。
• `packages/computer (@cloudflare/computer)`：Durable Object 使用的顶级 Computer 软件包，正在开发中。
• `packages/computer-computerd-linux-x64`：预构建的 `computerd` Linux x64 二进制文件的私有 Docker 镜像上下文。该镜像（而非 npm 软件包）是发布制品。

性能

`computerd` 的 FUSE 挂载在处理大量元数据的工作时优于真实磁盘，但在大型顺序 I/O 方面表现较差。完整的文件系统基准测试数据、`cloudflare/sandbox-sdk` npm 安装比较以及复现方法请参阅 `docs/19_performance.md`。

文档

• `docs/`：设计规范，具有前瞻性，应视为设计意图。
• `docs/19_performance.md`：文件系统基准测试。

贡献

我们通过问题和讨论接受错误报告、修复建议、功能请求和设计提案，但不接受未经请求的拉取请求。公共贡献途径请参阅 `CONTRIBUTING.md`。经批准的协作者应遵循 `COLLABORATORS.md` 中的设置、格式化、测试、提交消息和拉取请求规范。如果你作为代理在该仓库中工作，请从 `AGENTS.md` 和 `.agents/skills/` 下的技能开始。

许可证

本项目采用 MIT 许可证，详情请参阅 `LICENSE`。