# OpenMausBot 源码架构拆解 > 范围:当前工作区 OpenMausBot 源码快照;分析日期 2026-11-14。 > 方法:先读 AGENTS.md,再沿入口、导入、路由、驱动契约和持久化实现交叉阅读。没有安装依赖、启动服务、执行测试或修改两个仓库。 > “已实现”在本文中指有可追踪的实现代码与接线,不等于本机或所有平台已经运行验证。外部服务是否在线、账号是否有权限,本次均未验证。 ## 1. 一句话看懂 OpenMausBot 是一个“让一队 AI 在聊天界面里干活”的本地优先应用。 它不是只包了一层大模型 API:机器人档案、会话、协作交接、审批、电脑控制、浏览器、工具接入和持久化,都是宿主应用自己的工作。 大模型或编码助手只是可替换的执行引擎;Electron 是桌面入口,Node 服务是实际组织工作的中枢。 根包自述为 local-first chat app,版本为 0.1.158,许可证声明 Apache-2.0;桌面入口指向 Electron。 证据:[package.json:1](../OpenMausBot/package.json#L1)、[package.json:15](../OpenMausBot/package.json#L15)。 ## 2. 阅读约束与可信度 仓库要求:声称服务或会话改动有效之前,要按验证说明启动隔离 fixture,不能拿用户真实数据验证修改。 本次是只读架构分析,没有修改服务,也没有声称测试通过,所以没有启动这些 fixture。 证据:[AGENTS.md:3](../OpenMausBot/AGENTS.md#L3)。 证据分三层: - **实现明确**:入口确实导入模块,路由确实调用 handler,契约或存储确实有代码。 - **实现但有外部条件**:例如模型 CLI、Cua、Docker/Podman、Boat、云端控制面需要另行准备。 - **文档/规划**:设计文档只说明作者当时打算怎么做,不直接证明现在做到了什么。 下文没有把预览页面、功能开关、依赖包名或目录存在当作完整可用的证明。 ## 3. 总体分层 从使用者视角看,链路是: src/main.tsx → React 页面/状态层 → HTTP API / SSE ↓ server/index.ts ↓ 协调器 / 运行时 / ProviderDriver ↓ 模型 API 或外部 CLI、MCP 工具、电脑 ↓ SQLite / JSON / JSONL / 文件 这里第一行的入口是 [src/main.tsx](../OpenMausBot/src/main.tsx#L1)。 后端不是 Express/Nest/Fastify:核心直接导入 Node 的 createServer、IncomingMessage、ServerResponse。 证据:[server/index.ts:11](../OpenMausBot/server/index.ts#L11)。 主要目录的分工: - [src/App.tsx](../OpenMausBot/src/App.tsx#L1):大应用界面组合。 - [src/state/store.tsx](../OpenMausBot/src/state/store.tsx#L1):客户端状态与动作落到后端的桥梁。 - [server/index.ts](../OpenMausBot/server/index.ts#L1):服务装配、会话和运行生命周期、仍有大量内联路由。 - [server/contracts.ts](../OpenMausBot/server/contracts.ts#L1):模型驱动和运行宿主之间的接口。 - [shared/runtime-events.ts](../OpenMausBot/shared/runtime-events.ts#L1):前后端/驱动共同理解的运行事件。 - [electron/main.mjs](../OpenMausBot/electron/main.mjs#L1):桌面窗口与本地能力装配。 - [companion/src/index.ts](../OpenMausBot/companion/src/index.ts#L1):配套设备服务入口。 - [connector/src/agent.ts](../OpenMausBot/connector/src/agent.ts#L1):托管主机到云管理端的连接代理。 - [relay/src/main.ts](../OpenMausBot/relay/src/main.ts#L1):独立网络中继入口。 ## 3.1 功能模块速查 | 模块 | 用户看见的功能 | 后端负责的事情与源码入口 | |---|---|---| | Bot 与会话 | 建机器人、单聊、历史 | 身份、配置和会话归属:[Store](../OpenMausBot/server/store.ts#L275) | | 群聊与协作 | 群成员、任务交接、团队活动 | 多 Bot 调用和协调:[coordinator](../OpenMausBot/server/coordinator.ts#L1) | | 模型引擎 | 选择模型或本地编码助手 | 统一不同引擎的输入、事件和能力:[drivers](../OpenMausBot/server/drivers/builtIn.ts#L32) | | 记忆 | 查看、维护 Bot 记忆和个人信息 | 记忆文档、变更日志、回退和整理:[记忆路由](../OpenMausBot/server/routes/bot-memory.ts#L5) | | 自动化 | 定时工作、触发器、等待与继续 | 计划计算、运行记录、失败恢复及暂停:[routines](../OpenMausBot/server/routines.ts#L9) | | 工具与审批 | 工具执行过程、确认卡片 | MCP 桥接、权限范围、控制代理:[mcp-bridge](../OpenMausBot/server/mcp-bridge.ts#L1) | | 浏览器 | 实时网页画面与操作 | 浏览器控制、授权观看连接:[browser-viewers](../OpenMausBot/server/routes/browser-viewers.ts#L1) | | 电脑 | 本机、Local VM、云电脑面板 | 三种不同执行环境,详见第9节 | | 文件与数据 | 附件、文件视图、表格图表 | 附件归属和数据查询:[数据路由](../OpenMausBot/server/data/routes.ts#L21) | | 邮件与应用 | 连接邮箱及外部应用 | 邮箱发现、连接校验、发送配置与账户存储:[邮件服务](../OpenMausBot/server/email/service.ts#L1) | | 页面与技能 | 发布页面、技能和例程 | 独立服务模块:[页面服务](../OpenMausBot/server/pages/service.ts#L1)、[skills](../OpenMausBot/server/skills.ts#L1) | | 运行记录 | 用量与执行状态 | 运行数据库、用量日志:[runtime store](../OpenMausBot/server/runtime/store.ts#L1)、[usage ledger](../OpenMausBot/server/usage-ledger.ts#L1) | | 手机与云端配套 | 配对、远程连接、托管主机 | companion、relay、connector、control-plane,详见第13节 | 记忆不等于聊天记录:记忆路由导入独立 memory store、journal、upkeep,能分别管理记忆内容、修改记录和整理状态。团队环境还定义个人记忆层及写权限回调,见 [记忆依赖契约](../OpenMausBot/server/routes/bot-memory.ts#L26)。不能因为存在记忆维护接口,就宣称模型记住的内容一定正确。 ## 4. 前端:框架、入口和运行方式 前端是 React 19 + TypeScript + Vite 7。桌面开发依赖 Electron 43。 版本证据:[package.json:132](../OpenMausBot/package.json#L132)、[package.json:166](../OpenMausBot/package.json#L166)、[package.json:175](../OpenMausBot/package.json#L175)。 启动入口先设置主题、字体、聊天宽度、软件渲染与语言,避免首屏先闪出错误样式。 随后才决定当前应该显示主页、配对页、登录页还是完整应用。 证据:[src/main.tsx:22](../OpenMausBot/src/main.tsx#L22)、[src/main.tsx:40](../OpenMausBot/src/main.tsx#L40)。 这里不是简单地无条件渲染 App:/home、/pair、/desktop-viewer 不预先加载大应用块。 其他页面会并行开始加载 App 与读取会话,降低登录后的等待。 证据:[src/main.tsx:30](../OpenMausBot/src/main.tsx#L30)。 界面是否能用,还要经过会话判断:未认证展示配对,团队退出展示离开页,桌面本地主页可接 Electron bridge。 window.ogb 是桌面壳向页面暴露能力的入口,浏览器环境不应假定它存在。 证据:[src/main.tsx:41](../OpenMausBot/src/main.tsx#L41)、[src/main.tsx:52](../OpenMausBot/src/main.tsx#L52)。 Vite 的开发监听明确绑定 IPv4 127.0.0.1,默认 UI 端口 5199,可用 OMB_UI_PORT 改。 这是开发服务器,不应和正式 Node 后端混成一台服务。 证据:[vite.config.ts:79](../OpenMausBot/vite.config.ts#L79)。 客户端状态层负责把群组、机器人任务、项目等用户动作转换成 API 请求,并再分发服务端返回状态。 例如删除群组、更新任务、创建机器人项目分别有真实请求调用。 证据:[src/state/store.tsx:2668](../OpenMausBot/src/state/store.tsx#L2668)、[src/state/store.tsx:2708](../OpenMausBot/src/state/store.tsx#L2708)、[src/state/store.tsx:2723](../OpenMausBot/src/state/store.tsx#L2723)。 ## 5. 后端:入口、框架和 API 根脚本把 omb 指向 Node 直接执行的命令入口,dev:server 指向开发引导文件。 开发引导只设开发场景的本地浏览器信任变量,然后动态导入真正的服务入口。 证据:[package.json:33](../OpenMausBot/package.json#L33)、[server/dev-server.ts:1](../OpenMausBot/server/dev-server.ts#L1)。 主服务体积很大:本次读取快照的入口约 15,448 行。 它已经抽出 routes、host、runtime、drivers 等模块,但还不能称为完全解耦的插件内核。 一些路由已走统一分发,其他功能仍在主服务中组合或内联处理。 证据:[server/index.ts:12694](../OpenMausBot/server/index.ts#L12694)。 ### HTTP、SSE、WebSocket 分别干什么 HTTP 是“请求一件事并取得结果”:登录、配对、配置变更、查询、提交操作、附件等。 SSE 是“服务器不断告诉页面发生了什么”:聊天与运行状态变化,不需要浏览器不断轮询整段会话。 WebSocket 是适合双向实时或二进制通道的另一层,浏览器画面等实时连接由相应路由拥有;它不是所有聊天 API 的统一底座。 SSE 路径明确为 GET /api/events,响应 content-type 为 text/event-stream,并有心跳、会话存活判断、可见性过滤和背压状态。 证据:[server/index.ts:14627](../OpenMausBot/server/index.ts#L14627)。 WebSocket upgrade 不绕过 HTTP 安全门:它转入同一个请求处理器,通过认证、托管工作区和维护门后才由所属路由完成握手。 握手有 10 秒限制,提前到来的数据有 64 KiB 上限。 证据:[server/routes/upgrades.ts:1](../OpenMausBot/server/routes/upgrades.ts#L1)、[server/routes/upgrades.ts:35](../OpenMausBot/server/routes/upgrades.ts#L35)。 ### 已核验的 API 入口例子 - POST /api/auth/pair:浏览器配对入口。[server/index.ts:12577](../OpenMausBot/server/index.ts#L12577) - POST /api/pair:companion 配对,同一次性凭据窗口、锁定与交换机制。[server/index.ts:12611](../OpenMausBot/server/index.ts#L12611) - GET /api/auth/session:读取会话。[server/index.ts:12697](../OpenMausBot/server/index.ts#L12697) - GET /api/health:健康检查的一条入口。[server/index.ts:12659](../OpenMausBot/server/index.ts#L12659) - GET /api/events:状态事件流。[server/index.ts:14627](../OpenMausBot/server/index.ts#L14627) - GET /api/internal/agents、GET /api/internal/assignment-status、POST /api/internal/coordinate-bots:内部协作白名单。[server/index.ts:1652](../OpenMausBot/server/index.ts#L1652) - POST /api/internal/computer/mcp:云电脑工具接口,受 turn 级能力凭据保护。[server/cloud-computer-tools.ts:1](../OpenMausBot/server/cloud-computer-tools.ts#L1) - /api/bots/:botId/data:机器人数据模块路由族,并验证图表类型、字段和分页等参数。[server/data/routes.ts:21](../OpenMausBot/server/data/routes.ts#L21) 这是一份代表性接口地图,不是把 15,000 行入口及全部路由穷尽导出的 OpenAPI 文档。 internal 不代表不鉴权,也不代表可给外部集成任意调用。 ## 6. 模型引擎:真正的可替换边界 ProviderDriver 是“某种引擎怎样接进来”的公共契约,驱动把自己的模型/会话行为翻译成宿主统一理解的形式。 会话能力声明包含队列、审批等差异,因此相同界面不代表每种引擎功能完全相同。 证据:[server/contracts.ts:247](../OpenMausBot/server/contracts.ts#L247)、[server/contracts.ts:593](../OpenMausBot/server/contracts.ts#L593)。 当前 built-in 注册数组共有 29 项,按实际符号列出如下: GrokDriver、GrokAgentDriver、GeminiAgentDriver、KimiAgentDriver、DroidAgentDriver、CursorAgentDriver、OpenCodeDriver、QwenAgentDriver、HermesAgentDriver、ClineAgentDriver、CopilotAgentDriver、CommandCodeAgentDriver、KiroAgentDriver、OmpAgentDriver、CustomAcpDriver、PiDriver、OpenAICompatDriver、ClaudeDriver、CodexDriver、AntigravityDriver、MinimaxDriver、MistralDriver、CerebrasDriver、GroqDriver、GreenferenceDriver、ModelgoDriver、MetaDriver、MuseCodeDriver、DeepSeekAgentDriver。 唯一支持列表依据是实际导入和注册,不是 README 的营销名单。 证据:[server/drivers/builtIn.ts:1](../OpenMausBot/server/drivers/builtIn.ts#L1)、[server/drivers/builtIn.ts:32](../OpenMausBot/server/drivers/builtIn.ts#L32)。 其中大量 AgentDriver 从 acp 子目录接入;OpenAICompat、Claude、Codex 等有独立实现。 这意味着兼容层既有“直接接 API”的路线,也有“驾驭外部代理/CLI”的路线,不能一概当成 OpenAI Chat Completions。 所需 CLI、账号、订阅、API key、模型可用地区由各驱动决定。 驱动错误模型明确区分 missing_cli、invalid_credentials、inactive_subscription、insufficient_funds、quota_or_region_restriction、upstream_outage 等。 源码自己就承认这些是会阻断运行的外部条件。 证据:[server/contracts.ts:19](../OpenMausBot/server/contracts.ts#L19)。 ## 7. 机器人、会话、多机器人协作 机器人不是一个独立微服务;它更像宿主里的长期档案和配置,关联多条会话与执行状态。 聊天记录、运行会话和机器人档案要分开理解:删一个 UI 卡片,不等于所有底层引擎文件都消失。 协调器负责交接、派工、查询进度,把多个 bot 的工作组织成可恢复的过程。 主入口引入 createCoordinator、ComposedTurn、CoordinateBotsCall、HandoffOptions、HostTurnResult 等显式契约。 证据:[server/index.ts:27](../OpenMausBot/server/index.ts#L27)、[server/coordinator.ts:1](../OpenMausBot/server/coordinator.ts#L1)。 运行协调层另有 RuntimeStore 与 Runtime,保存停止记录、交接与工作状态。 因此 UI 看见的“正在做/等待用户/被停止”,不能只用一个 Promise 的 resolved/rejected 表示。 证据:[server/runtime-coordinator.ts:143](../OpenMausBot/server/runtime-coordinator.ts#L143)。 群聊还有独立的上下文与会话处理:房间 transcript、room sessions、room context tracker 都在服务装配时接入。 证据:[server/index.ts:20](../OpenMausBot/server/index.ts#L20)。 人与机器人交互不是只有一条纯文本回复;问题卡、等待用户、恢复卡片、MCP 登录卡等有专门宿主模块。 证据:[server/index.ts:28](../OpenMausBot/server/index.ts#L28)。 ## 8. 工具系统与审批边界 工具来源包含内建宿主能力、电脑能力、MCP 进程、连接的应用和不同模型引擎自身的工具。 MCP bridge 可以派生子进程,并增加控制授权、工具 schema 规范化、活动探测与 saved-steps journal。 证据:[server/mcp-bridge.ts:1](../OpenMausBot/server/mcp-bridge.ts#L1)。 因此“调用一个工具”不等于模型直接获得所有宿主权限。 电脑连接可以包装成 gatedLocalComputer:真实命令和参数留在环境变量里,调用先经过控制代理,携带 CONTROL_URL 和 CONTROL_TOKEN。 证据:[server/local-computer.ts:28](../OpenMausBot/server/local-computer.ts#L28)。 云电脑凭据更明确留在服务端,模型拿的是 turn-scoped capability 对应的工具入口。 工具包括远程命令、截图、复制文件、后台命令状态等,和普通模型文本生成是不同能力。 证据:[server/cloud-computer-tools.ts:1](../OpenMausBot/server/cloud-computer-tools.ts#L1)。 可复用的是这些契约和门禁设计;不能只复制工具 handler、丢掉运行上下文与授权代理。 ## 9. 桌面壳、真实电脑、Local VM、Cloud Computer ### Electron 壳 Electron 主进程是桌面程序入口,负责窗口和桌面能力组合;React 仍是渲染界面,Node 服务仍是业务中心。 浏览器模式没有天然的本机桌面权限;需要本地壳或配套连接,不能因为网页能打开就认为能控制电脑。 证据:[package.json:18](../OpenMausBot/package.json#L18)、[src/main.tsx:41](../OpenMausBot/src/main.tsx#L41)。 ### Your Computer / 本机桌面 本地电脑连接契约明确包含 darwin、linux、win32 三个平台。 macOS/Windows 使用 legacy descriptor 分支;Linux 另有严格的驱动文件身份核验及必要工具清单。 证据:[server/local-computer.ts:6](../OpenMausBot/server/local-computer.ts#L6)、[server/local-computer.ts:19](../OpenMausBot/server/local-computer.ts#L19)、[server/local-computer.ts:68](../OpenMausBot/server/local-computer.ts#L68)。 所以“只支持 macOS”不符合当前这份接口源码;但“三个平台接口存在”也不证明权限弹窗、辅助组件和各平台桌面会话全部已准备好。 本次不运行探测,无法据此宣布当前 Windows 机器可控制。 ### Local VM 源码自己说明:这是 Cua-backed Local VM,OMB 负责 sandbox 边界,桌面自动化由容器中的 cua-driver mcp 负责。 它不是 OpenMausBot 自己写的 CPU 虚拟机或全套远程桌面协议栈。 证据:[server/container-computer.ts:1](../OpenMausBot/server/container-computer.ts#L1)。 实现包含 Docker/Podman 运行时适配、容器启动/停止/删除、共享与按 bot 分隔的 target、工作区挂载和 viewer 端口。 共享 target 默认宿主 viewer 端口 6080,容器 viewer 端口 6901;per-bot target 使用受控身份生成。 证据:[server/container-computer.ts:71](../OpenMausBot/server/container-computer.ts#L71)、[server/container-computer.ts:91](../OpenMausBot/server/container-computer.ts#L91)。 Windows 分支专门处理 Podman Machine 的 WSL 挂载路径翻译,说明平台适配存在实际限制,不能把 Linux 命令原样搬到 Windows。 证据:[server/container-computer.ts:729](../OpenMausBot/server/container-computer.ts#L729)。 ### Cloud Computer 云电脑通过 Boat 适配器执行命令、截图和文件操作,仍由本地/托管宿主保存凭据并安排授权。 远端桌面可用性、资源、计费与网络属于外部依赖,仓库有调用代码不等于附送可用云资源。 证据:[server/cloud-computer-tools.ts:3](../OpenMausBot/server/cloud-computer-tools.ts#L3)。 ## 10. 浏览器、文件、数据和页面 浏览器能力不是聊天消息的一种格式,它有独立浏览器控制与实时 viewer 路由。 viewer 模块与统一 upgrade 门协作,避免把实时观看口变成免认证旁路。 证据:[server/routes/browser-viewers.ts:1](../OpenMausBot/server/routes/browser-viewers.ts#L1)、[server/routes/upgrades.ts:1](../OpenMausBot/server/routes/upgrades.ts#L1)。 数据模块以 bot 为所属边界,可产生表格和图表卡;schema 列出 bar、line、area、scatter、histogram、pie、heatmap 等图表类型。 字段、聚合函数、limit、bins 都有限制,不是任意输入都无条件交给渲染层。 证据:[server/data/routes.ts:21](../OpenMausBot/server/data/routes.ts#L21)。 文件与附件是独立资源,会话只引用它们;主服务检查附件是否仍被聊天或机器人头像使用。 证据:[server/index.ts:12099](../OpenMausBot/server/index.ts#L12099)。 页面、skills、routines 等模块各有独立实现,但本次没有穷尽每个操作分支:可确认是实际源码模块,不对所有子功能作运行保证。 阅读起点:[server/pages/service.ts](../OpenMausBot/server/pages/service.ts#L1)、[server/skills.ts](../OpenMausBot/server/skills.ts#L1)、[server/routines.ts](../OpenMausBot/server/routines.ts#L1)。 ## 11. 自动化、连接应用、语音与安全存储 自动化不是前端定时刷新:服务装配接入 bot automations、WaitManager、wait host 和 waits routes,用会话上下文管理等待与继续。 证据:[server/index.ts:486](../OpenMausBot/server/index.ts#L486)。 应用接入分多类:团队连接、cloud connected apps、聊天内应用;主服务分别建立对应 host 和 routes。 这些属于与外部应用账户和权限相连的子系统,不能把“配置了连接”当成“所有 bot 都可使用”。 证据:[server/index.ts:24](../OpenMausBot/server/index.ts#L24)、[server/index.ts:467](../OpenMausBot/server/index.ts#L467)。 仓库也有 tts、meetings、phones、vault 等实际子模块。 本报告不以目录存在推断会议服务、手机或语音供应商当前可用;这些应在部署时按对应路由、账户和设备逐项验证。 ## 12. 数据到底存在哪里 默认数据根目录是用户数据 home 下的 .openmausbot,可用 OMB_DATA_DIR 覆盖。 还保留从旧 .opengrokbot 目录迁移的逻辑,并创建 events、native 子目录。 证据:[server/config.ts:695](../OpenMausBot/server/config.ts#L695)。 config.json 是持久配置,读取时经过 schema/解析与文件缓存;机器人与群组档案由 store 管理 JSON 文件。 证据:[server/config.ts:568](../OpenMausBot/server/config.ts#L568)、[server/config.ts:712](../OpenMausBot/server/config.ts#L712)、[server/store.ts:178](../OpenMausBot/server/store.ts#L178)。 消息有 SQLite 数据层,运行协调器另有 RuntimeStore:聊天历史和执行状态不能当作同一张表。 这类嵌入式存储适合本地单服务,不需要用户先装 PostgreSQL,但备份需要覆盖多个文件。 证据:[server/message-db.ts:1](../OpenMausBot/server/message-db.ts#L1)、[server/runtime/store.ts:1](../OpenMausBot/server/runtime/store.ts#L1)。 用量、决策等追加日志采用 JSONL,适合逐条记录与按月维护;它们不是消息数据库的替代品。 证据:[server/usage-ledger.ts:1](../OpenMausBot/server/usage-ledger.ts#L1)、[server/decision-log.ts:1](../OpenMausBot/server/decision-log.ts#L1)。 外部 Claude/Codex 引擎还有自己的原生会话文件,删除/清理逻辑显式认识它们的 JSONL 布局。 证据:[server/host/delete-leftovers.ts:24](../OpenMausBot/server/host/delete-leftovers.ts#L24)。 不要把整个系统想成“复制一个 JSON 就迁移完了”:至少要考虑配置、档案、消息库、运行状态、附件、原生引擎目录及秘密材料。 恢复工作区时,代码还要求先解除团队电脑分配,防止恢复后的团队名字意外获得旧桌面权限。 证据:[server/index.ts:12684](../OpenMausBot/server/index.ts#L12684)。 ## 13. 配套服务不是主程序的别名 ### Companion companion 有独立 Node 入口和运行脚本,主服务给它提供专用配对入口。 它是配套设备接入路线,不是把全部主服务复制到一个手机网页。 证据:[package.json:33](../OpenMausBot/package.json#L33)、[companion/src/index.ts:1](../OpenMausBot/companion/src/index.ts#L1)、[server/index.ts:12611](../OpenMausBot/server/index.ts#L12611)。 ### Connector connector 的明确用途是:让用户自己的服务器承载一个 Cloud home,通过一条主动向外的连接受管理。 两端先证明密钥,管理员任务对这台机器签名,回复重发直到确认,home 请求通过 yamux streams 复用。 证据:[connector/package.json:5](../OpenMausBot/connector/package.json#L5)、[connector/src/agent.ts:1](../OpenMausBot/connector/src/agent.ts#L1)。 因此它是部署与控制代理,不是普通大模型驱动,更不能默认当成无需鉴权的远程 shell。 未获团队 Owner 接受时,任务范围只允许 status 和 host-health 两个读操作。 证据:[connector/src/agent.ts:27](../OpenMausBot/connector/src/agent.ts#L27)。 ### Relay 与 Cloudflare control-plane relay 是独立运行服务:读取环境配置后 startRelay,具备自己的退出与关闭逻辑。 它负责连接转发,不拥有主聊天产品全部状态。 证据:[relay/src/main.ts:1](../OpenMausBot/relay/src/main.ts#L1)、[relay/src/server.ts:1](../OpenMausBot/relay/src/server.ts#L1)。 Cloudflare control-plane 是另一个云部署面,有独立入口;不能把它的云基础设施依赖算成离线本地聊天的硬性前提。 阅读起点:[cloudflare/control-plane/src/index.ts](../OpenMausBot/cloudflare/control-plane/src/index.ts#L1)。 ## 14. 一次实际工作在架构上如何走 1. 页面先选择入口与验证会话,才进入完整 App。 2. 用户动作进入客户端 store,被翻译成后端 HTTP 请求。 3. 服务处理认证、可见范围与维护门,再派给路由或会话逻辑。 4. 宿主组合机器人配置、上下文、协调状态,交给所选 ProviderDriver。 5. 驱动运行模型/CLI;工具请求按 scope、审批与电脑控制边界处理。 6. 结果与状态写入对应持久层,通过 SSE 推给有权看到的页面。 7. 如需看实时桌面/浏览器,则另建受认证的 viewer/WebSocket 通道。 对应证据:[src/main.tsx:40](../OpenMausBot/src/main.tsx#L40)、[src/state/store.tsx:2708](../OpenMausBot/src/state/store.tsx#L2708)、[server/index.ts:12694](../OpenMausBot/server/index.ts#L12694)、[server/contracts.ts:593](../OpenMausBot/server/contracts.ts#L593)、[server/local-computer.ts:28](../OpenMausBot/server/local-computer.ts#L28)、[server/index.ts:14627](../OpenMausBot/server/index.ts#L14627)。 ## 15. 运行依赖和限制 核心开发环境要求 Node >=24、pnpm 10.33.0,代码使用 ESM 和 Node 的 TypeScript stripping 入口。 证据:[package.json:17](../OpenMausBot/package.json#L17)、[package.json:33](../OpenMausBot/package.json#L33)。 普通网页前端依赖 React/Vite;桌面版另需 Electron;实时远程桌面前端使用 noVNC 包,后端有 ws 与 zod。 证据:[package.json:108](../OpenMausBot/package.json#L108)、[package.json:149](../OpenMausBot/package.json#L149)。 可选能力需要额外条件:所选模型的 CLI/账号/API;本机桌面驱动与系统授权;Docker/Podman 和 Cua 镜像;Boat 云资源;连接应用账户;companion 设备与 relay/控制面部署。 没用到的功能不应被当作所有用户的必装依赖。 主服务集中装配很多功能,重用单个模块时容易碰到配置、全局 store、授权和事件上下文耦合。 SQLite/文件存储、原生 CLI session 和桌面平台适配,也限制了“随便放进无状态 serverless 就能运行”的设想。 代码存在并不保证数据迁移与并发恢复无缺陷;本次禁止运行,不能声称性能、故障恢复、跨平台打包或全部驱动已经验证。 ## 16. 已实现与规划,怎样不看错 已实现的强证据包括:真正的 React 启动分支、Node HTTP 入口、SSE route、WebSocket gate、内建驱动注册、容器 target、带控制凭据的工具代理、connector 的签名通道。 这些都有上面的实际代码引用,不依赖文档标题。 配置中的 feature flag 只是可选开关。例如 agentsToolBridge 默认不打开;savedSteps 默认开启;usbPhoneTakeover 和 cloudComputerAutoReplace 还各有默认或覆盖规则。 不能把这些布尔字段的存在等同于所有引擎、设备和平台都支持该能力。 证据:[server/config.ts:247](../OpenMausBot/server/config.ts#L247)。 仓库的 control-plane roadmap 是规划文本;读它只能知道规划拆分,不能用它覆盖当前实现事实。 当前 connector/relay/control-plane 已有代码,也不能反过来证明 roadmap 的每项验收都完成了。 证据:[控制面路线图:1](../OpenMausBot/docs/superpowers/plans/2026-08-31-00-control-plane-roadmap.md#L1)。 ## 17. 可复用边界:什么值得拿,什么不能生搬 最适合先研究的是 shared 事件结构、ProviderDriver 契约、路由上下文和 HTTP/SSE 组合。这些把不同引擎变成统一产品行为。 复制前必须一起理解 session、approval、tool scope、能力声明,否则表面接上模型,行为仍可能不兼容。 电脑部分可复用授权门、运行时适配和 target 身份设计,但实际桌面能力来自 Cua/Boat/平台助手。 拿走容器管理代码不等于拿走全部桌面自动化,也不等于获得外部服务使用权。 多机器人协调有参考价值,但它和持久运行状态、房间上下文、等待用户卡片和停止语义相连;不宜只摘一个 coordinate 函数。 客户端 UI 也依赖统一 wire 事件、会话和 store,不能直接视为可插拔聊天组件库。 connector/relay 应作为独立服务研究,维持签名、认证、限额和重连机制;不要当作聊天后端的几个可复制路由。 许可证需同时检查主仓库声明和 third_party 归属,Apache-2.0 的根声明不是替所有 vendored 组件做了许可证保证。 证据:[package.json:15](../OpenMausBot/package.json#L15)、[server/contracts.ts:1](../OpenMausBot/server/contracts.ts#L1)。 ## 18. 最终摘要 它的主干是 React 界面 + Node 原生 HTTP 服务 + 多引擎驱动,Electron 提供桌面壳与本地能力。 真正复杂的地方在于让机器人长期工作:多人可见性、协调交接、审批等待、工具和电脑授权、多个持久层,以及故障后的继续/停止语义。 Local VM 是容器化 Cua 桌面;Cloud Computer 是远程适配;Your Computer 是平台本机连接,三者不能混为一谈。 复用时优先拿契约和边界设计,再按目标功能带走依赖链;不要把整个项目当成轻量聊天 UI,也不要把文档规划或注册项当成已经实测成功。