关于 session-execution
session-execution 说明沙箱会话中可靠执行命令的架构与审查要点，面向开发相关功能的人员。内容涵盖前台和后台输出捕获、完成信号及并发检查。
主要功能
- 01前台与后台执行模式
- 02分别捕获 stdout 和 stderr
- 03原子写入退出码
- 04结合监听与轮询检测完成
- 05按会话串行执行命令
适用场景
- 01审查会话命令执行改动
- 02排查输出不完整或延迟
- 03检查清理逻辑与跨会话竞争
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/session-execution确认已加载。
详细介绍
会话执行
在处理此部分之前，请先阅读 docs/SESSION_EXECUTION.md。其中介绍了实现可靠命令执行并分离 stdout/stderr 的架构。
核心概念
两种执行模式：
- 前台（exec）：在主 shell 中运行，状态会保留。使用临时文件捕获输出。
- 后台（execStream/startProcess）：通过 FIFO 在子 shell 中运行。后台进程中的标记器会为输出添加前缀。
二进制前缀约定：
- Stdout：每行添加
\x01\x01\x01前缀 - Stderr：每行添加
\x02\x02\x02前缀 - 日志解析器根据这些前缀重建数据流
完成信号：
- 通过原子操作
tmp+mv将退出代码写入<id>.exit文件 - 通过结合使用 fs.watch 和轮询来检测完成（在 tmpfs/overlayfs 上也很可靠）
- 后台模式使用
labelers.done标记，确保输出已全部捕获
开发时
- 了解前台模式使用临时文件的原因（bash 会等待重定向完成）
- 了解后台模式使用 FIFO 的原因（可并发流式传输，且不会阻塞 shell）
- 测试无输出的命令（cd、变量赋值）——这些命令过去曾导致挂起
- 测试大量输出——缓冲问题可能导致日志不完整
审查时
正确性检查：
- 验证退出代码处理是原子的（先写入 .tmp，再执行 mv）
- 检查错误路径中的 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 接口
评论
支持 Markdown