socialdatax-skills 0.2.12 → 0.2.13

package/README.md

@@ -46,12 +46,12 @@ Common search phrases for this skill package:
 
 ## Platform MCPs
 
-- XHS hosted MCP endpoint: `https://mcp.52choujiang.com/xhs/mcp`
-- Douyin hosted MCP endpoint: `https://mcp.52choujiang.com/douyin/mcp`
-- Kuaishou hosted MCP endpoint: `https://mcp.52choujiang.com/kuaishou/mcp`
-- Weibo hosted MCP endpoint: `https://mcp.52choujiang.com/weibo/mcp`
-- WeChat Channels hosted MCP endpoint: `https://mcp.52choujiang.com/wechat/mcp`
-- Sensitive Check hosted MCP endpoint: `https://mcp.52choujiang.com/sensitive-check/mcp`
+- XHS hosted MCP endpoint: `https://mcp.socialdatax.com/xhs/mcp`
+- Douyin hosted MCP endpoint: `https://mcp.socialdatax.com/douyin/mcp`
+- Kuaishou hosted MCP endpoint: `https://mcp.socialdatax.com/kuaishou/mcp`
+- Weibo hosted MCP endpoint: `https://mcp.socialdatax.com/weibo/mcp`
+- WeChat Channels hosted MCP endpoint: `https://mcp.socialdatax.com/wechat/mcp`
+- Sensitive Check hosted MCP endpoint: `https://mcp.socialdatax.com/sensitive-check/mcp`
 - Hosted transport: `streamable-http`
 - Authentication: `Authorization: Bearer <SOCIALDATAX_API_KEY>`
 - Website: <https://socialdatax.com>
@@ -68,7 +68,7 @@ Common search phrases for this skill package:
 - Sensitive Check MCP server name: `sensitive-check`
 - Sensitive 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.12`
+- Current public capability version: `0.2.13`
 
 ## Direct CLI
 
@@ -78,6 +78,7 @@ Examples:
 
 ```bash
 npx -y socialdatax-skills@latest xhs search --keyword "露营" --pretty
+npx -y socialdatax-skills@latest xhs search --keyword "露营" --since-days 7 --pages 2 --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
@@ -85,6 +86,7 @@ npx -y socialdatax-skills@latest xhs comments --note-id "<note_id>" --all --incl
 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
+npx -y socialdatax-skills@latest xhs user-posts --user-id "<user_id>" --since-days 30 --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
@@ -143,6 +145,8 @@ For XHS outputs with a returned `note_url` field, when `note_url` is non-null, p
 
 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 search and creator content-list commands, use `--since-days <1-365>` to keep only items whose public `publish_time` is within the last N days. Search remains bounded by `--pages` and does not promise complete platform coverage; creator content lists continue until the publish-time boundary when `--pages` is omitted.
+
 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`.

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.12";
+const PACKAGE_VERSION = "0.2.13";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
 const LOG_PREFIX = `[${PACKAGE_NAME}]`;
 const MIN_NODE_VERSION = "20.18.1";
@@ -85,6 +85,7 @@ const XHS_DIRECT_ACTION_OPTIONS = {
     "pages",
     "all",
     "maxItems",
+    "sinceDays",
     "sortType",
     "noteType",
     "publishTimeRange",
@@ -112,7 +113,16 @@ const XHS_DIRECT_ACTION_OPTIONS = {
     "pretty",
   ],
   "user-info": ["userId", "profileUrl", "pretty"],
-  "user-posts": ["userId", "profileUrl", "pageToken", "pages", "all", "maxItems", "pretty"],
+  "user-posts": [
+    "userId",
+    "profileUrl",
+    "pageToken",
+    "pages",
+    "all",
+    "maxItems",
+    "sinceDays",
+    "pretty",
+  ],
 };
 const XHS_DIRECT_ACTION_NAMES = Object.keys(XHS_DIRECT_ACTION_OPTIONS).join(", ");
 const XHS_OPTION_DISPLAY_NAMES = {
@@ -126,6 +136,7 @@ const XHS_OPTION_DISPLAY_NAMES = {
   pageToken: "--page-token",
   pages: "--pages",
   maxItems: "--max-items",
+  sinceDays: "--since-days",
   all: "--all",
   includeReplies: "--include-replies",
   profileUrl: "--profile-url",
@@ -151,6 +162,7 @@ const DOUYIN_DIRECT_ACTION_OPTIONS = {
     "pages",
     "all",
     "maxItems",
+    "sinceDays",
     "sortType",
     "publishTimeRange",
     "durationRange",
@@ -179,7 +191,16 @@ const DOUYIN_DIRECT_ACTION_OPTIONS = {
     "pretty",
   ],
   "user-info": ["secUserId", "profileUrl", "pretty"],
-  "user-posts": ["secUserId", "profileUrl", "pageToken", "pages", "all", "maxItems", "pretty"],
+  "user-posts": [
+    "secUserId",
+    "profileUrl",
+    "pageToken",
+    "pages",
+    "all",
+    "maxItems",
+    "sinceDays",
+    "pretty",
+  ],
   "user-series": ["secUserId", "profileUrl", "pageToken", "pages", "all", "maxItems", "pretty"],
 };
 const DOUYIN_DIRECT_ACTION_NAMES = Object.keys(DOUYIN_DIRECT_ACTION_OPTIONS).join(", ");
@@ -197,6 +218,7 @@ const DOUYIN_OPTION_DISPLAY_NAMES = {
   pageToken: "--page-token",
   pages: "--pages",
   maxItems: "--max-items",
+  sinceDays: "--since-days",
   all: "--all",
   includeReplies: "--include-replies",
   sortType: "--sort-type",
@@ -211,7 +233,7 @@ const DOUYIN_OPTION_DISPLAY_NAMES = {
 };
 const KUAISHOU_DIRECT_ACTION_OPTIONS = {
   "hot-search": ["pretty"],
-  search: ["keyword", "pageToken", "pages", "all", "maxItems", "pretty"],
+  search: ["keyword", "pageToken", "pages", "all", "maxItems", "sinceDays", "pretty"],
   detail: ["photoId", "url", "pretty"],
   comments: [
     "photoId",
@@ -234,7 +256,16 @@ const KUAISHOU_DIRECT_ACTION_OPTIONS = {
     "pretty",
   ],
   "user-info": ["userId", "profileUrl", "pretty"],
-  "user-posts": ["userId", "profileUrl", "pageToken", "pages", "all", "maxItems", "pretty"],
+  "user-posts": [
+    "userId",
+    "profileUrl",
+    "pageToken",
+    "pages",
+    "all",
+    "maxItems",
+    "sinceDays",
+    "pretty",
+  ],
 };
 const KUAISHOU_DIRECT_ACTION_NAMES = Object.keys(KUAISHOU_DIRECT_ACTION_OPTIONS).join(", ");
 const KUAISHOU_OPTION_DISPLAY_NAMES = {
@@ -242,6 +273,7 @@ const KUAISHOU_OPTION_DISPLAY_NAMES = {
   pageToken: "--page-token",
   pages: "--pages",
   maxItems: "--max-items",
+  sinceDays: "--since-days",
   all: "--all",
   includeReplies: "--include-replies",
   url: "--url",
@@ -252,7 +284,7 @@ const KUAISHOU_OPTION_DISPLAY_NAMES = {
 };
 const WEIBO_DIRECT_ACTION_OPTIONS = {
   "hot-search": ["pretty"],
-  search: ["keyword", "pageToken", "pages", "all", "maxItems", "pretty"],
+  search: ["keyword", "pageToken", "pages", "all", "maxItems", "sinceDays", "pretty"],
   detail: ["postId", "postUrl", "pretty"],
   comments: [
     "postId",
@@ -277,7 +309,16 @@ const WEIBO_DIRECT_ACTION_OPTIONS = {
   likers: ["postId", "pageToken", "pages", "all", "maxItems", "pretty"],
   reposts: ["postId", "pageToken", "pages", "all", "maxItems", "pretty"],
   "user-info": ["userId", "profileUrl", "pretty"],
-  "user-posts": ["userId", "profileUrl", "pageToken", "pages", "all", "maxItems", "pretty"],
+  "user-posts": [
+    "userId",
+    "profileUrl",
+    "pageToken",
+    "pages",
+    "all",
+    "maxItems",
+    "sinceDays",
+    "pretty",
+  ],
 };
 const WEIBO_DIRECT_ACTION_NAMES = Object.keys(WEIBO_DIRECT_ACTION_OPTIONS).join(", ");
 const WEIBO_OPTION_DISPLAY_NAMES = {
@@ -285,6 +326,7 @@ const WEIBO_OPTION_DISPLAY_NAMES = {
   pageToken: "--page-token",
   pages: "--pages",
   maxItems: "--max-items",
+  sinceDays: "--since-days",
   all: "--all",
   includeReplies: "--include-replies",
   postId: "--post-id",
@@ -301,6 +343,7 @@ const WECHAT_DIRECT_ACTION_OPTIONS = {
     "pages",
     "all",
     "maxItems",
+    "sinceDays",
     "sortType",
     "durationRange",
     "pretty",
@@ -329,7 +372,16 @@ const WECHAT_DIRECT_ACTION_OPTIONS = {
     "pretty",
   ],
   "user-info": ["userId", "pretty"],
-  "user-posts": ["userId", "url", "pageToken", "pages", "all", "maxItems", "pretty"],
+  "user-posts": [
+    "userId",
+    "url",
+    "pageToken",
+    "pages",
+    "all",
+    "maxItems",
+    "sinceDays",
+    "pretty",
+  ],
 };
 const WECHAT_DIRECT_ACTION_NAMES = Object.keys(WECHAT_DIRECT_ACTION_OPTIONS).join(", ");
 const WECHAT_SEARCH_SORT_TYPES = ["all", "latest", "popular"];
@@ -344,6 +396,7 @@ const WECHAT_OPTION_DISPLAY_NAMES = {
   pageToken: "--page-token",
   pages: "--pages",
   maxItems: "--max-items",
+  sinceDays: "--since-days",
   all: "--all",
   includeReplies: "--include-replies",
   sortType: "--sort-type",
@@ -373,7 +426,7 @@ const PLATFORMS = {
     status: "public",
     registryName: "com.52choujiang/xhs-insights",
     futureRegistryName: "com.socialdatax/xhs-insights",
-    endpoint: "https://mcp.52choujiang.com/xhs/mcp",
+    endpoint: "https://mcp.socialdatax.com/xhs/mcp",
     apiKeyEnv: API_KEY_ENV_NAMES,
     upstreamEnv: [
       "SOCIAL_MEDIA_XHS_MCP_UPSTREAM_URL",
@@ -455,7 +508,7 @@ const PLATFORMS = {
     status: "public",
     registryName: "com.52choujiang/douyin-insights",
     futureRegistryName: "com.socialdatax/douyin-insights",
-    endpoint: "https://mcp.52choujiang.com/douyin/mcp",
+    endpoint: "https://mcp.socialdatax.com/douyin/mcp",
     apiKeyEnv: API_KEY_ENV_NAMES,
     upstreamEnv: [
       "SOCIAL_MEDIA_DOUYIN_MCP_UPSTREAM_URL",
@@ -539,7 +592,7 @@ const PLATFORMS = {
     status: "public",
     registryName: "com.52choujiang/kuaishou-insights",
     futureRegistryName: "com.socialdatax/kuaishou-insights",
-    endpoint: "https://mcp.52choujiang.com/kuaishou/mcp",
+    endpoint: "https://mcp.socialdatax.com/kuaishou/mcp",
     apiKeyEnv: API_KEY_ENV_NAMES,
     upstreamEnv: [
       "SOCIAL_MEDIA_KUAISHOU_MCP_UPSTREAM_URL",
@@ -615,7 +668,7 @@ const PLATFORMS = {
     status: "public",
     registryName: "com.52choujiang/weibo-insights",
     futureRegistryName: "com.socialdatax/weibo-insights",
-    endpoint: "https://mcp.52choujiang.com/weibo/mcp",
+    endpoint: "https://mcp.socialdatax.com/weibo/mcp",
     apiKeyEnv: API_KEY_ENV_NAMES,
     upstreamEnv: [
       "SOCIAL_MEDIA_WEIBO_MCP_UPSTREAM_URL",
@@ -699,7 +752,7 @@ const PLATFORMS = {
     status: "public",
     registryName: "com.52choujiang/wechat-channels-insights",
     futureRegistryName: "com.socialdatax/wechat-channels-insights",
-    endpoint: "https://mcp.52choujiang.com/wechat/mcp",
+    endpoint: "https://mcp.socialdatax.com/wechat/mcp",
     apiKeyEnv: API_KEY_ENV_NAMES,
     upstreamEnv: [
       "SOCIAL_MEDIA_WECHAT_MCP_UPSTREAM_URL",
@@ -771,7 +824,7 @@ const PLATFORMS = {
     status: "public",
     registryName: "sensitive-check",
     futureRegistryName: "com.socialdatax/sensitive-check",
-    endpoint: "https://mcp.52choujiang.com/sensitive-check/mcp",
+    endpoint: "https://mcp.socialdatax.com/sensitive-check/mcp",
     apiKeyEnv: API_KEY_ENV_NAMES,
     upstreamEnv: [
       "SOCIALDATAX_SENSITIVE_CHECK_MCP_UPSTREAM_URL",
@@ -1015,6 +1068,9 @@ function validateDirectPaginationOptions(platformId, action, options) {
   if (options.maxItems !== undefined) {
     parsePositiveIntegerOption(options.maxItems, "--max-items");
   }
+  if (options.sinceDays !== undefined) {
+    parseSinceDaysOption(options.sinceDays);
+  }
   if (options.all && action === "search") {
     throw new Error(`--all is not supported for ${platformId} search. Use --pages instead.`);
   }
@@ -1035,6 +1091,37 @@ function parsePositiveIntegerOption(value, displayName) {
   return parsed;
 }
 
+function parseSinceDaysOption(value) {
+  const text = String(value);
+  if (!/^\d+$/.test(text)) {
+    throw new Error("--since-days must be an integer between 1 and 365.");
+  }
+  const parsed = Number(text);
+  if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 365) {
+    throw new Error("--since-days must be an integer between 1 and 365.");
+  }
+  return parsed;
+}
+
+function parseOptionalSinceDays(options) {
+  return options.sinceDays === undefined
+    ? undefined
+    : parseSinceDaysOption(options.sinceDays);
+}
+
+function nativePublishTimeRangeForSinceDays(sinceDays) {
+  if (sinceDays <= 1) {
+    return "day";
+  }
+  if (sinceDays <= 7) {
+    return "week";
+  }
+  if (sinceDays <= 180) {
+    return "half_year";
+  }
+  return undefined;
+}
+
 function parseAllowedStringOption(value, displayName, allowedValues, label) {
   const normalized = String(value).trim();
   if (!allowedValues.includes(normalized)) {
@@ -1500,6 +1587,9 @@ function printHelp() {
   console.log(`  npx -y ${PACKAGE_SPEC} xhs search --keyword "露营" --pretty`);
   console.log("      Call the XHS search tool directly and print JSON.");
   console.log("");
+  console.log(`  npx -y ${PACKAGE_SPEC} xhs search --keyword "露营" --since-days 7 --pages 2 --pretty`);
+  console.log("      Search recent XHS results and keep items published in the last 7 days.");
+  console.log("");
   console.log(`  npx -y ${PACKAGE_SPEC} xhs hot-search --pretty`);
   console.log("      Call the XHS search hot list tool directly and print JSON.");
   console.log("");
@@ -1523,6 +1613,9 @@ function printHelp() {
   console.log(`  npx -y ${PACKAGE_SPEC} xhs user-posts --user-id "<user_id>" --pretty`);
   console.log("      Call the XHS creator posts tool directly and print JSON.");
   console.log("");
+  console.log(`  npx -y ${PACKAGE_SPEC} xhs user-posts --user-id "<user_id>" --since-days 30 --pretty`);
+  console.log("      Fetch recent creator posts until the publish-time boundary is reached.");
+  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("");
@@ -1762,6 +1855,8 @@ function printHelp() {
   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("  --since-days <1-365>");
+  console.log("      Keep search or creator content-list items with publish_time in the last N days. Search stays bounded by --pages; creator lists continue until the time boundary when --pages is omitted.");
   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>");
@@ -1811,18 +1906,18 @@ function printRemovedMcpConfigHelp(command) {
   console.error("  com.socialdatax/wechat-channels-insights");
   console.error("");
   console.error("Use hosted streamable HTTP when your client supports remote MCP:");
-  console.error("  https://mcp.52choujiang.com/xhs/mcp");
-  console.error("  https://mcp.52choujiang.com/douyin/mcp");
-  console.error("  https://mcp.52choujiang.com/kuaishou/mcp");
-  console.error("  https://mcp.52choujiang.com/weibo/mcp");
-  console.error("  https://mcp.52choujiang.com/wechat/mcp");
+  console.error("  https://mcp.socialdatax.com/xhs/mcp");
+  console.error("  https://mcp.socialdatax.com/douyin/mcp");
+  console.error("  https://mcp.socialdatax.com/kuaishou/mcp");
+  console.error("  https://mcp.socialdatax.com/weibo/mcp");
+  console.error("  https://mcp.socialdatax.com/wechat/mcp");
   console.error("");
   console.error("For command/stdio-only clients, use mcp-remote:");
-  console.error(`  npx -y mcp-remote https://mcp.52choujiang.com/xhs/mcp --header "Authorization: Bearer <${PRIMARY_API_KEY_ENV}>"`);
-  console.error(`  npx -y mcp-remote https://mcp.52choujiang.com/douyin/mcp --header "Authorization: Bearer <${PRIMARY_API_KEY_ENV}>"`);
-  console.error(`  npx -y mcp-remote https://mcp.52choujiang.com/kuaishou/mcp --header "Authorization: Bearer <${PRIMARY_API_KEY_ENV}>"`);
-  console.error(`  npx -y mcp-remote https://mcp.52choujiang.com/weibo/mcp --header "Authorization: Bearer <${PRIMARY_API_KEY_ENV}>"`);
-  console.error(`  npx -y mcp-remote https://mcp.52choujiang.com/wechat/mcp --header "Authorization: Bearer <${PRIMARY_API_KEY_ENV}>"`);
+  console.error(`  npx -y mcp-remote https://mcp.socialdatax.com/xhs/mcp --header "Authorization: Bearer <${PRIMARY_API_KEY_ENV}>"`);
+  console.error(`  npx -y mcp-remote https://mcp.socialdatax.com/douyin/mcp --header "Authorization: Bearer <${PRIMARY_API_KEY_ENV}>"`);
+  console.error(`  npx -y mcp-remote https://mcp.socialdatax.com/kuaishou/mcp --header "Authorization: Bearer <${PRIMARY_API_KEY_ENV}>"`);
+  console.error(`  npx -y mcp-remote https://mcp.socialdatax.com/weibo/mcp --header "Authorization: Bearer <${PRIMARY_API_KEY_ENV}>"`);
+  console.error(`  npx -y mcp-remote https://mcp.socialdatax.com/wechat/mcp --header "Authorization: Bearer <${PRIMARY_API_KEY_ENV}>"`);
 }
 
 async function runXhsDirectCommand(args) {
@@ -2475,8 +2570,13 @@ function buildXhsSearchCall(options) {
   if (!options.keyword) {
     throw new Error("Missing --keyword for xhs search.");
   }
+  const sinceDays = parseOptionalSinceDays(options);
+  const requestedSortType =
+    options.sortType === undefined && sinceDays !== undefined
+      ? "time_descending"
+      : options.sortType || "general";
   const sortType = parseSemanticOption(
-    options.sortType || "general",
+    requestedSortType,
     "--sort-type",
     XHS_SEARCH_SORT_TYPES,
     XHS_LEGACY_SEARCH_SORT_TYPE_ALIASES,
@@ -2504,12 +2604,19 @@ function buildXhsSearchCall(options) {
   }
   if (options.sortType !== undefined) {
     toolArguments.sort_type = sortType;
+  } else if (sinceDays !== undefined) {
+    toolArguments.sort_type = "time_descending";
   }
   if (options.noteType !== undefined) {
     toolArguments.note_type = noteType;
   }
   if (options.publishTimeRange !== undefined) {
     toolArguments.publish_time_range = publishTimeRange;
+  } else if (sinceDays !== undefined) {
+    const nativeRange = nativePublishTimeRangeForSinceDays(sinceDays);
+    if (nativeRange) {
+      toolArguments.publish_time_range = nativeRange;
+    }
   }
   return {
     tool: "xhs_search_notes",
@@ -2576,6 +2683,7 @@ function buildDouyinSearchCall(options) {
   if (!options.keyword) {
     throw new Error("Missing --keyword for douyin search.");
   }
+  const sinceDays = parseOptionalSinceDays(options);
   const toolArguments = {
     keyword: options.keyword,
   };
@@ -2586,6 +2694,8 @@ function buildDouyinSearchCall(options) {
       DOUYIN_SEARCH_SORT_TYPES,
       DOUYIN_SEARCH_SORT_TYPES.join(", ")
     );
+  } else if (sinceDays !== undefined) {
+    toolArguments.sort_type = "time_descending";
   }
   if (options.publishTimeRange !== undefined) {
     toolArguments.publish_time_range = parseAllowedStringOption(
@@ -2594,6 +2704,11 @@ function buildDouyinSearchCall(options) {
       DOUYIN_SEARCH_PUBLISH_TIME_RANGES,
       DOUYIN_SEARCH_PUBLISH_TIME_RANGES.join(", ")
     );
+  } else if (sinceDays !== undefined) {
+    const nativeRange = nativePublishTimeRangeForSinceDays(sinceDays);
+    if (nativeRange) {
+      toolArguments.publish_time_range = nativeRange;
+    }
   }
   if (options.durationRange !== undefined) {
     toolArguments.duration_range = parseAllowedStringOption(
@@ -2656,6 +2771,7 @@ function buildWechatSearchCall(options) {
   if (!options.keyword) {
     throw new Error("Missing --keyword for wechat search.");
   }
+  const sinceDays = parseOptionalSinceDays(options);
   const toolArguments = {
     keyword: options.keyword,
   };
@@ -2666,6 +2782,8 @@ function buildWechatSearchCall(options) {
       WECHAT_SEARCH_SORT_TYPES,
       WECHAT_SEARCH_SORT_TYPES.join(", ")
     );
+  } else if (sinceDays !== undefined) {
+    toolArguments.sort_type = "latest";
   }
   if (options.durationRange !== undefined) {
     toolArguments.duration_range = parseAllowedStringOption(
@@ -2875,7 +2993,8 @@ function shouldUsePaginatedDirectOutput(options) {
     options.all ||
       options.pages !== undefined ||
       options.maxItems !== undefined ||
-      options.includeReplies
+      options.includeReplies ||
+      options.sinceDays !== undefined
   );
 }
 
@@ -2897,6 +3016,7 @@ function parseDirectPaginationOptions(options) {
       options.maxItems === undefined
         ? undefined
         : parsePositiveIntegerOption(options.maxItems, "--max-items"),
+    sinceDays: parseOptionalSinceDays(options),
   };
 }
 
@@ -2905,7 +3025,14 @@ async function collectPaginatedDirectData(
   pagination,
   { includeReplies = false } = {}
 ) {
-  const pageLimit = pagination.all ? Number.POSITIVE_INFINITY : pagination.pages || 1;
+  const pageLimit =
+    pagination.all || shouldAutoPaginateSinceDays(operation, pagination)
+      ? Number.POSITIVE_INFINITY
+      : pagination.pages || 1;
+  const sinceDaysCutoff =
+    pagination.sinceDays === undefined
+      ? undefined
+      : cutoffPublishTimeForSinceDays(pagination.sinceDays);
   const collectedItems = [];
   const itemDedupeState = createPaginatedItemDedupeState();
   const seenNextMarkers = initialPaginationMarkers(operation);
@@ -2914,6 +3041,7 @@ async function collectPaginatedDirectData(
   let nextMarker;
   let parentContextData = {};
   let currentOperation = cloneDirectOperation(operation);
+  let stoppedBySinceDays = false;
 
   while (pageCount < pageLimit) {
     const pageData = await callDirectOperation(currentOperation);
@@ -2926,8 +3054,12 @@ async function collectPaginatedDirectData(
       directPageItems(pageData),
       itemDedupeState
     );
+    const filteredPage = filterItemsBySinceDays(pageItems, sinceDaysCutoff);
+    if (shouldStopAtSinceDaysBoundary(operation, sinceDaysCutoff, pageItems)) {
+      stoppedBySinceDays = true;
+    }
     const candidateItems = itemsForRemainingLimit(
-      pageItems,
+      filteredPage.items,
       collectedItems.length,
       pagination.maxItems
     );
@@ -2948,6 +3080,7 @@ async function collectPaginatedDirectData(
     if (
       !nextMarker ||
       reachedMaxItems(collectedItems, pagination.maxItems) ||
+      stoppedBySinceDays ||
       pageCount >= pageLimit
     ) {
       if (markerRepeated) {
@@ -2971,6 +3104,7 @@ async function collectPaginatedDirectData(
     items: collectedItems,
     pageCount,
     nextMarker,
+    stoppedBySinceDays,
   });
 }
 
@@ -2985,6 +3119,54 @@ function directPageItems(pageData) {
   return Array.isArray(pageData?.items) ? pageData.items : [];
 }
 
+function shouldAutoPaginateSinceDays(operation, pagination) {
+  return (
+    operation.operation === "user-posts" &&
+    pagination.sinceDays !== undefined &&
+    pagination.pages === undefined
+  );
+}
+
+function cutoffPublishTimeForSinceDays(sinceDays) {
+  return Math.floor(Date.now() / 1000) - sinceDays * 86400;
+}
+
+function itemPublishTimeSeconds(item) {
+  const value = item?.publish_time;
+  const timestamp =
+    typeof value === "number"
+      ? value
+      : typeof value === "string"
+        ? Number(value)
+        : NaN;
+  if (!Number.isFinite(timestamp) || timestamp <= 0) {
+    return undefined;
+  }
+  return timestamp;
+}
+
+function filterItemsBySinceDays(items, cutoffPublishTime) {
+  if (cutoffPublishTime === undefined) {
+    return { items };
+  }
+  return {
+    items: items.filter((item) => {
+      const publishTime = itemPublishTimeSeconds(item);
+      return publishTime !== undefined && publishTime >= cutoffPublishTime;
+    }),
+  };
+}
+
+function shouldStopAtSinceDaysBoundary(operation, cutoffPublishTime, items) {
+  if (operation.operation !== "user-posts" || cutoffPublishTime === undefined) {
+    return false;
+  }
+  return items.some((item) => {
+    const publishTime = itemPublishTimeSeconds(item);
+    return publishTime !== undefined && publishTime < cutoffPublishTime;
+  });
+}
+
 function createPaginatedItemDedupeState() {
   return { seenKeys: new Set() };
 }
@@ -3204,6 +3386,7 @@ function buildPaginatedData({
   items,
   pageCount,
   nextMarker,
+  stoppedBySinceDays,
 }) {
   const data = {
     ...(lastPageData && typeof lastPageData === "object" ? lastPageData : {}),
@@ -3214,6 +3397,9 @@ function buildPaginatedData({
   };
   delete data.next_page;
   data.next_page_token = nextMarker || "";
+  if (stoppedBySinceDays) {
+    data.stopped_by_since_days = true;
+  }
   return data;
 }
 

package/package.json

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

package/skills/media-search/SKILL.md

@@ -76,6 +76,7 @@ Optional arguments:
 - 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.
+- `--since-days <1-365>`: keep only results whose public `publish_time` is within the last N days. Search remains bounded by `--pages` and does not promise complete platform coverage.
 - `--pretty`: output formatting only.
 - 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.
 - Weibo `--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.
@@ -126,6 +127,7 @@ Douyin content type filter values:
 - `image`: image/text posts.
 
 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.
+With CLI `--since-days <n>`, XHS and Douyin search automatically prefer newest-first sorting and the closest native publish-time range unless the user explicitly sets sort or publish-time filters; WeChat Channels search defaults to `latest`; Kuaishou and Weibo only apply CLI-side `publish_time` filtering.
 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.
@@ -198,6 +200,7 @@ Do not pass `page` to `wechat_search_videos`; omit `page_token` on the first req
 - `sort_type`: optional, one of `all`, `latest`, `popular`; omit it for the default sort.
 - `duration_range`: optional duration filter, one of `all`, `under_5_min`, `between_5_and_20_min`, `over_20_min`; omit it for no duration filter.
 Continue WeChat Channels 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.
+`--since-days` uses CLI-side filtering only and is not an MCP tool argument; for MCP-only calls, request newest-first/native publish-time filters where available and filter returned `publish_time` values in your analysis.
 
 ## Output Guidance
 

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

@@ -73,6 +73,7 @@ Optional arguments:
 - `--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.
+- `--since-days <1-365>`: keep only creator content whose public `publish_time` is within the last N days. When `--pages` is omitted, the CLI continues creator content lists until the publish-time boundary is reached.
 - `--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.
@@ -84,6 +85,7 @@ Optional arguments:
 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`. Multi-page output keeps merged creator content or series items in `data.items` and adds `page_count`, `item_count`, and `next_page_token`.
+For recent creator research, prefer CLI `--since-days 30` or another user-specified day window. `--since-days` applies to creator content lists only, not Douyin `user-series`.
 
 ## Safety Boundary
 
@@ -124,6 +126,7 @@ Weibo creator post pagination uses opaque `page_token` values; pass the complete
 - `wechat_get_user_posted_videos_by_user_id`: preferred when the WeChat Channels / 视频号 `@finder` user_id is already known.
 - `wechat_get_user_posted_videos_by_url`: use a WeChat Channels / 视频号 video link or share text to resolve the author and list that creator's videos.
 WeChat Channels / 视频号 creator video 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.
+`--since-days` uses CLI-side filtering only and is not an MCP tool argument; for MCP-only calls, continue pages as needed and filter returned `publish_time` values in your analysis.
 
 ## Output Guidance
 

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

@@ -168,6 +168,7 @@ Optional arguments:
 - `--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.
+- `--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`.
 - `--comment-id`: required for reply/sub-comment commands together with the content ID.
@@ -185,6 +186,7 @@ Optional arguments:
 ## Choose The Narrowest Entry
 
 Use the most specific direct CLI command for the user's task instead of forcing every request through keyword research. The command prints JSON with `platform`, `tool`, `arguments`, and `data`.
+When the user asks for recent content, pass CLI `--since-days <n>` with bounded `--pages`; keep in mind this filters returned `publish_time` values and does not promise complete platform coverage.
 
 ## Safety Boundary