socialdatax-skills 0.2.36 → 0.2.37

package/CATALOG.md

@@ -6,7 +6,7 @@ Official website and API Key access: <https://socialdatax.com/ai?from=github>
 
 ## Quick Start
 
-Set your API Key in the environment:
+For installed AI clients, persist `SOCIALDATAX_API_KEY` in the client Secret or user environment. The `export` below is only for a one-off shell run:
 
 ```bash
 export SOCIALDATAX_API_KEY="<your_api_key>"

package/README.md

@@ -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.36`
+- Current public capability version: `0.2.37`
 
 ## Direct CLI
 
@@ -245,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>`. `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.
+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, make the CLI process use a proxy with `--proxy "http://127.0.0.1:7890"` or `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY`, 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.
 
@@ -333,7 +333,7 @@ npx -y socialdatax-skills@latest doctor
 npx -y socialdatax-skills@latest doctor --json
 ```
 
-The public package declares no npm lifecycle scripts such as `preinstall`, `install`, or `postinstall`. The installer copies AgentSkills files only, does not save API keys, and does not change MCP server configuration. Authenticated data calls require `SOCIALDATAX_API_KEY` at runtime, do not read local browser data, and do not perform account actions.
+The public package declares no npm lifecycle scripts such as `preinstall`, `install`, or `postinstall`. The installer copies Skill files only, does not save API keys, and does not change MCP server configuration. Authenticated data calls require `SOCIALDATAX_API_KEY` at runtime, do not read local browser data, and do not perform account actions.
 
 ## Platform Names
 
@@ -404,6 +404,8 @@ npx -y socialdatax-skills@latest install media-search --target codex
 npx -y socialdatax-skills@latest install media-search --target codex --scope workspace
 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 install --path ~/.workbuddy/skills/
+npx -y socialdatax-skills@latest install media-search --path ~/.workbuddy/skills/media-search
 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
@@ -457,6 +459,7 @@ Default install locations:
 - Codex workspace scope: `./.codex/skills/<skill-name>`
 - Claude Code: `~/.claude/skills/<skill-name>`
 - Claude Code workspace scope: `./.claude/skills/<skill-name>`
+- WorkBuddy: use `--path` with the Skills directory supported by your current WorkBuddy client, for example `npx -y socialdatax-skills@latest install --path ~/.workbuddy/skills/`
 
 If no skill name is provided, all skills are installed. If a destination already exists, re-run with `--force` to replace an existing directory for the same skill. Use `--path <directory>` to install one skill to a custom directory, or multiple skills under a custom parent directory. The `shared` scope is only meaningful for `--target hermes`; use `--target agents` for the shared AgentSkills directory directly.
 
@@ -572,7 +575,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.
+- 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, make the CLI process use a proxy with `--proxy "http://127.0.0.1:7890"` or `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY`, then retry.
 
 Current YouTube workflows include:
 
@@ -804,6 +807,8 @@ Current Sensitive Words Check workflows include:
 
 For agents that can execute shell commands, use the direct CLI. This is the recommended default for installed skills:
 
+For installed AI clients, persist `SOCIALDATAX_API_KEY` in the client Secret or user environment. The `export` below is only for a one-off shell run.
+
 ```bash
 export SOCIALDATAX_API_KEY="<SOCIALDATAX_API_KEY>"
 npx -y socialdatax-skills@latest xhs search --keyword "露营" --pretty

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.36";
+const PACKAGE_VERSION = "0.2.37";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
 const LOG_PREFIX = `[${PACKAGE_NAME}]`;
 const MIN_NODE_VERSION = "20.18.1";
@@ -172,7 +172,7 @@ const XHS_DIRECT_ACTION_OPTIONS = {
     "pretty",
   ],
   transcript: ["url", "noteId", "jobId", "maxWaitSeconds", "pretty"],
-  "download-media": ["url", "output", "outputDir", "pretty"],
+  "download-media": ["url", "output", "outputDir", "proxy", "pretty"],
 };
 const XHS_DIRECT_ACTION_NAMES = Object.keys(XHS_DIRECT_ACTION_OPTIONS).join(", ");
 const XHS_OPTION_DISPLAY_NAMES = {
@@ -195,6 +195,7 @@ const XHS_OPTION_DISPLAY_NAMES = {
   maxWaitSeconds: "--max-wait-seconds",
   output: "--output",
   outputDir: "--output-dir",
+  proxy: "--proxy",
 };
 const XHS_SEARCH_SORT_TYPES = [
   "general",
@@ -262,7 +263,7 @@ const DOUYIN_DIRECT_ACTION_OPTIONS = {
   ],
   "user-series": ["secUserId", "profileUrl", "pageToken", "pages", "all", "maxItems", "pretty"],
   transcript: ["url", "awemeId", "jobId", "maxWaitSeconds", "pretty"],
-  "download-media": ["url", "output", "outputDir", "pretty"],
+  "download-media": ["url", "output", "outputDir", "proxy", "pretty"],
 };
 const DOUYIN_DIRECT_ACTION_NAMES = Object.keys(DOUYIN_DIRECT_ACTION_OPTIONS).join(", ");
 const DOUYIN_SEARCH_SORT_TYPES = ["general", "time_descending", "like_count_descending"];
@@ -295,6 +296,7 @@ const DOUYIN_OPTION_DISPLAY_NAMES = {
   maxWaitSeconds: "--max-wait-seconds",
   output: "--output",
   outputDir: "--output-dir",
+  proxy: "--proxy",
 };
 const KUAISHOU_DIRECT_ACTION_OPTIONS = {
   "hot-search": ["pretty"],
@@ -333,7 +335,7 @@ const KUAISHOU_DIRECT_ACTION_OPTIONS = {
     "pretty",
   ],
   transcript: ["url", "photoId", "jobId", "maxWaitSeconds", "pretty"],
-  "download-media": ["url", "output", "outputDir", "pretty"],
+  "download-media": ["url", "output", "outputDir", "proxy", "pretty"],
 };
 const KUAISHOU_DIRECT_ACTION_NAMES = Object.keys(KUAISHOU_DIRECT_ACTION_OPTIONS).join(", ");
 const KUAISHOU_OPTION_DISPLAY_NAMES = {
@@ -353,6 +355,7 @@ const KUAISHOU_OPTION_DISPLAY_NAMES = {
   maxWaitSeconds: "--max-wait-seconds",
   output: "--output",
   outputDir: "--output-dir",
+  proxy: "--proxy",
 };
 const BILIBILI_DIRECT_ACTION_OPTIONS = {
   "search-videos": [
@@ -578,7 +581,7 @@ const X_DIRECT_ACTION_OPTIONS = {
     "maxItems",
     "pretty",
   ],
-  "download-media": ["url", "output", "outputDir", "pretty"],
+  "download-media": ["url", "output", "outputDir", "proxy", "pretty"],
 };
 const X_DIRECT_ACTION_NAMES = Object.keys(X_DIRECT_ACTION_OPTIONS).join(", ");
 const X_OPTION_DISPLAY_NAMES = {
@@ -597,6 +600,7 @@ const X_OPTION_DISPLAY_NAMES = {
   url: "--url",
   output: "--output",
   outputDir: "--output-dir",
+  proxy: "--proxy",
 };
 const X_SEARCH_SORT_TYPES = ["hot", "time_descending"];
 const YOUTUBE_DIRECT_ACTION_OPTIONS = {
@@ -724,7 +728,7 @@ const WEIBO_DIRECT_ACTION_OPTIONS = {
     "pretty",
   ],
   transcript: ["postUrl", "postId", "jobId", "maxWaitSeconds", "pretty"],
-  "download-media": ["url", "output", "outputDir", "pretty"],
+  "download-media": ["url", "output", "outputDir", "proxy", "pretty"],
 };
 const WEIBO_DIRECT_ACTION_NAMES = Object.keys(WEIBO_DIRECT_ACTION_OPTIONS).join(", ");
 const WEIBO_OPTION_DISPLAY_NAMES = {
@@ -745,6 +749,7 @@ const WEIBO_OPTION_DISPLAY_NAMES = {
   url: "--url",
   output: "--output",
   outputDir: "--output-dir",
+  proxy: "--proxy",
 };
 const WECHAT_DIRECT_ACTION_OPTIONS = {
   "hot-search": ["pretty"],
@@ -1741,11 +1746,66 @@ async function main() {
       process.exitCode = 1;
     }
   } catch (error) {
-    console.error(`${LOG_PREFIX} ${error.message}`);
+    console.error(`${LOG_PREFIX} ${formatCliErrorMessage(error)}`);
     process.exit(1);
   }
 }
 
+export function formatCliErrorMessage(error) {
+  const message = error?.message || String(error);
+  if (error?.structuredContent) {
+    return message;
+  }
+  if (isLocalDependencyInstallError(message)) {
+    return `${message}
+Local dependency/runtime/network/authorization issue, not a SocialDataX API key or business data error: install or restore the required CLI dependencies or Node.js runtime when missing, allow node/npm/npx and npm registry access, allow required local file or directory permissions, then retry the same command. 本地依赖/运行环境/网络/授权问题，不是 SocialDataX API Key 或业务数据返回错误：缺少依赖或 node/npm/npx 时请安装或启用当前 CLI 所需依赖/运行时；已有环境时允许当前 Agent 运行 node/npm/npx、访问 npm registry 和目标文件或目录权限，然后重试原命令；不要改用公开网页搜索替代 SocialDataX 数据。`;
+  }
+  return message;
+}
+
+function isLocalDependencyInstallError(message) {
+  if (isWrappedSocialDataxDirectCallError(message)) {
+    return false;
+  }
+
+  return (
+    isMissingNodeDependencyError(message) ||
+    /Node\.js \d+\.\d+\.\d+ or newer is required/i.test(message) ||
+    isLocalFilesystemPermissionError(message) ||
+    /npm ERR!.*\bENOTFOUND\b/i.test(message) ||
+    (/\bENOSPC\b/i.test(message) &&
+      /(?:npm|npx|socialdatax-skills|node_modules)/i.test(message)) ||
+    (/\b(?:ENOTFOUND|EAI_AGAIN|ECONNRESET|ECONNREFUSED|ETIMEDOUT)\b/.test(message) &&
+      /(?:npm|registry\.npmjs\.org|npm registry)/i.test(message)) ||
+    (/(?:npm|registry\.npmjs\.org|npm registry)/i.test(message) &&
+      /\b(?:E401|E403|401|403|SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_VERIFY_LEAF_SIGNATURE|CERT_HAS_EXPIRED|certificate)\b/i.test(message)) ||
+    /\bnpx\b.*(?:EACCES|EPERM|ENOENT|permission|denied|not found|被拒绝)/i.test(message) ||
+    /(?:EACCES|EPERM|ENOENT|permission|denied|not found|被拒绝).*\bnpx\b/i.test(message) ||
+    /\bnpm\b.*(?:EACCES|EPERM|permission|denied|被拒绝)/i.test(message)
+  );
+}
+
+function isLocalFilesystemPermissionError(message) {
+  return (
+    /\b(?:EACCES|EPERM)\b/i.test(message) &&
+    /(?:permission|denied|operation not permitted|mkdir|open|copyfile|cp|scandir|rename|unlink|rmdir)/i.test(message) &&
+    !/https?:\/\//i.test(message)
+  );
+}
+
+function isWrappedSocialDataxDirectCallError(message) {
+  return /Direct CLI call failed[\s\S]* at https?:\/\/\S+/i.test(message);
+}
+
+function isMissingNodeDependencyError(message) {
+  return (
+    /Cannot find (?:package|module)/i.test(message) &&
+    (/(?:imported from|ERR_MODULE_NOT_FOUND)[\s\S]*(?:cli\.mjs|socialdatax-skills|node_modules)/i.test(message) ||
+      /Cannot find module ['"][^'"]*node_modules[\\/]/i.test(message) ||
+      /Require stack:[\s\S]*(?:cli\.mjs|socialdatax-skills)/i.test(message))
+  );
+}
+
 function parseCommandArgs(args) {
   const options = {};
   const positional = [];
@@ -2348,6 +2408,15 @@ function expandHome(path) {
   if (path.startsWith("~/")) {
     return join(homedir(), path.slice(2));
   }
+  if (path.startsWith("~\\")) {
+    return join(
+      homedir(),
+      ...path
+        .slice(2)
+        .split(/[\\/]+/)
+        .filter(Boolean)
+    );
+  }
   return path;
 }
 
@@ -2493,11 +2562,13 @@ async function installSkills(args) {
   console.log("No MCP server setup is required for the bundled skills.");
   console.log("No API key was stored by this installer.");
   console.log("No MCP server configuration was changed.");
-  console.log("Installed files are AgentSkills files only.");
+  console.log("Installed files are Skill files only.");
   console.log(`Authenticated data calls require ${PRIMARY_API_KEY_ENV} at runtime.`);
   console.log("Data calls do not perform login, posting, editing, liking, commenting, or account actions.");
   console.log("Configure your API Key before making authenticated calls:");
-  console.log(`  export ${PRIMARY_API_KEY_ENV}="<${PRIMARY_API_KEY_ENV}>"`);
+  console.log(
+    `  Persist ${PRIMARY_API_KEY_ENV} in the target AI client Secret or user environment; do not rely on a temporary shell export.`
+  );
   printInstalledSkillAttributionNote();
 }
 
@@ -2516,7 +2587,7 @@ function resolveInstallDestination({
   path,
   usePathAsParent,
 }) {
-  const customPath = path && usePathAsParent ? join(path, skillName) : path;
+  const customPath = path && usePathAsParent ? join(expandHome(path), skillName) : path;
   return resolveInstallDir({
     target,
     scope,
@@ -2652,7 +2723,7 @@ function buildDoctorReport() {
       recommendedNode: "22 LTS or newer",
     },
     install: {
-      writes: "AgentSkills directories only",
+      writes: "Skill files only",
       apiKeyStored: false,
       mcpConfigChanged: false,
       supportsDryRun: true,
@@ -2696,7 +2767,7 @@ function printDoctor(args) {
   console.log("");
   console.log("Install safety:");
   console.log("- npm lifecycle scripts: none declared by this package.");
-  console.log("- install writes AgentSkills files only.");
+  console.log("- install writes Skill files only.");
   console.log("- install does not store API keys.");
   console.log("- install does not change MCP server configuration.");
   console.log("- install --dry-run previews destinations without writing files.");
@@ -3144,6 +3215,14 @@ function printHelp() {
   );
   console.log("      Install one skill to ./.claude/skills.");
   console.log("");
+  console.log(`  npx -y ${PACKAGE_SPEC} install --path ~/.workbuddy/skills/`);
+  console.log("      Install all skills under a custom WorkBuddy Skills parent directory.");
+  console.log("");
+  console.log(
+    `  npx -y ${PACKAGE_SPEC} install media-search --path ~/.workbuddy/skills/media-search`
+  );
+  console.log("      Install one skill to a direct custom Skills directory.");
+  console.log("");
   console.log("Available skills:");
   console.log(`  ${AVAILABLE_SKILL_NAMES.join(", ")}`);
   console.log("");
@@ -3160,6 +3239,8 @@ function printHelp() {
   console.log("      Output file path for local decrypt-media, download-media, or Bilibili download.");
   console.log("  --output-dir <directory>");
   console.log("      Directory for download-media or Bilibili download output when --output is omitted.");
+  console.log("  --proxy <http-or-https-proxy-url>");
+  console.log("      Proxy for local download-media requests; otherwise HTTPS_PROXY, HTTP_PROXY, or ALL_PROXY is used when set.");
   console.log("  --ffmpeg-path <path>");
   console.log("      ffmpeg executable path for Bilibili download; defaults to ffmpeg.");
   console.log("  --keep-tracks");
@@ -3273,7 +3354,8 @@ function printHelp() {
   console.log("  --target <openclaw|hermes|agents|codex|claude-code|claude>");
   console.log("      For install.");
   console.log("  --scope <user|workspace|shared>  shared is only for --target hermes.");
-  console.log("  --path <directory>   Override install destination.");
+  console.log("  --path <directory>");
+  console.log("      For install. Multiple/all skills: parent directory; one skill: skill destination directory.");
   console.log("  --dry-run           Preview install without writing files.");
   console.log("  --force              Replace an existing directory for the same skill.");
 }
@@ -3346,7 +3428,9 @@ async function runXhsDirectCommand(args) {
   validateXhsDirectActionOptions(action, options);
 
   if (action === "download-media") {
-    const data = await downloadPlatformMediaFromUrl("xhs", options.url, options);
+    const data = await downloadPlatformMediaFromUrl("xhs", options.url, options, {
+      env: process.env,
+    });
     process.stdout.write(JSON.stringify(data, null, options.pretty ? 2 : 0));
     process.stdout.write("\n");
     return;
@@ -3382,7 +3466,9 @@ async function runDouyinDirectCommand(args) {
   validateDouyinDirectActionOptions(action, options);
 
   if (action === "download-media") {
-    const data = await downloadPlatformMediaFromUrl("douyin", options.url, options);
+    const data = await downloadPlatformMediaFromUrl("douyin", options.url, options, {
+      env: process.env,
+    });
     process.stdout.write(JSON.stringify(data, null, options.pretty ? 2 : 0));
     process.stdout.write("\n");
     return;
@@ -3418,7 +3504,9 @@ async function runKuaishouDirectCommand(args) {
   validateKuaishouDirectActionOptions(action, options);
 
   if (action === "download-media") {
-    const data = await downloadPlatformMediaFromUrl("kuaishou", options.url, options);
+    const data = await downloadPlatformMediaFromUrl("kuaishou", options.url, options, {
+      env: process.env,
+    });
     process.stdout.write(JSON.stringify(data, null, options.pretty ? 2 : 0));
     process.stdout.write("\n");
     return;
@@ -3564,7 +3652,9 @@ async function runWeiboDirectCommand(args) {
   validateWeiboDirectActionOptions(action, options);
 
   if (action === "download-media") {
-    const data = await downloadPlatformMediaFromUrl("weibo", options.url, options);
+    const data = await downloadPlatformMediaFromUrl("weibo", options.url, options, {
+      env: process.env,
+    });
     process.stdout.write(JSON.stringify(data, null, options.pretty ? 2 : 0));
     process.stdout.write("\n");
     return;
@@ -3682,7 +3772,9 @@ async function runXDirectCommand(args) {
   validateXDirectActionOptions(action, options);
 
   if (action === "download-media") {
-    const data = await downloadPlatformMediaFromUrl("x", options.url, options);
+    const data = await downloadPlatformMediaFromUrl("x", options.url, options, {
+      env: process.env,
+    });
     process.stdout.write(JSON.stringify(data, null, options.pretty ? 2 : 0));
     process.stdout.write("\n");
     return;

package/lib/media/platform-download.mjs

@@ -10,6 +10,8 @@ import {
 import { homedir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 
+import { ProxyAgent } from "undici";
+
 import {
   MEDIA_DOWNLOAD_MAX_BYTES,
   MEDIA_DOWNLOAD_TIMEOUT_MS,
@@ -82,6 +84,10 @@ const MEDIA_URL_FORMAT_EXTENSIONS = new Map([
   ["mp4", "mp4"],
   ["m4a", "m4a"],
 ]);
+const MEDIA_DOWNLOAD_PROXY_ENV_BY_PROTOCOL = {
+  "http:": ["HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy"],
+  "https:": ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy"],
+};
 export async function downloadPlatformMediaFromUrl(
   platform,
   url,
@@ -94,6 +100,7 @@ export async function downloadPlatformMediaFromUrl(
     now = () => new Date(),
     linkFile = linkPath,
     copyFile = copyFilePath,
+    env = {},
   } = {}
 ) {
   const config = resolvePlatformMediaDownloadConfig(platform);
@@ -111,16 +118,27 @@ export async function downloadPlatformMediaFromUrl(
       existingOutput.size
     );
   }
-
-  return downloadWithPartResume(parsedUrl, target, {
+  const proxyDispatcher = createMediaDownloadProxyDispatcher(parsedUrl, options, {
     config,
-    fetchMedia,
-    downloadTimeoutMs,
-    maxDownloadBytes,
-    retryDelayMs,
-    linkFile,
-    copyFile,
+    env,
   });
+
+  try {
+    return await downloadWithPartResume(parsedUrl, target, {
+      config,
+      fetchMedia,
+      downloadTimeoutMs,
+      maxDownloadBytes,
+      retryDelayMs,
+      proxyDispatcher,
+      linkFile,
+      copyFile,
+    });
+  } finally {
+    if (proxyDispatcher) {
+      await proxyDispatcher.close().catch(ignoreError);
+    }
+  }
 }
 
 async function resolvePlatformMediaTarget(parsedUrl, options = {}, now, config) {
@@ -177,6 +195,7 @@ async function downloadWithPartResume(
     downloadTimeoutMs,
     maxDownloadBytes,
     retryDelayMs,
+    proxyDispatcher,
     linkFile,
     copyFile,
   }
@@ -189,6 +208,7 @@ async function downloadWithPartResume(
         fetchMedia,
         downloadTimeoutMs,
         maxDownloadBytes,
+        proxyDispatcher,
         linkFile,
         copyFile,
       });
@@ -242,6 +262,7 @@ async function downloadOnce(
     fetchMedia,
     downloadTimeoutMs,
     maxDownloadBytes,
+    proxyDispatcher,
     linkFile,
     copyFile,
   }
@@ -260,6 +281,7 @@ async function downloadOnce(
   const response = await fetchMedia(parsedUrl.href, {
     headers,
     ...(signal ? { signal } : {}),
+    ...(proxyDispatcher ? { dispatcher: proxyDispatcher } : {}),
   });
 
   if (MEDIA_EXPIRED_HTTP_STATUSES.has(response.status)) {
@@ -544,6 +566,53 @@ function parseHttpUrl(value, config) {
   return parsed;
 }
 
+function createMediaDownloadProxyDispatcher(parsedUrl, options, { config, env }) {
+  const proxyUrl = resolveMediaDownloadProxyUrl(parsedUrl, options, {
+    config,
+    env,
+  });
+  return proxyUrl ? new ProxyAgent(proxyUrl) : undefined;
+}
+
+function resolveMediaDownloadProxyUrl(parsedUrl, options = {}, { config, env }) {
+  if (options.proxy !== undefined) {
+    return normalizeMediaDownloadProxyUrl(options.proxy, "--proxy", config);
+  }
+  const envName = MEDIA_DOWNLOAD_PROXY_ENV_BY_PROTOCOL[parsedUrl.protocol]?.find(
+    (name) => normalizeOptionalString(env?.[name])
+  );
+  if (!envName) {
+    return "";
+  }
+  return normalizeMediaDownloadProxyUrl(env[envName], envName, config);
+}
+
+function normalizeMediaDownloadProxyUrl(value, displayName, config) {
+  const normalized = normalizeOptionalString(value);
+  if (!normalized) {
+    return "";
+  }
+  let parsed;
+  try {
+    parsed = new URL(normalized);
+  } catch {
+    throw new Error(
+      `${displayName} must be an HTTP or HTTPS proxy URL for ${config.platform} download-media.`
+    );
+  }
+  if (!["http:", "https:"].includes(parsed.protocol) || !parsed.hostname) {
+    throw new Error(
+      `${displayName} must be an HTTP or HTTPS proxy URL for ${config.platform} download-media.`
+    );
+  }
+  return parsed.href;
+}
+
+function normalizeOptionalString(value) {
+  const normalized = String(value ?? "").trim();
+  return normalized === "" ? "" : normalized;
+}
+
 function normalizePlatformDownloadHeaders(config) {
   return {
     "User-Agent": MEDIA_DOWNLOAD_USER_AGENT,
@@ -671,7 +740,7 @@ function formatPlatformMediaTimeoutMessage(config) {
     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.",
+      "make the CLI process use a proxy with --proxy \"http://127.0.0.1:7890\" or HTTP_PROXY / HTTPS_PROXY / ALL_PROXY, then retry.",
     ].join(" ");
   }
   return `${config.displayName} media download timed out.`;
@@ -682,7 +751,7 @@ function formatPlatformMediaNetworkFailureMessage(config) {
     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.",
+      "make the CLI process use a proxy with --proxy \"http://127.0.0.1:7890\" or HTTP_PROXY / HTTPS_PROXY / ALL_PROXY, then retry.",
     ].join(" ");
   }
   return `${config.displayName} media download failed before completion.`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "socialdatax-skills",
-  "version": "0.2.36",
+  "version": "0.2.37",
   "description": "SocialDataX / 社媒数据助手 skill installer and direct CLI helper for hosted MCP services.",
   "license": "MIT",
   "type": "module",
@@ -95,7 +95,8 @@
     "node": ">=20.18.1"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "undici": "^7.29.0"
   },
   "overrides": {
     "hono": "4.12.27",

package/skills/media-comments/SKILL.md

@@ -320,6 +320,7 @@ For Weibo and WeChat Channels / 视频号 comments, preserve returned content ID
 
 ## Troubleshooting
 
+- If an SDK/dependency, npm network, Node.js/npm/npx availability, permission, or missing runtime error appears, treat it as a local runtime, dependency installation, network, or agent authorization issue, not a SocialDataX API key or business data error. If the current environment has permission, install or restore automatically. When network or execution authorization is needed, ask the user to approve or finish authorization, then continue the same command; do not use public web search as a substitute for SocialDataX data.
 - For non-balance network or API errors, preserve the error message, check `SOCIALDATAX_API_KEY`, parameters, and link or ID format, then retry once when appropriate.
 - If the response returns `insufficient_balance` or says the balance/credits are insufficient, do not retry repeatedly. Show the recharge URL from the error exactly as returned, then continue the same command after the user recharges.
 - If the user has recharged but still sees insufficient balance, confirm `SOCIALDATAX_API_KEY` belongs to the same account that was recharged; if needed, copy a fresh API Key from the official dashboard.

package/skills/media-detail/SKILL.md

@@ -225,7 +225,7 @@ When the user wants to save Kuaishou media after detail, pass each returned `ima
 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.
+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 make the download process use their proxy, for example by adding `--proxy "http://127.0.0.1:7890"` or setting `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY`, 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`.
@@ -235,6 +235,7 @@ For WeChat Official Account / 微信公众号 article detail, include article ti
 
 ## Troubleshooting
 
+- If an SDK/dependency, npm network, Node.js/npm/npx availability, permission, or missing runtime error appears, treat it as a local runtime, dependency installation, network, or agent authorization issue, not a SocialDataX API key or business data error. If the current environment has permission, install or restore automatically. When network or execution authorization is needed, ask the user to approve or finish authorization, then continue the same command; do not use public web search as a substitute for SocialDataX data.
 - For non-balance network or API errors, preserve the error message, check `SOCIALDATAX_API_KEY`, parameters, and link or ID format, then retry once when appropriate.
 - If the response returns `insufficient_balance` or says the balance/credits are insufficient, do not retry repeatedly. Show the recharge URL from the error exactly as returned, then continue the same command after the user recharges.
 - If the user has recharged but still sees insufficient balance, confirm `SOCIALDATAX_API_KEY` belongs to the same account that was recharged; if needed, copy a fresh API Key from the official dashboard.

package/skills/media-search/SKILL.md

@@ -351,12 +351,13 @@ 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 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 the CLI process does not inherit the user's local proxy, add `--proxy "http://127.0.0.1:7890"` or set `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY`. 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.
 
 ## Troubleshooting
 
+- If an SDK/dependency, npm network, Node.js/npm/npx availability, permission, or missing runtime error appears, treat it as a local runtime, dependency installation, network, or agent authorization issue, not a SocialDataX API key or business data error. If the current environment has permission, install or restore automatically. When network or execution authorization is needed, ask the user to approve or finish authorization, then continue the same command; do not use public web search as a substitute for SocialDataX data.
 - For non-balance network or API errors, preserve the error message, check `SOCIALDATAX_API_KEY`, parameters, and link or ID format, then retry once when appropriate.
 - If the response returns `insufficient_balance` or says the balance/credits are insufficient, do not retry repeatedly. Show the recharge URL from the error exactly as returned, then continue the same command after the user recharges.
 - If the user has recharged but still sees insufficient balance, confirm `SOCIALDATAX_API_KEY` belongs to the same account that was recharged; if needed, copy a fresh API Key from the official dashboard.

package/skills/media-transcript/SKILL.md

@@ -166,6 +166,7 @@ If the result says no processable video resource is available or the job failed,
 
 ## Troubleshooting
 
+- If an SDK/dependency, npm network, Node.js/npm/npx availability, permission, or missing runtime error appears, treat it as a local runtime, dependency installation, network, or agent authorization issue, not a SocialDataX API key or business data error. If the current environment has permission, install or restore automatically. When network or execution authorization is needed, ask the user to approve or finish authorization, then continue the same command; do not use public web search as a substitute for SocialDataX data.
 - If the response returns `insufficient_balance` or says the balance/credits are insufficient, do not submit another job or keep polling. Show the recharge URL from the error exactly as returned, then continue the same command after the user recharges.
 - If the user has recharged but still sees insufficient balance, confirm `SOCIALDATAX_API_KEY` belongs to the same account that was recharged; if needed, copy a fresh API Key from the official dashboard.
 - If a transcript `job_id` already exists, only check that same job; do not submit the video again.

package/skills/media-user-info/SKILL.md

@@ -227,6 +227,7 @@ For YouTube, report channel profile facts separately from video-list evidence.
 
 ## Troubleshooting
 
+- If an SDK/dependency, npm network, Node.js/npm/npx availability, permission, or missing runtime error appears, treat it as a local runtime, dependency installation, network, or agent authorization issue, not a SocialDataX API key or business data error. If the current environment has permission, install or restore automatically. When network or execution authorization is needed, ask the user to approve or finish authorization, then continue the same command; do not use public web search as a substitute for SocialDataX data.
 - For non-balance network or API errors, preserve the error message, check `SOCIALDATAX_API_KEY`, parameters, and link or ID format, then retry once when appropriate.
 - If the response returns `insufficient_balance` or says the balance/credits are insufficient, do not retry repeatedly. Show the recharge URL from the error exactly as returned, then continue the same command after the user recharges.
 - If the user has recharged but still sees insufficient balance, confirm `SOCIALDATAX_API_KEY` belongs to the same account that was recharged; if needed, copy a fresh API Key from the official dashboard.

package/skills/media-user-posts/SKILL.md

@@ -315,6 +315,7 @@ For WeChat Channels / 视频号 creator videos, report object IDs, descriptions,
 
 ## Troubleshooting
 
+- If an SDK/dependency, npm network, Node.js/npm/npx availability, permission, or missing runtime error appears, treat it as a local runtime, dependency installation, network, or agent authorization issue, not a SocialDataX API key or business data error. If the current environment has permission, install or restore automatically. When network or execution authorization is needed, ask the user to approve or finish authorization, then continue the same command; do not use public web search as a substitute for SocialDataX data.
 - For non-balance network or API errors, preserve the error message, check `SOCIALDATAX_API_KEY`, parameters, and link or ID format, then retry once when appropriate.
 - If the response returns `insufficient_balance` or says the balance/credits are insufficient, do not retry repeatedly. Show the recharge URL from the error exactly as returned, then continue the same command after the user recharges.
 - If the user has recharged but still sees insufficient balance, confirm `SOCIALDATAX_API_KEY` belongs to the same account that was recharged; if needed, copy a fresh API Key from the official dashboard.

package/skills/sensitive-check/SKILL.md

@@ -79,6 +79,7 @@ Do not echo the full original text back unless the user explicitly asks; prefer
 
 ## Troubleshooting
 
+- If an SDK/dependency, npm network, Node.js/npm/npx availability, permission, or missing runtime error appears, treat it as a local runtime, dependency installation, network, or agent authorization issue, not a SocialDataX API key or business data error. If the current environment has permission, install or restore automatically. When network or execution authorization is needed, ask the user to approve or finish authorization, then continue the same command; do not use public web search as a substitute for SocialDataX data.
 - For non-balance network or API errors, preserve the error message, check `SOCIALDATAX_API_KEY`, parameters, and link or ID format, then retry once when appropriate.
 - If the response returns `insufficient_balance` or says the balance/credits are insufficient, do not retry repeatedly. Show the recharge URL from the error exactly as returned, then continue the same command after the user recharges.
 - If the user has recharged but still sees insufficient balance, confirm `SOCIALDATAX_API_KEY` belongs to the same account that was recharged; if needed, copy a fresh API Key from the official dashboard.

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

@@ -345,6 +345,7 @@ For hot-search, report ranking signals separately from keyword search results.
 
 ## Troubleshooting
 
+- If an SDK/dependency, npm network, Node.js/npm/npx availability, permission, or missing runtime error appears, treat it as a local runtime, dependency installation, network, or agent authorization issue, not a SocialDataX API key or business data error. If the current environment has permission, install or restore automatically. When network or execution authorization is needed, ask the user to approve or finish authorization, then continue the same command; do not use public web search as a substitute for SocialDataX data.
 - For non-balance, non-rate-limit network or API errors, preserve the error message, check `SOCIALDATAX_API_KEY`, parameters, and link or ID format, then retry once when appropriate.
 - If the response returns `insufficient_balance` or says the balance/credits are insufficient, do not retry repeatedly. Show the recharge URL from the error exactly as returned, then continue the same command after the user recharges.
 - If the user has recharged but still sees insufficient balance, confirm `SOCIALDATAX_API_KEY` belongs to the same account that was recharged; if needed, copy a fresh API Key from the official dashboard.