@sns-parse/core 0.5.0-alpha.1 → 0.6.0-alpha.2

package/lib/engine/compose.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 发送编排：把一条解析结果拆成「语义单元」（MessageUnit），按发送策略消费。
+ *
+ * 本模块发送层无关：只构建 OutboundElement，具体发送交给 OutboundSender。
+ *
+ * 每个单元带 mergeable 标记：
+ * - mergeable=true：概述文字/头像/封面/图片/音乐/提示文案（含受限视频与混淆图提示），
+ *   全部并入首条消息——提示说清楚「怎么取」
+ * - mergeable=false：后面跟着的干脆的可领取形式，不含其他内容：
+ *   视频文件 / 「取视频 <token>」/ 「解混淆 <token>[混淆图]」
+ *
+ * 消费方式见 core/flush.ts：
+ * - sendSingle：合并所有 mergeable 单元为一条，mergeable=false 单元逐条
+ * - sendSplit：每个单元一条
+ * - sendForward：每个单元一个转发气泡（仅一条时不打包直接发送）
+ */
+import type { ParserRuntime } from './runtime';
+import type { ParsedData } from '../types';
+import { type OutboundElement, type OutboundSender, type SessionLike } from '../sender';
+import type { ImageOutcome, VideoOutcome } from '../extensions';
+export interface ProcessedItem {
+    text: string;
+    parsed: ParsedData;
+    images: ImageOutcome[];
+    avatar: ImageOutcome;
+    cover: ImageOutcome | null;
+    video: VideoOutcome;
+    /** 推文动图转 GIF 的成品（转换失败为 null，回退发视频） */
+    gif?: Buffer | null;
+    /** 多视频推文的其余视频及其 GIF 成品/封面（与 extraVideos 一一对应） */
+    extraVideos?: VideoOutcome[];
+    extraGifs?: (Buffer | null)[];
+    extraCovers?: (ImageOutcome | null)[];
+}
+/** 一个待发送的语义单元 */
+export interface MessageUnit {
+    content: OutboundElement[];
+    /** true=可合并进单条消息；false=必须独立发送（视频文件/混淆图/取件码） */
+    mergeable: boolean;
+}
+/** 首条消息的混淆图数量提示（不含取件码，取件码只出现在独立领取消息里） */
+export declare function buildImageHint(rt: ParserRuntime, count: number): string;
+/** 首条消息的受限视频提示（不含取件码；token 只在独立的「取视频 <token>」消息里） */
+export declare function buildVideoHint(rt: ParserRuntime, item: ProcessedItem): string;
+/** 把 ProcessedItem 拆成有序语义单元 */
+export declare function buildUnits(rt: ParserRuntime, item: ProcessedItem): MessageUnit[];
+/**
+ * 单条整合：合并所有 mergeable 单元为一条消息（图片超限则退化为逐条），
+ * mergeable=false 单元独立逐条。
+ */
+export declare function sendSingle(rt: ParserRuntime, sender: OutboundSender, session: SessionLike, item: ProcessedItem, opts?: {
+    quoteId?: string;
+}): Promise<void>;
+/** 逐条发送：每个语义单元一条消息 */
+export declare function sendSplit(rt: ParserRuntime, sender: OutboundSender, session: SessionLike, item: ProcessedItem, opts?: {
+    quoteId?: string;
+}): Promise<void>;

package/lib/engine/compose.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildImageHint = buildImageHint;
+exports.buildVideoHint = buildVideoHint;
+exports.buildUnits = buildUnits;
+exports.sendSingle = sendSingle;
+exports.sendSplit = sendSplit;
+const common_1 = require("../utils/common");
+const sender_1 = require("../sender");
+const hooks_1 = require("../workflow/hooks");
+/** 首条消息的混淆图数量提示（不含取件码，取件码只出现在独立领取消息里） */
+function buildImageHint(rt, count) {
+    const nsfw = rt.config.nsfwPolicy || {};
+    return String(nsfw.tokenHintText || '').replace(/\$\{count\}/g, String(count));
+}
+/** 首条消息的受限视频提示（不含取件码；token 只在独立的「取视频 <token>」消息里） */
+function buildVideoHint(rt, item) {
+    const nsfw = rt.config.nsfwPolicy || {};
+    if (item.video.kind === 'card' && item.video.token) {
+        const ttl = rt.config.nsfwVault?.ttlMinutes || 30;
+        const until = new Date(Date.now() + ttl * 60000);
+        const untilStr = `${String(until.getHours()).padStart(2, '0')}:${String(until.getMinutes()).padStart(2, '0')}`;
+        return String(nsfw.videoCardHint || '')
+            .replace(/\$\{until\}/g, untilStr)
+            .replace(/\$\{ttl\}/g, String(ttl));
+    }
+    if (item.video.kind === 'link' && item.video.url)
+        return `受限视频未在群内发送。视频链接：${item.video.url}`;
+    if (item.video.kind === 'drop' && item.parsed.video)
+        return '受限视频未在群内发送。';
+    return '';
+}
+/** 把 ProcessedItem 拆成有序语义单元 */
+function buildUnits(rt, item) {
+    const { config } = rt;
+    const p = item.parsed;
+    const units = [];
+    const push = (content, mergeable) => { if (content.length)
+        units.push({ content, mergeable }); };
+    // ① 概述文字
+    if (item.text && config.showImageText)
+        push([sender_1.el.text(item.text)], true);
+    // ② 头像（非混淆）
+    if (config.showAuthorAvatar && p.avatar && item.avatar.kind !== 'drop' && item.avatar.kind !== 'scrambled' && item.avatar.url) {
+        push([sender_1.el.image(item.avatar.url)], true);
+    }
+    // ③ 封面（非混淆）；多视频推文的每个视频封面都进概述区
+    if (item.cover && item.cover.kind === 'raw' && item.cover.url
+        && p.cover && config.showCoverImage && p.type !== 'live_photo' && p.type !== 'image' && p.type !== 'live') {
+        const c = [];
+        if (config.showCoverText)
+            c.push(sender_1.el.text(config.coverText || '封面：'));
+        c.push(sender_1.el.image(item.cover.url));
+        push(c, true);
+    }
+    if (config.showCoverImage && p.type !== 'live_photo' && p.type !== 'image' && p.type !== 'live') {
+        for (const ec of item.extraCovers || []) {
+            if (ec?.kind === 'raw' && ec.url && ec.url !== item.cover?.url)
+                push([sender_1.el.image(ec.url)], true);
+            else if (ec?.kind === 'link' && ec.url && ec.url !== item.cover?.url)
+                push([sender_1.el.text(`封面链接：${ec.url}`)], true);
+        }
+    }
+    // ④ 音乐封面
+    if (config.showMusicCover && p.music.cover)
+        push([sender_1.el.image(p.music.cover)], true);
+    // ⑤ 非混淆图片（raw 可带 buffer：同源切图合并成品优先按 buffer 发送）
+    for (const img of item.images) {
+        if (img.kind === 'raw' && img.buffer)
+            push([sender_1.el.imageBuffer(img.buffer, 'image/jpeg')], true);
+        else if (img.kind === 'raw' && img.url)
+            push([sender_1.el.image(img.url)], true);
+        else if (img.kind === 'link' && img.url)
+            push([sender_1.el.text(`图片链接：${img.url}`)], true);
+    }
+    // ⑥ 合规视频（必须独立，含视频自动分条）；动图已转 GIF 时以图片形式独立发送
+    if (item.gif) {
+        push([sender_1.el.imageBuffer(item.gif, 'image/gif')], false);
+    }
+    else if (p.video && p.type !== 'live' && p.type !== 'live_photo' && item.video.kind === 'raw' && item.video.url) {
+        push([config.showVideoFile !== false ? sender_1.el.video(item.video.url) : sender_1.el.text(`视频链接：${item.video.url}`)], false);
+    }
+    // ⑥b 多视频推文：其余视频逐条独立发送（动图转 GIF 优先，受限降级链接）
+    for (let i = 0; i < (item.extraVideos?.length || 0); i++) {
+        const ev = item.extraVideos[i];
+        const eg = item.extraGifs?.[i];
+        if (eg) {
+            push([sender_1.el.imageBuffer(eg, 'image/gif')], false);
+        }
+        else if (ev.kind === 'raw' && ev.url) {
+            push([config.showVideoFile !== false ? sender_1.el.video(ev.url) : sender_1.el.text(`视频链接：${ev.url}`)], false);
+        }
+        else if (ev.kind === 'link' && ev.url) {
+            push([sender_1.el.text(`视频链接：${ev.url}`)], true);
+        }
+    }
+    // ⑦ 音乐语音
+    if (config.showMusicVoice && p.music.url)
+        push([sender_1.el.audio(p.music.url)], true);
+    // ⑧ 直播提示
+    if (p.type === 'live' && config.sendLiveMessage)
+        push([sender_1.el.text('直播进行中，无法发送视频流。')], true);
+    // ⑨ 受限视频：提示并入首条消息（存在任一受限视频即提示一次）；每个取件码独立成条
+    const cardOutcomes = [item.video, ...(item.extraVideos || [])]
+        .filter(v => v?.kind === 'card' && v.token);
+    let videoHint = buildVideoHint(rt, item);
+    if (!videoHint && cardOutcomes.length) {
+        // 主视频未受限但存在受限的额外视频（按各自封面单独判定）：仍给出领取提示
+        videoHint = buildVideoHint(rt, { ...item, video: cardOutcomes[0] });
+    }
+    if (videoHint)
+        push([sender_1.el.text(videoHint)], true);
+    for (const c of cardOutcomes)
+        push([sender_1.el.text(`取视频 ${c.token}`)], false);
+    // ⑩ 混淆图：首条只报数量；每张独立为干脆的「解混淆 <token>[混淆图]」（多视频封面同策略）
+    const scrambledImgs = [item.avatar, item.cover, ...(item.extraCovers || []), ...item.images]
+        .filter(img => img?.kind === 'scrambled' && img.buffer);
+    if (scrambledImgs.length) {
+        const summary = buildImageHint(rt, scrambledImgs.length);
+        if (summary)
+            push([sender_1.el.text(summary)], true);
+    }
+    for (const img of scrambledImgs) {
+        const c = [];
+        if (img.token)
+            c.push(sender_1.el.text(`解混淆 ${img.token}`));
+        c.push(sender_1.el.imageBuffer(img.buffer, 'image/png'));
+        push(c, false);
+    }
+    return units;
+}
+/** 发送一组元素；失败时视频元素降级为链接文字 */
+async function sendElements(sender, session, elements, quoteId) {
+    const withQuote = quoteId ? [sender_1.el.quote(quoteId), ...elements] : elements;
+    try {
+        await sender.send(session, withQuote);
+    }
+    catch {
+        const links = elements.map(sender_1.videoFallback);
+        await sender.send(session, quoteId ? [sender_1.el.quote(quoteId), ...links] : links).catch(() => { });
+    }
+}
+/**
+ * 单条整合：合并所有 mergeable 单元为一条消息（图片超限则退化为逐条），
+ * mergeable=false 单元独立逐条。
+ */
+async function sendSingle(rt, sender, session, item, opts = {}) {
+    const units = await (0, hooks_1.runStage)(rt, 'compose', { item });
+    const mergeable = units.filter(u => u.mergeable);
+    const standalone = units.filter(u => !u.mergeable);
+    const maxImages = rt.config.singleSendMaxImages || 10;
+    let quote = opts.quoteId;
+    if (mergeable.length) {
+        const imgCount = mergeable.reduce((n, u) => n + u.content.filter(e => e.type === 'image').length, 0);
+        if (imgCount <= maxImages) {
+            const merged = mergeable.flatMap(u => u.content);
+            await sendElements(sender, session, merged, quote);
+            await (0, common_1.delay)(300);
+            quote = undefined; // 仅首条引用原消息
+        }
+        else {
+            for (const u of mergeable) {
+                await sendElements(sender, session, u.content, quote);
+                await (0, common_1.delay)(300);
+                quote = undefined;
+            }
+        }
+    }
+    for (const u of standalone) {
+        await sendElements(sender, session, u.content, quote);
+        await (0, common_1.delay)(300);
+        quote = undefined;
+    }
+}
+/** 逐条发送：每个语义单元一条消息 */
+async function sendSplit(rt, sender, session, item, opts = {}) {
+    const units = await (0, hooks_1.runStage)(rt, 'compose', { item });
+    let quote = opts.quoteId;
+    for (const u of units) {
+        await sendElements(sender, session, u.content, quote);
+        await (0, common_1.delay)(300);
+        quote = undefined;
+    }
+}

package/lib/engine/config.js

@@ -261,5 +261,14 @@ function engineConfigContributions() {
                 { key: 'deduplicationTipText', type: 'string', default: '链接 ${url} 在最近 ${interval} 秒内已解析过，已跳过。', description: '重复解析提示，支持变量 ${url} ${interval}' },
             ],
         }),
+        (0, config_1.defineConfig)({
+            group: '通用链接解析（预留）',
+            fields: [
+                { key: 'genericParseEnabled', type: 'boolean', default: false, description: '对未命中平台声明的链接启用通用解析（预留：暂无实现，开启不生效）' },
+                { key: 'genericLlmBaseUrl', type: 'string', default: '', description: 'LLM 接口 Base URL（OpenAI 兼容格式；预留字段，暂不消费）' },
+                { key: 'genericLlmModel', type: 'string', default: '', description: 'LLM 模型名（预留字段，暂不消费）' },
+                { key: 'genericLlmApiKey', type: 'string', default: '', role: 'secret', description: 'LLM API Key（预留字段，暂不消费）' },
+            ],
+        }),
     ];
 }

package/lib/engine/fetcher.js

@@ -16,6 +16,7 @@ const platform_config_1 = require("./platform-config");
 const translate_1 = require("./translate");
 const tls_client_1 = require("../utils/tls-client");
 const gateway_1 = require("./gateway");
+const hooks_1 = require("../workflow/hooks");
 async function fetchApi(rt, url, type, fieldMapping, platformConf) {
     const { config, http, urlCacheLocal, proxyConfig, cacheTTL } = rt;
     const cacheKey = url;
@@ -53,7 +54,7 @@ async function fetchApi(rt, url, type, fieldMapping, platformConf) {
                         parsed.lang = nativeTr.sourceLang;
                 }
                 if (!translated) {
-                    const generic = await rt.extensions.translate?.(rt, parsed.desc, target, parsed.lang);
+                    const generic = await (0, hooks_1.runStage)(rt, 'translate', { text: parsed.desc, target, sourceLang: parsed.lang });
                     if (generic) {
                         translated = generic.text;
                         provider = generic.provider;

package/lib/engine/flush.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 解析编排（发送层无关）：三层去重 → 并发解析 → gate（NSFW 策略）预处理 → 发送分派。
+ *
+ * 发送由 OutboundSender 完成（Koishi 适配器见 src/sender/koishi-sender.ts）。
+ *
+ * 去重三层（默认全开）：
+ * ① 同消息 URL 去重（含并发竞态）
+ * ② 内容指纹去重（不同链接相同内容只发首个）
+ * ③ title===desc 抑制（engine/parser 与 twitter mapper 内实现）
+ *
+ * 发送分派（优先级）：
+ * enableForward(onebot/satori) → 合并转发
+ * sendStrategy='single'（默认）→ 单条整合；不可行/失败 → 转发 → split
+ * sendStrategy='split' → 逐条
+ */
+import type { ParserRuntime } from './runtime';
+import type { LinkMatch } from '../types';
+import type { OutboundSender, SessionLike } from '../sender';
+export interface FlushOptions {
+    /** 手动命令（parse <url>）显式触发：跳过去重检查（用户明确要求重新解析） */
+    skipDedup?: boolean;
+    /** 注入发送层；缺省取 host.sender */
+    sender?: OutboundSender;
+}
+export declare function flush(rt: ParserRuntime, session: SessionLike, matches: LinkMatch[], opts?: FlushOptions): Promise<void>;

package/lib/engine/flush.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flush = flush;
+const concurrency_1 = require("../utils/concurrency");
+const logger_1 = require("../logger");
+const common_1 = require("../utils/common");
+const platform_config_1 = require("./platform-config");
+const fetcher_1 = require("./fetcher");
+const sender_1 = require("../sender");
+const hooks_1 = require("../workflow/hooks");
+/** 去重键按会话隔离：防的是同一会话内刷屏，不阻断内容跨会话传播 */
+function dedupScopeKey(session, url) {
+    const scope = session?.channelId || session?.guildId || session?.userId || 'global';
+    return `${scope}::${url}`;
+}
+/** gate 预处理：把 ParsedData 转成发送层消费的 ProcessedItem */
+async function processItem(rt, session, platform, text, parsed) {
+    // 各能力一律经阶段管道（基线=直通/不合并/不转换），扩展可注入或替换
+    const requesterId = String(session?.userId || 'unknown');
+    const images = [];
+    // 同源切图合并：四宫格/九宫格/n×n 宫格与水平/垂直切分条带识别为一张母图的分片，合成后发送；
+    // 识别失败 / ffmpeg 不可用 / 审核 fail-closed → 回退逐张处理
+    let mergedSent = false;
+    if (rt.config.mergeSameOriginImages !== false && (parsed.images || []).length >= 2) {
+        try {
+            const merged = await (0, hooks_1.runStage)(rt, 'merge', { urls: parsed.images });
+            if (merged) {
+                const outcome = await (0, hooks_1.runStage)(rt, 'media.merged', { platform, buffer: merged.buffer, refUrl: parsed.images[0] });
+                if (outcome) {
+                    images.push(outcome);
+                    mergedSent = true;
+                }
+                else
+                    (0, logger_1.debugLog)('合并图未过内容安全策略，回退逐张处理');
+            }
+        }
+        catch (e) {
+            (0, logger_1.debugLog)(`切图合并跳过（${e?.message || e}）`);
+        }
+    }
+    if (!mergedSent) {
+        for (const url of (parsed.images || [])) {
+            images.push(await (0, hooks_1.runStage)(rt, 'media.image', { platform, url, kind: 'image' }));
+        }
+    }
+    const avatar = parsed.avatar ? await (0, hooks_1.runStage)(rt, 'media.image', { platform, url: parsed.avatar, kind: 'avatar' }) : { kind: 'drop' };
+    const cover = (parsed.cover && parsed.type !== 'image' && parsed.type !== 'live_photo' && parsed.type !== 'live')
+        ? await (0, hooks_1.runStage)(rt, 'media.image', { platform, url: parsed.cover, kind: 'cover' })
+        : null;
+    const video = parsed.video
+        ? await (0, hooks_1.runStage)(rt, 'media.video', { platform, videoUrl: parsed.video, coverUrl: parsed.cover || '', meta: { title: parsed.title, author: parsed.author, requesterId } })
+        : { kind: 'raw', url: '' };
+    // 推文动图：按配置转 GIF（仅合规视频；转换失败回退原视频）
+    let gif = null;
+    if (parsed.isGif && video.kind === 'raw' && video.url && rt.config.gifConvertEnabled !== false) {
+        gif = await (0, hooks_1.runStage)(rt, 'transcode', {
+            url: video.url, durationSec: parsed.duration,
+            opts: {
+                maxWidth: rt.config.gifMaxWidth || 480,
+                fps: rt.config.gifFps || 15,
+                maxDurationSec: rt.config.gifMaxDurationSec || 15,
+            },
+        });
+    }
+    // 多视频推文：其余视频逐条过 gate 与 GIF 转换；封面单独审核、随行展示，视频判定用各自封面
+    const extraVideos = [];
+    const extraGifs = [];
+    const extraCovers = [];
+    for (const ev of parsed.extraVideos || []) {
+        const evCover = ev.cover || parsed.cover || '';
+        extraCovers.push(evCover
+            ? await (0, hooks_1.runStage)(rt, 'media.image', { platform, url: evCover, kind: 'cover' })
+            : null);
+        const outcome = await (0, hooks_1.runStage)(rt, 'media.video', { platform, videoUrl: ev.url, coverUrl: evCover, meta: { title: parsed.title, author: parsed.author, requesterId } });
+        extraVideos.push(outcome);
+        if (ev.isGif && outcome.kind === 'raw' && outcome.url && rt.config.gifConvertEnabled !== false) {
+            extraGifs.push(await (0, hooks_1.runStage)(rt, 'transcode', {
+                url: outcome.url, durationSec: ev.duration || 0,
+                opts: {
+                    maxWidth: rt.config.gifMaxWidth || 480,
+                    fps: rt.config.gifFps || 15,
+                    maxDurationSec: rt.config.gifMaxDurationSec || 15,
+                },
+            }));
+        }
+        else {
+            extraGifs.push(null);
+        }
+    }
+    return { text, parsed, images, avatar, cover, video, gif, extraVideos, extraGifs, extraCovers };
+}
+async function flush(rt, session, matches, opts = {}) {
+    const sender = opts.sender ?? rt.host.sender;
+    if (!sender)
+        throw new Error('flush: 未提供 OutboundSender（请通过 opts.sender 或 host.sender 注入）');
+    const { config, dedupCache, contentDedupCache } = rt;
+    (0, logger_1.debugLog)(`开始解析 ${matches.length} 个链接`);
+    const items = [];
+    const errors = [];
+    const limiter = new concurrency_1.ConcurrencyLimiter(config.maxConcurrent || 3);
+    // 去重层①：同消息 URL 去重（保序）
+    const seenUrl = new Set();
+    const uniqueMatches = matches.filter((m) => {
+        const key = m.url.replace(/\/+$/, '');
+        if (seenUrl.has(key))
+            return false;
+        seenUrl.add(key);
+        return true;
+    });
+    const promises = uniqueMatches.map(async (match) => {
+        await limiter.acquire();
+        try {
+            const platformEnabled = config.platformEnabled?.[match.type] ?? true;
+            if (!platformEnabled && !match.type.startsWith('custom_')) {
+                (0, logger_1.debugLog)(`平台 ${match.type} 已禁用，跳过链接: ${match.url}`);
+                return;
+            }
+            const dedupEnabled = !opts.skipDedup && config.enableDeduplication !== false && config.deduplicationInterval > 0;
+            const scopeKey = dedupScopeKey(session, match.url);
+            if (dedupEnabled) {
+                const lastTime = dedupCache.get(scopeKey);
+                if (lastTime && (Date.now() - lastTime < config.deduplicationInterval * 1000)) {
+                    (0, logger_1.debugLog)(`跳过重复链接: ${match.url}`);
+                    const shortUrl = match.url.length > 80 ? match.url.slice(0, 80) + '...' : match.url;
+                    const tip = (0, common_1.getText)(config, 'deduplicationTipText').replace(/\$\{url\}/g, shortUrl).replace(/\$\{interval\}/g, String(config.deduplicationInterval));
+                    await sender.send(session, [sender_1.el.text(tip)]).catch(() => { });
+                    return;
+                }
+            }
+            logger_1.logger.info(`解析链接: ${match.url} (${match.type})`);
+            const platformConf = (0, platform_config_1.getPlatformConfig)(rt, match.type);
+            const result = await (0, fetcher_1.processSingleUrl)(rt, match.url, match.type, platformConf.fieldMapping, platformConf);
+            if (result.success) {
+                if (dedupEnabled) {
+                    // 去重层②：内容指纹按会话隔离；不同链接相同内容只发首个
+                    const fp = dedupScopeKey(session, (0, common_1.contentFingerprint)(result.data.parsed));
+                    const lastDedup = contentDedupCache.get(fp);
+                    if (lastDedup && (Date.now() - lastDedup < config.deduplicationInterval * 1000)) {
+                        (0, logger_1.debugLog)(`跳过重复内容: ${match.url}`);
+                        return;
+                    }
+                    contentDedupCache.set(fp, Date.now());
+                    dedupCache.set(scopeKey, Date.now());
+                }
+                items.push(await processItem(rt, session, match.type, result.data.text, result.data.parsed));
+            }
+            else {
+                const displayUrl = match.url.length > 80 ? match.url.slice(0, 80) + '...' : match.url;
+                const item = (0, common_1.getText)(config, 'parseErrorItemFormat').replace(/\$\{url\}/g, displayUrl).replace(/\$\{msg\}/g, result.msg);
+                errors.push(item);
+            }
+        }
+        finally {
+            limiter.release();
+        }
+    });
+    await Promise.all(promises);
+    if (errors.length)
+        await sender.send(session, [sender_1.el.text(`${(0, common_1.getText)(config, 'parseErrorPrefix')}\n${errors.join('\n')}`)]);
+    if (!items.length)
+        return;
+    await (0, hooks_1.runStage)(rt, 'send', { items, session, sender, quoteId: session?.messageId });
+}

package/lib/engine/forward.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 合并转发模式：把每个语义单元（MessageUnit）构建为一个转发气泡。
+ *
+ * 发送层无关：构建 ForwardBubble[]，由 OutboundSender.sendForward 翻译为
+ * 宿主实现（Koishi 为 <message forward> 嵌套 <message><author>）。
+ * 仅一个气泡时不打包卡片，直接发送。
+ */
+import type { ParserRuntime } from './runtime';
+import type { OutboundSender, SessionLike } from '../sender';
+import type { ProcessedItem } from './compose';
+export declare function buildForwardNode(_session: any, content: any, botName: string): {
+    content: any;
+    name: string;
+};
+export declare function sendForward(rt: ParserRuntime, sender: OutboundSender, session: SessionLike, items: ProcessedItem[]): Promise<void>;

package/lib/engine/forward.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildForwardNode = buildForwardNode;
+exports.sendForward = sendForward;
+const common_1 = require("../utils/common");
+const logger_1 = require("../logger");
+const hooks_1 = require("../workflow/hooks");
+// 保持兼容：旧签名 buildForwardNode(session, content, botName) 曾用于构建气泡；
+// 发送层无关后由 OutboundSender.sendForward 负责，占位导出避免外部引用断裂。
+function buildForwardNode(_session, content, botName) {
+    return { content, name: botName };
+}
+async function sendForward(rt, sender, session, items) {
+    const { config } = rt;
+    const botName = config.botName || '视频解析机器人';
+    const bubbles = [];
+    const total = items.length;
+    for (let i = 0; i < total; i++) {
+        const item = items[i];
+        const units = await (0, hooks_1.runStage)(rt, 'compose', { item });
+        // 多 item 时给概述文字加序号前缀
+        if (total > 1) {
+            for (const u of units) {
+                const txt = u.content.find((e) => e.type === 'text');
+                if (txt && txt.type === 'text') {
+                    txt.text = `【${i + 1}/${total}】\n${txt.text}`;
+                    break;
+                }
+            }
+        }
+        // mergeable 单元（概述+图片+提示）合并为第一个气泡；非 mergeable（视频文件/取件码/混淆图）各占一个气泡
+        const mergeable = units.filter(u => u.mergeable);
+        const standalone = units.filter(u => !u.mergeable);
+        if (mergeable.length)
+            bubbles.push({ content: mergeable.flatMap(u => u.content), name: botName });
+        for (const u of standalone)
+            bubbles.push({ content: u.content, name: botName });
+    }
+    // 仅一条消息：不打包转发卡片，直接发送
+    if (bubbles.length === 1) {
+        await sender.send(session, bubbles[0].content, config.retryTimes);
+        return;
+    }
+    const MAX_BUBBLES = 50;
+    for (let i = 0; i < bubbles.length; i += MAX_BUBBLES) {
+        const batch = bubbles.slice(i, i + MAX_BUBBLES);
+        try {
+            await sender.sendForward(session, batch, config.retryTimes);
+        }
+        catch (err) {
+            logger_1.logger.error('合并转发失败，降级逐条发送:', err);
+            for (const item of items) {
+                for (const u of await (0, hooks_1.runStage)(rt, 'compose', { item })) {
+                    await sender.send(session, u.content).catch(() => { });
+                    await (0, common_1.delay)(300);
+                }
+            }
+            return;
+        }
+    }
+}

package/lib/engine/generic.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 通用链接解析（预留，暂不实现）：对未命中任何平台声明的链接的基础解析能力。
+ *
+ * 设计：
+ * - 经 'parse.generic' 工作流阶段调度（见 workflow/hooks.ts）；
+ * - 基线实现 = 未实现（返回 null）——链路保持现状：非平台链接不进入解析流程；
+ * - 后续实现可由宿主或扩展 replace('parse.generic') 注入
+ *   （OG 元信息抽取 / 页面结构化 / LLM 归纳，source 字段标注来源）；
+ * - LLM 接口仅预留契约：engineConfigContributions() 的「通用链接解析（预留）」组
+ *   提供 baseUrl/model/apiKey 配置位，暂无消费方，开关默认关闭。
+ */
+export interface GenericLinkInput {
+    url: string;
+}
+export interface GenericLinkResult {
+    title?: string;
+    desc?: string;
+    images: string[];
+    /** 解析来源：og=OG 元信息 / html=页面结构化 / llm=模型归纳 */
+    source?: 'og' | 'html' | 'llm';
+}
+/** LLM 增强预留接口（字段与「通用链接解析（预留）」配置组一一对应） */
+export interface LlmOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    model?: string;
+}
+/** 通用解析器实现契约（replace('parse.generic') 的注入形态） */
+export interface GenericLinkParser {
+    parse(input: GenericLinkInput, rt: any): Promise<GenericLinkResult | null>;
+}

package/lib/engine/generic.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * 通用链接解析（预留，暂不实现）：对未命中任何平台声明的链接的基础解析能力。
+ *
+ * 设计：
+ * - 经 'parse.generic' 工作流阶段调度（见 workflow/hooks.ts）；
+ * - 基线实现 = 未实现（返回 null）——链路保持现状：非平台链接不进入解析流程；
+ * - 后续实现可由宿主或扩展 replace('parse.generic') 注入
+ *   （OG 元信息抽取 / 页面结构化 / LLM 归纳，source 字段标注来源）；
+ * - LLM 接口仅预留契约：engineConfigContributions() 的「通用链接解析（预留）」组
+ *   提供 baseUrl/model/apiKey 配置位，暂无消费方，开关默认关闭。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/engine/runtime.d.ts

@@ -1,23 +1,24 @@
 /**
- * 运行时构建（自宿主 runtime 下沉，平台无关）。
+ * 运行时装配（本文件在 core 内，平台无关）。
  *
- * 平台定义列表（defs）由调用方传入：
- * - koishi 兼容层传内置 BUILTIN_PLATFORMS（本地 definitions）
- * - CLI 传 collectPlatformDefinitions()（已安装的 @sns-parse/platform-*）
- * 默认扩展实现同样由宿主注入（loadExtensionImplementations() 发现已安装 ext-*）；
- * core 只负责调度，不持有任何功能实现。
+ * 平台定义列表（defs）由宿主按已加载平台插件声明注入：
+ * - koishi 兼容层：collectPlatformDefinitions(anchor)（聚合包 + 粒度包并集）
+ * - CLI：collectPlatformDefinitions()
+ * 工作流阶段基线在 createDefaultPipeline()，扩展经 WorkflowExtension.setup(hooks) 注入/替换。
+ * core 不依赖任何扩展包、不含扩展实现。
  */
 import { AxiosInstance } from 'axios';
 import type { ParsedData, CustomPlatformConfig } from '../types';
 import type { VideoParserHost } from '../host';
-import type { VideoParserExtensions } from '../extensions';
+import type { WorkflowExtension } from '../extensions';
 import type { PlatformDefinition } from '../platform';
 import { SimpleLRUCache } from '../utils/cache';
 import { type DedicatedApiMaps } from './gateway';
+import type { Pipeline } from '../workflow/hooks';
 export interface ParserRuntime {
-    /** 宿主抽象（core 统一入口） */
+    /** 宿主适配（core 统一入口） */
     host: VideoParserHost;
-    /** 过渡期兼容字段：底层上下文（等同于 host.context） */
+    /** 仅在特化字段：底层运行模块（等同于 host.context） */
     ctx: any;
     config: any;
     http: AxiosInstance;
@@ -34,17 +35,19 @@ export interface ParserRuntime {
         pattern: RegExp;
         type: string;
     }[];
-    /** 平台定义列表（原生解析/翻译钩子由 fetcher 查找使用） */
+    /** 平台定义列表（原生解析/原生翻译 fetcher 阶段使用） */
     defs: PlatformDefinition[];
-    /** 平台专属端点映射（由 defs 计算；getPlatformConfig 使用） */
+    /** 平台专属 API 映射（由 defs 推导；getPlatformConfig 使用） */
     dedicatedApis: DedicatedApiMaps;
-    /** 扩展能力（默认实现 + 宿主覆盖） */
-    extensions: VideoParserExtensions;
+    /** 已加载扩展片段（能力位/配置贡献查询用；实现经管道注入） */
+    extensions: WorkflowExtension[];
+    /** 工作流阶段管道（基线 + 扩展注入） */
+    pipeline: Pipeline;
 }
 export interface CreateRuntimeOptions {
-    /** 平台定义列表（内置或已安装包收集）；缺省为空（仅自定义平台规则可用） */
+    /** 平台定义列表（按用户已加载插件声明；缺省为空，只认自定义平台配置） */
     defs?: PlatformDefinition[];
-    /** 默认扩展实现（koishi 层含 NSFW；CLI 可用 createCoreExtensions） */
-    defaultExtensions?: VideoParserExtensions;
+    /** 扩展片段（setup 钩子注入；后注册者胜） */
+    extensions?: WorkflowExtension[];
 }
 export declare function createRuntime(source: any, config: any, opts?: CreateRuntimeOptions): ParserRuntime;