computer

Cloudflare Computer

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

• Container 将 SQLite 状态以真实 FUSE 挂载的形式投射到沙箱容器中。沙箱侧的守护进程（computerd）将状态挂载为文件系统，并通过 capnweb RPC 通道将变更同步回去。提供完整的 Linux 用户态、真实二进制文件、真实网络。
• Isolate shell 在 Dynamic Worker 中运行 just-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 也可以完全不配置后端来构建，调用方可以单独使用文件系统。

[!IMPORTANT] 仅限预览 此包仅作为预览提供，用于收集反馈。API 不稳定，设计可能会发生变化。

适用于实验、探索和原型。目前不适合用于生产环境。

docs/ 下的规范是前瞻性的——请将其视为设计意图，而非当前代码的描述。

如何使用

如果你想基于 Cloudflare Computer 构建，请安装 @cloudflare/computer 并按照该包的 README 操作——其中包含安装步骤、入口点映射，以及 fs 和 runtime 表面的可运行示例。

要提供反馈，请参阅 CONTRIBUTING.md。获得批准的协作者应按照 COLLABORATORS.md 的说明进行设置、构建和测试。

示例

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

• examples/container — 在容器中运行 computerd，挂载一个 workspace，并通过 capnweb 与 Durable Object 通信。提供 write / read / exec HTTP 表面。
• examples/worker-shell — 与 container 示例相同的 HTTP 表面，但 shell 在通过 env.LOADER 加载的 Dynamic Worker 中运行 just-bash。无需容器。
• examples/worker-javascript — 与 worker-shell 类似，但 exec 在 Dynamic Worker 中评估 ECMAScript 模块，而不是运行 shell 命令。
• examples/think — 一个 @cloudflare/think 聊天智能体，将 workspace 作为其工作目录，可从终端访问。
• examples/think-compare-runtimes — 一个 Web UI，并排运行相同的智能体任务，分别使用容器运行时和 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）— 基于 SQLite 的 Durable Object 虚拟文件系统、同步协议构建块，以及面向 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 Objects 使用的顶层 Computer 包。仍在开发中。
• packages/computer-computerd-linux-x64 — 预构建的 computerd linux-x64 二进制的私有 Docker 镜像上下文。发布产物是镜像，而不是 npm 包。

性能

computerd 的 FUSE 挂载在元数据密集型任务上优于真实磁盘，但在大型顺序 I/O 上略逊一筹。完整的 fs-bench 数字、cloudflare/sandbox-sdk npm install 对比以及复现方法，请参阅 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。