socialdatax-skills 0.2.25 → 0.2.26

package/README.md

@@ -79,7 +79,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.26`
 
 ## Direct CLI
 

package/cli.mjs

@@ -12,13 +12,16 @@ 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";
 
 export { decryptWechatMediaCommand };
 
 const PACKAGE_NAME = "socialdatax-skills";
-const PACKAGE_VERSION = "0.2.25";
+const PACKAGE_VERSION = "0.2.26";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
 const LOG_PREFIX = `[${PACKAGE_NAME}]`;
 const MIN_NODE_VERSION = "20.18.1";
@@ -527,12 +530,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",
@@ -2359,6 +2362,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 +4210,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 +4259,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/package.json

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