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

package/lib/engine/fetcher.js

@@ -0,0 +1,228 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchApi = fetchApi;
+exports.parseUrl = parseUrl;
+exports.processSingleUrl = processSingleUrl;
+const axios_1 = __importDefault(require("axios"));
+const https_proxy_agent_1 = require("https-proxy-agent");
+const logger_1 = require("../logger");
+const common_1 = require("../utils/common");
+const format_1 = require("../utils/format");
+const parser_1 = require("./parser");
+const platform_config_1 = require("./platform-config");
+const twitter_1 = require("./twitter");
+const translate_1 = require("./translate");
+const tls_client_1 = require("../utils/tls-client");
+const gateway_1 = require("./gateway");
+async function fetchApi(rt, url, type, fieldMapping, platformConf) {
+    const { config, http, urlCacheLocal, proxyConfig, cacheTTL } = rt;
+    const cacheKey = url;
+    const cached = urlCacheLocal.get(cacheKey);
+    if (cached && cached.expire > Date.now()) {
+        (0, logger_1.debugLog)('缓存命中，直接返回:', url);
+        return cached.data;
+    }
+    const { apiUrl: dedicatedUrl, dedicatedFirst, apiKey, authHeaderType, customHeaderName, customProxy } = platformConf || (0, platform_config_1.getPlatformConfig)(rt, type);
+    // X / Twitter：统一网关均走原生 syndication 解析（除非用户自定义了 API）
+    if (type === 'twitter' && !dedicatedUrl) {
+        (0, logger_1.debugLog)('twitter 走原生 syndication 解析:', url);
+        const twCreds = (config.twitterAuthToken && config.twitterCt0)
+            ? { authToken: String(config.twitterAuthToken), ct0: String(config.twitterCt0) }
+            : undefined;
+        // 代理串通：axios 走 runtime 实例；tlsget-rs（GraphQL/Grok 翻译）显式透传代理地址
+        const tlsProxy = (proxyConfig.enabled && proxyConfig.host)
+            ? `${proxyConfig.protocol || 'http'}://${proxyConfig.auth?.username ? `${encodeURIComponent(proxyConfig.auth.username)}:${encodeURIComponent(proxyConfig.auth.password || '')}@` : ''}${proxyConfig.host}:${proxyConfig.port || 7890}`
+            : undefined;
+        const tlsGetWithProxy = (u, o) => (0, tls_client_1.tlsGet)(u, { ...o, proxy: tlsProxy });
+        const parsed = await (0, twitter_1.parseTwitter)(url, http, twCreds, tlsGetWithProxy);
+        // 推文翻译：目标语种与推文语种相同时跳过；Grok（需登录态）优先，通用翻译兜底
+        if (config.tweetTranslateEnabled && parsed.desc) {
+            const target = config.tweetTranslateLang || 'zh';
+            if (!(0, translate_1.shouldSkipTranslate)(parsed.lang, target)) {
+                let translated = null;
+                let provider = '';
+                if (twCreds) {
+                    const grok = await (0, twitter_1.fetchGrokTranslation)(url, target, twCreds, tlsGetWithProxy).catch(() => null);
+                    if (grok) {
+                        translated = grok.text;
+                        provider = 'Grok';
+                        if (!parsed.lang && grok.sourceLang)
+                            parsed.lang = grok.sourceLang;
+                    }
+                }
+                if (!translated) {
+                    const generic = await (0, translate_1.translateText)(rt, parsed.desc, target, parsed.lang);
+                    if (generic) {
+                        translated = generic.text;
+                        provider = generic.provider;
+                    }
+                }
+                if (translated) {
+                    parsed.translation = translated;
+                    parsed.translationProvider = provider;
+                }
+            }
+        }
+        urlCacheLocal.set(cacheKey, { data: parsed, expire: Date.now() + cacheTTL });
+        return parsed;
+    }
+    // 网关选择（上游 issue #12）：配置 apiKey → 新网关（无备用 API）；否则 → 旧网关（主+备用）。
+    // 注意：primaryApiUrl 是旧网关覆盖字段，新网关不受其影响（避免旧配置劫持切换）
+    const useNewGateway = !!config.apiKey;
+    const primaryApi = useNewGateway
+        ? gateway_1.NEW_GATEWAY_PRIMARY
+        : (config.primaryApiUrl || gateway_1.LEGACY_GATEWAY_PRIMARY);
+    const backupApi = config.backupApiUrl || gateway_1.LEGACY_GATEWAY_BACKUP;
+    const backupAllowed = !useNewGateway && new Set(['douyin', 'xiaohongshu', 'instagram', 'jimeng']).has(type);
+    const gwConf = useNewGateway
+        ? { apiKey: config.apiKey, authHeaderType: 'X-API-Key', customHeaderName: 'X-API-Key' }
+        : { apiKey: '', authHeaderType: undefined, customHeaderName: undefined };
+    const apiList = [];
+    if (dedicatedFirst && dedicatedUrl) {
+        apiList.push({ url: dedicatedUrl, label: `专属API(${type})`, apiKey, authHeaderType, customHeaderName, fieldMapping });
+        apiList.push({ url: primaryApi, label: '默认主API', ...gwConf, fieldMapping });
+        if (backupAllowed)
+            apiList.push({ url: backupApi, label: '备用主API', ...gwConf, fieldMapping });
+    }
+    else {
+        apiList.push({ url: primaryApi, label: '默认主API', ...gwConf, fieldMapping });
+        if (backupAllowed)
+            apiList.push({ url: backupApi, label: '备用主API', ...gwConf, fieldMapping });
+        if (dedicatedUrl)
+            apiList.push({ url: dedicatedUrl, label: `专属API(${type})`, apiKey, authHeaderType, customHeaderName, fieldMapping });
+    }
+    if (type.startsWith('custom_') && apiList.length === 0 && dedicatedUrl) {
+        apiList.push({ url: dedicatedUrl, label: `自定义API(${type})`, apiKey, authHeaderType, customHeaderName, fieldMapping });
+    }
+    // 新网关模式下追加旧网关末位兜底：新网关无专属端点的平台（微博/小红书等）或主 API 故障
+    // （5xx/网关侧异常）时仍有机会解析；旧网关对语义问题会返回更明确的错误信息
+    if (useNewGateway && !type.startsWith('custom_')) {
+        const legacyDedicated = rt.dedicatedApis?.legacy?.[type];
+        const legacyMain = config.primaryApiUrl && config.primaryApiUrl !== gateway_1.LEGACY_GATEWAY_PRIMARY ? config.primaryApiUrl : gateway_1.LEGACY_GATEWAY_PRIMARY;
+        if (legacyDedicated && !apiList.some((a) => a.url === legacyDedicated)) {
+            apiList.push({ url: legacyDedicated, label: `旧网关专属API(${type})`, apiKey: '', authHeaderType: undefined, customHeaderName: undefined, fieldMapping });
+        }
+        if (!apiList.some((a) => a.url === legacyMain)) {
+            apiList.push({ url: legacyMain, label: '旧网关主API', apiKey: '', authHeaderType: undefined, customHeaderName: undefined, fieldMapping });
+        }
+        if (!apiList.some((a) => a.url === backupApi)) {
+            apiList.push({ url: backupApi, label: '旧网关备用API', apiKey: '', authHeaderType: undefined, customHeaderName: undefined, fieldMapping });
+        }
+    }
+    const customHeaders = config.customHeaders || [];
+    const errors = [];
+    for (const [apiIndex, api] of apiList.entries()) {
+        for (let attempt = 0; attempt <= config.retryTimes; attempt++) {
+            try {
+                const headers = {
+                    'User-Agent': config.userAgent,
+                    'Referer': 'https://www.baidu.com/',
+                    'Content-Type': 'application/x-www-form-urlencoded'
+                };
+                for (const h of customHeaders) {
+                    if (h.name && h.value)
+                        headers[h.name] = h.value;
+                }
+                if (api.apiKey) {
+                    const authHeaders = (0, platform_config_1.buildAuthHeaders)(api.apiKey, api.authHeaderType || 'Bearer', api.customHeaderName || 'X-API-Key');
+                    Object.assign(headers, authHeaders);
+                }
+                const proxyToUse = customProxy && customProxy.enabled ? customProxy : (proxyConfig.enabled ? proxyConfig : undefined);
+                const axiosConfigLocal = {
+                    params: { url },
+                    timeout: config.timeout,
+                    headers,
+                };
+                // 代理：runtime 实例已按全局代理配置好 https-proxy-agent；
+                // 仅当平台级 customProxy 覆盖时才按请求另建 agent（不用 axios 内置 proxy 选项——对 https 目标不做 CONNECT 隧道）
+                if (customProxy && customProxy.enabled && customProxy.host) {
+                    const pUrl = `${customProxy.protocol || 'http'}://${customProxy.auth?.username ? `${encodeURIComponent(customProxy.auth.username)}:${encodeURIComponent(customProxy.auth.password || '')}@` : ''}${customProxy.host}:${customProxy.port || 7890}`;
+                    const agent = new https_proxy_agent_1.HttpsProxyAgent(pUrl);
+                    axiosConfigLocal.httpAgent = agent;
+                    axiosConfigLocal.httpsAgent = agent;
+                    axiosConfigLocal.proxy = false;
+                }
+                const res = await http.get(api.url, axiosConfigLocal);
+                // 兼容第三方 API：响应不含 code/status 状态字段时视为成功，直接交由解析器处理
+                const code = res.data?.code;
+                const ok = res.data && (code === 200 || code === 0 || (code === undefined && res.data.status === undefined));
+                if (ok) {
+                    // 回退链路重要事件：非首个 API 成功说明上游发生了故障切换
+                    if (apiIndex > 0)
+                        logger_1.logger.info(`${api.label} 回退解析成功（此前 API 失败）: ${url}`);
+                    else
+                        (0, logger_1.debugLog)(`${api.label} 解析成功: ${url}`);
+                    const parsed = (0, parser_1.parseApiResponse)(res.data, config.maxDescLength, api.fieldMapping);
+                    urlCacheLocal.set(cacheKey, { data: parsed, expire: Date.now() + cacheTTL });
+                    return parsed;
+                }
+                throw new Error(res.data?.msg || res.data?.message || `API返回错误码: ${code ?? res.data?.status}`);
+            }
+            catch (error) {
+                const lastErr = error instanceof Error ? error : new Error(String(error));
+                errors.push(lastErr);
+                (0, logger_1.debugLog)(`${api.label} attempt ${attempt + 1} failed: ${lastErr.message}`);
+                if (axios_1.default.isAxiosError(error)) {
+                    if (!error.response) {
+                        if (attempt < config.retryTimes) {
+                            await (0, common_1.delay)(config.retryInterval);
+                            continue;
+                        }
+                    }
+                    const status = error.response?.status;
+                    if (status && (status >= 500 || status === 429)) {
+                        if (attempt < config.retryTimes) {
+                            await (0, common_1.delay)(config.retryInterval);
+                            continue;
+                        }
+                    }
+                }
+                break;
+            }
+        }
+        logger_1.logger.warn(`${api.label} 全部重试失败`);
+    }
+    // 优先返回语义级错误（服务端明确说明原因），避免被后续兜底 API 的 5xx/网络/风控泛错覆盖；
+    // 「Request failed with status code NNN」这类 axios 泛错无信息量，同样降级
+    const semantic = errors.find((e) => !/status code \d{3}|socket|ECONNRESET|ETIMEDOUT|timeout|Bad Gateway|Service Unavailable/i.test(e.message));
+    throw semantic || errors[errors.length - 1] || new Error('所有API请求全部失败');
+}
+async function parseUrl(rt, url, type, fieldMapping, platformConf) {
+    try {
+        const info = await fetchApi(rt, url, type, fieldMapping, platformConf);
+        const hasMedia = !!(info.video || info.images.length > 0 || info.live_photo.length > 0);
+        if (hasMedia)
+            return { success: true, data: info };
+        // 纯文字内容（如 X 纯文字推文）：有正文即视为成功，下游发送文字卡片
+        if (info.type === 'text' && (info.title || info.desc)) {
+            (0, logger_1.debugLog)(`纯文字内容: ${url}`);
+            return { success: true, data: info };
+        }
+        (0, logger_1.debugLog)(`解析成功但无内容: ${url}`);
+        return { success: false, msg: '解析接口返回空内容' };
+    }
+    catch (error) {
+        logger_1.logger.error(`解析失败: ${url}`, (0, common_1.getErrorMessage)(error));
+        let msg = (0, common_1.getErrorMessage)(error);
+        // 小红书风控：裸 /discovery/item 链接缺 xsec_token，服务端获取 gate 票据失败；提示用户改发完整分享链接
+        if (type === 'xiaohongshu' && /xsec_token|gate|票据/i.test(msg)) {
+            msg += '（小红书升级了风控：请发送完整分享链接，如 xhslink.com 短链、App 分享文案里的原链接，或带 xsec_token 参数的网页链接）';
+        }
+        // 微博：API 仅支持视频微博，图文微博/新版 base62 短链会报「无法从URL中提取视频ID」
+        if (type === 'weibo' && /无法从URL中提取视频ID|提取.*视频ID/.test(msg)) {
+            msg += '（微博解析仅支持视频微博链接，如 weibo.com/tv/show/… 或 video.weibo.com/show?fid=…；图文微博与新版短链 /用户ID/短ID 形式暂不支持）';
+        }
+        return { success: false, msg };
+    }
+}
+async function processSingleUrl(rt, url, type, fieldMapping, platformConf) {
+    const { config } = rt;
+    const result = await parseUrl(rt, url, type, fieldMapping, platformConf);
+    if (!result.success)
+        return { success: false, msg: result.msg, url };
+    const text = (0, format_1.generateFormattedText)(result.data, config.unifiedMessageFormat);
+    return { success: true, data: { text, parsed: result.data } };
+}

package/lib/engine/gateway.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 双网关配置（上游 issue #12）：
+ * - 旧网关 api.bugpk.com：无需 API Key，v1.5.8 及之前的行为
+ * - 新网关 api-new.ifphp.com：需 API Key（X-API-Key 头），上游唯一维护入口
+ * 选择规则：配置了 apiKey → 新网关；否则 → 旧网关
+ *
+ * 平台专属端点内联在各 PlatformDefinition（dedicated 字段），此处提供
+ * 由定义列表聚合出的映射函数（runtime 构建时计算一次挂在 rt 上）。
+ */
+import type { PlatformDefinition } from '../platform';
+export declare const NEW_GATEWAY_PRIMARY = "https://api-new.ifphp.com/api/svparse";
+export declare const LEGACY_GATEWAY_PRIMARY = "https://api.bugpk.com/api/short_videos";
+export declare const LEGACY_GATEWAY_BACKUP = "https://api.bugpk.com/api/svparse";
+export interface DedicatedApiMaps {
+    /** 旧网关平台专属端点（无需 Key） */
+    legacy: Record<string, string>;
+    /** 新网关平台专属端点（需 Key；未覆盖的平台走主 API 兜底） */
+    next: Record<string, string>;
+}
+/** 由平台定义列表聚合专属端点映射 */
+export declare function dedicatedApisFrom(defs: PlatformDefinition[]): DedicatedApiMaps;

package/lib/engine/gateway.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_GATEWAY_BACKUP = exports.LEGACY_GATEWAY_PRIMARY = exports.NEW_GATEWAY_PRIMARY = void 0;
+exports.dedicatedApisFrom = dedicatedApisFrom;
+exports.NEW_GATEWAY_PRIMARY = 'https://api-new.ifphp.com/api/svparse';
+exports.LEGACY_GATEWAY_PRIMARY = 'https://api.bugpk.com/api/short_videos';
+exports.LEGACY_GATEWAY_BACKUP = 'https://api.bugpk.com/api/svparse';
+/** 由平台定义列表聚合专属端点映射 */
+function dedicatedApisFrom(defs) {
+    const legacy = {};
+    const next = {};
+    for (const p of defs) {
+        if (p.dedicated?.legacy)
+            legacy[p.type] = p.dedicated.legacy;
+        if (p.dedicated?.next)
+            next[p.type] = p.dedicated.next;
+    }
+    return { legacy, next };
+}

package/lib/engine/parser.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedData } from '../types';
+export declare function parseApiResponse(rawInput: any, maxDescLen: number, fieldMapping?: Record<string, string>): ParsedData;

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;