Cloudflare Computer push/pull API详解10分钟搞懂手动同步与exec自动同步的边界【免费下载链接】computerGive your agent a computer 项目地址: https://gitcode.com/GitHub_Trending/computer1/computerCloudflare Computer 是让 AI Agent 拥有一台计算机的开源虚拟文件系统它的核心数据同步机制就是 push/pull API。本文将从新手视角讲清楚两件事workspace.push()/workspace.pull()手动同步在什么场景该用以及runtime.exec()命令执行时自动同步的安全围栏如何工作——帮你精准判断哪种同步方式适合你的应用。一张图看懂 Cloudflare Computer 同步架构整个系统只有两个主角Durable ObjectDO 侧用 SQLite 存储权威的虚拟文件系统是事实来源重启不丢数据Container 侧沙箱容器里的computerd守护进程把同一份文件系统通过 FUSE 挂载成真实目录让命令像操作本地磁盘一样工作。两者之间通过一条 WebSocket 通道跑push/pull 双向同步协议每次变更都会被盖上单调递增的修订号revision谁有新变更就推给谁接收方按增量合并不用每次传整棵目录树。协议全貌见 docs/02_sync_protocol.md。两条同步路径手动 push/pull 与 exec 自动同步手动同步什么时候该自己调 push() 和 pull()Workspace对外只暴露两个同步方法实现见 packages/computer/src/workspace.ts方法方向作用workspace.push()DO → 容器把宿主侧新写的文件推送到容器返回推送条目数workspace.pull()容器 → DO把容器侧产生的变更拉回 SQLite返回{ applied, skipped }关键点包内没有后台轮询线程同步完全由你显式触发。以下场景必须手动调用纯文件系统流程你在 DO 侧用workspace.fs.writeFile()写了文件想让容器里的命令看见它——先push()Agent 交接Agent A 在容器里干完活Agent B 接手前先pull()确保读到 A 的最终写入文档称之为显式同步点容器重启后computerd的本地数据库是进程级的重启会丢本地状态下一次 push 会被当作全新基线重新灌入通常由重连逻辑自动兜底。exec 自动同步push → 执行 → pull 的括号结构只要走命令执行路径同步就自动发生你不需要手动调用。packages/computer/src/shell.ts 把每次exec()包成一个固定结构push预推→ 在容器里 spawn 命令 → 事件流/结果返回 → pull回拉这个括号有三个新手容易忽略的细节预推是安全闸门不是优化。push 失败会直接让exec()拒绝执行命令不会带着过期的工作区跑起来回拉是幂等的。pull 按 256 条一批提交检查点中途崩溃也只重放一小批而且结果里带sync.statuscomplete表示同步完成pending表示命令本身成功了但回拉失败——可以之后用retryPendingSync()恢复不会重跑你的命令重连只重试一次。同步操作天然幂等靠水位线保证所以传输中断后可以安全重放但命令可能已经启动的场景绝不重放宁可报错也不让你执行两遍。执行结果的pushed/pulled计数就是这对括号的统计API 定义见 docs/05_runtime_interface.md。同步边界速查表哪些自动、哪些不自动操作是否自动同步说明workspace.runtime.exec(...)✅ 自动命令前后各同步一次push 括号 pull 括号workspace.fs.writeFile()等宿主侧写❌ 不自动需手动push()或等下一次 exec 的预推顺带发出容器内 FUSE 写文件⏳ 暂存每次写都盖章 revision等下一次pull()才回到 SQLiteworker-javascript/worker-shell后端 无需同步直接读写宿主权威存储sync: none计数恒为 0挂 R2/Artifacts 的只读挂载 拒绝回写容器侧写入只读挂载点会被跳过体现在skipped[]一句话总结边界命令执行自带同步围栏凡是绕过 exec 直接操作文件系统的场景同步责任就落在调用者身上。同步协议为什么快三个关键设计增量而非快照每次变更打上 revision同步只传对端没见过的部分同一路径改 5 次线上只走 1 条合并后的记录coalesce见 packages/dofs/src/sync/coalesce.ts按内容分块去重文件按 512 KiB 切块用 SHA-256 哈希寻址。两个路径放同一份node_modules只传一次改大文件只传动过的块。协商机制直接借用了 git 的 haves/wants 思路——hasObjects()问你有什么fetchObjects()/pushObjects()补传缺的忽略列表省钱fetchChanges默认忽略node_modules一次npm install不会把几万个碎片文件灌回 DO。容器里照样能用这些文件只是不跨线上行。完整 RPC 面6 个方法push/fetchChanges/watermarks/readEntry/hasObjects/fetchObjects定义在 packages/rpc/src/interface.ts帧格式说明见 docs/08_capnweb_interface.md。冲突语义最后是谁最后写赢多容器共享同一个 Workspace 时同步采用last-write-wins先拉远端再推本地但不做内容合并——两个容器改同一文件谁的 push 先到 DO 谁的版本存活另一个的修改被静默覆盖。这与不带锁的 NFS 共享挂载语义一致。对新手来说安全姿势有三条一个 Workspace 同时只有一个活跃写者——绝大多数 Agent 场景都符合多 Agent 分区写A 只写/workspace/a/B 只写/workspace/b/冲突从结构上不可能发生交接处显式 pull把 workspace 文件当作各 Agent 的私有草稿区而非共享可变状态。详见 docs/02_sync_protocol.md 的Conflict semantics一节。最佳实践清单 只读文件配置、脚手架宿主侧写好后 push 一次即可之后无需再管 长任务 exec不用关心同步看sync.status为complete即收敛 构建产物node_modules、dist保持默认忽略避免无谓流量 多 Agent 流水线在交接点手动pull()别假设自动围栏存在。去哪里看源码资料路径同步协议设计文档docs/02_sync_protocol.md手动同步门面Workspace 类packages/computer/src/workspace.tsexec 自动同步括号packages/computer/src/shell.ts双向同步驱动pullOnce / pushOnce / tickpackages/rpc/src/sync-driver.tsRPC 线格式定义packages/rpc/src/interface.ts运行时接口与结果类型docs/05_runtime_interface.md掌握这条手动 vs 自动的边界你就已经能正确驾驭 Cloudflare Computer 的数据一致性了——exec 里放心跑exec 外自己管。【免费下载链接】computerGive your agent a computer 项目地址: https://gitcode.com/GitHub_Trending/computer1/computer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考