用途
dev-desktop-sandbox 用于在开发过程中并行启动多个隔离的 xum 桌面(Electron)实例。make dev + make start(Electron)使用 XUM_ROOT 保存持久化状态(配置、会话、worktree 等)。在开发时让多个 Electron 实例共用同一个 xum root 会产生噪音和风险。该技能记录了仓库工作流:通过为每个实例分配独立的临时 XUM_ROOT,从而并行启动多个桌面开发实例(包括来自不同 git worktree 的实例)。
快速开始
make dev-desktop-sandbox
主要能力
- 创建一个全新的临时
XUM_ROOT目录。 - 如果存在以下文件,则将其复制进沙箱(除非被标志禁用):
providers.jsonc(provider 配置)config.json(项目列表)- 每个文件独立地从第一个拥有它的 root 播种(依次为
$XUM_ROOT、遗留的$MUX_ROOT、~/.xum[-dev]、遗留的~/.mux[-dev]/~/.cmux),因此只有config.json的 root 不会丢失 provider 配置。
- 在可能静默覆盖或与预期设置不匹配时,从子进程环境中剥离 provider 凭据环境变量:使用
--clean-providers时剥离全部(包括 Bedrock 的AWS_REGION和AWS_BEARER_TOKEN_BEDROCK;共享 AWS 凭据如AWS_PROFILE会保留);否则只剥离那些会遮蔽已播种providers.jsonc条目(该条目有apiKey但无显式baseUrl)的*_BASE_URL环境变量(API key 环境变量始终保留,以便环境 key 回退仍可用)。 - 挑选空闲端口:
- Vite 开发服务器端口(供渲染进程使用)
- Electron 远程调试端口(可选)
- 默认在沙箱内禁用教程(设置
XUM_ENABLE_TUTORIALS_IN_SANDBOX=1可重新启用)。 - 运行
make dev,并设置:XUM_ROOT=<temp>XUM_VITE_PORT=<free-port>
- 等待 Vite 可访问,然后运行
make build-static(Electron 需要dist/splash.html)。 - 启动 Electron(
bunx electron .),并设置:XUM_ROOT=<temp>XUM_DEVSERVER_HOST=127.0.0.1XUM_DEVSERVER_PORT=<vite-port>- 默认
XUM_SERVER_PORT=0(避免config.json固定apiServerPort时出现EADDRINUSE) XUM_ALLOW_MULTIPLE_INSTANCES=1以及遗留的CMUX_ALLOW_MULTIPLE_INSTANCES=1
使用方式
配合 bash.monitor 的 Agent 用法
在为 dogfooding 启动 Electron 沙箱时,优先使用受监控的后台 bash,这样 Xum 会在 Vite/Electron 就绪或启动失败时唤醒工作区,而无需手动轮询。
bash({
script: "make dev-desktop-sandbox",
display_name: "Desktop Sandbox",
run_in_background: true,
timeout_secs: 1800,
monitor: {
filter: "Vite|ready|localhost|Electron|ERROR|EADDRINUSE|failed|Failed",
cooldown_ms: 1000,
max_events: 5,
},
});
在就绪唤醒后,使用匹配日志中显示的沙箱输出/端口,通过 Electron 或 agent-browser 工作流进行连接。仅当唤醒行不足以提供上下文时才使用 task_await。
选项
# 以干净实例启动(不复制 providers 或项目)
make dev-desktop-sandbox DEV_DESKTOP_SANDBOX_ARGS="--clean-providers --clean-projects"
# 跳过复制 providers.jsonc
make dev-desktop-sandbox DEV_DESKTOP_SANDBOX_ARGS="--clean-providers"
# 从 config.json 中清除项目(保留其他配置)
make dev-desktop-sandbox DEV_DESKTOP_SANDBOX_ARGS="--clean-projects"
# 使用特定 root 进行播种(默认:逐文件从 $XUM_ROOT、遗留 $MUX_ROOT、~/.xum[-dev]、遗留 ~/.mux[-dev] / ~/.cmux)
SEED_XUM_ROOT=~/.xum-dev make dev-desktop-sandbox
# 退出后保留沙箱 root 目录(便于调试)
KEEP_SANDBOX=1 make dev-desktop-sandbox
# 固定 Vite 端口
VITE_PORT=5174 make dev-desktop-sandbox
# 控制等待 Vite 启动的时长(毫秒)
VITE_READY_TIMEOUT_MS=120000 make dev-desktop-sandbox
# 为沙箱 dogfooding 重新启用教程
XUM_ENABLE_TUTORIALS_IN_SANDBOX=1 make dev-desktop-sandbox
# 启用/固定 Electron 远程调试端口(默认自动挑选空闲端口)
ELECTRON_DEBUG_PORT=9223 make dev-desktop-sandbox
# 完全禁用 Electron 远程调试
ELECTRON_DEBUG_PORT=0 make dev-desktop-sandbox
# 覆盖内部 API 服务器端口(沙箱默认 0/随机)
XUM_SERVER_PORT=3772 make dev-desktop-sandbox
# 覆盖使用的 make 二进制
MAKE=gmake make dev-desktop-sandbox
可选:更深的 Electron 隔离(XUM_E2E=1)
即使有唯一的 XUM_ROOT,Electron 的 userData 目录(localStorage、窗口状态、单实例锁等)也不会自动重定位,除非设置 XUM_E2E=1。
如果需要完整隔离(包括 userData),运行:
XUM_E2E=1 make dev-desktop-sandbox
适用场景
- 在开发 xum 桌面(Electron)应用时,需要同时运行多个实例进行对比、调试或 dogfooding。
- 从不同 git worktree 并行启动桌面开发实例。
- 需要避免多个实例共用同一 xum root 导致的配置、会话或 worktree 冲突。
- 需要为每个实例提供独立端口和临时状态目录的隔离开发环境。
限制与安全说明
providers.jsonc可能包含 API key。- 沙箱 root 目录会创建在磁盘上(通常位于系统临时目录下)。
- 该流程有意不复制
secrets.json。 - 即使有唯一
XUM_ROOT,若不设置XUM_E2E=1,Electron 的userData目录不会自动重定位,因此无法实现包括userData在内的完整隔离。 - 关于收费、价格、平台支持范围等信息,资料中暂未提供。