@sns-parse/core 0.4.0-alpha.7 → 0.4.0-alpha.9

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

@@ -2,21 +2,12 @@
  * X 用户维度查询：时间线（推文/回复/点赞）与关注/粉丝列表。
  *
  * 全部走鉴权 GraphQL（auth_token + ct0，TLS 指纹由 tlsget-rs 提供）。
- * queryId 随 x.com web 版本漂移：默认值取自活跃维护的开源清单
- * （twitter-api-client），并支持调用方整体覆盖（queryIds 参数）。
+ * queryId 与特性集等公共件见 ./twitter（DEFAULT_QUERY_IDS 可被调用方覆盖）。
  */
 import type { ParsedData } from '../types';
-import { type GraphqlGetter, type TwitterCreds } from './twitter';
-export interface TwitterQueryIds {
-    UserByScreenName?: string;
-    UserTweets?: string;
-    UserTweetsAndReplies?: string;
-    Likes?: string;
-    Followers?: string;
-    Following?: string;
-}
-/** 默认 queryId 清单（漂移时可用 queryIds 参数整体覆盖） */
-export declare const DEFAULT_QUERY_IDS: Required<TwitterQueryIds>;
+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;
@@ -37,18 +28,7 @@ export interface TimelineEntry {
     replyToId?: string;
     url: string;
 }
-/** 纯函数：把单条 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 抽取推文结果与底部游标 */
+/** 兼容别名：timeline instructions → 推文结果 + 底部游标 */
 export declare function parseTimeline(instructions: any[]): {
     results: any[];
     bottomCursor?: string;

package/lib/engine/twitter-user.js

@@ -1,100 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_QUERY_IDS = void 0;
+exports.TIMELINE_FEATURES = exports.DEFAULT_QUERY_IDS = exports.categorizeTweetResult = void 0;
 exports.resolveTwitterUser = resolveTwitterUser;
-exports.categorizeTweetResult = categorizeTweetResult;
 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");
-// x.com 网页端公开 bearer（与 twitter.ts 同源固定值）
-const WEB_BEARER = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
-/** 默认 queryId 清单（漂移时可用 queryIds 参数整体覆盖） */
-exports.DEFAULT_QUERY_IDS = {
-    UserByScreenName: 'sLVLhk0bGj3MVFEKTdax1w',
-    UserTweets: 'HuTx74BxAnezK1gWvYY7zg',
-    UserTweetsAndReplies: 'RIWc55YCNyUJ-U3HHGYkdg',
-    Likes: 'nXEl0lfN_XSznVMlprThgQ',
-    Followers: 'pd8Tt1qUz1YWrICegqZ8cw',
-    Following: 'wjvx62Hye2dGVvnvVco0xA',
-};
-const 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,
-};
-async function gql(opName, queryId, variables, creds, get) {
-    const url = `https://x.com/i/api/graphql/${queryId}/${opName}` +
-        `?variables=${encodeURIComponent(JSON.stringify(variables))}&features=${encodeURIComponent(JSON.stringify(TIMELINE_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;
-}
+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 = { ...exports.DEFAULT_QUERY_IDS, ...queryIds };
+    const ids = { ...twitter_1.DEFAULT_QUERY_IDS, ...queryIds };
     const variables = {
         screen_name: screenName.replace(/^@/, ''),
         withSafetyModeUserFields: true,
         withSuperFollowsUserFields: true,
     };
-    const data = await gql('UserByScreenName', ids.UserByScreenName, variables, creds, get);
+    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} 不可访问（不存在、被封或需登录）`);
@@ -109,70 +33,16 @@ async function resolveTwitterUser(screenName, creds, get = tls_client_1.tlsGet,
         friends: Number(legacy.friends_count ?? 0) || 0,
     };
 }
-/** 纯函数：把单条 tweet result 归类（含转推解包） */
-function categorizeTweetResult(result) {
-    const raw = (0, twitter_1.unwrapTweetResult)(result);
-    const rtInner = raw?.legacy?.retweeted_status_result?.result;
-    const inner = rtInner ? (0, twitter_1.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 抽取推文结果与底部游标 */
+/** 兼容别名：timeline instructions → 推文结果 + 底部游标 */
 function parseTimeline(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 };
-}
-function timelineOf(data) {
-    const user = data?.data?.user?.result;
-    const timeline = user?.timeline_v2?.timeline || user?.timeline?.timeline;
-    return timeline?.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 = { ...exports.DEFAULT_QUERY_IDS, ...opts.queryIds };
+    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);
@@ -199,10 +69,14 @@ async function fetchUserTimeline(opts) {
         };
         if (cursor)
             variables.cursor = cursor;
-        const data = await gql(opName, queryId, variables, opts.creds, get);
-        const { results, bottomCursor } = parseTimeline(timelineOf(data));
+        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 = categorizeTweetResult(r);
+            const cat = (0, twitter_1.categorizeTweetResult)(r);
             if (!cat.id || seen.has(cat.id))
                 continue;
             seen.add(cat.id);
@@ -275,7 +149,7 @@ function parseConnections(instructions) {
 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 = { ...exports.DEFAULT_QUERY_IDS, ...opts.queryIds };
+    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]
@@ -289,8 +163,12 @@ async function fetchUserConnections(opts) {
         const variables = { userId: u.userId, count: 50, includePromotedContent: false };
         if (cursor)
             variables.cursor = cursor;
-        const data = await gql(opName, queryId, variables, opts.creds, get);
-        const { users, bottomCursor } = parseConnections(timelineOf(data));
+        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;

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;
@@ -31,21 +62,41 @@ 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 = 本推回复的目标（向根方向递归） */
+/**
+ * 推文树节点：
+ * - 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，向根递归）。
+ * 拉取推文树：引用链（quoted，向下递归）+ 回复链（replyTo，向根递归）
+ * + 可选会话回复树（replies，向下递归，TweetDetail 装配）。
  * - 有登录态：GraphQL 单次响应自带嵌套 quoted_status_result；父级逐次拉取
  * - 无登录态：syndication 逐节点拉取（引用 ID 走启发式）；不可达分支静默截断
  */
-export declare function fetchTweetTree(url: string, http: AxiosInstance, creds?: TwitterCreds, getGraphql?: GraphqlGetter): Promise<TweetTree>;
+export declare function fetchTweetTree(url: string, http: AxiosInstance, creds?: TwitterCreds, getGraphql?: GraphqlGetter, opts?: FetchTweetTreeOptions): Promise<TweetTree>;

package/lib/engine/twitter.js

@@ -1,5 +1,9 @@
 "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;
@@ -8,6 +12,7 @@ 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");
 /**
@@ -40,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,
@@ -458,6 +595,7 @@ async function parseTwitter(url, http, creds, getGraphql) {
 }
 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) {
@@ -498,11 +636,50 @@ async function fetchSyndicationRaw(tweetId, http) {
     return tw && tw.__typename === 'Tweet' && tw.user ? tw : null;
 }
 /**
- * 拉取推文树：引用链（quoted，向下递归）+ 回复链（replyTo，向根递归）。
+ * 纯函数：由会话内的全部 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) {
+async function fetchTweetTree(url, http, creds, getGraphql, opts = {}) {
     const id = extractTweetId(url);
     if (!id)
         throw new Error('无法从 X 链接提取推文 ID');
@@ -556,13 +733,59 @@ async function fetchTweetTree(url, http, creds, getGraphql) {
         const raw = await fetchGraphqlRaw(tweetId, creds, getGraphql || tls_client_1.tlsGet);
         return buildFromGraphqlResult(raw, depth);
     }
-    if (creds && creds.authToken && creds.ct0) {
+    /** 同步构建会话回复节点：嵌套引用链照常递归（无需网络），父链不拉（由会话集合装配） */
+    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 {
-            return await buildGraphqlById(id, 0);
+            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 buildGuest(id, 0);
+    return tree;
 }

package/lib/utils/merge.d.ts

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

package/lib/utils/merge.js

@@ -37,6 +37,10 @@ const COL_LEN = 64;
 /** 接缝差异 / 内部自然差异 的判定阈值（母图切片 ≈1，无关图片 ≫1；下限 3 防平坦图除零） */
 const BOUNDARY_THRESH = 3.0;
 const MAD_FLOOR = 3.0;
+/** 单缝边界容差：平台（如 X）对各分片独立重压缩会让个别接缝低频轻微错位；
+ *  其余接缝全部通过且仅一条落在 [BOUNDARY_THRESH, BORDERLINE_THRESH) 时放行 */
+const BORDERLINE_THRESH = 5.0;
+const BORDERLINE_MAX = 1;
 /** 边界带纹理能量下限：低于此值视为「不可验证接缝」（相似背景/平边照片会骗过亮度对比） */
 const TEXTURE_MIN = 4.0;
 /* ---------- 尺寸候选 ---------- */
@@ -184,7 +188,9 @@ function seamVerdictH(a, b, from, to) {
         [colOf(b, 2), colOf(b, 1)],
     ]);
 }
-/** 内容验证：所有接缝（趋势+纹理）均通过才成立；返回最大接缝比值与逐缝证据 */
+/** 内容验证：所有接缝（趋势+纹理）均通过才成立；允许至多一条「边界容差缝」
+ *  （比值 ∈ [3,5)，其余全部通过——平台独立重压缩的典型错位幅度；平坦不可验证缝不参与容差）。
+ *  返回最大接缝比值与逐缝证据。 */
 function verifyLayout(layout, grays) {
     const seams = [];
     const n = grays.length;
@@ -208,7 +214,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)
+        || (borderline.length <= BORDERLINE_MAX && failed.length === borderline.length);
+    return { pass, score: worst, seams };
 }
 /** 内容识别：候选布局逐一经接缝连续性验证，取通过者中比值最小的一个 */
 function detectMergeLayout(sizes, grays) {
@@ -232,8 +242,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.7+upstream.1.6.7",
+  "version": "0.4.0-alpha.9+upstream.1.6.7",
   "description": "sns-parse 核心：契约、宿主抽象、配置 DSL 与解析引擎（fetcher/parser/翻译/X 原生解析/合并/GIF/TLS 指纹客户端）",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",