01 / CONTAINER
容器Container · FUSE 挂载
将 SQLite 状态投射到沙箱容器中，作为真实的 FUSE 挂载。沙箱内的守护进程 computerd 将状态挂载为文件系统，并通过 capnweb RPC 通道将变更同步回去。
Durable Object · SQLite · 可插拔执行层
Cloudflare
Cloudflare
Computer.fs
一个运行在 Durable Object 内部的虚拟文件系统。以 SQLite 保存权威状态，通过 workspace.runtime 暴露可插拔的执行层 —— 容器、隔离 Shell、隔离 JavaScript，三种后端即插即用。
仅供预览
此包仅作为预览版提供以收集反馈。API 不稳定，设计可能发生变化。适用于实验、探索和原型，目前不适合生产环境使用。
docs/ 下的规范是前瞻性的 —— 请将其作为设计意图来阅读，而非对当前代码的描述。
01 · 概览
一台藏在 Durable Object 里的计算机
Cloudflare Computer 把权威状态收敛到 SQLite，把执行能力抽象为可插拔后端。一个 Workspace 可以在稳定 ID 下注册多个后端，也可以不配置任何后端 —— 此时调用方只能使用文件系统。
3种可插拔执行后端
1个执行入口 runtime.exec()
SQLiteDurable Object 权威状态存储
FUSE容器后端的真实文件系统挂载
02 · 执行后端
三种后端，一个入口
所选后端决定 source 是 shell 命令还是 ECMAScript 模块。后端在首次使用时惰性连接。
02 / ISOLATE SHELL
隔离 ShellDynamic Worker · just-bash
在 Dynamic Worker 中运行 just-bash。它通过 Workers RPC 直接访问权威 Workspace，因此不存在第二个存储或同步往返 —— 状态始终只有一份。
03 / ISOLATE JAVASCRIPT
隔离 JavaScriptDynamic Worker · ES Modules
在全新的 Dynamic Worker 中运行 ECMAScript 模块，支持结构化输入/输出、持久相对导入、已配置的库、基于 Workspace 的 node:fs/promises，以及受信任的 ws:git 与 ws:artifacts 模块。
03 · 运行模型
稳定 ID 下的多后端注册
一个 Workspace 可以在稳定 ID 下注册多个后端，调用侧无需关心执行发生在何处。
ƒ
唯一的执行入口
workspace.runtime.exec(source, { backend }) 是唯一的执行入口，执行位置由 backend 参数指定。
≔
source 的含义由后端决定
容器与隔离 Shell 后端将 source 视为 shell 命令；隔离 JavaScript 后端则将其视为 ECMAScript 模块。
◌
惰性连接
后端在首次使用时才建立连接，不为未使用的后端付出任何启动开销。
▤
纯文件系统模式
Workspace 也可以不配置任何后端来构建，此时调用方只能使用文件系统 —— 适合只需要权威状态的场景。
// 在稳定 ID 下注册多个后端 const workspace = await createWorkspace({ backends: { container: containerBackend(), shell: isolateShellBackend(), js: isolateJsBackend(), }, }); // shell 命令 → 容器 await workspace.runtime.exec( "ls -la /workspace", { backend: "container" } ); // ES 模块 → 隔离 JavaScript await workspace.runtime.exec( "./tasks/build.mjs", { backend: "js" } );
04 · 使用方式
安装与上手
如果你想基于 Cloudflare Computer 进行开发，安装 @cloudflare/computer 并参考该包的 README —— 其中包含安装步骤、入口映射，以及 fs 和 runtime 接口的完整示例。
# 安装顶层 Computer 包 $ npm install @cloudflare/computer
05 · 示例
examples/ 目录
包含公共接口的可运行消费者。每个示例都是一个独立的 Worker 工作区，附带自己的 README。
01examples/container
容器后端
在容器内运行 computerd，挂载 workspace，并通过 capnweb 与 Durable Object 通信。提供 write / read / exec HTTP 接口。
查看示例 →02examples/worker-shell
Worker Shell
与容器示例相同的 HTTP 接口，但 shell 是通过 env.LOADER 加载的 Dynamic Worker 中运行的 just-bash。无需容器。
查看示例 →03examples/worker-javascript
Worker JavaScript
与 worker-shell 类似，但 exec 在 Dynamic Worker 中执行 ECMAScript 模块而非运行 shell 命令。
查看示例 →04examples/think
Think 聊天代理
一个 @cloudflare/think 聊天代理，使用 workspace 作为其工作目录，可通过终端访问。
查看示例 →05examples/think-compare-runtimes
运行时对比 Web UI
一个 Web UI，可将相同的代理任务分别在容器和 Worker 运行时中并行执行以进行对比 —— 直观感受两种执行模型的行为差异。
查看示例 →06examples/tutorial
分步构建教程
一个端点：代理在主机上编写 markdown 食谱卡片，然后在容器中运行 pandoc 生成 PDF。
查看示例 →07examples/artifacts
Artifacts 发布
在 workspace 中生成一个 Worker 项目，并将其发布到 Cloudflare Artifacts 作为可克隆的仓库。
查看示例 →08examples/assets
Assets 图片生成
使用 Workers AI 将提示转换为图片，写入 workspace，并通过 @cloudflare/computer/assets 返回可分享链接。
查看示例 →06 · 仓库结构
小型 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 包。
Docker 镜像07 · 性能
元数据密集？快过真实磁盘
computerd 的 FUSE 挂载在元数据密集型操作上优于真实磁盘，在大型顺序 I/O 上则略逊。
完整的 fs-bench 数据、与 cloudflare/sandbox-sdk 的 npm install 对比，以及复现方法，都记录在性能文档中。
docs/19_performance.md →08 · 文档与贡献
深入阅读
❐设计规范
docs/ 目录下的设计规范具有前瞻性，请作为设计意图来阅读，而非对当前代码的描述。
其中 docs/19_performance.md 记录了文件系统基准测试的完整数据。
✦贡献方式
我们通过 issues 和 discussions 接受 bug 报告、修复提案、功能请求和设计提案。我们不接受未经邀请的 pull request。
如果你作为 AI 代理在此仓库中工作，请从 AGENTS.md 开始，并参阅 .agents/skills/ 下的技能文件。