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.
+
-## 关于项目
-项目处于开发初期,仅支持部分功能,高速迭代中,随时可能出现破坏性更新。
+
+
+
+
+
+
+
+
+
+ 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技术。
+
+
+
-## 加入我们
-[SnowLuma-QQ](https://qm.qq.com/q/g3UMLpWALe)
+## Star 趋势
-[SnowLuma-TG](https://t.me/napcatqq)
\ No newline at end of file
+
+
+
+
+
+
+
+
+## 社区
+
+- QQ 群:[SnowLuma-QQ](https://qm.qq.com/q/g3UMLpWALe)
+- Telegram:[SnowLuma-TG](https://t.me/napcatqq)
+- 问题反馈:[GitHub Issues](https://github.com/SnowLuma/SnowLuma/issues)
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 9c52bf0b..c6932a99 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/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);
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",