socialdatax-skills 0.2.28 → 0.2.29

package/README.md

@@ -82,7 +82,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.28`
+- Current public capability version: `0.2.29`
 
 ## Direct CLI
 
@@ -176,6 +176,8 @@ 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 download-media` is also local: pass one image or video media URL returned by XHS 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 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.
+
 `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.
 
 For XHS outputs with a returned `note_url` field, when `note_url` is non-null, preserve it exactly as the full URL, including `xsec_token` query parameters, such as in final answers or display. Do not modify, truncate, redact, normalize, rebuild, or replace it with a link assembled from `note_id`. If `note_url` is null, do not synthesize a public link from `note_id`.
@@ -192,7 +194,7 @@ For commands that accept `--page-token`, continue only with the complete returne
 
 Search pagination uses `--page-token` when continuing with a returned `next_page_token`. Omit `--page-token` on the first search request and pass the complete returned `next_page_token` only when continuing the same search chain.
 
-Transcript commands submit a bounded video speech-to-text job or check an existing job. Pass exactly one entrypoint for each call: URL/share text, platform content ID, or `--job-id`. Completed get-job responses return transcript plus content context, not summary.
+Transcript commands submit a bounded video speech-to-text job or check an existing job. Pass exactly one entrypoint for each call: URL/share text, platform content ID, or `--job-id`. Direct CLI transcript commands wait and poll the same job by default; completed get-job responses return transcript plus content context, not summary.
 
 Generated Agent Skill examples include `--source-client socialdatax-skills --source-platform <marketplace> --source-skill <skill-slug>` so SocialDataX can attribute authenticated direct data CLI usage to the current marketplace Skill. Keep those values unchanged when running commands from a Skill; omit them for ad hoc CLI use. Authenticated direct data CLI commands also accept `SOCIALDATAX_SOURCE_CLIENT`, `SOCIALDATAX_SOURCE_PLATFORM`, and `SOCIALDATAX_SOURCE_SKILL` as environment-variable fallbacks.
 
@@ -357,7 +359,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 提交后最多等待 15 秒.
+- Submit and check video note 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 210 秒，未完成时继续查询同一个 job_id 直到终态.
 
 Current Kuaishou workflows include:
 
@@ -370,7 +372,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 提交后最多等待 15 秒.
+- Submit and check video work 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 210 秒，未完成时继续查询同一个 job_id 直到终态.
 
 Current Bilibili workflows include:
 
@@ -389,7 +391,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 提交后最多等待 15 秒.
+- Submit and check video work 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 210 秒，未完成时继续查询同一个 job_id 直到终态.
 
 Current Weibo workflows include:
 
@@ -401,7 +403,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 提交后最多等待 15 秒.
+- Submit and check Weibo video 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 210 秒，未完成时继续查询同一个 job_id 直到终态.
 
 Current WeChat / 微信 workflows include:
 
@@ -415,7 +417,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 finder user_id.
 - Fetch paginated creator video lists from a finder user_id or a video link/share text.
-- Submit and check WeChat Channels / 视频号 video 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 15 秒.
+- Submit and check WeChat Channels / 视频号 video 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 210 秒，未完成时继续查询同一个 job_id 直到终态.
 
 Current Sensitive Words Check workflows include:
 
@@ -439,9 +441,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 15 seconds. |
-| `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 15 seconds. |
-| `xhs_get_video_speech_text_job` | Check an XHS speech-to-text transcript job by job_id without creating a new task. 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 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. |
 
 ## Douyin Tools
 
@@ -460,9 +462,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 15 seconds. |
-| `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 15 seconds. |
-| `douyin_get_video_speech_text_job` | Check a Douyin speech-to-text transcript job by job_id without creating a new task. 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 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. |
 
 ## Kuaishou Tools
 
@@ -480,9 +482,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 15 seconds. |
-| `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 15 seconds. |
-| `kuaishou_get_video_speech_text_job` | Check a Kuaishou speech-to-text transcript job by job_id without creating a new task. 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 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. |
 
 ## Bilibili Tools
 
@@ -505,9 +507,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 15 seconds. |
-| `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 15 seconds. |
-| `weibo_get_video_speech_text_job` | Check a Weibo speech-to-text transcript job by job_id without creating a new task. 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 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. |
 
 ## WeChat Tools
 
@@ -524,9 +526,9 @@ Current Sensitive Words Check workflows include:
 | `wechat_get_user_info_by_user_id` | Fetch creator profile data when the 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 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 15 seconds. |
-| `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 15 seconds. |
-| `wechat_get_video_speech_text_job` | Check a WeChat Channels / 视频号 speech-to-text transcript job by job_id without creating a new task. 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 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. |
 
 ## Sensitive Words Check Tools
 

package/cli.mjs

@@ -22,7 +22,7 @@ import { downloadXhsMediaFromUrl } from "./lib/media/xhs-download.mjs";
 export { decryptWechatMediaCommand };
 
 const PACKAGE_NAME = "socialdatax-skills";
-const PACKAGE_VERSION = "0.2.28";
+const PACKAGE_VERSION = "0.2.29";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
 const LOG_PREFIX = `[${PACKAGE_NAME}]`;
 const MIN_NODE_VERSION = "20.18.1";
@@ -42,9 +42,16 @@ const SOURCE_SKILL_HEADER = "X-SocialDataX-Source-Skill";
 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 直到终态，不要重复提交.";
+const TRANSCRIPT_GET_JOB_WAIT_DESCRIPTION =
+  "Optional wait_seconds 0-240 can long-poll the same job in one request.";
+const TRANSCRIPT_DEFAULT_MAX_WAIT_SECONDS = 1200;
+const TRANSCRIPT_GET_JOB_WAIT_SECONDS = 240;
+const TRANSCRIPT_FALLBACK_POLL_SECONDS = 2;
 
 export function buildTranscriptJobDescription(subject) {
-  return `Check ${subject} by job_id without starting a new task. ${TRANSCRIPT_JOB_DESCRIPTION_SUFFIX}`;
+  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}`;
 }
 
 const AVAILABLE_SKILLS = [
@@ -163,7 +170,7 @@ const XHS_DIRECT_ACTION_OPTIONS = {
     "sinceDays",
     "pretty",
   ],
-  transcript: ["url", "noteId", "jobId", "pretty"],
+  transcript: ["url", "noteId", "jobId", "maxWaitSeconds", "pretty"],
   "download-media": ["url", "output", "outputDir", "pretty"],
 };
 const XHS_DIRECT_ACTION_NAMES = Object.keys(XHS_DIRECT_ACTION_OPTIONS).join(", ");
@@ -184,6 +191,7 @@ const XHS_OPTION_DISPLAY_NAMES = {
   profileUrl: "--profile-url",
   userId: "--user-id",
   jobId: "--job-id",
+  maxWaitSeconds: "--max-wait-seconds",
   output: "--output",
   outputDir: "--output-dir",
 };
@@ -252,7 +260,7 @@ const DOUYIN_DIRECT_ACTION_OPTIONS = {
     "pretty",
   ],
   "user-series": ["secUserId", "profileUrl", "pageToken", "pages", "all", "maxItems", "pretty"],
-  transcript: ["url", "awemeId", "jobId", "pretty"],
+  transcript: ["url", "awemeId", "jobId", "maxWaitSeconds", "pretty"],
 };
 const DOUYIN_DIRECT_ACTION_NAMES = Object.keys(DOUYIN_DIRECT_ACTION_OPTIONS).join(", ");
 const DOUYIN_SEARCH_SORT_TYPES = ["general", "time_descending", "like_count_descending"];
@@ -282,6 +290,7 @@ const DOUYIN_OPTION_DISPLAY_NAMES = {
   commentId: "--comment-id",
   secUserId: "--sec-user-id",
   jobId: "--job-id",
+  maxWaitSeconds: "--max-wait-seconds",
 };
 const KUAISHOU_DIRECT_ACTION_OPTIONS = {
   "hot-search": ["pretty"],
@@ -319,7 +328,7 @@ const KUAISHOU_DIRECT_ACTION_OPTIONS = {
     "sinceDays",
     "pretty",
   ],
-  transcript: ["url", "photoId", "jobId", "pretty"],
+  transcript: ["url", "photoId", "jobId", "maxWaitSeconds", "pretty"],
 };
 const KUAISHOU_DIRECT_ACTION_NAMES = Object.keys(KUAISHOU_DIRECT_ACTION_OPTIONS).join(", ");
 const KUAISHOU_OPTION_DISPLAY_NAMES = {
@@ -336,6 +345,7 @@ const KUAISHOU_OPTION_DISPLAY_NAMES = {
   commentId: "--comment-id",
   userId: "--user-id",
   jobId: "--job-id",
+  maxWaitSeconds: "--max-wait-seconds",
 };
 const BILIBILI_DIRECT_ACTION_OPTIONS = {
   download: ["url", "output", "outputDir", "ffmpegPath", "keepTracks", "pretty"],
@@ -384,7 +394,7 @@ const WEIBO_DIRECT_ACTION_OPTIONS = {
     "sinceDays",
     "pretty",
   ],
-  transcript: ["postUrl", "postId", "jobId", "pretty"],
+  transcript: ["postUrl", "postId", "jobId", "maxWaitSeconds", "pretty"],
 };
 const WEIBO_DIRECT_ACTION_NAMES = Object.keys(WEIBO_DIRECT_ACTION_OPTIONS).join(", ");
 const WEIBO_OPTION_DISPLAY_NAMES = {
@@ -401,6 +411,7 @@ const WEIBO_OPTION_DISPLAY_NAMES = {
   profileUrl: "--profile-url",
   userId: "--user-id",
   jobId: "--job-id",
+  maxWaitSeconds: "--max-wait-seconds",
 };
 const WECHAT_DIRECT_ACTION_OPTIONS = {
   "hot-search": ["pretty"],
@@ -450,7 +461,7 @@ const WECHAT_DIRECT_ACTION_OPTIONS = {
     "sinceDays",
     "pretty",
   ],
-  transcript: ["url", "encryptedObjectId", "jobId", "pretty"],
+  transcript: ["url", "encryptedObjectId", "jobId", "maxWaitSeconds", "pretty"],
   "decrypt-media": ["mediaUrl", "output", "pretty"],
 };
 const WECHAT_LOCAL_DIRECT_ACTIONS = new Set(["decrypt-media"]);
@@ -485,6 +496,7 @@ const WECHAT_OPTION_DISPLAY_NAMES = {
   jobId: "--job-id",
   mediaUrl: "--media-url",
   output: "--output",
+  maxWaitSeconds: "--max-wait-seconds",
 };
 const SENSITIVE_CHECK_DIRECT_ACTION_OPTIONS = {
   text: ["text", "platform", "pretty"],
@@ -567,12 +579,12 @@ const PLATFORMS = {
       {
         name: "xhs_submit_video_speech_text_by_note_url",
         description:
-          "Submit a video note speech-to-text transcript task from a note link, short link, or share text; 提交后最多等待 15 秒.",
+          `Submit a video note speech-to-text transcript task from a note link, short link, or share text; ${TRANSCRIPT_SUBMIT_WAIT_DESCRIPTION}`,
       },
       {
         name: "xhs_submit_video_speech_text_by_note_id",
         description:
-          "Submit a video note speech-to-text transcript task from a note_id; 提交后最多等待 15 秒.",
+          `Submit a video note speech-to-text transcript task from a note_id; ${TRANSCRIPT_SUBMIT_WAIT_DESCRIPTION}`,
       },
       {
         name: "xhs_get_video_speech_text_job",
@@ -651,12 +663,12 @@ const PLATFORMS = {
       {
         name: "douyin_submit_video_speech_text_by_video_url",
         description:
-          "Submit a Douyin work video speech-to-text transcript task from a work page link, short link, or share text; 提交后最多等待 15 秒.",
+          `Submit a Douyin work video speech-to-text transcript task from a work page link, short link, or share text; ${TRANSCRIPT_SUBMIT_WAIT_DESCRIPTION}`,
       },
       {
         name: "douyin_submit_video_speech_text_by_aweme_id",
         description:
-          "Submit a Douyin work video speech-to-text transcript task from an aweme_id; 提交后最多等待 15 秒.",
+          `Submit a Douyin work video speech-to-text transcript task from an aweme_id; ${TRANSCRIPT_SUBMIT_WAIT_DESCRIPTION}`,
       },
       {
         name: "douyin_get_video_speech_text_job",
@@ -735,12 +747,12 @@ const PLATFORMS = {
       {
         name: "kuaishou_submit_video_speech_text_by_video_url",
         description:
-          "Submit a Kuaishou work video speech-to-text transcript task from a work page link, short link, or share text; 提交后最多等待 15 秒.",
+          `Submit a Kuaishou work video speech-to-text transcript task from a work page link, short link, or share text; ${TRANSCRIPT_SUBMIT_WAIT_DESCRIPTION}`,
       },
       {
         name: "kuaishou_submit_video_speech_text_by_photo_id",
         description:
-          "Submit a Kuaishou work video speech-to-text transcript task from a photo_id; 提交后最多等待 15 秒.",
+          `Submit a Kuaishou work video speech-to-text transcript task from a photo_id; ${TRANSCRIPT_SUBMIT_WAIT_DESCRIPTION}`,
       },
       {
         name: "kuaishou_get_video_speech_text_job",
@@ -840,12 +852,12 @@ const PLATFORMS = {
       {
         name: "weibo_submit_video_speech_text_by_post_url",
         description:
-          "Submit a Weibo video speech-to-text transcript task from a post URL, short link, or share text; 提交后最多等待 15 秒.",
+          `Submit a Weibo video speech-to-text transcript task from a post URL, short link, or share text; ${TRANSCRIPT_SUBMIT_WAIT_DESCRIPTION}`,
       },
       {
         name: "weibo_submit_video_speech_text_by_post_id",
         description:
-          "Submit a Weibo video speech-to-text transcript task from a post_id; 提交后最多等待 15 秒.",
+          `Submit a Weibo video speech-to-text transcript task from a post_id; ${TRANSCRIPT_SUBMIT_WAIT_DESCRIPTION}`,
       },
       {
         name: "weibo_get_video_speech_text_job",
@@ -917,12 +929,12 @@ const PLATFORMS = {
       {
         name: "wechat_submit_video_speech_text_by_video_url",
         description:
-          "Submit a WeChat Channels / 视频号 video speech-to-text transcript task from a video link or share text; 提交后最多等待 15 秒.",
+          `Submit a WeChat Channels / 视频号 video speech-to-text transcript task from a video link or share text; ${TRANSCRIPT_SUBMIT_WAIT_DESCRIPTION}`,
       },
       {
         name: "wechat_submit_video_speech_text_by_encrypted_object_id",
         description:
-          "Submit a WeChat Channels / 视频号 video speech-to-text transcript task from an encrypted_object_id; 提交后最多等待 15 秒.",
+          `Submit a WeChat Channels / 视频号 video speech-to-text transcript task from an encrypted_object_id; ${TRANSCRIPT_SUBMIT_WAIT_DESCRIPTION}`,
       },
       {
         name: "wechat_get_video_speech_text_job",
@@ -1124,6 +1136,7 @@ function validateXhsDirectActionOptions(action, options) {
   validateKnownOptions(options, allowedDirectOptions(allowedOptions));
   validateDirectMetaOptions(options);
   validateDirectPaginationOptions("xhs", action, options);
+  validateDirectTranscriptOptions(action, options);
   for (const key of allowedOptions) {
     if (!DIRECT_BOOLEAN_OPTIONS.has(key)) {
       requireOptionValue(options, key, XHS_OPTION_DISPLAY_NAMES[key]);
@@ -1140,6 +1153,7 @@ function validateDouyinDirectActionOptions(action, options) {
   validateKnownOptions(options, allowedDirectOptions(allowedOptions));
   validateDirectMetaOptions(options);
   validateDirectPaginationOptions("douyin", action, options);
+  validateDirectTranscriptOptions(action, options);
   for (const key of allowedOptions) {
     if (!DIRECT_BOOLEAN_OPTIONS.has(key)) {
       requireOptionValue(options, key, DOUYIN_OPTION_DISPLAY_NAMES[key]);
@@ -1156,6 +1170,7 @@ function validateKuaishouDirectActionOptions(action, options) {
   validateKnownOptions(options, allowedDirectOptions(allowedOptions));
   validateDirectMetaOptions(options);
   validateDirectPaginationOptions("kuaishou", action, options);
+  validateDirectTranscriptOptions(action, options);
   for (const key of allowedOptions) {
     if (!DIRECT_BOOLEAN_OPTIONS.has(key)) {
       requireOptionValue(options, key, KUAISHOU_OPTION_DISPLAY_NAMES[key]);
@@ -1200,6 +1215,7 @@ function validateWeiboDirectActionOptions(action, options) {
   validateKnownOptions(options, allowedDirectOptions(allowedOptions));
   validateDirectMetaOptions(options);
   validateDirectPaginationOptions("weibo", action, options);
+  validateDirectTranscriptOptions(action, options);
   for (const key of allowedOptions) {
     if (!DIRECT_BOOLEAN_OPTIONS.has(key)) {
       requireOptionValue(options, key, WEIBO_OPTION_DISPLAY_NAMES[key]);
@@ -1220,6 +1236,7 @@ function validateWechatDirectActionOptions(action, options) {
     validateKnownOptions(options, allowedDirectOptions(allowedOptions));
     validateDirectMetaOptions(options);
     validateDirectPaginationOptions("wechat", action, options);
+    validateDirectTranscriptOptions(action, options);
   }
   for (const key of allowedOptions) {
     if (!DIRECT_BOOLEAN_OPTIONS.has(key)) {
@@ -1283,6 +1300,18 @@ function validateDirectPaginationOptions(platformId, action, options) {
   }
 }
 
+function validateDirectTranscriptOptions(action, options) {
+  if (action !== "transcript") {
+    return;
+  }
+  if (options.maxWaitSeconds !== undefined) {
+    parsePositiveIntegerOption(
+      options.maxWaitSeconds,
+      "--max-wait-seconds"
+    );
+  }
+}
+
 function parsePositiveIntegerOption(value, displayName) {
   const text = String(value);
   if (!/^\d+$/.test(text)) {
@@ -2254,9 +2283,7 @@ async function runXhsDirectCommand(args) {
   }
 
   const operation = attachDirectMetadata(buildXhsOperation(action, options), options);
-  const data = shouldUsePaginatedDirectOutput(options)
-    ? await callPaginatedDirectOperation(operation, options)
-    : await callDirectOperation(operation);
+  const data = await callDirectOperationWithOptions(operation, options);
   const envelope = {
     platform: operation.platform.id,
     tool: operation.tool,
@@ -2285,9 +2312,7 @@ async function runDouyinDirectCommand(args) {
   validateDouyinDirectActionOptions(action, options);
 
   const operation = attachDirectMetadata(buildDouyinOperation(action, options), options);
-  const data = shouldUsePaginatedDirectOutput(options)
-    ? await callPaginatedDirectOperation(operation, options)
-    : await callDirectOperation(operation);
+  const data = await callDirectOperationWithOptions(operation, options);
   const envelope = {
     platform: operation.platform.id,
     tool: operation.tool,
@@ -2316,9 +2341,7 @@ async function runKuaishouDirectCommand(args) {
   validateKuaishouDirectActionOptions(action, options);
 
   const operation = attachDirectMetadata(buildKuaishouOperation(action, options), options);
-  const data = shouldUsePaginatedDirectOutput(options)
-    ? await callPaginatedDirectOperation(operation, options)
-    : await callDirectOperation(operation);
+  const data = await callDirectOperationWithOptions(operation, options);
   const envelope = {
     platform: operation.platform.id,
     tool: operation.tool,
@@ -2447,9 +2470,7 @@ async function runWeiboDirectCommand(args) {
   validateWeiboDirectActionOptions(action, options);
 
   const operation = attachDirectMetadata(buildWeiboOperation(action, options), options);
-  const data = shouldUsePaginatedDirectOutput(options)
-    ? await callPaginatedDirectOperation(operation, options)
-    : await callDirectOperation(operation);
+  const data = await callDirectOperationWithOptions(operation, options);
   const envelope = {
     platform: operation.platform.id,
     tool: operation.tool,
@@ -2485,9 +2506,7 @@ async function runWechatDirectCommand(args) {
   }
 
   const operation = attachDirectMetadata(buildWechatOperation(action, options), options);
-  const data = shouldUsePaginatedDirectOutput(options)
-    ? await callPaginatedDirectOperation(operation, options)
-    : await callDirectOperation(operation);
+  const data = await callDirectOperationWithOptions(operation, options);
   const envelope = {
     platform: operation.platform.id,
     tool: operation.tool,
@@ -3136,13 +3155,15 @@ function buildSensitiveCheckOperation(action, options) {
   }
 }
 
-function buildDirectOperation(operation, { tool, toolArguments }, platform = PLATFORMS.xhs) {
+function buildDirectOperation(operation, call, platform = PLATFORMS.xhs) {
+  const { tool, toolArguments, ...metadata } = call;
   return {
     platform,
     operation,
     backend: "mcp",
     tool,
     arguments: toolArguments,
+    ...metadata,
   };
 }
 
@@ -3299,6 +3320,9 @@ function buildTranscriptCall(
     toolArguments: {
       [choice.argument]: choice.value,
     },
+    transcriptJobTool: jobTool,
+    transcriptJobArgument: jobArgument,
+    transcriptIsJobLookup: choice.tool === jobTool,
   };
 }
 
@@ -3663,6 +3687,144 @@ async function callDirectOperation(operation) {
   }
 }
 
+async function callDirectOperationWithOptions(operation, options) {
+  if (shouldUsePaginatedDirectOutput(options)) {
+    return callPaginatedDirectOperation(operation, options);
+  }
+  if (operation.operation === "transcript") {
+    return callTranscriptDirectOperation(operation, options);
+  }
+  return callDirectOperation(operation);
+}
+
+async function callTranscriptDirectOperation(operation, options) {
+  const maxWaitSeconds = parseTranscriptMaxWaitSeconds(options);
+  let currentOperation = transcriptInitialOperation(operation, maxWaitSeconds);
+  let data = await callDirectOperation(currentOperation);
+  if (maxWaitSeconds <= 0 || isTerminalTranscriptData(data)) {
+    return data;
+  }
+
+  let jobId = readTranscriptJobId(data, operation);
+  if (!jobId || !operation.transcriptJobTool) {
+    return data;
+  }
+
+  const startedAtMs = Date.now();
+  while (!isTerminalTranscriptData(data)) {
+    const remainingBeforeSleep = transcriptRemainingWaitSeconds(
+      startedAtMs,
+      maxWaitSeconds
+    );
+    if (remainingBeforeSleep <= 0) {
+      break;
+    }
+
+    const sleepSeconds = Math.min(
+      transcriptNextPollAfterSeconds(data),
+      remainingBeforeSleep
+    );
+    if (sleepSeconds > 0) {
+      await sleepForSeconds(sleepSeconds);
+    }
+
+    const remainingSeconds = transcriptRemainingWaitSeconds(
+      startedAtMs,
+      maxWaitSeconds
+    );
+    if (remainingSeconds <= 0) {
+      break;
+    }
+
+    currentOperation = transcriptGetJobOperation(
+      operation,
+      jobId,
+      transcriptWaitSecondsForCall(remainingSeconds)
+    );
+    data = await callDirectOperation(currentOperation);
+    jobId = readTranscriptJobId(data, operation) || jobId;
+  }
+
+  return data;
+}
+
+function parseTranscriptMaxWaitSeconds(options) {
+  if (options.maxWaitSeconds !== undefined) {
+    return parsePositiveIntegerOption(
+      options.maxWaitSeconds,
+      "--max-wait-seconds"
+    );
+  }
+  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 transcriptGetJobOperation(operation, jobId, waitSeconds) {
+  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;
+}
+
+function transcriptNextPollAfterSeconds(data) {
+  const value = Number(data?.next_poll_after_seconds);
+  if (Number.isFinite(value) && value >= 0) {
+    return value;
+  }
+  return TRANSCRIPT_FALLBACK_POLL_SECONDS;
+}
+
+function readTranscriptJobId(data, operation) {
+  const candidate =
+    data?.job_id ||
+    data?.next_action?.job_id ||
+    data?.next_action?.arguments?.job_id ||
+    operation.arguments?.[operation.transcriptJobArgument || "job_id"];
+  const normalized = String(candidate || "").trim();
+  return normalized || undefined;
+}
+
+function isTerminalTranscriptData(data) {
+  if (data?.is_terminal === true) {
+    return true;
+  }
+  return ["succeeded", "failed", "expired"].includes(data?.status);
+}
+
+function sleepForSeconds(seconds) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, Math.max(seconds, 0) * 1000);
+  });
+}
+
 function shouldUsePaginatedDirectOutput(options) {
   return Boolean(
     options.all ||

package/package.json

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

package/skills/media-detail/SKILL.md

@@ -112,7 +112,7 @@ The command prints JSON with `platform`, `tool`, `arguments`, and `data`.
 
 ## Safety Boundary
 
-Platform detail access is read-only. It uses `SOCIALDATAX_API_KEY` from the user's environment at runtime for SocialDataX detail requests. Generated Skill files do not contain API keys. It does not read local browser data or perform login, posting, liking, commenting, or account changes. The optional WeChat Channels / 视频号 local save command writes only to the user-provided `--output` file, decrypts when needed, and does not require `SOCIALDATAX_API_KEY`. Prefer the direct CLI; hosted MCP tools are optional when the current agent already supports authenticated streamable HTTP MCP.
+Platform detail access is read-only. It uses `SOCIALDATAX_API_KEY` from the user's environment at runtime for SocialDataX detail requests. Generated Skill files do not contain API keys. It does not read local browser data or perform login, posting, liking, commenting, or account changes. The optional XHS local save command writes only to the requested local `--output` path or `--output-dir` directory and does not require `SOCIALDATAX_API_KEY`. The optional WeChat Channels / 视频号 local save command writes only to the user-provided `--output` file, decrypts when needed, and does not require `SOCIALDATAX_API_KEY`. Prefer the direct CLI; hosted MCP tools are optional when the current agent already supports authenticated streamable HTTP MCP.
 
 ## MCP Tools
 

package/skills/media-transcript/SKILL.md

@@ -118,10 +118,12 @@ Required arguments:
 
 Optional arguments:
 
+- Direct CLI transcript commands automatically wait and poll the same job by default; use positive `--max-wait-seconds <seconds>` to tune the CLI-side follow-up window after the first response.
 - `--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.
-Submit commands may wait briefly after creating the job. If the transcript is not ready, return the `job_id` and next action instead of starting a second 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.
+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
 
@@ -153,11 +155,11 @@ 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. Use the platform get-job tool with the returned `job_id`.
+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`.
 
 ## Output Guidance
 
 Return the transcript text and content context when available; include content IDs, titles or descriptions, author facts, and duration when the response provides them.
 This v1 surface does not return summary.
-When a job is still running, include the `job_id`, status, and next action so the user or agent can check later.
+When a job is still running, continue querying the same `job_id` until a terminal result is available; only surface `job_id`, status, and next action if the tool cannot continue, the command/session is interrupted, the bounded wait window is reached, or the user asks to stop.
 If the result says no processable video resource is available or the job failed, report that as the observed job result instead of retrying with another platform.