用途:该技能用于开发或审查 Cloudflare Sandbox SDK 的会话执行(session execution)相关代码,涉及命令处理、shell 状态、基于 FIFO 的流式输出以及 stdout/stderr 分离。开始前应先阅读 docs/SESSION_EXECUTION.md,其中说明了可靠命令执行与输出流分离的架构。
主要能力与概念:
- 两种执行模式。前台模式(exec)在主 shell 中运行,状态会持久化,使用临时文件捕获输出;后台模式(execStream/startProcess)通过 FIFO 在子 shell 中运行,由 labeler 为输出添加前缀。
- 二进制前缀约定。stdout 每行以 \x01\x01\x01 为前缀,stderr 每行以 \x02\x02\x02 为前缀,日志解析器据此重建两条流。
- 完成信号。退出码通过原子写入(先写 <id>.exit.tmp 再 mv 到 <id>.exit)落盘;使用 fs.watch 加轮询的混合方式检测完成,以兼容 tmpfs/overlayfs;后台模式使用 labelers.done 标记确保输出被完整捕获。
开发要点:理解前台为何用临时文件(bash 会等待重定向完成)、后台为何用 FIFO(并发流式输出且不阻塞 shell);测试静默命令(如 cd、变量赋值,历史上会导致挂起)和大输出(缓冲问题可能造成日志不完整)。
审查要点:验证退出码处理是否原子;检查错误路径中的 FIFO 清理;后台模式读取最终输出前确保已等待 labelers.done。并发方面,会话执行有互斥锁按会话串行化命令,判断竞态前需确认操作是否在同一会话内(受互斥锁保护)以及是会话内还是会话间(跨会话竞态才是真实问题),完整并发模型见 docs/CONCURRENCY.md。常见误报包括“会话状态并发读写”和“FIFO 操作可能竞态”;真正需关注的是缺少隔离的跨会话操作、可能影响仍在运行命令的清理操作,以及互斥锁保护范围之外的文件操作。
关键文件:packages/sandbox-container/src/session.ts(含 exec/execStream 的 Session 类)、packages/sandbox-container/src/managers/SessionManager.ts(互斥锁与生命周期)、packages/sandbox/src/clients/CommandClient.ts(会话命令的 SDK 接口)。
限制:资料未提供安装命令、收费、平台支持范围或具体使用步骤,这些内容暂未提供。