cloudflare/computer

来源：https://github.com/cloudflare/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（https://github.com/vercel-labs/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，让调用方仅获得文件系统本身。

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

适合实验、探索和原型开发。目前不适合在生产环境中使用。

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

使用方法

如果你想在 Cloudflare Computer 之上构建，请安装 @cloudflare/computer 并遵循该包的 README——其中包含安装步骤、入口点映射，以及 fs 和 runtime 表面的实际示例。

如需贡献反馈，请参阅 CONTRIBUTING.md。 经批准的协作者应按照 COLLABORATORS.md 进行设置、构建和测试。

示例

examples/ 目录包含针对公共表面的可运行消费端。每个都是一个 Worker 工作区，并带有自己的 README。

• examples/container — 在容器中运行 computerd，挂载一个工作区，并通过 capnweb 与 Durable Object 通信。提供 write / read / exec HTTP 表面。
• examples/worker-shell — 与容器示例相同的 HTTP 表面，但 shell 运行的是通过 env.LOADER 加载的 Dynamic Worker 中的 just-bash（https://github.com/vercel-labs/just-bash）。没有容器。
• examples/worker-javascript — 与 worker-shell 类似，但 exec 在 Dynamic Worker 中评估 ECMAScript 模块，而不是运行 shell 命令。
• examples/think — 一个 @cloudflare/think（https://www.npmjs.com/package/@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 返回可共享链接。

仓库布局

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

• packages/dofs（@cloudflare/dofs）— 基于 Durable Object SQLite 的虚拟文件系统、同步协议构建块，以及一个用于 Node 的 @platformatic/vfs 提供程序。
• packages/rpc （@cloudflare/computer-rpc）— 在 Durable Object 和 computerd 之间共享的 capnweb 线格式类型及服务器/客户端辅助工具。
• packages/computerd （@cloudflare/computerd）— computerd 守护进程：一个 FUSE 挂载加上运行在沙箱容器内的 HTTP/WebSocket RPC 服务器。
• packages/computer （@cloudflare/computer）— 由 Durable Objects 使用的顶层 Computer 包。仍在开发中。
• packages/computer-computerd-linux-x64 （@cloudflare/computer-computerd-linux-x64）— 为 linux-x64 预构建的 computerd 二进制文件，分发给容器镜像使用。

性能

在元数据密集型工作中，computerd 的 FUSE 挂载优于真实磁盘，而在大型顺序 I/O 中则落后于真实磁盘。请参阅 docs/19_performance.md 了解完整的 fs-bench 数据、cloudflare/sandbox-sdk 的 npm install 对比，以及如何重现这些结果。

文档

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

贡献

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

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

如果你以 Agent 身份在此仓库中工作，请先阅读 AGENTS.md 以及 .agents/skills/ 下的技能。

许可证

MIT。参见 LICENSE。