socialdatax-skills 0.2.25 → 0.2.27

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, 微博 / Weibo, 视频号 / WeChat Channels, and 微信公众号 / WeChat Official Account article content research and analysis workflows, plus Bilibili / 哔哩哔哩 / B站 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, 微博 / Weibo, 视频号 / WeChat Channels, and 微信公众号 / WeChat Official Account article content research and analysis workflows, plus XHS local media download, Bilibili / 哔哩哔哩 / B站 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
@@ -28,6 +28,9 @@ Common search phrases for this skill package:
 - `Xiaohongshu skills`
 - `XHS skills`
 - `RedNote skills`
+- `XHS media download`
+- `小红书图片下载`
+- `小红书视频下载`
 - `Douyin skills`
 - `抖音 skills`
 - `Kuaishou skills`
@@ -79,7 +82,7 @@ Common search phrases for this skill package:
 - Sensitive Words Check MCP server name: `sensitive-check`
 - Sensitive Words Check future MCP registry name: `com.socialdatax/sensitive-check`
 - Unified MCP registry name: none; this package installs skills and calls explicit platform services.
-- Current public capability version: `0.2.25`
+- Current public capability version: `0.2.27`
 
 ## Direct CLI
 
@@ -102,6 +105,7 @@ npx -y socialdatax-skills@latest xhs user-posts --user-id "<user_id>" --since-da
 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 xhs download-media --url "<xhs_media_url>" --output-dir ./downloads --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
@@ -170,7 +174,7 @@ 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
 ```
 
-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`.
+Most direct CLI commands print a JSON envelope with `platform`, `tool`, `arguments`, and `data`. `sensitive-check` prints `platform`, `tool`, and `data` only; it does not echo the original text in CLI output. `wechat decrypt-media` is a local save command: pass the `video.video_url` returned by WeChat detail and an `--output` file path. It saves the media locally, decrypts when needed, and does not require `SOCIALDATAX_API_KEY`. `xhs download-media` is also local: pass one image or video media URL returned by XHS detail and either `--output <file>` or `--output-dir <directory>`. It writes through a `.part` file, resumes partial downloads when the server supports range requests, skips an already existing output file, and infers common image/video extensions in `--output-dir` mode.
 
 `bilibili download` calls SocialDataX once to fetch short-lived download links, then downloads video and audio tracks on the local machine and merges them with local `ffmpeg`. Set `SOCIALDATAX_API_KEY`, install `ffmpeg`, and pass either `--output <file>` or `--output-dir <directory>`. The download-links request consumes 10 credits; the local track download and merge do not consume additional SocialDataX credits. Use `--ffmpeg-path <path>` when `ffmpeg` is not on `PATH`, and `--keep-tracks` to retain the separate track files after merge.
 

package/cli.mjs

@@ -12,13 +12,17 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { downloadBilibiliVideoFromManifest } from "./lib/media/bilibili-download.mjs";
+import {
+  assertBilibiliFfmpegAvailable,
+  downloadBilibiliVideoFromManifest,
+} from "./lib/media/bilibili-download.mjs";
 import { decryptWechatMediaCommand } from "./lib/media/wechat-decrypt.mjs";
+import { downloadXhsMediaFromUrl } from "./lib/media/xhs-download.mjs";
 
 export { decryptWechatMediaCommand };
 
 const PACKAGE_NAME = "socialdatax-skills";
-const PACKAGE_VERSION = "0.2.25";
+const PACKAGE_VERSION = "0.2.27";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
 const LOG_PREFIX = `[${PACKAGE_NAME}]`;
 const MIN_NODE_VERSION = "20.18.1";
@@ -160,6 +164,7 @@ const XHS_DIRECT_ACTION_OPTIONS = {
     "pretty",
   ],
   transcript: ["url", "noteId", "jobId", "pretty"],
+  "download-media": ["url", "output", "outputDir", "pretty"],
 };
 const XHS_DIRECT_ACTION_NAMES = Object.keys(XHS_DIRECT_ACTION_OPTIONS).join(", ");
 const XHS_OPTION_DISPLAY_NAMES = {
@@ -179,6 +184,8 @@ const XHS_OPTION_DISPLAY_NAMES = {
   profileUrl: "--profile-url",
   userId: "--user-id",
   jobId: "--job-id",
+  output: "--output",
+  outputDir: "--output-dir",
 };
 const XHS_SEARCH_SORT_TYPES = [
   "general",
@@ -527,12 +534,12 @@ const PLATFORMS = {
       {
         name: "xhs_get_note_comments_by_note_id",
         description:
-          "Fetch paginated first-level comments by note ID with optional sort.",
+          "Fetch paginated first-level comments by note ID.",
       },
       {
         name: "xhs_get_note_comments_by_note_url",
         description:
-          "Fetch paginated first-level comments from a note URL, short link, or share text with optional sort.",
+          "Fetch paginated first-level comments from a note URL, short link, or share text.",
       },
       {
         name: "xhs_get_note_sub_comments_by_comment_id",
@@ -1094,6 +1101,26 @@ function validateXhsDirectActionOptions(action, options) {
     return;
   }
 
+  if (action === "download-media") {
+    validateKnownOptions(options, allowedOptions);
+    validateFlagOption(options, "pretty", "--pretty");
+    for (const key of allowedOptions) {
+      if (!DIRECT_BOOLEAN_OPTIONS.has(key)) {
+        requireOptionValue(options, key, XHS_OPTION_DISPLAY_NAMES[key]);
+      }
+    }
+    if (!options.url) {
+      throw new Error("Missing --url for xhs download-media.");
+    }
+    if (!options.output && !options.outputDir) {
+      throw new Error("Missing --output or --output-dir for xhs download-media.");
+    }
+    if (options.output && options.outputDir) {
+      throw new Error("Use only one of --output or --output-dir for xhs download-media.");
+    }
+    return;
+  }
+
   validateKnownOptions(options, allowedDirectOptions(allowedOptions));
   validateDirectMetaOptions(options);
   validateDirectPaginationOptions("xhs", action, options);
@@ -1844,6 +1871,9 @@ function printHelp() {
   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} xhs download-media --url "<xhs_media_url>" --output-dir ./downloads --pretty`);
+  console.log("      Save one XHS image or video media URL returned by detail to a local file.");
+  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("");
@@ -2087,13 +2117,14 @@ function printHelp() {
   console.log("  --keyword <text>");
   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 download-media, pass one image or video media URL returned by XHS 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.");
   console.log("  --output <file>");
-  console.log("      Output file path for local decrypt-media or Bilibili download.");
+  console.log("      Output file path for local decrypt-media, XHS download-media, or Bilibili download.");
   console.log("  --output-dir <directory>");
-  console.log("      Directory for Bilibili download output when --output is omitted.");
+  console.log("      Directory for XHS download-media or Bilibili download output when --output is omitted.");
   console.log("  --ffmpeg-path <path>");
   console.log("      ffmpeg executable path for Bilibili download; defaults to ffmpeg.");
   console.log("  --keep-tracks");
@@ -2215,6 +2246,13 @@ async function runXhsDirectCommand(args) {
   }
   validateXhsDirectActionOptions(action, options);
 
+  if (action === "download-media") {
+    const data = await downloadXhsMediaFromUrl(options.url, options);
+    process.stdout.write(JSON.stringify(data, null, options.pretty ? 2 : 0));
+    process.stdout.write("\n");
+    return;
+  }
+
   const operation = attachDirectMetadata(buildXhsOperation(action, options), options);
   const data = shouldUsePaginatedDirectOutput(options)
     ? await callPaginatedDirectOperation(operation, options)
@@ -2359,6 +2397,10 @@ async function assertBilibiliDownloadLocalPreflight(options) {
       await assertBilibiliParentDirectory(outputDir, "--output-dir parent path");
     }
   }
+
+  ensureSupportedNodeVersion();
+  readDirectApiKey(PLATFORMS.bilibili);
+  await assertBilibiliFfmpegAvailable(options.ffmpegPath || "ffmpeg");
 }
 
 async function assertBilibiliParentDirectory(targetPath, displayName) {
@@ -4203,13 +4245,7 @@ function buildRepliesOperationForComment(platform, comment, parentArguments, par
 async function callMcpBackend(operation) {
   ensureSupportedNodeVersion();
   const { platform, tool } = operation;
-  const apiKey = readFirstEnv(platform.apiKeyEnv);
-  if (!apiKey) {
-    throw new Error(
-      `Missing API Key. Set ${PRIMARY_API_KEY_ENV} before running direct CLI calls.`
-    );
-  }
-
+  const apiKey = readDirectApiKey(platform);
   const { Client, StreamableHTTPClientTransport } = await loadMcpSdkModules();
   const upstreamUrl = resolveUpstreamUrl(platform);
   const client = new Client(
@@ -4258,6 +4294,16 @@ async function callMcpBackend(operation) {
   }
 }
 
+function readDirectApiKey(platform) {
+  const apiKey = readFirstEnv(platform.apiKeyEnv);
+  if (!apiKey) {
+    throw new Error(
+      `Missing API Key. Set ${PRIMARY_API_KEY_ENV} before running direct CLI calls.`
+    );
+  }
+  return apiKey;
+}
+
 async function loadMcpSdkModules() {
   if (!mcpSdkModules) {
     const [{ Client }, { StreamableHTTPClientTransport }] = await Promise.all([

package/lib/media/bilibili-download.mjs

@@ -8,7 +8,12 @@ import {
   stat,
   unlink,
 } from "node:fs/promises";
-import { homedir } from "node:os";
+import {
+  arch as osArch,
+  homedir,
+  platform as osPlatform,
+  release as osRelease,
+} from "node:os";
 import { dirname, join, resolve } from "node:path";
 
 import {
@@ -39,11 +44,18 @@ export async function downloadBilibiliVideoFromManifest(
   validateBilibiliDownloadManifest(manifest);
 
   const outputPath = resolveBilibiliOutputPath(manifest, options);
+  const ffmpegPath = options.ffmpegPath || "ffmpeg";
   await mkdir(dirname(outputPath), { recursive: true });
   await reserveBilibiliOutputPath(outputPath);
 
   const downloadedTracks = [];
   try {
+    await assertBilibiliTrackPathsAvailable(
+      manifest.download_manifest.tracks,
+      outputPath
+    );
+    await assertBilibiliFfmpegAvailable(ffmpegPath, spawnProcess);
+
     for (const track of manifest.download_manifest.tracks) {
       downloadedTracks.push(
         await downloadBilibiliTrack(track, {
@@ -63,7 +75,7 @@ export async function downloadBilibiliVideoFromManifest(
     }
 
     await mergeBilibiliTracksWithFfmpeg({
-      ffmpegPath: options.ffmpegPath || "ffmpeg",
+      ffmpegPath,
       videoPath: videoTrack.path,
       audioPath: audioTrack.path,
       outputPath,
@@ -222,9 +234,10 @@ async function downloadBilibiliTrack(
     maxDownloadBytes,
   }
 ) {
-  const trackType = String(track.type);
-  const ext = sanitizeFileExtension(track.ext || "m4s");
-  const trackPath = `${outputPath}.${trackType}.${ext}`;
+  const { trackType, ext, trackPath } = resolveBilibiliTrackTarget(
+    track,
+    outputPath
+  );
   const tempPath = `${trackPath}.tmp-${process.pid}-${Date.now()}-${randomUUID()}`;
   await mkdir(dirname(trackPath), { recursive: true });
 
@@ -275,6 +288,31 @@ async function downloadBilibiliTrack(
   };
 }
 
+async function assertBilibiliTrackPathsAvailable(tracks, outputPath) {
+  for (const track of tracks) {
+    const { trackType, trackPath } = resolveBilibiliTrackTarget(track, outputPath);
+    const existingTrack = await stat(trackPath).catch((error) => {
+      if (error?.code === "ENOENT") {
+        return undefined;
+      }
+      throw error;
+    });
+    if (existingTrack) {
+      throw new Error(`Bilibili ${trackType} track file already exists.`);
+    }
+  }
+}
+
+function resolveBilibiliTrackTarget(track, outputPath) {
+  const trackType = String(track.type);
+  const ext = sanitizeFileExtension(track.ext || "m4s");
+  return {
+    trackType,
+    ext,
+    trackPath: `${outputPath}.${trackType}.${ext}`,
+  };
+}
+
 async function reserveBilibiliTrackPath(trackPath, trackType) {
   let file;
   try {
@@ -341,7 +379,21 @@ async function mergeBilibiliTracksWithFfmpeg({
   await runFfmpegProcess(ffmpegPath, args, spawnProcess);
 }
 
-async function runFfmpegProcess(ffmpegPath, args, spawnProcess) {
+export async function assertBilibiliFfmpegAvailable(
+  ffmpegPath = "ffmpeg",
+  spawnProcess = spawn
+) {
+  await runFfmpegProcess(ffmpegPath, ["-version"], spawnProcess, {
+    failurePrefix: "ffmpeg availability check failed",
+  });
+}
+
+async function runFfmpegProcess(
+  ffmpegPath,
+  args,
+  spawnProcess,
+  { failurePrefix = "ffmpeg failed for bilibili download" } = {}
+) {
   return new Promise((resolvePromise, reject) => {
     let stderr = "";
     const child = spawnProcess(ffmpegPath, args, {
@@ -358,7 +410,7 @@ async function runFfmpegProcess(ffmpegPath, args, spawnProcess) {
       if (error?.code === "ENOENT") {
         reject(
           new Error(
-            "ffmpeg not found. Install ffmpeg or pass --ffmpeg-path for bilibili download."
+            buildFfmpegMissingMessage(ffmpegPath)
           )
         );
         return;
@@ -372,13 +424,26 @@ async function runFfmpegProcess(ffmpegPath, args, spawnProcess) {
       }
       reject(
         new Error(
-          `ffmpeg failed for bilibili download with exit code ${status}. ${stderr.trim()}`.trim()
+          `${failurePrefix} with exit code ${status}. ${stderr.trim()}`.trim()
         )
       );
     });
   });
 }
 
+function buildFfmpegMissingMessage(ffmpegPath) {
+  const detectedSystem = `${osPlatform()} ${osRelease()} ${osArch()}`;
+  return [
+    `ffmpeg not found at "${ffmpegPath}".`,
+    `Detected system: ${detectedSystem}.`,
+    "Install ffmpeg, then retry:",
+    "macOS (Homebrew): brew install ffmpeg",
+    "Ubuntu/Debian: sudo apt update && sudo apt install ffmpeg",
+    "Windows (winget): winget install Gyan.FFmpeg",
+    "If ffmpeg is already installed, pass --ffmpeg-path /path/to/ffmpeg for bilibili download.",
+  ].join("\n");
+}
+
 function stringValue(value) {
   return typeof value === "string" && value.trim() ? value : undefined;
 }

package/lib/media/xhs-download.mjs

@@ -0,0 +1,723 @@
+import { constants as fsConstants } from "node:fs";
+import {
+  copyFile as copyFilePath,
+  link as linkPath,
+  open as openFile,
+  mkdir,
+  stat,
+  unlink,
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, extname, join, resolve } from "node:path";
+
+import {
+  MEDIA_DOWNLOAD_MAX_BYTES,
+  MEDIA_DOWNLOAD_TIMEOUT_MS,
+  assertMediaDownloadWithinLimit,
+  createMediaDownloadAbortSignal,
+  isAbortLikeError,
+  parseOptionalIntegerHeader,
+  writeAllToFile,
+} from "./common.mjs";
+
+const XHS_DOWNLOAD_USER_AGENT =
+  "Mozilla/5.0 (compatible; SocialDataX/1.0; +https://socialdatax.com)";
+const XHS_DOWNLOAD_REFERER = "https://www.xiaohongshu.com/";
+const XHS_DOWNLOAD_MAX_ATTEMPTS = 10;
+const XHS_DOWNLOAD_RETRY_DELAY_MS = 250;
+const XHS_RETRYABLE_HTTP_STATUSES = new Set([
+  408,
+  409,
+  425,
+  429,
+  500,
+  502,
+  503,
+  504,
+]);
+const XHS_EXPIRED_HTTP_STATUSES = new Set([403, 404, 410]);
+const XHS_CONTENT_TYPE_EXTENSIONS = new Map([
+  ["image/jpeg", "jpg"],
+  ["image/jpg", "jpg"],
+  ["image/png", "png"],
+  ["image/webp", "webp"],
+  ["image/heif", "heif"],
+  ["image/heic", "heic"],
+  ["video/mp4", "mp4"],
+]);
+const XHS_URL_FORMAT_EXTENSIONS = new Map([
+  ["jpg", "jpg"],
+  ["jpeg", "jpg"],
+  ["png", "png"],
+  ["webp", "webp"],
+  ["heif", "heif"],
+  ["heic", "heic"],
+  ["mp4", "mp4"],
+]);
+export async function downloadXhsMediaFromUrl(
+  url,
+  options,
+  {
+    fetchMedia = fetch,
+    downloadTimeoutMs = MEDIA_DOWNLOAD_TIMEOUT_MS,
+    maxDownloadBytes = MEDIA_DOWNLOAD_MAX_BYTES,
+    retryDelayMs = XHS_DOWNLOAD_RETRY_DELAY_MS,
+    now = () => new Date(),
+    linkFile = linkPath,
+    copyFile = copyFilePath,
+  } = {}
+) {
+  const parsedUrl = parseHttpUrl(url);
+  const target = await resolveXhsMediaTarget(parsedUrl, options, now);
+  const existingOutput = await stat(target.outputPath).catch(ignoreMissing);
+  if (existingOutput?.isDirectory()) {
+    throw new Error("--output must be a file path for xhs download-media.");
+  }
+  if (existingOutput) {
+    return buildSkippedExistingResult(parsedUrl.href, target.outputPath, existingOutput.size);
+  }
+
+  return downloadWithPartResume(parsedUrl, target, {
+    fetchMedia,
+    downloadTimeoutMs,
+    maxDownloadBytes,
+    retryDelayMs,
+    linkFile,
+    copyFile,
+  });
+}
+
+async function resolveXhsMediaTarget(parsedUrl, options = {}, now) {
+  if (options.output && options.outputDir) {
+    throw new Error("Use only one of --output or --output-dir for xhs download-media.");
+  }
+  if (options.output) {
+    const outputPath = resolve(expandHome(options.output));
+    await ensureParentDirectory(outputPath, "--output parent path");
+    return {
+      outputPath,
+      partPath: `${outputPath}.part`,
+      fixedOutputPath: true,
+    };
+  }
+  if (!options.outputDir) {
+    throw new Error("Missing --output or --output-dir for xhs download-media.");
+  }
+
+  const outputDir = resolve(expandHome(options.outputDir));
+  const existingOutputDir = await stat(outputDir).catch(ignoreMissing);
+  if (existingOutputDir && !existingOutputDir.isDirectory()) {
+    throw new Error("--output-dir must be a directory for xhs download-media.");
+  }
+  if (!existingOutputDir) {
+    await ensureParentDirectory(outputDir, "--output-dir parent path");
+    await mkdir(outputDir, { recursive: true });
+  }
+
+  const fileTarget = inferMediaFileTarget(parsedUrl, now);
+  const initialExtension =
+    fileTarget.extension || fileTarget.urlFormatExtension || "bin";
+  const fileName = formatMediaFileName(fileTarget.stem, initialExtension);
+  const outputPath = join(outputDir, fileName);
+  return {
+    outputPath,
+    partPath: `${outputPath}.part`,
+    outputDir,
+    fileStem: fileTarget.stem,
+    extension: fileTarget.extension,
+    urlFormatExtension: fileTarget.urlFormatExtension,
+    fixedOutputPath: false,
+  };
+}
+
+async function downloadWithPartResume(
+  parsedUrl,
+  target,
+  {
+    fetchMedia,
+    downloadTimeoutMs,
+    maxDownloadBytes,
+    retryDelayMs,
+    linkFile,
+    copyFile,
+  }
+) {
+  let lastError;
+  for (let attempt = 1; attempt <= XHS_DOWNLOAD_MAX_ATTEMPTS; attempt += 1) {
+    try {
+      const result = await downloadOnce(parsedUrl, target, {
+        fetchMedia,
+        downloadTimeoutMs,
+        maxDownloadBytes,
+        linkFile,
+        copyFile,
+      });
+      if (result.skippedExisting) {
+        return buildSkippedExistingResult(
+          parsedUrl.href,
+          result.outputPath,
+          result.outputBytes
+        );
+      }
+      return {
+        platform: "xhs",
+        action: "download-media",
+        status: "downloaded",
+        url: parsedUrl.href,
+        output_path: result.outputPath,
+        output_bytes: result.outputBytes,
+        resumed: result.resumed,
+        content_type: result.contentType,
+      };
+    } catch (error) {
+      if (error instanceof XhsExpiredMediaLinkError) {
+        throw error;
+      }
+      lastError = error;
+      if (!shouldRetryDownloadError(error)) {
+        throw error;
+      }
+      if (attempt === XHS_DOWNLOAD_MAX_ATTEMPTS) {
+        break;
+      }
+      await sleep(retryDelayMs);
+    }
+  }
+
+  if (isAbortLikeError(lastError)) {
+    throw new Error("XHS media download timed out.");
+  }
+  throw new Error("XHS media download failed before completion.");
+}
+
+async function downloadOnce(
+  parsedUrl,
+  target,
+  {
+    fetchMedia,
+    downloadTimeoutMs,
+    maxDownloadBytes,
+    linkFile,
+    copyFile,
+  }
+) {
+  await mkdir(dirname(target.outputPath), { recursive: true });
+  const partPath = target.partPath;
+  const existingPart = await stat(partPath).catch(ignoreMissing);
+  let existingPartBytes = existingPart?.isFile() ? existingPart.size : 0;
+  const headers = normalizeXhsDownloadHeaders();
+  if (existingPartBytes > 0) {
+    headers.Range = `bytes=${existingPartBytes}-`;
+    delete headers["accept-encoding"];
+  }
+
+  const signal = createMediaDownloadAbortSignal(downloadTimeoutMs);
+  const response = await fetchMedia(parsedUrl.href, {
+    headers,
+    ...(signal ? { signal } : {}),
+  });
+
+  if (XHS_EXPIRED_HTTP_STATUSES.has(response.status)) {
+    throw new XhsExpiredMediaLinkError();
+  }
+  if (response.status === 416) {
+    return handleRangeNotSatisfiable(response, {
+      target,
+      partPath,
+      existingPartBytes,
+      linkFile,
+      copyFile,
+    });
+  }
+  if (!response.ok) {
+    if (XHS_RETRYABLE_HTTP_STATUSES.has(response.status)) {
+      throw new XhsRetryableDownloadError();
+    }
+    throw new Error(`XHS media download failed with HTTP ${response.status}.`);
+  }
+
+  const contentType = normalizedContentType(headerValue(response.headers, "content-type"));
+  const outputPath = resolveFinalOutputPath(target, contentType);
+  const existingOutput = await stat(outputPath).catch(ignoreMissing);
+  if (existingOutput?.isDirectory()) {
+    throw new Error("--output must be a file path for xhs download-media.");
+  }
+  if (existingOutput) {
+    await cancelResponseBody(response);
+    return {
+      skippedExisting: true,
+      outputPath,
+      outputBytes: existingOutput.size,
+      contentType,
+    };
+  }
+  const contentLength = parseOptionalIntegerHeader(
+    headerValue(response.headers, "content-length")
+  );
+  let append = false;
+  let expectedTotalBytes = contentLength;
+  let expectedResponseBytes;
+
+  if (existingPartBytes > 0 && response.status === 206) {
+    const contentRange = parseContentRange(
+      headerValue(response.headers, "content-range")
+    );
+    if (
+      !isUsableContentRange(contentRange, contentLength) ||
+      contentRange.start !== existingPartBytes
+    ) {
+      await cancelResponseBody(response);
+      await unlink(partPath).catch(ignoreError);
+      throw new XhsRetryableDownloadError();
+    }
+    append = true;
+    expectedResponseBytes = contentRange.end - contentRange.start + 1;
+    expectedTotalBytes = contentRange.total;
+  } else if (existingPartBytes > 0) {
+    existingPartBytes = 0;
+    expectedTotalBytes = contentLength;
+  } else if (response.status === 206) {
+    const contentRange = parseContentRange(
+      headerValue(response.headers, "content-range")
+    );
+    if (
+      !isUsableContentRange(contentRange, contentLength) ||
+      contentRange.start !== 0
+    ) {
+      await cancelResponseBody(response);
+      throw new XhsRetryableDownloadError();
+    }
+    expectedResponseBytes = contentRange.end - contentRange.start + 1;
+    expectedTotalBytes = contentRange.total;
+  }
+
+  assertMediaDownloadWithinLimit(expectedTotalBytes, maxDownloadBytes);
+  let outputBytes;
+  let bytesWritten;
+  try {
+    bytesWritten = await writeResponseBodyToPart(response, partPath, {
+      append,
+      existingBytes: existingPartBytes,
+      maxBytes: maxDownloadBytes,
+    });
+    outputBytes = existingPartBytes + bytesWritten;
+  } catch (error) {
+    if (isAbortLikeError(error) || isDownloadTooLargeError(error)) {
+      throw error;
+    }
+    throw new XhsRetryableDownloadError();
+  }
+
+  if (
+    expectedResponseBytes !== undefined &&
+    bytesWritten !== expectedResponseBytes
+  ) {
+    if (bytesWritten > expectedResponseBytes) {
+      await unlink(partPath).catch(ignoreError);
+    }
+    throw new XhsRetryableDownloadError();
+  }
+
+  if (expectedTotalBytes !== undefined && outputBytes !== expectedTotalBytes) {
+    if (outputBytes > expectedTotalBytes) {
+      await unlink(partPath).catch(ignoreError);
+    }
+    throw new XhsRetryableDownloadError();
+  }
+
+  await finalizePartFile(partPath, outputPath, { linkFile, copyFile });
+  return {
+    outputPath,
+    outputBytes,
+    resumed: append && existingPartBytes > 0,
+    contentType,
+  };
+}
+
+async function handleRangeNotSatisfiable(
+  response,
+  {
+    target,
+    partPath,
+    existingPartBytes,
+    linkFile,
+    copyFile,
+  }
+) {
+  const contentRange = parseContentRange(headerValue(response.headers, "content-range"));
+  if (
+    existingPartBytes > 0 &&
+    contentRange?.total !== undefined &&
+    existingPartBytes === contentRange.total
+  ) {
+    const contentType = normalizedContentType(headerValue(response.headers, "content-type"));
+    const outputPath = resolveFinalOutputPath(target, contentType);
+    const existingOutput = await stat(outputPath).catch(ignoreMissing);
+    if (existingOutput?.isDirectory()) {
+      throw new Error("--output must be a file path for xhs download-media.");
+    }
+    if (existingOutput) {
+      await cancelResponseBody(response);
+      return {
+        skippedExisting: true,
+        outputPath,
+        outputBytes: existingOutput.size,
+        contentType,
+      };
+    }
+    await finalizePartFile(partPath, outputPath, { linkFile, copyFile });
+    return {
+      outputPath,
+      outputBytes: existingPartBytes,
+      resumed: true,
+      contentType,
+    };
+  }
+  await unlink(partPath).catch(ignoreError);
+  throw new XhsRetryableDownloadError();
+}
+
+async function writeResponseBodyToPart(
+  response,
+  partPath,
+  {
+    append,
+    existingBytes,
+    maxBytes,
+  }
+) {
+  if (!response.body) {
+    throw new XhsRetryableDownloadError();
+  }
+
+  const file = await openFile(partPath, append ? "r+" : "w");
+  let bytesWritten = 0;
+  try {
+    for await (const chunk of response.body) {
+      const buffer = Buffer.from(chunk);
+      if (buffer.length === 0) {
+        continue;
+      }
+      const nextTotal = existingBytes + bytesWritten + buffer.length;
+      assertMediaDownloadWithinLimit(nextTotal, maxBytes);
+      await writeAllToFile(file, buffer, existingBytes + bytesWritten);
+      bytesWritten += buffer.length;
+    }
+  } finally {
+    await file.close();
+  }
+  return bytesWritten;
+}
+
+async function finalizePartFile(
+  partPath,
+  outputPath,
+  {
+    linkFile = linkPath,
+    copyFile = copyFilePath,
+  } = {}
+) {
+  try {
+    await ensureParentDirectory(outputPath, "xhs download-media output parent path");
+    try {
+      await linkFile(partPath, outputPath);
+    } catch (error) {
+      if (isExistingOutputPathError(error)) {
+        throw error;
+      }
+      if (!shouldFallbackToCopyAfterLinkError(error)) {
+        throw error;
+      }
+      await copyFile(partPath, outputPath, fsConstants.COPYFILE_EXCL);
+    }
+  } catch (error) {
+    if (isExistingOutputPathError(error)) {
+      throw await buildExistingOutputPathError(outputPath);
+    }
+    throw error;
+  }
+
+  await unlink(partPath);
+}
+
+async function cancelResponseBody(response) {
+  const body = response.body;
+  if (!body) {
+    return;
+  }
+  if (typeof body.cancel === "function") {
+    await body.cancel().catch(ignoreError);
+    return;
+  }
+  if (typeof body.return === "function") {
+    await body.return().catch(ignoreError);
+    return;
+  }
+  if (typeof body.destroy === "function") {
+    body.destroy();
+  }
+}
+
+function parseHttpUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(String(value || ""));
+  } catch {
+    throw new Error("XHS media URL must be an HTTP URL.");
+  }
+  if (!["http:", "https:"].includes(parsed.protocol) || !parsed.hostname) {
+    throw new Error("XHS media URL must be an HTTP URL.");
+  }
+  return parsed;
+}
+
+function normalizeXhsDownloadHeaders() {
+  return {
+    "User-Agent": XHS_DOWNLOAD_USER_AGENT,
+    Referer: XHS_DOWNLOAD_REFERER,
+    "accept-encoding": "identity",
+  };
+}
+
+function resolveFinalOutputPath(target, contentType) {
+  if (target.fixedOutputPath) {
+    return target.outputPath;
+  }
+  const extension =
+    target.extension ||
+    mediaExtensionFromContentType(contentType) ||
+    target.urlFormatExtension ||
+    "bin";
+  return join(target.outputDir, formatMediaFileName(target.fileStem, extension));
+}
+
+function inferMediaFileTarget(parsedUrl, now) {
+  const fallbackStem = `xhs-media-${formatTimestamp(now())}`;
+  const urlFormatExtension = inferUrlFormatExtension(parsedUrl);
+  const rawBasename = safeDecodeURIComponent(basename(parsedUrl.pathname || ""));
+  const sanitized = sanitizeFileName(rawBasename);
+  if (sanitized && sanitized !== "." && sanitized !== "..") {
+    const currentExt = extname(sanitized);
+    const extension = sanitizeFileExtension(currentExt.slice(1));
+    const stem = extension
+      ? sanitizeFileName(sanitized.slice(0, -currentExt.length)) || fallbackStem
+      : sanitized;
+    return {
+      stem,
+      extension,
+      urlFormatExtension,
+    };
+  }
+  return {
+    stem: fallbackStem,
+    extension: "",
+    urlFormatExtension,
+  };
+}
+
+async function ensureParentDirectory(outputPath, displayName) {
+  const parent = dirname(outputPath);
+  const existingParent = await stat(parent).catch(ignoreMissing);
+  if (existingParent && !existingParent.isDirectory()) {
+    throw new Error(`${displayName} must be a directory for xhs download-media.`);
+  }
+  if (!existingParent) {
+    await mkdir(parent, { recursive: true });
+  }
+}
+
+function buildSkippedExistingResult(url, outputPath, outputBytes) {
+  return {
+    platform: "xhs",
+    action: "download-media",
+    status: "skipped_existing",
+    url,
+    output_path: outputPath,
+    output_bytes: outputBytes,
+  };
+}
+
+function parseContentRange(value) {
+  if (!value) {
+    return undefined;
+  }
+  const trimmed = String(value).trim();
+  const unsatisfied = /^bytes\s+\*\/(\d+)$/i.exec(trimmed);
+  if (unsatisfied) {
+    return {
+      start: undefined,
+      end: undefined,
+      total: Number.parseInt(unsatisfied[1], 10),
+    };
+  }
+  const matched = /^bytes\s+(\d+)-(\d+)\/(\d+|\*)$/i.exec(trimmed);
+  if (!matched) {
+    return undefined;
+  }
+  return {
+    start: Number.parseInt(matched[1], 10),
+    end: Number.parseInt(matched[2], 10),
+    total: matched[3] === "*" ? undefined : Number.parseInt(matched[3], 10),
+  };
+}
+
+function isUsableContentRange(contentRange, contentLength) {
+  if (
+    contentRange?.start === undefined ||
+    contentRange.end === undefined ||
+    contentRange.total === undefined ||
+    !Number.isSafeInteger(contentRange.start) ||
+    !Number.isSafeInteger(contentRange.end) ||
+    !Number.isSafeInteger(contentRange.total) ||
+    contentRange.end < contentRange.start ||
+    contentRange.end >= contentRange.total
+  ) {
+    return false;
+  }
+  const rangeBytes = contentRange.end - contentRange.start + 1;
+  return contentLength === undefined || contentLength === rangeBytes;
+}
+
+function shouldRetryDownloadError(error) {
+  return (
+    error instanceof XhsRetryableDownloadError ||
+    isAbortLikeError(error) ||
+    isNetworkLikeError(error)
+  );
+}
+
+function isNetworkLikeError(error) {
+  return (
+    error?.name === "TypeError" ||
+    ["ECONNRESET", "ECONNREFUSED", "EPIPE", "ETIMEDOUT"].includes(error?.code)
+  );
+}
+
+function isDownloadTooLargeError(error) {
+  return error?.message === "Media download is too large for local media processing.";
+}
+
+function normalizedContentType(value) {
+  if (!value) {
+    return null;
+  }
+  return String(value).split(";")[0].trim().toLowerCase() || null;
+}
+
+function headerValue(headers, name) {
+  if (!headers || typeof headers.get !== "function") {
+    return null;
+  }
+  return headers.get(name);
+}
+
+function sanitizeFileName(value) {
+  const normalized = String(value || "")
+    .replace(/[\\/:*?"<>|\u0000-\u001f]/g, "_")
+    .replace(/\s+/g, " ")
+    .trim();
+  return normalized.slice(0, 120);
+}
+
+function sanitizeFileExtension(value) {
+  const normalized = String(value || "").toLowerCase().replace(/[^a-z0-9]/g, "");
+  if (!normalized || normalized.length > 8) {
+    return "";
+  }
+  return normalized;
+}
+
+function formatMediaFileName(stem, extension) {
+  return `${stem}.${sanitizeFileExtension(extension) || "bin"}`;
+}
+
+function mediaExtensionFromContentType(contentType) {
+  return XHS_CONTENT_TYPE_EXTENSIONS.get(contentType) || "";
+}
+
+function inferUrlFormatExtension(parsedUrl) {
+  const matched = /(?:^|[/?&])format\/([a-z0-9]+)(?:[/?&#]|$)/i.exec(
+    `${parsedUrl.pathname}${parsedUrl.search}`
+  );
+  if (!matched) {
+    return "";
+  }
+  return XHS_URL_FORMAT_EXTENSIONS.get(sanitizeFileExtension(matched[1])) || "";
+}
+
+function isExistingOutputPathError(error) {
+  return error?.code === "EEXIST" || error?.code === "EISDIR";
+}
+
+function shouldFallbackToCopyAfterLinkError(error) {
+  return ["EPERM", "ENOTSUP", "ENOSYS", "EOPNOTSUPP", "EXDEV"].includes(
+    error?.code
+  );
+}
+
+async function buildExistingOutputPathError(outputPath) {
+  const existingOutput = await stat(outputPath).catch(ignoreMissing);
+  if (existingOutput?.isDirectory()) {
+    return new Error("--output must be a file path for xhs download-media.");
+  }
+  return new Error("XHS media download output file already exists.");
+}
+
+function formatTimestamp(value) {
+  const date = value instanceof Date ? value : new Date(value);
+  const pad = (part) => String(part).padStart(2, "0");
+  return [
+    date.getFullYear(),
+    pad(date.getMonth() + 1),
+    pad(date.getDate()),
+    pad(date.getHours()),
+    pad(date.getMinutes()),
+    pad(date.getSeconds()),
+  ].join("");
+}
+
+function safeDecodeURIComponent(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function expandHome(path) {
+  if (!path || path === "~") {
+    return homedir();
+  }
+  if (path.startsWith("~/")) {
+    return join(homedir(), path.slice(2));
+  }
+  return path;
+}
+
+function ignoreMissing(error) {
+  if (error?.code === "ENOENT" || error?.code === "ENOTDIR") {
+    return undefined;
+  }
+  throw error;
+}
+
+function ignoreError() {}
+
+function sleep(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) {
+    return Promise.resolve();
+  }
+  return new Promise((resolvePromise) => {
+    setTimeout(resolvePromise, ms);
+  });
+}
+
+class XhsRetryableDownloadError extends Error {}
+
+class XhsExpiredMediaLinkError extends Error {
+  constructor() {
+    super(
+      "XHS media link is unavailable or expired. Get a fresh media URL from the XHS detail result and retry."
+    );
+  }
+}

package/package.json

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