socialdatax-skills 0.2.35 → 0.2.36

package/README.md

@@ -2,7 +2,7 @@
 
 This public package provides the unified skill installer and direct CLI helper for SocialDataX services.
 
-The current public tools support 小红书 / Xiaohongshu / XHS / RedNote, 抖音 / Douyin, 快手 / Kuaishou / Kwai, Bilibili / 哔哩哔哩 / B站, 微博 / Weibo, 视频号 / WeChat Channels, 知乎 / Zhihu, Instagram, X / Twitter, YouTube, and TikTok content research and analysis workflows, plus WeChat Official Account / 微信公众号 article details, XHS / Douyin / Kuaishou / Weibo local media download, WeChat Channels local media decrypt/save, Bilibili local video download, and 敏感词检测 / 违禁词检查 text checks. The public skill layer is intentionally named by capability so supported services can evolve without changing the installation model.
+The current public tools support 小红书 / Xiaohongshu / XHS / RedNote, 抖音 / Douyin, 快手 / Kuaishou / Kwai, Bilibili / 哔哩哔哩 / B站, 微博 / Weibo, 视频号 / WeChat Channels, 知乎 / Zhihu, Instagram, X / Twitter, YouTube, and TikTok content research and analysis workflows, plus WeChat Official Account / 微信公众号 article details, XHS / Douyin / Kuaishou / Weibo / X / Twitter local media download, WeChat Channels local media decrypt/save, Bilibili local video download, and 敏感词检测 / 违禁词检查 text checks. The public skill layer is intentionally named by capability so supported services can evolve without changing the installation model.
 
 - direct `npx` JSON commands for agents that can run shell commands
 - AgentSkills-compatible installers split by capability for OpenClaw, Hermes Agent, Codex, Claude Code, and general agent skill directories
@@ -89,7 +89,7 @@ Common search phrases for this skill package:
 - Reserved future SocialDataX namespace names for existing platform listings without draft files yet: `com.socialdatax/kuaishou-insights`, `com.socialdatax/weibo-insights`, `com.socialdatax/wechat-channels-insights`, and `com.socialdatax/instagram-insights`.
 - Hosted endpoints without repo-tracked standalone listing materials yet: Bilibili, Zhihu, X / Twitter, YouTube, TikTok, and Sensitive Words Check.
 - Unified MCP registry name: none; this package installs skills and calls explicit hosted MCP entries.
-- Current public capability version: `0.2.35`
+- Current public capability version: `0.2.36`
 
 ## Direct CLI
 
@@ -226,6 +226,7 @@ npx -y socialdatax-skills@latest x user-info --profile-url "<profile_url_or_shar
 npx -y socialdatax-skills@latest x user-posts --user-id "<user_id>" --pretty
 npx -y socialdatax-skills@latest x user-posts --username "<username>" --pretty
 npx -y socialdatax-skills@latest x user-posts --profile-url "<profile_url_or_share_text>" --pretty
+npx -y socialdatax-skills@latest x download-media --url "<x_media_url>" --output-dir ./downloads --pretty
 npx -y socialdatax-skills@latest youtube search --keyword "camping" --pretty
 npx -y socialdatax-skills@latest youtube detail --url "<youtube_video_url>" --pretty
 npx -y socialdatax-skills@latest youtube comments --url "<youtube_video_url>" --pretty
@@ -244,7 +245,7 @@ npx -y socialdatax-skills@latest tiktok user-posts --profile-url "<profile_url_o
 npx -y socialdatax-skills@latest sensitive-check text --text "<content>" --platform xhs --pretty
 ```
 
-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.
+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>`. `x download-media` accepts one X media URL returned by search or detail. These local commands write through a `.part` file, resume partial downloads when the server supports range requests, skip an already existing output file, and infer common image/video/audio extensions in `--output-dir` mode. X / Twitter media URLs are served from overseas CDN domains such as `pbs.twimg.com` and `video.twimg.com`; if the local download times out, enable a global/TUN/VPN proxy for the download process, then retry.
 
 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.
 
@@ -428,6 +429,7 @@ npx -y socialdatax-skills@latest wechat transcript --encrypted-object-id "<encry
 npx -y socialdatax-skills@latest zhihu search --keyword "露营" --pretty
 npx -y socialdatax-skills@latest instagram search --keyword "camping" --pretty
 npx -y socialdatax-skills@latest x search --keyword "camping" --pretty
+npx -y socialdatax-skills@latest x download-media --url "<x_media_url>" --output-dir ./downloads --pretty
 npx -y socialdatax-skills@latest youtube search --keyword "camping" --pretty
 npx -y socialdatax-skills@latest tiktok search --keyword "camping" --pretty
 npx -y socialdatax-skills@latest sensitive-check text --text "<content>" --platform xhs --pretty
@@ -570,6 +572,7 @@ Current X / Twitter workflows include:
 - Fetch paginated replies under a first-level comment by post_id and comment_id.
 - Read creator profile data by user_id, username, or profile URL/share text.
 - Fetch paginated public posts by creator user_id, username, or profile URL/share text.
+- Save returned `media_items[].cover_image_url` or `media_items[].video_url` media links locally with `x download-media`. Search results may already include these URLs; use detail as a fallback when search media fields are absent. If X CDN downloads time out, enable a global/TUN/VPN proxy for the download process and retry.
 
 Current YouTube workflows include:
 

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.35";
+const PACKAGE_VERSION = "0.2.36";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
 const LOG_PREFIX = `[${PACKAGE_NAME}]`;
 const MIN_NODE_VERSION = "20.18.1";
@@ -578,6 +578,7 @@ const X_DIRECT_ACTION_OPTIONS = {
     "maxItems",
     "pretty",
   ],
+  "download-media": ["url", "output", "outputDir", "pretty"],
 };
 const X_DIRECT_ACTION_NAMES = Object.keys(X_DIRECT_ACTION_OPTIONS).join(", ");
 const X_OPTION_DISPLAY_NAMES = {
@@ -593,6 +594,9 @@ const X_OPTION_DISPLAY_NAMES = {
   userId: "--user-id",
   username: "--username",
   profileUrl: "--profile-url",
+  url: "--url",
+  output: "--output",
+  outputDir: "--output-dir",
 };
 const X_SEARCH_SORT_TYPES = ["hot", "time_descending"];
 const YOUTUBE_DIRECT_ACTION_OPTIONS = {
@@ -2072,6 +2076,21 @@ function validateInstagramDirectActionOptions(action, options) {
 }
 
 function validateXDirectActionOptions(action, options) {
+  const allowedOptions = X_DIRECT_ACTION_OPTIONS[action];
+  if (!allowedOptions) {
+    return;
+  }
+
+  if (action === "download-media") {
+    validateDownloadMediaDirectActionOptions(
+      "x",
+      options,
+      allowedOptions,
+      X_OPTION_DISPLAY_NAMES
+    );
+    return;
+  }
+
   validateMcpDirectActionOptions(
     "x",
     action,
@@ -3023,6 +3042,9 @@ function printHelp() {
   console.log(`  npx -y ${PACKAGE_SPEC} x user-posts --username "<username>" --pretty`);
   console.log("      Call the X creator posts tool by username.");
   console.log("");
+  console.log(`  npx -y ${PACKAGE_SPEC} x download-media --url "<x_media_url>" --output-dir ./downloads --pretty`);
+  console.log("      Save one X image or video media URL returned by search or detail to a local file.");
+  console.log("");
   console.log(`  npx -y ${PACKAGE_SPEC} youtube search --keyword "camping" --pretty`);
   console.log("      Call the YouTube public video search tool directly and print JSON.");
   console.log("");
@@ -3130,6 +3152,7 @@ function printHelp() {
   console.log("  --url <url-or-share-text>");
   console.log("      Content link, short link, or share text for URL-based detail/comment/article commands.");
   console.log("      For xhs/douyin/kuaishou/weibo download-media, pass one media URL returned by detail.");
+  console.log("      For x download-media, pass one media URL returned by search or detail.");
   console.log("      For Douyin detail/comments, pass a content page link, not video.play_url.");
   console.log("  --media-url <video.video_url>");
   console.log("      WeChat detail result media URL for local decrypt-media download.");
@@ -3644,12 +3667,37 @@ async function runInstagramDirectCommand(args) {
 }
 
 async function runXDirectCommand(args) {
-  await runMcpDirectCommand(args, {
-    displayName: "X",
-    actionNames: X_DIRECT_ACTION_NAMES,
-    validateActionOptions: validateXDirectActionOptions,
-    buildOperation: buildXOperation,
-  });
+  const { options, positional } = parseCommandArgs(args);
+  if (shouldPrintDirectHelp(options, positional)) {
+    printHelp();
+    return;
+  }
+  const action = positional[0];
+  if (!action) {
+    throw new Error(`Missing X command. Use ${X_DIRECT_ACTION_NAMES}.`);
+  }
+  if (positional.length > 1) {
+    throw new Error(`Unexpected argument: ${positional[1]}`);
+  }
+  validateXDirectActionOptions(action, options);
+
+  if (action === "download-media") {
+    const data = await downloadPlatformMediaFromUrl("x", options.url, options);
+    process.stdout.write(JSON.stringify(data, null, options.pretty ? 2 : 0));
+    process.stdout.write("\n");
+    return;
+  }
+
+  const operation = attachDirectMetadata(buildXOperation(action, options), options);
+  const data = await callDirectOperationWithOptions(operation, options);
+  const envelope = {
+    platform: operation.platform.id,
+    tool: operation.tool,
+    arguments: operation.arguments,
+    data,
+  };
+  process.stdout.write(JSON.stringify(envelope, null, options.pretty ? 2 : 0));
+  process.stdout.write("\n");
 }
 
 async function runYoutubeDirectCommand(args) {

package/lib/media/platform-download.mjs

@@ -43,6 +43,11 @@ const PLATFORM_MEDIA_DOWNLOAD_CONFIGS = {
     displayName: "Weibo",
     referer: "https://weibo.com/",
   },
+  x: {
+    platform: "x",
+    displayName: "X / Twitter",
+    referer: "https://x.com/",
+  },
 };
 const MEDIA_DOWNLOAD_MAX_ATTEMPTS = 10;
 const MEDIA_DOWNLOAD_RETRY_DELAY_MS = 250;
@@ -221,7 +226,10 @@ async function downloadWithPartResume(
   }
 
   if (isAbortLikeError(lastError)) {
-    throw new Error(`${config.displayName} media download timed out.`);
+    throw new Error(formatPlatformMediaTimeoutMessage(config));
+  }
+  if (isNetworkLikeError(lastError)) {
+    throw new Error(formatPlatformMediaNetworkFailureMessage(config));
   }
   throw new Error(`${config.displayName} media download failed before completion.`);
 }
@@ -658,6 +666,28 @@ function isNetworkLikeError(error) {
   );
 }
 
+function formatPlatformMediaTimeoutMessage(config) {
+  if (config.platform === "x") {
+    return [
+      "X / Twitter media download timed out.",
+      "X media is served from overseas CDN domains such as pbs.twimg.com and video.twimg.com;",
+      "enable a global/TUN/VPN proxy for the download process, then retry.",
+    ].join(" ");
+  }
+  return `${config.displayName} media download timed out.`;
+}
+
+function formatPlatformMediaNetworkFailureMessage(config) {
+  if (config.platform === "x") {
+    return [
+      "X / Twitter media download could not reach the media CDN.",
+      "X media is served from overseas CDN domains such as pbs.twimg.com and video.twimg.com;",
+      "enable a global/TUN/VPN proxy for the download process, then retry.",
+    ].join(" ");
+  }
+  return `${config.displayName} media download failed before completion.`;
+}
+
 function isDownloadTooLargeError(error) {
   return error?.message === "Media download is too large for local media processing.";
 }
@@ -704,10 +734,14 @@ function inferUrlFormatExtension(parsedUrl) {
   const matched = /(?:^|[/?&])format\/([a-z0-9]+)(?:[/?&#]|$)/i.exec(
     `${parsedUrl.pathname}${parsedUrl.search}`
   );
-  if (!matched) {
-    return "";
+  if (matched) {
+    return MEDIA_URL_FORMAT_EXTENSIONS.get(sanitizeFileExtension(matched[1])) || "";
   }
-  return MEDIA_URL_FORMAT_EXTENSIONS.get(sanitizeFileExtension(matched[1])) || "";
+  return (
+    MEDIA_URL_FORMAT_EXTENSIONS.get(
+      sanitizeFileExtension(parsedUrl.searchParams.get("format"))
+    ) || ""
+  );
 }
 
 function isExistingOutputPathError(error) {

package/package.json

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

package/skills/media-detail/SKILL.md

@@ -163,7 +163,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 XHS, Douyin, Kuaishou, and Weibo local save commands write only to the requested local `--output` path or `--output-dir` directory and do 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.
+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, Douyin, Kuaishou, Weibo, and X / Twitter local save commands write only to the requested local `--output` path or `--output-dir` directory and do 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
 
@@ -224,6 +224,8 @@ When the user wants to save Douyin media after detail, pass each returned `image
 When the user wants to save Kuaishou media after detail, pass each returned `images[].url`, `video.play_url`, or `cover_image_url` to `npx -y socialdatax-skills@latest kuaishou download-media --url "<media_url>" --output-dir <directory> --pretty`; this local save command does not require `SOCIALDATAX_API_KEY`.
 For Bilibili detail, preserve returned content IDs and URLs because comments, replies, and article/dynamic reactions may need them.
 For Zhihu, Instagram, X / Twitter, YouTube, and TikTok detail results, keep the returned URL and public content ID values exactly as returned for follow-up comments or creator lookups.
+When the user wants to save X / Twitter media after search or detail, pass each returned `media_items[].cover_image_url` or `media_items[].video_url` to `npx -y socialdatax-skills@latest x download-media --url "<media_url>" --output-dir <directory> --pretty`; this local save command does not require `SOCIALDATAX_API_KEY`. Search results may already include these media URLs; use detail as a fallback when search media fields are absent.
+If an X / Twitter local media download times out, explain that X media is served from overseas CDN domains such as `pbs.twimg.com` and `video.twimg.com`; ask the user to enable a global/TUN/VPN proxy for the download process, then retry the same `x download-media` command.
 Detail access is read-only and does not provide account actions.
 For Weibo detail, include `post_id`, content, author, media, interaction counts, publish time, and post URL when available.
 When the user wants to save Weibo media after detail, pass each returned `image_urls[]` or `video.video_url` to `npx -y socialdatax-skills@latest weibo download-media --url "<media_url>" --output-dir <directory> --pretty`; this local save command does not require `SOCIALDATAX_API_KEY`.

package/skills/media-search/SKILL.md

@@ -272,7 +272,7 @@ Weibo and WeChat Channels search pagination:
 
 ## Safety Boundary
 
-This skill is read-only. 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.
+Search access is read-only. It uses `SOCIALDATAX_API_KEY` from the user's environment at runtime for SocialDataX search 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 X / Twitter local save command writes only to the requested local `--output` path or `--output-dir` directory 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
 
@@ -351,6 +351,7 @@ For Kuaishou search results, include `photo_id`, `share_url`, author facts, and
 For Bilibili search results, include content IDs, URLs, titles or descriptions, creator facts, and visible interaction counts when the user needs traceability.
 For Zhihu search results, include content URLs, titles or summaries, creator facts, and visible interaction counts when the user needs traceability.
 For Instagram, X / Twitter, YouTube, and TikTok search results, include returned post or video URLs, public IDs, author facts, and visible interaction counts when the user needs traceability.
+For X / Twitter search results, preserve returned `media_items[].cover_image_url` and `media_items[].video_url` values when present. When the user wants to save X media, pass one returned media URL at a time to `npx -y socialdatax-skills@latest x download-media --url "<media_url>" --output-dir <directory> --pretty`; this local save command does not require `SOCIALDATAX_API_KEY`. If search media fields are absent, use X detail as the fallback before downloading.
 For Weibo search results, include `post_id`, `post_url`, author facts, interaction counts, and publish time when the user needs traceability.
 For WeChat Channels / 视频号 search results, include `encrypted_object_id`, author facts, interaction counts, publish time, and duration when the user needs traceability.