cloudflare computer

Cloudflare Computer

Cloudflare Computer 是一个虚拟文件系统，它存在于 Durable Object 内部。该 Durable Object 在 SQLite 中持有权威状态，并通过 workspace.runtime 暴露一个可插拔的执行表面。目前内置了三种后端：

• Container：将 SQLite 状态以真实的 FUSE 挂载方式投射到沙箱容器中。沙箱侧的守护进程（computerd）将该状态挂载为文件系统，并通过 capnweb RPC 通道将变更同步回去。完整的 Linux 用户空间、真实的二进制文件、真实的网络。
• Isolate shell：在 Dynamic Worker 中仅运行 bash。它通过 Workers RPC 访问权威的 Workspace，因此没有第二份存储或同步往返。
• Isolate JavaScript：在一个全新的 Dynamic 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——其中包含安装步骤、入口点映射，以及 fs 和 runtime 表面的可运行示例。

如需贡献反馈，请参阅 CONTRIBUTING.md。经批准的协作者应遵循 COLLABORATORS.md 中的设置、构建和测试说明。

示例

examples/ 目录包含公共表面的可运行消费者。每个示例都是一个 Worker workspace，并带有自己的 README。

• examples/container — 在容器内运行 computerd，挂载一个 workspace，并通过 capnweb 与 Durable Object 通信。提供 write / read / exec 的 HTTP 表面。
• examples/worker-shell — 与 container 示例具有相同的 HTTP 表面，但 shell 在通过 env.LOADER 加载的 Dynamic Worker 中仅运行 bash。无需容器。
• examples/worker-javascript — 镜像 worker-shell，但 exec 在 Dynamic Worker 中评估 ECMAScript 模块，而不是运行 shell 命令。
• examples/think — 一个 @cloudflare/think 聊天代理，将 workspace 作为其工作目录，可从终端访问。
• examples/think-compare-runtimes — 一个 Web UI，并排运行相同的代理任务，分别使用 container 和 worker 运行时。
• examples/tutorial — 一个逐步构建的教程：一个端点，一个代理，在主机上编写 markdown 配方卡片，并在容器中对其运行 pandoc 以生成 PDF。
• examples/artifacts — 在 workspace 中生成一个 Worker 项目，并将其作为可克隆的仓库发布到 Cloudflare Artifacts。
• examples/assets — 使用 Workers AI 将提示词转换为图像，将其写入 workspace，并通过 @cloudflare/computer/assets 返回一个可分享的链接。

仓库结构

该仓库是一个小型 monorepo。每个包都有自己的 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) — 顶层 Computer 包，由 Durable Objects 使用。仍在开发中。
• packages/computer-computerd-linux-x64 — 预构建的 computerd linux-x64 二进制的私有 Docker 镜像上下文。发布产物是镜像，而不是 npm 包。

性能

computerd 的 FUSE 挂载在元数据密集型工作上优于真实磁盘，在大规模顺序 I/O 上则略逊一筹。完整的 fs-bench 数据、cloudflare/sandbox-sdk npm 安装对比以及复现方法，请参阅 docs/19_performance.md。

文档

• docs/ — 设计规范。前瞻性的；请视为设计意图。
• docs/19_performance.md — 文件系统基准测试。

贡献

我们通过 issue 和 discussion 接受错误报告、修复提案、功能请求和设计提案。我们不接受未经请求的 pull request。公开贡献路径请参阅 CONTRIBUTING.md。

经批准的协作者应遵循 COLLABORATORS.md 中的设置、格式化、测试、提交消息和 pull request 约定。

如果你以代理身份在此仓库中工作，请从 AGENTS.md 和 .agents/skills/ 下的技能开始。

许可证

MIT。参见 LICENSE。