DrSmoothl
3e5dca1bd4
First of 13 commits decomposing the Bridge god-object into typed Api
classes following NapCat's `ctx.apis.XxxApi.method()` pattern. This
commit lays the foundation (BridgeContext, ApiHub, eager construction)
plus moves the message-send/recall/mark-read methods onto MessageApi.
Subsequent commits will move the other 12 areas (group admin, files,
profile, …) similarly.
Architecture
------------
* `bridge-context.ts` — new interface, the surface Api classes see.
Carries identity / events / apis / sendRawPacket / resolveUserUid /
next{Message,Client}Sequence helpers / upload meta cache. Replaces
the previous `BridgeInterface` for Api-class consumption (the
legacy interface still exists, just slimmed; full removal happens
in commit 13).
* `apis/index.ts` — `ApiHub` interface + `buildApiHub(ctx)` factory.
Each commit grows `ApiHub` by one entry; today only `message` is
populated.
* `apis/message.ts` — `MessageApi` with seven methods inlined from
the previous Bridge implementation:
sendGroup ← Bridge.sendGroupMessage
sendPrivate ← Bridge.sendPrivateMessage
sendC2cFile ← Bridge.sendC2cFileMessage
recallGroup ← actions/group-message.ts::recallGroupMessage
recallPrivate ← actions/group-message.ts::recallPrivateMessage
markGroupRead ← actions/group-message.ts::markGroupMessageRead
markPrivateRead ← actions/group-message.ts::markPrivateMessageRead
(Names trimmed: the `apis.message` prefix already signals the
context, so `apis.message.sendGroupMessage` would be redundant.)
Bridge changes
--------------
* Removed the 7 methods listed above (moved to MessageApi).
* Removed unused imports + `SEND_MSG_CMD` constant + `buildSendElems`
+ `protobuf_encode/decode` (now used only inside MessageApi).
* Added `readonly apis: ApiHub` field, built eagerly in constructor.
* Promoted `nextMessageRandom` / `nextClientSequence` from private →
public (Api classes need them to build SendMessageRequest packets).
* `BridgeInterface` now also lists `apis: ApiHub` + the two
generators; the 7 deleted method signatures are gone.
Caller-site updates (~9 files)
------------------------------
* `bridge/actions/group-file.ts` — `bridge.sendC2cFileMessage(...)`
→ `bridge.apis.message.sendC2cFile(...)`.
* `onebot/instance-context.ts` — markGroupMsgAsRead / markPrivateMsgAsRead
bindings now route through `apis.message.markGroup/PrivateRead`.
* `onebot/modules/message-actions.ts` — every send/recall site
rerouted; `typeof ref.bridge.sendXxx` type refs also updated.
* `onebot/actions/extended.ts` — same.
Tests (~5 files)
----------------
* `tests/actions/_helpers.ts` — `mockBridge()` grows an `apis` field
built by `mockApiHub()`; the previous flat `sendGroupMessage` etc.
vi.fn stubs are replaced with `mockMessageApi()`.
* All test files using direct `bridge.sendXxx` / `bridge.recallXxx` /
`bridge.markXxxAsRead` calls or stubs updated to `bridge.apis.message.*`.
* No behaviour changes — 587/587 pass (same baseline; pre-existing
network-manager native-addon failure unchanged).
❄️ SnowLuma
Next Remote Protocol Framework.
Releases · Issues · QQ 群 · Telegram
简介
SnowLuma 在 QQ 客户端与生态侧之间承担协议转换工作，向上以 OneBot v11 标准协议暴露能力。Bridge 层负责会话与事件枢纽，再通过 WebSocket / HTTP / WebUI 等多种适配器对外提供接入。
项目持续迭代中，稳定版本通过 Releases 发布。
特性
- OneBot v11 兼容 —— 涵盖文本、图片、视频、语音、合并转发、戳一戳、Markdown、JSON、XML 等常用消息段。
- 多账号并行 —— 同一进程可同时托管多个 QQ 账号，会话彼此独立。
- 多种适配器 —— WebSocket Server / WebSocket Client / HTTP Server / HTTP Post，HTTP 服务端同时支持
application/json与application/x-www-form-urlencoded。 - WebUI 管理面板 —— 浏览器登录、密码强度校验、登录限流、SSE 实时日志、配置热更新。
- TypeScript 全链路 —— Bridge / OneBot / SDK / UI 均使用 TypeScript，发布到 npm 的
@snowluma/sdk与@snowluma/ui可直接供下游应用消费。 - 数据持久化 —— 好友、群、群成员等关系数据落 SQLite，跨重启可用。
快速开始
下载预构建发布包：
# 从 Releases 下载 zip，解压到任意目录
./launcher.bat # Windows
或从源码开发：
git clone https://github.com/SnowLuma/SnowLuma.git
cd SnowLuma
pnpm install
pnpm build
pnpm start
WebUI 默认监听 5099 端口。首次启动会在控制台打印 initial credentials: user=admin password=<...>，登录后请立即修改。
若未完成首次改密就关闭进程，下次启动会自动重新生成一个新的随机密码。
工作区
本仓库使用 pnpm monorepo 管理，各包职责如下：
| 包 | 说明 |
|---|---|
@snowluma/core |
核心：协议层 / Bridge / OneBot / WebUI 全部在此。 |
@snowluma/sdk |
OneBot HTTP & WebSocket TypeScript SDK，发布到 npm。 |
@snowluma/ui |
Tailwind 4 共享组件库（shadcn 风格），发布到 npm。 |
@snowluma/websocket |
OneBot WebSocket 适配器底层。 |
@snowluma/proton |
编译期 protobuf 编/解码器生成器：TS interface 标注 pb<N, T>，Vite 插件在构建时把 protobuf_encode<T> / protobuf_decode<T> 替换为内联 codec，零运行时反射。 |
@snowluma/runtime |
运行时清单与发布包资源。 |
webui |
Web 管理面板前端。 |
架构
flowchart TD
A([QQ 客户端])
B["协议层<br/><sub>packet pipeline · cmd 分派</sub>"]
C["Bridge 层<br/><sub>会话调度 · 花名册缓存 · 消息发送</sub>"]
D["OneBot 层<br/><sub>Event Converter · Action Handler</sub>"]
E([WS / HTTP / WebUI])
A --> B --> C --> D --> E
文档
开发命令
pnpm dev # 启动 core dev server
pnpm dev:web # 启动 webui dev server
pnpm test # 运行 core 测试
pnpm typecheck # 全仓库 type check
pnpm build:all # 构建 core + sdk + webui
鸣谢
- LagrangeV2 —— Proto 定义参考。
- NapCatQQ —— Scanner 与 Packet 处理实现参考。
贡献者
感谢每一位为 SnowLuma 提交过代码的伙伴。
Star 趋势
社区
- QQ 群：SnowLuma-QQ
- Telegram：SnowLuma-TG
- 问题反馈：GitHub Issues