cloudflare/computer 0.2.x 版本演进全解读Worker 后端、Git 增强与执行可靠性改进【免费下载链接】computerGive your agent a computer 项目地址: https://gitcode.com/GitHub_Trending/computer1/computer导读cloudflare/computer是 Cloudflare Computer 项目的核心 npm 包它把 Durable Object、SQLite 与多种执行后端容器 shell、Worker shell、Worker JavaScript组合成可供 AI Agent 使用的工作区Workspace。本文以 packages/computer/CHANGELOG.md 为主线逐一拆解 0.2.0 与 0.2.1 两个版本引入的架构级变更Worker 后端的模块化瘦身、egress 网络策略统一、文件系统工具集增强、git 模块的 revision 支持以及执行中断后的容器重连恢复机制。阅读完成后你将掌握这些变更背后的设计动机、对应的源码位置与可落地的配置方式。版本总览0.2.x 带来了什么0.2.0一次整合 扩充的小版本。将 egress 配置在三个执行后端间统一通过 RPC 暴露有界bounded的工作区字节读取并返回带文件元数据的分页目录列表read工具支持图片与 data URI 格式find/grep工具支持更多过滤参数并新增delete工具通过 worker-shell 把大量命令改为按需引入opt-in以大幅压缩 bundle 体积。0.2.1一次聚焦可靠性的补丁版本。在 Worker JavaScript 能力capability超限错误中内嵌配置的字节上限git 模块支持短 revision idcontainer-shell操作在 computerd 重启后可安全重连进程本地执行在容器替换后返回EEXEC_LOST。下文按主题拆解每个主题都同时给出变更内容 源码/文档依据 实战含义。一、bundle 瘦身worker-shell 命令按需引入变更内容0.2.0 通过 PR #41commita753db7Reduced the size of bundles using worker-shell by making many commands opt-in即把 worker-shell 中较重的命令拆成核心组 可选组只有被 import 的命令组才会进入最终 bundle。官方文档 docs/12_worker_backend.md 的 Optional shell commands 一节对此有完整说明。实现机制从源码看这一设计建立在以 import 而非编译期 flag 选择的机制之上见 packages/computer/src/backends/worker-shell/shell-modules.ts构建脚本build-bundle.mjs以splitting: true运行 esbuild把产物按模块切分为一个核心组所有常驻命令 ShellWorker入口和每个可选命令各自的一组并分别发布到cloudflare/computer/shell/feature子路径SHELL_CORE_MODULES是常驻的核心模块组类型为ReadonlyRecordstring, { js: string }模块名 → 源码字符串assembleShellModules([...groups])把核心组与消费者传入的可选组合并供需要自己构造 Loader 回调的外部 runtime source 使用。由于核心模块组从不引用可选组一个从未被 import 的组在消费者的模块图中不可达bundler 会直接丢弃它——没有需要设置的构建标志也没有默认开启的额外成本这一点在 packages/computer/src/backends/worker-shell/shell-modules.ts 的注释中明确说明。如何按需引入命令import curlModules from cloudflare/computer/shell/curl; import htmlToMarkdownModules from cloudflare/computer/shell/html-to-markdown; new WorkerShellBackend({ loader: env.LOADER, workspace: { binding: ContainerExample, id: ctx.id.toString() }, ctx, commands: [curlModules, htmlToMarkdownModules], });完整可用的可选命令组为curl、html-to-markdown、python、sqlite、js-exec、yq、file、xan、jq。核心组始终携带cat、ls、grep、sed、awk、sort等常驻命令。两点值得注意的实现细节均来自文档与源码curl运行在一个基于 isolate 全局fetch的SecureFetch适配器上——undici在构建期被重定向到抛错的 stub永远不会被打包进去即使引入了curl出站网络仍由后端的WorkspaceEgressPolicy管控而不是由 shell 自行决定因此启用 curl不等于打开网络。测试侧也有对应约束packages/computer/src/backends/worker-shell/shell-modules.test.ts 验证了assembleShellModules()与核心组等价、加入curlModules/sqliteModules后模块表被正确合并。实战含义对以 worker-shell 作为执行后端的 Agent 而言bundle 体积直接决定 Worker 的冷启动与按量成本。把jq、python、sqlite这类重量级命令改成按需引入后不用的功能在模块图中物理消失相比传统的 feature flag 方案更彻底。二、egress 网络策略统一变更内容0.2.0 通过 PR #88commit9ecb912Consolidate egress configuration across the existing backends并在 examples/egress 提供了三后端对照示例。egress 三模式速查examples/egress/README.md 用EGRESS_MODE环境变量统一驱动容器 shell、Worker shell、Worker JavaScript 三个后端模式对照如下EGRESS_MODEWorkspace 策略行为none{ mode: none }阻止出站网络访问默认all{ mode: direct }允许直接出站访问custom{ mode: http-gateway }经由仅放行https://example.com的网关其他来源返回403在 Worker shell 后端中模式直接体现为构造参数见 docs/12_worker_backend.md 的 Wire shape 一节// 默认阻断环境网络 new WorkerShellBackend({ loader: env.LOADER, workspace: { binding: ContainerExample, id: ctx.id.toString() }, ctx, egress: { mode: none }, }); // 直接出站 new WorkerShellBackend({ /* ... */ egress: { mode: direct }, }); // 经由 Fetcher 网关 new WorkerShellBackend({ /* ... */ egress: { mode: http-gateway, gateway, revision }, });网关模式与 isolate 缓存的关系http-gateway模式需要稳定的revision它让 Worker Loader 在网关策略未变化前复用同一个 isolate没有revision时每个后端生命周期都会使用全新的缓存身份。因为 egress 策略身份参与 isolate 缓存 key缓存 id 形如workspace-shell:${workspace.id}再加上策略身份一个策略变化绝不能复用一个网络权限更宽的 isolate。这些模式约束的是 shell 发起的环境级fetch()与connect()宿主侧能力保持独立——例如宿主转发的 git 命令可以拥有自己的网络权限而环境级 shell 网络被完全阻断。运行示例验证npm run dev --workspace example/computer-egress -- --var EGRESS_MODE:none npm run dev --workspace example/computer-egress -- --var EGRESS_MODE:all npm run dev --workspace example/computer-egress -- --var EGRESS_MODE:customcurl -X POST http://127.0.0.1:8787/fetch?urlhttps%3A%2F%2Fexample.comall模式下三个后端container / worker-shell / worker-javascript都返回200与text/htmlnone模式下各后端返回error对象custom模式下访问 allowlist 之外如cloudflare.com的来源三个后端一致返回403与text/plain。示例的目录结构examples/egress中Dockerfile打包 computerd、FUSE 库与 curlwrangler.jsonc声明 Worker Loader、container、durable object 与EGRESS_MODE。三、文件系统工具增强有界读取、分页目录与图片支持有界字节读取与分页目录列表0.2.0 的 commit2bfce96通过 RPC 暴露了有界bounded的工作区字节读取并让目录列表支持分页且附带文件元数据。这意味着在大文件或大目录场景下工具层不再需要一次性把整个内容拉进 isolate 内存。read工具支持图片与 data 格式commit19a65bc扩展了read工具使其支持图片与 data URI 格式。相关实现位于 packages/computer/src/tools/fs/read.ts结果类型包含kind: image | file | binary等分支图片/文件分支返回{ type: data, data }的 data URI 形态媒体类型识别由 packages/computer/src/tools/fs/media.ts 完成既按扩展名.png/.jpg/.jpeg/.gif/.webp也按**文件魔数magic bytes**判定SVG 则按内容前缀识别为text类型image/svgxml默认有内联发送给模型的最大图片/PDF 大小上限空文件会返回Cannot attach empty file错误见 packages/computer/src/tools/fs/read.test.ts。测试 packages/computer/src/tools/fs/media.test.ts 覆盖了 PNG/JPEG/GIF/WEBP 的魔数识别以及image.JPG这类大小写混合扩展名。find/grep过滤参数与delete工具commitf673226更新了find和grep支持额外过滤参数并新增了delete工具。以 packages/computer/src/tools/fs/find.ts 为例find的输入 schema 包括path绝对目录默认/workspacepattern相对于path的 glob如**/*.ts或src/?.jslimit/offset分页参数limit默认 200、上限 1000。执行时后端会多取一条记录limit 1来判断是否截断并在结果中给出nextOffset供继续翻页——这是把分页目录列表能力落到工具层后的典型用法。四、Worker JavaScript 后端能力超限错误内嵌字节上限变更内容0.2.1 的 PR #102commite09135bEmbed the configured byte limit directly in Worker JavaScript capability size errors当传给 Worker JavaScript 的能力capability例如注入的模块或参数超过配置上限时生成的错误信息会直接包含配置的字节上限而不是含糊的太大。源码依据packages/computer/src/backends/worker-javascript/worker-javascript.test.ts 的测试用例includes the configured capability byte limit in generated errors展示了完整链路new WorkerJavaScriptBackend({ loader: { load }, maxCapabilityBytes: 256, }); // ... const capabilities load.mock.calls[0]?.[0].modules[workspace-capabilities.js]; expect(capabilities).toContain(exceeds 256 bytes);测试先以maxCapabilityBytes: 256构造后端并执行一次runtime.exec然后断言生成的workspace-capabilities.js模块源码中包含 exceeds 256 bytes。也就是说能力超限错误现在是可诊断、可量化的——错误文本直接告诉你上限是多少方便判断是该调大配置还是精简注入内容。实战含义对在runtime.exec中注入大模块或大参数的 Agent 而言遇到超限错误时可以直接根据错误信息定位是配置问题还是输入问题无需再翻源码确认上限值。五、git 模块短 revision id 支持变更内容0.2.1 的 PR #95commit1e6c027为 git 模块增加了对短 revision id的支持即允许在 ref 位置使用完整 40 位 OID 的缩写形式如abc1234。实现机制从 packages/computer/src/git/reads.ts 看解析层把 revision spec 分为基础 ref 祖先遍历步骤完整 OID 是 40 位十六进制isAbbreviatedOid(ref)判断ref.length 40且全为[0-9a-f]据此识别缩写 OIDparseRevision用正则/^(.*?)((?:[\^~][0-9]*)*)$/把形如HEAD^、HEAD^2、HEAD~N、HEAD~2^2的gitrevisions(7)后缀与基础 ref 分离——~N展开为 N 个 first-parent 步骤^N选择第 N 个父提交1 基后缀可左到右串联。对应测试分散在 packages/computer/src/git/cli.test.ts覆盖diff/log/show/reset --hard等命令对 revision 后缀的预解析见其中pre-resolves revision suffixes in from/to refs、show pre-resolves a revision suffix to an oid、--hard resolves a revision suffix in the ref等用例。这意味着 Agent 的 git 工具现在可以写出git show abc1234或git diff HEAD~2^2这类接近真实 git CLI 习惯的命令由工具层在宿主侧解析成精确 OID 再执行。六、执行可靠性container-shell 重连与EEXEC_LOST变更内容0.2.1 的 PR #103commit8afbb7c解决了一个真实的生产痛点container-shell操作在computerd 重启后、当重试是安全的时候会重新连接而不是直接失败进程本地process-local执行在容器被替换后返回EEXEC_LOST错误。官方文档在 docs/05_runtime_interface.md 的 Command synchronization 一节对此有更详细说明。源码依据在 packages/computer/src/workspace.ts 的执行调度逻辑中EEXEC_LOST被作为一等错误码处理当intent.runtimeId ! undefined且错误码为EEXEC_LOST时调度器清除该运行时的调度器条目并返回{ status: lost, backend, runtimeId, error }——即明确标记执行丢失而不是把它当作普通重试或失败其他错误则走常规的重试路径超过retryMaxAttempts返回status: exhausted否则构造下一次尝试的 intentattempt 1、携带targetCursor重新入调度队列。EEXEC_LOST的定义在 packages/computer/src/workspace.ts 与 packages/computer/src/workspace.ts 两处WorkspaceExecutionLostError测试覆盖见 packages/computer/src/workspace.test.ts既有直接rejects.toMatchObject({ code: EEXEC_LOST })的用例也有旧执行对象的kill()在容器替换后同样返回EEXEC_LOST的用例。设计含义这套机制把底层容器被替换这一不可控事件在 API 层转化为语义明确的EEXEC_LOST让上层 Agent 应用能够区分执行失败与执行丢失可安全重试从而在 computerd 重启、容器漂移等场景下做出正确的重连与重试决策。七、同步拉取的峰值内存优化变更内容0.2.0 的 PR #87commit8758b51优化了同步 pull 过程中的峰值内存应用一个文件条目时直接链接link发送方已暂存的 chunks而不再把 chunks 读回来拼接成整个文件的 buffer。为什么重要改动前的做法是读取所有 chunks → 拼接为整个文件 buffer → 写入这会让 isolate 同时持有约两倍文件大小的内存chunk 数据 拼接缓冲。改动后应用路径只做 chunk 级链接。源码侧的依据在 packages/dofs/src/sync/apply.tslinkStagedChunksSync相关的注释明确写着 Link a file entry to staged chunks without loading payload bytes——声明的大小在不加载 payload 的前提下校验chunk 哈希沿袭stageBlob的信任契约随后调用linkStagedChunksSync完成链接。实战含义对工作区包含大文件如二进制资产、大日志的同步场景这一改动显著降低 Durable Object 内单个 isolate 的峰值内存占用降低 OOM 风险也让大文件同步在内存受限的 Workers 环境里更可预期。八、git 边界修复与 SQLite 批处理0.2.0 的 PR #77commit5062158是一次正确性 稳定性补丁修复 git 的diff/status/log各类边界情况edge cases在 Durable Object SQLite 的限制内批量处理同步哈希探测sync hash probes避免逐个探测触发 SQL 语句上限或性能问题RPC 目标的计数改为按**身份identity**统计避免同一目标被重复计数。这三项分别对应git 命令输出正确性、同步过程中的 SQLite 交互开销、以及运行时资源统计口径。对深度使用同步与 git 工具的 Agent 而言它们直接影响结果的可靠性与大规模工作区下的稳定性。总结与升级建议回顾 0.2.x 两个版本cloudflare/computer的演进主线非常清晰维度0.2.0 核心变更0.2.1 核心变更执行后端worker-shell 命令按需引入bundle 大幅瘦身能力超限错误内嵌字节上限网络egress 策略三后端统一none / direct / http-gatewaycontainer-shell 重连恢复 EEXEC_LOST文件系统有界读取、分页目录、图片/data 格式、delete工具—gitdiff/status/log 边界修复短 revision id 支持内存同步 pull 改为 chunk 链接峰值内存减半—对使用者而言建议的落地顺序是若使用 worker-shell尽快把curl、sqlite、python等命令改为按cloudflare/computer/shell/feature显式引入观察 bundle 体积与冷启动变化统一用WorkspaceEgressPolicy的三种模式管理 Agent 网络边界网关模式下务必配置稳定的revision以复用 isolate在容器后端出现 computerd 重启或容器替换时识别EEXEC_LOST并走安全重试/重连路径而不是盲目重放执行升级后利用read工具的图片与 data 格式支持让多模态 Agent 能直接消费工作区内的图片资产。进一步深入可阅读 docs/12_worker_backend.mdWorker 后端的完整设计与 fidelity gaps、docs/05_runtime_interface.md命令同步与运行时会话、examples/egress三后端 egress 对照示例与 packages/computer/CHANGELOG.md 原文。【免费下载链接】computerGive your agent a computer 项目地址: https://gitcode.com/GitHub_Trending/computer1/computer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考