socialdatax-skills 0.2.22 → 0.2.24

package/README.md

@@ -73,7 +73,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.22`
+- Current public capability version: `0.2.24`
 
 ## Direct CLI
 
@@ -87,6 +87,7 @@ npx -y socialdatax-skills@latest xhs search --keyword "露营" --since-days 7 --
 npx -y socialdatax-skills@latest xhs hot-search --pretty
 npx -y socialdatax-skills@latest xhs detail --note-id "<note_id>" --pretty
 npx -y socialdatax-skills@latest xhs comments --note-id "<note_id>" --pretty
+npx -y socialdatax-skills@latest xhs comments --note-id "<note_id>" --sort-type time_descending --pretty
 npx -y socialdatax-skills@latest xhs comments --note-id "<note_id>" --all --include-replies --pretty
 npx -y socialdatax-skills@latest xhs sub-comments --note-id "<note_id>" --comment-id "<comment_id>" --pretty
 npx -y socialdatax-skills@latest xhs user-info --user-id "<user_id>" --pretty
@@ -186,6 +187,10 @@ XHS, Douyin, Kuaishou, Weibo, and WeChat Channels search use `--keyword` and opt
 Kuaishou work search uses `kuaishou search --keyword` and optional `--page-token`; Kuaishou creator search uses `kuaishou user-search --keyword` and optional `--page-token`. Kuaishou search does not accept Douyin semantic filters, and `kuaishou user-search` does not support `--since-days`.
 Weibo and WeChat Channels search use `--keyword` and optional `--page-token`.
 
+XHS comments accept optional `--sort-type` values: `default`,
+`time_descending`, and `like_count_descending`; omit it for the platform
+default comment order.
+
 Douyin search filters use semantic values: `--sort-type` supports `general`,
 `time_descending`, and `like_count_descending`; `--publish-time-range` supports
 `all`, `day`, `week`, and `half_year`; `--duration-range` supports `all`,
@@ -405,8 +410,8 @@ Current Sensitive Words Check workflows include:
 | `xhs_search_notes` | Search Xiaohongshu / 小红书 notes by keyword with optional sort, note type, and publish-time filters. |
 | `xhs_get_note_detail_by_note_url` | Resolve a shared XHS link, short link, or share text into structured note details. |
 | `xhs_get_note_detail_by_note_id` | Fetch structured note details when the caller already has a note ID. |
-| `xhs_get_note_comments_by_note_id` | Fetch paginated first-level comments when the caller already has a note ID. |
-| `xhs_get_note_comments_by_note_url` | Fetch paginated first-level comments directly from a shared note URL, short link, or share text. |
+| `xhs_get_note_comments_by_note_id` | Fetch paginated first-level comments when the caller already has a note ID; accepts optional comment `sort_type`. |
+| `xhs_get_note_comments_by_note_url` | Fetch paginated first-level comments directly from a shared note URL, short link, or share text; accepts optional comment `sort_type`. |
 | `xhs_get_note_sub_comments_by_comment_id` | Fetch paginated replies under a first-level comment by note ID and comment ID. |
 | `xhs_get_user_info_by_user_id` | Fetch creator profile data when the caller already has a user ID. |
 | `xhs_get_user_info_by_profile_url` | Resolve a profile link, short link, or share text into creator profile data. |

package/cli.mjs

@@ -17,7 +17,7 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PACKAGE_NAME = "socialdatax-skills";
-const PACKAGE_VERSION = "0.2.22";
+const PACKAGE_VERSION = "0.2.24";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
 const LOG_PREFIX = `[${PACKAGE_NAME}]`;
 const MIN_NODE_VERSION = "20.18.1";
@@ -29,6 +29,37 @@ const MEDIA_DOWNLOAD_TIMEOUT_MS = 10 * 60 * 1000;
 const MEDIA_DOWNLOAD_MAX_BYTES = 2 * 1024 * 1024 * 1024;
 const MEDIA_DECRYPT_CHUNK_SIZE = 64 * 1024;
 const MEDIA_DOWNLOAD_MAX_REDIRECTS = 5;
+const MP4_BOX_HEADER_SIZE = 8;
+const MP4_EXTENDED_BOX_HEADER_SIZE = 16;
+const MP4_MAX_BOX_SCAN_DEPTH = 16;
+const MP4_FULL_BOX_HEADER_SIZE = 4;
+const MP4_STSD_ENTRY_COUNT_SIZE = 4;
+const MP4_VISUAL_SAMPLE_ENTRY_HEADER_SIZE = 78;
+const MP4_VVC_NAL_LENGTH_SIZE_BYTE_OFFSET = 4;
+const MP4_CONTAINER_BOX_TYPES = new Set([
+  "dinf",
+  "edts",
+  "mdia",
+  "meta",
+  "minf",
+  "moof",
+  "moov",
+  "mfra",
+  "stbl",
+  "traf",
+  "trak",
+  "udta",
+]);
+const MP4_VISUAL_SAMPLE_ENTRY_TYPES = new Set([
+  "av01",
+  "avc1",
+  "avc3",
+  "encv",
+  "hev1",
+  "hvc1",
+  "vvc1",
+  "vvi1",
+]);
 // Keep this local helper scoped to WeChat media host trees; require k for the decrypt key.
 const WECHAT_MEDIA_DOWNLOAD_HOST_SUFFIXES = [
   ".wxapp.tc.qq.com",
@@ -146,6 +177,7 @@ const XHS_DIRECT_ACTION_OPTIONS = {
     "all",
     "maxItems",
     "includeReplies",
+    "sortType",
     "pretty",
   ],
   "sub-comments": [
@@ -197,6 +229,11 @@ const XHS_SEARCH_SORT_TYPES = [
   "comment_count_descending",
   "collect_count_descending",
 ];
+const XHS_COMMENT_SORT_TYPES = [
+  "default",
+  "time_descending",
+  "like_count_descending",
+];
 const XHS_LEGACY_SEARCH_SORT_TYPE_ALIASES = {
   popularity_descending: "like_count_descending",
   comment_descending: "comment_count_descending",
@@ -521,12 +558,13 @@ const PLATFORMS = {
       },
       {
         name: "xhs_get_note_comments_by_note_id",
-        description: "Fetch paginated first-level comments by note ID.",
+        description:
+          "Fetch paginated first-level comments by note ID with optional sort.",
       },
       {
         name: "xhs_get_note_comments_by_note_url",
         description:
-          "Fetch paginated first-level comments from a note URL, short link, or share text.",
+          "Fetch paginated first-level comments from a note URL, short link, or share text with optional sort.",
       },
       {
         name: "xhs_get_note_sub_comments_by_comment_id",
@@ -2061,6 +2099,8 @@ function printHelp() {
   console.log("      For comments commands, also fetch nested second-level replies for each returned first-level comment.");
   console.log("  --sort-type <general|time_descending|like_count_descending|comment_count_descending|collect_count_descending>");
   console.log("      XHS sort meanings: general=default, time_descending=newest, like_count_descending=most liked, comment_count_descending=most commented, collect_count_descending=most collected.");
+  console.log("  --sort-type <default|time_descending|like_count_descending>");
+  console.log("      XHS comments sort meanings: default=platform default, time_descending=newest, like_count_descending=most liked.");
   console.log("  --note-type <all|image|video>  XHS search note type filter; default is all.");
   console.log("  --publish-time-range <all|day|week|half_year>");
   console.log("      XHS search publish-time filter; default is all.");
@@ -2355,6 +2395,7 @@ function buildXhsOperation(action, options) {
           idDisplay: "--note-id",
           urlDisplay: "--url",
           pageToken: options.pageToken,
+          extraArguments: buildXhsCommentsExtraArguments(options),
         })
       );
     case "sub-comments":
@@ -2936,6 +2977,7 @@ export async function decryptWechatMediaCommand(
         encryptedLength,
         decodeKey,
       });
+      await patchWechatVvcMp4NalLengthMetadata(tempPath);
       decrypted = true;
     }
     await rename(tempPath, outputPath);
@@ -3185,6 +3227,158 @@ async function decryptWechatMediaFilePrefix(
   }
 }
 
+async function patchWechatVvcMp4NalLengthMetadata(filePath) {
+  const file = await openFile(filePath, "r+");
+  try {
+    const stats = await file.stat();
+    await patchMp4ChildBoxes(file, 0, stats.size, 0);
+  } finally {
+    await file.close();
+  }
+}
+
+async function patchMp4ChildBoxes(file, startOffset, endOffset, depth) {
+  if (
+    depth > MP4_MAX_BOX_SCAN_DEPTH ||
+    startOffset < 0 ||
+    endOffset - startOffset < MP4_BOX_HEADER_SIZE
+  ) {
+    return;
+  }
+
+  let offset = startOffset;
+  while (offset + MP4_BOX_HEADER_SIZE <= endOffset) {
+    const box = await readMp4BoxHeader(file, offset, endOffset);
+    if (!box) {
+      return;
+    }
+    if (box.type === "vvcC") {
+      await patchVvcConfigurationNalLengthSize(file, box);
+    } else {
+      const childRange = mp4ChildBoxRange(box);
+      if (childRange) {
+        await patchMp4ChildBoxes(
+          file,
+          childRange.startOffset,
+          childRange.endOffset,
+          depth + 1
+        );
+      }
+    }
+    offset = box.endOffset;
+  }
+}
+
+async function readMp4BoxHeader(file, offset, parentEndOffset) {
+  const baseHeader = Buffer.allocUnsafe(MP4_BOX_HEADER_SIZE);
+  const baseRead = await file.read(
+    baseHeader,
+    0,
+    MP4_BOX_HEADER_SIZE,
+    offset
+  );
+  if (baseRead.bytesRead !== MP4_BOX_HEADER_SIZE) {
+    return undefined;
+  }
+
+  const size32 = baseHeader.readUInt32BE(0);
+  const type = baseHeader.toString("ascii", 4, 8);
+  let headerSize = MP4_BOX_HEADER_SIZE;
+  let size;
+  if (size32 === 0) {
+    size = parentEndOffset - offset;
+  } else if (size32 === 1) {
+    if (offset + MP4_EXTENDED_BOX_HEADER_SIZE > parentEndOffset) {
+      return undefined;
+    }
+    const extendedSizeBuffer = Buffer.allocUnsafe(8);
+    const extendedRead = await file.read(
+      extendedSizeBuffer,
+      0,
+      8,
+      offset + MP4_BOX_HEADER_SIZE
+    );
+    if (extendedRead.bytesRead !== 8) {
+      return undefined;
+    }
+    const extendedSize = extendedSizeBuffer.readBigUInt64BE(0);
+    if (extendedSize > BigInt(Number.MAX_SAFE_INTEGER)) {
+      return undefined;
+    }
+    size = Number(extendedSize);
+    headerSize = MP4_EXTENDED_BOX_HEADER_SIZE;
+  } else {
+    size = size32;
+  }
+
+  if (
+    size < headerSize ||
+    offset + size > parentEndOffset ||
+    !isMp4BoxType(type)
+  ) {
+    return undefined;
+  }
+
+  return {
+    type,
+    startOffset: offset,
+    headerSize,
+    payloadOffset: offset + headerSize,
+    endOffset: offset + size,
+  };
+}
+
+function isMp4BoxType(type) {
+  return /^[\x20-\x7e]{4}$/.test(type);
+}
+
+function mp4ChildBoxRange(box) {
+  if (box.type === "stsd") {
+    const childStart =
+      box.payloadOffset + MP4_FULL_BOX_HEADER_SIZE + MP4_STSD_ENTRY_COUNT_SIZE;
+    return childStart < box.endOffset
+      ? { startOffset: childStart, endOffset: box.endOffset }
+      : undefined;
+  }
+  if (box.type === "meta") {
+    const childStart = box.payloadOffset + MP4_FULL_BOX_HEADER_SIZE;
+    return childStart < box.endOffset
+      ? { startOffset: childStart, endOffset: box.endOffset }
+      : undefined;
+  }
+  if (MP4_VISUAL_SAMPLE_ENTRY_TYPES.has(box.type)) {
+    const childStart = box.payloadOffset + MP4_VISUAL_SAMPLE_ENTRY_HEADER_SIZE;
+    return childStart < box.endOffset
+      ? { startOffset: childStart, endOffset: box.endOffset }
+      : undefined;
+  }
+  if (MP4_CONTAINER_BOX_TYPES.has(box.type)) {
+    return box.payloadOffset < box.endOffset
+      ? { startOffset: box.payloadOffset, endOffset: box.endOffset }
+      : undefined;
+  }
+  return undefined;
+}
+
+async function patchVvcConfigurationNalLengthSize(file, box) {
+  const targetOffset =
+    box.payloadOffset + MP4_VVC_NAL_LENGTH_SIZE_BYTE_OFFSET;
+  if (targetOffset >= box.endOffset) {
+    return;
+  }
+  const buffer = Buffer.allocUnsafe(1);
+  const { bytesRead } = await file.read(buffer, 0, 1, targetOffset);
+  if (bytesRead !== 1) {
+    return;
+  }
+  const patched = (buffer[0] & 0xf8) | 0x07;
+  if (patched === buffer[0]) {
+    return;
+  }
+  buffer[0] = patched;
+  await writeAllToFile(file, buffer, targetOffset);
+}
+
 function isAbortLikeError(error) {
   return error?.name === "AbortError" || error?.name === "TimeoutError";
 }
@@ -3500,6 +3694,7 @@ function buildOneOfCall(
     idDisplay,
     urlDisplay,
     pageToken,
+    extraArguments = {},
   }
 ) {
   const idValue = options[idOption];
@@ -3516,9 +3711,23 @@ function buildOneOfCall(
   if (pageToken) {
     toolArguments.page_token = pageToken;
   }
+  Object.assign(toolArguments, extraArguments);
   return { tool, toolArguments };
 }
 
+function buildXhsCommentsExtraArguments(options) {
+  const toolArguments = {};
+  if (options.sortType !== undefined) {
+    toolArguments.sort_type = parseAllowedStringOption(
+      options.sortType,
+      "--sort-type",
+      XHS_COMMENT_SORT_TYPES,
+      XHS_COMMENT_SORT_TYPES.join(", ")
+    );
+  }
+  return toolArguments;
+}
+
 function buildTranscriptCall(
   options,
   {

package/package.json

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

package/skills/media-comments/SKILL.md

@@ -142,6 +142,7 @@ npx -y socialdatax-skills@latest wechat replies \
 Optional arguments:
 
 - XHS `--note-id <note_id>`: use the complete 24-character lowercase hexadecimal `note_id` returned from search, detail, comments, or creator note lists; do not pass only a prefix.
+- XHS comments `--sort-type <default|time_descending|like_count_descending>`: optional first-level comment sort order; omit it for the platform default order.
 - Douyin `--aweme-id <aweme_id>`: preferred when the video ID is already known and should anchor the comment thread.
 - `--url <url_or_share_text>`: use for a content page URL, short link, or share text for first-level comments.
 - Douyin URL safety: do not pass `video.play_url`; use a Douyin content page URL, short link, or share text instead.
@@ -188,8 +189,8 @@ MCP tools matching the direct CLI commands above:
 - `wechat_get_video_comment_replies_by_comment_id`
 
 If MCP tools are already available in the current agent, use one of these tools:
-- `xhs_get_note_comments_by_note_id`: use when the complete 24-character lowercase hexadecimal `note_id` is known; do not pass only a prefix.
-- `xhs_get_note_comments_by_note_url`: use for note URLs, short links, or share text.
+- `xhs_get_note_comments_by_note_id`: use when the complete 24-character lowercase hexadecimal `note_id` is known; do not pass only a prefix; optional `sort_type` accepts `default`, `time_descending`, or `like_count_descending`.
+- `xhs_get_note_comments_by_note_url`: use for note URLs, short links, or share text; optional `sort_type` accepts `default`, `time_descending`, or `like_count_descending`.
 - `xhs_get_note_sub_comments_by_comment_id`: use when the complete 24-character lowercase hexadecimal `note_id` and first-level comment ID are known; do not pass only a note ID prefix.
 - `douyin_get_video_comments_by_aweme_id`: use when the aweme_id is known.
 - `douyin_get_video_comments_by_url`: use for Douyin content page URLs, short links, or share text; do not pass playback URLs such as `video.play_url`.

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

@@ -436,7 +436,8 @@ Optional arguments:
 - Kuaishou `user-search` supports `--pages <n>` and `--max-items <n>` for bounded creator candidate discovery; it does not support `--since-days`.
 - `--since-days <1-365>`: keep search or creator content-list items whose public `publish_time` is within the last N days. Search stays bounded by `--pages`; creator content lists continue until the publish-time boundary when `--pages` is omitted.
 - `--include-replies`: for first-level comments, also fetch nested second-level replies under each returned comment.
-- `--sort-type`, `--note-type`, `--publish-time-range`, `--duration-range`, and `--content-type`: apply only to XHS, Douyin, or WeChat Channels keyword research commands when the user asks for filtering; Kuaishou and Weibo search currently use `--keyword` and optional `--page-token`.
+- XHS comments `--sort-type <default|time_descending|like_count_descending>`: optional first-level comment sort order; omit it for the platform default order.
+- Keyword research filters: use the documented XHS, Douyin, and WeChat Channels search `--sort-type` values; `--note-type`, `--publish-time-range`, `--duration-range`, and `--content-type` apply only where supported. Kuaishou and Weibo search currently use `--keyword` and optional `--page-token`.
 - `--comment-id`: required for reply/sub-comment commands together with the content ID.
 - `--pretty`: output formatting only.
 - `--source-client socialdatax-skills --source-platform npm --source-skill socialdatax-content-research-assistant`: usage attribution for this Agent Skill; keep these values unchanged when running examples from this Skill.