dsh-sansheng-liubu/docs/architecture-overview.md

10 KiB
Raw Blame History

DS Bot 与 OpenMausBot:架构拆解总览

分析日期:2026-11-14。分析对象为本地克隆源码,不是在线产品演示。

  • DS Bot:提交 a66cc737,插件与桌面应用清单版本均为 0.3.6。
  • OpenMausBot:提交 a6cd67c78,清单版本为 0.1.158。
  • 三省六部新项目从 v0.0.1 开始,这是我们自己的版本,不应把下载来的两个上游项目版本强改为 0.0.1。

本轮只做源码阅读与架构分析,没有安装依赖、启动应用、验证外部账号或修改上游业务代码。文中“已实现”表示找到源码接线与实现,不代表已在本机实测所有功能。

1. 先把几个词分清

层 大白话 举例
前端 人看见、点击、输入的界面 Bot 列表、聊天框、设置、审批卡、电脑画面
后端 收消息、决定交给谁、保存数据和协调执行的服务 建 Bot、发群消息、排队、记账、读写历史
Agent 执行引擎 真正和模型来回交互、调用工具干活的部分 DSH 会话循环、Claude/Codex 适配器、API 模型循环
工具与集成 Agent 能使用的具体能力 文件、浏览器、电脑、邮件、MCP、外部应用
桌面壳 把网页装进桌面窗口,并接入操作系统 Electron 窗口、更新、托盘、进程管理
数据层 关掉软件之后还保存的东西 Bot 配置、聊天记录、记忆、任务与运行状态

前端显示“正在工作”,不等于前端自己在跑模型;聊天界面、任务调度和模型执行是不同层。

2. 两个项目最根本的区别

DS Bot 是 DSH 之上的 Bot 团队产品层;OpenMausBot 是拥有自己服务端和执行适配层的独立应用。

对比项 DS Bot OpenMausBot
产品形态 DSH 插件,另有捆绑固定 DSH 的桌面应用 独立应用,网页与桌面共用核心服务
前端 插件版 JavaScript + React 接入 DSH;桌面另有 React 页面;手机为 Expo / React Native TypeScript + React,独立应用根组件;Vite 构建
后端 DSH 插件的宿主模块,使用注入服务 Node.js + TypeScript,自建 HTTP 服务
执行核心 普通 DSH Session 执行循环;另有本地 Agent 接入模块 自己的驱动接口,连接多种 CLI/ACP 引擎及 API 模型
前后端通信 POST api/bot 发送 endpoint/payload;会话还依赖 DSH 服务 自己的 HTTP API 与事件流;部分实时连接另用 WebSocket
桌面 Electron;启动隔离的 DSH 环境 Electron;启动自己的服务,并桥接设备与窗口能力
核心状态 Bot 团队状态 JSON + DSH 管理的会话;另有索引/记忆/附件 配置文件 + SQLite 数据库 + 事件与文件资源
运行时依赖 离不开 DSH 插件服务接口 不依赖 DSH;部分能力依赖额外引擎、系统组件或云服务

证据入口:DS Bot 插件装配、DS Bot 浏览器入口、DS Bot 请求封装、DS Bot 桌面清单、OpenMausBot 网页入口、OpenMausBot 后端入口、OpenMausBot 驱动注册。

3. DS Bot:从外到内怎么分

用户
  → DS Bot 的 React 界面
    → DSH 界面插槽 / 会话界面 + api/bot 业务请求
      → DS Bot 宿主模块:Bot 名册、群聊、投递、权限、记忆、计划
        → DSH 会话与执行服务
          → 模型、工具和外部集成

桌面版:独立 React 页面 → Bot API / SSE → 带 DS Bot 插件的精简 DSH engine。
手机版:Expo / React Native 页面 → 配对与加密链路 → 同一个 Bot 后端。

最外层克隆目录和里面的插件目录都叫 ds-bot,所以存在双层同名目录,这是上游布局。

源码区 职责
插件目录 真正装入 DSH 的功能包
前端源码 团队侧栏、聊天呈现、设置、功能面板
后端源码 Bot 生命周期、调度、消息、工具与存储
共享源码 前后端共用的规则与结构
桌面应用 安装、窗口、独立 React 页面、固定 DSH engine
桌面前端 桌面版独立页面,复用插件组件与样式
手机应用 Expo / React Native 原生客户端
手机链路 配对加密协议与 Relay 中继
测试 功能与边界测试,不属于运行时界面
开发环境 测试用 DSH、模拟模型及开发验证

桌面端不是完整 DSH Web 的简单套壳:桌面页面入口 有自己的 React 根组件,engine 配置 明确不装 DSH Web 前端,窗口只与 Bot API 交互。

插件入口 用一个模块列表依次安装功能,各模块通过同一个运行时对象相互调用。它是“一个宿主里很多业务模块”,不能把每个文件理解成独立后端服务。

前端生成文件 是编译产物。后续改界面应改 前端源码,再构建,而不是直接改生成文件。

4. OpenMausBot:从外到内怎么分

用户
  → React 网页 / Electron 窗口
    → 自有 HTTP API 与实时事件
      → Node 服务:Bot、会话、群聊、权限、调度、持久化
        → 统一驱动接口
          → CLI / ACP / API 模型执行
        → 电脑、浏览器、文件、MCP、外部应用等工具

Electron 还承担桌面启动、系统桥接与本地设备能力。
云端与远程功能在核心聊天之外有额外的服务组件和部署条件。
源码区 职责
网页前端 主应用、界面组件、状态与请求处理
后端 主服务与具体业务能力
引擎适配 把不同 Agent 引擎统一接到应用
共享结构 前后端之间的类型、规则和数据约定
桌面进程 窗口、启动、更新和系统桥接
脚本 构建、控制命令与配套工具

主界面装配 直接接入单聊、群聊、活动、文件、电脑、虚拟机、插件、团队图、触发器等面板。驱动注册 显示它不是只接一个模型:Claude、Codex、多个 ACP Agent 以及 OpenAI-compatible 等模型 API 都走对应适配器。

注意:驱动是“接线转换层”,不是这些第三方引擎本身;存在适配器也不代表本机已安装引擎、已经登录或配置了有效账号。

还要把这些配套项目与核心后端分开看:

配套组件 职责与边界
手机伴随服务 让已经配对的手机连接核心服务,不替代核心 Agent 执行
远程中继 分别接入 host、data、phone 的 WebSocket 连接
云主机连接器 通过出站连接把用户自己的服务器纳入云端管理
Cloudflare 控制平面 云账号身份、安装归属和托管连接入口;文档明确它不存放本地 Bot、聊天与 SQLite 会话数据
手机协议包 手机连接相关的共享协议约定
文档站 产品文档页面,不是聊天前端

5. 两者都要沿着这条链理解

以“让两个 Bot 一起分析文件”为例:

  1. 前端收集文字、附件和目标 Bot/群聊。
  2. 后端检查权限、工作目录和当前会话,接收或排队。
  3. 团队模块决定消息发给谁,维护上下文和协作关系。
  4. 执行引擎向模型发送输入,再调用读文件等工具。
  5. 工具结果回到执行引擎,模型继续分析或给出回答。
  6. 后端保存结果、更新状态,前端显示过程和产物。

DS Bot 的第 4 步主要交给 DSH;OpenMausBot 通过自己的驱动体系衔接执行。两边的界面可以长得相似,但底下的会话 ID、事件格式、权限和数据保存方式不同。

DS Bot 也支持本地 Agent,并非只能直接调用模型 API:本地 Agent 入口 会发现 CLI、注册 DSH 模型适配器,并保存 DSH Session 与 CLI Session 的对应关系。这和 OpenMausBot 的自有驱动体系是两种接入方式。

DS Bot 的 JSON 保存团队状态,不代表所有数据都是 JSON:聊天搜索索引 使用 SQLite,真正的 DSH 会话记录另由宿主管理。迁移时不能只搬团队配置文件就认为带走了全部聊天历史。

6. 对三省六部 v0.0.1 的直接意义

这部分是基于架构的判断,不是已经确定的实施方案。

  • 如果继续在 DSH 内做部门团队,DS Bot 的宿主接入、角色配置、会话管理和消息协作与现有环境更接近。
  • 如果做脱离 DSH 的独立产品,OpenMausBot 的自有前后端、驱动接口和桌面管理更值得详细研究。
  • 不能把两个项目的文件夹直接拼起来就得到一个完整产品。至少要统一 Bot 身份、会话、任务、权限、事件和存储接口。
  • Main Bot/管理员权限不等于三省六部的审核、退回、执行制度;现有角色系统只是基础。
  • 一个 Bot 绑定文件夹,也不等于项目之间的配置、上下文、任务、模型与运行操作已经全部隔离。项目隔离仍需逐层设计和验收。
  • 电脑控制、云电脑、手机、邮件和外部应用均属于能力层,不能据此推断核心聊天必须启动全部外部服务。

7. 详细模块手册

详细手册给出各模块的职责、源码入口、数据与通信链路、运行依赖,以及源码存在和本机实测之间的区别。