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

package/lib/config.d.ts

@@ -22,6 +22,8 @@ export interface ConfigField {
     /** koishi 的 role：多行文本 / 密钥 */
     role?: 'textarea' | 'secret';
     hidden?: boolean;
+    /** 宿主 Schema 生成时的必填标记（仅 UI 层语义） */
+    required?: boolean;
     min?: number;
     max?: number;
     step?: number;

package/lib/engine/config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 引擎层配置声明（中立 DSL）：fetcher/parser/compose/sender/gateway 等引擎
+ * 自身读取的配置项，由 core 统一声明；koishi / CLI 兼容层据此生成 Schema 与默认值。
+ *
+ * 组序即 UI 展示序（koishi 兼容层在「发送策略」后插入扩展与平台的动态声明）。
+ */
+import { type ConfigContribution } from '../config';
+/** 引擎层配置声明（有序；组名即 UI 分组标题） */
+export declare function engineConfigContributions(): ConfigContribution[];

package/lib/engine/config.js

@@ -0,0 +1,265 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.engineConfigContributions = engineConfigContributions;
+/**
+ * 引擎层配置声明（中立 DSL）：fetcher/parser/compose/sender/gateway 等引擎
+ * 自身读取的配置项，由 core 统一声明；koishi / CLI 兼容层据此生成 Schema 与默认值。
+ *
+ * 组序即 UI 展示序（koishi 兼容层在「发送策略」后插入扩展与平台的动态声明）。
+ */
+const config_1 = require("../config");
+const PROXY_FIELDS = [
+    { key: 'enabled', type: 'boolean', default: false, description: '启用代理' },
+    {
+        key: 'protocol', type: 'union', default: 'http', description: '协议',
+        values: [
+            { value: 'http', description: 'HTTP' },
+            { value: 'https', description: 'HTTPS' },
+        ],
+    },
+    { key: 'host', type: 'string', default: '127.0.0.1', description: '地址' },
+    { key: 'port', type: 'number', default: 7890, description: '端口' },
+    {
+        key: 'auth', type: 'object', description: '认证',
+        fields: [
+            { key: 'username', type: 'string', default: '', description: '用户名' },
+            { key: 'password', type: 'string', default: '', description: '密码' },
+        ],
+    },
+];
+const AUTH_HEADER_FIELDS = [
+    {
+        key: 'authHeaderType', type: 'union', default: 'Bearer', description: '认证头类型',
+        values: [
+            { value: 'Bearer', description: 'Bearer' },
+            { value: 'X-API-Key', description: 'X-API-Key' },
+            { value: 'Custom', description: '自定义' },
+        ],
+    },
+    { key: 'customHeaderName', type: 'string', default: 'X-API-Key', description: '自定义头名称' },
+];
+const FIELD_MAPPING_FIELD = {
+    key: 'fieldMapping', type: 'string', role: 'textarea',
+    default: '{}', description: '字段映射 JSON',
+};
+const API_PLATFORM_VALUES = [
+    { value: 'bilibili', description: '哔哩哔哩' },
+    { value: 'douyin', description: '抖音' },
+    { value: 'kuaishou', description: '快手' },
+    { value: 'xiaohongshu', description: '小红书' },
+    { value: 'weibo', description: '微博' },
+    { value: 'xigua', description: '西瓜视频' },
+    { value: 'youtube', description: 'YouTube' },
+    { value: 'tiktok', description: 'TikTok' },
+    { value: 'acfun', description: 'AcFun（A站）' },
+    { value: 'zhihu', description: '知乎' },
+    { value: 'weishi', description: '微视' },
+    { value: 'huya', description: '虎牙' },
+    { value: 'haokan', description: '好看视频' },
+    { value: 'meipai', description: '美拍' },
+    { value: 'twitter', description: 'Twitter/X' },
+    { value: 'instagram', description: 'Instagram' },
+    { value: 'doubao', description: '豆包' },
+    { value: 'doubao_image', description: '豆包图片' },
+    { value: 'jimeng', description: '即梦' },
+    { value: 'oasis', description: '绿洲' },
+    { value: 'wechat_channel', description: '视频号' },
+    { value: 'lishi', description: '梨视频' },
+    { value: 'quanmin', description: '全民直播' },
+    { value: 'pipigx', description: '皮皮搞笑' },
+    { value: 'pipixia', description: '皮皮虾' },
+    { value: 'zuiyou', description: '最右' },
+    { value: 'toutiao', description: '今日头条' },
+];
+const GLOBAL_FIELD_MAPPING_DEFAULT = [
+    '{',
+    '  "title": "data.title",',
+    '  "desc": "data.description",',
+    '  "author": "data.author.name",',
+    '  "uid": "data.author.id",',
+    '  "avatar": "data.author.avatar",',
+    '  "cover": "data.cover_url",',
+    '  "video": "data.video_url",',
+    '  "video_backup": "data.video_qualities",',
+    '  "videos": "data.videos",',
+    '  "type": "data.type",',
+    '  "like": "data.statistics.likes",',
+    '  "comment": "data.statistics.comments",',
+    '  "collect": "data.statistics.favorites",',
+    '  "share": "data.statistics.shares",',
+    '  "play": "data.statistics.plays",',
+    '  "duration": "data.duration",',
+    '  "publishTime": "data.create_time",',
+    '  "music_title": "data.music.title",',
+    '  "music_author": "data.music.author",',
+    '  "music_cover": "data.music.cover",',
+    '  "music_url": "data.music.url"',
+    '}',
+].join('\n');
+/** 引擎层配置声明（有序；组名即 UI 分组标题） */
+function engineConfigContributions() {
+    return [
+        (0, config_1.defineConfig)({
+            group: '消息格式',
+            fields: [
+                {
+                    key: 'unifiedMessageFormat', type: 'string', role: 'textarea',
+                    default: '标题：${标题}\n作者：${作者}\n简介：${简介}\n正文：${正文}\n翻译（${翻译提供方}，${原文语言}）：${翻译}\n音乐标题：${音乐标题}\n音乐作者：${音乐作者}\n点赞：${点赞数}\n收藏：${收藏数}\n转发：${转发数}\n播放：${播放数}\n评论：${评论数}\n图片数量：${图片数量}',
+                    description: '消息文字模板，可用变量：${标题} ${作者} ${简介} ${正文}（纯文字作品正文，启用后该类作品不再显示为简介） ${翻译} ${翻译提供方} ${原文语言} ${视频时长} ${点赞数} ${收藏数} ${转发数} ${播放数} ${评论数} ${发布时间} ${图片数量} ${作者ID} ${音乐标题} ${音乐作者}（空行自动隐藏）',
+                },
+            ],
+        }),
+        (0, config_1.defineConfig)({
+            group: '媒体发送',
+            fields: [
+                { key: 'showImageText', type: 'boolean', default: true, description: '发送文字内容' },
+                { key: 'showCoverImage', type: 'boolean', default: true, description: '发送封面图片' },
+                { key: 'showCoverFile', type: 'boolean', default: true, description: '封面以图片形式发送（关闭则只发链接）' },
+                { key: 'showCoverText', type: 'boolean', default: true, description: '封面图前显示文字提示' },
+                { key: 'coverText', type: 'string', default: '封面：', description: '封面提示文字' },
+                { key: 'showImageFileNew', type: 'boolean', default: true, description: '图片以图片形式发送（关闭则只发链接）' },
+                { key: 'showAuthorAvatar', type: 'boolean', default: true, description: '发送作者头像' },
+                { key: 'showAuthorAvatarFile', type: 'boolean', default: true, description: '头像以图片形式发送（关闭则只发链接）' },
+                { key: 'showAuthorAvatarText', type: 'boolean', default: true, description: '头像前显示文字提示' },
+                { key: 'authorAvatarText', type: 'string', default: '作者头像：', description: '头像提示文字' },
+                { key: 'showMusicCover', type: 'boolean', default: true, description: '发送音乐封面' },
+                { key: 'showVideoFile', type: 'boolean', default: true, description: '视频以视频形式发送（关闭则只发链接）' },
+                { key: 'sendLiveMessage', type: 'boolean', default: true, description: '直播作品发文字消息（不发视频）' },
+                { key: 'mergeSameOriginImages', type: 'boolean', default: true, description: '同源切图内容识别合并（纯像素内容裁决，不依赖链接/文件名/色调风格）：网格/竖堆/横拼三种布局各自经接缝连续性验证（低频趋势延续+纹理能量可验证性），取证据最强者合并；均不过回退逐张；需 ffmpeg' },
+            ],
+        }),
+        (0, config_1.defineConfig)({
+            group: '音乐语音（需 silk 和 ffmpeg）',
+            fields: [
+                { key: 'showMusicVoice', type: 'boolean', default: false, description: '音乐链接以语音形式发送' },
+                { key: 'showMusicVoiceFile', type: 'boolean', default: true, description: '音乐是否以语音形式发送（关闭则只发送链接）' },
+            ],
+        }),
+        (0, config_1.defineConfig)({
+            group: 'GIF 转换',
+            fields: [
+                { key: 'gifConvertEnabled', type: 'boolean', default: true, description: '推文动图转 GIF 发送（ffmpeg 随插件自动安装，失败回退原视频）' },
+                { key: 'gifMaxWidth', type: 'number', min: 120, max: 1080, step: 1, default: 480, description: 'GIF 宽度 (px)' },
+                { key: 'gifFps', type: 'number', min: 5, max: 30, step: 1, default: 15, description: 'GIF 帧率' },
+                { key: 'gifMaxDurationSec', type: 'number', min: 1, max: 60, step: 1, default: 15, description: 'GIF 时长上限 (s)' },
+            ],
+        }),
+        (0, config_1.defineConfig)({
+            group: '性能与限制',
+            fields: [
+                { key: 'maxDescLength', type: 'number', min: 0, step: 1, default: 200, description: '简介长度上限' },
+                { key: 'maxConcurrent', type: 'number', min: 1, step: 1, default: 3, description: '解析最大并发数' },
+            ],
+        }),
+        (0, config_1.defineConfig)({
+            group: '发送策略',
+            fields: [
+                {
+                    key: 'sendStrategy', type: 'union', default: 'single', description: '发送策略',
+                    values: [
+                        { value: 'single', description: '单条整合（默认；图片过多/含视频自动回退合并转发）' },
+                        { value: 'split', description: '逐条分开发送（旧版行为）' },
+                    ],
+                },
+                { key: 'singleSendMaxImages', type: 'number', min: 1, default: 10, description: '单条消息最大图片数（超出回退合并转发）' },
+            ],
+        }),
+        (0, config_1.defineConfig)({
+            group: '网络与请求',
+            fields: [
+                { key: 'timeout', type: 'number', min: 0, step: 1, default: 180000, description: 'API 请求超时 (ms)' },
+                { key: 'videoSendTimeout', type: 'number', min: 0, step: 1, default: 180000, description: '消息发送超时 (ms)' },
+                { key: 'userAgent', type: 'string', default: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36', description: 'User-Agent' },
+                { key: 'proxy', type: 'object', description: 'HTTP/HTTPS 代理', fields: PROXY_FIELDS },
+                {
+                    key: 'customHeaders', type: 'array', default: [], description: '自定义请求头',
+                    itemFields: [
+                        { key: 'name', type: 'string', required: true, description: '头名称' },
+                        { key: 'value', type: 'string', required: true, description: '头值' },
+                    ],
+                },
+            ],
+        }),
+        (0, config_1.defineConfig)({
+            group: '发送与重试',
+            fields: [
+                { key: 'ignoreSendError', type: 'boolean', default: true, description: '忽略发送失败' },
+                { key: 'retryTimes', type: 'number', min: 0, default: 3, description: '重试次数' },
+                { key: 'retryInterval', type: 'number', min: 0, default: 1000, description: '重试间隔 (ms)' },
+                { key: 'enableForward', type: 'boolean', default: false, description: '合并转发（OneBot/Satori）' },
+            ],
+        }),
+        (0, config_1.defineConfig)({
+            group: '缓存与临时文件',
+            fields: [
+                { key: 'deduplicationInterval', type: 'number', min: 0, default: 180, description: '去重间隔 (s)' },
+                { key: 'enableDeduplication', type: 'boolean', default: true, description: '启用重复解析检测与提示' },
+                { key: 'cacheTTL', type: 'number', min: 0, default: 600, description: '缓存时间 (s)' },
+            ],
+        }),
+        (0, config_1.defineConfig)({
+            group: 'API 与平台',
+            fields: [
+                { key: 'primaryApiUrl', type: 'string', default: 'https://api.bugpk.com/api/short_videos', hidden: true },
+                { key: 'backupApiUrl', type: 'string', default: 'https://api.bugpk.com/api/svparse', hidden: true },
+                {
+                    key: 'customApis', type: 'array', default: [], description: '覆盖内置平台 API',
+                    itemFields: [
+                        { key: 'platform', type: 'union', required: true, description: '平台', values: API_PLATFORM_VALUES },
+                        { key: 'apiUrl', type: 'string', description: 'API 地址' },
+                        { key: 'apiKey', type: 'string', default: '', description: 'API Key' },
+                        ...AUTH_HEADER_FIELDS.map(f => ({ ...f })),
+                        FIELD_MAPPING_FIELD,
+                    ],
+                },
+                {
+                    key: 'customPlatforms', type: 'array', default: [], description: '自定义新平台',
+                    itemFields: [
+                        { key: 'name', type: 'string', required: true, description: '平台名称' },
+                        { key: 'exampleUrl', type: 'string', description: '示例链接' },
+                        { key: 'keywords', type: 'string', required: true, description: '关键词（逗号分隔）' },
+                        { key: 'apiUrl', type: 'string', required: true, description: '解析 API' },
+                        { key: 'apiKey', type: 'string', default: '', description: 'API Key' },
+                        ...AUTH_HEADER_FIELDS.map(f => ({ ...f })),
+                        FIELD_MAPPING_FIELD,
+                        { key: 'proxy', type: 'object', description: '独立代理（覆盖全局代理）', fields: PROXY_FIELDS },
+                    ],
+                },
+                {
+                    key: 'globalFieldMapping', type: 'string', role: 'textarea',
+                    default: GLOBAL_FIELD_MAPPING_DEFAULT, description: '全局字段映射 JSON',
+                },
+                { key: 'twitterAuthToken', type: 'string', default: '', role: 'secret', description: 'X 登录态 auth_token（解析需登录推文用，受 Cloudflare 指纹限制可能 403）' },
+                { key: 'twitterCt0', type: 'string', default: '', role: 'secret', description: 'X 登录态 ct0（与 auth_token 配对）' },
+                { key: 'tweetTranslateEnabled', type: 'boolean', default: true, description: '外语推文自动翻译（配置 X 登录态时用网页同源 Grok 翻译，否则通用翻译；附译文行）' },
+                {
+                    key: 'tweetTranslateLang', type: 'union', default: 'zh', description: '翻译目标语言',
+                    values: [
+                        { value: 'zh', description: '简体中文' },
+                        { value: 'zh-TW', description: '繁體中文' },
+                        { value: 'en', description: 'English' },
+                        { value: 'ja', description: '日本語' },
+                        { value: 'ko', description: '한국어' },
+                        { value: 'fr', description: 'Français' },
+                        { value: 'de', description: 'Deutsch' },
+                        { value: 'ru', description: 'Русский' },
+                        { value: 'es', description: 'Español' },
+                        { value: 'pt', description: 'Português' },
+                    ],
+                },
+                { key: 'apiKey', type: 'string', default: '', role: 'secret', description: '新网关 API Key（https://api-new.ifphp.com/auth/login 注册获取；留空用旧网关）' },
+            ],
+        }),
+        (0, config_1.defineConfig)({
+            group: '界面文本',
+            fields: [
+                { key: 'waitingTipText', type: 'string', default: '正在解析视频，请稍候...', description: '等待提示' },
+                { key: 'unsupportedPlatformText', type: 'string', default: '不支持该平台链接', description: '不支持提示' },
+                { key: 'invalidLinkText', type: 'string', default: '无效的视频链接', description: '无效链接提示' },
+                { key: 'parseErrorPrefix', type: 'string', default: '❌ 解析失败：', description: '错误前缀' },
+                { key: 'parseErrorItemFormat', type: 'string', default: '【${url}】: ${msg}', description: '错误格式' },
+                { key: 'deduplicationTipText', type: 'string', default: '链接 ${url} 在最近 ${interval} 秒内已解析过，已跳过。', description: '重复解析提示，支持变量 ${url} ${interval}' },
+            ],
+        }),
+    ];
+}

package/lib/engine/twitter-user.d.ts

@@ -0,0 +1,67 @@
+/**
+ * X 用户维度查询：时间线（推文/回复/点赞）与关注/粉丝列表。
+ *
+ * 全部走鉴权 GraphQL（auth_token + ct0，TLS 指纹由 tlsget-rs 提供）。
+ * queryId 与特性集等公共件见 ./twitter（DEFAULT_QUERY_IDS 可被调用方覆盖）。
+ */
+import type { ParsedData } from '../types';
+import { categorizeTweetResult, DEFAULT_QUERY_IDS, TIMELINE_FEATURES, type GraphqlGetter, type TwitterCreds, type TwitterQueryIds } from './twitter';
+export { categorizeTweetResult, DEFAULT_QUERY_IDS, TIMELINE_FEATURES };
+export type { TwitterQueryIds };
+export interface TwitterUserInfo {
+    userId: string;
+    name: string;
+    screenName: string;
+    description: string;
+    followers: number;
+    friends: number;
+}
+export declare function resolveTwitterUser(screenName: string, creds: TwitterCreds, get?: GraphqlGetter, queryIds?: TwitterQueryIds): Promise<TwitterUserInfo>;
+export type TimelineTab = 'tweets' | 'replies' | 'likes';
+export interface TimelineEntry {
+    id: string;
+    tweet: ParsedData;
+    /** 文字/视频/图片/转推/回复 中的若干类 */
+    kinds: ('text' | 'video' | 'image' | 'retweet' | 'reply')[];
+    isRetweet: boolean;
+    isReply: boolean;
+    replyToId?: string;
+    url: string;
+}
+/** 兼容别名：timeline instructions → 推文结果 + 底部游标 */
+export declare function parseTimeline(instructions: any[]): {
+    results: any[];
+    bottomCursor?: string;
+};
+/** 用户时间线（tab：tweets=推文/转推；replies=含回复；likes=当前登录用户的点赞） */
+export declare function fetchUserTimeline(opts: {
+    screenName?: string;
+    userId?: string;
+    tab?: TimelineTab;
+    limit?: number;
+    creds: TwitterCreds;
+    get?: GraphqlGetter;
+    queryIds?: TwitterQueryIds;
+}): Promise<TimelineEntry[]>;
+export interface TwitterConnectionUser {
+    name: string;
+    screenName: string;
+    description: string;
+    followers: number;
+    verified: boolean;
+    followedBy: boolean;
+}
+/** 纯函数：从 Followers/Following instructions 抽取用户与底部游标 */
+export declare function parseConnections(instructions: any[]): {
+    users: TwitterConnectionUser[];
+    bottomCursor?: string;
+};
+/** 关注列表（following）或粉丝列表（followers） */
+export declare function fetchUserConnections(opts: {
+    screenName: string;
+    type: 'followers' | 'following';
+    limit?: number;
+    creds: TwitterCreds;
+    get?: GraphqlGetter;
+    queryIds?: TwitterQueryIds;
+}): Promise<TwitterConnectionUser[]>;

package/lib/engine/twitter-user.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TIMELINE_FEATURES = exports.DEFAULT_QUERY_IDS = exports.categorizeTweetResult = void 0;
+exports.resolveTwitterUser = resolveTwitterUser;
+exports.parseTimeline = parseTimeline;
+exports.fetchUserTimeline = fetchUserTimeline;
+exports.parseConnections = parseConnections;
+exports.fetchUserConnections = fetchUserConnections;
+const tls_client_1 = require("../utils/tls-client");
+const twitter_1 = require("./twitter");
+Object.defineProperty(exports, "categorizeTweetResult", { enumerable: true, get: function () { return twitter_1.categorizeTweetResult; } });
+Object.defineProperty(exports, "DEFAULT_QUERY_IDS", { enumerable: true, get: function () { return twitter_1.DEFAULT_QUERY_IDS; } });
+Object.defineProperty(exports, "TIMELINE_FEATURES", { enumerable: true, get: function () { return twitter_1.TIMELINE_FEATURES; } });
+async function resolveTwitterUser(screenName, creds, get = tls_client_1.tlsGet, queryIds = {}) {
+    const ids = { ...twitter_1.DEFAULT_QUERY_IDS, ...queryIds };
+    const variables = {
+        screen_name: screenName.replace(/^@/, ''),
+        withSafetyModeUserFields: true,
+        withSuperFollowsUserFields: true,
+    };
+    const data = await (0, twitter_1.twitterGraphql)('UserByScreenName', ids.UserByScreenName, variables, creds, get);
+    const user = data?.data?.user?.result;
+    if (!user || user.__typename === 'UserUnavailable') {
+        throw new Error(`用户 @${screenName} 不可访问（不存在、被封或需登录）`);
+    }
+    const legacy = user.legacy || user.core || {};
+    return {
+        userId: String(user.rest_id ?? legacy.id_str ?? ''),
+        name: String(legacy.name ?? ''),
+        screenName: String(legacy.screen_name ?? screenName.replace(/^@/, '')),
+        description: String(user.profile_bio?.description ?? legacy.description ?? ''),
+        followers: Number(legacy.followers_count ?? 0) || 0,
+        friends: Number(legacy.friends_count ?? 0) || 0,
+    };
+}
+/** 兼容别名：timeline instructions → 推文结果 + 底部游标 */
+function parseTimeline(instructions) {
+    return (0, twitter_1.walkTimelineResults)(instructions);
+}
+/** 用户时间线（tab：tweets=推文/转推；replies=含回复；likes=当前登录用户的点赞） */
+async function fetchUserTimeline(opts) {
+    const tab = opts.tab || 'tweets';
+    const limit = Math.max(1, Math.min(200, opts.limit ?? 20));
+    const get = opts.get || tls_client_1.tlsGet;
+    const ids = { ...twitter_1.DEFAULT_QUERY_IDS, ...opts.queryIds };
+    let userId = opts.userId;
+    if (!userId) {
+        const u = await resolveTwitterUser(opts.screenName, opts.creds, get, opts.queryIds);
+        userId = u.userId;
+    }
+    const [opName, queryId] = tab === 'likes'
+        ? ['Likes', ids.Likes]
+        : tab === 'replies'
+            ? ['UserTweetsAndReplies', ids.UserTweetsAndReplies]
+            : ['UserTweets', ids.UserTweets];
+    const out = [];
+    const seen = new Set();
+    let cursor;
+    let pages = 0;
+    while (out.length < limit && pages < 20) {
+        pages++;
+        const variables = {
+            userId,
+            count: 20,
+            includePromotedContent: false,
+            withQuickPromoteEligibilityTweetQuery: false,
+            withVoice: true,
+            withV2Timeline: true,
+        };
+        if (cursor)
+            variables.cursor = cursor;
+        const data = await (0, twitter_1.twitterGraphql)(opName, queryId, variables, opts.creds, get);
+        const instructions = (() => {
+            const user = data?.data?.user?.result;
+            return (user?.timeline_v2?.timeline || user?.timeline?.timeline)?.instructions || [];
+        })();
+        const { results, bottomCursor } = (0, twitter_1.walkTimelineResults)(instructions);
+        for (const r of results) {
+            const cat = (0, twitter_1.categorizeTweetResult)(r);
+            if (!cat.id || seen.has(cat.id))
+                continue;
+            seen.add(cat.id);
+            const kinds = [];
+            if (cat.isRetweet)
+                kinds.push('retweet');
+            if (cat.isReply)
+                kinds.push('reply');
+            if (cat.hasVideo)
+                kinds.push('video');
+            else if (cat.hasImage)
+                kinds.push('image');
+            else if (!cat.isRetweet)
+                kinds.push('text');
+            out.push({
+                id: cat.id,
+                tweet: (0, twitter_1.mapGraphql)(cat.inner),
+                kinds,
+                isRetweet: cat.isRetweet,
+                isReply: cat.isReply,
+                replyToId: cat.replyToId,
+                url: `https://x.com/i/web/status/${cat.id}`,
+            });
+            if (out.length >= limit)
+                break;
+        }
+        if (!bottomCursor || !results.length)
+            break;
+        cursor = bottomCursor;
+    }
+    return out;
+}
+function userOfEntry(itemContent) {
+    const user = itemContent?.user_results?.result;
+    if (!user || user.__typename === 'UserUnavailable')
+        return null;
+    const legacy = user.legacy || {};
+    return {
+        name: String(legacy.name ?? user.core?.name ?? ''),
+        screenName: String(legacy.screen_name ?? user.core?.screen_name ?? ''),
+        description: String(user.profile_bio?.description ?? legacy.description ?? ''),
+        followers: Number(legacy.followers_count ?? 0) || 0,
+        verified: !!user.is_blue_verified || !!legacy.verified,
+        followedBy: !!legacy.followed_by,
+    };
+}
+/** 纯函数：从 Followers/Following instructions 抽取用户与底部游标 */
+function parseConnections(instructions) {
+    const users = [];
+    let bottomCursor;
+    for (const ins of instructions || []) {
+        for (const entry of ins?.entries || []) {
+            const content = entry?.content;
+            if (!content)
+                continue;
+            if (content.entryType === 'TimelineTimelineCursor' && content.contentType === 'Bottom') {
+                bottomCursor = String(content.value || bottomCursor || '');
+                continue;
+            }
+            if (content.entryType === 'TimelineTimelineItem' && content.itemContent) {
+                const u = userOfEntry(content.itemContent);
+                if (u && u.screenName)
+                    users.push(u);
+            }
+        }
+    }
+    return { users, bottomCursor };
+}
+/** 关注列表（following）或粉丝列表（followers） */
+async function fetchUserConnections(opts) {
+    const limit = Math.max(1, Math.min(1000, opts.limit ?? 50));
+    const get = opts.get || tls_client_1.tlsGet;
+    const ids = { ...twitter_1.DEFAULT_QUERY_IDS, ...opts.queryIds };
+    const u = await resolveTwitterUser(opts.screenName, opts.creds, get, opts.queryIds);
+    const [opName, queryId] = opts.type === 'following'
+        ? ['Following', ids.Following]
+        : ['Followers', ids.Followers];
+    const out = [];
+    const seen = new Set();
+    let cursor;
+    let pages = 0;
+    while (out.length < limit && pages < 50) {
+        pages++;
+        const variables = { userId: u.userId, count: 50, includePromotedContent: false };
+        if (cursor)
+            variables.cursor = cursor;
+        const data = await (0, twitter_1.twitterGraphql)(opName, queryId, variables, opts.creds, get);
+        const instructions = (() => {
+            const user = data?.data?.user?.result;
+            return (user?.timeline_v2?.timeline || user?.timeline?.timeline)?.instructions || [];
+        })();
+        const { users, bottomCursor } = parseConnections(instructions);
+        for (const user of users) {
+            if (seen.has(user.screenName))
+                continue;
+            seen.add(user.screenName);
+            out.push(user);
+            if (out.length >= limit)
+                break;
+        }
+        if (!bottomCursor || !users.length)
+            break;
+        cursor = bottomCursor;
+    }
+    return out;
+}

package/lib/engine/twitter.d.ts

@@ -13,6 +13,37 @@ export interface TwitterCreds {
     authToken: string;
     ct0: string;
 }
+export interface TwitterQueryIds {
+    UserByScreenName?: string;
+    UserTweets?: string;
+    UserTweetsAndReplies?: string;
+    Likes?: string;
+    Followers?: string;
+    Following?: string;
+    TweetDetail?: string;
+}
+/** 默认 queryId 清单（随 x.com web 版本漂移；调用方可整体覆盖） */
+export declare const DEFAULT_QUERY_IDS: Required<TwitterQueryIds>;
+/** 时间线类查询的特性集（UserTweets/Likes/Followers/TweetDetail 共用） */
+export declare const TIMELINE_FEATURES: Record<string, boolean>;
+/** 鉴权 GraphQL 通用请求（headers/cookie 与 TweetResultByRestId 同源） */
+export declare function twitterGraphql(opName: string, queryId: string, variables: Record<string, any>, creds: TwitterCreds, get: GraphqlGetter, features?: Record<string, boolean>): Promise<any>;
+/** 纯函数：把单条 tweet result 归类（含转推解包） */
+export declare function categorizeTweetResult(result: any): {
+    inner: any;
+    isRetweet: boolean;
+    isReply: boolean;
+    hasVideo: boolean;
+    hasImage: boolean;
+    isText: boolean;
+    id: string;
+    replyToId?: string;
+};
+/** 纯函数：从 timeline instructions 抽取推文结果与底部游标（Item/Module 均收） */
+export declare function walkTimelineResults(instructions: any[]): {
+    results: any[];
+    bottomCursor?: string;
+};
 export interface GrokTranslation {
     text: string;
     sourceLang?: string;
@@ -23,4 +54,49 @@ export interface GrokTranslation {
  * 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 extractTweetId(url: string): string | null;
+/** 把 GraphQL TweetResultByRestId 响应映射为 ParsedData */
+export declare function mapGraphql(rawResult: any): ParsedData;
+/** 解除 TweetWithVisibilityResults 包裹（NSFW/受限推文） */
+export declare function unwrapTweetResult(result: any): any;
+/** 鉴权 GraphQL 原始获取：返回未映射的 tweet result 节点（树构建复用） */
+export declare function fetchGraphqlRaw(id: string, creds: TwitterCreds, get: GraphqlGetter): Promise<any>;
 export declare function parseTwitter(url: string, http: AxiosInstance, creds?: TwitterCreds, getGraphql?: GraphqlGetter): Promise<ParsedData>;
+/**
+ * 推文树节点：
+ * - quoted = 本推引用的推文（递归）
+ * - replyTo = 本推回复的目标（向根方向递归）
+ * - replies = 本推收到的回复（评论，向下递归；withReplies 时填充）
+ */
+export interface TweetTree {
+    id: string;
+    tweet: ParsedData;
+    quoted?: TweetTree;
+    replyTo?: TweetTree;
+    replies?: TweetTree[];
+}
+/** 游客态（syndication）取被引用推文 ID：显式字段优先；否则启发式——引用链的
+ *  t.co 短链由 X 追加在正文末尾，expanded_url 为推文永久链。 */
+export declare function guestQuoteId(tw: any): string | undefined;
+/** 游客态（syndication）取回复目标推文 ID */
+export declare function guestReplyToId(tw: any): string | undefined;
+export interface FetchTweetTreeOptions {
+    /** 拉取会话回复树（TweetDetail；需登录态） */
+    withReplies?: boolean;
+    /** 回复条数上限（默认 100） */
+    repliesLimit?: number;
+    /** queryId 覆盖 */
+    queryIds?: TwitterQueryIds;
+}
+/**
+ * 纯函数：由会话内的全部 tweet result 装配回复树（挂在 focal 节点下）。
+ * 依据 in_reply_to_status_id_str 建父子边；父不在集合内的孤儿回复跳过。
+ */
+export declare function assembleReplies(focalId: string, results: any[], limit: number, makeNode: (raw: any) => TweetTree): TweetTree[];
+/**
+ * 拉取推文树：引用链（quoted，向下递归）+ 回复链（replyTo，向根递归）
+ * + 可选会话回复树（replies，向下递归，TweetDetail 装配）。
+ * - 有登录态：GraphQL 单次响应自带嵌套 quoted_status_result；父级逐次拉取
+ * - 无登录态：syndication 逐节点拉取（引用 ID 走启发式）；不可达分支静默截断
+ */
+export declare function fetchTweetTree(url: string, http: AxiosInstance, creds?: TwitterCreds, getGraphql?: GraphqlGetter, opts?: FetchTweetTreeOptions): Promise<TweetTree>;

package/lib/engine/twitter.js

@@ -1,7 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TIMELINE_FEATURES = exports.DEFAULT_QUERY_IDS = void 0;
+exports.twitterGraphql = twitterGraphql;
+exports.categorizeTweetResult = categorizeTweetResult;
+exports.walkTimelineResults = walkTimelineResults;
 exports.fetchGrokTranslation = fetchGrokTranslation;
+exports.extractTweetId = extractTweetId;
+exports.mapGraphql = mapGraphql;
+exports.unwrapTweetResult = unwrapTweetResult;
+exports.fetchGraphqlRaw = fetchGraphqlRaw;
 exports.parseTwitter = parseTwitter;
+exports.guestQuoteId = guestQuoteId;
+exports.guestReplyToId = guestReplyToId;
+exports.assembleReplies = assembleReplies;
+exports.fetchTweetTree = fetchTweetTree;
 const tls_client_1 = require("../utils/tls-client");
 /**
  * X / Twitter 原生解析器。
@@ -33,6 +45,138 @@ const GRAPHQL_FEATURES = {
     longform_notetweets_rich_text_read_enabled: true,
     responsive_web_graphql_timeline_navigation_enabled: true,
 };
+/** 默认 queryId 清单（随 x.com web 版本漂移；调用方可整体覆盖） */
+exports.DEFAULT_QUERY_IDS = {
+    UserByScreenName: 'sLVLhk0bGj3MVFEKTdax1w',
+    UserTweets: 'HuTx74BxAnezK1gWvYY7zg',
+    UserTweetsAndReplies: 'RIWc55YCNyUJ-U3HHGYkdg',
+    Likes: 'nXEl0lfN_XSznVMlprThgQ',
+    Followers: 'pd8Tt1qUz1YWrICegqZ8cw',
+    Following: 'wjvx62Hye2dGVvnvVco0xA',
+    TweetDetail: 'zXaXQgfyR4GxE21uwYQSyA',
+};
+/** 时间线类查询的特性集（UserTweets/Likes/Followers/TweetDetail 共用） */
+exports.TIMELINE_FEATURES = {
+    blue_business_profile_image_shape_enabled: true,
+    creator_subscriptions_tweet_preview_api_enabled: true,
+    freedom_of_speech_not_reach_fetch_enabled: true,
+    graphql_is_translatable_rweb_tweet_is_translatable_enabled: true,
+    graphql_timeline_v2_bookmark_timeline: true,
+    hidden_profile_likes_enabled: true,
+    highlights_tweets_tab_ui_enabled: true,
+    interactive_text_enabled: true,
+    longform_notetweets_consumption_enabled: true,
+    longform_notetweets_inline_media_enabled: true,
+    longform_notetweets_rich_text_read_enabled: true,
+    longform_notetweets_richtext_consumption_enabled: true,
+    profile_foundations_tweet_stats_enabled: true,
+    profile_foundations_tweet_stats_tweet_frequency: true,
+    responsive_web_birdwatch_note_limit_enabled: true,
+    responsive_web_edit_tweet_api_enabled: true,
+    responsive_web_enhance_cards_enabled: false,
+    responsive_web_graphql_exclude_directive_enabled: true,
+    responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+    responsive_web_graphql_timeline_navigation_enabled: true,
+    responsive_web_media_download_video_enabled: false,
+    responsive_web_text_conversations_enabled: false,
+    responsive_web_twitter_article_data_v2_enabled: true,
+    responsive_web_twitter_article_tweet_consumption_enabled: false,
+    responsive_web_twitter_blue_verified_badge_is_enabled: true,
+    rweb_lists_timeline_redesign_enabled: true,
+    spaces_2022_h2_clipping: true,
+    spaces_2022_h2_spaces_communities: true,
+    standardized_nudges_misinfo: true,
+    subscriptions_verification_info_verified_since_enabled: true,
+    tweet_awards_web_tipping_enabled: false,
+    tweet_with_visibility_results_prefer_gql_limited_actions_policy_enabled: true,
+    tweetypie_unmention_optimization_enabled: true,
+    verified_phone_label_enabled: false,
+    vibe_api_enabled: true,
+    view_counts_everywhere_api_enabled: true,
+};
+/** 鉴权 GraphQL 通用请求（headers/cookie 与 TweetResultByRestId 同源） */
+async function twitterGraphql(opName, queryId, variables, creds, get, features = exports.TIMELINE_FEATURES) {
+    const url = `https://x.com/i/api/graphql/${queryId}/${opName}` +
+        `?variables=${encodeURIComponent(JSON.stringify(variables))}&features=${encodeURIComponent(JSON.stringify(features))}`;
+    let res;
+    try {
+        res = await get(url, {
+            headers: {
+                authorization: `Bearer ${WEB_BEARER}`,
+                'x-csrf-token': creds.ct0,
+                'x-twitter-auth-type': 'OAuth2Session',
+                'x-twitter-active-user': 'yes',
+                'x-twitter-client-language': 'en',
+            },
+            cookies: { auth_token: creds.authToken, ct0: creds.ct0 },
+            timeout: 30000,
+        });
+    }
+    catch (e) {
+        throw new Error(`X GraphQL 请求失败：${e?.message || e}`);
+    }
+    if (res.status === 403 || res.status === 429) {
+        throw new Error(`X GraphQL 被 Cloudflare 拦截 (HTTP ${res.status})：TLS 指纹校验未通过。` +
+            `请确认已安装可选依赖 @char46/tlsget-rs（npm i @char46/tlsget-rs），它提供浏览器级 TLS 指纹。`);
+    }
+    if (res.status !== 200) {
+        throw new Error(`X GraphQL ${opName} 返回 HTTP ${res.status}：${typeof res.data === 'string' ? res.data.slice(0, 120) : JSON.stringify(res.data || {}).slice(0, 120)}`);
+    }
+    return res.data;
+}
+/** 纯函数：把单条 tweet result 归类（含转推解包） */
+function categorizeTweetResult(result) {
+    const raw = unwrapTweetResult(result);
+    const rtInner = raw?.legacy?.retweeted_status_result?.result;
+    const inner = rtInner ? unwrapTweetResult(rtInner) : raw;
+    const legacy = inner?.legacy || {};
+    const media = Array.isArray(legacy.extended_entities?.media) ? legacy.extended_entities.media : [];
+    const hasImage = media.some((m) => m?.type === 'photo');
+    const hasVideo = media.some((m) => m?.type === 'video' || m?.type === 'animated_gif');
+    const isRetweet = !!rtInner;
+    const replyToId = typeof legacy.in_reply_to_status_id_str === 'string' ? legacy.in_reply_to_status_id_str : undefined;
+    const isReply = !!replyToId;
+    const isText = !hasImage && !hasVideo && !isRetweet;
+    return {
+        inner,
+        isRetweet,
+        isReply,
+        hasVideo,
+        hasImage,
+        isText,
+        id: String(inner?.rest_id ?? legacy.id_str ?? ''),
+        replyToId,
+    };
+}
+/** 纯函数：从 timeline instructions 抽取推文结果与底部游标（Item/Module 均收） */
+function walkTimelineResults(instructions) {
+    const results = [];
+    let bottomCursor;
+    for (const ins of instructions || []) {
+        const entries = ins?.entries || ins?.entry ? [].concat(ins.entry, ins.entries).filter(Boolean) : [];
+        for (const entry of entries) {
+            const content = entry?.content;
+            if (!content)
+                continue;
+            if (content.entryType === 'TimelineTimelineCursor' && content.contentType === 'Bottom') {
+                bottomCursor = String(content.value || bottomCursor || '');
+                continue;
+            }
+            if (content.entryType === 'TimelineTimelineItem' && content.itemContent?.tweet_results?.result) {
+                results.push(content.itemContent.tweet_results.result);
+                continue;
+            }
+            if (content.entryType === 'TimelineTimelineModule') {
+                for (const item of content.items || []) {
+                    const r = item?.itemContent?.tweet_results?.result;
+                    if (r)
+                        results.push(r);
+                }
+            }
+        }
+    }
+    return { results, bottomCursor };
+}
 /** Grok 翻译特性集（与网页端抓包一致；关键是 grok_show_grok_translated_post 开关） */
 const GROK_FEATURES = {
     creator_subscriptions_tweet_preview_api_enabled: true,
@@ -138,14 +282,45 @@ function pick(...vals) {
             return v;
     return '';
 }
-/** 清理描述中的 t.co 短链（Twitter 自动附加的截断 URL，无实际内容价值） */
+/** BFS 深取子树中第一个非空的指定键值（X GraphQL 用户结构随版本漂移：legacy ↔ core/avatar） */
+function deepPick(node, key) {
+    const queue = [node];
+    while (queue.length) {
+        const cur = queue.shift();
+        if (!cur || typeof cur !== 'object')
+            continue;
+        const v = cur[key];
+        if (v !== undefined && v !== null && v !== '')
+            return v;
+        for (const k of Object.keys(cur))
+            queue.push(cur[k]);
+    }
+    return undefined;
+}
+/** BFS 找子树中最长的 text 字符串（笔记正文位置随版本漂移，取最长以避开截断副本） */
+function deepFindLongestText(node) {
+    let best;
+    const queue = [node];
+    while (queue.length) {
+        const cur = queue.shift();
+        if (!cur || typeof cur !== 'object')
+            continue;
+        if (typeof cur.text === 'string' && cur.text && (!best || cur.text.length > best.length))
+            best = cur.text;
+        for (const k of Object.keys(cur))
+            queue.push(cur[k]);
+    }
+    return best;
+}
+/** 清理描述中的 t.co 短链（Twitter 自动附加的截断 URL，无实际内容价值）。
+ *  注意保留段落换行：仅折叠水平空白，≥3 连续换行压成空行一档。 */
 function cleanDesc(text) {
     if (!text)
         return text;
-    // 移除末尾的 t.co URL（含可能的空格前导）
-    let cleaned = text.replace(/\s*https?:\/\/t\.co\/[A-Za-z0-9]+(?:\?[^\s]*)?\s*$/g, '').trim();
-    // 移除中间出现的 t.co URL（较少见，但推文内嵌的缩短链）
-    cleaned = cleaned.replace(/\s*https?:\/\/t\.co\/[A-Za-z0-9]+/g, ' ').replace(/\s{2,}/g, ' ').trim();
+    // 去掉全部 t.co URL（文末自动附加 + 文中内嵌）
+    let cleaned = text.replace(/https?:\/\/t\.co\/[A-Za-z0-9]+(?:\?[^\s]*)?/g, '');
+    // 仅折叠空格/制表（不动换行）；去掉行首尾空格；连续空行压成一个空行
+    cleaned = cleaned.replace(/[^\S\n]+/g, ' ').replace(/ *\n */g, '\n').replace(/\n{3,}/g, '\n\n').trim();
     return cleaned || text;
 }
 function baseParsed() {
@@ -273,8 +448,10 @@ function mapGraphql(rawResult) {
     }
     const legacy = result.legacy || {};
     const user = result.core?.user_results?.result;
-    const ulegacy = user?.legacy || {};
-    const text = String(pick(legacy.full_text, result.note_tweet?.note_results?.note?.text, ''));
+    const ures = user || {};
+    // 长推（note tweet）：legacy.full_text 是截断版，全文在 note_tweet 子树（位置随版本漂移，深取最长 text）
+    // 用户字段同理：legacy ↔ core/avatar/profile_bio 漂移，深取键值
+    const text = String(pick(deepFindLongestText(result.note_tweet), legacy.full_text, ''));
     const p = baseParsed();
     const media = Array.isArray(legacy.entities?.media) ? legacy.entities.media : [];
     const photos = [];
@@ -318,9 +495,9 @@ function mapGraphql(rawResult) {
     p.title = cleaned.slice(0, 100);
     p.desc = cleaned;
     p.lang = legacy.lang ? String(legacy.lang) : undefined;
-    p.author = String(pick(ulegacy.name, ulegacy.screen_name, ''));
-    p.uid = String(pick(ulegacy.screen_name, user?.rest_id, ''));
-    p.avatar = String(pick(ulegacy.profile_image_url_https, ''));
+    p.author = String(pick(deepPick(ures, 'name'), ''));
+    p.uid = String(pick(deepPick(ures, 'screen_name'), user?.rest_id, ''));
+    p.avatar = String(pick(deepPick(ures, 'profile_image_url_https'), deepPick(ures, 'image_url'), ''));
     p.like = Number(pick(legacy.favorite_count, 0)) || 0;
     p.comment = Number(pick(legacy.reply_count, 0)) || 0;
     p.share = Number(pick(legacy.retweet_count, 0)) || 0;
@@ -331,14 +508,18 @@ function mapGraphql(rawResult) {
         if (!isNaN(t))
             p.publishTime = t;
     }
-    p.author_followers = Number(pick(ulegacy.followers_count, 0)) || 0;
-    p.author_signature = String(pick(ulegacy.description, ''));
+    p.author_followers = Number(pick(deepPick(ures, 'followers_count'), 0)) || 0;
+    p.author_signature = String(pick(deepPick(ures, 'description'), ''));
     if (p.title && p.desc && p.desc.startsWith(p.title))
         p.title = '';
     return p;
 }
-/** 鉴权 GraphQL：仅用 auth_token + ct0，回退取登录受限推文 */
-async function fetchGraphqlTweet(id, creds, get) {
+/** 解除 TweetWithVisibilityResults 包裹（NSFW/受限推文） */
+function unwrapTweetResult(result) {
+    return result && result.__typename === 'TweetWithVisibilityResults' && result.tweet ? result.tweet : result;
+}
+/** 鉴权 GraphQL 原始获取：返回未映射的 tweet result 节点（树构建复用） */
+async function fetchGraphqlRaw(id, creds, get) {
     const variables = { tweetId: id, includePromotedContent: true, withBirdwatchNotes: true, withVoice: true, withCommunity: true };
     const url = `https://x.com/i/api/graphql/${TWEET_RESULT_QUERY_ID}/TweetResultByRestId` +
         `?variables=${encodeURIComponent(JSON.stringify(variables))}&features=${encodeURIComponent(JSON.stringify(GRAPHQL_FEATURES))}`;
@@ -373,7 +554,11 @@ async function fetchGraphqlTweet(id, creds, get) {
         const tb = result?.tombstone?.text?.text || result?.tombstone?.text;
         throw new Error(`推文不可访问（可能需要登录、已被删除或为非公开内容）${tb ? '：' + tb : ''}`);
     }
-    return mapGraphql(result);
+    return unwrapTweetResult(result);
+}
+/** 鉴权 GraphQL：仅用 auth_token + ct0，回退取登录受限推文 */
+async function fetchGraphqlTweet(id, creds, get) {
+    return mapGraphql(await fetchGraphqlRaw(id, creds, get));
 }
 async function parseTwitter(url, http, creds, getGraphql) {
     const id = extractTweetId(url);
@@ -387,7 +572,19 @@ async function parseTwitter(url, http, creds, getGraphql) {
     });
     const tw = res.data;
     if (tw && tw.__typename === 'Tweet' && tw.user) {
-        return mapSyndication(tw);
+        const p = mapSyndication(tw);
+        // 长推：syndication 现仅返回 note_tweet 的 id 引用（无 text），tw.text 被
+        // display_text_range 截断。有登录态时改走 GraphQL 取全文；失败回退截断结果。
+        const noteTruncated = tw.note_tweet && !tw.note_tweet.text;
+        if (noteTruncated && creds && creds.authToken && creds.ct0) {
+            try {
+                return await fetchGraphqlTweet(id, creds, getGraphql || tls_client_1.tlsGet);
+            }
+            catch {
+                return p;
+            }
+        }
+        return p;
     }
     // 2) tombstone（需登录）：回退到鉴权 GraphQL（TLS 指纹模拟）
     if (creds && creds.authToken && creds.ct0) {
@@ -396,3 +593,199 @@ async function parseTwitter(url, http, creds, getGraphql) {
     const reasonRaw = pick(tw?.tombstone?.text, tw?.tombstone?.name);
     throw new Error(`推文不可访问（可能需要登录、已被删除或为非公开内容）${reasonRaw ? '：' + reasonRaw : ''}`);
 }
+const TREE_QUOTE_DEPTH = 6;
+const TREE_REPLY_DEPTH = 12;
+const TREE_REPLIES_LIMIT = 100;
+/** 游客态（syndication）取被引用推文 ID：显式字段优先；否则启发式——引用链的
+ *  t.co 短链由 X 追加在正文末尾，expanded_url 为推文永久链。 */
+function guestQuoteId(tw) {
+    const q = tw?.quoted_tweet || tw?.quoted_status_result;
+    if (q) {
+        const id = String(pick(q.id_str, q.rest_id, ''));
+        if (/^\d+$/.test(id))
+            return id;
+    }
+    const urls = Array.isArray(tw?.entities?.urls) ? tw.entities.urls : [];
+    const rawText = String(tw?.text || '');
+    const textEnd = rawText.trimEnd();
+    for (const u of urls) {
+        if (!u?.url || !textEnd.endsWith(u.url))
+            continue;
+        const m = /(?:x|twitter)\.com\/[^/]+\/status(?:es)?\/(\d+)/.exec(String(u.expanded_url || ''));
+        if (m)
+            return m[1];
+    }
+    return undefined;
+}
+/** 游客态（syndication）取回复目标推文 ID */
+function guestReplyToId(tw) {
+    const id = pick(tw?.in_reply_to_status_id_str, tw?.in_reply_to_status_id);
+    if (typeof id === 'string' && /^\d+$/.test(id))
+        return id;
+    if (typeof id === 'number')
+        return String(id);
+    return undefined;
+}
+async function fetchSyndicationRaw(tweetId, http) {
+    const res = await http.get(SYNDICATION_URL, {
+        params: { id: tweetId, token: 'a' },
+        timeout: 30000,
+        headers: { 'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36' },
+    });
+    const tw = res.data;
+    return tw && tw.__typename === 'Tweet' && tw.user ? tw : null;
+}
+/**
+ * 纯函数：由会话内的全部 tweet result 装配回复树（挂在 focal 节点下）。
+ * 依据 in_reply_to_status_id_str 建父子边；父不在集合内的孤儿回复跳过。
+ */
+function assembleReplies(focalId, results, limit, makeNode) {
+    const byId = new Map();
+    for (const r of results) {
+        const cat = categorizeTweetResult(r);
+        if (!cat.id || byId.has(cat.id) || cat.id === focalId)
+            continue;
+        byId.set(cat.id, { node: makeNode(cat.inner), replyToId: cat.replyToId });
+    }
+    const childrenOf = new Map();
+    const roots = [];
+    for (const { node, replyToId } of byId.values()) {
+        if (replyToId && byId.has(replyToId)) {
+            ;
+            (childrenOf.get(replyToId) || childrenOf.set(replyToId, []).get(replyToId)).push(node);
+        }
+        else if (replyToId === focalId) {
+            roots.push(node);
+        }
+        /* 父不在集合内（祖先线程外）→ 跳过 */
+    }
+    let budget = limit;
+    const attach = (nodes) => {
+        const out = [];
+        for (const n of nodes) {
+            if (budget <= 0)
+                break;
+            budget--;
+            n.replies = attach(childrenOf.get(n.id) || []);
+            out.push(n);
+        }
+        return out;
+    };
+    return attach(roots);
+}
+/**
+ * 拉取推文树：引用链（quoted，向下递归）+ 回复链（replyTo，向根递归）
+ * + 可选会话回复树（replies，向下递归，TweetDetail 装配）。
+ * - 有登录态：GraphQL 单次响应自带嵌套 quoted_status_result；父级逐次拉取
+ * - 无登录态：syndication 逐节点拉取（引用 ID 走启发式）；不可达分支静默截断
+ */
+async function fetchTweetTree(url, http, creds, getGraphql, opts = {}) {
+    const id = extractTweetId(url);
+    if (!id)
+        throw new Error('无法从 X 链接提取推文 ID');
+    const visited = new Set();
+    async function buildGuest(tweetId, depth) {
+        visited.add(tweetId);
+        const tw = await fetchSyndicationRaw(tweetId, http);
+        if (!tw)
+            throw new Error(`推文 ${tweetId} 不可访问（可能需要登录或已删除）`);
+        const node = { id: tweetId, tweet: mapSyndication(tw) };
+        const qid = guestQuoteId(tw);
+        if (qid && !visited.has(qid) && depth < TREE_QUOTE_DEPTH) {
+            try {
+                node.quoted = await buildGuest(qid, depth + 1);
+            }
+            catch { /* 引用不可达则截断 */ }
+        }
+        const rid = guestReplyToId(tw);
+        if (rid && !visited.has(rid) && depth < TREE_REPLY_DEPTH) {
+            try {
+                node.replyTo = await buildGuest(rid, depth + 1);
+            }
+            catch { /* 父推不可达则截断 */ }
+        }
+        return node;
+    }
+    async function buildFromGraphqlResult(raw, depth) {
+        raw = unwrapTweetResult(raw);
+        const rid0 = String(pick(raw?.rest_id, raw?.legacy?.id_str, ''));
+        if (rid0)
+            visited.add(rid0);
+        const node = { id: rid0, tweet: mapGraphql(raw) };
+        const q = unwrapTweetResult(raw?.quoted_status_result?.result);
+        if (q && q.legacy && q.__typename !== 'TweetTombstone' && depth < TREE_QUOTE_DEPTH) {
+            const qid = String(pick(q.rest_id, q.legacy?.id_str, ''));
+            if (!qid || !visited.has(qid))
+                node.quoted = await buildFromGraphqlResult(q, depth + 1);
+        }
+        const rid = raw?.legacy?.in_reply_to_status_id_str;
+        if (typeof rid === 'string' && /^\d+$/.test(rid) && !visited.has(rid) && depth < TREE_REPLY_DEPTH) {
+            try {
+                node.replyTo = await buildGraphqlById(rid, depth + 1);
+            }
+            catch { /* 父推不可达则截断 */ }
+        }
+        return node;
+    }
+    async function buildGraphqlById(tweetId, depth) {
+        if (visited.has(tweetId))
+            throw new Error('引用环');
+        const raw = await fetchGraphqlRaw(tweetId, creds, getGraphql || tls_client_1.tlsGet);
+        return buildFromGraphqlResult(raw, depth);
+    }
+    /** 同步构建会话回复节点：嵌套引用链照常递归（无需网络），父链不拉（由会话集合装配） */
+    function nodeFromResultSync(raw) {
+        raw = unwrapTweetResult(raw);
+        const rid0 = String(pick(raw?.rest_id, raw?.legacy?.id_str, ''));
+        if (rid0)
+            visited.add(rid0);
+        const node = { id: rid0, tweet: mapGraphql(raw) };
+        const q = unwrapTweetResult(raw?.quoted_status_result?.result);
+        if (q && q.legacy && q.__typename !== 'TweetTombstone') {
+            const qid = String(pick(q.rest_id, q.legacy?.id_str, ''));
+            if (!qid || !visited.has(qid))
+                node.quoted = nodeFromResultSync(q);
+        }
+        return node;
+    }
+    async function attachConversation(node) {
+        if (!node)
+            return;
+        const qids = { ...exports.DEFAULT_QUERY_IDS, ...opts.queryIds };
+        const variables = {
+            focalTweetId: node.id,
+            with_rux_injections: false,
+            rankingMode: 'Relevance',
+            includePromotedContent: true,
+            withCommunity: true,
+            withQuickPromoteEligibilityTweetQuery: false,
+            withBirdwatchNotes: true,
+            withVoice: true,
+        };
+        const data = await twitterGraphql('TweetDetail', qids.TweetDetail, variables, creds, getGraphql || tls_client_1.tlsGet);
+        const instructions = data?.data?.threaded_conversation_with_injections_v2?.timeline?.instructions;
+        const { results } = walkTimelineResults(instructions || []);
+        node.replies = assembleReplies(node.id, results, opts.repliesLimit ?? TREE_REPLIES_LIMIT, nodeFromResultSync);
+    }
+    const usedGraphql = !!(creds && creds.authToken && creds.ct0);
+    let tree;
+    if (usedGraphql) {
+        try {
+            tree = await buildGraphqlById(id, 0);
+        }
+        catch {
+            /* 登录态失败（如 Cloudflare）回退游客路径 */
+            tree = await buildGuest(id, 0);
+        }
+    }
+    else {
+        tree = await buildGuest(id, 0);
+    }
+    if (opts.withReplies && usedGraphql && tree) {
+        try {
+            await attachConversation(tree);
+        }
+        catch { /* 会话不可达则保留无回复树 */ }
+    }
+    return tree;
+}

package/lib/index.d.ts

@@ -19,9 +19,11 @@ export * from './utils/tls-client';
 export * from './utils/gif';
 export * from './utils/merge';
 export * from './engine/gateway';
+export * from './engine/config';
 export * from './engine/platform-config';
 export * from './engine/translate';
 export * from './engine/twitter';
+export * from './engine/twitter-user';
 export * from './engine/parser';
 export * from './engine/fetcher';
 export * from './engine/runtime';

package/lib/index.js

@@ -35,9 +35,11 @@ __exportStar(require("./utils/tls-client"), exports);
 __exportStar(require("./utils/gif"), exports);
 __exportStar(require("./utils/merge"), exports);
 __exportStar(require("./engine/gateway"), exports);
+__exportStar(require("./engine/config"), exports);
 __exportStar(require("./engine/platform-config"), exports);
 __exportStar(require("./engine/translate"), exports);
 __exportStar(require("./engine/twitter"), exports);
+__exportStar(require("./engine/twitter-user"), exports);
 __exportStar(require("./engine/parser"), exports);
 __exportStar(require("./engine/fetcher"), exports);
 __exportStar(require("./engine/runtime"), exports);

package/lib/utils/format.js

@@ -28,10 +28,15 @@ function formatPublishTime(ms) {
 }
 function generateFormattedText(p, format, index, total) {
     const imageCount = p.images.length || p.live_photo.length;
+    // 纯文字作品（type=text）：正文即内容。模板含 ${正文} 时启用新语义——
+    // 正文=desc、简介置空（自动隐藏），避免把正文标成「简介」；旧模板保持原行为。
+    const plainTextWork = p.type === 'text' && !!p.desc;
+    const wantsBody = plainTextWork && format.includes('${正文}');
     const vars = {
         '标题': p.title,
         '作者': p.author,
-        '简介': p.desc,
+        '简介': wantsBody ? '' : p.desc,
+        '正文': plainTextWork ? p.desc : '',
         '视频时长': p.duration > 0 ? formatDuration(p.duration) : '',
         '点赞数': String(p.like),
         '收藏数': String(p.collect),

package/lib/utils/merge.d.ts

@@ -28,7 +28,10 @@ export interface SeamVerdict {
     /** 结论文案 */
     reason: string;
 }
-/** 内容验证：所有接缝（趋势+纹理）均通过才成立；返回最大接缝比值与逐缝证据 */
+/** 内容验证：所有接缝（趋势+纹理）均通过才成立；接缝总数 ≥3 时允许至多一条
+ *  「边界容差缝」（比值 ∈ [3,5)——平台独立重压缩的典型错位幅度；多条缝相互
+ *  印证才可信，2 缝场景证据不足不放行；平坦不可验证缝不参与容差）。
+ *  返回最大接缝比值与逐缝证据。 */
 export declare function verifyLayout(layout: MergeLayout, grays: Buffer[]): {
     pass: boolean;
     score: number;

package/lib/utils/merge.js

@@ -37,6 +37,12 @@ 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;
 /* ---------- 尺寸候选 ---------- */
@@ -184,7 +190,10 @@ function seamVerdictH(a, b, from, to) {
         [colOf(b, 2), colOf(b, 1)],
     ]);
 }
-/** 内容验证：所有接缝（趋势+纹理）均通过才成立；返回最大接缝比值与逐缝证据 */
+/** 内容验证：所有接缝（趋势+纹理）均通过才成立；接缝总数 ≥3 时允许至多一条
+ *  「边界容差缝」（比值 ∈ [3,5)——平台独立重压缩的典型错位幅度；多条缝相互
+ *  印证才可信，2 缝场景证据不足不放行；平坦不可验证缝不参与容差）。
+ *  返回最大接缝比值与逐缝证据。 */
 function verifyLayout(layout, grays) {
     const seams = [];
     const n = grays.length;
@@ -208,7 +217,11 @@ function verifyLayout(layout, grays) {
     if (!seams.length)
         return { pass: false, score: Infinity, seams };
     const worst = Math.max(...seams.map((v) => v.score));
-    return { pass: seams.every((v) => v.ok), score: worst, seams };
+    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) {
@@ -232,8 +245,9 @@ function pickMergeLayout(sizes, grays) {
     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 ? '通过' : '拒绝'}，worst=${score === Infinity ? '∞' : score.toFixed(2)} ⟶ ${detail}`);
+        (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 };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sns-parse/core",
-  "version": "0.4.0-alpha.1+upstream.1.6.7",
+  "version": "0.4.0-alpha.10+upstream.1.6.7",
   "description": "sns-parse 核心：契约、宿主抽象、配置 DSL 与解析引擎（fetcher/parser/翻译/X 原生解析/合并/GIF/TLS 指纹客户端）",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "axios": "^1.16.1",
-    "https-proxy-agent": "^9.1.0"
+    "https-proxy-agent": "^5.0.1"
   },
   "optionalDependencies": {
     "@char46/tlsget-rs": "^1.0.0",