OpenMausBot 本地环境(Local Environments)实测指南:在打包版桌面端创建、切换与故障回退
OpenMausBot 本地环境(Local Environments)实测指南:在打包版桌面端创建、切换与故障回退
本文围绕 OpenMausBot 仓库中的手动验证配方 docs/verification/local-environments.md 展开,完整继承其中的每一步验证操作(创建环境、切换、切回、未挂载卷中止、启动回退),并结合 electron/environment-switch.mjs、electron/environments.cjs 与 electron/main.mjs 的源码实现,说明每一步操作背后"为什么应该出现这个结果",帮助你在安装版构建上完成验证并理解其底层编排逻辑。
功能定位:为什么必须手动验证
本地环境(local environments)允许同一个桌面安装通过命名环境在多个数据目录之间切换:每个环境是一组独立的 bots、providers、API keys、MCP servers、groups、routines 与消息历史,一次只有一个处于激活状态。完整的设计见 docs/superpowers/specs/2026-10-07-local-environments-design.md,实施计划见 docs/plans/local-environments.md。
这个功能是打包版桌面端专属行为,控制面(control surface)无法驱动它:
- 未打包的 dev 运行中,创建与切换都会返回
dev错误,"Environments on this computer" 卡片因为 bridge 报告packaged: false而保持隐藏; - 因此验证只能在安装版构建上按配方手动执行。
源码印证了这一点:electron/main.mjs 中 createLocalEnvironment 开头即有 if (!app.isPackaged) return { ok: false, error: "dev", state: environmentsState },切换入口 switchLocalEnvironmentTo 同样以 if (!app.isPackaged) return { ok: false, error: "dev" } 拦截;渲染端 src/components/ConnectedWorkspacesSettings.tsx 只有在 saved?.packaged 为真时才渲染该卡片({saved?.packaged && <Card title={t("connectedWorkspaces.localTitle")} ...)。
测试底线(Floor):先跑单元测试
手动验证之前,配方要求先跑两条 unit test 文件作为"地板":
node --test electron/environments.node-test.mjs electron/environment-switch.node-test.mjs
pnpm test:electron(即 package.json 中的 node --test "electron/*.node-test.mjs")会连同整个 Electron 测试套件一起执行它们。这些测试覆盖:
- 注册表(registry)解析与 v1→v2 迁移;
- 创建时的守卫规则(绝对路径、不允许重复、不允许嵌套、不允许指向默认目录);
- 编排器(orchestrator)的 stop → lease → start → probe → persist 顺序;
- 每条失败路径上的回滚(rollback)。
但单元测试不能证明用户工作流——那正是这份手动配方的职责。从 electron/environment-switch.node-test.mjs 可以确认测试确实锁定了调用顺序:happy path 断言 calls 恰好为 ["stop", "release", "acquire", "start", "probe", "persist"],且 persistActive 永远是最后一步;父目录缺失时断言 { ok: false, error: "unavailable", rolledBack: true } 且从未调用 persist;lease 被其他进程持有时 DataDirLeaseError 转化为 locked 错误。
验证前置条件
按配方要求准备以下环境:
- 该分支的打包版桌面安装,且已在本机(This computer)完成登录,至少有一个 bot,使 bot 列表可见地非空;
- 注册表位于应用的 user-data 目录:macOS 上是
~/Library/Application Support/OpenMausBot/environments.json; - 应用日志(logs 目录下的
server.log)会记录每一次切换决策——保持它处于打开状态。
步骤一:创建环境
- 打开 Settings → Servers。在 "Environments on this computer" 卡片下输入名称
APRS Chat,数据目录留空,选择 Create。 - 预期结果:出现一行
APRS Chat,路径为~/.openmausbot-aprs-chat,带 Switch 按钮和一个删除(Forget,垃圾桶图标)入口。不会发生重启,"This computer" 仍显示 Current。此时新目录还没有任何文件写入——创建只注册条目,目录在首次切换时才创建并自举。 - 预期
environments.json中新增的条目包含"kind": "local"、一个生成的id,且activeId仍为"local"。
源码层对应关系:IPC 处理器 environments:create 调用 electron/main.mjs 中的 createLocalEnvironment(name, dataDir)。当数据目录留空时,它把名称 slug 化后拼出默认路径:
const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
candidateDir = path.join(os.homedir(), `.openmausbot-${slug || randomUUID().slice(0, 8)}`);
这解释了为什么 APRS Chat 会落到 ~/.openmausbot-aprs-chat。该 slug 兄弟目录模式是设计文档中有意选择的,与 companion app 使用的 ~/.openmausbot-companion 保持一致。随后 withLocalEnvironment(electron/environments.cjs)执行守卫检查:名称必须非空且不超过 60 字符(MAX_NAME);路径必须通过 cleanDataDir 的绝对路径模式(POSIX 开头 /、Windows 盘符或 UNC \\);同一路径不允许重复注册(duplicate);新目录不得落在任何已注册环境目录之内,也不得把已注册目录包含进来(nested),且不得是默认目录。任何一条失败都会返回 { ok: false, error: "name" | "path" | "duplicate" | "nested" }。
步骤二:切换到该环境
- 点击 Switch,然后确认对话框 "Switch to APRS Chat? The app restarts on that environment."
- 预期:旧服务器子进程停止、目标环境启动期间窗口变为空白/不可用,然后重载到新环境——对已存在的目录大约 15 秒。启动探测每个端口尝试最多允许 60 秒(端口依次为 8799、18799、28799,两轮),因此冷盘上的首次启动可能更久。
- 预期到达后:bot 列表为空(全新环境),侧边栏药丸显示
APRS Chat,Settings → Servers 中 "APRS Chat" 被标记为 Current。 - 预期终端可见:
~/.openmausbot-aprs-chat/environment-id存在且是一个不同于~/.openmausbot/environment-id的 UUID——两个环境是两个不同的服务器,所有状态文件都在各自目录下。此时environments.json的activeId已更新为该条目的 id。 - 在这里创建一个一次性 bot,然后确认
~/.openmausbot/没有留下它的任何痕迹。
这些预期都能在源码中找到依据:
- 端口与超时:electron/desktop-ports.mjs 定义
DESKTOP_PORTS = Object.freeze(<a href="https://link.gitcode.com/i/d1869a9a59184ca56dccae2fee9b900c" target="_blank">8799, 18799, 28799]);[electron/server-boot-probe.mjs 中SERVER_BOOT_TIMEOUT_MS = 60_000,即每个端口尝试的上限 60 秒。 - 切换编排:核心模块 electron/environment-switch.mjs 是一个纯函数、依赖注入的编排器,执行
stopChild → releaseLease → validateTargetDir →(需要时 createDir)→ acquireLease → startChild → probeReady → persistActive。关键设计是persistActive只写注册表、且是最后一步——"健康探测通过后才持久化activeId,所以切换中途崩溃会启动上一个环境"。每条失败路径都统一走fail():调用rollback(port)(模块自身绝不在失败路径上调用startChild,保证失败切换不会双重启动),并返回{ ok: false, error, rolledBack }。 - 回滚的真实动作:在 electron/main.mjs 的接线中,
rollback依赖会停掉目标子进程、释放目标 lease、重新获取原目录的 lease 并用startServerOn(SERVER_PORT, previousDir)把旧环境拉起来,再交给serverSupervisor.ready。 - 环境隔离:服务器侧的
DATA_DIR在启动时从OMB_DATA_DIR环境变量解析(server/config.ts 中export const DATA_DIR = process.env.OMB_DATA_DIR ?? join(homedir(), ".openmausbot")),每个数据目录下的environment-id由 server/environment.ts 生成并保证 0600 权限(见 server/environment.test.ts 的断言)。切换时startServerOn会为每次调用重建启动环境并注入对应的OMB_DATA_DIR,因此两个环境天然是两台独立"服务器"。
步骤三:切回
在同一页面(或 Server 菜单)切换到 This computer。预期看到同样的重载过程,原有的 bot 列表恢复,而新环境仍然列在列表中、其内部创建的 bot 完好无损。
从源码看,切回走的是同一条 switchLocalEnvironmentTo(desktopDataDir(), LOCAL_ID) 路径(switchEnvironment 中判断目标 id 为 local 且当前运行目录不是默认目录时触发),因此与正向切换享受完全相同的编排与回滚保证。
步骤四:未挂载卷中止(保持原地)
模拟一个位于已消失磁盘上的环境,无需真实磁盘:
-
完全退出应用。
-
编辑
environments.json:把一个非激活条目的dataDir指向一个父路径不存在的路径,例如/Volumes/NO-VOLUME/openmausbot-env。 -
在 This computer 上启动应用。预期:该行显示 missing 徽标(该标记在读取时被打上,因此路径重新出现后它会清除)。
-
点击 Switch 并确认。预期:切换中止造成短暂不可用,弹出对话框 "Could not switch environments"("…The app log has the details."),安装状态与操作前完全一致——This computer 在运行、
activeId未变、旧服务器被回滚重启。日志中可见switch to /Volumes/NO-VOLUME/openmausbot-env aborted: target unavailable随后是
environment switch to … failed (unavailable)——探测拒绝穿过缺失的父目录去创建目录,且该条目保留 missing 徽标。
源码印证:
- "missing 标记在读取时打上"对应 electron/environments-file.mjs:每次读取注册表时,
local条目会被重写为{ ...entry, missing: !fs.existsSync(entry.dataDir) },所以它是无状态的、随读取刷新,路径恢复后自动清除。 - "拒绝穿过缺失父目录创建目录"对应 electron/environment-switch.mjs 的
validateTargetDir:
export function validateTargetDir(dataDir, fsImpl = fs) {
if (!fsImpl.existsSync(dirname(dataDir))) return { ok: false, error: "unavailable" };
return { ok: true, needsCreate: !fsImpl.existsSync(dataDir) };
}
只有父目录存在而目录本身缺失时才会走 createDir 自举路径;父目录不存在直接 unavailable 中止,日志行 switch to … aborted: target unavailable 正是 switchLocalEnvironment 中该分支写入的字符串。失败后 fail("unavailable") 触发回滚,对应日志 environment switch to … failed (unavailable) 由 electron/main.mjs 中 slog(\environment switch to {result.error})`)输出,随后switchLocalEnvironmentTo` 弹出 "Could not switch environments" 对话框。
步骤五:启动回退(不健康的环境)
让激活的环境无法启动:
- 退出应用。创建一个不可写父目录,例如
sudo mkdir /opt/omb-locked && sudo chmod 500 /opt/omb-locked,把激活条目的dataDir设为/opt/omb-locked/env,并把activeId设为该条目的 id。 - 启动应用。预期启动在整个端口调度上失败(无法创建数据目录的子进程会很快退出;卡住的子进程则每次尝试烧满完整的探测超时),然后:
- 安装落在 This computer 上,使用正常数据目录;
- 弹出标题为 "The environment was unhealthy" 的对话框,说明 OpenMausBot "came up on this computer's default data folder instead",并提示在环境可用后重新选择它;
environments.json中activeId被重置为"local",而该条目原样保留供调试。
electron/main.mjs 中的启动逻辑与之一一对应:启动时先读取注册表并调用 bootEnvironmentDir 决定数据目录;若打包版启动失败且 bootDataDir !== desktopDataDir(),则释放原 lease、重新获取默认目录的 lease、再次尝试启动,成功后弹出 "The environment was unhealthy" 错误框。另一条更早的分支处理"激活环境目录整体缺失"(条目带 missing 标记):bootEnvironmentDir 直接返回默认目录并置 fellBack: true,把 activeId 持久化为 local 并弹出 "The environment's folder is missing" 对话框。两条分支的共同点是:条目保留、activeId 回落到 "local"、默认环境恢复运行——"回退一次并明确告知"正是设计文档中的错误处理约定。
Dev 模式说明
在 pnpm dev:desktop(node scripts/prepare-cloudflared.mjs --current && electron .,见 package.json)下该功能刻意关闭:
- "Environments on this computer" 卡片不渲染(bridge 的
packaged为false); environments:create与本地environments:switch返回{ ok: false, error: "dev" };- 远程服务器条目在 dev 模式下仍正常工作——被 packaged 门控的只有本地数据目录切换。
验证边界:本配方不证明什么
配方末尾明确划定了验证范围,引用时应注意这些边界:
- 跨进程 lease 竞争(两个应用进程、同一个环境)由 electron/data-dir-lease.node-test.mjs 覆盖,不属于本配方。lease 机制本身在 electron/data-dir-lease.mjs 中实现:以
openmausbot-server.lease文件为锁记录,linkSync原子抢占,并用 boot id、pid namespace、进程启动时钟等多重证据判断持有者是否存活;被持有的 lease 意味着"环境在别处运行",切换会以locked中止。 - 本配方不覆盖 Forget 的 delete-files 选择、Windows/Linux 路径行为,也不覆盖打包构建矩阵。
延伸阅读:相关文件索引
| 组件 | 文件 |
|---|---|
| 手动验证配方(本文主体) | docs/verification/local-environments.md |
| 实施计划 | docs/plans/local-environments.md |
| 完整设计 | docs/superpowers/specs/2026-10-07-local-environments-design.md |
| 注册表:版本化条目、v1→v2 迁移、名称/路径守卫 | electron/environments.cjs |
| 注册表读写(missing 标记在读取时刷新) | electron/environments-file.mjs |
| 切换编排(纯函数、依赖注入) | electron/environment-switch.mjs |
| IPC 接线、单次切换互斥、supervisor 暂停、回滚重启、启动回退 | electron/main.mjs |
| 数据目录 lease | electron/data-dir-lease.mjs |
| 启动健康探测(60s/端口) | electron/server-boot-probe.mjs |
| 端口表(8799/18799/28799) | electron/desktop-ports.mjs |
| "Environments on this computer" 卡片(创建表单、Switch、Forget) | src/components/ConnectedWorkspacesSettings.tsx |
服务器端 OMB_DATA_DIR 解析 |
server/config.ts |
每目录 environment-id 生成 |
server/environment.ts |
| 单元测试 | electron/environments.node-test.mjs、electron/environment-switch.node-test.mjs、electron/data-dir-lease.node-test.mjs |
最后再强调适用前提:所有手动步骤都以"打包版安装 + 本机登录 + 至少一个 bot"为前提;dev 模式下该功能整体门控,environments.json 的 activeId 也只在健康探测通过后才被写入,这是"失败的切换不会把你留在半路"这一安全属性的核心机制。