Skip to content

项目架构 ​

WeqBot 由 9 个包组成,依赖方向单一,没有环。这一页讲清每个包负责什么、为什么这么切, 以及那条靠脚本强制的架构护栏。

分层 ​

text
common  ←  wire  ←  protocol  ←  session  ←  onebot
                        ↑            ↑          ↑
                        └────────── bot ────────┘
                                     ↑
                                   node  ──→  control  ──→  common / wire

读取方式:箭头从右指向左表示「可以依赖」。bot 在中间,同时依赖 protocol、session、onebot。

包职责不负责
@weqbot/common日志、错误码、事件总线、退避、字节工具任何业务
@weqbot/wireNativePort 契约、SessionId、能力探测、宿主绑定适配网络、协议细节
@weqbot/protocolprotobuf 运行时、OIDB / trpc spec、消息编解码、推送解码会话管理
@weqbot/sessiona1 凭据、quickLogin、openSession(mode 2)、状态机、BotEvent 契约OneBot 词汇、元素编解码
@weqbot/onebotOneBot v11 事件 / 动作 / 网络适配协议细节、登录上线
@weqbot/botcreateBot() 门面,宿主与测试的唯一入口加载原生组件
@weqbot/controldesktop ↔ sidecar 控制通道契约与 NDJSON 编解码socket 实现、业务
@weqbot/node独立宿主、sidecar 入口与 CLI被其它包 import
@weqbot/webuiWebUI 前端(纯静态 SPA),只通过 HTTP 与 node 通信任何 @weqbot 运行时包

两条结构性约束 ​

1. 只有 node 能加载原生组件 ​

除 packages/node 外,任何文件出现 .node / process.dlopen / createRequire 一律失败。

这条不是风格偏好:WeQ 嵌入 WeqBot 时是纯 TS 打包,一旦某个包偷偷 require 了 .node, 宿主产物里就会出现第二份原生组件 —— 两份 .node 在同一进程里争同一个全局状态,症状是 随机崩溃,极难定位。

2. 不得依赖 @weq/* ​

WeqBot 必须能独立构建、独立发版。依赖 WeQ 的私有包会让它变成 WeQ 的附庸。

这两条 + 依赖方向都由 scripts/check-pure-ts.mjs 强制:

bash
pnpm check:pure-ts
# 架构检查通过:依赖方向正确,除 @weqbot/node 外无原生加载。

为什么用脚本而不是 linter 规则:分层规则要读「当前文件属于哪个包」,linter 的规则是路径 glob,写出来会是一串重复配置,改结构时容易漏。脚本只有一张 LAYERS 表。

js
const LAYERS = {
  common: [],
  wire: ['common'],
  protocol: ['common', 'wire'],
  session: ['common', 'wire', 'protocol'],
  onebot: ['common', 'protocol', 'session'],
  bot: ['common', 'wire', 'protocol', 'session', 'onebot'],
  control: ['common', 'wire'],
  node: ['common', 'wire', 'protocol', 'session', 'onebot', 'bot', 'control'],
  webui: [],
};

为什么 control 只依赖 common / wire ​

@weqbot/control 会被同时打进 WeQ 和 sidecar。它只承载线上协议(信封类型 + NDJSON 编解码)和 DeviceProfile 这一类共享形状,不含 socket 实现、不含 supervisor、不含事件语义。

socket 实现分居两侧:sidecar 侧在 @weqbot/node,宿主侧在 WeQ desktop。事件语义在 @weqbot/bot 的 BotEventMap 里定义,control 只固定通道上的名字。

运行时组装顺序 ​

createBot() 的组装顺序是刻意固定的 —— 每一步失败后的动作不同:

text
native 能力探测 → 预检 → 取 a1 → quickLogin → openSession(mode 2) → 挂 sink → 在线

本层只和 sessionId 打交道,不接触 pid。宿主把 native 端口递进来:

宿主传什么
WeQ desktopadaptNativeBinding(platform.native.ntHelper) —— 注意 NativeBundle 不是扁平 binding
独立进程packages/node/src/loader.ts 加载的 nt_helper.node

两条 sink 都在这里接:

  • 推送 sink:推送帧 → @weqbot/protocol/push 解码 → PushBridge → BotEvent;
  • 状态 sink:状态事件 → 状态机(kicked 终止;closed 按网络掉线走退避重登)。

消息只来自推送 ​

bot 不读本地数据库。消息全部来自服务端推送,没有「拉历史补洞」这条路。

这条决定了三件事:

  1. 本地不落任何消息 / 媒体数据(红线 13);
  2. 离线期间的消息不会补投(重连后只有新消息);
  3. 历史查询类 OneBot action 依赖进程内观测(MessageStore 的有界内存表), 不落盘、不建索引。

读下去 ​

版本未定(0.0.0 是占位);文档与代码同步演进,以主仓为准