socialdatax-skills 0.2.5 → 0.2.7

package/README.md

@@ -48,7 +48,7 @@ Common search phrases for this skill package:
 - Kuaishou current platform MCP registry name: `com.52choujiang/kuaishou-insights`
 - Kuaishou future platform MCP registry name: `com.socialdatax/kuaishou-insights`
 - Unified MCP registry name: none; this package installs skills and calls explicit platform services.
-- Current public capability version: `0.2.5`
+- Current public capability version: `0.2.7`
 
 ## Direct CLI
 
@@ -61,6 +61,7 @@ npx -y socialdatax-skills@latest xhs search --keyword "露营桌" --pretty
 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>" --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
 npx -y socialdatax-skills@latest xhs user-posts --user-id "<user_id>" --pretty
@@ -68,6 +69,7 @@ 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
 npx -y socialdatax-skills@latest douyin comments --aweme-id "<aweme_id>" --pretty
+npx -y socialdatax-skills@latest douyin comments --aweme-id "<aweme_id>" --all --include-replies --pretty
 npx -y socialdatax-skills@latest douyin replies --aweme-id "<aweme_id>" --comment-id "<comment_id>" --pretty
 npx -y socialdatax-skills@latest douyin user-info --sec-user-id "<sec_user_id>" --pretty
 npx -y socialdatax-skills@latest douyin user-info --profile-url "<profile_url_or_share_text>" --pretty
@@ -80,6 +82,7 @@ npx -y socialdatax-skills@latest kuaishou search --keyword "露营桌" --pretty
 npx -y socialdatax-skills@latest kuaishou detail --photo-id "<photo_id>" --pretty
 npx -y socialdatax-skills@latest kuaishou detail --url "<kuaishou_content_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest kuaishou comments --photo-id "<photo_id>" --pretty
+npx -y socialdatax-skills@latest kuaishou comments --photo-id "<photo_id>" --all --include-replies --pretty
 npx -y socialdatax-skills@latest kuaishou comments --url "<kuaishou_content_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest kuaishou replies --photo-id "<photo_id>" --comment-id "<comment_id>" --pretty
 npx -y socialdatax-skills@latest kuaishou user-info --user-id "<user_id>" --pretty
@@ -90,6 +93,16 @@ npx -y socialdatax-skills@latest kuaishou user-posts --profile-url "<profile_url
 
 The direct CLI prints a JSON envelope with `platform`, `tool`, `arguments`, and `data`.
 
+For list-style commands, use `--pages <n>` to fetch N pages from the current starting point and `--max-items <n>` to cap the merged `data.items` output. Search commands support `--pages` but not `--all`, because search has no stable complete-result boundary.
+
+For comments, replies, creator content lists, and Douyin creator series, use `--all` to continue until the returned `next_page_token` is empty. `--all` has no default item or page cap; add `--max-items <n>` or use `--pages <n>` when you want a bounded run.
+
+For first-level comments, add `--include-replies` to fetch the second-level replies under each returned first-level comment. Multi-page output keeps `data.items` as the merged first-level list; each item gets `replies`, `replies_page_count`, and `replies_next_page_token`.
+
+For commands that accept `--page-token`, continue only with the complete returned `next_page_token` from the same pagination chain. Do not modify, truncate, redact, mask, omit, normalize, rebuild, generate, or replace the middle with ellipses.
+
+XHS search uses numeric `--page`; Douyin and Kuaishou search do not accept `--page`. For Douyin and Kuaishou search, omit `--page-token` on the first request and pass the complete returned `next_page_token` only when continuing the same search chain.
+
 Kuaishou search uses `--keyword` and optional `--page-token`; it does not accept Douyin semantic filters.
 
 Douyin search filters use semantic values: `--sort-type` supports `general`,
@@ -234,7 +247,7 @@ Current Douyin workflows include:
 - Search related Douyin works by keyword.
 - Resolve a Douyin content page link, short link, share text, or aweme_id into structured work details.
 - Fetch paginated first-level comments for comment analysis.
-- Fetch paginated replies under a first-level comment.
+- Fetch paginated replies under a first-level comment; pass both `aweme_id` and `comment_id`, and use `page_token` to continue pagination.
 - Continue Douyin comment and reply pagination only when `next_page_token` is non-empty; an empty string means there are no more comments or replies to request.
 - Read creator profile data from a profile link, short link, share text, or sec_user_id.
 - Fetch paginated creator work lists from a sec_user_id, profile link, short link, or share text.
@@ -261,12 +274,12 @@ Current Douyin workflows include:
 | Tool | Public purpose |
 | --- | --- |
 | `douyin_get_hot_search_list` | Fetch the current Douyin main hot search list. |
-| `douyin_search_videos` | Search Douyin works by keyword with optional paging and filters. |
+| `douyin_search_videos` | Search Douyin works by keyword with optional `page_token` continuation and filters; do not pass `page`. |
 | `douyin_get_video_detail_by_aweme_id` | Fetch structured Douyin work details when the caller already has an aweme_id. |
 | `douyin_get_video_detail_by_url` | Resolve a Douyin content page link, short link, or share text into structured Douyin work details. |
 | `douyin_get_video_comments_by_aweme_id` | Fetch paginated first-level comments when the caller already has an aweme_id. |
 | `douyin_get_video_comments_by_url` | Fetch paginated first-level comments directly from a Douyin content page URL, short link, or share text. |
-| `douyin_get_video_comment_replies_by_comment_id` | Fetch paginated replies under a first-level Douyin comment by aweme_id and comment_id. |
+| `douyin_get_video_comment_replies_by_comment_id` | Fetch paginated replies under a first-level Douyin comment; pass both aweme_id and comment_id, and use page_token to continue pagination. |
 | `douyin_get_user_info_by_sec_user_id` | Fetch creator profile data when the caller already has a sec_user_id. |
 | `douyin_get_user_info_by_profile_url` | Resolve a profile link, short link, or share text into creator profile data. |
 | `douyin_get_user_posted_videos_by_sec_user_id` | Fetch a paginated list of works published by a creator when the caller already has a sec_user_id. |
@@ -279,7 +292,7 @@ Current Douyin workflows include:
 | Tool | Public purpose |
 | --- | --- |
 | `kuaishou_get_hot_search_list` | Get the current Kuaishou / 快手 short-video hot list. |
-| `kuaishou_search_videos` | Search Kuaishou works by natural-language keyword with optional paging. |
+| `kuaishou_search_videos` | Search Kuaishou works by natural-language keyword with optional `page_token` continuation; do not pass `page`. |
 | `kuaishou_get_video_detail_by_photo_id` | Fetch structured work details when the caller already has a photo_id. |
 | `kuaishou_get_video_detail_by_url` | Resolve a Kuaishou work page link, short link, or share text into structured work details. |
 | `kuaishou_get_video_comments_by_photo_id` | Fetch paginated first-level comments when the caller already has a photo_id. |

package/cli.mjs

@@ -7,7 +7,7 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PACKAGE_NAME = "socialdatax-skills";
-const PACKAGE_VERSION = "0.2.5";
+const PACKAGE_VERSION = "0.2.7";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
 const LOG_PREFIX = `[${PACKAGE_NAME}]`;
 const MIN_NODE_VERSION = "20.18.1";
@@ -50,17 +50,53 @@ const AVAILABLE_SKILLS = [
   },
 ];
 const AVAILABLE_SKILL_NAMES = AVAILABLE_SKILLS.map((skill) => skill.name);
-const BOOLEAN_OPTIONS = new Set(["dryRun", "force", "json", "pretty"]);
+const BOOLEAN_OPTIONS = new Set([
+  "all",
+  "dryRun",
+  "force",
+  "includeReplies",
+  "json",
+  "pretty",
+]);
+const DIRECT_BOOLEAN_OPTIONS = new Set(["all", "includeReplies", "pretty"]);
 const INSTALL_TARGETS = ["openclaw", "hermes", "agents", "codex", "claude-code", "claude"];
 const VALID_SCOPES = ["user", "workspace", "shared"];
 const XHS_DIRECT_ACTION_OPTIONS = {
   "hot-search": ["pretty"],
-  search: ["keyword", "page", "sortType", "noteType", "publishTimeRange", "pretty"],
+  search: [
+    "keyword",
+    "page",
+    "pages",
+    "all",
+    "maxItems",
+    "sortType",
+    "noteType",
+    "publishTimeRange",
+    "pretty",
+  ],
   detail: ["noteId", "url", "pretty"],
-  comments: ["noteId", "url", "pageToken", "pretty"],
-  "sub-comments": ["noteId", "commentId", "pageToken", "pretty"],
+  comments: [
+    "noteId",
+    "url",
+    "pageToken",
+    "pages",
+    "all",
+    "maxItems",
+    "includeReplies",
+    "pretty",
+  ],
+  "sub-comments": [
+    "noteId",
+    "commentId",
+    "pageToken",
+    "pages",
+    "all",
+    "maxItems",
+    "includeReplies",
+    "pretty",
+  ],
   "user-info": ["userId", "profileUrl", "pretty"],
-  "user-posts": ["userId", "profileUrl", "pageToken", "pretty"],
+  "user-posts": ["userId", "profileUrl", "pageToken", "pages", "all", "maxItems", "pretty"],
 };
 const XHS_DIRECT_ACTION_NAMES = Object.keys(XHS_DIRECT_ACTION_OPTIONS).join(", ");
 const XHS_OPTION_DISPLAY_NAMES = {
@@ -73,6 +109,10 @@ const XHS_OPTION_DISPLAY_NAMES = {
   noteId: "--note-id",
   commentId: "--comment-id",
   pageToken: "--page-token",
+  pages: "--pages",
+  maxItems: "--max-items",
+  all: "--all",
+  includeReplies: "--include-replies",
   profileUrl: "--profile-url",
   userId: "--user-id",
 };
@@ -93,6 +133,9 @@ const DOUYIN_DIRECT_ACTION_OPTIONS = {
   search: [
     "keyword",
     "pageToken",
+    "pages",
+    "all",
+    "maxItems",
     "sortType",
     "publishTimeRange",
     "durationRange",
@@ -100,11 +143,29 @@ const DOUYIN_DIRECT_ACTION_OPTIONS = {
     "pretty",
   ],
   detail: ["awemeId", "url", "pretty"],
-  comments: ["awemeId", "url", "pageToken", "pretty"],
-  replies: ["awemeId", "commentId", "pageToken", "pretty"],
+  comments: [
+    "awemeId",
+    "url",
+    "pageToken",
+    "pages",
+    "all",
+    "maxItems",
+    "includeReplies",
+    "pretty",
+  ],
+  replies: [
+    "awemeId",
+    "commentId",
+    "pageToken",
+    "pages",
+    "all",
+    "maxItems",
+    "includeReplies",
+    "pretty",
+  ],
   "user-info": ["secUserId", "profileUrl", "pretty"],
-  "user-posts": ["secUserId", "profileUrl", "pageToken", "pretty"],
-  "user-series": ["secUserId", "profileUrl", "pageToken", "pretty"],
+  "user-posts": ["secUserId", "profileUrl", "pageToken", "pages", "all", "maxItems", "pretty"],
+  "user-series": ["secUserId", "profileUrl", "pageToken", "pages", "all", "maxItems", "pretty"],
 };
 const DOUYIN_DIRECT_ACTION_NAMES = Object.keys(DOUYIN_DIRECT_ACTION_OPTIONS).join(", ");
 const DOUYIN_SEARCH_SORT_TYPES = ["general", "time_descending", "like_count_descending"];
@@ -119,6 +180,10 @@ const DOUYIN_SEARCH_CONTENT_TYPES = ["all", "video", "image"];
 const DOUYIN_OPTION_DISPLAY_NAMES = {
   keyword: "--keyword",
   pageToken: "--page-token",
+  pages: "--pages",
+  maxItems: "--max-items",
+  all: "--all",
+  includeReplies: "--include-replies",
   sortType: "--sort-type",
   publishTimeRange: "--publish-time-range",
   durationRange: "--duration-range",
@@ -131,17 +196,39 @@ const DOUYIN_OPTION_DISPLAY_NAMES = {
 };
 const KUAISHOU_DIRECT_ACTION_OPTIONS = {
   "hot-search": ["pretty"],
-  search: ["keyword", "pageToken", "pretty"],
+  search: ["keyword", "pageToken", "pages", "all", "maxItems", "pretty"],
   detail: ["photoId", "url", "pretty"],
-  comments: ["photoId", "url", "pageToken", "pretty"],
-  replies: ["photoId", "commentId", "pageToken", "pretty"],
+  comments: [
+    "photoId",
+    "url",
+    "pageToken",
+    "pages",
+    "all",
+    "maxItems",
+    "includeReplies",
+    "pretty",
+  ],
+  replies: [
+    "photoId",
+    "commentId",
+    "pageToken",
+    "pages",
+    "all",
+    "maxItems",
+    "includeReplies",
+    "pretty",
+  ],
   "user-info": ["userId", "profileUrl", "pretty"],
-  "user-posts": ["userId", "profileUrl", "pageToken", "pretty"],
+  "user-posts": ["userId", "profileUrl", "pageToken", "pages", "all", "maxItems", "pretty"],
 };
 const KUAISHOU_DIRECT_ACTION_NAMES = Object.keys(KUAISHOU_DIRECT_ACTION_OPTIONS).join(", ");
 const KUAISHOU_OPTION_DISPLAY_NAMES = {
   keyword: "--keyword",
   pageToken: "--page-token",
+  pages: "--pages",
+  maxItems: "--max-items",
+  all: "--all",
+  includeReplies: "--include-replies",
   url: "--url",
   profileUrl: "--profile-url",
   photoId: "--photo-id",
@@ -252,7 +339,7 @@ const PLATFORMS = {
       },
       {
         name: "douyin_get_video_comment_replies_by_comment_id",
-        description: "Fetch paginated replies under a first-level Douyin comment by aweme_id and comment_id.",
+        description: "Fetch paginated replies under a first-level Douyin comment; pass both aweme_id and comment_id, and use page_token to continue pagination.",
       },
       {
         name: "douyin_get_user_info_by_sec_user_id",
@@ -280,7 +367,8 @@ const PLATFORMS = {
       },
       {
         name: "douyin_search_videos",
-        description: "Search Douyin works by keyword with optional paging and filters.",
+        description:
+          "Search Douyin works by keyword with optional page_token continuation and filters; do not pass page.",
       },
     ],
   },
@@ -304,7 +392,8 @@ const PLATFORMS = {
       },
       {
         name: "kuaishou_search_videos",
-        description: "Search Kuaishou works by natural-language keyword with optional paging.",
+        description:
+          "Search Kuaishou works by natural-language keyword with optional page_token continuation; do not pass page.",
       },
       {
         name: "kuaishou_get_video_detail_by_photo_id",
@@ -471,9 +560,9 @@ function validateXhsDirectActionOptions(action, options) {
   }
 
   validateKnownOptions(options, allowedOptions);
-  validateFlagOption(options, "pretty", "--pretty");
+  validateDirectPaginationOptions("xhs", action, options);
   for (const key of allowedOptions) {
-    if (key !== "pretty") {
+    if (!DIRECT_BOOLEAN_OPTIONS.has(key)) {
       requireOptionValue(options, key, XHS_OPTION_DISPLAY_NAMES[key]);
     }
   }
@@ -486,9 +575,9 @@ function validateDouyinDirectActionOptions(action, options) {
   }
 
   validateKnownOptions(options, allowedOptions);
-  validateFlagOption(options, "pretty", "--pretty");
+  validateDirectPaginationOptions("douyin", action, options);
   for (const key of allowedOptions) {
-    if (key !== "pretty") {
+    if (!DIRECT_BOOLEAN_OPTIONS.has(key)) {
       requireOptionValue(options, key, DOUYIN_OPTION_DISPLAY_NAMES[key]);
     }
   }
@@ -501,14 +590,35 @@ function validateKuaishouDirectActionOptions(action, options) {
   }
 
   validateKnownOptions(options, allowedOptions);
-  validateFlagOption(options, "pretty", "--pretty");
+  validateDirectPaginationOptions("kuaishou", action, options);
   for (const key of allowedOptions) {
-    if (key !== "pretty") {
+    if (!DIRECT_BOOLEAN_OPTIONS.has(key)) {
       requireOptionValue(options, key, KUAISHOU_OPTION_DISPLAY_NAMES[key]);
     }
   }
 }
 
+function validateDirectPaginationOptions(platformId, action, options) {
+  validateFlagOption(options, "pretty", "--pretty");
+  validateFlagOption(options, "all", "--all");
+  validateFlagOption(options, "includeReplies", "--include-replies");
+  if (options.all && options.pages !== undefined) {
+    throw new Error("Use only one of --all or --pages.");
+  }
+  if (options.pages !== undefined) {
+    parsePositiveIntegerOption(options.pages, "--pages");
+  }
+  if (options.maxItems !== undefined) {
+    parsePositiveIntegerOption(options.maxItems, "--max-items");
+  }
+  if (options.all && action === "search") {
+    throw new Error(`--all is not supported for ${platformId} search. Use --pages instead.`);
+  }
+  if (options.includeReplies && action !== "comments") {
+    throw new Error(`--include-replies is only supported for ${platformId} comments.`);
+  }
+}
+
 function parsePositiveIntegerOption(value, displayName) {
   const text = String(value);
   if (!/^\d+$/.test(text)) {
@@ -992,6 +1102,9 @@ function printHelp() {
   console.log(`  npx -y ${PACKAGE_SPEC} xhs comments --note-id "<note_id>" --pretty`);
   console.log("      Call the XHS comments tool directly and print JSON.");
   console.log("");
+  console.log(`  npx -y ${PACKAGE_SPEC} xhs comments --note-id "<note_id>" --all --include-replies --pretty`);
+  console.log("      Fetch all XHS first-level comments and nested replies.");
+  console.log("");
   console.log(
     `  npx -y ${PACKAGE_SPEC} xhs sub-comments --note-id "<note_id>" --comment-id "<comment_id>" --pretty`
   );
@@ -1015,10 +1128,13 @@ function printHelp() {
   console.log(`  npx -y ${PACKAGE_SPEC} douyin comments --aweme-id "<aweme_id>" --pretty`);
   console.log("      Call the Douyin work comments tool directly and print JSON.");
   console.log("");
+  console.log(`  npx -y ${PACKAGE_SPEC} douyin comments --aweme-id "<aweme_id>" --all --include-replies --pretty`);
+  console.log("      Fetch all Douyin first-level comments and nested replies.");
+  console.log("");
   console.log(
     `  npx -y ${PACKAGE_SPEC} douyin replies --aweme-id "<aweme_id>" --comment-id "<comment_id>" --pretty`
   );
-  console.log("      Call the Douyin comment replies tool directly and print JSON.");
+  console.log("      Call the Douyin comment replies tool with aweme_id and comment_id; use page_token for pagination.");
   console.log("");
   console.log(`  npx -y ${PACKAGE_SPEC} douyin user-info --sec-user-id "<sec_user_id>" --pretty`);
   console.log("      Call the Douyin creator profile tool directly and print JSON.");
@@ -1053,6 +1169,9 @@ function printHelp() {
   console.log(`  npx -y ${PACKAGE_SPEC} kuaishou comments --photo-id "<photo_id>" --pretty`);
   console.log("      Call the Kuaishou work comments tool directly and print JSON.");
   console.log("");
+  console.log(`  npx -y ${PACKAGE_SPEC} kuaishou comments --photo-id "<photo_id>" --all --include-replies --pretty`);
+  console.log("      Fetch all Kuaishou first-level comments and nested replies.");
+  console.log("");
   console.log(`  npx -y ${PACKAGE_SPEC} kuaishou comments --url "<kuaishou_content_url_or_share_text>" --pretty`);
   console.log("      Call the Kuaishou work comments tool from a work link or share text.");
   console.log("");
@@ -1148,6 +1267,15 @@ function printHelp() {
   console.log("  --user-id <user_id>");
   console.log("  --sec-user-id <sec_user_id>");
   console.log("  --page <number>");
+  console.log("      XHS search only. Douyin and Kuaishou search do not accept --page.");
+  console.log("  --pages <number>");
+  console.log("      Fetch and merge N pages from the current starting point for search, comments, replies, creator content lists, and creator series.");
+  console.log("  --all");
+  console.log("      Continue comments, replies, creator content lists, and creator series until next_page_token is empty; not supported for search.");
+  console.log("  --max-items <number>");
+  console.log("      Stop after collecting this many primary items.");
+  console.log("  --include-replies");
+  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("  --note-type <all|image|video>  XHS search note type filter; default is all.");
@@ -1162,6 +1290,7 @@ function printHelp() {
   console.log("  --content-type <all|video|image>");
   console.log("      Douyin content type filter; omit for all content types.");
   console.log("  --page-token <token>");
+  console.log("      Continue token-paginated commands with the complete returned next_page_token. For Douyin and Kuaishou search, omit it on the first request.");
   console.log("  --pretty            Pretty-print direct CLI JSON output.");
   console.log("  --json              Print doctor output as JSON.");
   console.log("  --target <openclaw|hermes|agents|codex|claude-code|claude>");
@@ -1210,7 +1339,9 @@ async function runXhsDirectCommand(args) {
   validateXhsDirectActionOptions(action, options);
 
   const operation = buildXhsOperation(action, options);
-  const data = await callDirectOperation(operation);
+  const data = shouldUsePaginatedDirectOutput(options)
+    ? await callPaginatedDirectOperation(operation, options)
+    : await callDirectOperation(operation);
   const envelope = {
     platform: operation.platform.id,
     tool: operation.tool,
@@ -1235,7 +1366,9 @@ async function runDouyinDirectCommand(args) {
   validateDouyinDirectActionOptions(action, options);
 
   const operation = buildDouyinOperation(action, options);
-  const data = await callDirectOperation(operation);
+  const data = shouldUsePaginatedDirectOutput(options)
+    ? await callPaginatedDirectOperation(operation, options)
+    : await callDirectOperation(operation);
   const envelope = {
     platform: operation.platform.id,
     tool: operation.tool,
@@ -1260,7 +1393,9 @@ async function runKuaishouDirectCommand(args) {
   validateKuaishouDirectActionOptions(action, options);
 
   const operation = buildKuaishouOperation(action, options);
-  const data = await callDirectOperation(operation);
+  const data = shouldUsePaginatedDirectOutput(options)
+    ? await callPaginatedDirectOperation(operation, options)
+    : await callDirectOperation(operation);
   const envelope = {
     platform: operation.platform.id,
     tool: operation.tool,
@@ -1773,6 +1908,469 @@ async function callDirectOperation(operation) {
   }
 }
 
+function shouldUsePaginatedDirectOutput(options) {
+  return Boolean(
+    options.all ||
+      options.pages !== undefined ||
+      options.maxItems !== undefined ||
+      options.includeReplies
+  );
+}
+
+async function callPaginatedDirectOperation(operation, options) {
+  const pagination = parseDirectPaginationOptions(options);
+  return collectPaginatedDirectData(operation, pagination, {
+    includeReplies: Boolean(options.includeReplies),
+  });
+}
+
+function parseDirectPaginationOptions(options) {
+  return {
+    all: Boolean(options.all),
+    pages:
+      options.pages === undefined
+        ? undefined
+        : parsePositiveIntegerOption(options.pages, "--pages"),
+    maxItems:
+      options.maxItems === undefined
+        ? undefined
+        : parsePositiveIntegerOption(options.maxItems, "--max-items"),
+  };
+}
+
+async function collectPaginatedDirectData(
+  operation,
+  pagination,
+  { includeReplies = false } = {}
+) {
+  const pageLimit = pagination.all ? Number.POSITIVE_INFINITY : pagination.pages || 1;
+  const collectedItems = [];
+  const itemDedupeState = createPaginatedItemDedupeState();
+  const seenNextMarkers = initialPaginationMarkers(operation);
+  let pageCount = 0;
+  let lastPageData;
+  let nextMarker;
+  let parentContextData = {};
+  let currentOperation = cloneDirectOperation(operation);
+
+  while (pageCount < pageLimit) {
+    const pageData = await callDirectOperation(currentOperation);
+    pageCount += 1;
+    lastPageData = pageData;
+    parentContextData = mergeParentContextData(parentContextData, pageData);
+
+    const pageItems = uniquePaginatedPageItems(
+      operation,
+      directPageItems(pageData),
+      itemDedupeState
+    );
+    const candidateItems = itemsForRemainingLimit(
+      pageItems,
+      collectedItems.length,
+      pagination.maxItems
+    );
+    const decoratedItems =
+      includeReplies && operation.operation === "comments"
+        ? await attachRepliesToCommentItems(
+            currentOperation,
+            candidateItems,
+            parentContextData
+          )
+        : candidateItems;
+    appendItemsWithLimit(collectedItems, decoratedItems, pagination.maxItems);
+
+    nextMarker = readNextPageMarker(currentOperation, pageData);
+    const markerKey = nextMarker === undefined ? undefined : String(nextMarker);
+    const markerRepeated =
+      markerKey !== undefined && seenNextMarkers.has(markerKey);
+    if (
+      !nextMarker ||
+      reachedMaxItems(collectedItems, pagination.maxItems) ||
+      pageCount >= pageLimit
+    ) {
+      if (markerRepeated) {
+        nextMarker = undefined;
+      }
+      break;
+    }
+    if (markerRepeated) {
+      throw new Error(
+        `Pagination stopped because ${nextMarkerName(currentOperation)} repeated.`
+      );
+    }
+    seenNextMarkers.add(markerKey);
+    currentOperation = operationWithNextPageMarker(currentOperation, nextMarker);
+  }
+
+  return buildPaginatedData({
+    operation,
+    lastPageData,
+    parentContextData,
+    items: collectedItems,
+    pageCount,
+    nextMarker,
+  });
+}
+
+function cloneDirectOperation(operation) {
+  return {
+    ...operation,
+    arguments: { ...operation.arguments },
+  };
+}
+
+function directPageItems(pageData) {
+  return Array.isArray(pageData?.items) ? pageData.items : [];
+}
+
+function createPaginatedItemDedupeState() {
+  return { seenKeys: new Set() };
+}
+
+function uniquePaginatedPageItems(operation, items, itemDedupeState) {
+  const uniqueItems = [];
+  for (const item of items) {
+    const dedupeKeys = paginatedItemDedupeKeys(operation, item);
+    if (dedupeKeys.length === 0) {
+      uniqueItems.push(item);
+      continue;
+    }
+    if (dedupeKeys.some((key) => itemDedupeState.seenKeys.has(key))) {
+      recordPaginatedItemDedupeKeys(itemDedupeState, dedupeKeys);
+      continue;
+    }
+    recordPaginatedItemDedupeKeys(itemDedupeState, dedupeKeys);
+    uniqueItems.push(item);
+  }
+  return uniqueItems;
+}
+
+function recordPaginatedItemDedupeKeys(itemDedupeState, dedupeKeys) {
+  for (const key of dedupeKeys) {
+    itemDedupeState.seenKeys.add(key);
+  }
+}
+
+function paginatedItemDedupeKeys(operation, item) {
+  if (shouldDeduplicateCommentItems(operation)) {
+    const commentId = itemStringField(item, "comment_id");
+    return commentId ? [`comment:${commentId}`] : [];
+  }
+  if (!shouldDeduplicateContentItems(operation)) {
+    return [];
+  }
+  const keys = [];
+  const itemId = contentItemId(operation, item);
+  if (itemId) {
+    keys.push(`${operation.operation}:${operation.platform.id}:id:${itemId}`);
+  }
+  const xhsFingerprint = xhsContentItemFingerprint(operation, item);
+  if (xhsFingerprint) {
+    keys.push(`${operation.operation}:xhs:fingerprint:${xhsFingerprint}`);
+  }
+  return keys;
+}
+
+function shouldDeduplicateCommentItems(operation) {
+  return ["comments", "replies", "sub-comments"].includes(operation.operation);
+}
+
+function shouldDeduplicateContentItems(operation) {
+  return ["search", "user-posts", "user-series"].includes(operation.operation);
+}
+
+function contentItemId(operation, item) {
+  switch (operation.platform.id) {
+    case "xhs":
+      return itemStringField(item, "note_id");
+    case "douyin":
+      if (operation.operation === "user-series") {
+        return itemStringField(item, "series_id");
+      }
+      return itemStringField(item, "aweme_id");
+    case "kuaishou":
+      return itemStringField(item, "photo_id");
+    default:
+      return undefined;
+  }
+}
+
+function xhsContentItemFingerprint(operation, item) {
+  if (
+    operation.platform.id !== "xhs" ||
+    !shouldDeduplicateContentItems(operation)
+  ) {
+    return undefined;
+  }
+  const authorId = itemStringField(item?.author, "user_id");
+  const publishTime = itemStringField(item, "publish_time");
+  const publishTimeNumber = Number(publishTime);
+  const coverToken = xhsImageUrlToken(item?.cover_image_url);
+  if (
+    !authorId ||
+    !publishTime ||
+    !Number.isFinite(publishTimeNumber) ||
+    publishTimeNumber <= 0 ||
+    !coverToken
+  ) {
+    return undefined;
+  }
+  return `${authorId}\t${publishTime}\t${coverToken}`;
+}
+
+function xhsImageUrlToken(imageUrl) {
+  const urlValue = stringValue(imageUrl);
+  if (!urlValue) {
+    return undefined;
+  }
+  let pathname;
+  try {
+    pathname = new URL(urlValue).pathname;
+  } catch {
+    return undefined;
+  }
+  let token = pathname.replace(/^\/+/, "");
+  const webpicContentIndex = token.indexOf("/c/");
+  if (webpicContentIndex !== -1) {
+    token = token.slice(webpicContentIndex + 3);
+  }
+  token = token.split("!", 1)[0];
+  return token || undefined;
+}
+
+function itemStringField(item, field) {
+  if (!item || typeof item !== "object") {
+    return undefined;
+  }
+  return stringValue(item[field]);
+}
+
+function stringValue(value) {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+  return String(value);
+}
+
+function mergeParentContextData(current, pageData) {
+  return {
+    ...current,
+    ...pickDefinedFields(pageData, ["note_id", "aweme_id", "photo_id"]),
+  };
+}
+
+function pickDefinedFields(source, fields) {
+  if (!source || typeof source !== "object") {
+    return {};
+  }
+  const picked = {};
+  for (const field of fields) {
+    if (source[field] !== undefined && source[field] !== null && source[field] !== "") {
+      picked[field] = source[field];
+    }
+  }
+  return picked;
+}
+
+function itemsForRemainingLimit(items, collectedItemCount, maxItems) {
+  if (maxItems === undefined) {
+    return items;
+  }
+  const remaining = maxItems - collectedItemCount;
+  return remaining > 0 ? items.slice(0, remaining) : [];
+}
+
+function appendItemsWithLimit(target, source, maxItems) {
+  if (maxItems === undefined) {
+    target.push(...source);
+    return;
+  }
+  const remaining = maxItems - target.length;
+  if (remaining <= 0) {
+    return;
+  }
+  target.push(...source.slice(0, remaining));
+}
+
+function reachedMaxItems(items, maxItems) {
+  return maxItems !== undefined && items.length >= maxItems;
+}
+
+function readNextPageMarker(operation, pageData) {
+  if (operation.platform.id === "xhs" && operation.operation === "search") {
+    const page = pageData?.next_page;
+    return page === undefined || page === null || page === "" ? undefined : page;
+  }
+  const token = pageData?.next_page_token;
+  return typeof token === "string" && token ? token : undefined;
+}
+
+function nextMarkerName(operation) {
+  return operation.platform.id === "xhs" && operation.operation === "search"
+    ? "next_page"
+    : "next_page_token";
+}
+
+function initialPaginationMarkers(operation) {
+  const marker = currentPageMarker(operation);
+  return marker === undefined ? new Set() : new Set([String(marker)]);
+}
+
+function currentPageMarker(operation) {
+  if (operation.platform.id === "xhs" && operation.operation === "search") {
+    return operation.arguments.page;
+  }
+  return operation.arguments.page_token;
+}
+
+function operationWithNextPageMarker(operation, nextMarker) {
+  const nextOperation = cloneDirectOperation(operation);
+  if (operation.platform.id === "xhs" && operation.operation === "search") {
+    nextOperation.arguments.page = nextMarker;
+  } else {
+    nextOperation.arguments.page_token = nextMarker;
+  }
+  return nextOperation;
+}
+
+function buildPaginatedData({
+  operation,
+  lastPageData,
+  parentContextData,
+  items,
+  pageCount,
+  nextMarker,
+}) {
+  const data = {
+    ...(lastPageData && typeof lastPageData === "object" ? lastPageData : {}),
+    ...parentContextData,
+    items,
+    page_count: pageCount,
+    item_count: items.length,
+  };
+  if (operation.platform.id === "xhs" && operation.operation === "search") {
+    data.next_page = nextMarker ?? null;
+  } else {
+    data.next_page_token = nextMarker || "";
+  }
+  return data;
+}
+
+async function attachRepliesToCommentItems(operation, items, pageData) {
+  const decorated = [];
+  for (const item of items) {
+    const comment = { ...item };
+    if (commentMayHaveReplies(comment)) {
+      const repliesOperation = buildRepliesOperationForComment(
+        operation.platform,
+        comment,
+        operation.arguments,
+        pageData
+      );
+      const repliesData = await collectPaginatedDirectData(
+        repliesOperation,
+        { all: true, pages: undefined, maxItems: undefined },
+        { includeReplies: false }
+      );
+      comment.replies = repliesData.items;
+      comment.replies_page_count = repliesData.page_count;
+      comment.replies_next_page_token = repliesData.next_page_token || "";
+    } else {
+      comment.replies = [];
+      comment.replies_page_count = 0;
+      comment.replies_next_page_token = "";
+    }
+    decorated.push(comment);
+  }
+  return decorated;
+}
+
+function commentMayHaveReplies(comment) {
+  if (typeof comment.reply_count === "number") {
+    return comment.reply_count > 0;
+  }
+  const replyCount = parseNonNegativeIntegerString(comment.reply_count);
+  if (replyCount !== undefined) {
+    return replyCount > 0;
+  }
+  if (typeof comment.has_replies === "boolean") {
+    return comment.has_replies;
+  }
+  return true;
+}
+
+function parseNonNegativeIntegerString(value) {
+  if (typeof value !== "string" || !/^\d+$/.test(value)) {
+    return undefined;
+  }
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+
+function buildRepliesOperationForComment(platform, comment, parentArguments, parentData) {
+  if (!comment.comment_id) {
+    throw new Error("Cannot fetch comment replies because comment_id is missing.");
+  }
+  switch (platform.id) {
+    case "xhs":
+      {
+        const noteId = comment.note_id || parentArguments.note_id || parentData?.note_id;
+        if (!noteId) {
+          throw new Error("Cannot fetch XHS comment replies because note_id is missing.");
+        }
+        return buildDirectOperation(
+          "sub-comments",
+          {
+            tool: "xhs_get_note_sub_comments_by_comment_id",
+            toolArguments: {
+              note_id: noteId,
+              comment_id: comment.comment_id,
+            },
+          },
+          platform
+        );
+      }
+    case "douyin":
+      {
+        const awemeId = comment.aweme_id || parentArguments.aweme_id || parentData?.aweme_id;
+        if (!awemeId) {
+          throw new Error("Cannot fetch Douyin comment replies because aweme_id is missing.");
+        }
+        return buildDirectOperation(
+          "replies",
+          {
+            tool: "douyin_get_video_comment_replies_by_comment_id",
+            toolArguments: {
+              aweme_id: awemeId,
+              comment_id: comment.comment_id,
+            },
+          },
+          platform
+        );
+      }
+    case "kuaishou":
+      {
+        const photoId = comment.photo_id || parentArguments.photo_id || parentData?.photo_id;
+        if (!photoId) {
+          throw new Error("Cannot fetch Kuaishou comment replies because photo_id is missing.");
+        }
+        return buildDirectOperation(
+          "replies",
+          {
+            tool: "kuaishou_get_video_comment_replies_by_comment_id",
+            toolArguments: {
+              photo_id: photoId,
+              comment_id: comment.comment_id,
+            },
+          },
+          platform
+        );
+      }
+    default:
+      throw new Error(`Unsupported comment reply platform: ${platform.id}.`);
+  }
+}
+
 async function callMcpBackend(operation) {
   ensureSupportedNodeVersion();
   const { platform, tool } = operation;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "socialdatax-skills",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "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

@@ -40,30 +40,37 @@ Prefer the direct CLI when the agent can run shell commands. It does not require
 
 ```bash
 npx -y socialdatax-skills@latest xhs comments --note-id "<note_id>" --pretty
+npx -y socialdatax-skills@latest xhs comments --note-id "<note_id>" --all --include-replies --pretty
 npx -y socialdatax-skills@latest xhs comments --url "<note_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest xhs sub-comments --note-id "<note_id>" --comment-id "<comment_id>" --pretty
 npx -y socialdatax-skills@latest douyin comments --aweme-id "<aweme_id>" --pretty
+npx -y socialdatax-skills@latest douyin comments --aweme-id "<aweme_id>" --all --include-replies --pretty
 npx -y socialdatax-skills@latest douyin comments --url "<douyin_content_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest douyin replies --aweme-id "<aweme_id>" --comment-id "<comment_id>" --pretty
 npx -y socialdatax-skills@latest kuaishou comments --photo-id "<photo_id>" --pretty
+npx -y socialdatax-skills@latest kuaishou comments --photo-id "<photo_id>" --all --include-replies --pretty
 npx -y socialdatax-skills@latest kuaishou comments --url "<kuaishou_content_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest kuaishou replies --photo-id "<photo_id>" --comment-id "<comment_id>" --pretty
 ```
 
 Optional arguments:
 
-- XHS `--note-id <note_id>`: preferred when the note ID is already known and should anchor the comment thread.
+- 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.
 - 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.
 - `--comment-id <comment_id>`: required for reply commands; use the first-level comment ID under the same content item.
-- `--page-token <next_page_token>`: opaque pagination token; pass back exactly the token returned by the previous page and do not reuse it across content items or comments.
+- `--page-token <next_page_token>`: opaque pagination token; pass the complete returned `next_page_token` back unchanged for the same content item or comment chain. Do not modify, truncate, redact, mask, omit, normalize, rebuild, generate, or replace the middle with ellipses.
+- `--pages <n>`: fetch and merge N pages of first-level comments or replies.
+- `--all`: continue first-level comments or replies until `next_page_token` is empty; there is no default item or page cap.
+- `--max-items <n>`: stop after collecting N primary comments or replies.
+- `--include-replies`: for first-level `comments` commands only, also fetch all second-level replies under each returned first-level comment.
 - `--pretty`: output formatting only.
 - Kuaishou `--photo-id <photo_id>`: preferred when the Kuaishou work photo_id is already known and should anchor the comment thread.
 
 Use either the content ID option or the URL option for first-level comments, not both. For reply commands, use the content ID together with `--comment-id`.
 
-The command prints JSON with `platform`, `tool`, `arguments`, and `data`.
+The command prints JSON with `platform`, `tool`, `arguments`, and `data`. Multi-page output keeps merged primary comments in `data.items` and adds `page_count`, `item_count`, and the next-page marker. With `--include-replies`, each first-level comment includes `replies`, `replies_page_count`, and `replies_next_page_token`.
 
 ## Safety Boundary
 
@@ -84,14 +91,14 @@ MCP tools matching the direct CLI commands above:
 - `kuaishou_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 note ID is known.
+- `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_sub_comments_by_comment_id`: use when the note ID and first-level comment ID are known.
+- `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`.
-- `douyin_get_video_comment_replies_by_comment_id`: use when the aweme_id and first-level comment ID are known.
+- `douyin_get_video_comment_replies_by_comment_id`: use when both aweme_id and first-level comment ID are known; use page_token to continue pagination.
 
-Comment pagination uses `page_token`. Pass back exactly the returned `next_page_token`; tokens are bound to the current content item and should not be reused across objects.
+Comment pagination uses opaque `page_token` values. Pass the complete returned `next_page_token` back unchanged for the same content item or comment chain. Do not modify, truncate, redact, mask, omit, normalize, rebuild, generate, or replace the middle with ellipses. Prefer CLI `--pages`, `--all`, and `--include-replies` when the user asks for multiple pages or a full first-level plus second-level comment tree.
 For Douyin comments and replies, continue only when `next_page_token` is non-empty; an empty string means there are no more comments or replies to request.
 XHS reply pagination also uses `page_token` and is bound to the current comment.
 - `kuaishou_get_video_comments_by_photo_id`: use when the photo_id is known.

package/skills/media-detail/SKILL.md

@@ -49,7 +49,7 @@ npx -y socialdatax-skills@latest kuaishou detail --url "<kuaishou_content_url_or
 
 Optional arguments:
 
-- XHS `--note-id <note_id>`: preferred when the note ID is already known from search, comments, or a previous detail result.
+- XHS `--note-id <note_id>`: use the complete 24-character lowercase hexadecimal `note_id` returned from search, comments, creator note lists, or a previous detail result; do not pass only a prefix.
 - XHS `--url <note_url_or_share_text>`: use for a note link, short link, or share text.
 - Douyin `--aweme-id <aweme_id>`: preferred when the Douyin work ID is already known.
 - Douyin `--url <douyin_content_url_or_share_text>`: use for a Douyin content page URL, short link, or share text; do not pass `video.play_url`.
@@ -77,7 +77,7 @@ MCP tools matching the direct CLI commands above:
 - `kuaishou_get_video_detail_by_url`
 
 If MCP tools are already available in the current agent, use one of these tools:
-- `xhs_get_note_detail_by_note_id`: use when a note ID is already known.
+- `xhs_get_note_detail_by_note_id`: use when the complete 24-character lowercase hexadecimal `note_id` is already known; do not pass only a prefix.
 - `xhs_get_note_detail_by_note_url`: use for note URLs, short links, or share text.
 - `douyin_get_video_detail_by_aweme_id`: use when an aweme_id is already known.
 - `douyin_get_video_detail_by_url`: use for Douyin content page URLs, short links, or share text; do not pass playback URLs such as `video.play_url`.
@@ -87,6 +87,8 @@ If MCP tools are already available in the current agent, use one of these tools:
 ## Output Guidance
 
 Return factual fields such as title or description, content, author, publish time, interaction counts, images, and media summary when available.
+For XHS detail results, preserve any returned `note_url` exactly, including `xsec_token` query parameters. Do not modify, truncate, redact, mask, normalize, rebuild, or synthesize the URL from `note_id`; if `note_url` is null, show the `note_id` or say that no directly openable full link is available.
+For XHS `note_id`, copy the complete 24-character lowercase hexadecimal ID exactly; do not pass or display only a prefix.
 For Douyin detail, include `content_type` when available.
 For Douyin detail, use `images` for image/text posts; `video` is the platform player resource and may be audio for image/text posts; `music` is the bound music or original-sound asset.
 Detail access is read-only and does not provide account actions.

package/skills/media-search/SKILL.md

@@ -40,8 +40,11 @@ Prefer the direct CLI when the agent can run shell commands. It does not require
 
 ```bash
 npx -y socialdatax-skills@latest xhs search --keyword "<keyword>" --pretty
+npx -y socialdatax-skills@latest xhs search --keyword "<keyword>" --pages 3 --pretty
 npx -y socialdatax-skills@latest douyin search --keyword "<keyword>" --pretty
+npx -y socialdatax-skills@latest douyin search --keyword "<keyword>" --pages 3 --pretty
 npx -y socialdatax-skills@latest kuaishou search --keyword "<keyword>" --pretty
+npx -y socialdatax-skills@latest kuaishou search --keyword "<keyword>" --pages 3 --pretty
 ```
 
 Required arguments:
@@ -56,13 +59,17 @@ Optional arguments:
 - XHS `--sort-type <general|time_descending|like_count_descending|comment_count_descending|collect_count_descending>`: optional sort value; omit it for default sorting.
 - XHS `--note-type <all|image|video>`: optional note type filter; default is `all`.
 - XHS `--publish-time-range <all|day|week|half_year>`: optional publish-time filter; default is `all`.
-- Douyin `--page-token <next_page_token>`: opaque pagination token returned by the previous page.
+- Douyin `--page-token <next_page_token>`: opaque pagination token; omit it on the first search request. Continue only with the complete returned `next_page_token` from the same search pagination chain. Do not modify, truncate, redact, mask, omit, normalize, rebuild, generate, or replace the middle with ellipses.
 - Douyin `--sort-type <general|time_descending|like_count_descending>`: optional sort value; omit it for the default sort.
 - Douyin `--publish-time-range <all|day|week|half_year>`: optional publish-time filter; omit it for no publish-time filter.
 - Douyin `--duration-range <all|under_1_minute|one_to_five_minutes|over_5_minutes>`: optional duration filter; omit it for no duration filter.
 - Douyin `--content-type <all|video|image>`: optional content type filter; omit it for all content types.
+- XHS `--pages <n>`: fetch and merge N search pages from the current starting point; continue with returned `next_page`.
+- Douyin `--pages <n>`: fetch and merge N search pages from the current starting point; continue with returned `next_page_token`.
+- Kuaishou `--pages <n>`: fetch and merge N search pages from the current starting point; continue with returned `next_page_token`.
+- `--max-items <n>`: stop after collecting N search results.
 - `--pretty`: output formatting only.
-- Kuaishou `--page-token <next_page_token>`: opaque pagination token returned by the previous page.
+- Kuaishou `--page-token <next_page_token>`: opaque pagination token; omit it on the first search request. Continue only with the complete returned `next_page_token` from the same search pagination chain. Do not modify, truncate, redact, mask, omit, normalize, rebuild, generate, or replace the middle with ellipses.
 
 XHS sort values:
 - `general`: default sorting.
@@ -104,9 +111,10 @@ Douyin content type filter values:
 - `video`: video works.
 - `image`: image/text posts.
 
-The command prints JSON with `platform`, `tool`, `arguments`, and `data`.
+The command prints JSON with `platform`, `tool`, `arguments`, and `data`. Search supports `--pages` and `--max-items`, but not `--all`, because search has no stable complete-result boundary. Multi-page output keeps merged results in `data.items` and adds `page_count`, `item_count`, and the next-page marker.
 Kuaishou search pagination:
 - Continue only when `next_page_token` is not empty.
+- Pass the complete returned `next_page_token` back unchanged as `page_token` for the same search pagination chain. Do not modify, truncate, redact, mask, omit, normalize, rebuild, generate, or replace the middle with ellipses.
 
 ## Safety Boundary
 
@@ -131,21 +139,27 @@ Use the same meanings as the CLI XHS sort and filter values above.
 
 For Douyin, call `douyin_search_videos` with:
 - `keyword`: required search phrase or topic.
-- `page_token`: optional opaque pagination token from the previous page.
+- `page_token`: optional opaque pagination token. Continue only with the complete returned `next_page_token` from the same search pagination chain. Do not modify, truncate, redact, mask, omit, normalize, rebuild, generate, or replace the middle with ellipses.
+Do not pass `page` to `douyin_search_videos`; omit `page_token` on the first request.
 - `sort_type`: optional, one of `general`, `time_descending`, `like_count_descending`; omit it for the default sort.
 - `publish_time_range`: optional publish-time filter, one of `all`, `day`, `week`, `half_year`; omit it for no publish-time filter.
 - `duration_range`: optional duration filter, one of `all`, `under_1_minute`, `one_to_five_minutes`, `over_5_minutes`; omit it for no duration filter.
 - `content_type`: optional content type filter, one of `all`, `video`, `image`; omit it for all content types.
 
 Continue XHS pagination only when `next_page` is not `null`, and keep the same `keyword`, `sort_type`, `note_type`, and `publish_time_range` while changing only `page`.
-Continue Douyin pagination only when `next_page_token` is not empty.
+Continue Douyin pagination only when `next_page_token` is not empty. Pass the complete returned `next_page_token` back unchanged as `page_token` for the same keyword and filter chain.
 Do not stop only because one page has empty `items`.
 For Kuaishou, call `kuaishou_search_videos` with:
-Continue Kuaishou pagination only when `next_page_token` is not empty.
+- `keyword`: required search phrase or topic.
+- `page_token`: optional opaque pagination token. Continue only with the complete returned `next_page_token` from the same search pagination chain. Do not modify, truncate, redact, mask, omit, normalize, rebuild, generate, or replace the middle with ellipses.
+Do not pass `page` to `kuaishou_search_videos`; omit `page_token` on the first request.
+Continue Kuaishou pagination only when `next_page_token` is not empty. Pass the complete returned `next_page_token` back unchanged as `page_token` for the same keyword chain.
 
 ## Output Guidance
 
 Summarize visible evidence separately from interpretation. Include useful content IDs, URLs, titles or descriptions, authors, counts, and publish time when the user needs traceability.
+For XHS search results, preserve any returned `note_url` exactly, including `xsec_token` query parameters. Do not modify, truncate, redact, mask, normalize, rebuild, or synthesize the URL from `note_id`.
+For XHS `note_id`, copy the complete 24-character lowercase hexadecimal ID exactly; do not pass or display only a prefix.
 For Douyin search results, include `content_type` when the user needs traceability.
 For Douyin image/text search results, use returned `images` and treat `video.media_type="audio"` as an audio player resource rather than a video post.
 For Kuaishou search results, include `photo_id`, `share_url`, author facts, and visible interaction counts when the user needs traceability.

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

@@ -41,12 +41,16 @@ Prefer the direct CLI when the agent can run shell commands. It does not require
 
 ```bash
 npx -y socialdatax-skills@latest xhs user-posts --user-id "<user_id>" --pretty
+npx -y socialdatax-skills@latest xhs user-posts --user-id "<user_id>" --all --pretty
 npx -y socialdatax-skills@latest xhs user-posts --profile-url "<profile_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest douyin user-posts --sec-user-id "<sec_user_id>" --pretty
+npx -y socialdatax-skills@latest douyin user-posts --sec-user-id "<sec_user_id>" --all --pretty
 npx -y socialdatax-skills@latest douyin user-posts --profile-url "<profile_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest douyin user-series --sec-user-id "<sec_user_id>" --pretty
+npx -y socialdatax-skills@latest douyin user-series --sec-user-id "<sec_user_id>" --all --pretty
 npx -y socialdatax-skills@latest douyin user-series --profile-url "<profile_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest kuaishou user-posts --user-id "<user_id>" --pretty
+npx -y socialdatax-skills@latest kuaishou user-posts --user-id "<user_id>" --all --pretty
 npx -y socialdatax-skills@latest kuaishou user-posts --profile-url "<profile_url_or_share_text>" --pretty
 ```
 
@@ -57,14 +61,17 @@ Optional arguments:
 - Douyin `--sec-user-id <sec_user_id>`: preferred when the creator sec_user_id is already known.
 - Douyin `--profile-url <profile_url_or_share_text>`: use for a profile URL, short link, or profile share text.
 - Douyin `user-series`: use for a creator's short-drama series list instead of regular published works.
-- `--page-token <next_page_token>`: opaque pagination token; pass back exactly the token returned by the previous page and do not reuse it across users.
+- `--page-token <next_page_token>`: opaque pagination token; pass the complete returned `next_page_token` back unchanged for the same creator content-list or series chain. Do not modify, truncate, redact, mask, omit, normalize, rebuild, generate, or replace the middle with ellipses.
+- `--pages <n>`: fetch and merge N pages of creator content or creator series.
+- `--all`: continue until `next_page_token` is empty; there is no default item or page cap.
+- `--max-items <n>`: stop after collecting N creator content or series items.
 - `--pretty`: output formatting only.
 - Kuaishou `--user-id <user_id>`: preferred when the creator user_id is already known.
 - Kuaishou `--profile-url <profile_url_or_share_text>`: use for a profile URL, short link, or profile share text.
 
 Use either the ID option or the profile URL option for a single command, not both.
 
-The command prints JSON with `platform`, `tool`, `arguments`, and `data`.
+The command prints JSON with `platform`, `tool`, `arguments`, and `data`. Multi-page output keeps merged creator content or series items in `data.items` and adds `page_count`, `item_count`, and `next_page_token`.
 
 ## Safety Boundary
 
@@ -91,14 +98,15 @@ If MCP tools are already available in the current agent, use one of these tools:
 - `douyin_get_user_series_by_sec_user_id`: preferred for creator short-drama series when `sec_user_id` is already known.
 - `douyin_get_user_series_by_profile_url`: use for creator short-drama series from profile URLs, short links, or profile share text.
 
-Creator content-list and series pagination use `page_token`. Pass back exactly the returned `next_page_token`; tokens are bound to the current user and command family and should not be reused across users.
+Creator content-list and series pagination use opaque `page_token` values. Pass the complete returned `next_page_token` back unchanged for the same user and command family. Do not modify, truncate, redact, mask, omit, normalize, rebuild, generate, or replace the middle with ellipses. Prefer CLI `--pages`, `--all`, and `--max-items` when the user asks for multiple pages or all available creator content.
 - `kuaishou_get_user_posted_videos_by_user_id`: preferred when `user_id` is already known.
 - `kuaishou_get_user_posted_videos_by_profile_url`: use for profile URLs, short links, or profile share text.
-Kuaishou creator work pagination uses `page_token`; pass back exactly the returned `next_page_token` and do not reuse it across users.
+Kuaishou creator work pagination uses opaque `page_token` values; pass the complete returned `next_page_token` back unchanged for the same user. Do not modify, truncate, redact, mask, omit, normalize, rebuild, generate, or replace the middle with ellipses.
 
 ## Output Guidance
 
 Summarize content-list evidence by title or description, summary, publish time, interaction counts, media links, and content type when present.
+For XHS creator note-list results, copy each returned `note_id` as the complete 24-character lowercase hexadecimal ID exactly; do not pass or display only a prefix.
 For Douyin image/text posts, use `image_urls` rather than assuming a video playback URL exists.
 For Douyin short-drama series, report series IDs, titles, descriptions, covers, prices, and author facts when present.
 Use returned content IDs to chain into detail or comment analysis when needed.

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

@@ -57,22 +57,31 @@ Prefer the direct CLI when the agent can run shell commands. It does not require
 ```bash
 npx -y socialdatax-skills@latest xhs hot-search --pretty
 npx -y socialdatax-skills@latest xhs search --keyword "<keyword>" --pretty
+npx -y socialdatax-skills@latest xhs search --keyword "<keyword>" --pages 3 --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>" --all --include-replies --pretty
 npx -y socialdatax-skills@latest xhs user-info --user-id "<user_id>" --pretty
 npx -y socialdatax-skills@latest xhs user-posts --user-id "<user_id>" --pretty
+npx -y socialdatax-skills@latest xhs user-posts --user-id "<user_id>" --all --pretty
 npx -y socialdatax-skills@latest douyin hot-search --pretty
 npx -y socialdatax-skills@latest douyin search --keyword "<keyword>" --pretty
+npx -y socialdatax-skills@latest douyin search --keyword "<keyword>" --pages 3 --pretty
 npx -y socialdatax-skills@latest douyin detail --aweme-id "<aweme_id>" --pretty
 npx -y socialdatax-skills@latest douyin comments --aweme-id "<aweme_id>" --pretty
+npx -y socialdatax-skills@latest douyin comments --aweme-id "<aweme_id>" --all --include-replies --pretty
 npx -y socialdatax-skills@latest douyin user-info --sec-user-id "<sec_user_id>" --pretty
 npx -y socialdatax-skills@latest douyin user-posts --sec-user-id "<sec_user_id>" --pretty
+npx -y socialdatax-skills@latest douyin user-posts --sec-user-id "<sec_user_id>" --all --pretty
 npx -y socialdatax-skills@latest kuaishou hot-search --pretty
 npx -y socialdatax-skills@latest kuaishou search --keyword "<keyword>" --pretty
+npx -y socialdatax-skills@latest kuaishou search --keyword "<keyword>" --pages 3 --pretty
 npx -y socialdatax-skills@latest kuaishou detail --photo-id "<photo_id>" --pretty
 npx -y socialdatax-skills@latest kuaishou comments --photo-id "<photo_id>" --pretty
+npx -y socialdatax-skills@latest kuaishou comments --photo-id "<photo_id>" --all --include-replies --pretty
 npx -y socialdatax-skills@latest kuaishou user-info --user-id "<user_id>" --pretty
 npx -y socialdatax-skills@latest kuaishou user-posts --user-id "<user_id>" --pretty
+npx -y socialdatax-skills@latest kuaishou user-posts --user-id "<user_id>" --all --pretty
 ```
 
 Additional direct CLI entrypoints:
@@ -87,6 +96,7 @@ npx -y socialdatax-skills@latest douyin comments --url "<douyin_content_url_or_s
 npx -y socialdatax-skills@latest douyin user-info --profile-url "<profile_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest douyin user-posts --profile-url "<profile_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest douyin user-series --sec-user-id "<sec_user_id>" --pretty
+npx -y socialdatax-skills@latest douyin user-series --sec-user-id "<sec_user_id>" --all --pretty
 npx -y socialdatax-skills@latest douyin user-series --profile-url "<profile_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest xhs sub-comments --note-id "<note_id>" --comment-id "<comment_id>" --pretty
 npx -y socialdatax-skills@latest douyin replies --aweme-id "<aweme_id>" --comment-id "<comment_id>" --pretty
@@ -110,7 +120,12 @@ Required arguments:
 
 Optional arguments:
 
-- `--page` and `--page-token`: continue only with returned next-page values and keep the original topic, content item, or creator target stable.
+- XHS numeric `page` is only for XHS search; Douyin and Kuaishou search use `page_token` only and do not accept `page`. Omit `page_token` on the first Douyin/Kuaishou search request, and continue only with the complete returned `next_page_token` from the same chain.
+- `--page-token <next_page_token>`: use for Douyin/Kuaishou search continuation and for token-paginated comments, replies, creator posts, creator notes, and creator series. Keep the original topic, content item, or creator target stable. Do not modify, truncate, redact, mask, omit, normalize, rebuild, generate, or replace the middle with ellipses.
+- `--pages <n>`: fetch and merge N pages for search, comments, replies, creator posts, or creator series.
+- `--all`: fetch comments, replies, creator posts, or creator series until `next_page_token` is empty; do not use it for search.
+- `--max-items <n>`: stop after collecting N primary results.
+- `--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 or Douyin keyword research commands when the user asks for filtering; Kuaishou search currently uses `--keyword` and optional `--page-token`.
 - `--comment-id`: required for reply/sub-comment commands together with the content ID.
 - `--pretty`: output formatting only.
@@ -171,7 +186,7 @@ MCP tools matching the direct CLI commands above:
 - `kuaishou_get_video_comment_replies_by_comment_id`
 
 Use the automatically listed MCP tools above as the source of truth for tool names. Pick the narrowest tool for the user's platform and task.
-Continue pagination only when a returned next-page value is present, and keep the user's original topic, URL, creator target, or platform stable while changing only the page cursor or page number.
+Use numeric `page` only for `xhs_search_notes`. Do not pass `page` to `douyin_search_videos` or `kuaishou_search_videos`; omit `page_token` on the first request and pass only the complete returned `next_page_token` when continuing the same chain.
 
 ## Output Guidance