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

package/lib/engine/parser.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseApiResponse = parseApiResponse;
+const logger_1 = require("../logger");
+const field_mapping_1 = require("../utils/field-mapping");
+const common_1 = require("../utils/common");
+function parseApiResponse(rawInput, maxDescLen, fieldMapping) {
+    // 兼容：响应本身为数组时取首个元素（部分第三方 API 行为）
+    const raw = Array.isArray(rawInput) ? rawInput[0] : rawInput;
+    (0, logger_1.debugLog)('API raw response', raw);
+    let data = raw?.data || {};
+    if (Array.isArray(data))
+        data = data[0] || {};
+    const extra = data.extra || {};
+    const mapField = (name, fallback) => {
+        if (fieldMapping && fieldMapping[name]) {
+            const value = (0, field_mapping_1.getNestedValue)(raw, fieldMapping[name]);
+            if (value !== undefined)
+                return value;
+        }
+        return fallback();
+    };
+    let type = mapField('type', () => {
+        let t = data.type || data.videoType || '';
+        if (!t) {
+            if (data.images?.length > 0 && !data.url)
+                t = 'image';
+            else if (data.live_photo?.length > 0)
+                t = 'live_photo';
+            else if (raw.msg === 'live' || data.live)
+                t = 'live';
+            else
+                t = 'video';
+        }
+        return t;
+    });
+    let authorObj = mapField('author', () => data.author || data.user);
+    let author = '', uid = '', avatar = '';
+    if (authorObj && typeof authorObj === 'object') {
+        author = authorObj.name || authorObj.author || '';
+        uid = String(authorObj.id || authorObj.userID || data.uid || data.userID || data.author_id || '');
+        avatar = authorObj.avatar || data.avatar || '';
+    }
+    else {
+        author = mapField('author', () => data.author || data.auther || '');
+        uid = String(mapField('uid', () => data.uid || data.userID || data.author_id || ''));
+        avatar = mapField('avatar', () => data.avatar || '');
+    }
+    let title = mapField('title', () => data.title || '');
+    let desc = mapField('desc', () => data.desc || data.description || '').slice(0, maxDescLen).trim();
+    const coverRaw = mapField('cover', () => data.cover || '');
+    const cover = coverRaw ? (String(coverRaw).startsWith('http') ? String(coverRaw) : 'https:' + String(coverRaw)) : '';
+    let video = '';
+    let videos = [];
+    const videoBackup = mapField('video_backup', () => data.video_backup);
+    if (Array.isArray(videoBackup) && videoBackup.length) {
+        const bestQ = (0, common_1.pickBestQuality)(videoBackup);
+        videos = bestQ;
+        video = bestQ[0]?.url || '';
+    }
+    if (!video) {
+        const rawVideos = mapField('videos', () => data.videos);
+        if (Array.isArray(rawVideos) && rawVideos.length) {
+            const validVideos = rawVideos.filter((v) => v && v.url);
+            if (validVideos.length) {
+                video = validVideos[0].url;
+                videos = validVideos.map((v) => ({ quality: v.accept?.[0] || 'unknown', url: v.url }));
+            }
+        }
+    }
+    if (!video && data.quality_urls && typeof data.quality_urls === 'object') {
+        const entries = Object.entries(data.quality_urls);
+        videos = entries.map(([label, url]) => ({ quality: label, url: String(url) }));
+        if (videos.length)
+            video = videos[0].url;
+    }
+    if (!video)
+        video = mapField('video', () => data.url || '');
+    if (video && !video.startsWith('http'))
+        video = 'https:' + video;
+    let images = [];
+    // 统一图片地址规范化：兼容大写协议、// 协议相对地址、{url} 对象与数组形式（上游 v1.6.7）
+    const normalizeImageUrl = (img) => {
+        if (typeof img === 'string') {
+            if (!img)
+                return null;
+            return /^https?:\/\//i.test(img) ? img : (/^\/\//.test(img) ? 'https:' + img : 'https:' + img);
+        }
+        if (Array.isArray(img) && img.length)
+            return normalizeImageUrl(img[0]);
+        if (img && typeof img === 'object' && img.url)
+            return normalizeImageUrl(String(img.url));
+        return null;
+    };
+    const directImages = mapField('images', () => data.images);
+    if (Array.isArray(directImages)) {
+        images = directImages.map(normalizeImageUrl).filter((u) => !!u);
+    }
+    else if (Array.isArray(data.imgurl)) {
+        images = data.imgurl.map(normalizeImageUrl).filter((u) => !!u);
+    }
+    else if (directImages && typeof directImages === 'object') {
+        const single = normalizeImageUrl(directImages);
+        if (single)
+            images = [single];
+    }
+    const live_photo = Array.isArray(data.live_photo) ? data.live_photo.filter((lp) => lp && lp.image).map((lp) => ({
+        image: lp.image.startsWith('http') ? lp.image : 'https:' + lp.image,
+        video: lp.video ? (lp.video.startsWith('http') ? lp.video : 'https:' + lp.video) : ''
+    })) : [];
+    if (type === 'live' && live_photo.length > 0 && !data.live) {
+        type = 'live_photo';
+    }
+    const musicCoverRaw = mapField('music_cover', () => data.music?.cover || data.music?.albumCover?.url || '');
+    const musicUrlRaw = mapField('music_url', () => data.music?.url || data.music?.playURL || '');
+    const musicUrlNorm = musicUrlRaw ? (String(musicUrlRaw).startsWith('http') ? String(musicUrlRaw) : 'https:' + String(musicUrlRaw)) : '';
+    const music = {
+        title: mapField('music_title', () => data.music?.title || data.music?.name || ''),
+        author: mapField('music_author', () => data.music?.author || data.music?.artist || ''),
+        cover: musicCoverRaw ? (String(musicCoverRaw).startsWith('http') ? String(musicCoverRaw) : 'https:' + String(musicCoverRaw)) : '',
+        // 过滤占位垃圾值（如即梦接口返回的 map[]），含空白/括号的地址不视为有效链接（上游 v1.6.7）
+        url: /[\s\[\]]/.test(musicUrlNorm) ? '' : musicUrlNorm,
+    };
+    const like = (0, common_1.parseCount)(mapField('like', () => data.like ?? data.statistics?.digg_count ?? data.statistics?.like_count ?? data.statistics?.likes ?? extra.statistics?.digg_count ?? extra.statistics?.like_count ?? extra.statistics?.likes ?? data.attitudes_count ?? 0));
+    const comment = (0, common_1.parseCount)(mapField('comment', () => data.comment ?? data.statistics?.comment_count ?? data.statistics?.comments ?? extra.statistics?.comment_count ?? extra.statistics?.comments ?? data.comments_count ?? 0));
+    const collect = (0, common_1.parseCount)(mapField('collect', () => data.collect ?? data.statistics?.collect_count ?? data.statistics?.favorite_count ?? data.statistics?.favorites ?? extra.statistics?.collect_count ?? extra.statistics?.favorite_count ?? extra.statistics?.favorites ?? data.favorites_count ?? 0));
+    const share = (0, common_1.parseCount)(mapField('share', () => data.share ?? data.statistics?.share_count ?? data.statistics?.forward_count ?? data.statistics?.shares ?? extra.statistics?.share_count ?? extra.statistics?.forward_count ?? extra.statistics?.shares ?? data.reposts_count ?? 0));
+    const play = (0, common_1.parseCount)(mapField('play', () => data.play ?? data.statistics?.play_count ?? data.statistics?.view_count ?? data.statistics?.plays ?? extra.statistics?.play_count ?? extra.statistics?.view_count ?? extra.statistics?.plays ?? data.play_count ?? data.view_count ?? 0));
+    let duration = 0;
+    if (extra.duration_ms) {
+        duration = Math.floor(Number(extra.duration_ms) / 1000);
+    }
+    else {
+        const durRaw = mapField('duration', () => data.duration);
+        if (durRaw) {
+            duration = typeof durRaw === 'string' ? parseInt(durRaw, 10) : Math.floor(Number(durRaw));
+        }
+    }
+    let publishTime = 0;
+    const timeRaw = mapField('publishTime', () => data.time);
+    if (timeRaw) {
+        publishTime = typeof timeRaw === 'number' ? timeRaw : parseInt(timeRaw, 10);
+        if (publishTime < 1000000000000)
+            publishTime *= 1000;
+    }
+    else if (extra.create_time) {
+        publishTime = Number(extra.create_time) * 1000;
+    }
+    const author_followers = (0, common_1.parseCount)(mapField('author_followers', () => extra.author_extra?.follower_count ?? data.author_extra?.follower_count ?? 0));
+    const author_signature = String(mapField('author_signature', () => extra.author_extra?.signature ?? data.author_extra?.signature ?? ''));
+    const admire = (0, common_1.parseCount)(mapField('admire', () => extra.statistics?.admire_count ?? data.statistics?.admire_count ?? 0));
+    title = title.replace(/\[话题\]/g, '');
+    desc = desc.replace(/\[话题\]/g, '');
+    if (title && desc && title.trim() === desc.trim()) {
+        desc = '';
+    }
+    if (title.trim().startsWith('#'))
+        title = '';
+    if (desc.trim().startsWith('#'))
+        desc = '';
+    return { type, title, desc, author, uid, avatar, cover, video, videos, images, live_photo, music, like, comment, collect, share, play, duration, publishTime, author_followers, author_signature, admire };
+}

package/lib/engine/platform-config.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 平台配置装配（自 custom.ts 下沉）：
+ * - buildCustomLinkRules：customPlatforms 关键词 → 链接规则
+ * - buildAuthHeaders：API Key → 鉴权头
+ * - getPlatformConfig：平台专属端点/鉴权/字段映射的逐平台配置
+ *
+ * 专属端点映射来自 rt.dedicatedApis（由 createRuntime 从平台定义列表计算），
+ * 因此本模块不再依赖具体平台清单。
+ */
+import type { ParserRuntime } from './runtime';
+export declare function buildCustomLinkRules(customPlatforms: any[]): {
+    pattern: RegExp;
+    type: string;
+}[];
+export declare function buildAuthHeaders(apiKey: string, authHeaderType: string, customHeaderName: string): Record<string, string>;
+export declare function getPlatformConfig(rt: ParserRuntime, type: string): {
+    apiUrl: string | null;
+    dedicatedFirst: boolean;
+    apiKey: string;
+    authHeaderType: string;
+    customHeaderName: string;
+    fieldMapping?: Record<string, string>;
+    customProxy?: any;
+};

package/lib/engine/platform-config.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCustomLinkRules = buildCustomLinkRules;
+exports.buildAuthHeaders = buildAuthHeaders;
+exports.getPlatformConfig = getPlatformConfig;
+const field_mapping_1 = require("../utils/field-mapping");
+function buildCustomLinkRules(customPlatforms) {
+    if (!Array.isArray(customPlatforms) || customPlatforms.length === 0)
+        return [];
+    return customPlatforms
+        .filter(p => p.keywords)
+        .map(p => {
+        const keywords = p.keywords.split(',').map((s) => s.trim()).filter(Boolean);
+        if (keywords.length === 0)
+            return null;
+        const escaped = keywords.map((k) => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+        const pattern = new RegExp(`https?://[^/\\s"'“”‘’]*(${escaped.join('|')})[^\\s"'“”‘’]*`, 'gi');
+        return { pattern, type: `custom_${p.name}` };
+    })
+        .filter(Boolean);
+}
+function buildAuthHeaders(apiKey, authHeaderType, customHeaderName) {
+    if (!apiKey)
+        return {};
+    if (authHeaderType === 'Bearer')
+        return { 'Authorization': `Bearer ${apiKey}` };
+    if (authHeaderType === 'X-API-Key')
+        return { 'X-API-Key': apiKey };
+    if (authHeaderType === 'Custom' && customHeaderName)
+        return { [customHeaderName]: apiKey };
+    return {};
+}
+function getPlatformConfig(rt, type) {
+    const { config, customPlatforms } = rt;
+    if (type.startsWith('custom_')) {
+        const name = type.slice(7);
+        const custom = customPlatforms.find(p => p.name === name);
+        if (custom) {
+            return {
+                apiUrl: custom.apiUrl,
+                dedicatedFirst: true,
+                apiKey: custom.apiKey || '',
+                authHeaderType: custom.authHeaderType,
+                customHeaderName: custom.customHeaderName,
+                fieldMapping: custom.fieldMapping,
+                customProxy: custom.proxy
+            };
+        }
+        return { apiUrl: null, dedicatedFirst: false, apiKey: '', authHeaderType: 'Bearer', customHeaderName: 'X-API-Key' };
+    }
+    // 网关选择（上游 issue #12）：配置 apiKey → 新网关；否则 → 旧网关
+    const useNewGateway = !!config.apiKey;
+    const maps = rt.dedicatedApis || {};
+    const custom = config.customApis?.find((item) => item.platform === type);
+    let apiUrl = (useNewGateway ? maps.next?.[type] : maps.legacy?.[type]) || null;
+    let apiKey = '';
+    let authHeaderType = 'X-API-Key';
+    let customHeaderName = 'X-API-Key';
+    let fieldMapping = undefined;
+    if (custom && custom.apiUrl) {
+        apiUrl = custom.apiUrl;
+        apiKey = custom.apiKey || '';
+        authHeaderType = custom.authHeaderType || 'Bearer';
+        customHeaderName = custom.customHeaderName || 'X-API-Key';
+        fieldMapping = (0, field_mapping_1.parseFieldMapping)(custom.fieldMapping);
+    }
+    else if (useNewGateway) {
+        apiKey = config.apiKey;
+        authHeaderType = 'X-API-Key';
+    }
+    const dedicatedFirst = config.platformDedicatedFirst?.[type] ?? false;
+    if (!fieldMapping) {
+        fieldMapping = (0, field_mapping_1.parseFieldMapping)(config.globalFieldMapping);
+    }
+    return { apiUrl, dedicatedFirst, apiKey, authHeaderType, customHeaderName, fieldMapping };
+}

package/lib/engine/runtime.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 运行时构建（自宿主 runtime 下沉，平台无关）。
+ *
+ * 平台定义列表（defs）由调用方传入：
+ * - koishi 兼容层传内置 BUILTIN_PLATFORMS（本地 definitions）
+ * - CLI 传 collectPlatformDefinitions()（已安装的 @sns-parse/platform-*）
+ * 默认扩展实现同样注入：koishi 传含 NSFW 的完整默认实现，CLI 传 createCoreExtensions()。
+ */
+import { AxiosInstance } from 'axios';
+import type { ParsedData, CustomPlatformConfig } from '../types';
+import type { VideoParserHost } from '../host';
+import type { VideoParserExtensions } from '../extensions';
+import type { PlatformDefinition } from '../platform';
+import { SimpleLRUCache } from '../utils/cache';
+import { type DedicatedApiMaps } from './gateway';
+export interface ParserRuntime {
+    /** 宿主抽象（core 统一入口） */
+    host: VideoParserHost;
+    /** 过渡期兼容字段：底层上下文（等同于 host.context） */
+    ctx: any;
+    config: any;
+    http: AxiosInstance;
+    proxyConfig: any;
+    cacheTTL: number;
+    dedupCache: SimpleLRUCache<number>;
+    urlCacheLocal: SimpleLRUCache<{
+        data: ParsedData;
+        expire: number;
+    }>;
+    contentDedupCache: SimpleLRUCache<number>;
+    customPlatforms: CustomPlatformConfig[];
+    allRules: {
+        pattern: RegExp;
+        type: string;
+    }[];
+    /** 平台专属端点映射（由 defs 计算；getPlatformConfig 使用） */
+    dedicatedApis: DedicatedApiMaps;
+    /** 扩展能力（默认实现 + 宿主覆盖） */
+    extensions: VideoParserExtensions;
+}
+export interface CreateRuntimeOptions {
+    /** 平台定义列表（内置或已安装包收集）；缺省为空（仅自定义平台规则可用） */
+    defs?: PlatformDefinition[];
+    /** 默认扩展实现（koishi 层含 NSFW；CLI 可用 createCoreExtensions） */
+    defaultExtensions?: VideoParserExtensions;
+}
+export declare function createRuntime(source: any, config: any, opts?: CreateRuntimeOptions): ParserRuntime;
+/** core 自带扩展实现（无 NSFW：CLI / 嵌入式宿主用；koishi 层在其上叠加 NSFW） */
+export declare function createCoreExtensions(): VideoParserExtensions;

package/lib/engine/runtime.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRuntime = createRuntime;
+exports.createCoreExtensions = createCoreExtensions;
+/**
+ * 运行时构建（自宿主 runtime 下沉，平台无关）。
+ *
+ * 平台定义列表（defs）由调用方传入：
+ * - koishi 兼容层传内置 BUILTIN_PLATFORMS（本地 definitions）
+ * - CLI 传 collectPlatformDefinitions()（已安装的 @sns-parse/platform-*）
+ * 默认扩展实现同样注入：koishi 传含 NSFW 的完整默认实现，CLI 传 createCoreExtensions()。
+ */
+const axios_1 = __importDefault(require("axios"));
+const https_proxy_agent_1 = require("https-proxy-agent");
+const host_1 = require("../host");
+const cache_1 = require("../utils/cache");
+const field_mapping_1 = require("../utils/field-mapping");
+const platform_config_1 = require("./platform-config");
+const gateway_1 = require("./gateway");
+const merge_1 = require("../utils/merge");
+const gif_1 = require("../utils/gif");
+const translate_1 = require("./translate");
+function createRuntime(source, config, opts = {}) {
+    const host = (0, host_1.createHost)(source);
+    const ctx = host.context;
+    const extensions = { ...(opts.defaultExtensions || {}), ...(host.extensions || {}) };
+    const dedupCache = new cache_1.SimpleLRUCache(1000, config.deduplicationInterval * 1000);
+    const cacheTTL = (config.cacheTTL || 600) * 1000;
+    const urlCacheLocal = new cache_1.SimpleLRUCache(500, cacheTTL);
+    const contentDedupCache = new cache_1.SimpleLRUCache(1000, config.deduplicationInterval * 1000);
+    const proxyConfig = config.proxy || {};
+    const customPlatforms = (config.customPlatforms || []).map((p) => ({
+        name: p.name,
+        apiUrl: p.apiUrl,
+        apiKey: p.apiKey || '',
+        authHeaderType: p.authHeaderType || 'Bearer',
+        customHeaderName: p.customHeaderName || 'X-API-Key',
+        fieldMapping: (0, field_mapping_1.parseFieldMapping)(p.fieldMapping),
+        proxy: p.proxy || null
+    }));
+    const defs = opts.defs || [];
+    const builtinRules = defs.flatMap(d => d.rules.map(pattern => ({ pattern, type: d.type })));
+    const customRules = (0, platform_config_1.buildCustomLinkRules)(config.customPlatforms || []);
+    const allRules = [...builtinRules, ...customRules];
+    const dedicatedApis = (0, gateway_1.dedicatedApisFrom)(defs);
+    const axiosConfig = {
+        timeout: config.timeout,
+        headers: {
+            'User-Agent': config.userAgent,
+            'Referer': 'https://www.baidu.com/',
+            'Content-Type': 'application/x-www-form-urlencoded'
+        }
+    };
+    if (proxyConfig.enabled && proxyConfig.host) {
+        // axios 内置 proxy 选项对 https 目标存在不做 CONNECT 隧道的经典缺陷，
+        // 改用 https-proxy-agent 显式代理（按请求生效，不污染全局 env）
+        const proxyUrl = `${proxyConfig.protocol || 'http'}://${proxyConfig.auth?.username ? `${encodeURIComponent(proxyConfig.auth.username)}:${encodeURIComponent(proxyConfig.auth.password || '')}@` : ''}${proxyConfig.host}:${proxyConfig.port || 7890}`;
+        const agent = new https_proxy_agent_1.HttpsProxyAgent(proxyUrl);
+        axiosConfig.httpAgent = agent;
+        axiosConfig.httpsAgent = agent;
+        axiosConfig.proxy = false;
+    }
+    const http = axios_1.default.create(axiosConfig);
+    return {
+        host,
+        ctx,
+        config,
+        http,
+        proxyConfig,
+        cacheTTL,
+        dedupCache,
+        urlCacheLocal,
+        contentDedupCache,
+        customPlatforms,
+        allRules,
+        dedicatedApis,
+        extensions,
+    };
+}
+/** core 自带扩展实现（无 NSFW：CLI / 嵌入式宿主用；koishi 层在其上叠加 NSFW） */
+function createCoreExtensions() {
+    return {
+        mergeImages: merge_1.mergeImages,
+        mp4ToGif: gif_1.mp4ToGif,
+        translate: translate_1.translateText,
+    };
+}

package/lib/engine/translate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 推文翻译：Google gtx 免费端点（无 Key、GET-only）。
+ *
+ * X 网页端的 Grok 翻译走私有通道（translations/show.json 已 404，GraphQL
+ * 仅返回 is_translatable 标志），无公开端点可调，故用通用翻译源兜底。
+ * 译文存入 ParsedData.translation，经 ${翻译} 模板变量展示，空值行自动隐藏。
+ */
+import type { ParserRuntime } from './runtime';
+import type { TranslateResult } from '../extensions';
+export type { TranslateResult };
+/** 判断是否需要跳过翻译（目标语系与推文语种相同 / 无语言内容） */
+export declare function shouldSkipTranslate(tweetLang: string | undefined, target: string): boolean;
+export declare function langName(code?: string): string;
+/** 翻译文本；失败返回 null（调用方保持无译文继续发送）。gtx 优先，MyMemory 兜底 */
+export declare function translateText(rt: ParserRuntime, text: string, target: string, sourceLang?: string): Promise<TranslateResult | null>;

package/lib/engine/translate.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldSkipTranslate = shouldSkipTranslate;
+exports.langName = langName;
+exports.translateText = translateText;
+const logger_1 = require("../logger");
+/** 判断是否需要跳过翻译（目标语系与推文语种相同 / 无语言内容） */
+function shouldSkipTranslate(tweetLang, target) {
+    if (!tweetLang)
+        return false;
+    const l = tweetLang.toLowerCase();
+    if (l === 'zxx' || l === 'und')
+        return l === 'zxx'; // zxx=无语言内容；und=未定则仍尝试
+    const t = target.toLowerCase();
+    if (t === 'zh')
+        return l === 'zh' || l.startsWith('zh-');
+    if (t === 'zh-tw')
+        return l === 'zh-tw' || l === 'zh-hant' || (l.startsWith('zh') && l !== 'zh-cn');
+    if (t === 'en')
+        return l === 'en';
+    return l === t;
+}
+/** 常见语种代码 → 中文名（未知代码原样展示） */
+const LANG_NAMES = {
+    fr: '法语', ja: '日语', ko: '韩语', en: '英语', zh: '中文', es: '西班牙语', pt: '葡萄牙语',
+    de: '德语', ru: '俄语', ar: '阿拉伯语', it: '意大利语', th: '泰语', vi: '越南语',
+    id: '印尼语', tr: '土耳其语', nl: '荷兰语', pl: '波兰语', hi: '印地语', uk: '乌克兰语',
+    sv: '瑞典语', no: '挪威语', fi: '芬兰语', da: '丹麦语', cs: '捷克语', ro: '罗马尼亚语',
+    hu: '匈牙利语', el: '希腊语', he: '希伯来语', fa: '波斯语', ur: '乌尔都语', ms: '马来语',
+    tl: '菲律宾语', ca: '加泰罗尼亚语', bg: '保加利亚语', hr: '克罗地亚语', sr: '塞尔维亚语',
+};
+function langName(code) {
+    if (!code)
+        return '';
+    const base = code.toLowerCase().split('-')[0];
+    if (base === 'und')
+        return '';
+    return LANG_NAMES[base] || code;
+}
+/** 翻译文本；失败返回 null（调用方保持无译文继续发送）。gtx 优先，MyMemory 兜底 */
+async function translateText(rt, text, target, sourceLang) {
+    if (!text)
+        return null;
+    const out = await viaGtx(rt, text, target);
+    if (out)
+        return { text: out, provider: 'Google' };
+    const backup = await viaMyMemory(rt, text, target, sourceLang);
+    if (backup)
+        return { text: backup, provider: 'MyMemory' };
+    return null;
+}
+/** Google gtx 免费端点（无 Key；sl=auto 自动检测源语种） */
+async function viaGtx(rt, text, target) {
+    const url = 'https://translate.googleapis.com/translate_a/single' +
+        `?client=gtx&sl=auto&dt=t&tl=${encodeURIComponent(target)}` +
+        `&q=${encodeURIComponent(text.slice(0, 2000))}`;
+    try {
+        const res = await rt.http.get(url, {
+            timeout: 15000,
+            headers: { 'User-Agent': rt.config.userAgent },
+        });
+        const data = res.data;
+        // gtx 响应形如 [[["译文","原文",null,null,10]],null,"fr",...]
+        if (Array.isArray(data?.[0])) {
+            const out = data[0].map((seg) => (typeof seg?.[0] === 'string' ? seg[0] : '')).join('').trim();
+            if (out)
+                return out;
+        }
+        (0, logger_1.debugLog)('gtx 翻译响应结构异常，尝试备用通道');
+        return null;
+    }
+    catch (e) {
+        (0, logger_1.debugLog)(`gtx 翻译失败：${e?.message || e}`);
+        return null;
+    }
+}
+/** MyMemory 备用（免费无 Key；需已知源语种，不支持 auto） */
+async function viaMyMemory(rt, text, target, sourceLang) {
+    const sl = normalizeLang(sourceLang);
+    if (!sl)
+        return null;
+    const tl = target.toLowerCase();
+    const url = 'https://api.mymemory.translated.net/get' +
+        `?q=${encodeURIComponent(text.slice(0, 500))}&langpair=${encodeURIComponent(sl + '|' + tl)}`;
+    try {
+        const res = await rt.http.get(url, { timeout: 15000, headers: { 'User-Agent': rt.config.userAgent } });
+        const out = res.data?.responseData?.translatedText;
+        if (typeof out === 'string' && out.trim() && !/^MYMEMORY WARNING/i.test(out))
+            return out.trim();
+        (0, logger_1.debugLog)('MyMemory 翻译响应异常，放弃译文');
+        return null;
+    }
+    catch (e) {
+        logger_1.logger.info(`推文翻译失败（跳过译文继续发送）：${e?.message || e}`);
+        return null;
+    }
+}
+function normalizeLang(lang) {
+    if (!lang)
+        return null;
+    const l = lang.toLowerCase();
+    if (l === 'und' || l === 'zxx')
+        return null;
+    if (l.startsWith('zh'))
+        return 'zh-CN';
+    return l.split('-')[0];
+}

package/lib/engine/twitter.d.ts

@@ -0,0 +1,26 @@
+import type { AxiosInstance } from 'axios';
+import type { ParsedData } from '../types';
+/** GraphQL GET 器：可注入（生产用 tlsGet，测试用 mock） */
+export type GraphqlGetter = (url: string, opts: {
+    headers?: Record<string, string>;
+    cookies?: Record<string, string>;
+    timeout?: number;
+}) => Promise<{
+    status: number;
+    data: any;
+}>;
+export interface TwitterCreds {
+    authToken: string;
+    ct0: string;
+}
+export interface GrokTranslation {
+    text: string;
+    sourceLang?: string;
+}
+/**
+ * X 原生 Grok 翻译（与网页"翻译推文"同源）。
+ * 需登录态；网页抓包实证：grok 特性开关 + client-language 头即可，无需
+ * x-client-transaction-id / cf_clearance。任何失败返回 null 由调用方回落通用翻译。
+ */
+export declare function fetchGrokTranslation(url: string, targetLang: string, creds: TwitterCreds, get?: GraphqlGetter): Promise<GrokTranslation | null>;
+export declare function parseTwitter(url: string, http: AxiosInstance, creds?: TwitterCreds, getGraphql?: GraphqlGetter): Promise<ParsedData>;