fix(onebot): support custom nested forward previews (#493)

Accept custom preview metadata on nested forward messages and carry it through card creation.

Refs #493
This commit is contained in:
under-the-ocean
2026-10-04 15:44:06 +08:00
committed by GitHub
parent 1919e16081
commit 89275ae279
5 changed files with 208 additions and 5 deletions
+15 -4
View File
@@ -243,6 +243,11 @@ function cloneNodeWithElements(node: ForwardNodePayload, elements: MessageElemen
senderCard: node.senderCard,
messageType: node.messageType,
innerForward: node.innerForward,
news: node.news,
title: node.title,
source: node.source,
summary: node.summary,
prompt: node.prompt,
};
}
@@ -478,10 +483,16 @@ export class ForwardApi {
type: 'forward',
resId: inner.resId,
forwardUuid: inner.uuid,
forwardSource: deriveInnerSource(node.innerForward, isGroup),
forwardSummary: `查看${node.innerForward.length}条转发消息`,
forwardPrompt: '[聊天记录]',
forwardNews: previewLinesFromNodes(node.innerForward),
forwardSource: node.source && node.source.length > 0
? node.source
: deriveInnerSource(node.innerForward, isGroup),
forwardSummary: node.summary && node.summary.length > 0
? node.summary
: `查看${node.innerForward.length}条转发消息`,
forwardPrompt: node.prompt && node.prompt.length > 0
? node.prompt
: '[聊天记录]',
forwardNews: node.news && node.news.length > 0 ? node.news : previewLinesFromNodes(node.innerForward),
forwardTSum: node.innerForward.length,
};
processedNodes.push({
@@ -59,7 +59,7 @@ function decodeOuterLongMsg(rawBytes: Uint8Array): LongMsgResult {
return protobuf_decode<LongMsgResult>(gunzipSync(Buffer.from(payload)));
}
function findLightAppJson(msgBody: PushMsgBody[]): { resid?: string; uniseq?: string; app?: string } | null {
function findLightAppJson(msgBody: PushMsgBody[]): { resid?: string; uniseq?: string; app?: string; news?: Array<{ text: string }>; source?: string; summary?: string } | null {
for (const body of msgBody) {
const elems: Elem[] = body.body?.richText?.elems ?? [];
for (const elem of elems) {
@@ -74,6 +74,9 @@ function findLightAppJson(msgBody: PushMsgBody[]): { resid?: string; uniseq?: st
app: parsed.app,
resid: parsed.meta?.detail?.resid,
uniseq: parsed.meta?.detail?.uniseq,
news: parsed.meta?.detail?.news,
source: parsed.meta?.detail?.source,
summary: parsed.meta?.detail?.summary,
};
}
} catch { /* ignore */ }
@@ -178,4 +181,86 @@ describe('forward / nested upload wire alignment', () => {
expect(outermost.action![2]!.actionCommand).not.toBe('MultiMsg');
expect(outermost.action![1]!.actionCommand).not.toBe(outermost.action![2]!.actionCommand);
});
it('inner forward bubble prefers caller-supplied node news over auto-generated lines', async () => {
const responses = ['inner-res', 'outer-res'];
const sendRawPacket = vi.fn(async () =>
uploadResponseWithResId(responses.shift()!)) as any;
const bridge = mockBridge({ sendRawPacket });
const customNews = [{ text: '自定义预览行 1' }, { text: '自定义预览行 2' }];
await new ForwardApi(bridge as any).upload([{
userUin: 111,
nickname: 'outer',
elements: [],
news: customNews,
innerForward: [
{ userUin: 222, nickname: 'inner', elements: [{ type: 'text', text: '会被覆盖的正文' }] },
],
}]);
const outerBytes = sendRawPacket.mock.calls[1]![1] as Uint8Array;
const outerMsgBody = decodeOuterLongMsg(outerBytes).action![0]!.actionData!.msgBody!;
const preview = findLightAppJson(outerMsgBody);
expect(preview).not.toBeNull();
// Caller-supplied news wins over `inner: 会被覆盖的正文`.
expect(preview!.news).toEqual(customNews);
});
it('inner forward bubble falls back to auto-generated lines when node has no news', async () => {
const responses = ['inner-res', 'outer-res'];
const sendRawPacket = vi.fn(async () =>
uploadResponseWithResId(responses.shift()!)) as any;
const bridge = mockBridge({ sendRawPacket });
await new ForwardApi(bridge as any).upload([{
userUin: 111,
nickname: 'outer',
elements: [],
// no `news` field — auto-generate from inner nodes
innerForward: [
{ userUin: 222, nickname: '内层说话人', elements: [{ type: 'text', text: '第一句台词' }] },
],
}]);
const outerBytes = sendRawPacket.mock.calls[1]![1] as Uint8Array;
const outerMsgBody = decodeOuterLongMsg(outerBytes).action![0]!.actionData!.msgBody!;
const preview = findLightAppJson(outerMsgBody);
expect(preview).not.toBeNull();
expect(preview!.news).toEqual([{ text: '内层说话人: 第一句台词' }]);
});
it('inner forward card prefers caller-supplied source/summary/prompt metadata', async () => {
const responses = ['inner-res', 'outer-res'];
const sendRawPacket = vi.fn(async () =>
uploadResponseWithResId(responses.shift()!)) as any;
const bridge = mockBridge({ sendRawPacket });
await new ForwardApi(bridge as any).upload([{
userUin: 111,
nickname: 'outer',
elements: [],
source: '万叶的手记',
summary: '共 12 条剧情消息',
prompt: '查看剧情',
innerForward: [
{ userUin: 222, nickname: 'inner', elements: [{ type: 'text', text: 'hi' }] },
],
}]);
const outerBytes = sendRawPacket.mock.calls[1]![1] as Uint8Array;
const outerMsgBody = decodeOuterLongMsg(outerBytes).action![0]!.actionData!.msgBody!;
const preview = findLightAppJson(outerMsgBody);
expect(preview).not.toBeNull();
// decodeOuterLongMsg → lightApp meta.detail as built by element-builder
expect(preview!.app).toBe('com.tencent.multimsg');
// The plaintext preview lines of the wire bubble.
// Caller metadata wins: source = 万叶的手记, summary used instead of
// the auto-generated `查看N条转发消息`.
expect(preview!.source).toBe('万叶的手记');
expect(preview!.summary).toBe('共 12 条剧情消息');
});
});
@@ -1531,6 +1531,9 @@ export async function getForwardMessage(
nickname: node.nickname,
};
if (isGroup) sender.card = node.senderCard ?? '';
if (node.title !== undefined && node.title.length > 0) {
sender.title = node.title;
}
const message: JsonObject = {
self_id: ref.selfId,
@@ -1679,6 +1682,11 @@ function assertForwardNodeMetadataIsScalar(
value === undefined || value === null || typeof value === 'string'
|| typeof value === 'number' || typeof value === 'boolean'
) continue;
// OneBot 生态兼容:多个上游框架(NapCat / LLOneBot / AstrBot 等)
// 允许 forward node 携带 `news` 预览元数据(数组形态,
// `[{ text: string }]`,与 ForwardPreviewMeta.news 同构)。这些字段
// 仅用于生成卡片预览,不影响上传;直接放行而非拒绝整个转发。
if (field === 'news' && isForwardNewsArray(value)) continue;
throw new MessageElementValidationError(
'INVALID_FIELD',
`forward messages[${index}].${field} must be a scalar value`,
@@ -1688,6 +1696,16 @@ function assertForwardNodeMetadataIsScalar(
}
}
/** Whether a value looks like OneBot preview news: `Array<{ text: string }>`. */
function isForwardNewsArray(value: JsonValue): boolean {
if (!Array.isArray(value)) return false;
for (const item of value) {
const obj = asJsonObject(item);
if (!obj || typeof obj.text !== 'string') return false;
}
return true;
}
function assertForwardMessageInputPolicies(
ref: OneBotInstanceContext,
messages: JsonValue,
@@ -1914,6 +1932,20 @@ async function parseForwardNodes(
}
const node: ForwardNodePayload = { userUin, nickname, elements };
// Forward optional preview news lines (OneBot `data.news`) onto the
// payload so nested-forward bubble previews can prefer caller-supplied
// lines over auto-generated ones. Only accepted when the array shape
// is valid (already asserted by assertForwardNodeMetadataIsScalar).
if (isForwardNewsArray(nodeData.news)) {
node.news = nodeData.news as Array<{ text: string }>;
}
// Forward optional OneBot bubble-preview metadata so nested-forward
// cards can prefer caller-supplied titles/source/summary/prompt over
// auto-derived ones (all scalar, already asserted above).
if (nodeData.title !== undefined && typeof nodeData.title === 'string') node.title = nodeData.title;
if (nodeData.source !== undefined && typeof nodeData.source === 'string') node.source = nodeData.source;
if (nodeData.summary !== undefined && typeof nodeData.summary === 'string') node.summary = nodeData.summary;
if (nodeData.prompt !== undefined && typeof nodeData.prompt === 'string') node.prompt = nodeData.prompt;
// Honour an explicit per-node display time (OneBot `data.time`, unix
// seconds) so a custom forward can set/back-date each node's timestamp
// (#209). The wire field is uint32, so reject a millisecond value or any
@@ -615,4 +615,63 @@ describe('forward — nested {type:"node"} content', () => {
expect((nodes as any[])[0].nickname).toBe('PixivBot'); // custom nickname preserved
expect((nodes as any[])[1].userUin).toBe(10001); // omitted → self_id
});
it('accepts node metadata `news` preview arrays (OneBot ecosystem compat)', async () => {
// Upstream frameworks (NapCat / LLOneBot / AstrBot etc.) attach
// `news: [{ text }]` preview metadata to forward nodes. Only scalar
// metadata was allowed before, so a standard OneBot-style node was
// rejected with `forward messages[i].news must be a scalar value`.
const uploadForwardNodes = vi.fn(async (_nodes: any[]) => 'RESID');
const sendGroupMessage = vi.fn(async () => ({
messageId: 1, sequence: 100, clientSequence: 0, random: 1, timestamp: 1700000000,
}));
const bridge = fakeBridge({ apis: { message: { sendGroup: sendGroupMessage }, forward: { upload: uploadForwardNodes } } } as any);
const ctx = makeCtx(bridge);
const messages = [{
type: 'node',
data: {
user_id: 111,
nickname: 'outer',
news: [{ text: '预览行 1' }, { text: '预览行 2' }],
summary: '共 2 条',
content: [{ type: 'node', data: { user_id: 222, nickname: 'inner', content: [{ type: 'text', data: { text: 'hi' } }] } }],
},
}];
await sendGroupForwardMessage(ctx, 12345, messages as any);
expect(uploadForwardNodes).toHaveBeenCalledOnce();
const [nodes] = uploadForwardNodes.mock.calls[0]!;
expect((nodes as any[])[0].userUin).toBe(111);
expect((nodes as any[])[0].innerForward).toHaveLength(1);
});
it('rejects non-scalar node metadata that is not an accepted preview field', async () => {
// The news carve-out must stay narrow: any other non-scalar metadata
// (e.g. an accidental nested object) is still rejected up front.
const uploadForwardNodes = vi.fn(async (_nodes: any[]) => 'RESID');
const sendGroupMessage = vi.fn();
const bridge = fakeBridge({
apis: { message: { sendGroup: sendGroupMessage }, forward: { upload: uploadForwardNodes } },
} as any);
const ctx = makeCtx(bridge);
const messages = [{
type: 'node',
data: {
user_id: 111,
nickname: 'bad',
arbitrary: { nested: true },
content: [{ type: 'text', data: { text: 'hi' } }],
},
}];
await expect(sendGroupForwardMessage(ctx, 12345, messages as any)).rejects.toMatchObject({
code: 'INVALID_FIELD',
elementType: 'node',
field: 'arbitrary',
});
expect(uploadForwardNodes).not.toHaveBeenCalled();
expect(sendGroupMessage).not.toHaveBeenCalled();
});
});
+16
View File
@@ -255,6 +255,22 @@ export interface ForwardNodePayload {
// Caller never sets this on top-level OneBot input — `parseForward
// Nodes` synthesises it when it detects a nested-node array.
innerForward?: ForwardNodePayload[];
// Optional preview news lines carried on this node (OneBot
// `data.news`, `Array<{ text: string }>`). When this node embeds a
// nested forward (`innerForward`), the upload pipeline prefers these
// lines over auto-generated ones for the inner forward's bubble
// preview, matching NapCat / LLOneBot behaviour.
news?: Array<{ text: string }>;
// Optional bubble-preview metadata carried on this node (OneBot
// `data.title` / `data.source` / `data.summary` / `data.prompt`).
// When this node embeds a nested forward, the upload pipeline uses
// these to label the inner forward's card (source line, summary,
// prompt) instead of deriving them from the inner nodes. title is
// exposed back through get_forward_msg for OneBot compatibility.
title?: string;
source?: string;
summary?: string;
prompt?: string;
}
export interface QQEvent {