socialdatax-skills 0.2.18 → 0.2.20

package/README.md

@@ -71,7 +71,7 @@ Common search phrases for this skill package:
 - Sensitive Check MCP server name: `sensitive-check`
 - Sensitive 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.18`
+- Current public capability version: `0.2.20`
 
 ## Direct CLI
 
@@ -90,6 +90,9 @@ npx -y socialdatax-skills@latest xhs sub-comments --note-id "<note_id>" --commen
 npx -y socialdatax-skills@latest xhs user-info --user-id "<user_id>" --pretty
 npx -y socialdatax-skills@latest xhs user-posts --user-id "<user_id>" --pretty
 npx -y socialdatax-skills@latest xhs user-posts --user-id "<user_id>" --since-days 30 --pretty
+npx -y socialdatax-skills@latest xhs transcript --url "<note_url_or_share_text>" --pretty
+npx -y socialdatax-skills@latest xhs transcript --note-id "<note_id>" --pretty
+npx -y socialdatax-skills@latest xhs transcript --job-id "<job_id>" --pretty
 npx -y socialdatax-skills@latest douyin hot-search --pretty
 npx -y socialdatax-skills@latest douyin search --keyword "露营" --pretty
 npx -y socialdatax-skills@latest douyin detail --aweme-id "<aweme_id>" --pretty
@@ -102,6 +105,9 @@ npx -y socialdatax-skills@latest douyin user-posts --sec-user-id "<sec_user_id>"
 npx -y socialdatax-skills@latest douyin user-posts --profile-url "<profile_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest douyin user-series --sec-user-id "<sec_user_id>" --pretty
 npx -y socialdatax-skills@latest douyin user-series --profile-url "<profile_url_or_share_text>" --pretty
+npx -y socialdatax-skills@latest douyin transcript --url "<douyin_content_url_or_share_text>" --pretty
+npx -y socialdatax-skills@latest douyin transcript --aweme-id "<aweme_id>" --pretty
+npx -y socialdatax-skills@latest douyin transcript --job-id "<job_id>" --pretty
 npx -y socialdatax-skills@latest kuaishou search --keyword "露营" --pretty
 npx -y socialdatax-skills@latest kuaishou user-search --keyword "露营" --pretty
 npx -y socialdatax-skills@latest kuaishou detail --photo-id "<photo_id>" --pretty
@@ -114,6 +120,9 @@ npx -y socialdatax-skills@latest kuaishou user-info --user-id "<user_id>" --pret
 npx -y socialdatax-skills@latest kuaishou user-info --profile-url "<profile_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest kuaishou user-posts --user-id "<user_id>" --pretty
 npx -y socialdatax-skills@latest kuaishou user-posts --profile-url "<profile_url_or_share_text>" --pretty
+npx -y socialdatax-skills@latest kuaishou transcript --url "<kuaishou_content_url_or_share_text>" --pretty
+npx -y socialdatax-skills@latest kuaishou transcript --photo-id "<photo_id>" --pretty
+npx -y socialdatax-skills@latest kuaishou transcript --job-id "<job_id>" --pretty
 npx -y socialdatax-skills@latest weibo hot-search --pretty
 npx -y socialdatax-skills@latest weibo search --keyword "露营" --pretty
 npx -y socialdatax-skills@latest weibo detail --post-id "<post_id>" --pretty
@@ -128,6 +137,9 @@ npx -y socialdatax-skills@latest weibo user-info --user-id "<user_id>" --pretty
 npx -y socialdatax-skills@latest weibo user-info --profile-url "<profile_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest weibo user-posts --user-id "<user_id>" --pretty
 npx -y socialdatax-skills@latest weibo user-posts --profile-url "<profile_url_or_share_text>" --pretty
+npx -y socialdatax-skills@latest weibo transcript --post-url "<weibo_post_url_or_share_text>" --pretty
+npx -y socialdatax-skills@latest weibo transcript --post-id "<post_id>" --pretty
+npx -y socialdatax-skills@latest weibo transcript --job-id "<job_id>" --pretty
 npx -y socialdatax-skills@latest wechat hot-search --pretty
 npx -y socialdatax-skills@latest wechat search --keyword "露营" --pretty
 npx -y socialdatax-skills@latest wechat detail --encrypted-object-id "<encrypted_object_id>" --pretty
@@ -140,6 +152,9 @@ npx -y socialdatax-skills@latest wechat replies --object-id "<object_id>" --obje
 npx -y socialdatax-skills@latest wechat user-info --user-id "<finder_user_id>" --pretty
 npx -y socialdatax-skills@latest wechat user-posts --user-id "<finder_user_id>" --pretty
 npx -y socialdatax-skills@latest wechat user-posts --url "<wechat_video_url_or_share_text>" --pretty
+npx -y socialdatax-skills@latest wechat transcript --url "<wechat_video_url_or_share_text>" --pretty
+npx -y socialdatax-skills@latest wechat transcript --encrypted-object-id "<encrypted_object_id>" --pretty
+npx -y socialdatax-skills@latest wechat transcript --job-id "<job_id>" --pretty
 npx -y socialdatax-skills@latest sensitive-check text --text "<content>" --platform xhs --pretty
 ```
 
@@ -159,6 +174,8 @@ 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`.
+
 Generated Agent Skill examples include `--source-client socialdatax-skills --source-platform <marketplace> --source-skill <skill-slug>` so SocialDataX can attribute direct CLI usage to the current marketplace Skill. Keep those values unchanged when running commands from a Skill; omit them for ad hoc CLI use. The direct CLI also accepts `SOCIALDATAX_SOURCE_CLIENT`, `SOCIALDATAX_SOURCE_PLATFORM`, and `SOCIALDATAX_SOURCE_SKILL` as environment-variable fallbacks.
 
 XHS, Douyin, Kuaishou, Weibo, and WeChat Channels search use `--keyword` and optional `--page-token`.
@@ -258,15 +275,20 @@ npx -y socialdatax-skills@latest install media-search --target claude-code
 npx -y socialdatax-skills@latest install media-search --target claude-code --scope workspace
 npx -y socialdatax-skills@latest xhs search --keyword "露营" --pretty
 npx -y socialdatax-skills@latest xhs hot-search --pretty
+npx -y socialdatax-skills@latest xhs transcript --url "<note_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest douyin hot-search --pretty
 npx -y socialdatax-skills@latest douyin search --keyword "露营" --pretty
 npx -y socialdatax-skills@latest douyin user-series --sec-user-id "<sec_user_id>" --pretty
+npx -y socialdatax-skills@latest douyin transcript --aweme-id "<aweme_id>" --pretty
 npx -y socialdatax-skills@latest kuaishou search --keyword "露营" --pretty
+npx -y socialdatax-skills@latest kuaishou transcript --photo-id "<photo_id>" --pretty
 npx -y socialdatax-skills@latest weibo hot-search --pretty
 npx -y socialdatax-skills@latest weibo search --keyword "露营" --pretty
+npx -y socialdatax-skills@latest weibo transcript --post-id "<post_id>" --pretty
 npx -y socialdatax-skills@latest wechat hot-search --pretty
 npx -y socialdatax-skills@latest wechat search --keyword "露营" --pretty
 npx -y socialdatax-skills@latest wechat article --url "<mp_article_url_or_share_text>" --pretty
+npx -y socialdatax-skills@latest wechat transcript --encrypted-object-id "<encrypted_object_id>" --pretty
 npx -y socialdatax-skills@latest sensitive-check text --text "<content>" --platform xhs --pretty
 ```
 
@@ -276,7 +298,7 @@ Available skills:
 - `media-search`: search social media content by keyword; supports XHS notes, Douyin works, Kuaishou works, Weibo posts, and WeChat Channels videos.
 - `media-detail`: read structured content details and metrics; supports XHS notes, Douyin works, Kuaishou works, Weibo posts, WeChat Channels videos, and WeChat Official Account articles.
 - `media-comments`: fetch and analyze XHS comments/replies, Douyin comments/replies, Kuaishou comments/replies, Weibo comments/replies, and WeChat Channels comments/replies.
-- `media-transcript`: submit and check video 口播转文字 / speech-to-text transcript jobs through hosted MCP tools; supports XHS, Douyin, Kuaishou, Weibo, and WeChat Channels.
+- `media-transcript`: submit and check video 口播转文字 / speech-to-text transcript jobs through direct CLI commands or hosted MCP tools; supports XHS, Douyin, Kuaishou, Weibo, and WeChat Channels.
 - `media-user-info`: retrieve creator profile information; supports XHS, Douyin, Kuaishou, Weibo, and WeChat Channels creators.
 - `media-user-posts`: retrieve creator content lists; supports XHS notes, Douyin works, Kuaishou works, Weibo posts, WeChat Channels videos, and Douyin creator short-drama series.
 - `sensitive-check`: run 敏感检测 text checks; supports `generic`, `xhs`, `douyin`, and `kuaishou` platform contexts.
@@ -297,7 +319,7 @@ If no skill name is provided, all skills are installed. If a destination already
 
 ## Workflow Scope
 
-The current platform MCP services are designed for social media content intelligence workflows. Some tools read public content directly; some submit bounded analysis jobs such as video speech-to-text transcript. They do not provide account login, posting, editing, liking, commenting, or other account actions.
+The current direct CLI and platform MCP services are designed for social media content intelligence workflows. Some commands read public content directly; some submit bounded analysis jobs such as video speech-to-text transcript. They do not provide account login, posting, editing, liking, commenting, or other account actions.
 
 Current XHS workflows include:
 
@@ -309,7 +331,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 提交后最多等待 15 秒.
 
 Current Kuaishou workflows include:
 
@@ -321,7 +343,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 提交后最多等待 15 秒.
 
 Current Douyin workflows include:
 
@@ -334,7 +356,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 提交后最多等待 15 秒.
 
 Current Weibo workflows include:
 
@@ -346,7 +368,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 提交后最多等待 15 秒.
 
 Current WeChat / 微信 workflows include:
 
@@ -359,7 +381,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 提交后最多等待 15 秒.
 
 Current Sensitive Check workflows include:
 

package/cli.mjs

@@ -7,7 +7,7 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PACKAGE_NAME = "socialdatax-skills";
-const PACKAGE_VERSION = "0.2.18";
+const PACKAGE_VERSION = "0.2.20";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
 const LOG_PREFIX = `[${PACKAGE_NAME}]`;
 const MIN_NODE_VERSION = "20.18.1";
@@ -53,7 +53,7 @@ const AVAILABLE_SKILLS = [
   {
     name: "media-transcript",
     summary:
-      "Submit and check video speech-to-text transcript jobs for XHS, Douyin, Kuaishou, Weibo, and WeChat Channels through hosted MCP tools.",
+      "Submit and check video speech-to-text transcript jobs for XHS, Douyin, Kuaishou, Weibo, and WeChat Channels.",
     emoji: "🎙️",
   },
   {
@@ -134,6 +134,7 @@ const XHS_DIRECT_ACTION_OPTIONS = {
     "sinceDays",
     "pretty",
   ],
+  transcript: ["url", "noteId", "jobId", "pretty"],
 };
 const XHS_DIRECT_ACTION_NAMES = Object.keys(XHS_DIRECT_ACTION_OPTIONS).join(", ");
 const XHS_OPTION_DISPLAY_NAMES = {
@@ -152,6 +153,7 @@ const XHS_OPTION_DISPLAY_NAMES = {
   includeReplies: "--include-replies",
   profileUrl: "--profile-url",
   userId: "--user-id",
+  jobId: "--job-id",
 };
 const XHS_SEARCH_SORT_TYPES = [
   "general",
@@ -213,6 +215,7 @@ const DOUYIN_DIRECT_ACTION_OPTIONS = {
     "pretty",
   ],
   "user-series": ["secUserId", "profileUrl", "pageToken", "pages", "all", "maxItems", "pretty"],
+  transcript: ["url", "awemeId", "jobId", "pretty"],
 };
 const DOUYIN_DIRECT_ACTION_NAMES = Object.keys(DOUYIN_DIRECT_ACTION_OPTIONS).join(", ");
 const DOUYIN_SEARCH_SORT_TYPES = ["general", "time_descending", "like_count_descending"];
@@ -241,6 +244,7 @@ const DOUYIN_OPTION_DISPLAY_NAMES = {
   awemeId: "--aweme-id",
   commentId: "--comment-id",
   secUserId: "--sec-user-id",
+  jobId: "--job-id",
 };
 const KUAISHOU_DIRECT_ACTION_OPTIONS = {
   search: ["keyword", "pageToken", "pages", "all", "maxItems", "sinceDays", "pretty"],
@@ -277,6 +281,7 @@ const KUAISHOU_DIRECT_ACTION_OPTIONS = {
     "sinceDays",
     "pretty",
   ],
+  transcript: ["url", "photoId", "jobId", "pretty"],
 };
 const KUAISHOU_DIRECT_ACTION_NAMES = Object.keys(KUAISHOU_DIRECT_ACTION_OPTIONS).join(", ");
 const KUAISHOU_OPTION_DISPLAY_NAMES = {
@@ -292,6 +297,7 @@ const KUAISHOU_OPTION_DISPLAY_NAMES = {
   photoId: "--photo-id",
   commentId: "--comment-id",
   userId: "--user-id",
+  jobId: "--job-id",
 };
 const WEIBO_DIRECT_ACTION_OPTIONS = {
   "hot-search": ["pretty"],
@@ -330,6 +336,7 @@ const WEIBO_DIRECT_ACTION_OPTIONS = {
     "sinceDays",
     "pretty",
   ],
+  transcript: ["postUrl", "postId", "jobId", "pretty"],
 };
 const WEIBO_DIRECT_ACTION_NAMES = Object.keys(WEIBO_DIRECT_ACTION_OPTIONS).join(", ");
 const WEIBO_OPTION_DISPLAY_NAMES = {
@@ -345,6 +352,7 @@ const WEIBO_OPTION_DISPLAY_NAMES = {
   commentId: "--comment-id",
   profileUrl: "--profile-url",
   userId: "--user-id",
+  jobId: "--job-id",
 };
 const WECHAT_DIRECT_ACTION_OPTIONS = {
   "hot-search": ["pretty"],
@@ -394,6 +402,7 @@ const WECHAT_DIRECT_ACTION_OPTIONS = {
     "sinceDays",
     "pretty",
   ],
+  transcript: ["url", "encryptedObjectId", "jobId", "pretty"],
 };
 const WECHAT_DIRECT_ACTION_NAMES = Object.keys(WECHAT_DIRECT_ACTION_OPTIONS).join(", ");
 const WECHAT_SEARCH_SORT_TYPES = [
@@ -423,6 +432,7 @@ const WECHAT_OPTION_DISPLAY_NAMES = {
   objectNonceId: "--object-nonce-id",
   commentId: "--comment-id",
   userId: "--user-id",
+  jobId: "--job-id",
 };
 const SENSITIVE_CHECK_DIRECT_ACTION_OPTIONS = {
   text: ["text", "platform", "pretty"],
@@ -504,12 +514,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; 提交后最多等待 15 秒.",
       },
       {
         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; 提交后最多等待 15 秒.",
       },
       {
         name: "xhs_get_video_speech_text_job",
@@ -588,12 +598,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; 提交后最多等待 15 秒.",
       },
       {
         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; 提交后最多等待 15 秒.",
       },
       {
         name: "douyin_get_video_speech_text_job",
@@ -668,12 +678,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; 提交后最多等待 15 秒.",
       },
       {
         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; 提交后最多等待 15 秒.",
       },
       {
         name: "kuaishou_get_video_speech_text_job",
@@ -752,12 +762,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; 提交后最多等待 15 秒.",
       },
       {
         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; 提交后最多等待 15 秒.",
       },
       {
         name: "weibo_get_video_speech_text_job",
@@ -829,12 +839,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; 提交后最多等待 15 秒.",
       },
       {
         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; 提交后最多等待 15 秒.",
       },
       {
         name: "wechat_get_video_speech_text_job",
@@ -978,6 +988,15 @@ function validateKnownOptions(options, allowedOptions) {
   }
 }
 
+function shouldPrintDirectHelp(options, positional) {
+  return (
+    options.help !== undefined ||
+    options.h !== undefined ||
+    positional.includes("help") ||
+    positional.includes("-h")
+  );
+}
+
 function allowedDirectOptions(allowedOptions) {
   return [...allowedOptions, ...DIRECT_META_OPTIONS];
 }
@@ -1613,7 +1632,8 @@ function buildDoctorReport() {
     },
     security: {
       readOnly: false,
-      directCliReadOnly: true,
+      directCliReadOnly: false,
+      directCliMaySubmitAnalysisJobs: true,
       platformMcpMaySubmitAnalysisJobs: true,
       accountActions: false,
       readsLocalBrowserData: false,
@@ -1656,6 +1676,7 @@ function printDoctor(args) {
   console.log("");
   console.log("Runtime data calls:");
   console.log("- social media content intelligence workflows.");
+  console.log("- some commands submit bounded analysis jobs such as video speech-to-text transcript.");
   console.log("- no login, posting, editing, liking, commenting, or other account actions.");
   console.log("- no local browser data access.");
   console.log(`- requires ${PRIMARY_API_KEY_ENV} only when making authenticated data calls.`);
@@ -1712,6 +1733,9 @@ function printHelp() {
   console.log(`  npx -y ${PACKAGE_SPEC} xhs user-posts --user-id "<user_id>" --since-days 30 --pretty`);
   console.log("      Fetch recent creator posts until the publish-time boundary is reached.");
   console.log("");
+  console.log(`  npx -y ${PACKAGE_SPEC} xhs transcript --url "<xhs_note_url_or_share_text>" --pretty`);
+  console.log("      Submit or check an XHS video note speech-to-text transcript job.");
+  console.log("");
   console.log(`  npx -y ${PACKAGE_SPEC} douyin hot-search --pretty`);
   console.log("      Call the Douyin main hot search list tool directly and print JSON.");
   console.log("");
@@ -1750,6 +1774,9 @@ function printHelp() {
   console.log(`  npx -y ${PACKAGE_SPEC} douyin user-series --profile-url "<profile_url_or_share_text>" --pretty`);
   console.log("      Call the Douyin creator short-drama series tool from a profile link or share text.");
   console.log("");
+  console.log(`  npx -y ${PACKAGE_SPEC} douyin transcript --aweme-id "<aweme_id>" --pretty`);
+  console.log("      Submit or check a Douyin video speech-to-text transcript job.");
+  console.log("");
   console.log(`  npx -y ${PACKAGE_SPEC} kuaishou search --keyword "露营" --pretty`);
   console.log("      Call the Kuaishou work search tool directly and print JSON.");
   console.log("");
@@ -1790,6 +1817,9 @@ function printHelp() {
     "      Call the Kuaishou creator works tool from a profile link or share text that resolves directly to a non-empty user_id."
   );
   console.log("");
+  console.log(`  npx -y ${PACKAGE_SPEC} kuaishou transcript --photo-id "<photo_id>" --pretty`);
+  console.log("      Submit or check a Kuaishou video speech-to-text transcript job.");
+  console.log("");
   console.log(`  npx -y ${PACKAGE_SPEC} weibo hot-search --pretty`);
   console.log("      Call the Weibo hot-search list tool directly and print JSON.");
   console.log("");
@@ -1829,6 +1859,9 @@ function printHelp() {
   console.log(`  npx -y ${PACKAGE_SPEC} weibo user-posts --profile-url "<profile_url_or_share_text>" --pretty`);
   console.log("      Call the Weibo creator posts tool from a profile link or share text.");
   console.log("");
+  console.log(`  npx -y ${PACKAGE_SPEC} weibo transcript --post-url "<weibo_post_url_or_share_text>" --pretty`);
+  console.log("      Submit or check a Weibo video speech-to-text transcript job.");
+  console.log("");
   console.log(`  npx -y ${PACKAGE_SPEC} wechat hot-search --pretty`);
   console.log("      Call the WeChat Channels / 视频号 hot-search list tool directly and print JSON.");
   console.log("");
@@ -1864,6 +1897,9 @@ function printHelp() {
   console.log(`  npx -y ${PACKAGE_SPEC} wechat user-posts --url "<wechat_video_url_or_share_text>" --pretty`);
   console.log("      Call the WeChat Channels / 视频号 creator videos tool from a video link or share text.");
   console.log("");
+  console.log(`  npx -y ${PACKAGE_SPEC} wechat transcript --encrypted-object-id "<encrypted_object_id>" --pretty`);
+  console.log("      Submit or check a WeChat Channels / 视频号 video speech-to-text transcript job.");
+  console.log("");
   console.log(`  npx -y ${PACKAGE_SPEC} sensitive-check text --text "<content>" --platform xhs --pretty`);
   console.log("      Call the SocialDataX 敏感检测 text tool directly and print JSON.");
   console.log("");
@@ -1941,6 +1977,7 @@ function printHelp() {
   console.log("  --post-id <post_id>");
   console.log("  --post-url <weibo-post-url-or-share-text>");
   console.log("  --encrypted-object-id <encrypted_object_id>");
+  console.log("  --job-id <job_id>");
   console.log("  --object-id <object_id>");
   console.log("  --object-nonce-id <object_nonce_id>");
   console.log("  --comment-id <comment_id>");
@@ -2030,6 +2067,10 @@ function printRemovedMcpConfigHelp(command) {
 
 async function runXhsDirectCommand(args) {
   const { options, positional } = parseCommandArgs(args);
+  if (shouldPrintDirectHelp(options, positional)) {
+    printHelp();
+    return;
+  }
   const action = positional[0];
   if (!action) {
     throw new Error(
@@ -2057,6 +2098,10 @@ async function runXhsDirectCommand(args) {
 
 async function runDouyinDirectCommand(args) {
   const { options, positional } = parseCommandArgs(args);
+  if (shouldPrintDirectHelp(options, positional)) {
+    printHelp();
+    return;
+  }
   const action = positional[0];
   if (!action) {
     throw new Error(
@@ -2084,6 +2129,10 @@ async function runDouyinDirectCommand(args) {
 
 async function runKuaishouDirectCommand(args) {
   const { options, positional } = parseCommandArgs(args);
+  if (shouldPrintDirectHelp(options, positional)) {
+    printHelp();
+    return;
+  }
   const action = positional[0];
   if (!action) {
     throw new Error(
@@ -2111,6 +2160,10 @@ async function runKuaishouDirectCommand(args) {
 
 async function runWeiboDirectCommand(args) {
   const { options, positional } = parseCommandArgs(args);
+  if (shouldPrintDirectHelp(options, positional)) {
+    printHelp();
+    return;
+  }
   const action = positional[0];
   if (!action) {
     throw new Error(
@@ -2138,6 +2191,10 @@ async function runWeiboDirectCommand(args) {
 
 async function runWechatDirectCommand(args) {
   const { options, positional } = parseCommandArgs(args);
+  if (shouldPrintDirectHelp(options, positional)) {
+    printHelp();
+    return;
+  }
   const action = positional[0];
   if (!action) {
     throw new Error(
@@ -2165,6 +2222,10 @@ async function runWechatDirectCommand(args) {
 
 async function runSensitiveCheckDirectCommand(args) {
   const { options, positional } = parseCommandArgs(args);
+  if (shouldPrintDirectHelp(options, positional)) {
+    printHelp();
+    return;
+  }
   const action = positional[0];
   if (!action) {
     throw new Error(
@@ -2262,6 +2323,24 @@ function buildXhsOperation(action, options) {
           pageToken: options.pageToken,
         })
       );
+    case "transcript":
+      return buildDirectOperation(
+        "transcript",
+        buildTranscriptCall(options, {
+          urlOption: "url",
+          idOption: "noteId",
+          jobOption: "jobId",
+          urlTool: "xhs_submit_video_speech_text_by_note_url",
+          idTool: "xhs_submit_video_speech_text_by_note_id",
+          jobTool: "xhs_get_video_speech_text_job",
+          urlArgument: "note_url",
+          idArgument: "note_id",
+          jobArgument: "job_id",
+          urlDisplay: "--url",
+          idDisplay: "--note-id",
+          jobDisplay: "--job-id",
+        })
+      );
     default:
       throw new Error(
         `Unsupported XHS command "${action}". Use ${XHS_DIRECT_ACTION_NAMES}.`
@@ -2370,6 +2449,25 @@ function buildDouyinOperation(action, options) {
         }),
         PLATFORMS.douyin
       );
+    case "transcript":
+      return buildDirectOperation(
+        "transcript",
+        buildTranscriptCall(options, {
+          urlOption: "url",
+          idOption: "awemeId",
+          jobOption: "jobId",
+          urlTool: "douyin_submit_video_speech_text_by_video_url",
+          idTool: "douyin_submit_video_speech_text_by_aweme_id",
+          jobTool: "douyin_get_video_speech_text_job",
+          urlArgument: "video_url",
+          idArgument: "aweme_id",
+          jobArgument: "job_id",
+          urlDisplay: "--url",
+          idDisplay: "--aweme-id",
+          jobDisplay: "--job-id",
+        }),
+        PLATFORMS.douyin
+      );
     default:
       throw new Error(
         `Unsupported Douyin command "${action}". Use ${DOUYIN_DIRECT_ACTION_NAMES}.`
@@ -2459,6 +2557,25 @@ function buildKuaishouOperation(action, options) {
         }),
         PLATFORMS.kuaishou
       );
+    case "transcript":
+      return buildDirectOperation(
+        "transcript",
+        buildTranscriptCall(options, {
+          urlOption: "url",
+          idOption: "photoId",
+          jobOption: "jobId",
+          urlTool: "kuaishou_submit_video_speech_text_by_video_url",
+          idTool: "kuaishou_submit_video_speech_text_by_photo_id",
+          jobTool: "kuaishou_get_video_speech_text_job",
+          urlArgument: "video_url",
+          idArgument: "photo_id",
+          jobArgument: "job_id",
+          urlDisplay: "--url",
+          idDisplay: "--photo-id",
+          jobDisplay: "--job-id",
+        }),
+        PLATFORMS.kuaishou
+      );
     default:
       throw new Error(
         `Unsupported Kuaishou command "${action}". Use ${KUAISHOU_DIRECT_ACTION_NAMES}.`
@@ -2563,6 +2680,25 @@ function buildWeiboOperation(action, options) {
         }),
         PLATFORMS.weibo
       );
+    case "transcript":
+      return buildDirectOperation(
+        "transcript",
+        buildTranscriptCall(options, {
+          urlOption: "postUrl",
+          idOption: "postId",
+          jobOption: "jobId",
+          urlTool: "weibo_submit_video_speech_text_by_post_url",
+          idTool: "weibo_submit_video_speech_text_by_post_id",
+          jobTool: "weibo_get_video_speech_text_job",
+          urlArgument: "post_url",
+          idArgument: "post_id",
+          jobArgument: "job_id",
+          urlDisplay: "--post-url",
+          idDisplay: "--post-id",
+          jobDisplay: "--job-id",
+        }),
+        PLATFORMS.weibo
+      );
     default:
       throw new Error(
         `Unsupported Weibo command "${action}". Use ${WEIBO_DIRECT_ACTION_NAMES}.`
@@ -2648,6 +2784,25 @@ function buildWechatOperation(action, options) {
         }),
         PLATFORMS.wechat
       );
+    case "transcript":
+      return buildDirectOperation(
+        "transcript",
+        buildTranscriptCall(options, {
+          urlOption: "url",
+          idOption: "encryptedObjectId",
+          jobOption: "jobId",
+          urlTool: "wechat_submit_video_speech_text_by_video_url",
+          idTool: "wechat_submit_video_speech_text_by_encrypted_object_id",
+          jobTool: "wechat_get_video_speech_text_job",
+          urlArgument: "video_url",
+          idArgument: "encrypted_object_id",
+          jobArgument: "job_id",
+          urlDisplay: "--url",
+          idDisplay: "--encrypted-object-id",
+          jobDisplay: "--job-id",
+        }),
+        PLATFORMS.wechat
+      );
     default:
       throw new Error(
         `Unsupported WeChat command "${action}". Use ${WECHAT_DIRECT_ACTION_NAMES}.`
@@ -2769,6 +2924,58 @@ function buildOneOfCall(
   return { tool, toolArguments };
 }
 
+function buildTranscriptCall(
+  options,
+  {
+    urlOption,
+    idOption,
+    jobOption,
+    urlTool,
+    idTool,
+    jobTool,
+    urlArgument,
+    idArgument,
+    jobArgument,
+    urlDisplay,
+    idDisplay,
+    jobDisplay,
+  }
+) {
+  const choices = [
+    {
+      value: options[urlOption],
+      tool: urlTool,
+      argument: urlArgument,
+    },
+    {
+      value: options[idOption],
+      tool: idTool,
+      argument: idArgument,
+    },
+    {
+      value: options[jobOption],
+      tool: jobTool,
+      argument: jobArgument,
+    },
+  ].filter((choice) => Boolean(choice.value));
+  const displays = `${urlDisplay}, ${idDisplay}, or ${jobDisplay}`;
+
+  if (choices.length === 0) {
+    throw new Error(`Missing input. Use exactly one of ${displays}.`);
+  }
+  if (choices.length > 1) {
+    throw new Error(`Use exactly one of ${displays}.`);
+  }
+
+  const choice = choices[0];
+  return {
+    tool: choice.tool,
+    toolArguments: {
+      [choice.argument]: choice.value,
+    },
+  };
+}
+
 function buildRequiredIdCall(
   options,
   {

package/package.json

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

package/skills/media-transcript/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "media-transcript"
-description: "Submit and check video speech-to-text transcript / 口播转文字 jobs for XHS, Douyin, Kuaishou, Weibo, and WeChat Channels through hosted platform MCP tools."
+description: "Submit and check video speech-to-text transcript / 口播转文字 jobs for XHS, Douyin, Kuaishou, Weibo, and WeChat Channels through direct CLI commands or hosted platform MCP tools."
 source_client: "socialdatax-skills"
 source_platform: "npm"
 source_skill: "media-transcript"
@@ -39,30 +39,49 @@ Current platform support:
 Use `SOCIALDATAX_API_KEY` for SocialDataX requests. The only official website for requesting or managing API access is <https://socialdatax.com/?from=npm>. If a user asks where to get a key, provide only this URL; do not infer alternate domains.
 获取或管理 API Key：访问 <https://socialdatax.com/?from=npm>，按官网的 API Key 申请/管理入口操作。环境变量名固定使用 `SOCIALDATAX_API_KEY`；不要引导用户使用其他域名。
 
+## Preferred Direct CLI
+
+Prefer the direct CLI when the agent can run shell commands. It does not require MCP server configuration:
+
+```bash
+npx -y socialdatax-skills@latest xhs transcript --url "<note_url_or_share_text>" --pretty --source-client socialdatax-skills --source-platform npm --source-skill media-transcript
+npx -y socialdatax-skills@latest xhs transcript --note-id "<note_id>" --pretty --source-client socialdatax-skills --source-platform npm --source-skill media-transcript
+npx -y socialdatax-skills@latest xhs transcript --job-id "<job_id>" --pretty --source-client socialdatax-skills --source-platform npm --source-skill media-transcript
+npx -y socialdatax-skills@latest douyin transcript --url "<douyin_content_url_or_share_text>" --pretty --source-client socialdatax-skills --source-platform npm --source-skill media-transcript
+npx -y socialdatax-skills@latest douyin transcript --aweme-id "<aweme_id>" --pretty --source-client socialdatax-skills --source-platform npm --source-skill media-transcript
+npx -y socialdatax-skills@latest douyin transcript --job-id "<job_id>" --pretty --source-client socialdatax-skills --source-platform npm --source-skill media-transcript
+npx -y socialdatax-skills@latest kuaishou transcript --url "<kuaishou_content_url_or_share_text>" --pretty --source-client socialdatax-skills --source-platform npm --source-skill media-transcript
+npx -y socialdatax-skills@latest kuaishou transcript --photo-id "<photo_id>" --pretty --source-client socialdatax-skills --source-platform npm --source-skill media-transcript
+npx -y socialdatax-skills@latest kuaishou transcript --job-id "<job_id>" --pretty --source-client socialdatax-skills --source-platform npm --source-skill media-transcript
+npx -y socialdatax-skills@latest weibo transcript --post-url "<weibo_post_url_or_share_text>" --pretty --source-client socialdatax-skills --source-platform npm --source-skill media-transcript
+npx -y socialdatax-skills@latest weibo transcript --post-id "<post_id>" --pretty --source-client socialdatax-skills --source-platform npm --source-skill media-transcript
+npx -y socialdatax-skills@latest weibo transcript --job-id "<job_id>" --pretty --source-client socialdatax-skills --source-platform npm --source-skill media-transcript
+npx -y socialdatax-skills@latest wechat transcript --url "<wechat_video_url_or_share_text>" --pretty --source-client socialdatax-skills --source-platform npm --source-skill media-transcript
+npx -y socialdatax-skills@latest wechat transcript --encrypted-object-id "<encrypted_object_id>" --pretty --source-client socialdatax-skills --source-platform npm --source-skill media-transcript
+npx -y socialdatax-skills@latest wechat transcript --job-id "<job_id>" --pretty --source-client socialdatax-skills --source-platform npm --source-skill media-transcript
+```
+
 Required arguments:
 
-- Use a submit-by-URL tool when the user provides a content link, short link, or share text.
-- Use a submit-by-ID tool only when the platform content ID is already known: XHS `note_id`, Douyin `aweme_id`, Kuaishou `photo_id`, Weibo `post_id`, or WeChat Channels / 视频号 `encrypted_object_id`.
-- Use the matching get-job tool with `job_id` when continuing or checking an existing transcript job.
+- Use a submit-by-URL command when the user provides a content link, short link, or share text.
+- Use a submit-by-ID command only when the platform content ID is already known: XHS `note_id`, Douyin `aweme_id`, Kuaishou `photo_id`, Weibo `post_id`, or WeChat Channels / 视频号 `encrypted_object_id`.
+- Use the matching `transcript --job-id <job_id>` command when continuing or checking an existing transcript job.
+- For one transcript command, pass exactly one entrypoint: URL/share text, platform content ID, or `job_id`.
+
+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.
 
-These video speech-to-text transcript / 口播转文字 workflows are MCP-only and not available through the direct CLI.
-Submit tools 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.
+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.
 
 ## Safety Boundary
 
-This skill can submit bounded analysis jobs through hosted MCP tools. It uses authenticated MCP access from the current agent at runtime. Generated Skill files do not contain API keys. It does not read local browser data or perform login, posting, liking, commenting, or account changes. Use hosted MCP tools only when the current agent already supports authenticated streamable HTTP MCP.
+This skill can submit bounded video speech-to-text analysis jobs through the direct CLI or hosted MCP tools. It uses `SOCIALDATAX_API_KEY` from the user's environment at runtime. Generated Skill files do not contain API keys. It does not read local browser data or perform login, posting, liking, commenting, or account changes. Prefer the direct CLI; hosted MCP tools are optional when the current agent already supports authenticated streamable HTTP MCP.
 
 ## MCP Tools
 
-If MCP tools are already available in the current agent, choose the platform-specific submit tool by entrypoint:
-- XHS: `xhs_submit_video_speech_text_by_note_url`, `xhs_submit_video_speech_text_by_note_id`, `xhs_get_video_speech_text_job`.
-- Douyin: `douyin_submit_video_speech_text_by_video_url`, `douyin_submit_video_speech_text_by_aweme_id`, `douyin_get_video_speech_text_job`.
-- 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`.
-
-MCP-only tools not available through the direct CLI:
+MCP tools matching the direct CLI commands above:
 
 - `xhs_submit_video_speech_text_by_note_url`
 - `xhs_submit_video_speech_text_by_note_id`
@@ -80,6 +99,14 @@ MCP-only tools not available through the direct CLI:
 - `wechat_submit_video_speech_text_by_encrypted_object_id`
 - `wechat_get_video_speech_text_job`
 
+If MCP tools are already available in the current agent, choose the platform-specific submit tool by entrypoint:
+- XHS: `xhs_submit_video_speech_text_by_note_url`, `xhs_submit_video_speech_text_by_note_id`, `xhs_get_video_speech_text_job`.
+- Douyin: `douyin_submit_video_speech_text_by_video_url`, `douyin_submit_video_speech_text_by_aweme_id`, `douyin_get_video_speech_text_job`.
+- 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`.
+
 ## Output Guidance
 
 Return the transcript text when available. When a job is still running, include the `job_id`, status, and next action so the user or agent can check later.