socialdatax-skills 0.2.32 → 0.2.33

package/README.md

@@ -86,7 +86,7 @@ Common search phrases for this skill package:
 - Sensitive Words Check MCP server name: `sensitive-check`
 - Sensitive Words Check future MCP registry name: `com.socialdatax/sensitive-check`
 - Unified MCP registry name: none; this package installs skills and calls explicit platform services.
-- Current public capability version: `0.2.32`
+- Current public capability version: `0.2.33`
 
 ## Direct CLI
 
@@ -183,7 +183,7 @@ npx -y socialdatax-skills@latest sensitive-check text --text "<content>" --platf
 
 Most direct CLI commands print a JSON envelope with `platform`, `tool`, `arguments`, and `data`. `sensitive-check` prints `platform`, `tool`, and `data` only; it does not echo the original text in CLI output. `wechat decrypt-media` is a local save command: pass the `video.video_url` returned by WeChat detail and an `--output` file path. It saves the media locally, decrypts when needed, and does not require `SOCIALDATAX_API_KEY`. `xhs/douyin/kuaishou/weibo download-media` is also local: pass one media URL returned by detail and either `--output <file>` or `--output-dir <directory>`. It writes through a `.part` file, resumes partial downloads when the server supports range requests, skips an already existing output file, and infers common image/video/audio extensions in `--output-dir` mode.
 
-For transcript commands, the direct CLI tries to deliver the final result in one run: submit may wait up to 210 seconds, and if `data.is_terminal` is not `true`, the CLI automatically continues matching get-job requests for up to 1200 seconds by default, with each get-job request waiting up to 240 seconds. Use positive `--max-wait-seconds <seconds>` to tune that follow-up window. Do not submit a duplicate transcript job just to poll status.
+For transcript commands, the direct CLI tries to deliver the final result in one run: submit may wait up to 240 seconds, and if `data.is_terminal` is not `true`, the CLI automatically continues matching get-job requests for up to 1200 seconds by default, with each get-job request waiting up to 240 seconds. Use positive `--max-wait-seconds <seconds>` to tune that follow-up window. Do not submit a duplicate transcript job just to poll status.
 
 `bilibili download` calls SocialDataX once to fetch short-lived download links, then downloads video and audio tracks on the local machine and merges them with local `ffmpeg`. Set `SOCIALDATAX_API_KEY`, install `ffmpeg`, and pass either `--output <file>` or `--output-dir <directory>`. The download-links request consumes 10 credits; the local track download and merge do not consume additional SocialDataX credits. Use `--ffmpeg-path <path>` when `ffmpeg` is not on `PATH`, and `--keep-tracks` to retain the separate track files after merge.
 
@@ -369,7 +369,7 @@ Current XHS workflows include:
 - Fetch paginated replies under a first-level comment.
 - Read creator profile data from a profile link, short link, share text, or user ID.
 - Fetch paginated creator note lists from a user ID, profile link, short link, or share text for content style and account research.
-- Submit and check video note 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 210 秒，未完成时继续查询同一个 job_id 直到终态.
+- Submit and check video note 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 240 秒，未完成时继续查询同一个 job_id 直到终态.
 - Save returned `image_items[].image_url`, `image_items[].live_photo.video_url`, or `video.video_url` media links locally with `xhs download-media`.
 
 Current Kuaishou workflows include:
@@ -383,7 +383,7 @@ Current Kuaishou workflows include:
 - Continue Kuaishou list pagination only when `next_page_token` is non-empty; an empty string means there are no more results to request.
 - Read creator profile data from a non-empty user_id, profile link, short link, or share text. Live/fw-user profile shares are supported for profile data; successful results return a reusable non-empty user_id.
 - Fetch paginated creator work lists from a non-empty user_id, or from a profile link, short link, or share text that resolves directly to a non-empty user_id. For live/fw-user profile shares, call creator profile first and use the returned non-empty user_id.
-- Submit and check video work 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 210 秒，未完成时继续查询同一个 job_id 直到终态.
+- Submit and check video work 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 240 秒，未完成时继续查询同一个 job_id 直到终态.
 - Save returned `images[].url`, `video.play_url`, or `cover_image_url` media links locally with `kuaishou download-media`.
 
 Current Bilibili workflows include:
@@ -403,7 +403,7 @@ Current Douyin workflows include:
 - Read creator profile data from a profile link, short link, share text, or sec_user_id.
 - Fetch paginated creator work lists from a sec_user_id, profile link, short link, or share text.
 - Fetch paginated creator short-drama series lists from a sec_user_id, profile link, short link, or share text.
-- Submit and check video work 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 210 秒，未完成时继续查询同一个 job_id 直到终态.
+- Submit and check video work 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 240 秒，未完成时继续查询同一个 job_id 直到终态.
 - Save returned `images[].url`, `images[].live_photo.play_url`, `video.play_url`, `music.play_url`, or `cover_image_url` media links locally with `douyin download-media`.
 
 Current Weibo workflows include:
@@ -416,7 +416,7 @@ Current Weibo workflows include:
 - Continue Weibo list pagination only when `next_page_token` is non-empty; an empty string means there are no more results to request.
 - Read creator profile data from a profile link, short link, share text, or user_id.
 - Fetch paginated creator post lists from a user_id, profile link, short link, or share text.
-- Submit and check Weibo video 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 210 秒，未完成时继续查询同一个 job_id 直到终态.
+- Submit and check Weibo video 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 240 秒，未完成时继续查询同一个 job_id 直到终态.
 - Save returned `image_urls[]` or `video.video_url` media links locally with `weibo download-media`.
 
 Current WeChat / 微信 workflows include:
@@ -431,7 +431,7 @@ Current WeChat / 微信 workflows include:
 - Continue WeChat Channels list pagination only when `next_page_token` is non-empty; an empty string means there are no more results to request.
 - Read creator profile data from a `v2_...@finder` user_id.
 - Fetch paginated creator video lists from a `v2_...@finder` user_id or a video link/share text.
-- Submit and check WeChat Channels / 视频号 video 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 210 秒，未完成时继续查询同一个 job_id 直到终态.
+- Submit and check WeChat Channels / 视频号 video 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 240 秒，未完成时继续查询同一个 job_id 直到终态.
 
 Current Sensitive Words Check workflows include:
 
@@ -455,9 +455,9 @@ Current Sensitive Words Check workflows include:
 | `xhs_get_user_info_by_profile_url` | Resolve a profile link, short link, or share text into creator profile data. |
 | `xhs_get_user_posted_notes_by_user_id` | Fetch a paginated list of notes published by a creator when the caller already has a user ID. |
 | `xhs_get_user_posted_notes_by_profile_url` | Fetch a paginated list of notes published by a creator from a profile link, short link, or share text. |
-| `xhs_submit_video_speech_text_by_note_url` | Submit an XHS video note speech-to-text transcript job from a note link, short link, or share text; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
-| `xhs_submit_video_speech_text_by_note_id` | Submit an XHS video note speech-to-text transcript job when the caller already has a note ID; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
-| `xhs_get_video_speech_text_job` | Check an XHS speech-to-text transcript job by job_id without creating a new task; optional wait_seconds 0-240 can long-poll the same job in one request. Continue querying the same job_id until is_terminal is true. Returns transcript plus content context, not summary. |
+| `xhs_submit_video_speech_text_by_note_url` | Submit an XHS video note speech-to-text transcript job from a note link, short link, or share text; submit waits up to 240 seconds. If unfinished, continue checking the same job_id until is_terminal is true. |
+| `xhs_submit_video_speech_text_by_note_id` | Submit an XHS video note speech-to-text transcript job when the caller already has a note ID; submit waits up to 240 seconds. If unfinished, continue checking the same job_id until is_terminal is true. |
+| `xhs_get_video_speech_text_job` | Check an XHS speech-to-text transcript job by job_id without creating a new task. Each call waits up to 240 seconds for the same job. If unfinished, continue querying the same job_id until is_terminal is true. Returns transcript plus content context, not summary. |
 
 ## Douyin Tools
 
@@ -476,9 +476,9 @@ Current Sensitive Words Check workflows include:
 | `douyin_get_user_posted_videos_by_profile_url` | Fetch a paginated list of works published by a creator from a profile link, short link, or share text. |
 | `douyin_get_user_series_by_sec_user_id` | Fetch a paginated list of short-drama series by a creator when the caller already has a sec_user_id. |
 | `douyin_get_user_series_by_profile_url` | Fetch a paginated list of short-drama series by a creator from a profile link, short link, or share text. |
-| `douyin_submit_video_speech_text_by_video_url` | Submit a Douyin video speech-to-text transcript job from a content page link, short link, or share text; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
-| `douyin_submit_video_speech_text_by_aweme_id` | Submit a Douyin video speech-to-text transcript job when the caller already has an aweme_id; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
-| `douyin_get_video_speech_text_job` | Check a Douyin speech-to-text transcript job by job_id without creating a new task; optional wait_seconds 0-240 can long-poll the same job in one request. Continue querying the same job_id until is_terminal is true. Returns transcript plus content context, not summary. |
+| `douyin_submit_video_speech_text_by_video_url` | Submit a Douyin video speech-to-text transcript job from a content page link, short link, or share text; submit waits up to 240 seconds. If unfinished, continue checking the same job_id until is_terminal is true. |
+| `douyin_submit_video_speech_text_by_aweme_id` | Submit a Douyin video speech-to-text transcript job when the caller already has an aweme_id; submit waits up to 240 seconds. If unfinished, continue checking the same job_id until is_terminal is true. |
+| `douyin_get_video_speech_text_job` | Check a Douyin speech-to-text transcript job by job_id without creating a new task. Each call waits up to 240 seconds for the same job. If unfinished, continue querying the same job_id until is_terminal is true. Returns transcript plus content context, not summary. |
 
 ## Kuaishou Tools
 
@@ -496,9 +496,9 @@ Current Sensitive Words Check workflows include:
 | `kuaishou_get_user_info_by_profile_url` | Resolve a Kuaishou profile link, including live/fw-user profile shares, short link, or share text into creator profile data; successful results return a reusable non-empty user_id. |
 | `kuaishou_get_user_posted_videos_by_user_id` | Fetch a paginated list of works published by a creator when the caller already has a non-empty user_id. |
 | `kuaishou_get_user_posted_videos_by_profile_url` | Fetch a paginated list of works published by a creator from a profile link, short link, or share text that resolves directly to a non-empty user_id; for live/fw-user profile shares, call creator profile first and use the returned non-empty user_id. |
-| `kuaishou_submit_video_speech_text_by_video_url` | Submit a Kuaishou video speech-to-text transcript job from a work page link, short link, or share text; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
-| `kuaishou_submit_video_speech_text_by_photo_id` | Submit a Kuaishou video speech-to-text transcript job when the caller already has a photo_id; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
-| `kuaishou_get_video_speech_text_job` | Check a Kuaishou speech-to-text transcript job by job_id without creating a new task; optional wait_seconds 0-240 can long-poll the same job in one request. Continue querying the same job_id until is_terminal is true. Returns transcript plus content context, not summary. |
+| `kuaishou_submit_video_speech_text_by_video_url` | Submit a Kuaishou video speech-to-text transcript job from a work page link, short link, or share text; submit waits up to 240 seconds. If unfinished, continue checking the same job_id until is_terminal is true. |
+| `kuaishou_submit_video_speech_text_by_photo_id` | Submit a Kuaishou video speech-to-text transcript job when the caller already has a photo_id; submit waits up to 240 seconds. If unfinished, continue checking the same job_id until is_terminal is true. |
+| `kuaishou_get_video_speech_text_job` | Check a Kuaishou speech-to-text transcript job by job_id without creating a new task. Each call waits up to 240 seconds for the same job. If unfinished, continue querying the same job_id until is_terminal is true. Returns transcript plus content context, not summary. |
 
 ## Bilibili Tools
 
@@ -521,9 +521,9 @@ Current Sensitive Words Check workflows include:
 | `weibo_get_user_info_by_profile_url` | Resolve a Weibo profile link, short link, or share text into creator profile data. |
 | `weibo_get_user_posts_by_user_id` | Fetch a paginated list of posts published by a creator when the caller already has a user_id. |
 | `weibo_get_user_posts_by_profile_url` | Fetch a paginated list of posts published by a creator from a profile link, short link, or share text. |
-| `weibo_submit_video_speech_text_by_post_url` | Submit a Weibo video speech-to-text transcript job from a post URL, short link, or share text; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
-| `weibo_submit_video_speech_text_by_post_id` | Submit a Weibo video speech-to-text transcript job when the caller already has a post_id; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
-| `weibo_get_video_speech_text_job` | Check a Weibo speech-to-text transcript job by job_id without creating a new task; optional wait_seconds 0-240 can long-poll the same job in one request. Continue querying the same job_id until is_terminal is true. Returns transcript plus content context, not summary. |
+| `weibo_submit_video_speech_text_by_post_url` | Submit a Weibo video speech-to-text transcript job from a post URL, short link, or share text; submit waits up to 240 seconds. If unfinished, continue checking the same job_id until is_terminal is true. |
+| `weibo_submit_video_speech_text_by_post_id` | Submit a Weibo video speech-to-text transcript job when the caller already has a post_id; submit waits up to 240 seconds. If unfinished, continue checking the same job_id until is_terminal is true. |
+| `weibo_get_video_speech_text_job` | Check a Weibo speech-to-text transcript job by job_id without creating a new task. Each call waits up to 240 seconds for the same job. If unfinished, continue querying the same job_id until is_terminal is true. Returns transcript plus content context, not summary. |
 
 ## WeChat Tools
 
@@ -540,9 +540,9 @@ Current Sensitive Words Check workflows include:
 | `wechat_get_user_info_by_user_id` | Fetch creator profile data when the `v2_...@finder` user_id is already known. |
 | `wechat_get_user_posted_videos_by_user_id` | Fetch a paginated list of videos published by a creator when the `v2_...@finder` user_id is already known. |
 | `wechat_get_user_posted_videos_by_url` | Fetch a paginated list of videos published by a creator from a video link or share text. |
-| `wechat_submit_video_speech_text_by_video_url` | Submit a WeChat Channels / 视频号 video speech-to-text transcript job from a video link or share text; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
-| `wechat_submit_video_speech_text_by_encrypted_object_id` | Submit a WeChat Channels / 视频号 video speech-to-text transcript job when encrypted_object_id is already known; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
-| `wechat_get_video_speech_text_job` | Check a WeChat Channels / 视频号 speech-to-text transcript job by job_id without creating a new task; optional wait_seconds 0-240 can long-poll the same job in one request. Continue querying the same job_id until is_terminal is true. Returns transcript plus content context, not summary. |
+| `wechat_submit_video_speech_text_by_video_url` | Submit a WeChat Channels / 视频号 video speech-to-text transcript job from a video link or share text; submit waits up to 240 seconds. If unfinished, continue checking the same job_id until is_terminal is true. |
+| `wechat_submit_video_speech_text_by_encrypted_object_id` | Submit a WeChat Channels / 视频号 video speech-to-text transcript job when encrypted_object_id is already known; submit waits up to 240 seconds. If unfinished, continue checking the same job_id until is_terminal is true. |
+| `wechat_get_video_speech_text_job` | Check a WeChat Channels / 视频号 speech-to-text transcript job by job_id without creating a new task. Each call waits up to 240 seconds for the same job. If unfinished, continue querying the same job_id until is_terminal is true. Returns transcript plus content context, not summary. |
 
 ## Sensitive Words Check Tools
 

package/cli.mjs

@@ -22,7 +22,7 @@ import { decryptWechatMediaCommand } from "./lib/media/wechat-decrypt.mjs";
 export { decryptWechatMediaCommand };
 
 const PACKAGE_NAME = "socialdatax-skills";
-const PACKAGE_VERSION = "0.2.32";
+const PACKAGE_VERSION = "0.2.33";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
 const LOG_PREFIX = `[${PACKAGE_NAME}]`;
 const MIN_NODE_VERSION = "20.18.1";
@@ -43,15 +43,16 @@ const SOURCE_ATTRIBUTION_PATTERN = /^[a-z0-9][a-z0-9-]{0,99}$/;
 export const TRANSCRIPT_JOB_DESCRIPTION_SUFFIX =
   "Returns transcript plus content context, not summary.";
 const TRANSCRIPT_SUBMIT_WAIT_DESCRIPTION =
-  "提交后最多等待 210 秒；未完成时继续用对应 get-job 查询同一个 job_id 直到终态，不要重复提交.";
+  "提交后最多等待 240 秒；未完成时继续用对应 get-job 查询同一个 job_id 直到终态，不要重复提交.";
 const TRANSCRIPT_GET_JOB_WAIT_DESCRIPTION =
-  "Optional wait_seconds 0-240 can long-poll the same job in one request.";
+  "Each call waits up to 240 seconds for the same job. If unfinished, continue querying the same job_id until is_terminal is true.";
 const TRANSCRIPT_DEFAULT_MAX_WAIT_SECONDS = 1200;
-const TRANSCRIPT_GET_JOB_WAIT_SECONDS = 240;
 const TRANSCRIPT_FALLBACK_POLL_SECONDS = 2;
+const TRANSCRIPT_MCP_CALL_TIMEOUT_MS = 330_000;
+const MCP_REQUEST_TIMEOUT_ERROR_CODE = -32001;
 
 export function buildTranscriptJobDescription(subject) {
-  return `Check ${subject} by job_id without starting a new task. ${TRANSCRIPT_GET_JOB_WAIT_DESCRIPTION} Continue querying the same job_id until is_terminal is true. ${TRANSCRIPT_JOB_DESCRIPTION_SUFFIX}`;
+  return `Check ${subject} by job_id without starting a new task. ${TRANSCRIPT_GET_JOB_WAIT_DESCRIPTION} ${TRANSCRIPT_JOB_DESCRIPTION_SUFFIX}`;
 }
 
 const AVAILABLE_SKILLS = [
@@ -3764,10 +3765,10 @@ function buildXhsSubCommentsCall(options) {
   };
 }
 
-async function callDirectOperation(operation) {
+async function callDirectOperation(operation, requestOptions) {
   switch (operation.backend) {
     case "mcp":
-      return callMcpBackend(operation);
+      return callMcpBackend(operation, requestOptions);
     default:
       throw new Error(`Unsupported direct CLI backend: ${operation.backend}.`);
   }
@@ -3785,7 +3786,7 @@ async function callDirectOperationWithOptions(operation, options) {
 
 async function callTranscriptDirectOperation(operation, options) {
   const maxWaitSeconds = parseTranscriptMaxWaitSeconds(options);
-  let currentOperation = transcriptInitialOperation(operation, maxWaitSeconds);
+  let currentOperation = transcriptInitialOperation(operation);
   let data = await callDirectOperation(currentOperation);
   if (maxWaitSeconds <= 0 || isTerminalTranscriptData(data)) {
     return data;
@@ -3822,12 +3823,18 @@ async function callTranscriptDirectOperation(operation, options) {
       break;
     }
 
-    currentOperation = transcriptGetJobOperation(
-      operation,
-      jobId,
-      transcriptWaitSecondsForCall(remainingSeconds)
-    );
-    data = await callDirectOperation(currentOperation);
+    currentOperation = transcriptGetJobOperation(operation, jobId);
+    try {
+      data = await callDirectOperation(currentOperation, {
+        requestDeadlineMs: Date.now() + remainingSeconds * 1000,
+        preserveRequestTimeout: true,
+      });
+    } catch (error) {
+      if (isMcpRequestTimeoutError(error)) {
+        break;
+      }
+      throw error;
+    }
     jobId = readTranscriptJobId(data, operation) || jobId;
   }
 
@@ -3844,38 +3851,21 @@ function parseTranscriptMaxWaitSeconds(options) {
   return TRANSCRIPT_DEFAULT_MAX_WAIT_SECONDS;
 }
 
-function transcriptInitialOperation(operation, maxWaitSeconds) {
-  const initialOperation = cloneDirectOperation(operation);
-  const isJobLookup =
-    operation.transcriptIsJobLookup ||
-    operation.tool === operation.transcriptJobTool ||
-    Object.hasOwn(operation.arguments, "job_id");
-  if (isJobLookup && maxWaitSeconds > 0) {
-    initialOperation.arguments.wait_seconds =
-      transcriptWaitSecondsForCall(maxWaitSeconds);
-  }
-  return initialOperation;
+function transcriptInitialOperation(operation) {
+  return cloneDirectOperation(operation);
 }
 
-function transcriptGetJobOperation(operation, jobId, waitSeconds) {
+function transcriptGetJobOperation(operation, jobId) {
   const jobArgument = operation.transcriptJobArgument || "job_id";
   return {
     ...operation,
     tool: operation.transcriptJobTool,
     arguments: {
       [jobArgument]: jobId,
-      wait_seconds: waitSeconds,
     },
   };
 }
 
-function transcriptWaitSecondsForCall(remainingSeconds) {
-  return Math.min(
-    TRANSCRIPT_GET_JOB_WAIT_SECONDS,
-    Math.max(1, Math.ceil(remainingSeconds))
-  );
-}
-
 function transcriptRemainingWaitSeconds(startedAtMs, maxWaitSeconds) {
   return maxWaitSeconds - (Date.now() - startedAtMs) / 1000;
 }
@@ -4490,7 +4480,10 @@ function buildRepliesOperationForComment(platform, comment, parentArguments, par
   }
 }
 
-async function callMcpBackend(operation) {
+async function callMcpBackend(
+  operation,
+  { requestDeadlineMs, requestTimeoutMs, preserveRequestTimeout = false } = {}
+) {
   ensureSupportedNodeVersion();
   const { platform, tool } = operation;
   const apiKey = readDirectApiKey(platform);
@@ -4520,11 +4513,22 @@ async function callMcpBackend(operation) {
   });
 
   try {
-    await client.connect(transport);
-    const result = await client.callTool({
-      name: tool,
-      arguments: operation.arguments,
+    const transcriptConnectOptions = transcriptMcpRequestOptions(operation, {
+      requestDeadlineMs,
+      requestTimeoutMs,
     });
+    await connectMcpClient(client, transport, transcriptConnectOptions);
+    const result = await client.callTool(
+      {
+        name: tool,
+        arguments: operation.arguments,
+      },
+      undefined,
+      transcriptMcpRequestOptions(operation, {
+        requestDeadlineMs,
+        requestTimeoutMs,
+      })
+    );
     if (result.isError) {
       const errorMessage =
         result.structuredContent?.message ||
@@ -4536,12 +4540,70 @@ async function callMcpBackend(operation) {
     }
     return result.structuredContent ?? result;
   } catch (error) {
+    if (preserveRequestTimeout && isMcpRequestTimeoutError(error)) {
+      throw error;
+    }
     throw formatDirectCallError({ error, operation, upstreamUrl });
   } finally {
     await client.close().catch(() => {});
   }
 }
 
+function isMcpRequestTimeoutError(error) {
+  return error?.code === MCP_REQUEST_TIMEOUT_ERROR_CODE;
+}
+
+async function connectMcpClient(client, transport, requestOptions) {
+  if (requestOptions?.timeout === undefined) {
+    await client.connect(transport, requestOptions);
+    return;
+  }
+  await withMcpRequestTimeout(
+    client.connect(transport, requestOptions),
+    requestOptions.timeout,
+    () => client.close().catch(() => {})
+  );
+}
+
+function transcriptMcpRequestOptions(
+  operation,
+  { requestDeadlineMs, requestTimeoutMs }
+) {
+  if (operation.operation !== "transcript") {
+    return undefined;
+  }
+  if (requestDeadlineMs !== undefined) {
+    return {
+      timeout: Math.max(Math.ceil(requestDeadlineMs - Date.now()), 1),
+    };
+  }
+  return {
+    timeout: requestTimeoutMs ?? TRANSCRIPT_MCP_CALL_TIMEOUT_MS,
+  };
+}
+
+async function withMcpRequestTimeout(promise, timeoutMs, onTimeout) {
+  let timeoutId;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(mcpRequestTimeoutError(timeoutMs));
+      Promise.resolve(onTimeout?.()).catch(() => {});
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+function mcpRequestTimeoutError(timeoutMs) {
+  const error = new Error("Request timed out");
+  error.code = MCP_REQUEST_TIMEOUT_ERROR_CODE;
+  error.data = { timeout: timeoutMs };
+  return error;
+}
+
 function readDirectApiKey(platform) {
   const apiKey = readFirstEnv(platform.apiKeyEnv);
   if (!apiKey) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "socialdatax-skills",
-  "version": "0.2.32",
+  "version": "0.2.33",
   "description": "SocialDataX / 社媒数据助手 skill installer and direct CLI helper for hosted platform social media MCP services.",
   "license": "MIT",
   "type": "module",

package/skills/media-search/SKILL.md

@@ -235,8 +235,6 @@ Do not pass `page` to `wechat_search_videos`; omit `page_token` on the first req
 Continue WeChat Channels pagination only when `next_page_token` is not empty. Pass the complete returned `next_page_token` back unchanged as `page_token` for the same keyword and filter chain.
 `--since-days` uses CLI-side filtering only and is not an MCP tool argument; for MCP-only calls, request newest-first/native publish-time filters where available and filter returned `publish_time` values in your analysis.
 
-XHS search parameter naming reminder: direct CLI uses `--sort-type`, `--publish-time-range`, and `--note-type`; the `xhs_search_notes` MCP tool uses `sort_type`, `publish_time_range`, and `note_type`. Do not pass `sortType`, `publishTimeRange`, or `noteType`.
-
 ## Output Guidance
 
 Summarize visible evidence separately from interpretation. Include useful content IDs, URLs, titles or descriptions, authors, counts, and publish time when the user needs traceability.

package/skills/media-transcript/SKILL.md

@@ -122,7 +122,7 @@ Optional arguments:
 - `--source-client socialdatax-skills --source-platform npm --source-skill media-transcript`: usage attribution for this Agent Skill; keep these values unchanged when running examples from this Skill.
 
 Use the direct CLI first when the agent can run shell commands. These video speech-to-text transcript / 口播转文字 workflows submit a bounded analysis job or check an existing job.
-Direct CLI transcript commands try to deliver the final result in one run: submit waits server-side up to 210 seconds, then the CLI keeps querying the same `job_id` with get-job long polling of up to 240 seconds per request for a bounded follow-up window. Do not start a second submit job just to poll status.
+Direct CLI transcript commands try to deliver the final result in one run: submit waits server-side up to 240 seconds, then the CLI keeps querying the same `job_id`; each get-job call also waits up to 240 seconds for that job. Do not start a second submit job just to poll status.
 If the direct CLI returns a non-terminal job because the command was interrupted or reached `--max-wait-seconds`, keep the returned `job_id` and continue with the matching `transcript --job-id <job_id>` command.
 
 ## Safety Boundary
@@ -155,7 +155,7 @@ If MCP tools are already available in the current agent, choose the platform-spe
 - Kuaishou: `kuaishou_submit_video_speech_text_by_video_url`, `kuaishou_submit_video_speech_text_by_photo_id`, `kuaishou_get_video_speech_text_job`.
 - Weibo: `weibo_submit_video_speech_text_by_post_url`, `weibo_submit_video_speech_text_by_post_id`, `weibo_get_video_speech_text_job`.
 - WeChat Channels / 视频号: `wechat_submit_video_speech_text_by_video_url`, `wechat_submit_video_speech_text_by_encrypted_object_id`, `wechat_get_video_speech_text_job`.
-Do not start a duplicate transcript job only to poll status. If an MCP response is non-terminal, call `data.next_action.tool_name` with `data.next_action.arguments` exactly as returned; those arguments include the same `job_id` and a bounded `wait_seconds` value. Continue until `is_terminal` is `true`.
+Do not start a duplicate transcript job only to poll status. If an MCP response is non-terminal, you must call `data.next_action.tool_name` with `data.next_action.arguments` exactly as returned; those arguments include the same `job_id`. The next response may still be non-terminal. Continue until `is_terminal` is `true`.
 
 ## Output Guidance
 

package/skills/socialdatax-content-research-assistant/SKILL.md

@@ -473,8 +473,6 @@ MCP tools matching the direct CLI commands above:
 Use the automatically listed MCP tools above as the source of truth for tool names. Pick the narrowest tool for the user's platform and task.
 For search pagination, omit `page_token` on the first request and pass only the complete returned `next_page_token` when continuing the same chain. Use `page_token` for all new search continuation calls.
 
-XHS search parameter naming reminder: direct CLI uses `--sort-type`, `--publish-time-range`, and `--note-type`; the `xhs_search_notes` MCP tool uses `sort_type`, `publish_time_range`, and `note_type`. Do not pass `sortType`, `publishTimeRange`, or `noteType`.
-
 ## Output Guidance
 
 For broad research, summarize visible evidence separately from interpretation and organize findings by platform, content angles, audience needs, trend signals, comment themes, creator positioning, and practical next steps.
@@ -486,7 +484,6 @@ For hot-search, report ranking signals separately from keyword search results.
 
 ## Troubleshooting
 
-- For non-balance, non-rate-limit network or API errors, preserve the error message, check `SOCIALDATAX_API_KEY`, parameters, and link or ID format, then retry once when appropriate.
+- For non-balance network or API errors, preserve the error message, check `SOCIALDATAX_API_KEY`, parameters, and link or ID format, then retry once when appropriate.
 - If the response returns `insufficient_balance` or says the balance/credits are insufficient, do not retry repeatedly. Show the recharge URL from the error exactly as returned, then continue the same command after the user recharges.
 - If the user has recharged but still sees insufficient balance, confirm `SOCIALDATAX_API_KEY` belongs to the same account that was recharged; if needed, copy a fresh API Key from the official dashboard.
-- Batch processing: process items one by one as a queue by default; when the user explicitly needs batch efficiency, use at most 3 concurrent requests. As each item finishes, continue with the next one. Do not launch a large burst of requests. If `rate_limited` or a too-frequent-request error appears, do not abandon the task; stop starting new requests, wait for the returned wait time, or wait 2 seconds if none is provided, then continue the same queue from the unfinished position. Preserve completed results. If `insufficient_balance` or insufficient credits appears, stop remaining requests immediately, output the results already obtained, and ask the user to recharge or switch to an API Key with balance before continuing.