898898a5076e208ec8dec7b554ed67d5b8f03c93
Close three coverage gaps surfaced by the cross-Lagrange-family
audit (Lagrange V2 / LagrangeGo / acidify / lagrange-python):
- **0x210 subType 179 + 226 (NewFriend)** — mutual-accept friend
notice. 179 fires when bot sent a request and the other side
accepted; 226 fires for the opposite direction. Both decode
through the same wire shape. LagrangeGo handles the pair via a
`case 226: case 179:` fallthrough in `client/listener.go:248`.
We surface them as `kind: 'friend_add'`, which the existing
converter routes straight to OneBot `notice.friend_add` — bot
frameworks that wait for "auto-add a friend after they accept"
were previously stuck because nothing arrived.
- **0x210 subType 139 (self-recall)** — bot recalled its own
message sent to a friend. Same `FriendRecall` wire shape as 138
but the peer is on `toUid` instead of `fromUid` — acidify's
`parseFriendRecall:380` splits exactly this way. Without 139,
self-recalls disappeared and downstream `notice.friend_recall`
handlers thought the bot had never recalled anything.
- **PkgType 85 (bot self-joined a group)** — fires on the bot's
session once `set_group_add_request` is approved or an invite is
accepted, ported from lagrange-python's `server_push/msg.py:108`.
PkgType 33 (GroupMemberIncreaseNotice) only fires for *other*
members joining, so without 85 the bot never received its own
`notice.group_increase` until the first message arrived. We
decode `SelfJoinInGroup` and emit `kind: 'group_member_join'`
with `userUin = selfUin`; the existing converter picks
`sub_type: 'approve' | 'invite'` from the operator/user equality
so consumers see the standard OneBot shape.
While wiring 139, also fix a *pre-existing* prod bug spotted via
proton call-site analysis on the resulting bundle: `event-0x210.ts`
imported `FriendRecall` from both `proto/proton/notify` (as
`FriendRecallNotify`) *and* `events` (as the event interface).
Proton's import-resolver registers `importedTypeSources` keyed on
the *imported* name (last-write-wins), so the events.ts import
shadowed the proto one — `protobuf_decode<FriendRecall>(...)` lost
its codec, fell through to the runtime fallback throw, and was
silently swallowed by `MsgPushRegistry.decode`'s catch. Verified by
the substituted codec list in `dist/index.mjs`: pre-fix it had
`FriendRequest` / `GeneralGrayTipInfo` but no `FriendRecall`;
post-fix `FriendRecall` / `NewFriend` / `SelfJoinInGroup` are all
emitted as expected. Side-step the collision by importing the
proto types unaliased and re-deriving the colliding event type via
`Extract<QQEventVariant, { kind: 'friend_recall' }>`.
New proto interfaces in `proto/proton/notify.ts`:
- `NewFriend` + `NewFriendInfo` (uid/time/message/nickName fields,
fields 1-9; ported from
`LagrangeGo/.../notify.proto:25 NewFriend`)
- `SelfJoinInGroup` (groupUin / operatorUid + a few placeholder
fields; ported from
`lagrange-python/pb/status/group.py:170 PBSelfJoinInGroup`)
Regression coverage in `tests/msg-push-handler.test.ts`:
- subType 179/226 both produce identical friend_add events
- falls back to `routingHead.fromUin` when the new friend's uid
isn't in the local cache (matches LagrangeGo's
"emit-then-resolve" pattern)
- subType 138 keeps fromUid as the peer (other recalled their
own msg to us); subType 139 picks toUid (we recalled ours
sent to them)
- PkgType 85 emits group_member_join with userUin == selfUin,
operator resolved through identity when known
core: 635/635 tests pass (+7), typecheck clean. Production bundle
now contains substituted codecs for FriendRecall, NewFriend,
SelfJoinInGroup (cross-checked via `grep protobuf_decode_X` on
`dist/index.mjs`).
❄️ 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
Languages
TypeScript
98.9%
CSS
0.5%
JavaScript
0.5%