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

package/lib/config.d.ts

@@ -48,3 +48,8 @@ export declare function defineConfig(contribution: ConfigContribution): ConfigCo
  * 用于 core 汇总所有扩展与平台声明的配置。
  */
 export declare function mergeConfigContributions(lists: ConfigContribution[][]): ConfigContribution[];
+/**
+ * 由配置声明提取默认值表（CLI / 无 Schema 宿主用）：
+ * 平台开关等 object 字段展开为逐键默认值（如 { douyin: true, ... }）。
+ */
+export declare function defaultsFromContributions(contribs: ConfigContribution[]): Record<string, any>;

package/lib/config.js

@@ -11,6 +11,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineConfig = defineConfig;
 exports.mergeConfigContributions = mergeConfigContributions;
+exports.defaultsFromContributions = defaultsFromContributions;
 /** 类型辅助：声明即校验 */
 function defineConfig(contribution) {
     return contribution;
@@ -36,3 +37,30 @@ function mergeConfigContributions(lists) {
     }
     return out;
 }
+function applyFieldDefault(target, f) {
+    if (f.type === 'object' && f.fields) {
+        const obj = {};
+        for (const sub of f.fields)
+            applyFieldDefault(obj, sub);
+        // object 自身 default 与子字段 default 合并（子字段优先）
+        target[f.key] = isPlainObject(f.default) ? { ...f.default, ...obj } : obj;
+        return;
+    }
+    if (f.default !== undefined)
+        target[f.key] = f.default;
+}
+function isPlainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+/**
+ * 由配置声明提取默认值表（CLI / 无 Schema 宿主用）：
+ * 平台开关等 object 字段展开为逐键默认值（如 { douyin: true, ... }）。
+ */
+function defaultsFromContributions(contribs) {
+    const out = {};
+    for (const c of contribs) {
+        for (const f of c.fields)
+            applyFieldDefault(out, f);
+    }
+    return out;
+}

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

@@ -0,0 +1,44 @@
+export declare const CONFIG_ENVELOPE_KIND = "sns-parse-config";
+export declare const CONFIG_ENVELOPE_VERSION = 1;
+/** 脱敏占位；导入时遇此值跳过（保留现有密钥） */
+export declare const MASK = "***";
+export interface ConfigEnvelope {
+    kind: typeof CONFIG_ENVELOPE_KIND;
+    version: number;
+    exportedAt: string;
+    pluginName: string;
+    redacted: boolean;
+    config: Record<string, any>;
+}
+/** 判断键名是否为敏感字段（另含 customHeaders[].value 等，由调用方逐层递归统一处理） */
+export declare function isSecretKey(key: string): boolean;
+/** 深度克隆并按敏感键名打码；数组原样保留（元素递归） */
+export declare function redactConfig(config: any): any;
+/** 构造导出信封 */
+export declare function createConfigEnvelope(config: any, opts?: {
+    pluginName?: string;
+    includeSecrets?: boolean;
+}): ConfigEnvelope;
+/** 序列化信封（pretty JSON） */
+export declare function serializeConfigEnvelope(env: ConfigEnvelope): string;
+export declare function isConfigEnvelope(x: any): x is ConfigEnvelope;
+/**
+ * 解析导入输入：接受
+ * - 信封 JSON
+ * - 裸配置对象 JSON
+ * - 旧版导出（无 kind，直接是配置）
+ */
+export declare function parseConfigInput(input: string): {
+    config: Record<string, any>;
+    envelope: boolean;
+    pluginName?: string;
+};
+/** 深度合并：对象递归合并，数组/标量直接替换；MASK 值跳过（保留现有） */
+export declare function mergeConfig(base: any, patch: any): any;
+/** 统计将被覆盖的顶层键，供 import/migrate 输出摘要 */
+export declare function diffKeys(base: any, patch: any): string[];
+export declare function overrideFilePath(baseDir: string | undefined, name: string): string;
+export declare function readOverride(baseDir: string | undefined, name: string): Record<string, any> | null;
+export declare function writeOverride(baseDir: string | undefined, name: string, config: Record<string, any>, pluginName?: string): string;
+/** 读覆盖文件并合并到 schema 配置之上（启动时调用） */
+export declare function applyOverrideToConfig(config: any, baseDir: string | undefined, name: string): any;

package/lib/engine/config-io.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MASK = exports.CONFIG_ENVELOPE_VERSION = exports.CONFIG_ENVELOPE_KIND = void 0;
+exports.isSecretKey = isSecretKey;
+exports.redactConfig = redactConfig;
+exports.createConfigEnvelope = createConfigEnvelope;
+exports.serializeConfigEnvelope = serializeConfigEnvelope;
+exports.isConfigEnvelope = isConfigEnvelope;
+exports.parseConfigInput = parseConfigInput;
+exports.mergeConfig = mergeConfig;
+exports.diffKeys = diffKeys;
+exports.overrideFilePath = overrideFilePath;
+exports.readOverride = readOverride;
+exports.writeOverride = writeOverride;
+exports.applyOverrideToConfig = applyOverrideToConfig;
+/**
+ * 配置导出 / 导入 / 迁移。
+ *
+ * 目的：新旧包使用不同命名空间（旧 video-parser-all / 新 sns-parse），
+ * koishi 配置键随之不同，因此提供可跨命名空间移植的配置信封。
+ *
+ * - 导出：默认脱敏（密钥打码 MASK），--include-secrets 才输出明文
+ * - 导入：深度合并进当前配置；MASK 值跳过（保留现有密钥）
+ * - 持久化：自管覆盖文件 <baseDir>/data/<name>/config.override.json
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+exports.CONFIG_ENVELOPE_KIND = 'sns-parse-config';
+exports.CONFIG_ENVELOPE_VERSION = 1;
+/** 脱敏占位；导入时遇此值跳过（保留现有密钥） */
+exports.MASK = '***';
+/** 需要脱敏的键名（大小写不敏感） */
+const SECRET_KEYS = new Set([
+    'apikey', 'secretkey', 'secretid', 'accesskeyid', 'accesskeysecret',
+    'authtoken', 'ct0', 'twitterauthtoken', 'twitterct0', 'password',
+]);
+function isPlainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+/** 判断键名是否为敏感字段（另含 customHeaders[].value 等，由调用方逐层递归统一处理） */
+function isSecretKey(key) {
+    return SECRET_KEYS.has(key.toLowerCase());
+}
+/** 深度克隆并按敏感键名打码；数组原样保留（元素递归） */
+function redactConfig(config) {
+    if (Array.isArray(config))
+        return config.map(redactConfig);
+    if (!isPlainObject(config))
+        return config;
+    const out = {};
+    for (const [k, v] of Object.entries(config)) {
+        if (isSecretKey(k) && typeof v === 'string' && v)
+            out[k] = exports.MASK;
+        else
+            out[k] = redactConfig(v);
+    }
+    return out;
+}
+/** 构造导出信封 */
+function createConfigEnvelope(config, opts = {}) {
+    const cfg = opts.includeSecrets ? JSON.parse(JSON.stringify(config ?? {})) : redactConfig(config);
+    return {
+        kind: exports.CONFIG_ENVELOPE_KIND,
+        version: exports.CONFIG_ENVELOPE_VERSION,
+        exportedAt: new Date().toISOString(),
+        pluginName: opts.pluginName || '',
+        redacted: !opts.includeSecrets,
+        config: cfg,
+    };
+}
+/** 序列化信封（pretty JSON） */
+function serializeConfigEnvelope(env) {
+    return JSON.stringify(env, null, 2);
+}
+function isConfigEnvelope(x) {
+    return !!x && typeof x === 'object' && x.kind === exports.CONFIG_ENVELOPE_KIND;
+}
+/**
+ * 解析导入输入：接受
+ * - 信封 JSON
+ * - 裸配置对象 JSON
+ * - 旧版导出（无 kind，直接是配置）
+ */
+function parseConfigInput(input) {
+    let data;
+    const text = (input || '').trim();
+    if (!text)
+        throw new Error('导入内容为空');
+    try {
+        data = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`导入内容不是合法 JSON：${e?.message || e}`);
+    }
+    if (isConfigEnvelope(data)) {
+        return { config: data.config || {}, envelope: true, pluginName: data.pluginName };
+    }
+    if (isPlainObject(data))
+        return { config: data, envelope: false };
+    throw new Error('导入内容既不是配置信封也不是配置对象');
+}
+/** 深度合并：对象递归合并，数组/标量直接替换；MASK 值跳过（保留现有） */
+function mergeConfig(base, patch) {
+    if (!isPlainObject(patch))
+        return patch;
+    const out = isPlainObject(base) ? { ...base } : {};
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === exports.MASK)
+            continue;
+        out[k] = isPlainObject(v) && isPlainObject(out[k]) ? mergeConfig(out[k], v) : v;
+    }
+    return out;
+}
+/** 统计将被覆盖的顶层键，供 import/migrate 输出摘要 */
+function diffKeys(base, patch) {
+    if (!isPlainObject(patch))
+        return [];
+    const out = [];
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === exports.MASK)
+            continue;
+        if (isPlainObject(v) && isPlainObject(base?.[k]))
+            out.push(...diffKeys(base[k], v).map(sub => `${k}.${sub}`));
+        else
+            out.push(k);
+    }
+    return out;
+}
+/* ---------- 覆盖文件持久化 ---------- */
+function overrideFilePath(baseDir, name) {
+    const root = baseDir || process.cwd();
+    return (0, path_1.join)(root, 'data', name, 'config.override.json');
+}
+function readOverride(baseDir, name) {
+    try {
+        const raw = (0, fs_1.readFileSync)(overrideFilePath(baseDir, name), 'utf8');
+        const data = JSON.parse(raw);
+        return isConfigEnvelope(data) ? data.config : (isPlainObject(data) ? data : null);
+    }
+    catch {
+        return null;
+    }
+}
+function writeOverride(baseDir, name, config, pluginName) {
+    const file = overrideFilePath(baseDir, name);
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(file), { recursive: true });
+    const env = createConfigEnvelope(config, { pluginName: pluginName || name, includeSecrets: true });
+    (0, fs_1.writeFileSync)(file, serializeConfigEnvelope(env), 'utf8');
+    return file;
+}
+/** 读覆盖文件并合并到 schema 配置之上（启动时调用） */
+function applyOverrideToConfig(config, baseDir, name) {
+    const override = readOverride(baseDir, name);
+    return override ? mergeConfig(config, override) : config;
+}

package/lib/engine/fetcher.d.ts

@@ -0,0 +1,21 @@
+import type { ParserRuntime } from './runtime';
+import type { ParsedData } from '../types';
+export declare function fetchApi(rt: ParserRuntime, url: string, type: string, fieldMapping?: Record<string, string>, platformConf?: any): Promise<ParsedData>;
+export declare function parseUrl(rt: ParserRuntime, url: string, type: string, fieldMapping?: Record<string, string>, platformConf?: any): Promise<{
+    success: true;
+    data: ParsedData;
+} | {
+    success: false;
+    msg: string;
+}>;
+export declare function processSingleUrl(rt: ParserRuntime, url: string, type: string, fieldMapping?: Record<string, string>, platformConf?: any): Promise<{
+    success: true;
+    data: {
+        text: string;
+        parsed: ParsedData;
+    };
+} | {
+    success: false;
+    msg: string;
+    url: string;
+}>;

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;