DrSmoothl 4e51b4bd7d build(sqlite): wrap better-sqlite3 with @snowluma/sqlite + vendor prebuilts
Replaces "runtime npm dependency that gets `npm install`-ed into
dist/" with "TS wrapper that loads the native `.node` from
`dist/native/` like every other native binding in the project".

Why the change
--------------
The previous approach (better-sqlite3 declared in
packages/runtime/package.json, materialized by `npm install
--omit=dev` in dist/) worked but produced an artifact that needed
runtime npm install — a step the rest of SnowLuma's native bindings
don't need (websocket / snowluma-hook / ffmpeg are all standalone
`.node` files copied into `dist/native/` by vite-plugin-cp). The
asymmetry was friction: dev mode required `pnpm dist:install`,
build artifacts carried a `dist/node_modules/` tree the other
modules didn't need, and Docker images had to special-case the
glibc-vs-musl ABI lookup that prebuild-install runs.

The new shape:
  - `@snowluma/sqlite` (packages/sqlite/) — TS wrapper. Has
    `better-sqlite3` as a devDep (for the JS-layer types + the
    actual JS wrapper code that vite inlines). At runtime, calls
    `createRequire().require()` against
    `<dist|repo>/native/better-sqlite3-v<abi>-<platform>-<arch>.node`
    and passes the resolved addon to `new Database(path, {
    nativeBinding })`.
  - `packages/runtime/native/better-sqlite3-v<abi>-<triplet>.node`
    — prebuilt binaries vendored into the repo. Two ABIs ship side-
    by-side (v127 = Node 22 LTS used by CI, v137 = Node 24 used by
    dev boxes) so `process.versions.modules` picks the matching one
    at load time.
  - `tools/fetch-sqlite-prebuilts.mjs` — fetches all 5 platforms ×
    N ABIs from WiseLibs's GitHub releases. Idempotent: existing
    `.node` files skip. Accepts extra ABI args:
    `node tools/fetch-sqlite-prebuilts.mjs 12.10.0 v127 v137 v115`.

What was unwound
----------------
- packages/runtime/package.json — dependencies removed (runtime
  artifact is now self-contained, no `npm install` step needed).
- root package.json — `dist:install` script removed (no node_modules
  to install).
- .github/workflows/dev-build.yml — `Bundle runtime dependencies`
  step removed.
- .github/workflows/release.yml — kept the `Bundle runtime
  dependencies` step (was a no-op already, but harmless safety net
  in case a future runtime dep shows up).
- packages/core/vite.config.ts — `better-sqlite3` no longer
  external; vite inlines the JS wrapper (+~33 KB to bundle, ~2.84
  MB → 2.87 MB total).

Naming
------
Mirrors the existing `websocket-${triplet}.node` convention (flat
dir under `runtime/native/`, dash-separated `<platform>-<arch>`).
Adds a `v<abi>` segment because better-sqlite3 is NOT N-API — one
binary per Node ABI. Naming:

  better-sqlite3-v127-darwin-arm64.node    Node 22 / macOS arm
  better-sqlite3-v127-darwin-x64.node      Node 22 / macOS intel
  better-sqlite3-v127-linux-arm64.node     Node 22 / Linux arm
  better-sqlite3-v127-linux-x64.node       Node 22 / Linux x64
  better-sqlite3-v127-win32-x64.node       Node 22 / Windows x64
  better-sqlite3-v137-... (5)              Node 24 / same 5 hosts

Total: 10 binaries × ~1.9 MB = ~19 MB committed. Aligned with the
existing native-vendoring footprint (websocket ~2 MB × 5, snowluma-
hook ~10 MB × Windows + Linux, ffmpeg ~10-30 MB × 4).

What changes for consumers
--------------------------
Source-side: nothing. `import Database, { type Database, type
Statement } from '@snowluma/sqlite'` is a drop-in for the previous
`import Database from 'better-sqlite3'`. The wrapper re-exports the
same types and the `Database` callable factory has the same
overload set.

Runtime: `node` finds the binding at
`<dist|repo>/native/better-sqlite3-v${process.versions.modules}-
${process.platform}-${process.arch}.node`. If the ABI doesn't
match a vendored binary, the wrapper throws a clear error pointing
at `tools/fetch-sqlite-prebuilts.mjs` with the missing ABI/triplet.

Bumped better-sqlite3 from 11.10.0 → 12.10.0 because v11 only had
prebuilt up to Node ABI v127 (no v137 = no Node 24). v12.10.0
ships both. Both versions are API-compat (the breaking changes
between v11 and v12 were either internal or in error-handling
paths SnowLuma doesn't exercise).

Verification
------------
- pnpm -r typecheck (12 projects): clean
- @snowluma/core test: 302/302
- @snowluma/onebot test: 250/250 (552/552 combined, unchanged from
  the perf-series baseline)
- Bench numbers preserved — wrapper indirection is sub-μs:
  storeMeta ~11 μs, storeEvent ~17 μs, findMeta hit ~1.1 μs (all
  within noise of the post-RoadMap-#5 measurements).
- Vite build clean, bundle = 2.87 MB / 230 KB gzip
- `dist/index.mjs` no longer contains a `node:sqlite` import (it
  did before — media-store hadn't migrated; now neither it nor
  message-store reach into the Node builtin).

Bonus side-fix: `packages/onebot/src/media-store.ts` also moved
off `node:sqlite` (caught by the post-build bundle grep — the
file was using `DatabaseSync` + `StatementSync` from the builtin
even though it had already been written to cache its prepared
statements). Its hot paths now go through the same wrapper.
2026-05-21 13:49:19 +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%