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

29 KiB
Raw Blame History

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、package.json:15。

2. 阅读约束与可信度

仓库要求:声称服务或会话改动有效之前,要按验证说明启动隔离 fixture,不能拿用户真实数据验证修改。 本次是只读架构分析,没有修改服务,也没有声称测试通过,所以没有启动这些 fixture。 证据:AGENTS.md:3。

证据分三层:

  • 实现明确:入口确实导入模块,路由确实调用 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。 后端不是 Express/Nest/Fastify:核心直接导入 Node 的 createServer、IncomingMessage、ServerResponse。 证据:server/index.ts:11。

主要目录的分工:

3.1 功能模块速查

模块 用户看见的功能 后端负责的事情与源码入口
Bot 与会话 建机器人、单聊、历史 身份、配置和会话归属:Store
群聊与协作 群成员、任务交接、团队活动 多 Bot 调用和协调:coordinator
模型引擎 选择模型或本地编码助手 统一不同引擎的输入、事件和能力:drivers
记忆 查看、维护 Bot 记忆和个人信息 记忆文档、变更日志、回退和整理:记忆路由
自动化 定时工作、触发器、等待与继续 计划计算、运行记录、失败恢复及暂停:routines
工具与审批 工具执行过程、确认卡片 MCP 桥接、权限范围、控制代理:mcp-bridge
浏览器 实时网页画面与操作 浏览器控制、授权观看连接:browser-viewers
电脑 本机、Local VM、云电脑面板 三种不同执行环境,详见第9节
文件与数据 附件、文件视图、表格图表 附件归属和数据查询:数据路由
邮件与应用 连接邮箱及外部应用 邮箱发现、连接校验、发送配置与账户存储:邮件服务
页面与技能 发布页面、技能和例程 独立服务模块:页面服务、skills
运行记录 用量与执行状态 运行数据库、用量日志:runtime store、usage ledger
手机与云端配套 配对、远程连接、托管主机 companion、relay、connector、control-plane,详见第13节

记忆不等于聊天记录:记忆路由导入独立 memory store、journal、upkeep,能分别管理记忆内容、修改记录和整理状态。团队环境还定义个人记忆层及写权限回调,见 记忆依赖契约。不能因为存在记忆维护接口,就宣称模型记住的内容一定正确。

4. 前端:框架、入口和运行方式

前端是 React 19 + TypeScript + Vite 7。桌面开发依赖 Electron 43。 版本证据:package.json:132、package.json:166、package.json:175。

启动入口先设置主题、字体、聊天宽度、软件渲染与语言,避免首屏先闪出错误样式。 随后才决定当前应该显示主页、配对页、登录页还是完整应用。 证据:src/main.tsx:22、src/main.tsx:40。

这里不是简单地无条件渲染 App:/home、/pair、/desktop-viewer 不预先加载大应用块。 其他页面会并行开始加载 App 与读取会话,降低登录后的等待。 证据:src/main.tsx:30。

界面是否能用,还要经过会话判断:未认证展示配对,团队退出展示离开页,桌面本地主页可接 Electron bridge。 window.ogb 是桌面壳向页面暴露能力的入口,浏览器环境不应假定它存在。 证据:src/main.tsx:41、src/main.tsx:52。

Vite 的开发监听明确绑定 IPv4 127.0.0.1,默认 UI 端口 5199,可用 OMB_UI_PORT 改。 这是开发服务器,不应和正式 Node 后端混成一台服务。 证据:vite.config.ts:79。

客户端状态层负责把群组、机器人任务、项目等用户动作转换成 API 请求,并再分发服务端返回状态。 例如删除群组、更新任务、创建机器人项目分别有真实请求调用。 证据:src/state/store.tsx:2668、src/state/store.tsx:2708、src/state/store.tsx:2723。

5. 后端:入口、框架和 API

根脚本把 omb 指向 Node 直接执行的命令入口,dev:server 指向开发引导文件。 开发引导只设开发场景的本地浏览器信任变量,然后动态导入真正的服务入口。 证据:package.json:33、server/dev-server.ts:1。

主服务体积很大:本次读取快照的入口约 15,448 行。 它已经抽出 routes、host、runtime、drivers 等模块,但还不能称为完全解耦的插件内核。 一些路由已走统一分发,其他功能仍在主服务中组合或内联处理。 证据:server/index.ts:12694。

HTTP、SSE、WebSocket 分别干什么

HTTP 是“请求一件事并取得结果”:登录、配对、配置变更、查询、提交操作、附件等。 SSE 是“服务器不断告诉页面发生了什么”:聊天与运行状态变化,不需要浏览器不断轮询整段会话。 WebSocket 是适合双向实时或二进制通道的另一层,浏览器画面等实时连接由相应路由拥有;它不是所有聊天 API 的统一底座。

SSE 路径明确为 GET /api/events,响应 content-type 为 text/event-stream,并有心跳、会话存活判断、可见性过滤和背压状态。 证据:server/index.ts:14627。

WebSocket upgrade 不绕过 HTTP 安全门:它转入同一个请求处理器,通过认证、托管工作区和维护门后才由所属路由完成握手。 握手有 10 秒限制,提前到来的数据有 64 KiB 上限。 证据:server/routes/upgrades.ts:1、server/routes/upgrades.ts:35。

已核验的 API 入口例子

这是一份代表性接口地图,不是把 15,000 行入口及全部路由穷尽导出的 OpenAPI 文档。 internal 不代表不鉴权,也不代表可给外部集成任意调用。

6. 模型引擎:真正的可替换边界

ProviderDriver 是“某种引擎怎样接进来”的公共契约,驱动把自己的模型/会话行为翻译成宿主统一理解的形式。 会话能力声明包含队列、审批等差异,因此相同界面不代表每种引擎功能完全相同。 证据:server/contracts.ts:247、server/contracts.ts:593。

当前 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、server/drivers/builtIn.ts:32。

其中大量 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。

7. 机器人、会话、多机器人协作

机器人不是一个独立微服务;它更像宿主里的长期档案和配置,关联多条会话与执行状态。 聊天记录、运行会话和机器人档案要分开理解:删一个 UI 卡片,不等于所有底层引擎文件都消失。

协调器负责交接、派工、查询进度,把多个 bot 的工作组织成可恢复的过程。 主入口引入 createCoordinator、ComposedTurn、CoordinateBotsCall、HandoffOptions、HostTurnResult 等显式契约。 证据:server/index.ts:27、server/coordinator.ts:1。

运行协调层另有 RuntimeStore 与 Runtime,保存停止记录、交接与工作状态。 因此 UI 看见的“正在做/等待用户/被停止”,不能只用一个 Promise 的 resolved/rejected 表示。 证据:server/runtime-coordinator.ts:143。

群聊还有独立的上下文与会话处理:房间 transcript、room sessions、room context tracker 都在服务装配时接入。 证据:server/index.ts:20。

人与机器人交互不是只有一条纯文本回复;问题卡、等待用户、恢复卡片、MCP 登录卡等有专门宿主模块。 证据:server/index.ts:28。

8. 工具系统与审批边界

工具来源包含内建宿主能力、电脑能力、MCP 进程、连接的应用和不同模型引擎自身的工具。 MCP bridge 可以派生子进程,并增加控制授权、工具 schema 规范化、活动探测与 saved-steps journal。 证据:server/mcp-bridge.ts:1。

因此“调用一个工具”不等于模型直接获得所有宿主权限。 电脑连接可以包装成 gatedLocalComputer:真实命令和参数留在环境变量里,调用先经过控制代理,携带 CONTROL_URL 和 CONTROL_TOKEN。 证据:server/local-computer.ts:28。

云电脑凭据更明确留在服务端,模型拿的是 turn-scoped capability 对应的工具入口。 工具包括远程命令、截图、复制文件、后台命令状态等,和普通模型文本生成是不同能力。 证据:server/cloud-computer-tools.ts:1。

可复用的是这些契约和门禁设计;不能只复制工具 handler、丢掉运行上下文与授权代理。

9. 桌面壳、真实电脑、Local VM、Cloud Computer

Electron 壳

Electron 主进程是桌面程序入口,负责窗口和桌面能力组合;React 仍是渲染界面,Node 服务仍是业务中心。 浏览器模式没有天然的本机桌面权限;需要本地壳或配套连接,不能因为网页能打开就认为能控制电脑。 证据:package.json:18、src/main.tsx:41。

Your Computer / 本机桌面

本地电脑连接契约明确包含 darwin、linux、win32 三个平台。 macOS/Windows 使用 legacy descriptor 分支;Linux 另有严格的驱动文件身份核验及必要工具清单。 证据:server/local-computer.ts:6、server/local-computer.ts:19、server/local-computer.ts:68。

所以“只支持 macOS”不符合当前这份接口源码;但“三个平台接口存在”也不证明权限弹窗、辅助组件和各平台桌面会话全部已准备好。 本次不运行探测,无法据此宣布当前 Windows 机器可控制。

Local VM

源码自己说明:这是 Cua-backed Local VM,OMB 负责 sandbox 边界,桌面自动化由容器中的 cua-driver mcp 负责。 它不是 OpenMausBot 自己写的 CPU 虚拟机或全套远程桌面协议栈。 证据:server/container-computer.ts:1。

实现包含 Docker/Podman 运行时适配、容器启动/停止/删除、共享与按 bot 分隔的 target、工作区挂载和 viewer 端口。 共享 target 默认宿主 viewer 端口 6080,容器 viewer 端口 6901;per-bot target 使用受控身份生成。 证据:server/container-computer.ts:71、server/container-computer.ts:91。

Windows 分支专门处理 Podman Machine 的 WSL 挂载路径翻译,说明平台适配存在实际限制,不能把 Linux 命令原样搬到 Windows。 证据:server/container-computer.ts:729。

Cloud Computer

云电脑通过 Boat 适配器执行命令、截图和文件操作,仍由本地/托管宿主保存凭据并安排授权。 远端桌面可用性、资源、计费与网络属于外部依赖,仓库有调用代码不等于附送可用云资源。 证据:server/cloud-computer-tools.ts:3。

10. 浏览器、文件、数据和页面

浏览器能力不是聊天消息的一种格式,它有独立浏览器控制与实时 viewer 路由。 viewer 模块与统一 upgrade 门协作,避免把实时观看口变成免认证旁路。 证据:server/routes/browser-viewers.ts:1、server/routes/upgrades.ts:1。

数据模块以 bot 为所属边界,可产生表格和图表卡;schema 列出 bar、line、area、scatter、histogram、pie、heatmap 等图表类型。 字段、聚合函数、limit、bins 都有限制,不是任意输入都无条件交给渲染层。 证据:server/data/routes.ts:21。

文件与附件是独立资源,会话只引用它们;主服务检查附件是否仍被聊天或机器人头像使用。 证据:server/index.ts:12099。

页面、skills、routines 等模块各有独立实现,但本次没有穷尽每个操作分支:可确认是实际源码模块,不对所有子功能作运行保证。 阅读起点:server/pages/service.ts、server/skills.ts、server/routines.ts。

11. 自动化、连接应用、语音与安全存储

自动化不是前端定时刷新:服务装配接入 bot automations、WaitManager、wait host 和 waits routes,用会话上下文管理等待与继续。 证据:server/index.ts:486。

应用接入分多类:团队连接、cloud connected apps、聊天内应用;主服务分别建立对应 host 和 routes。 这些属于与外部应用账户和权限相连的子系统,不能把“配置了连接”当成“所有 bot 都可使用”。 证据:server/index.ts:24、server/index.ts:467。

仓库也有 tts、meetings、phones、vault 等实际子模块。 本报告不以目录存在推断会议服务、手机或语音供应商当前可用;这些应在部署时按对应路由、账户和设备逐项验证。

12. 数据到底存在哪里

默认数据根目录是用户数据 home 下的 .openmausbot,可用 OMB_DATA_DIR 覆盖。 还保留从旧 .opengrokbot 目录迁移的逻辑,并创建 events、native 子目录。 证据:server/config.ts:695。

config.json 是持久配置,读取时经过 schema/解析与文件缓存;机器人与群组档案由 store 管理 JSON 文件。 证据:server/config.ts:568、server/config.ts:712、server/store.ts:178。

消息有 SQLite 数据层,运行协调器另有 RuntimeStore:聊天历史和执行状态不能当作同一张表。 这类嵌入式存储适合本地单服务,不需要用户先装 PostgreSQL,但备份需要覆盖多个文件。 证据:server/message-db.ts:1、server/runtime/store.ts:1。

用量、决策等追加日志采用 JSONL,适合逐条记录与按月维护;它们不是消息数据库的替代品。 证据:server/usage-ledger.ts:1、server/decision-log.ts:1。

外部 Claude/Codex 引擎还有自己的原生会话文件,删除/清理逻辑显式认识它们的 JSONL 布局。 证据:server/host/delete-leftovers.ts:24。

不要把整个系统想成“复制一个 JSON 就迁移完了”:至少要考虑配置、档案、消息库、运行状态、附件、原生引擎目录及秘密材料。 恢复工作区时,代码还要求先解除团队电脑分配,防止恢复后的团队名字意外获得旧桌面权限。 证据:server/index.ts:12684。

13. 配套服务不是主程序的别名

Companion

companion 有独立 Node 入口和运行脚本,主服务给它提供专用配对入口。 它是配套设备接入路线,不是把全部主服务复制到一个手机网页。 证据:package.json:33、companion/src/index.ts:1、server/index.ts:12611。

Connector

connector 的明确用途是:让用户自己的服务器承载一个 Cloud home,通过一条主动向外的连接受管理。 两端先证明密钥,管理员任务对这台机器签名,回复重发直到确认,home 请求通过 yamux streams 复用。 证据:connector/package.json:5、connector/src/agent.ts:1。

因此它是部署与控制代理,不是普通大模型驱动,更不能默认当成无需鉴权的远程 shell。 未获团队 Owner 接受时,任务范围只允许 status 和 host-health 两个读操作。 证据:connector/src/agent.ts:27。

Relay 与 Cloudflare control-plane

relay 是独立运行服务:读取环境配置后 startRelay,具备自己的退出与关闭逻辑。 它负责连接转发,不拥有主聊天产品全部状态。 证据:relay/src/main.ts:1、relay/src/server.ts:1。

Cloudflare control-plane 是另一个云部署面,有独立入口;不能把它的云基础设施依赖算成离线本地聊天的硬性前提。 阅读起点:cloudflare/control-plane/src/index.ts。

14. 一次实际工作在架构上如何走

  1. 页面先选择入口与验证会话,才进入完整 App。
  2. 用户动作进入客户端 store,被翻译成后端 HTTP 请求。
  3. 服务处理认证、可见范围与维护门,再派给路由或会话逻辑。
  4. 宿主组合机器人配置、上下文、协调状态,交给所选 ProviderDriver。
  5. 驱动运行模型/CLI;工具请求按 scope、审批与电脑控制边界处理。
  6. 结果与状态写入对应持久层,通过 SSE 推给有权看到的页面。
  7. 如需看实时桌面/浏览器,则另建受认证的 viewer/WebSocket 通道。

对应证据:src/main.tsx:40、src/state/store.tsx:2708、server/index.ts:12694、server/contracts.ts:593、server/local-computer.ts:28、server/index.ts:14627。

15. 运行依赖和限制

核心开发环境要求 Node >=24、pnpm 10.33.0,代码使用 ESM 和 Node 的 TypeScript stripping 入口。 证据:package.json:17、package.json:33。

普通网页前端依赖 React/Vite;桌面版另需 Electron;实时远程桌面前端使用 noVNC 包,后端有 ws 与 zod。 证据:package.json:108、package.json:149。

可选能力需要额外条件:所选模型的 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。

仓库的 control-plane roadmap 是规划文本;读它只能知道规划拆分,不能用它覆盖当前实现事实。 当前 connector/relay/control-plane 已有代码,也不能反过来证明 roadmap 的每项验收都完成了。 证据:控制面路线图:1。

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、server/contracts.ts:1。

18. 最终摘要

它的主干是 React 界面 + Node 原生 HTTP 服务 + 多引擎驱动,Electron 提供桌面壳与本地能力。 真正复杂的地方在于让机器人长期工作:多人可见性、协调交接、审批等待、工具和电脑授权、多个持久层,以及故障后的继续/停止语义。 Local VM 是容器化 Cua 桌面;Cloud Computer 是远程适配;Your Computer 是平台本机连接,三者不能混为一谈。 复用时优先拿契约和边界设计,再按目标功能带走依赖链;不要把整个项目当成轻量聊天 UI,也不要把文档规划或注册项当成已经实测成功。