Compare commits

...

5 Commits

Author SHA1 Message Date
手瓜一十雪
68deb48811 chore(release): v2.0.1 2026-10-18 19:02:31 +08:00
手瓜一十雪
bdf224cbc9 fix(protocol): preserve nested XML forward lookup keys 2026-10-18 18:59:22 +08:00
snowluma-bot[bot]
a69ec6fedb chore(native): replace native artifacts (native-de06ed1) (#544)
Build: https://github.com/SnowLuma/SnowLumaNative/releases/tag/native-de06ed1

Co-authored-by: snowluma-bot[bot] <283088347+snowluma-bot[bot]@users.noreply.github.com>
2026-10-18 18:56:51 +08:00
晚晴
39d1f40583 docs: point action reference at the published docs site (#540)
docs/onebot-actions.md is referenced twice but does not exist in the repository, so both "动作参考" links in the README resolve to 404s. The OneBot action reference is published on the docs site, kept in sync from collectActionDocs() via the sync-docs-catalog workflow, so link there instead. Also add a deploy row pointing at the Docker/Windows guide, which the README had no entry for.

Co-authored-by: zhngzhu <215231231+zhngzhu@users.noreply.github.com>
2026-10-18 18:54:56 +08:00
手瓜一十雪
0cdb389831 [merge] docs: remove reply and media explanations 2026-10-18 14:24:33 +08:00
25 changed files with 266 additions and 30 deletions

View File

@@ -12,7 +12,7 @@
<p align="center">
<a href="#快速开始">快速开始</a> ·
<a href="./docs/onebot-actions.md">动作参考</a> ·
<a href="https://snowluma.github.io/zh/docs/api">动作参考</a> ·
<a href="https://github.com/SnowLuma/SnowLuma/issues">问题反馈</a>
</p>
@@ -60,7 +60,8 @@ SnowLuma 是面向 QQ 客户端的 TypeScript 互操作运行时,将 QQ 原生
| 入口 | 文档 |
| --- | --- |
| WebSocket / HTTP | [OneBot 动作参考](docs/onebot-actions.md) |
| WebSocket / HTTP | [OneBot 动作参考](https://snowluma.github.io/zh/docs/api) |
| 部署(Docker / Windows) | [部署指南](https://snowluma.github.io/zh/docs/guide/deploy) |
| TypeScript SDK | [`packages/sdk/README.md`](packages/sdk/README.md) |
| MCP | [`packages/mcp/README.md`](packages/mcp/README.md) |
@@ -81,18 +82,6 @@ pnpm test
贡献流程见 [`CONTRIBUTING.md`](CONTRIBUTING.md);模块边界与项目词汇见 [`CONTEXT.md`](CONTEXT.md);开发方向见 [`RoadMap.md`](RoadMap.md)。
## 引用消息预览
OneBot 发送 `reply` 段时,会将本地消息缓存中的原文附入 QQ 引用预览,保留文字、换行与引用关系。图片、语音等非文字段以类型提示显示,不重新上传媒体;原消息中的嵌套引用不递归展开。只有消息元数据而没有缓存正文时,不生成虚构的预览内容。
## 媒体读取与归档
`get_msg` 逐个尝试刷新图片、语音和视频的下载地址:获取到新地址就用于本次响应,刷新失败或缺少资源元数据时保留该段原地址,并继续处理其他资源。原地址为空时仍保持为空,单个资源失败不影响整条消息返回。地址更新时同步响应中的 `raw_message`,不改写保存的消息;保留的旧地址仍可能已经过期。
`get_record` 单独向 QQ 获取语音的当前下载地址,资源元数据缺失或远端获取失败时动作返回错误,不使用旧地址或发送时的本地文件兜底。历史记录若没有保存资源引用,无法仅凭文件名恢复下载地址。
SnowLuma 不为这些查询长期保存媒体文件或 Base64 内容,本地保留的是消息及资源元数据;上传、转码仍会使用临时文件。下载地址和 QQ 远端资源都有可用性限制,需要长期归档的消费端应及时下载并自行保存。
## 使用边界与许可
> [!IMPORTANT]

View File

@@ -1,7 +1,7 @@
{
"license": "SEE LICENSE IN LICENSE",
"name": "snowluma-monorepo",
"version": "2.0.0",
"version": "2.0.1",
"description": "SnowLuma monorepo workspace (pnpm)",
"private": true,
"type": "module",

View File

@@ -1,7 +1,7 @@
{
"license": "SEE LICENSE IN LICENSE",
"name": "@snowluma/bridge",
"version": "2.0.0",
"version": "2.0.1",
"private": true,
"type": "module",
"description": "SnowLuma bridge — QQ NT desktop client lifecycle: hook injection (via native addon), per-PID HookSession orchestration, pipe-watcher for process discovery, and the BridgeManagerSink interface that lets the hook layer call back into a UIN-keyed session router without depending on @snowluma/core. Consumed by the top-level app entry (which constructs the BridgeManager from @snowluma/core and injects it as the sink) and by the WebUI server (read-only HookProcessInfo views).",

View File

@@ -1,7 +1,7 @@
{
"license": "SEE LICENSE IN LICENSE",
"name": "@snowluma/common",
"version": "2.0.0",
"version": "2.0.1",
"private": true,
"type": "module",
"description": "SnowLuma shared infrastructure — leaf-package utilities with zero business dependencies. Logger / hex codec / log file transport / log line summariser / packet sender wire-protocol types / runtime config loader. Consumed by @snowluma/protocol, @snowluma/core, and @snowluma/onebot. Per-file subpath exports keep import sites unambiguous and let the bundler tree-shake aggressively (importing `@snowluma/common/hex` doesn't pull in `node:fs` from the logger transport).",

View File

@@ -1,7 +1,7 @@
{
"license": "SEE LICENSE IN LICENSE",
"name": "@snowluma/core",
"version": "2.0.0",
"version": "2.0.1",
"description": "SnowLuma core - NTQQ packet sniffer with Node.js native addon",
"private": true,
"type": "module",

View File

@@ -0,0 +1,216 @@
import { describe, expect, it, vi } from 'vitest';
import { deflateSync, gzipSync } from 'zlib';
import { buildApiContext, type OneBotInstanceContext } from '@snowluma/onebot/instance-context';
import type { Elem } from '@snowluma/proto-defs/element';
import type { LongMsgResult, RecvLongMsgReq, RecvLongMsgResp } from '@snowluma/proto-defs/longmsg';
import type { PushMsgBody } from '@snowluma/proto-defs/message';
import { protobuf_decode, protobuf_encode } from '@snowluma/proton';
import { ForwardApi } from '../../src/bridge/apis/forward';
import type { BridgeContext } from '../../src/bridge/bridge-context';
import { mockBridge } from './_helpers';
function forwardCard(format: 'xml' | 'lightApp', resId: string, key?: string): Elem {
const content =
format === 'xml'
? `<msg serviceID="35" m_resid="${resId}"${key ? ` m_fileName="${key}"` : ''} />`
: JSON.stringify({
app: 'com.tencent.multimsg',
meta: { detail: { resid: resId, uniseq: key } },
});
const data = Buffer.concat([Buffer.from([1]), deflateSync(Buffer.from(content))]);
return format === 'xml'
? { richMsg: { serviceId: 35, template1: data } }
: { lightApp: { data } };
}
function message(...elems: Elem[]): PushMsgBody {
return {
responseHead: {
fromUin: 20002,
fromUid: 'sender-uid',
grp: { groupUin: 12345, memberCard: 'alice' },
},
contentHead: { msgType: 82, sequence: 10, timestamp: 1700000000 },
body: { richText: { elems } },
};
}
function setup(downloads: Map<string, LongMsgResult>) {
const requested: string[] = [];
const bridge = mockBridge({
sendRawPacket: vi.fn(async (command: string, bytes: Uint8Array) => {
expect(command).toBe('trpc.group.long_msg_interface.MsgService.SsoRecvLongMsg');
const resId = protobuf_decode<RecvLongMsgReq>(bytes).info!.resId!;
requested.push(resId);
const data = downloads.get(resId);
return {
success: true,
gotResponse: true,
errorCode: 0,
errorMessage: '',
responseData: Buffer.from(
protobuf_encode<RecvLongMsgResp>({
result: {
resId,
payload: data
? gzipSync(protobuf_encode<LongMsgResult>(data))
: undefined,
},
}),
),
};
}),
});
const forward = new ForwardApi(bridge as unknown as BridgeContext);
const ctx = {
selfId: 10001,
bridge: { apis: { forward } },
converterCtx: {
selfId: 10001,
imageUrlResolver: null,
mediaUrlResolver: null,
messageIdResolver: null,
mediaSegmentSink: null,
},
} as unknown as OneBotInstanceContext;
return { api: buildApiContext(ctx), requested };
}
describe('get_forward_msg / nested downloads (#529)', () => {
it.each(['xml', 'lightApp'] as const)(
'resolves siblings and three levels of %s forwards from one outer payload',
async (format) => {
const outer = `nested-fetch-${format}-outer`;
const inner = `nested-fetch-${format}-inner`;
const sibling = `nested-fetch-${format}-sibling`;
const leaf = `nested-fetch-${format}-leaf`;
const { api, requested } = setup(
new Map([
[
outer,
{
action: [
{
actionCommand: 'MultiMsg',
actionData: {
msgBody: [
message(forwardCard(format, inner, 'inner-key')),
message(forwardCard(format, sibling, 'sibling-key')),
],
},
},
{
actionCommand: 'leaf-key',
actionData: {
msgBody: [
message(
{ text: { str: 'deepest content' } },
{
customFace: {
md5: Buffer.alloc(16, 0xab),
origUrl: 'https://example.com/forward.png',
width: 32,
height: 24,
},
},
),
],
},
},
{
actionCommand: 'sibling-key',
actionData: {
msgBody: [message({ text: { str: 'sibling content' } })],
},
},
{
actionCommand: 'inner-key',
actionData: {
msgBody: [message(forwardCard(format, leaf, 'leaf-key'))],
},
},
],
},
],
]),
);
const parent = await api.getForwardMsg(outer);
expect(parent.map((node) => node.message)).toEqual([
[{ type: 'forward', data: { id: inner } }],
[{ type: 'forward', data: { id: sibling } }],
]);
const middle = await api.getForwardMsg(inner);
expect(middle[0]!.message).toEqual([{ type: 'forward', data: { id: leaf } }]);
expect((await api.getForwardMsg(leaf))[0]).toMatchObject({
sender: { user_id: 20002, nickname: 'alice' },
time: 1700000000,
message: [
{ type: 'text', data: { text: 'deepest content' } },
{ type: 'image', data: { url: 'https://example.com/forward.png' } },
],
});
expect((await api.getForwardMsg(sibling))[0]!.message).toEqual([
{ type: 'text', data: { text: 'sibling content' } },
]);
expect(requested).toEqual([outer]);
},
);
it.each([undefined, 'unmatched-key'])(
'downloads by resId when the XML filename is %s and preserves empty-payload errors',
async (key) => {
const outer = `nested-fetch-fallback-${key}-outer`;
const inner = `nested-fetch-fallback-${key}-inner`;
const empty = `nested-fetch-fallback-${key}-empty`;
const { api, requested } = setup(
new Map([
[
outer,
{
action: [
{
actionCommand: 'MultiMsg',
actionData: {
msgBody: [
message(forwardCard('xml', inner, key)),
message(forwardCard('xml', empty, key)),
],
},
},
{
actionCommand: 'unrelated-key',
actionData: {
msgBody: [message({ text: { str: 'unrelated content' } })],
},
},
],
},
],
[
inner,
{
action: [
{
actionCommand: 'MultiMsg',
actionData: {
msgBody: [message({ text: { str: 'downloaded content' } })],
},
},
],
},
],
]),
);
await api.getForwardMsg(outer);
expect((await api.getForwardMsg(inner))[0]!.message).toEqual([
{ type: 'text', data: { text: 'downloaded content' } },
]);
await expect(api.getForwardMsg(empty)).rejects.toThrow(
'download forward message payload is empty',
);
expect(requested).toEqual([outer, inner, empty]);
},
);
});

View File

@@ -1,7 +1,7 @@
{
"license": "SEE LICENSE IN LICENSE",
"name": "@snowluma/mcp",
"version": "2.0.0",
"version": "2.0.1",
"description": "MCP server exposing the SnowLuma OneBot action catalog (docs + JSON Schemas) and optional execution to LLM clients.",
"repository": {
"type": "git",

View File

@@ -1,7 +1,7 @@
{
"license": "SEE LICENSE IN LICENSE",
"name": "@snowluma/onebot",
"version": "2.0.0",
"version": "2.0.1",
"private": true,
"type": "module",
"description": "SnowLuma OneBot v11 adapter — the protocol translation layer that maps the public OneBot vocabulary (HTTP / WebSocket actions, message segments, post events) onto @snowluma/core's typed Api hub (`bridge.apis.<area>.method()`). Owns network adapters (HTTP server / HTTP client / WS server / WS client), the registered action handlers, the receive-side event→OneBot converter, message-id hashing, message store (SQLite-backed event history), media store, and the OneBot instance + manager that ties one OneBotConfig to one Bridge. Per-file subpath exports mirror the legacy `core/src/onebot/*` layout 1:1 so the previous `import { … } from '../onebot/<x>'` collapses to `import { … } from '@snowluma/onebot/<x>'`.",

View File

@@ -1,7 +1,7 @@
{
"license": "SEE LICENSE IN LICENSE",
"name": "@snowluma/proto-defs",
"version": "2.0.0",
"version": "2.0.1",
"private": true,
"type": "module",
"description": "SnowLuma QQ/Lagrange wire-protobuf type definitions. Pure TypeScript interfaces with proton's `pb<N, T>` marker types — `@snowluma/proton`'s vite plugin compiles them into zero-runtime encoder/decoder functions at the call sites in `@snowluma/core` (and any downstream consumer). Exposed as per-file subpaths (`@snowluma/proto-defs/oidb`, `@snowluma/proto-defs/message`, …) so the import-site shape mirrors the legacy `bridge/proto/proton/*` layout and avoids name collisions across files (notably `highway.ts` and `oidb-actions/media.ts` share NTV2-prefixed names).",

View File

@@ -1,7 +1,7 @@
{
"license": "SEE LICENSE IN LICENSE",
"name": "@snowluma/protocol",
"version": "2.0.0",
"version": "2.0.1",
"private": true,
"type": "module",
"description": "SnowLuma protocol — the protocol-layer between QQ wire bytes and typed events. Owns: identity service (uid↔uin cache with SQLite persistence), event bus, packet pipeline (incoming SSO packet → QQEventVariant), msg-push decoders, element-builder (MessageElement → wire elems[]), highway upload protocol (file/image/video/ptt), OIDB envelope helper, and the event/notice/request type vocabulary. Consumers (@snowluma/core, @snowluma/onebot) talk to this package through `BridgeContext` for runtime calls and the standalone classes (IdentityService, BridgeEventBus, IncomingPacketPipeline) for composition. Per-file subpath exports mirror the legacy `core/src/bridge/*` layout 1:1 so the previous `import { …} from '../bridge/<x>'` collapses to `import { … } from '@snowluma/protocol/<x>'`.",

View File

@@ -137,9 +137,12 @@ function decodeRichMsgCard(
if (svcId === 35) {
const match = /\bm_resid="([^"]+)"/.exec(content);
// XML forwards link bundled inner messages by m_fileName, just as
// LightApp forwards use uniseq. Keep it for the outer payload lookup.
const fileName = /\bm_fileName="([^"]+)"/.exec(content)?.[1];
return {
element: match
? { type: 'forward', resId: match[1] }
? { type: 'forward', resId: match[1], forwardUuid: fileName }
: { type: 'xml', text: content, subType: svcId },
error: null,
inputBytes: data.length,

View File

@@ -218,6 +218,34 @@ describe('decodeRichBody / forward LightApp', () => {
expect(out[0]!.type).toBe('json');
});
it.each([false, true])(
'preserves the XML forward filename for nested lookup (compressed=%s, #529)',
(compressed) => {
const xml = Buffer.from(
'<msg serviceID="35" m_resid="inner-xml-res" m_fileName="inner-xml-key" />',
);
const body: MessageBody = {
richText: {
elems: [
{
richMsg: {
serviceId: 35,
template1: Buffer.concat([
Buffer.from([compressed ? 1 : 0]),
compressed ? deflateSync(xml) : xml,
]),
},
},
],
},
};
expect(decodeRichBody(body, true)).toEqual([
{ type: 'forward', resId: 'inner-xml-res', forwardUuid: 'inner-xml-key' },
]);
},
);
it('still decodes the legacy richMsg serviceID=35 path (backward compat with mobile QQ)', () => {
// Older clients (and some bridges) still emit the m_resid XML
// shape. The decoder must keep treating it as a forward element

View File

@@ -1,7 +1,7 @@
{
"license": "SEE LICENSE IN LICENSE",
"name": "@snowluma/proton",
"version": "2.0.0",
"version": "2.0.1",
"private": true,
"type": "module",
"description": "Compile-time protobuf encoder/decoder generator for SnowLuma. TypeScript interfaces → fully-inlined, zero-runtime protobuf codec functions. Vendored from SnowLuma/protobuf-dsl with edge-case fixes applied.",

View File

@@ -1,7 +1,7 @@
{
"license": "SEE LICENSE IN LICENSE",
"name": "@snowluma/runtime",
"version": "2.0.0",
"version": "2.0.1",
"private": true,
"type": "module",
"main": "index.mjs",

View File

@@ -4,7 +4,7 @@
"name": "MotricSeven",
"email": "motricseven@gmail.com"
},
"version": "2.0.0",
"version": "2.0.1",
"description": "TypeScript SDK for SnowLuma OneBot HTTP and WebSocket transports",
"keywords": [
"snowluma",

View File

@@ -1,7 +1,7 @@
{
"license": "SEE LICENSE IN LICENSE",
"name": "@snowluma/sqlite",
"version": "2.0.0",
"version": "2.0.1",
"private": true,
"type": "module",
"description": "SnowLuma asynchronous SQLite facade, native loader and release assets.",

View File

@@ -4,7 +4,7 @@
"name": "MotricSeven",
"email": "motricseven@gmail.com"
},
"version": "2.0.0",
"version": "2.0.1",
"description": "Shared SnowLuma UI primitives — Tailwind 4 theme tokens + shadcn-style atomic components",
"keywords": [
"snowluma",

View File

@@ -1,7 +1,7 @@
{
"license": "SEE LICENSE IN LICENSE",
"name": "@snowluma/websocket",
"version": "2.0.0",
"version": "2.0.1",
"private": true,
"type": "module",
"main": "./src/index.ts",

View File

@@ -2,7 +2,7 @@
"license": "SEE LICENSE IN LICENSE",
"name": "webui",
"private": true,
"version": "2.0.0",
"version": "2.0.1",
"type": "module",
"scripts": {
"dev": "vite",