Cloudflare Computer | AI Agent 持久工作空间源码 – 三种执行后端

Cloudflare Computer 是一个面向 AI Agent 的开源 TypeScript 项目，核心 npm 包为 @cloudflare/computer。它把 Durable Object 中由 SQLite 支撑的持久虚拟文件系统，与可插拔的命令和代码执行后端组合为统一 Workspace，让 Agent 能在同一目录里读写文件、运行命令、操作 Git，并按任务选择 Worker 或 Container。

如果你想先了解 Cloudflare 为什么提出“Agent 需要电脑而不只是容器”，以及这套混合执行模型的发布背景，可以阅读站内的 Cloudflare Computer 的发布背景与“电脑而非容器”思路。本文集中查看仓库结构、API、部署条件、后端差异和当前限制。

截至 2026 年 8 月 11 日核对，npm 公共注册表的最新版本为 0.1.1，仓库未建立正式 GitHub Release。项目采用 MIT 许可证，但 README 在开头明确标注 PREVIEW ONLY：API 与设计都可能变化，只适合实验、探索和原型，不适合生产环境。版本号存在不等于稳定版承诺。

仓库提供的不是一台固定容器，而是一套 Workspace 接口

项目采用 monorepo 组织方式，主包负责 Workspace、文件系统代理和运行时入口，另有 Container、Worker Shell、Worker JavaScript、AI SDK Tools、Git、Assets、Artifacts 和观测适配等子入口。调用方可以只引入需要的后端，未使用的 Worker 模块可以被打包器移除。

workspace.fs 的用法接近 node:fs/promises，支持 readFile、writeFile、mkdir、readdir、rm 和 grep 等异步操作；workspace.runtime.exec() 则是统一执行入口。Workspace 甚至可以不配置任何执行后端，只作为持久文件系统使用。

Durable Object 与 SQLite 是文件系统的权威状态

每个 Workspace 由 Durable Object 承载，虚拟文件系统的权威状态写入该对象自己的 SQLite 存储。Worker 内的轻量后端可以通过绑定直接操作这些文件；Container 后端则运行 computerd，借助 FUSE 挂载、内存虚拟文件系统与同步协议，把命令产生的文件变更拉回 Durable Object。

Cloudflare Computer Durable Object、SQLite、FUSE 与 Container 同步架构 — 仓库中的架构图：SQLite 是 Durable Object 文件系统的权威状态，Container 通过 FUSE 与同步协议处理同一工作空间。

这个设计避免把 Workspace 永久绑定到某一只容器，但也引入同步和 I/O 成本。Container 侧文件系统保存在内存中，FUSE 访问不等于原生磁盘；项目文档建议把它用于小型 Agent 工作目录，而不是完整的大型 monorepo。

三种执行后端如何选择

后端	适合任务	额外条件
Container	真实 Linux 用户空间、npm、Node.js、系统二进制与网络命令	Cloudflare Container 与 computerd；冷启动和同步成本较高
Worker Shell	文本处理、Git、curl、轻量脚本和常见命令	基于 just-bash；需要 Worker Loader 与 experimental 标志
Worker JavaScript	执行 ECMAScript 模块、结构化输入输出与隔离 JS 逻辑	新的 Dynamic Worker；需要 Worker Loader 与 experimental 标志

同一个 Workspace 可以注册多个后端，并用稳定的 backend ID 选择执行位置。默认后端适合低成本通用命令，需要完整 Linux 时再指定 Container。不同后端共享 Workspace 文件，但同步游标相互独立，后端也采用惰性连接。

using run = await ws.runtime.exec(
  "npm test",
  { backend: "sandbox", encoding: "utf8" }
);
const { stdout, stderr, exitCode } = await run.result();

安装与最小 Wrangler 配置

安装主包只需要 npm。所有使用方式都要求 Worker 开启 nodejs_compat；Worker Shell 与 Worker JavaScript 还需要 experimental 兼容标志和 Worker Loader 绑定。Container 后端另有容器绑定及服务配置，不能只安装 npm 包就获得完整 Linux 环境。

npm install @cloudflare/computer

只启用持久文件系统时，可以把 Durable Object 类包装为 Workspace，并在迁移中创建 SQLite 类：

{
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [{ "name": "Agent", "class_name": "Agent" }]
  },
  "migrations": [
    { "tag": "v1", "new_sqlite_classes": ["Agent"] }
  ]
}

如果选择 Worker Shell 或 Worker JavaScript，则还要加入 "experimental" 与 Loader：

{
  "compatibility_flags": ["nodejs_compat", "experimental"],
  "worker_loaders": [{ "binding": "LOADER" }]
}

Worker Shell 的可选命令按功能组导入，包括 curl、Python、SQLite、jq、yq、文件识别与 JavaScript 执行等。未导入的命令不会进入最终 bundle，这有助于控制能力面和包体积，但也意味着示例中的 shell 并不是无所不包的 Linux。

文件、Git 和 AI SDK 工具可以直接组合

仓库提供基于 isomorphic-git 的可选 Git 客户端，它直接操作 SQLite 虚拟文件系统，不要求先启动 shell。AI SDK 入口则能创建 read、write、edit、ls 工具；配置后再加入 exec 与 publish。Assets 可以把 Workspace 文件上传到 R2 并生成预签名 URL，Artifacts 则提供按会话隔离的产物接口。

这种模块化设计的价值在于 Agent 框架面对的是稳定的文件与执行表面，而不是直接依赖某一种容器 API。不过，仓库 docs/ 中的设计规范包含前瞻内容，README 明确提醒：设计意图不一定等于当前代码全部实现，评估时应以对应版本的包 API、测试和示例为准。

容量、性能与 RPC 生命周期限制

容量：每个 Workspace 约 10 GB，并与 Durable Object 共享存储配额。
重 I/O：Container 通过 FUSE 访问文件，大型依赖安装与大压缩包解包会比原生磁盘慢。
内存：Container 侧文件系统驻留内存，不适合无边界增长的工作目录。
实验标志：两种 Worker 执行后端依赖 experimental 与 Worker Loader，平台兼容性要按当前 Cloudflare 文档复核。
RPC 释放：getWorkspace() 和 runtime.exec() 返回的远程 stub/handle 不会自动在对端回收，长会话应使用 using 或显式释放，避免累积。

此外，容器命令完成后的回拉同步可能失败，结果会标记为 pending。项目允许接入重试调度器，但不会自动替应用管理 Durable Object alarm。准备做长任务或多后端切换时，应把同步失败、超时、幂等和恢复流程纳入应用设计。

MIT 许可与贡献边界

仓库代码采用 MIT 许可证，允许使用、修改和再分发，但需要保留版权与许可声明，且软件不提供担保。Cloudflare 的名称和商标不因代码采用 MIT 就自动开放品牌使用。

项目当前欢迎通过 Issues 和 Discussions 提交问题与反馈，但仓库说明暂不接受未经邀请的 Pull Request。准备二次开发时，可以 fork 后自行验证；若希望贡献上游，先讨论设计和维护方向，避免直接提交大规模改动。

适合哪些项目

Cloudflare Computer 适合已经使用 Cloudflare Workers/Durable Objects，想为编程 Agent、研究助手或自动化流程增加持久工作目录，并希望把轻量命令与完整 Linux 分级执行的团队。它尤其适合验证“多数操作留在 Worker，少数任务进入 Container”的产品架构。

如果项目要求稳定 API、本地或多云部署、原生磁盘吞吐、超大仓库、严格生产 SLA，当前 Preview 版本并不合适。更稳妥的做法是用代表性任务制作小型原型，记录冷启动、执行、同步、存储与容器成本，等接口和平台依赖稳定后再决定是否进入核心链路。