dsh-sansheng-liubu/docs/openmausbot-analysis.md

373 lines
29 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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,也不要把文档规划或注册项当成已经实测成功。