SnowLuma 是面向 QQ 客户端的 TypeScript 互操作运行时，将 QQ 原生会话转换为 OneBot v11 动作与事件，并通过 WebSocket、HTTP、WebUI、SDK 和 MCP 提供统一入口。
Caution
SnowLuma 是独立的第三方项目，与腾讯 / QQ 无隶属或授权关系。项目仅供学习与技术研究，请遵守《QQ 用户协议》及适用法律；软件按“现状”提供，使用风险自负。详见
EULA.md。Disclaimer: SnowLuma is independent of Tencent / QQ and is provided for study and research only, “as is” and without warranty.
核心能力
| 场景 | 能力 |
|---|---|
| OneBot 接入 | OneBot v11 动作与事件；WebSocket 服务端 / 客户端及 HTTP 服务端 / 上报 |
| 消息与媒体 | 文本、图片、语音、视频、文件、回复、提及、转发及常见卡片 |
| 多账号运行 | 各账号独立维护会话、身份映射、消息存储和网络配置 |
| WebUI 管理 | 账号状态、实时日志、连接配置、动作调试和存储管理 |
| 开发者工具 | @snowluma/sdk 与 @snowluma/mcp |
运行链路
会话接入、协议解析、身份映射、OneBot 转换和网络适配保持独立边界；多个 QQ 账号可并行运行。
快速开始
-
从 Releases 下载对应平台的完整发行包并解压。Lite 版需 Node.js 24+。
-
Windows 运行
launcher.bat；Linux 执行：chmod +x launcher.sh ./launcher.sh -
打开
http://localhost:5099，使用启动日志中的初始密码登录 WebUI，按引导接入 QQ 进程并配置 OneBot 连接。
在「设置 → 关于 → 软件更新」下载新版本，再点「重启更新」。文件优先暂存于系统临时目录，不可用时使用安装目录的 tmp/update，下次启动时替换并清理，配置、日志与消息数据保留。更新沿用当前 Node.js；容器部署请更新镜像。
接入与文档
| 入口 | 文档 |
|---|---|
| WebSocket / HTTP | OneBot 动作参考 |
| TypeScript SDK | packages/sdk/README.md |
| MCP | packages/mcp/README.md |
JSON 消息段接受标准的 data.data 字符串，也兼容 data.data 非数组对象和 { type: "json", data: "..." } 简写；data 必填，最终内容必须是 JSON 对象。
开发
需要 Node.js 24+ 与 pnpm 11.25.0，日常开发基于 dev 分支：
git clone https://github.com/SnowLuma/SnowLuma.git
cd SnowLuma
git checkout dev
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
贡献流程见 CONTRIBUTING.md；模块边界与项目词汇见 CONTEXT.md；开发方向见 RoadMap.md。
引用消息预览
OneBot 发送 reply 段时，会将本地消息缓存中的原文附入 QQ 引用预览，保留文字、换行与引用关系。图片、语音等非文字段以类型提示显示，不重新上传媒体；原消息中的嵌套引用不递归展开。只有消息元数据而没有缓存正文时，不生成虚构的预览内容。
媒体读取与归档
get_msg 逐个尝试刷新图片、语音和视频的下载地址：获取到新地址就用于本次响应，刷新失败或缺少资源元数据时保留该段原地址，并继续处理其他资源。原地址为空时仍保持为空，单个资源失败不影响整条消息返回。地址更新时同步响应中的 raw_message，不改写保存的消息；保留的旧地址仍可能已经过期。
get_record 单独向 QQ 获取语音的当前下载地址，资源元数据缺失或远端获取失败时动作返回错误，不使用旧地址或发送时的本地文件兜底。历史记录若没有保存资源引用，无法仅凭文件名恢复下载地址。
SnowLuma 不为这些查询长期保存媒体文件或 Base64 内容，本地保留的是消息及资源元数据；上传、转码仍会使用临时文件。下载地址和 QQ 远端资源都有可用性限制，需要长期归档的消费端应及时下载并自行保存。
使用边界与许可
Important
SnowLuma 使用源码可见非商业许可，不是 OSI 开源许可。源码可用于查看、学习、非商业自托管及私下修改；商业使用，以及公开发布修改版或衍生版，均需事先取得书面授权。
完整条款见 LICENSE；二进制发行包另受 EULA.md 与 PRIVACY.md 约束；商业授权请联系 motricseven@foxmail.com。随附的原生附加组件为专有组件，不在源码许可范围内。
SnowLuma is source-available for study and non-commercial self-hosting, but it is not OSI open source. Commercial use and public distribution of modified or derivative versions require prior written permission.
社区与鸣谢
项目参考了 LagrangeV2 的协议定义与 NapCatQQ 的实现思路。