computer:基于 Cloudflare Durable Object 的虚拟文件系统项目

Give your agent a computer 👾

分支19Tags19
文件最后提交记录最后更新时间
20 天前
19 天前
27 天前
17 天前
4 天前
17 天前
20 天前
3 个月前
26 天前
20 天前
27 天前
1 个月前
3 个月前
4 天前
1 个月前
21 小时前
27 天前

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:gitws:artifacts 模块。

一个 Workspace 可以在稳定 ID 下注册多个后端。 workspace.runtime.exec(source, { backend }) 是唯一的执行入口点;所选后端决定 source 是 shell 命令还是 ECMAScript 模块。后端在首次使用时延迟连接。

Workspace 也可以完全不使用任何后端来构造,从而让调用方单独获得文件系统。

Important

仅预览 此包仅作为预览提供,以便收集反馈。 API 不稳定,设计可能会变更。

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

docs/ 下的规范具有前瞻性——请阅读其意图,而非将其视为对当前代码的描述。

使用

如果你想基于 Cloudflare Computer 构建,请安装 @cloudflare/computer 并遵循该 包的 README——其中包含安装步骤、入口点映射,以及 fsruntime 接口的完整示例。

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

示例

examples/ 目录包含可直接运行的公共接口使用方。每个示例都是一个 Worker workspace,并附有独立的 README。

  • examples/container — 在容器内运行 computerd,挂载 workspace,并通过 capnweb 与 Durable Object 通信。提供 write / read / exec HTTP 接口。
  • examples/worker-shell — 与容器示例相同的 HTTP 接口,但 shell 在通过 env.LOADER 加载的 Dynamic Worker 中运行 just-bash,无需容器。
  • examples/worker-javascript — 与 worker-shell 类似,但 exec 会在 Dynamic Worker 中评估 ECMAScript 模块,而不是执行 shell 命令。
  • examples/egress — 通过容器、Worker shell 和 Worker JavaScript 后端发送一个 URL,并使用对应的 none、all 或自定义 egress 策略。
  • examples/mcp — 一个 Computer MCP 示例:提供由 durable workspace、Worker shell 和完整 Linux 容器支撑的 Code Mode code 工具。
  • examples/rlm — 展示生成的 JavaScript 如何从 Computer Workspace 读取长上下文,调用受限的 model workers,并用代码归并它们的结构化结果。
  • examples/think — 一个 @cloudflare/think 聊天 agent,使用 workspace 作为其工作目录,并可从终端访问。
  • examples/think-compare-runtimes — 一个 web UI,可将同一 agent 任务在 container 与 worker 运行时上并排运行。
  • examples/tutorial — 一个分步构建示例:一个 endpoint,一个 agent 在宿主机上写入 markdown 食谱卡片,并在容器中对它运行 pandoc 以生成 PDF。
  • examples/artifacts — 在 workspace 中生成一个 Worker 项目,并将其发布到 Cloudflare Artifacts,作为可直接 clone 的仓库。
  • examples/assets — 使用 Workers AI 将 prompt 转换为图片,写入 workspace,并通过 @cloudflare/computer/assets 返回可分享链接。

仓库结构

本仓库是一个小型 monorepo。每个包都有自己的 README,其中包含该包的状态和用法说明。

  • packages/dofs (@cloudflare/dofs) — Durable Object 中基于 SQLite 的虚拟文件系统、同步协议基础组件,以及面向 Node 的 @platformatic/vfs provider。
  • packages/rpc (@cloudflare/computer-rpc) — Durable Object 与 computerd 之间共享的 capnweb wire types 及服务端/客户端辅助函数。
  • 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-sdknpm install 对比以及复现方法,见 docs/19_performance.md

文档

贡献

我们通过 issue 和 discussions 接受 bug 报告、修复方案、功能请求和设计提案。我们不接受未经请求的 pull request。公开贡献渠道见 CONTRIBUTING.md

已获批准的协作者应遵循 COLLABORATORS.md 中的环境配置、代码格式、测试、提交信息和 pull request 规范。

如果你以 agent 身份在该仓库中工作,请从 AGENTS.md 以及 .agents/skills/ 下的技能开始。

许可证

MIT。请参阅 LICENSE

项目介绍

给你的智能体配备一台电脑 👾【此简介由AI生成】

定制我的领域
329.13 K507访问 GitHub