DrSmoothl 6bf53890dc refactor(api): move contacts methods to ContactsApi (#6 commit 2/13)
Second of 13 commits decomposing Bridge. Moves the six "fetch the
roster / a profile / outstanding requests / download rkeys" methods
off Bridge and onto a new `apis.contacts.*`.

Methods moved
-------------
* fetchFriendList       — OIDB 0xfd4_1 + identity.rememberFriends
* fetchGroupList        — OIDB 0xfe5_2 + identity.rememberGroups
* fetchGroupMemberList  — OIDB 0xfe7_3 + identity.rememberGroupMembers
                          (includes the 60s TTL + per-group inflight
                          coalesce cache that prevents Tencent
                          risk-control from triggering)
* fetchUserProfile      — OIDB 0xfe1_2 + identity.rememberUserProfile
* fetchGroupRequests    — OIDB 0x10c0_{1,2}
* fetchDownloadRKeys    — OIDB 0x9067_202

Cache fields moved
------------------
The two member-list throttle maps (`memberListInflight_`,
`memberListLastFetch_`) move from Bridge to `ContactsApi` as private
fields. Same TTL, same semantics — just owned by the Api class that
exposes the method.

Constructor ordering
--------------------
`buildApiHub(this)` now runs BEFORE `identity.setFetcher(...)` in the
Bridge constructor because the `fetchProfile` / `fetchGroupMemberList`
callbacks installed there reach into `this.apis.contacts.*`. With
eager construction this is safe; the alternative (pass a thunk that
forwards once apis is built) was strictly worse for readability.

bridge-contacts.ts removed
--------------------------
The file existed solely as the previous module-function delegate
target; ContactsApi inlines every function body so there's nothing
left to keep.

Caller-site updates
-------------------
* `bridge/actions/friend.ts` — `bridge.fetchFriendList()` →
  `bridge.apis.contacts.fetchFriendList()`.
* `onebot/manager.ts`, `onebot/instance-rkey.ts`,
  `onebot/modules/contact-actions.ts`, `modules/request-actions.ts`,
  `actions/extended.ts` — same shape rewrite (6 method names).

Test plumbing
-------------
* `tests/actions/_helpers.ts` — `mockApiHub()` grows a `contacts`
  field built by `mockContactsApi()`.
* `tests/bridge-member-identity.test.ts::RefreshingBridge` — was
  `override async fetchGroupMemberList()`. After the move the method
  lives on `this.apis.contacts`, not `this`. Switched to patching the
  method on the constructed ContactsApi instance directly.
* `tests/actions/friend.test.ts` — `bridge.fetchFriendList` →
  `bridge.apis.contacts.fetchFriendList`; the "refresh throws" branch
  overrides via `bridge.apis.contacts.fetchFriendList = vi.fn(…)`.
* `tests/onebot/contact-actions.test.ts`, `extended-actions.test.ts`,
  `request-actions.test.ts` — local `fakeBridge` helpers gained an
  auto-promotion shim that rewrites flat method stubs (the pre-#6
  test API) into the new `apis.<area>.method` shape. Keeps existing
  test setup readable while the production code uses the new path.

Tests: 587/587 pass (same baseline; pre-existing network-manager
native-addon failure unchanged).
2026-05-20 22:27:32 +08:00
2026-05-03 14:02:29 +08:00

❄️ SnowLuma

Next Remote Protocol Framework.

Release Build @snowluma/sdk @snowluma/ui Stars

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 提交过代码的伙伴。

Contributors

Star 趋势

Star History Chart

社区

S
Description
No description provided
Readme
64 MiB
Languages
TypeScript 98.9%
CSS 0.5%
JavaScript 0.5%