Cloudflare Computer exec-wire协议解析命令执行流式事件的线格式设计完整指南【免费下载链接】computerGive your agent a computer 项目地址: https://gitcode.com/GitHub_Trending/computer1/computer本文解析 Cloudflare Computer 的 exec-wire 协议——它如何让 AI Agent 远程执行命令时stdout/stderr 输出像本地终端一样逐行流式呈现。exec-wire 是一个轻量的命令执行流式事件线格式wire format设计每个事件一帧 JSONL文本走 utf8、二进制走 base64解码端容忍任意分片边界。读完你会理解它在整个 Cloudflare Computer 架构中的位置以及为什么这种朴素的 JSONL 方案反而最稳。为什么需要 exec-wireWorkers RPC 的字节流限制 在 Cloudflare Computer 中宿主侧Durable Object拿到的执行句柄是一个ReadableStreamWorkspaceExecEvent——一个对象流。但 Workers RPC 在 isolate 之间天然携带的是字节流并且带流控它并不会为你传输任意对象流。这正是 exec-wire 要解决的问题把事件流在持久对象侧装帧成 JSONL 字节在 Worker 侧再解析回事件。一句话概括线上传字节两端各自还原成结构化事件。代价是每个 chunk 多一次序列化换来的是线两侧各有一份保真度一致的 Workspace 接口。exec-wire 线格式一条命令的生命周期 一次执行的输出流由三类事件帧组成每行一个 JSON 对象换行分隔事件帧示例概念示意说明stdout 文本{id,seq,name:stdout,enc:utf8,value:...}调用方指定encoding: utf8时的文本块stdout 二进制{id,seq,name:stdout,enc:b64,value:...}默认执行的原始字节base64 编码exit{id,seq,name:exit,value:0}进程退出码流的终结帧几个关键设计决策都写在 exec-wire.ts 的文件头注释里enc标签区分字符串与字节。解码端据此决定交回string还是Uint8Array二进制一律 base64。这样无论 chunk 内容是什么哪怕是0xff 0xfe这种非法 UTF-8 序列帧都保持合法 JSON文本按 JSON 字符串携带。JSON 本身会转义换行和引号所以内容里的换行不可能与换行帧分隔符混淆idseq双字段。id标识一次执行reattach 时靠它找回日志seq是递增序号支持按序号重放与续传。编码侧事件流 → JSONL 字节流编码只有两个函数逻辑极其直接encodeExecEvent把单个事件映射成帧JSON.stringify后追加换行输出Uint8ArrayencodeExecEvents用TransformStream把整条事件流逐个转帧串成字节流。映射规则在 frameOfexit事件 → 直接透传退出码value是字符串 →enc: utf8原样入帧value是Uint8Array→ base64 后入帧。其中 base64 编码toBase64特意分块调用String.fromCharCode每块 0x8000避免大缓冲区触发参数数量上限——这种细节正是给 Agent 一台计算机这类基础设施项目值得学习的地方。解码侧为什么分片边界落在哪都行是硬需求 解码端的 decodeExecEvents 是整个协议里最有含金量的部分。字节流从 RPC 过来chunk 的切分位置与帧边界完全无关——一个 JSON 行可能恰好被劈成两个 chunk。它的处理方式是经典的行缓冲维护一个字符串buffer每个 chunk 用TextDecoder({ stream: true })增量解码后追加循环indexOf(\n)只把完整行解析成帧并发出事件流结束时flush把剩余半行兜底发出正常情况下流末尾是空。配套的单测 exec-wire.test.ts 专门验证了这一点把编码后的字节逐字节拆开再喂给解码器结果依然与原事件流完全一致。此外还覆盖了多字节文本café — 日本語 、含 JSON 元字符的文本、非 UTF-8 二进制和空字节块等边界情况。注上图与架构图为同一文件此处仅示意位置实际引用见文章开头架构图。它在架构中的位置Worker 后端的事件流框架exec-wire 不是孤立存在的。官方文档 docs/12_worker_backend.md 专门有一节Event stream framing描述了同一思路在 worker 后端的应用ShellWorker.exec返回{ id, events: ReadableStreamUint8Array }字节流就是换行分隔 JSON、每行一个ExecEventWorkers RPC 天然携带字节流JSON 帧日志是跨越 isolate 边界摩擦最小的形态后端再把字符串载荷重新编码回Uint8Array让运行时统一从原始事件累积结果。而上层的 shell.ts 则展示了这条线如何嵌入完整的命令生命周期每次exec()用同步协议夹住 spawn——执行前 push 宿主侧写入、事件流耗尽后 post-drain pull 把命令产出的变更拉回来。exec-wire 负责的是其中事件流这一段的跨边界传输。对新手/开发者的 3 个可复用启示 能用 JSONL 就别自造二进制协议。JSONL 文本可读、可调试、tail -f友好朴素在这里是优势不是妥协用enc这类显式标签区分载荷形态比让解码端猜类型可靠得多尤其要同时兼容文本与二进制流式协议必须把分片当作一等公民。解码端不能假设 chunk 边界对齐消息边界行缓冲 流式解码器是最小可靠实现。延伸阅读协议实现exec-wire.ts约 140 行含完整注释值得通读单元测试exec-wire.test.ts往返测试 逐字节分片测试事件定义shell.ts 中的WorkspaceExecEvent类型运行时接口docs/05_runtime_interface.mdWorker 后端框架细节docs/12_worker_backend.md【免费下载链接】computerGive your agent a computer 项目地址: https://gitcode.com/GitHub_Trending/computer1/computer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
