SuperAPI AI 工具集

dev-desktop-sandbox

编程与开发

查看项目

更新于 10-16 22:15

技能介绍

用途

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.1
    • XUM_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 在内的完整隔离。
  • 关于收费、价格、平台支持范围等信息,资料中暂未提供。