DrSmoothl
bd14b0a98e
Surface delivery failures instead of reporting success for rejected image and text cards. Reject responses without a delivery result. Fixes #611
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 连接。
账号识别由登录数据库的文件变化、进程和登录事件或手动操作触发，不做周期探测。未载入的 QQ 进程也不会持续调用 Windows Restart Manager；需要重查时可点击 WebUI 进程行的刷新/重连。
接入与文档
| 入口 | 文档 |
|---|---|
| WebSocket / HTTP | OneBot 动作参考 |
| 部署（Docker / Windows） | 部署指南 |
| 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。
使用边界与许可
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 的实现思路。