diff --git a/packages/core/src/bridge/element-builder.ts b/packages/core/src/bridge/element-builder.ts
index 61755c86..8158a319 100644
--- a/packages/core/src/bridge/element-builder.ts
+++ b/packages/core/src/bridge/element-builder.ts
@@ -115,13 +115,59 @@ function makeMarkdownElem(element: MessageElement): ProtoElem {
};
}
+function escapeXml(value: string): string {
+ return value
+ .replace(/&/g, '&')
+ .replace(//g, '>')
+ .replace(/"/g, '"')
+ .replace(/'/g, ''');
+}
+
function makeForwardElem(element: MessageElement): ProtoElem {
const resId = (element.resId ?? '').trim();
if (!resId) {
throw new Error('forward resId is required');
}
- const xml = `- 聊天记录查看转发消息查看转发消息
`;
+ // Multi-msg preview bubble — modelled on the go-cqhttp / NapCat XML.
+ // `source` becomes the bold header (e.g. "群聊的聊天记录"), `news`
+ // entries become per-line previews ("nick: text"), `summary` is the
+ // grey footer ("查看 N 条转发消息"), `prompt` is the chat-list brief.
+ const source = element.forwardSource && element.forwardSource.length > 0
+ ? element.forwardSource
+ : '聊天记录';
+ const summary = element.forwardSummary && element.forwardSummary.length > 0
+ ? element.forwardSummary
+ : '查看转发消息';
+ const prompt = element.forwardPrompt && element.forwardPrompt.length > 0
+ ? element.forwardPrompt
+ : '[聊天记录]';
+ const news = Array.isArray(element.forwardNews) ? element.forwardNews : [];
+ const tSum = element.forwardTSum && element.forwardTSum > 0
+ ? element.forwardTSum
+ : Math.max(news.length, 1);
+
+ const newsTitles = news
+ .map(n => `
${escapeXml(n.text ?? '')}`)
+ .join('');
+
+ const resIdAttr = escapeXml(resId);
+ const xml =
+ `` +
+ `` +
+ `- ` +
+ `${escapeXml(source)}` +
+ newsTitles +
+ `
` +
+ `${escapeXml(summary)}` +
+ ` ` +
+ `` +
+ ``;
+
const encodedXml = new TextEncoder().encode(xml);
const payload = new Uint8Array(encodedXml.length + 1);
payload[0] = 0x00;
diff --git a/packages/core/src/bridge/events.ts b/packages/core/src/bridge/events.ts
index f74df37c..27e75eb6 100644
--- a/packages/core/src/bridge/events.ts
+++ b/packages/core/src/bridge/events.ts
@@ -27,6 +27,15 @@ export interface MessageElement {
flash?: boolean;
resId?: string;
fileHash?: string;
+ // Preview-bubble metadata for the `forward` element. Drives the XML
+ // template (brief/title/news/summary/tSum) the recipient renders before
+ // they tap to expand. When unset, the element builder falls back to
+ // generic defaults so old call sites keep working.
+ forwardSource?: string;
+ forwardSummary?: string;
+ forwardPrompt?: string;
+ forwardNews?: Array<{ text: string }>;
+ forwardTSum?: number;
// Server-side fingerprints carried from receive side so a forward can do a
// pure md5/sha1 fast-upload without re-downloading the original bytes.
// Set together with `noByteFallback: true` to make the upload modules throw
diff --git a/packages/core/src/onebot/actions/extended.ts b/packages/core/src/onebot/actions/extended.ts
index c4912a3f..a4d1d15e 100644
--- a/packages/core/src/onebot/actions/extended.ts
+++ b/packages/core/src/onebot/actions/extended.ts
@@ -1,7 +1,34 @@
import type { ApiHandler, ApiActionContext } from '../api-handler';
import { asMessage, asNumber, asString, asBoolean } from '../api-handler';
+import type { ForwardPreviewMeta } from '../modules/message-actions';
import { RETCODE, failedResponse, okResponse } from '../types';
+/**
+ * Pull NapCat-compatible forward preview overrides off a send_*_forward_msg
+ * payload. All four fields are optional — when omitted, the module layer
+ * derives sensible defaults from the actual node list.
+ */
+function readForwardPreviewMeta(params: Record): ForwardPreviewMeta | undefined {
+ const source = asString(params.source) || undefined;
+ const summary = asString(params.summary) || undefined;
+ const prompt = asString(params.prompt) || undefined;
+ let news: Array<{ text: string }> | undefined;
+ if (Array.isArray(params.news)) {
+ const collected: Array<{ text: string }> = [];
+ for (const item of params.news) {
+ if (typeof item === 'string') {
+ collected.push({ text: item });
+ } else if (item && typeof item === 'object' && !Array.isArray(item)) {
+ const text = asString((item as Record).text);
+ if (text) collected.push({ text });
+ }
+ }
+ if (collected.length > 0) news = collected;
+ }
+ if (!source && !summary && !prompt && !news) return undefined;
+ return { source, summary, prompt, news };
+}
+
export function register(h: ApiHandler, ctx: ApiActionContext): void {
// --- Likes & Pokes ---
@@ -301,18 +328,19 @@ export function register(h: ApiHandler, ctx: ApiActionContext): void {
const groupId = asNumber(params.group_id);
const userId = asNumber(params.user_id);
const messages = asMessage(params.messages ?? params.message);
+ const meta = readForwardPreviewMeta(params);
if (messages === undefined) return failedResponse(RETCODE.BAD_REQUEST, 'message/messages is required');
if ((messageType === 'group' || groupId > 0) && ctx.sendGroupForwardMsg) {
if (!groupId) return failedResponse(RETCODE.BAD_REQUEST, 'group_id is required');
- const result = await ctx.sendGroupForwardMsg(groupId, messages);
+ const result = await ctx.sendGroupForwardMsg(groupId, messages, meta);
return okResponse({ message_id: result.messageId, res_id: result.forwardId, forward_id: result.forwardId });
}
if ((messageType === 'private' || userId > 0) && ctx.sendPrivateForwardMsg) {
if (!userId) return failedResponse(RETCODE.BAD_REQUEST, 'user_id is required');
- const result = await ctx.sendPrivateForwardMsg(userId, messages);
+ const result = await ctx.sendPrivateForwardMsg(userId, messages, meta);
return okResponse({ message_id: result.messageId, res_id: result.forwardId, forward_id: result.forwardId });
}
@@ -326,7 +354,7 @@ export function register(h: ApiHandler, ctx: ApiActionContext): void {
if (!groupId) return failedResponse(RETCODE.BAD_REQUEST, 'group_id is required');
if (messages === undefined) return failedResponse(RETCODE.BAD_REQUEST, 'message/messages is required');
- const result = await ctx.sendGroupForwardMsg(groupId, messages);
+ const result = await ctx.sendGroupForwardMsg(groupId, messages, readForwardPreviewMeta(params));
return okResponse({ message_id: result.messageId, res_id: result.forwardId, forward_id: result.forwardId });
});
@@ -336,7 +364,7 @@ export function register(h: ApiHandler, ctx: ApiActionContext): void {
if (!userId) return failedResponse(RETCODE.BAD_REQUEST, 'user_id is required');
if (messages === undefined) return failedResponse(RETCODE.BAD_REQUEST, 'message/messages is required');
- const result = await ctx.sendPrivateForwardMsg(userId, messages);
+ const result = await ctx.sendPrivateForwardMsg(userId, messages, readForwardPreviewMeta(params));
return okResponse({ message_id: result.messageId, res_id: result.forwardId, forward_id: result.forwardId });
});
diff --git a/packages/core/src/onebot/api-handler.ts b/packages/core/src/onebot/api-handler.ts
index 0ffa1447..f2815912 100644
--- a/packages/core/src/onebot/api-handler.ts
+++ b/packages/core/src/onebot/api-handler.ts
@@ -1,4 +1,5 @@
import type { JsonObject, JsonValue, MessageMeta } from './types';
+import type { ForwardPreviewMeta } from './modules/message-actions';
import { RETCODE, failedResponse } from './types';
import { register as registerInfo } from './actions/info';
@@ -97,8 +98,8 @@ export interface ApiActionContext {
handleGetGroupSystemMsg: () => Promise;
getDownloadRKeys: () => Promise;
// Forward message
- sendGroupForwardMsg: (groupId: number, messages: JsonValue) => Promise<{ messageId: number; forwardId: string }>;
- sendPrivateForwardMsg: (userId: number, messages: JsonValue) => Promise<{ messageId: number; forwardId: string }>;
+ sendGroupForwardMsg: (groupId: number, messages: JsonValue, meta?: ForwardPreviewMeta) => Promise<{ messageId: number; forwardId: string }>;
+ sendPrivateForwardMsg: (userId: number, messages: JsonValue, meta?: ForwardPreviewMeta) => Promise<{ messageId: number; forwardId: string }>;
sendForwardMsg: (messages: JsonValue) => Promise<{ forwardId: string }>;
getForwardMsg: (resId: string) => Promise;
forwardSingleMsg: (messageId: number, target: { groupId?: number; userId?: number }) => Promise<{ messageId: number }>;
diff --git a/packages/core/src/onebot/instance-context.ts b/packages/core/src/onebot/instance-context.ts
index fc7c2182..3131a020 100644
--- a/packages/core/src/onebot/instance-context.ts
+++ b/packages/core/src/onebot/instance-context.ts
@@ -163,8 +163,8 @@ export function buildApiContext(ref: OneBotInstanceContext): ApiActionContext {
getFriendMsgHistory: (userId, messageId, count) => getFriendMsgHistory(messageStore, userId, messageId, count),
handleGetGroupSystemMsg: () => getGroupSystemMessages(bridge),
getDownloadRKeys: () => getDownloadRKeys(bridge),
- sendGroupForwardMsg: (groupId, messages) => sendGroupForwardMessage(ref, groupId, messages),
- sendPrivateForwardMsg: (userId, messages) => sendPrivateForwardMessage(ref, userId, messages),
+ sendGroupForwardMsg: (groupId, messages, meta) => sendGroupForwardMessage(ref, groupId, messages, meta),
+ sendPrivateForwardMsg: (userId, messages, meta) => sendPrivateForwardMessage(ref, userId, messages, meta),
sendForwardMsg: (messages) => uploadForwardMessage(ref, messages),
getForwardMsg: (resId) => getForwardMessage(ref, resId),
forwardSingleMsg: (messageId, target) => forwardSingleMessage(ref, messageId, target),
diff --git a/packages/core/src/onebot/modules/message-actions.ts b/packages/core/src/onebot/modules/message-actions.ts
index 2be490d0..b0267909 100644
--- a/packages/core/src/onebot/modules/message-actions.ts
+++ b/packages/core/src/onebot/modules/message-actions.ts
@@ -180,14 +180,23 @@ export async function sendGroupMessage(
return { messageId };
}
+export interface ForwardPreviewMeta {
+ source?: string;
+ summary?: string;
+ prompt?: string;
+ news?: Array<{ text: string }>;
+}
+
export async function sendGroupForwardMessage(
ref: OneBotInstanceContext,
groupId: number,
messages: JsonValue,
+ meta?: ForwardPreviewMeta,
): Promise<{ messageId: number; forwardId: string }> {
const nodes = await parseForwardNodes(ref, messages);
const forwardId = await ref.bridge.uploadForwardNodes(nodes, groupId);
- const receipt = await ref.bridge.sendGroupMessage(groupId, [{ type: 'forward', resId: forwardId }]);
+ const previewElement = buildForwardPreviewElement(forwardId, nodes, true, meta);
+ const receipt = await ref.bridge.sendGroupMessage(groupId, [previewElement]);
const messageId = hashMessageIdInt32(receipt.sequence, groupId, GROUP_MESSAGE_EVENT);
ref.cacheMessageMeta(messageId, {
@@ -207,10 +216,12 @@ export async function sendPrivateForwardMessage(
ref: OneBotInstanceContext,
userId: number,
messages: JsonValue,
+ meta?: ForwardPreviewMeta,
): Promise<{ messageId: number; forwardId: string }> {
const nodes = await parseForwardNodes(ref, messages);
const forwardId = await ref.bridge.uploadForwardNodes(nodes);
- const receipt = await ref.bridge.sendPrivateMessage(userId, [{ type: 'forward', resId: forwardId }]);
+ const previewElement = buildForwardPreviewElement(forwardId, nodes, false, meta);
+ const receipt = await ref.bridge.sendPrivateMessage(userId, [previewElement]);
const messageId = hashMessageIdInt32(receipt.sequence, userId, PRIVATE_MESSAGE_EVENT);
ref.cacheMessageMeta(messageId, {
@@ -563,6 +574,88 @@ async function parseForwardNodes(
return nodes;
}
+// Per-element preview string for the forward bubble's `news` lines.
+// Mirrors NapCat's `PacketMsg.toPreview()` mapping; keeps text trim short
+// so a chain of segments doesn't blow past the bubble's 80-char display.
+function elementPreview(element: MessageElement): string {
+ switch (element.type) {
+ case 'text': {
+ const t = element.text ?? '';
+ return t.length > 40 ? `${t.slice(0, 40)}…` : t;
+ }
+ case 'at': return element.text?.trim() || '@';
+ case 'face': return '[表情]';
+ case 'mface': return element.text ? `[${element.text}]` : '[表情]';
+ case 'image': return '[图片]';
+ case 'record': return '[语音]';
+ case 'video': return '[视频]';
+ case 'file': return element.fileName ? `[文件:${element.fileName}]` : '[文件]';
+ case 'reply': return '';
+ case 'json': return '[JSON消息]';
+ case 'xml': return '[XML消息]';
+ case 'markdown': return '[Markdown]';
+ case 'forward': return '[聊天记录]';
+ case 'poke': return '[戳一戳]';
+ default: return '';
+ }
+}
+
+function buildNewsFromNodes(nodes: ForwardNodePayload[]): Array<{ text: string }> {
+ // Match NapCat ForwardMsgBuilder: each line is ": ".
+ // Cap to the first 4 lines — that's what QQ's bubble can actually render
+ // before it truncates; anything beyond is silently dropped by the client.
+ const lines: Array<{ text: string }> = [];
+ for (const node of nodes) {
+ const preview = node.elements.map(elementPreview).filter(Boolean).join(' ').trim();
+ const nickname = node.nickname || String(node.userUin);
+ lines.push({ text: `${nickname}: ${preview || '[消息]'}` });
+ if (lines.length >= 4) break;
+ }
+ return lines;
+}
+
+function deriveForwardSource(nodes: ForwardNodePayload[], isGroup: boolean): string {
+ if (nodes.length === 0) return '聊天记录';
+ if (isGroup) return '群聊的聊天记录';
+ // Private chat: stitch up to 4 distinct sender nicks, NapCat-style.
+ const seen = new Set();
+ const nicks: string[] = [];
+ for (const node of nodes) {
+ const nick = (node.nickname || String(node.userUin)).trim();
+ if (!nick || seen.has(nick)) continue;
+ seen.add(nick);
+ nicks.push(nick);
+ if (nicks.length >= 4) break;
+ }
+ return nicks.length > 0 ? `${nicks.join('和')}的聊天记录` : '聊天记录';
+}
+
+function buildForwardPreviewElement(
+ resId: string,
+ nodes: ForwardNodePayload[],
+ isGroup: boolean,
+ meta: ForwardPreviewMeta | undefined,
+): MessageElement {
+ const news = meta?.news && meta.news.length > 0 ? meta.news : buildNewsFromNodes(nodes);
+ const source = meta?.source && meta.source.length > 0
+ ? meta.source
+ : deriveForwardSource(nodes, isGroup);
+ const summary = meta?.summary && meta.summary.length > 0
+ ? meta.summary
+ : `查看${nodes.length}条转发消息`;
+ const prompt = meta?.prompt && meta.prompt.length > 0 ? meta.prompt : '[聊天记录]';
+
+ return {
+ type: 'forward',
+ resId,
+ forwardSource: source,
+ forwardSummary: summary,
+ forwardPrompt: prompt,
+ forwardNews: news,
+ forwardTSum: nodes.length,
+ };
+}
+
function asJsonObject(value: JsonValue | undefined): JsonObject | null {
if (typeof value !== 'object' || value === null || Array.isArray(value)) return null;
return value as JsonObject;
diff --git a/packages/sdk/src/types/params.ts b/packages/sdk/src/types/params.ts
index 52bf28b0..4935154c 100644
--- a/packages/sdk/src/types/params.ts
+++ b/packages/sdk/src/types/params.ts
@@ -222,7 +222,18 @@ export interface GroupNoticeParams extends GroupIdParams {
confirm_required?: number;
}
-export interface ForwardMessageParams extends JsonObject {
+export interface ForwardPreviewParams {
+ // Header above the preview ("群聊的聊天记录"). Default: "聊天记录" / nicks.
+ source?: string;
+ // Per-line preview entries ("nick: text"). Default: derived from nodes.
+ news?: Array<{ text: string }>;
+ // Grey footer ("查看 N 条转发消息"). Default: "查看 N 条转发消息".
+ summary?: string;
+ // Chat-list brief ("[聊天记录]"). Default: "[聊天记录]".
+ prompt?: string;
+}
+
+export interface ForwardMessageParams extends JsonObject, ForwardPreviewParams {
message_type?: 'private' | 'group' | string;
user_id?: number;
group_id?: number;
@@ -230,12 +241,12 @@ export interface ForwardMessageParams extends JsonObject {
messages?: JsonValue;
}
-export interface GroupForwardMessageParams extends GroupIdParams {
+export interface GroupForwardMessageParams extends GroupIdParams, ForwardPreviewParams {
message?: JsonValue;
messages?: JsonValue;
}
-export interface PrivateForwardMessageParams extends UserIdParams {
+export interface PrivateForwardMessageParams extends UserIdParams, ForwardPreviewParams {
message?: JsonValue;
messages?: JsonValue;
}