@sns-parse/core 0.3.0-alpha.1 → 0.4.0-alpha.10

package/lib/utils/merge.d.ts

@@ -0,0 +1,64 @@
+import type { ParserRuntime } from '../engine/runtime';
+import { type ImageSize } from './image-size';
+export type MergeLayout = {
+    kind: 'grid';
+    cols: number;
+    rows: number;
+} | {
+    kind: 'v';
+} | {
+    kind: 'h';
+};
+/** 仅凭数量与尺寸给出全部可行布局（内容验证前） */
+export declare function candidateLayouts(n: number, sizes: ImageSize[]): MergeLayout[];
+export interface SeamVerdict {
+    /** false = 接缝不可验证（边界带平坦，无纹理可判）或不连续 */
+    ok: boolean;
+    score: number;
+    /** 证据明细（供 debug 日志） */
+    dir: 'V' | 'H';
+    from: number;
+    to: number;
+    /** 边界带高频纹理能量（两侧最大值；低于 TEXTURE_MIN 即不可验证） */
+    texture: number;
+    /** 平滑后接缝差 */
+    trendMAD: number;
+    /** 片内自然步进基线 */
+    baseline: number;
+    /** 结论文案 */
+    reason: string;
+}
+/** 内容验证：所有接缝（趋势+纹理）均通过才成立；接缝总数 ≥3 时允许至多一条
+ *  「边界容差缝」（比值 ∈ [3,5)——平台独立重压缩的典型错位幅度；多条缝相互
+ *  印证才可信，2 缝场景证据不足不放行；平坦不可验证缝不参与容差）。
+ *  返回最大接缝比值与逐缝证据。 */
+export declare function verifyLayout(layout: MergeLayout, grays: Buffer[]): {
+    pass: boolean;
+    score: number;
+    seams: SeamVerdict[];
+};
+/** 内容识别：候选布局逐一经接缝连续性验证，取通过者中比值最小的一个 */
+export declare function detectMergeLayout(sizes: ImageSize[], grays: Buffer[]): MergeLayout | null;
+/** 布局名（日志用） */
+export declare function layoutName(layout: MergeLayout): string;
+/**
+ * 候选布局逐一验证并产出证据链；返回通过者中证据最强（worst 接缝比值最小）的一个。
+ * 每次调用都会把逐候选、逐接缝的判定依据写入 debug 日志（含尺寸与灰度行数）。
+ */
+export declare function pickMergeLayout(sizes: ImageSize[], grays: Buffer[]): {
+    layout: MergeLayout;
+    score: number;
+    seams: SeamVerdict[];
+} | null;
+/** xstack 均匀网格布局串（各片已统一缩放为 w×h，行优先） */
+export declare function xstackLayout(cols: number, rows: number, w: number, h: number): string;
+/** 生成 ffmpeg filter_complex（输出标签恒为 [out]，导出供测试） */
+export declare function buildMergeFilter(n: number, layout: MergeLayout, sizes: ImageSize[]): string;
+/**
+ * 下载 → 灰度解码 → 内容识别接缝 → 合并。
+ * 不构成母图切片（接缝不连续）或任一环节失败 → null。
+ */
+export declare function mergeImages(rt: ParserRuntime, urls: string[]): Promise<{
+    buffer: Buffer;
+    layout: MergeLayout;
+} | null>;

package/lib/utils/merge.js

@@ -0,0 +1,402 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.candidateLayouts = candidateLayouts;
+exports.verifyLayout = verifyLayout;
+exports.detectMergeLayout = detectMergeLayout;
+exports.layoutName = layoutName;
+exports.pickMergeLayout = pickMergeLayout;
+exports.xstackLayout = xstackLayout;
+exports.buildMergeFilter = buildMergeFilter;
+exports.mergeImages = mergeImages;
+/**
+ * 同源切图识别与合并（纯内容识别，不依赖 URL/文件名等外部信息）：
+ * - 候选布局：n∈{4,9,16} 且各片等尺寸 → n×n 宫格；各片同宽 → 垂直堆叠；各片同高 → 水平拼接
+ * - 内容验证：ffmpeg 解码为 256 宽灰度图，比较接缝两侧边界行/列的平均绝对差（MAD），
+ *   与图片内部相邻行/列的自然差异比较——母图切片在接缝处连续（比值≈1），无关图片差异显著（比值≫1）
+ * - 合并：宫格 xstack / 垂直 vstack / 水平 hstack
+ *
+ * 识别/解码/ffmpeg 任一环节失败均返回 null，调用方回退逐张发送。
+ */
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+const promises_1 = require("fs/promises");
+const os_1 = require("os");
+const path_1 = require("path");
+const image_size_1 = require("./image-size");
+const gif_1 = require("./gif");
+const logger_1 = require("../logger");
+const MAX_PIECES = 12;
+/** 同一母图切出的分片尺寸精确相等，仅留极小容差防探测/编解码舍入 */
+const DIM_TOLERANCE = 2;
+const MAX_OUTPUT_SIDE = 4096;
+const MAX_TOTAL_BYTES = 150 * 1048576;
+/** 灰度归一化宽度（边界行/列向量长度基准） */
+const GRAY_W = 256;
+/** 列向量统一重采样长度 */
+const COL_LEN = 64;
+/** 接缝差异 / 内部自然差异 的判定阈值（母图切片 ≈1，无关图片 ≫1；下限 3 防平坦图除零） */
+const BOUNDARY_THRESH = 3.0;
+const MAD_FLOOR = 3.0;
+/** 单缝边界容差：平台（如 X）对各分片独立重压缩会让个别接缝低频轻微错位。
+ *  仅当接缝总数 ≥3（≥4 图，多条缝相互印证）且恰好一条落在
+ *  [BOUNDARY_THRESH, BORDERLINE_THRESH)、其余全部通过时放行；平坦不可验证缝不参与容差 */
+const BORDERLINE_THRESH = 5.0;
+const BORDERLINE_MAX = 1;
+const BORDERLINE_MIN_SEAMS = 3;
+/** 边界带纹理能量下限：低于此值视为「不可验证接缝」（相似背景/平边照片会骗过亮度对比） */
+const TEXTURE_MIN = 4.0;
+/* ---------- 尺寸候选 ---------- */
+function dimsEqual(a, b, tol) {
+    return Math.abs(a.width - b.width) <= tol && Math.abs(a.height - b.height) <= tol;
+}
+/** 仅凭数量与尺寸给出全部可行布局（内容验证前） */
+function candidateLayouts(n, sizes) {
+    if (n < 2 || n > MAX_PIECES)
+        return [];
+    if (sizes.some((s) => !s || s.width < 8 || s.height < 8))
+        return [];
+    const out = [];
+    const sqrt = Math.sqrt(n);
+    if (Number.isInteger(sqrt) && sizes.every((s) => dimsEqual(s, sizes[0], DIM_TOLERANCE))) {
+        out.push({ kind: 'grid', cols: sqrt, rows: sqrt });
+    }
+    if (sizes.every((s) => Math.abs(s.width - sizes[0].width) <= DIM_TOLERANCE))
+        out.push({ kind: 'v' });
+    if (sizes.every((s) => Math.abs(s.height - sizes[0].height) <= DIM_TOLERANCE))
+        out.push({ kind: 'h' });
+    return out;
+}
+/* ---------- 灰度边界向量 ---------- */
+/** 解码为固定宽度灰度原始流（buf = rows × GRAY_W 字节） */
+function toGray(file) {
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)((0, gif_1.resolveFfmpeg)(), [
+            '-hide_banner', '-loglevel', 'error', '-i', file,
+            '-vf', `scale=${GRAY_W}:-2:flags=area,format=gray`, '-f', 'rawvideo', 'pipe:1',
+        ]);
+        const chunks = [];
+        child.stdout.on('data', (d) => chunks.push(d));
+        child.stderr.on('data', (d) => reject(new Error(d.toString().slice(0, 120))));
+        child.on('error', (e) => reject(e));
+        child.on('close', (code) => {
+            const buf = Buffer.concat(chunks);
+            if (code === 0 && buf.length >= GRAY_W * 2)
+                resolve(buf);
+            else
+                reject(new Error(`gray decode exit ${code}`));
+        });
+    });
+}
+function grayRows(g) {
+    return Math.floor(g.length / GRAY_W);
+}
+/** 取一行（256 长） */
+function rowOf(g, r) {
+    const rows = grayRows(g);
+    const rr = Math.min(Math.max(r, 0), rows - 1);
+    const out = new Float32Array(GRAY_W);
+    for (let x = 0; x < GRAY_W; x++)
+        out[x] = g[rr * GRAY_W + x];
+    return out;
+}
+/** 取一列（重采样到 COL_LEN，适配各片灰度高度不一） */
+function colOf(g, c) {
+    const rows = grayRows(g);
+    const cc = Math.min(Math.max(c, 0), GRAY_W - 1);
+    const out = new Float32Array(COL_LEN);
+    for (let i = 0; i < COL_LEN; i++) {
+        const y = Math.min(rows - 1, Math.round((i / (COL_LEN - 1)) * (rows - 1)));
+        out[i] = g[y * GRAY_W + cc];
+    }
+    return out;
+}
+function mad(a, b) {
+    let sum = 0;
+    for (let i = 0; i < a.length; i++)
+        sum += Math.abs(a[i] - b[i]);
+    return sum / a.length;
+}
+/** 滑动平均（提取平滑趋势） */
+function smooth(v) {
+    const win = Math.max(3, Math.floor(v.length / 16) | 1);
+    const out = new Float32Array(v.length);
+    let sum = 0;
+    for (let i = 0; i < v.length; i++) {
+        sum += v[i];
+        if (i >= win)
+            sum -= v[i - win];
+        out[i] = sum / Math.min(i + 1, win);
+    }
+    return out;
+}
+/** 去趋势残差（高频纹理成分） */
+function residual(v) {
+    const s = smooth(v);
+    const out = new Float32Array(v.length);
+    for (let i = 0; i < v.length; i++)
+        out[i] = v[i] - s[i];
+    return out;
+}
+function std(v) {
+    let mean = 0;
+    for (let i = 0; i < v.length; i++)
+        mean += v[i];
+    mean /= v.length;
+    let acc = 0;
+    for (let i = 0; i < v.length; i++)
+        acc += (v[i] - mean) ** 2;
+    return Math.sqrt(acc / v.length);
+}
+/**
+ * 单条接缝裁决：
+ * - 可验证性：任一侧边界带高频纹理能量不足（TEXTURE_MIN）→ 拒绝（平坦边缘无法证明连续）
+ * - 连续性：低频成分（平滑后）的边界差 vs 片内相邻行/列的自然步进，比值 < 阈值才通过。
+ *   高频纹理逐行天然去相关、不能作匹配信号，先平滑剔除；基线取各自片内相邻对
+ *   （不可跨片比较，否则无关片间差异会稀释接缝信号）。
+ */
+function judgeSeam(edgeA, edgeB, dir, from, to, innerPairs) {
+    const texture = Math.max(std(residual(edgeA)), std(residual(edgeB)));
+    const mk = (ok, score, reason, trendMAD = 0, baseline = 0) => ({ ok, score, dir, from, to, texture, trendMAD, baseline, reason });
+    if (texture < TEXTURE_MIN)
+        return mk(false, Infinity, `纹理能量 ${texture.toFixed(1)} < ${TEXTURE_MIN}，平坦边缘不可验证`);
+    const sA = smooth(edgeA);
+    const sB = smooth(edgeB);
+    const pairs = innerPairs();
+    const innerTrend = pairs.map(([p, q]) => mad(smooth(p), smooth(q)));
+    const baseline = innerTrend.reduce((t, s) => t + s, 0) / innerTrend.length;
+    const trendRef = Math.max(baseline, MAD_FLOOR);
+    const trendMAD = mad(sA, sB);
+    const score = trendMAD / trendRef;
+    return mk(score < BOUNDARY_THRESH, score, score < BOUNDARY_THRESH
+        ? `连续（趋势差 ${trendMAD.toFixed(1)} / 基线 ${trendRef.toFixed(1)} = ${score.toFixed(2)} < ${BOUNDARY_THRESH}，纹理 ${texture.toFixed(1)}）`
+        : `不连续（趋势差 ${trendMAD.toFixed(1)} / 基线 ${trendRef.toFixed(1)} = ${score.toFixed(2)} ≥ ${BOUNDARY_THRESH}，纹理 ${texture.toFixed(1)}）`, trendMAD, baseline);
+}
+/** 垂直接缝：A 末行 vs B 首行（基线取各自片内相邻行对） */
+function seamVerdictV(a, b, from, to) {
+    const r = grayRows(a);
+    return judgeSeam(rowOf(a, r - 1), rowOf(b, 0), 'V', from, to, () => [
+        [rowOf(a, r - 2), rowOf(a, r - 1)],
+        [rowOf(a, r - 3), rowOf(a, r - 2)],
+        [rowOf(b, 1), rowOf(b, 0)],
+        [rowOf(b, 2), rowOf(b, 1)],
+    ]);
+}
+/** 水平接缝：A 末列 vs B 首列（基线取各自片内相邻列对） */
+function seamVerdictH(a, b, from, to) {
+    return judgeSeam(colOf(a, GRAY_W - 1), colOf(b, 0), 'H', from, to, () => [
+        [colOf(a, GRAY_W - 2), colOf(a, GRAY_W - 1)],
+        [colOf(a, GRAY_W - 3), colOf(a, GRAY_W - 2)],
+        [colOf(b, 1), colOf(b, 0)],
+        [colOf(b, 2), colOf(b, 1)],
+    ]);
+}
+/** 内容验证：所有接缝（趋势+纹理）均通过才成立；接缝总数 ≥3 时允许至多一条
+ *  「边界容差缝」（比值 ∈ [3,5)——平台独立重压缩的典型错位幅度；多条缝相互
+ *  印证才可信，2 缝场景证据不足不放行；平坦不可验证缝不参与容差）。
+ *  返回最大接缝比值与逐缝证据。 */
+function verifyLayout(layout, grays) {
+    const seams = [];
+    const n = grays.length;
+    if (layout.kind === 'v') {
+        for (let i = 0; i + 1 < n; i++)
+            seams.push(seamVerdictV(grays[i], grays[i + 1], i, i + 1));
+    }
+    else if (layout.kind === 'h') {
+        for (let i = 0; i + 1 < n; i++)
+            seams.push(seamVerdictH(grays[i], grays[i + 1], i, i + 1));
+    }
+    else {
+        const { cols } = layout;
+        for (let i = 0; i < n; i++) {
+            if (i % cols < cols - 1 && i + 1 < n)
+                seams.push(seamVerdictH(grays[i], grays[i + 1], i, i + 1));
+            if (i + cols < n)
+                seams.push(seamVerdictV(grays[i], grays[i + cols], i, i + cols));
+        }
+    }
+    if (!seams.length)
+        return { pass: false, score: Infinity, seams };
+    const worst = Math.max(...seams.map((v) => v.score));
+    const failed = seams.filter((v) => !v.ok);
+    const borderline = failed.filter((v) => v.score < BORDERLINE_THRESH);
+    const pass = seams.every((v) => v.ok)
+        || (seams.length >= BORDERLINE_MIN_SEAMS && borderline.length <= BORDERLINE_MAX && failed.length === borderline.length);
+    return { pass, score: worst, seams };
+}
+/** 内容识别：候选布局逐一经接缝连续性验证，取通过者中比值最小的一个 */
+function detectMergeLayout(sizes, grays) {
+    return pickMergeLayout(sizes, grays)?.layout ?? null;
+}
+/** 布局名（日志用） */
+function layoutName(layout) {
+    return layout.kind === 'grid' ? `网格 ${layout.cols}x${layout.rows}` : layout.kind === 'v' ? '竖堆（水平切分）' : '横拼（垂直切分）';
+}
+/**
+ * 候选布局逐一验证并产出证据链；返回通过者中证据最强（worst 接缝比值最小）的一个。
+ * 每次调用都会把逐候选、逐接缝的判定依据写入 debug 日志（含尺寸与灰度行数）。
+ */
+function pickMergeLayout(sizes, grays) {
+    const candidates = candidateLayouts(sizes.length, sizes);
+    (0, logger_1.debugLog)(`同源合并候选：${sizes.length} 张，尺寸 ${sizes.map((s) => `${s.width}x${s.height}`).join(' / ')}，灰度行数 ${grays.map((g) => grayRows(g)).join('/')}`);
+    if (!candidates.length) {
+        (0, logger_1.debugLog)('同源合并候选：无（数量/尺寸组合不构成网格/竖堆/横拼任何可能）');
+        return null;
+    }
+    let best = null;
+    for (const c of candidates) {
+        const { pass, score, seams } = verifyLayout(c, grays);
+        const tolerated = seams.filter((v) => !v.ok).length;
+        const detail = seams.map((v) => `[${v.dir === 'V' ? '竖' : '横'}缝 ${v.from}→${v.to}] ${v.reason}`).join('；');
+        (0, logger_1.debugLog)(`同源合并证据·${layoutName(c)}：${pass ? '通过' : '拒绝'}${pass && tolerated ? `（含 ${tolerated} 条边界容差缝）` : ''}，worst=${score === Infinity ? '∞' : score.toFixed(2)} ⟶ ${detail}`);
+        if (pass && (!best || score < best.score))
+            best = { layout: c, score, seams };
+    }
+    if (best)
+        (0, logger_1.debugLog)(`同源合并裁决：${layoutName(best.layout)}（证据最强，worst 接缝比值 ${best.score.toFixed(2)}）`);
+    else
+        (0, logger_1.debugLog)('同源合并裁决：全部候选未通过内容验证 → 逐张发送');
+    return best;
+}
+/* ---------- ffmpeg 合并 ---------- */
+/** xstack 均匀网格布局串（各片已统一缩放为 w×h，行优先） */
+function xstackLayout(cols, rows, w, h) {
+    const parts = [];
+    for (let i = 0; i < cols * rows; i++) {
+        const x = (i % cols) * w;
+        const y = Math.floor(i / cols) * h;
+        parts.push(`${x}_${y}`);
+    }
+    return parts.join('|');
+}
+/** 生成 ffmpeg filter_complex（输出标签恒为 [out]，导出供测试） */
+function buildMergeFilter(n, layout, sizes) {
+    const chains = [];
+    const stacks = [];
+    const chainOf = (stack, outW, outH) => {
+        if (outW > MAX_OUTPUT_SIDE || outH > MAX_OUTPUT_SIDE) {
+            const scale = Math.min(1, MAX_OUTPUT_SIDE / Math.max(outW, outH));
+            return `${stack}[tmp];[tmp]scale=${Math.round(outW * scale) / 2 * 2}:${Math.round(outH * scale) / 2 * 2}:flags=lanczos[out]`;
+        }
+        return `${stack}[out]`;
+    };
+    if (layout.kind === 'grid') {
+        // 宫格拼图：各片等比缩放进统一格子（不足处黑边补齐——切片场景无补边，杂图集保持各自比例），
+        // 逐片 concat 成帧序列后 tile 出宫格（支持非满宫格，如 7 图 3x3）
+        const cellW = Math.min(Math.max(...sizes.map((s) => s.width)), 1920);
+        const cellH = Math.min(Math.max(...sizes.map((s) => s.height)), 1920);
+        const cw = Math.ceil(cellW / 2) * 2;
+        const ch = Math.ceil(cellH / 2) * 2;
+        for (let i = 0; i < n; i++) {
+            chains.push(`[${i}:v]scale=${cw}:${ch}:force_original_aspect_ratio=decrease:flags=lanczos,pad=${cw}:${ch}:(ow-iw)/2:(oh-ih)/2:color=black,setsar=1[c${i}]`);
+            stacks.push(`[c${i}]`);
+        }
+        chains.push(`${stacks.join('')}concat=n=${n}:v=1:a=0[frames]`);
+        chains.push(chainOf(`[frames]tile=${layout.cols}x${layout.rows}`, layout.cols * cw, layout.rows * ch));
+    }
+    else if (layout.kind === 'v') {
+        const w = Math.max(...sizes.map((s) => s.width));
+        for (let i = 0; i < n; i++)
+            chains.push(`[${i}:v]scale=${w}:-2:flags=lanczos[s${i}]`);
+        for (let i = 0; i < n; i++)
+            stacks.push(`[s${i}]`);
+        chains.push(chainOf(`${stacks.join('')}vstack=inputs=${n}`, w, sizes.reduce((t, s) => t + s.height, 0)));
+    }
+    else {
+        const h = Math.max(...sizes.map((s) => s.height));
+        for (let i = 0; i < n; i++)
+            chains.push(`[${i}:v]scale=-2:${h}:flags=lanczos[s${i}]`);
+        for (let i = 0; i < n; i++)
+            stacks.push(`[s${i}]`);
+        chains.push(chainOf(`${stacks.join('')}hstack=inputs=${n}`, sizes.reduce((t, s) => t + s.width, 0), h));
+    }
+    return chains.join(';');
+}
+/** 按魔数给临时文件配扩展名（ffmpeg 也可自行探测，显式更稳） */
+function extOf(buf) {
+    if (buf[0] === 0x89 && buf[1] === 0x50)
+        return 'png';
+    if (buf[0] === 0xff && buf[1] === 0xd8)
+        return 'jpg';
+    if (buf.toString('ascii', 0, 4) === 'RIFF')
+        return 'webp';
+    if (buf.toString('ascii', 0, 4) === 'GIF8')
+        return 'gif';
+    return 'bin';
+}
+const MERGE_UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36';
+function downloadImage(rt, url) {
+    const headers = { 'User-Agent': MERGE_UA };
+    headers['Referer'] = /twimg\.com/.test(url) ? 'https://twitter.com/' : 'https://www.baidu.com/';
+    return rt.http.get(url, { responseType: 'arraybuffer', timeout: 30000, headers })
+        .then((res) => Buffer.from(res.data));
+}
+/**
+ * 下载 → 灰度解码 → 内容识别接缝 → 合并。
+ * 不构成母图切片（接缝不连续）或任一环节失败 → null。
+ */
+async function mergeImages(rt, urls) {
+    if (urls.length < 2 || urls.length > MAX_PIECES)
+        return null;
+    let buffers;
+    try {
+        buffers = await Promise.all(urls.map((u) => downloadImage(rt, u)));
+    }
+    catch (e) {
+        (0, logger_1.debugLog)(`切图合并跳过（分片下载失败）：${e?.message || e}`);
+        return null;
+    }
+    const total = buffers.reduce((t, b) => t + b.length, 0);
+    if (total > MAX_TOTAL_BYTES || buffers.some((b) => !b.length))
+        return null;
+    const sizes = buffers.map((b) => (0, image_size_1.probeImageSize)(b));
+    if (sizes.some((s) => !s))
+        return null;
+    const dir = await (0, promises_1.mkdtemp)((0, path_1.join)((0, os_1.tmpdir)(), `vpa-merge-${(0, crypto_1.randomBytes)(4).toString('hex')}-`));
+    try {
+        const files = [];
+        for (let i = 0; i < buffers.length; i++) {
+            const f = (0, path_1.join)(dir, `${i}.${extOf(buffers[i])}`);
+            await (0, promises_1.writeFile)(f, buffers[i]);
+            files.push(f);
+        }
+        // 布局决策（完全由像素内容裁决，不依赖数量规则、链接/文件名与色调风格）：
+        // 网格/竖堆/横拼三种布局候选（按尺寸可能性给出），逐一经接缝内容验证
+        // （亮度趋势 + 去趋势纹理双通道、平坦边缘不可验证即拒绝），
+        // 取通过者中证据最强（接缝比值最小）的一种——真 2x2/3x3 切片网格缝连续、
+        // 长图条带单向连续、无关图全部不过；合并方式由内容区分，均不过则逐张发送
+        let grays;
+        try {
+            grays = await Promise.all(files.map(toGray));
+        }
+        catch (e) {
+            (0, logger_1.debugLog)(`切图合并跳过（灰度解码失败）：${e?.message || e}`);
+            return null;
+        }
+        const picked = pickMergeLayout(sizes, grays);
+        if (!picked)
+            return null;
+        const layout = picked.layout;
+        const filter = buildMergeFilter(files.length, layout, sizes);
+        const args = ['-hide_banner', '-loglevel', 'error', ...files.flatMap((f) => ['-i', f]),
+            '-filter_complex', filter, '-map', '[out]', '-frames:v', '1', '-q:v', '2',
+            '-f', 'image2pipe', '-c:v', 'mjpeg', 'pipe:1'];
+        const out = await new Promise((resolve) => {
+            const child = (0, child_process_1.spawn)((0, gif_1.resolveFfmpeg)(), args);
+            const chunks = [];
+            child.stdout.on('data', (d) => chunks.push(d));
+            child.stderr.on('data', () => { });
+            child.on('error', () => resolve(null));
+            child.on('close', (code) => resolve(code === 0 && chunks.length ? Buffer.concat(chunks) : null));
+        });
+        if (!out) {
+            (0, logger_1.debugLog)(`切图合并失败（ffmpeg 退出非 0），回退逐张发送`);
+            return null;
+        }
+        const desc = layout.kind === 'grid' ? `${layout.cols}x${layout.rows} 宫格` : layout.kind === 'v' ? '垂直堆叠' : '水平拼接';
+        logger_1.logger.info(`同源切图已合并为一张（内容识别：${urls.length} 张 → ${desc}，${Math.round(out.length / 1024)}KB）`);
+        return { buffer: out, layout };
+    }
+    finally {
+        (0, promises_1.rm)(dir, { recursive: true, force: true }).catch(() => { });
+    }
+}

package/lib/utils/tls-client.d.ts

@@ -0,0 +1,30 @@
+/**
+ * TLS 指纹模拟 HTTP 客户端（一次性 CLI 模式）。
+ *
+ * X/Twitter 的 GraphQL 受 Cloudflare TLS 指纹校验保护：普通 Node/axios 的
+ * TLS 握手(JA3/JA4)与 Chrome 不同，会被 CF 直接 403。此模块经
+ * @char46/tlsget-rs（wreq/BoringSSL 内核，Chrome147 指纹）发起请求。
+ *
+ * 每次请求 spawn 一个静态二进制：stdin 进 JSON、stdout 出 JSON。
+ * 无常驻服务、无端口管理、无生命周期问题；musl 环境自动使用静态 musl 构建。
+ * tlsget-rs 为 optionalDependency，未安装时抛出明确错误，调用方据此降级。
+ */
+export interface TlsGetOptions {
+    headers?: Record<string, string>;
+    cookies?: Record<string, string>;
+    timeout?: number;
+    /** HTTP(S) 代理地址（如 http://127.0.0.1:7890），透传给 tlsget-rs 二进制 */
+    proxy?: string;
+}
+export interface TlsResponse {
+    status: number;
+    data: any;
+}
+export declare function tlsGet(url: string, opts?: TlsGetOptions): Promise<TlsResponse>;
+/** 一次性二进制无需常驻进程；保留接口兼容旧调用方与测试 */
+export declare function shutdownTlsClient(): Promise<void>;
+/**
+ * 环境诊断：二进制定位 → 自检 → TLS 指纹回显 → X 边缘探测。
+ * 失败环节即根因，全部结果同时输出到日志。
+ */
+export declare function diagnoseTls(): Promise<string[]>;

package/lib/utils/tls-client.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * TLS 指纹模拟 HTTP 客户端（一次性 CLI 模式）。
+ *
+ * X/Twitter 的 GraphQL 受 Cloudflare TLS 指纹校验保护：普通 Node/axios 的
+ * TLS 握手(JA3/JA4)与 Chrome 不同，会被 CF 直接 403。此模块经
+ * @char46/tlsget-rs（wreq/BoringSSL 内核，Chrome147 指纹）发起请求。
+ *
+ * 每次请求 spawn 一个静态二进制：stdin 进 JSON、stdout 出 JSON。
+ * 无常驻服务、无端口管理、无生命周期问题；musl 环境自动使用静态 musl 构建。
+ * tlsget-rs 为 optionalDependency，未安装时抛出明确错误，调用方据此降级。
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tlsGet = tlsGet;
+exports.shutdownTlsClient = shutdownTlsClient;
+exports.diagnoseTls = diagnoseTls;
+let modPromise = null;
+/** 惰性加载 npm 包装（未安装时不缓存失败，装好后无需重启即可生效） */
+async function getMod() {
+    if (!modPromise) {
+        modPromise = Promise.resolve().then(() => __importStar(require('@char46/tlsget-rs'))).then((m) => m.default || m)
+            .catch(() => {
+            modPromise = null;
+            throw new Error('TLS 指纹模拟工具 @char46/tlsget-rs 未安装（可选依赖）。解析需登录的 X 推文需要它：npm i @char46/tlsget-rs');
+        });
+    }
+    return modPromise;
+}
+async function tlsGet(url, opts = {}) {
+    const mod = await getMod();
+    const r = await mod.tlsGet({
+        url,
+        headers: opts.headers,
+        cookies: opts.cookies,
+        timeoutMs: Math.max(1000, opts.timeout || 30000),
+        proxy: opts.proxy,
+    });
+    return { status: r.status, data: r.body };
+}
+/** 一次性二进制无需常驻进程；保留接口兼容旧调用方与测试 */
+async function shutdownTlsClient() {
+    modPromise = null;
+}
+/**
+ * 环境诊断：二进制定位 → 自检 → TLS 指纹回显 → X 边缘探测。
+ * 失败环节即根因，全部结果同时输出到日志。
+ */
+async function diagnoseTls() {
+    const lines = [];
+    try {
+        const mod = await getMod();
+        const bin = mod.binaryPath?.();
+        if (bin)
+            lines.push(`[1] ✓ 二进制：${bin}`);
+        else
+            lines.push(`[1] ✗ 当前平台 ${process.platform}/${process.arch} 无二进制子包（npm i @char46/tlsget-rs --force 重装）`);
+        try {
+            const st = await mod.selftest();
+            lines.push(`[2] ✓ 自检：v${st.version}，指纹 ${st.emulation}`);
+        }
+        catch (e) {
+            lines.push(`[2] ✗ 二进制无法执行：${e?.message || e}（可能被杀软/安全策略拦截）`);
+        }
+        try {
+            const r = await mod.tlsGet({ url: 'https://tls.peet.ws/api/all', timeoutMs: 20000 });
+            const ja4 = r.body?.tls?.ja4 || '?';
+            const chromeLike = ja4.startsWith('t13d');
+            lines.push(`[3] ${chromeLike ? '✓' : '✗'} TLS 回显：JA4=${ja4}${chromeLike ? '（Chrome 形态）' : '（异常：非浏览器形态）'}`);
+        }
+        catch (e) {
+            lines.push(`[3] ✗ 回显请求失败：${e?.message || e}`);
+        }
+        try {
+            const x = await mod.tlsGet({ url: 'https://x.com/robots.txt', timeoutMs: 20000 });
+            lines.push(`[4] ${x.status === 200 ? '✓' : '✗'} X 边缘探测：HTTP ${x.status}`);
+        }
+        catch (e) {
+            lines.push(`[4] ✗ X 边缘探测失败：${e?.message || e}`);
+        }
+        if (!lines.some(l => l.includes('✗')))
+            lines.push('结论：环境正常。');
+    }
+    catch (e) {
+        lines.push(`✗ 诊断失败：${e?.message || e}`);
+    }
+    return lines;
+}

package/lib/utils/url.d.ts

@@ -0,0 +1,10 @@
+import type { LinkMatch } from '../types';
+export declare function cleanUrl(url: string): string;
+export declare function linkTypeParser(content: string, rules: {
+    pattern: RegExp;
+    type: string;
+}[]): LinkMatch[];
+export declare function extractAllUrlsFromMessage(session: any, rules: {
+    pattern: RegExp;
+    type: string;
+}[]): LinkMatch[];