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

149 lines
10 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.

# 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/index.js#L55)、[DS Bot 浏览器入口](../ds-bot/ds-bot/src/client/index.js#L61)、[DS Bot 请求封装](../ds-bot/ds-bot/src/client/api.js#L4)、[DS Bot 桌面清单](../ds-bot/app/package.json#L25)、[OpenMausBot 网页入口](../OpenMausBot/src/main.tsx#L1)、[OpenMausBot 后端入口](../OpenMausBot/server/index.ts#L11)、[OpenMausBot 驱动注册](../OpenMausBot/server/drivers/builtIn.ts#L32)。
## 3. DS Bot:从外到内怎么分
```text
用户
→ DS Bot 的 React 界面
→ DSH 界面插槽 / 会话界面 + api/bot 业务请求
→ DS Bot 宿主模块:Bot 名册、群聊、投递、权限、记忆、计划
→ DSH 会话与执行服务
→ 模型、工具和外部集成
桌面版:独立 React 页面 → Bot API / SSE → 带 DS Bot 插件的精简 DSH engine。
手机版:Expo / React Native 页面 → 配对与加密链路 → 同一个 Bot 后端。
```
最外层克隆目录和里面的插件目录都叫 ds-bot,所以存在双层同名目录,这是上游布局。
| 源码区 | 职责 |
|---|---|
| [插件目录](../ds-bot/ds-bot/) | 真正装入 DSH 的功能包 |
| [前端源码](../ds-bot/ds-bot/src/client/) | 团队侧栏、聊天呈现、设置、功能面板 |
| [后端源码](../ds-bot/ds-bot/src/host/) | Bot 生命周期、调度、消息、工具与存储 |
| [共享源码](../ds-bot/ds-bot/src/shared/) | 前后端共用的规则与结构 |
| [桌面应用](../ds-bot/app/) | 安装、窗口、独立 React 页面、固定 DSH engine |
| [桌面前端](../ds-bot/app/ui/src/) | 桌面版独立页面,复用插件组件与样式 |
| [手机应用](../ds-bot/mobile/) | Expo / React Native 原生客户端 |
| [手机链路](../ds-bot/link/) | 配对加密协议与 Relay 中继 |
| [测试](../ds-bot/ds-bot/test/) | 功能与边界测试,不属于运行时界面 |
| [开发环境](../ds-bot/ds-bot/dev/) | 测试用 DSH、模拟模型及开发验证 |
桌面端不是完整 DSH Web 的简单套壳:[桌面页面入口](../ds-bot/app/ui/src/main.js#L1) 有自己的 React 根组件,[engine 配置](../ds-bot/app/engine/cordis.patch.yml#L1) 明确不装 DSH Web 前端,窗口只与 Bot API 交互。
[插件入口](../ds-bot/ds-bot/index.js#L63) 用一个模块列表依次安装功能,各模块通过同一个运行时对象相互调用。它是“一个宿主里很多业务模块”,不能把每个文件理解成独立后端服务。
[前端生成文件](../ds-bot/ds-bot/client.js) 是编译产物。后续改界面应改 [前端源码](../ds-bot/ds-bot/src/client/),再构建,而不是直接改生成文件。
## 4. OpenMausBot:从外到内怎么分
```text
用户
→ React 网页 / Electron 窗口
→ 自有 HTTP API 与实时事件
→ Node 服务:Bot、会话、群聊、权限、调度、持久化
→ 统一驱动接口
→ CLI / ACP / API 模型执行
→ 电脑、浏览器、文件、MCP、外部应用等工具
Electron 还承担桌面启动、系统桥接与本地设备能力。
云端与远程功能在核心聊天之外有额外的服务组件和部署条件。
```
| 源码区 | 职责 |
|---|---|
| [网页前端](../OpenMausBot/src/) | 主应用、界面组件、状态与请求处理 |
| [后端](../OpenMausBot/server/) | 主服务与具体业务能力 |
| [引擎适配](../OpenMausBot/server/drivers/) | 把不同 Agent 引擎统一接到应用 |
| [共享结构](../OpenMausBot/shared/) | 前后端之间的类型、规则和数据约定 |
| [桌面进程](../OpenMausBot/electron/) | 窗口、启动、更新和系统桥接 |
| [脚本](../OpenMausBot/scripts/) | 构建、控制命令与配套工具 |
[主界面装配](../OpenMausBot/src/App.tsx#L19) 直接接入单聊、群聊、活动、文件、电脑、虚拟机、插件、团队图、触发器等面板。[驱动注册](../OpenMausBot/server/drivers/builtIn.ts#L32) 显示它不是只接一个模型:Claude、Codex、多个 ACP Agent 以及 OpenAI-compatible 等模型 API 都走对应适配器。
注意:驱动是“接线转换层”,不是这些第三方引擎本身;存在适配器也不代表本机已安装引擎、已经登录或配置了有效账号。
还要把这些配套项目与核心后端分开看:
| 配套组件 | 职责与边界 |
|---|---|
| [手机伴随服务](../OpenMausBot/companion/package.json#L6) | 让已经配对的手机连接核心服务,不替代核心 Agent 执行 |
| [远程中继](../OpenMausBot/relay/src/server.ts#L15) | 分别接入 host、data、phone 的 WebSocket 连接 |
| [云主机连接器](../OpenMausBot/connector/package.json#L6) | 通过出站连接把用户自己的服务器纳入云端管理 |
| [Cloudflare 控制平面](../OpenMausBot/cloudflare/control-plane/README.md#L3) | 云账号身份、安装归属和托管连接入口;文档明确它不存放本地 Bot、聊天与 SQLite 会话数据 |
| [手机协议包](../OpenMausBot/packages/phone-protocol/) | 手机连接相关的共享协议约定 |
| [文档站](../OpenMausBot/apps/docs/) | 产品文档页面,不是聊天前端 |
## 5. 两者都要沿着这条链理解
以“让两个 Bot 一起分析文件”为例:
1. 前端收集文字、附件和目标 Bot/群聊。
2. 后端检查权限、工作目录和当前会话,接收或排队。
3. 团队模块决定消息发给谁,维护上下文和协作关系。
4. 执行引擎向模型发送输入,再调用读文件等工具。
5. 工具结果回到执行引擎,模型继续分析或给出回答。
6. 后端保存结果、更新状态,前端显示过程和产物。
DS Bot 的第 4 步主要交给 DSH;OpenMausBot 通过自己的驱动体系衔接执行。两边的界面可以长得相似,但底下的会话 ID、事件格式、权限和数据保存方式不同。
DS Bot 也支持本地 Agent,并非只能直接调用模型 API:[本地 Agent 入口](../ds-bot/ds-bot/src/host/local-agents/index.js#L1) 会发现 CLI、注册 DSH 模型适配器,并保存 DSH Session 与 CLI Session 的对应关系。这和 OpenMausBot 的自有驱动体系是两种接入方式。
DS Bot 的 JSON 保存团队状态,不代表所有数据都是 JSON:[聊天搜索索引](../ds-bot/ds-bot/src/host/chat-index.js#L48) 使用 SQLite,真正的 DSH 会话记录另由宿主管理。迁移时不能只搬团队配置文件就认为带走了全部聊天历史。
## 6. 对三省六部 v0.0.1 的直接意义
这部分是基于架构的判断,不是已经确定的实施方案。
- 如果继续在 DSH 内做部门团队,DS Bot 的宿主接入、角色配置、会话管理和消息协作与现有环境更接近。
- 如果做脱离 DSH 的独立产品,OpenMausBot 的自有前后端、驱动接口和桌面管理更值得详细研究。
- 不能把两个项目的文件夹直接拼起来就得到一个完整产品。至少要统一 Bot 身份、会话、任务、权限、事件和存储接口。
- Main Bot/管理员权限不等于三省六部的审核、退回、执行制度;现有角色系统只是基础。
- 一个 Bot 绑定文件夹,也不等于项目之间的配置、上下文、任务、模型与运行操作已经全部隔离。项目隔离仍需逐层设计和验收。
- 电脑控制、云电脑、手机、邮件和外部应用均属于能力层,不能据此推断核心聊天必须启动全部外部服务。
## 7. 详细模块手册
- [DS Bot 分层与功能模块拆解](ds-bot-analysis.md)
- [OpenMausBot 分层与功能模块拆解](openmausbot-analysis.md)
详细手册给出各模块的职责、源码入口、数据与通信链路、运行依赖,以及源码存在和本机实测之间的区别。