TomyJan/SnowLuma

项目介绍

SnowLuma 是一个 TypeScript 互操作运行时，把 QQ 客户端的原生会话转换为 OneBot v11 动作与事件。它通过 WebSocket 服务端/客户端、HTTP 服务端/上报、WebUI、TypeScript SDK 和 MCP 包对外提供统一入口，适合已经使用 QQ、希望用标准协议而非逐个对接客户端回调的机器人开发者。

运行时把会话接入、协议解析、身份映射、OneBot 转换和网络适配划分成独立边界，因此多个 QQ 账号可以并行运行，各自维护会话、身份映射、消息存储和网络配置。消息能力覆盖文本、图片、语音、视频、文件、回复、提及、转发和常见卡片。WebUI 提供账号状态、实时日志、连接配置、动作调试和存储管理。

快速使用

1. 从 SnowLuma Releases 下载对应平台的完整发行包并解压。Lite 版要求 Node.js 24 及以上。

2. Windows 上运行 launcher.bat；Linux 上先给脚本加执行权限再启动：

   chmod +x launcher.sh
   ./launcher.sh
   

3. 在浏览器打开 本地 WebUI 的 http://localhost:5099，用启动日志中的初始密码登录，再按引导接入 QQ 进程并配置 OneBot 连接。

账号识别依靠登录数据库文件变化、进程与登录事件或手动操作，不做周期探测；如果进程没有被载入，可在 WebUI 的进程行刷新或重连。Docker 与 Windows 的部署方式见部署指南，OneBot 动作细节见动作参考。

使用约束

SnowLuma 是独立的第三方项目，与腾讯 / QQ 没有隶属或授权关系，项目定位为学习与技术研究，使用者需自行遵守 QQ 用户协议和适用法律。许可证为源码可见而非 OSI 开源：允许查看、学习、非商业自托管和私下修改，商业使用以及公开发布修改版或衍生版需事先获得书面授权。详见 LICENSE 与 EULA。随附的原生附加组件为专有组件，不在源码许可范围内。发行包面向 Windows x64 与 Linux x64/arm64。

开发

开发需要 Node.js 24+ 与 pnpm 11.25.0，基于 dev 分支；仓库给出了克隆、安装、类型检查和测试的流程，贡献流程与模块边界可参考 CONTRIBUTING.md 和 CONTEXT.md。SDK 与 MCP 的接入说明分别见 SDK 和 MCP 包内文档。

HotRepo 点评

SnowLuma 在 2026-11-10 的 HotRepo 新项目榜（TypeScript 榜）中出现，同一统计窗口内新增 109 个 Star 和 285 个 Fork。对一个协议桥接运行时来说，Fork 数明显高于 Star 数值得注意，但单次快照无法判断趋势或解释原因；该仓库目前没有全部语言日榜名次记录，因此它在更大范围日榜上的位置尚不可知。