From 360fe8bd49266d0f8b246f0f33ac9c9f299074dd Mon Sep 17 00:00:00 2001 From: DrSmoothl <1787882683@qq.com> Date: Sun, 17 May 2026 23:47:12 +0800 Subject: [PATCH 1/3] fix(forward): carry image/video in private merged forward MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit For a private send_private_forward_msg, the inner image/record/video needs an OIDB upload scene — but uploadForwardNodes never received the recipient, so the SendContext fell back to {bridge} only and the element builder threw "private image target uid is missing". Plumb userId through uploadForwardNodes → buildForwardPushBody and, when the nodes contain media, resolve it to a uid via bridge.resolveUserUid() once up-front. Group forwards are unchanged (they already passed groupId). Mirrors NapCat's design where the destination peer is threaded all the way down to createSendElements. --- packages/core/src/bridge/actions/forward.ts | 33 +++++++++++++++++-- packages/core/src/bridge/bridge-interface.ts | 2 +- packages/core/src/bridge/bridge.ts | 2 +- .../src/onebot/modules/message-actions.ts | 5 ++- 4 files changed, 36 insertions(+), 6 deletions(-) diff --git a/packages/core/src/bridge/actions/forward.ts b/packages/core/src/bridge/actions/forward.ts index 6558c4b7..9ade79e2 100644 --- a/packages/core/src/bridge/actions/forward.ts +++ b/packages/core/src/bridge/actions/forward.ts @@ -29,14 +29,21 @@ async function buildForwardPushBody( bridge: Bridge, node: ForwardNodePayload, groupId?: number, + userUid?: string, ): Promise> { const fromUin = node.userUin > 0 ? node.userUin : toInt(bridge.identity.uin); if (fromUin <= 0) throw new Error('forward node user uin is invalid'); const nickname = node.nickname.trim() || String(fromUin); + // image/record/video upload inside a forward node must be scoped to the + // forward's recipient: group → groupId, private → recipient uid. + // Without this the OIDB upload (0x11c4/0x11c5) has no scene and the + // element builder throws "private image target uid is missing". const sendCtx = groupId !== undefined ? { bridge, groupId } - : { bridge }; + : userUid + ? { bridge, userUid } + : { bridge }; const elems = await buildSendElems(node.elements, sendCtx); const now = Math.floor(Date.now() / 1000); const random = Math.floor(Math.random() * 0x7fffffff) >>> 0; @@ -66,12 +73,32 @@ async function buildForwardPushBody( }; } -export async function uploadForwardNodes(bridge: Bridge, nodes: ForwardNodePayload[], groupId?: number): Promise { +export async function uploadForwardNodes( + bridge: Bridge, + nodes: ForwardNodePayload[], + groupId?: number, + userId?: number, +): Promise { if (!Array.isArray(nodes) || nodes.length === 0) { throw new Error('forward nodes are required'); } - const msgBody = await Promise.all(nodes.map(node => buildForwardPushBody(bridge, node, groupId))); + // For a private forward to `userId`, any image/record/video inside a node + // needs the recipient's uid as upload scene. Resolve it once up-front, + // and only when at least one node actually contains media (saves an RPC + // for text-only forwards). + let userUid: string | undefined; + if (groupId === undefined && userId !== undefined && userId > 0) { + const hasMedia = nodes.some(node => node.elements.some( + e => e.type === 'image' || e.type === 'record' || e.type === 'video', + )); + if (hasMedia) { + const resolved = await bridge.resolveUserUid(userId); + if (resolved) userUid = resolved; + } + } + + const msgBody = await Promise.all(nodes.map(node => buildForwardPushBody(bridge, node, groupId, userUid))); const longMsgResult = protoEncode({ action: [ { diff --git a/packages/core/src/bridge/bridge-interface.ts b/packages/core/src/bridge/bridge-interface.ts index a459b8f8..1a73fa31 100644 --- a/packages/core/src/bridge/bridge-interface.ts +++ b/packages/core/src/bridge/bridge-interface.ts @@ -92,7 +92,7 @@ export interface BridgeInterface { fetchGroupFileCount(groupId: number): Promise<{ fileCount: number; maxCount: number }>; // ─── Forward ─── - uploadForwardNodes(nodes: ForwardNodePayload[], groupId?: number): Promise; + uploadForwardNodes(nodes: ForwardNodePayload[], groupId?: number, userId?: number): Promise; fetchForwardNodes(resId: string): Promise; // ─── Message ops ─── diff --git a/packages/core/src/bridge/bridge.ts b/packages/core/src/bridge/bridge.ts index acdbcc1f..a3a64ebb 100644 --- a/packages/core/src/bridge/bridge.ts +++ b/packages/core/src/bridge/bridge.ts @@ -454,7 +454,7 @@ export class Bridge implements BridgeInterface { async fetchPrivatePttUrlByNode(node: MediaIndexNode): Promise { return fetchPrivatePttUrlByNode_(this, node); } async fetchGroupVideoUrlByNode(groupId: number, node: MediaIndexNode): Promise { return fetchGroupVideoUrlByNode_(this, groupId, node); } async fetchPrivateVideoUrlByNode(node: MediaIndexNode): Promise { return fetchPrivateVideoUrlByNode_(this, node); } - async uploadForwardNodes(nodes: ForwardNodePayload[], groupId?: number): Promise { return uploadForwardNodes_(this, nodes, groupId); } + async uploadForwardNodes(nodes: ForwardNodePayload[], groupId?: number, userId?: number): Promise { return uploadForwardNodes_(this, nodes, groupId, userId); } async fetchForwardNodes(resId: string): Promise { return fetchForwardNodes_(this, resId); } async deleteGroupFile(groupId: number, fileId: string): Promise { return deleteGroupFile_(this, groupId, fileId); } async moveGroupFile(groupId: number, fileId: string, parentDirectory: string, targetDirectory: string): Promise { return moveGroupFile_(this, groupId, fileId, parentDirectory, targetDirectory); } diff --git a/packages/core/src/onebot/modules/message-actions.ts b/packages/core/src/onebot/modules/message-actions.ts index 5a847f9c..ffee4639 100644 --- a/packages/core/src/onebot/modules/message-actions.ts +++ b/packages/core/src/onebot/modules/message-actions.ts @@ -241,7 +241,10 @@ export async function sendPrivateForwardMessage( meta?: ForwardPreviewMeta, ): Promise<{ messageId: number; forwardId: string }> { const nodes = await parseForwardNodes(ref, messages); - const forwardId = await ref.bridge.uploadForwardNodes(nodes); + // userId is plumbed through so inner image/record/video can be uploaded + // under the recipient's scene (otherwise the OIDB private-image upload + // has no target uid and the element builder bails). + const forwardId = await ref.bridge.uploadForwardNodes(nodes, undefined, userId); const previewElement = buildForwardPreviewElement(forwardId, nodes, false, meta); const receipt = await ref.bridge.sendPrivateMessage(userId, [previewElement]); const messageId = hashMessageIdInt32(receipt.sequence, userId, PRIVATE_MESSAGE_EVENT); From 82b52a3b2d5c737fcce7d14616f359ade3cf1af8 Mon Sep 17 00:00:00 2001 From: DrSmoothl <1787882683@qq.com> Date: Mon, 18 May 2026 00:10:12 +0800 Subject: [PATCH 2/3] update README --- README.md | 132 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 120 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index d28a6cd0..739c313b 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,130 @@ -# ❄️ SnowLuma -> Next Remote Protocol Framework. +

❄️ SnowLuma

+

+ Next Remote Protocol Framework. +

-## 关于项目 -项目处于开发初期,仅支持部分功能,高速迭代中,随时可能出现破坏性更新。 +

+ Release + Build + @snowluma/sdk + @snowluma/ui + Stars +

+ +

+ Releases · + Issues · + QQ 群 · + Telegram +

+ +--- + +## 简介 + +SnowLuma 在 QQ 客户端与生态侧之间承担协议转换工作,向上以 [OneBot v11](https://github.com/botuniverse/onebot-11) 标准协议暴露能力。Bridge 层负责会话与事件枢纽,再通过 WebSocket / HTTP / WebUI 等多种适配器对外提供接入。 + +项目持续迭代中,稳定版本通过 [Releases](https://github.com/SnowLuma/SnowLuma/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,跨重启可用。 + +## 快速开始 + +下载预构建发布包: + +```bash +# 从 Releases 下载 zip,解压到任意目录 +./launcher.bat # Windows +``` + +或从源码开发: + +```bash +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`](packages/core) | 核心:协议层 / Bridge / OneBot / WebUI 全部在此。 | +| [`@snowluma/sdk`](packages/sdk) | OneBot HTTP & WebSocket TypeScript SDK,发布到 npm。 | +| [`@snowluma/ui`](packages/ui) | Tailwind 4 共享组件库(shadcn 风格),发布到 npm。 | +| [`@snowluma/websocket`](packages/websocket) | OneBot WebSocket 适配器底层。 | +| [`@snowluma/runtime`](packages/runtime) | 运行时清单与发布包资源。 | +| [`webui`](packages/webui) | Web 管理面板前端。 | + +## 架构 + +```mermaid +flowchart TD + A([QQ 客户端]) + B["协议层
packet pipeline · cmd 分派"] + C["Bridge 层
会话调度 · 花名册缓存 · 消息发送"] + D["OneBot 层
Event Converter · Action Handler"] + E([WS / HTTP / WebUI]) + + A --> B --> C --> D --> E +``` + +## 文档 + +- [路线图](RoadMap.md) +- [贡献指南](CONTRIBUTING.md) +- [行为准则](CODE_OF_CONDUCT.md) + +## 开发命令 + +```bash +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](https://github.com/LagrangeDev/LagrangeV2) - Proto -[NapCatQQ](https://github.com/NapNeko/NapCatQQ) - Scaner/Packet +- [LagrangeV2](https://github.com/LagrangeDev/LagrangeV2) —— Proto 定义参考。 +- [NapCatQQ](https://github.com/NapNeko/NapCatQQ) —— Scanner 与 Packet 处理实现参考。 -## 辅助编程 +## 贡献者 -推荐 Opus4.6 + Gemini3.1pro 对本项目辅助开发 +感谢每一位为 SnowLuma 提交过代码的伙伴。 -本项目大量使用Ai技术。 + + Contributors + -## 加入我们 -[SnowLuma-QQ](https://qm.qq.com/q/g3UMLpWALe) +## Star 趋势 -[SnowLuma-TG](https://t.me/napcatqq) \ No newline at end of file + + + + + Star History Chart + + + +## 社区 + +- QQ 群:[SnowLuma-QQ](https://qm.qq.com/q/g3UMLpWALe) +- Telegram:[SnowLuma-TG](https://t.me/napcatqq) +- 问题反馈:[GitHub Issues](https://github.com/SnowLuma/SnowLuma/issues) From c6f4d5c5a277bc82329da4b14c120ae91c3680b5 Mon Sep 17 00:00:00 2001 From: DrSmoothl <1787882683@qq.com> Date: Mon, 18 May 2026 00:10:43 +0800 Subject: [PATCH 3/3] chore(release): v1.8.3 --- package.json | 2 +- packages/core/package.json | 2 +- packages/runtime/package.json | 2 +- packages/sdk/package.json | 2 +- packages/ui/package.json | 2 +- packages/websocket/package.json | 2 +- packages/webui/package.json | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/package.json b/package.json index 3de5e909..49acb6e9 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "snowluma-monorepo", - "version": "1.8.2", + "version": "1.8.3", "description": "SnowLuma monorepo workspace (pnpm)", "private": true, "type": "module", diff --git a/packages/core/package.json b/packages/core/package.json index 858d38b5..dcfbb1bb 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -1,6 +1,6 @@ { "name": "@snowluma/core", - "version": "1.8.2", + "version": "1.8.3", "description": "SnowLuma core - NTQQ packet sniffer with Node.js native addon", "private": true, "type": "module", diff --git a/packages/runtime/package.json b/packages/runtime/package.json index aed52074..08f97c34 100644 --- a/packages/runtime/package.json +++ b/packages/runtime/package.json @@ -1,6 +1,6 @@ { "name": "@snowluma/runtime", - "version": "1.8.2", + "version": "1.8.3", "private": true, "type": "module", "main": "index.mjs", diff --git a/packages/sdk/package.json b/packages/sdk/package.json index 0cbb085e..238c3dcd 100644 --- a/packages/sdk/package.json +++ b/packages/sdk/package.json @@ -4,7 +4,7 @@ "name": "MotricSeven", "email": "motricseven@gmail.com" }, - "version": "1.8.2", + "version": "1.8.3", "description": "TypeScript SDK for SnowLuma OneBot HTTP and WebSocket transports", "keywords": [ "snowluma", diff --git a/packages/ui/package.json b/packages/ui/package.json index 5a0a7d4b..7baf9f05 100644 --- a/packages/ui/package.json +++ b/packages/ui/package.json @@ -4,7 +4,7 @@ "name": "MotricSeven", "email": "motricseven@gmail.com" }, - "version": "1.8.2", + "version": "1.8.3", "description": "Shared SnowLuma UI primitives — Tailwind 4 theme tokens + shadcn-style atomic components", "keywords": [ "snowluma", diff --git a/packages/websocket/package.json b/packages/websocket/package.json index cd32d250..3245ccc5 100644 --- a/packages/websocket/package.json +++ b/packages/websocket/package.json @@ -1,6 +1,6 @@ { "name": "@snowluma/websocket", - "version": "1.8.2", + "version": "1.8.3", "private": true, "type": "module", "main": "./src/index.ts", diff --git a/packages/webui/package.json b/packages/webui/package.json index 086dd109..b5352ec2 100644 --- a/packages/webui/package.json +++ b/packages/webui/package.json @@ -1,7 +1,7 @@ { "name": "webui", "private": true, - "version": "1.8.2", + "version": "1.8.3", "type": "module", "scripts": { "dev": "vite",