OpenMausBot 本地环境(Local Environments)实测指南:在打包版桌面端创建、切换与故障回退

原创2026-10-30 11:37:261,336 阅读
文章标签:人工智能AI Agent多智能体交互助手桌面应用本地部署工具调用前端

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 错误。

验证前置条件

按配方要求准备以下环境:

  1. 该分支的打包版桌面安装,且已在本机(This computer)完成登录,至少有一个 bot,使 bot 列表可见地非空;
  2. 注册表位于应用的 user-data 目录:macOS 上是 ~/Library/Application Support/OpenMausBot/environments.json;
  3. 应用日志(logs 目录下的 server.log)会记录每一次切换决策——保持它处于打开状态。

步骤一:创建环境

  1. 打开 Settings → Servers。在 "Environments on this computer" 卡片下输入名称 APRS Chat,数据目录留空,选择 Create。
  2. 预期结果:出现一行 APRS Chat,路径为 ~/.openmausbot-aprs-chat,带 Switch 按钮和一个删除(Forget,垃圾桶图标)入口。不会发生重启,"This computer" 仍显示 Current。此时新目录还没有任何文件写入——创建只注册条目,目录在首次切换时才创建并自举。
  3. 预期 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" }。

步骤二:切换到该环境

  1. 点击 Switch,然后确认对话框 "Switch to APRS Chat? The app restarts on that environment."
  2. 预期:旧服务器子进程停止、目标环境启动期间窗口变为空白/不可用,然后重载到新环境——对已存在的目录大约 15 秒。启动探测每个端口尝试最多允许 60 秒(端口依次为 8799、18799、28799,两轮),因此冷盘上的首次启动可能更久。
  3. 预期到达后:bot 列表为空(全新环境),侧边栏药丸显示 APRS Chat,Settings → Servers 中 "APRS Chat" 被标记为 Current。
  4. 预期终端可见:~/.openmausbot-aprs-chat/environment-id 存在且是一个不同于 ~/.openmausbot/environment-id 的 UUID——两个环境是两个不同的服务器,所有状态文件都在各自目录下。此时 environments.json 的 activeId 已更新为该条目的 id。
  5. 在这里创建一个一次性 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 且当前运行目录不是默认目录时触发),因此与正向切换享受完全相同的编排与回滚保证。

步骤四:未挂载卷中止(保持原地)

模拟一个位于已消失磁盘上的环境,无需真实磁盘:

  1. 完全退出应用。

  2. 编辑 environments.json:把一个非激活条目的 dataDir 指向一个父路径不存在的路径,例如 /Volumes/NO-VOLUME/openmausbot-env。

  3. 在 This computer 上启动应用。预期:该行显示 missing 徽标(该标记在读取时被打上,因此路径重新出现后它会清除)。

  4. 点击 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 targetDirfailed({targetDir} failed ({result.error})`)输出,随后switchLocalEnvironmentTo` 弹出 "Could not switch environments" 对话框。

步骤五:启动回退(不健康的环境)

让激活的环境无法启动:

  1. 退出应用。创建一个不可写父目录,例如 sudo mkdir /opt/omb-locked && sudo chmod 500 /opt/omb-locked,把激活条目的 dataDir 设为 /opt/omb-locked/env,并把 activeId 设为该条目的 id。
  2. 启动应用。预期启动在整个端口调度上失败(无法创建数据目录的子进程会很快退出;卡住的子进程则每次尝试烧满完整的探测超时),然后:
    • 安装落在 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 也只在健康探测通过后才被写入,这是"失败的切换不会把你留在半路"这一安全属性的核心机制。

登录后查看全文
OpenMausBot