socialdatax-skills 0.2.28 → 0.2.30

package/README.md

@@ -2,7 +2,7 @@
 
 This public package provides the unified skill installer and direct CLI helper for SocialDataX services.
 
-The current public tools support 小红书 / Xiaohongshu / XHS / RedNote, 抖音 / Douyin, 快手 / Kuaishou / Kwai, 微博 / Weibo, 视频号 / WeChat Channels, and 微信公众号 / WeChat Official Account article content research and analysis workflows, plus XHS local media download, Bilibili / 哔哩哔哩 / B站 local video download, and 敏感词检测 / 违禁词检查 text checks. The public skill layer is intentionally named by capability so supported services can evolve without changing the installation model.
+The current public tools support 小红书 / Xiaohongshu / XHS / RedNote, 抖音 / Douyin, 快手 / Kuaishou / Kwai, 微博 / Weibo, 视频号 / WeChat Channels, and 微信公众号 / WeChat Official Account article content research and analysis workflows, plus XHS / Douyin / Kuaishou / Weibo local media download, Bilibili / 哔哩哔哩 / B站 local video download, and 敏感词检测 / 违禁词检查 text checks. The public skill layer is intentionally named by capability so supported services can evolve without changing the installation model.
 
 - direct `npx` JSON commands for agents that can run shell commands
 - AgentSkills-compatible installers split by capability for OpenClaw, Hermes Agent, Codex, Claude Code, and general agent skill directories
@@ -10,6 +10,10 @@ The current public tools support 小红书 / Xiaohongshu / XHS / RedNote, 抖音
 
 The business implementation is privately hosted. This repository exposes only the public package, skill, and connection surface for social media content intelligence workflows. It is not a unified MCP server and does not include a registry server card; platform MCPs are published separately.
 
+## High-Intent Skill Catalog
+
+See [CATALOG.md](./CATALOG.md) for curated high-intent Agent Skill entries across SkillHub, ClawHub, ModelScope, and direct CLI usage. The catalog focuses on proven workflows such as XHS content research, comment analysis, hot topic planning, viral note research, Douyin transcript extraction, and sensitive term checks.
+
 ## Search Aliases
 
 Common search phrases for this skill package:
@@ -82,7 +86,7 @@ Common search phrases for this skill package:
 - Sensitive Words Check MCP server name: `sensitive-check`
 - Sensitive Words Check future MCP registry name: `com.socialdatax/sensitive-check`
 - Unified MCP registry name: none; this package installs skills and calls explicit platform services.
-- Current public capability version: `0.2.28`
+- Current public capability version: `0.2.30`
 
 ## Direct CLI
 
@@ -121,6 +125,7 @@ npx -y socialdatax-skills@latest douyin user-series --profile-url "<profile_url_
 npx -y socialdatax-skills@latest douyin transcript --url "<douyin_content_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest douyin transcript --aweme-id "<aweme_id>" --pretty
 npx -y socialdatax-skills@latest douyin transcript --job-id "<job_id>" --pretty
+npx -y socialdatax-skills@latest douyin download-media --url "<douyin_media_url>" --output-dir ./downloads --pretty
 npx -y socialdatax-skills@latest kuaishou hot-search --pretty
 npx -y socialdatax-skills@latest kuaishou search --keyword "露营" --pretty
 npx -y socialdatax-skills@latest kuaishou user-search --keyword "露营" --pretty
@@ -137,6 +142,7 @@ npx -y socialdatax-skills@latest kuaishou user-posts --profile-url "<profile_url
 npx -y socialdatax-skills@latest kuaishou transcript --url "<kuaishou_content_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest kuaishou transcript --photo-id "<photo_id>" --pretty
 npx -y socialdatax-skills@latest kuaishou transcript --job-id "<job_id>" --pretty
+npx -y socialdatax-skills@latest kuaishou download-media --url "<kuaishou_media_url>" --output-dir ./downloads --pretty
 npx -y socialdatax-skills@latest bilibili download --url "<bilibili_video_url_or_share_text>" --output-dir ./downloads --pretty
 npx -y socialdatax-skills@latest weibo hot-search --pretty
 npx -y socialdatax-skills@latest weibo search --keyword "露营" --pretty
@@ -155,6 +161,7 @@ npx -y socialdatax-skills@latest weibo user-posts --profile-url "<profile_url_or
 npx -y socialdatax-skills@latest weibo transcript --post-url "<weibo_post_url_or_share_text>" --pretty
 npx -y socialdatax-skills@latest weibo transcript --post-id "<post_id>" --pretty
 npx -y socialdatax-skills@latest weibo transcript --job-id "<job_id>" --pretty
+npx -y socialdatax-skills@latest weibo download-media --url "<weibo_media_url>" --output-dir ./downloads --pretty
 npx -y socialdatax-skills@latest wechat hot-search --pretty
 npx -y socialdatax-skills@latest wechat search --keyword "露营" --pretty
 npx -y socialdatax-skills@latest wechat detail --encrypted-object-id "<encrypted_object_id>" --pretty
@@ -174,7 +181,9 @@ npx -y socialdatax-skills@latest wechat transcript --job-id "<job_id>" --pretty
 npx -y socialdatax-skills@latest sensitive-check text --text "<content>" --platform xhs --pretty
 ```
 
-Most direct CLI commands print a JSON envelope with `platform`, `tool`, `arguments`, and `data`. `sensitive-check` prints `platform`, `tool`, and `data` only; it does not echo the original text in CLI output. `wechat decrypt-media` is a local save command: pass the `video.video_url` returned by WeChat detail and an `--output` file path. It saves the media locally, decrypts when needed, and does not require `SOCIALDATAX_API_KEY`. `xhs download-media` is also local: pass one image or video media URL returned by XHS detail and either `--output <file>` or `--output-dir <directory>`. It writes through a `.part` file, resumes partial downloads when the server supports range requests, skips an already existing output file, and infers common image/video extensions in `--output-dir` mode.
+Most direct CLI commands print a JSON envelope with `platform`, `tool`, `arguments`, and `data`. `sensitive-check` prints `platform`, `tool`, and `data` only; it does not echo the original text in CLI output. `wechat decrypt-media` is a local save command: pass the `video.video_url` returned by WeChat detail and an `--output` file path. It saves the media locally, decrypts when needed, and does not require `SOCIALDATAX_API_KEY`. `xhs/douyin/kuaishou/weibo download-media` is also local: pass one media URL returned by detail and either `--output <file>` or `--output-dir <directory>`. It writes through a `.part` file, resumes partial downloads when the server supports range requests, skips an already existing output file, and infers common image/video/audio extensions in `--output-dir` mode.
+
+For transcript commands, the direct CLI tries to deliver the final result in one run: submit may wait up to 210 seconds, and if `data.is_terminal` is not `true`, the CLI automatically continues matching get-job requests for up to 1200 seconds by default, with each get-job request waiting up to 240 seconds. Use positive `--max-wait-seconds <seconds>` to tune that follow-up window. Do not submit a duplicate transcript job just to poll status.
 
 `bilibili download` calls SocialDataX once to fetch short-lived download links, then downloads video and audio tracks on the local machine and merges them with local `ffmpeg`. Set `SOCIALDATAX_API_KEY`, install `ffmpeg`, and pass either `--output <file>` or `--output-dir <directory>`. The download-links request consumes 10 credits; the local track download and merge do not consume additional SocialDataX credits. Use `--ffmpeg-path <path>` when `ffmpeg` is not on `PATH`, and `--keep-tracks` to retain the separate track files after merge.
 
@@ -192,7 +201,7 @@ For commands that accept `--page-token`, continue only with the complete returne
 
 Search pagination uses `--page-token` when continuing with a returned `next_page_token`. Omit `--page-token` on the first search request and pass the complete returned `next_page_token` only when continuing the same search chain.
 
-Transcript commands submit a bounded video speech-to-text job or check an existing job. Pass exactly one entrypoint for each call: URL/share text, platform content ID, or `--job-id`. Completed get-job responses return transcript plus content context, not summary.
+Transcript commands submit a bounded video speech-to-text job or check an existing job. Pass exactly one entrypoint for each call: URL/share text, platform content ID, or `--job-id`. Direct CLI transcript commands wait and poll the same job by default; completed get-job responses return transcript plus content context, not summary.
 
 Generated Agent Skill examples include `--source-client socialdatax-skills --source-platform <marketplace> --source-skill <skill-slug>` so SocialDataX can attribute authenticated direct data CLI usage to the current marketplace Skill. Keep those values unchanged when running commands from a Skill; omit them for ad hoc CLI use. Authenticated direct data CLI commands also accept `SOCIALDATAX_SOURCE_CLIENT`, `SOCIALDATAX_SOURCE_PLATFORM`, and `SOCIALDATAX_SOURCE_SKILL` as environment-variable fallbacks.
 
@@ -304,13 +313,16 @@ npx -y socialdatax-skills@latest douyin hot-search --pretty
 npx -y socialdatax-skills@latest douyin search --keyword "露营" --pretty
 npx -y socialdatax-skills@latest douyin user-series --sec-user-id "<sec_user_id>" --pretty
 npx -y socialdatax-skills@latest douyin transcript --aweme-id "<aweme_id>" --pretty
+npx -y socialdatax-skills@latest douyin download-media --url "<douyin_media_url>" --output-dir ./downloads --pretty
 npx -y socialdatax-skills@latest kuaishou hot-search --pretty
 npx -y socialdatax-skills@latest kuaishou search --keyword "露营" --pretty
 npx -y socialdatax-skills@latest kuaishou transcript --photo-id "<photo_id>" --pretty
+npx -y socialdatax-skills@latest kuaishou download-media --url "<kuaishou_media_url>" --output-dir ./downloads --pretty
 npx -y socialdatax-skills@latest bilibili download --url "<bilibili_video_url_or_share_text>" --output-dir ./downloads --pretty
 npx -y socialdatax-skills@latest weibo hot-search --pretty
 npx -y socialdatax-skills@latest weibo search --keyword "露营" --pretty
 npx -y socialdatax-skills@latest weibo transcript --post-id "<post_id>" --pretty
+npx -y socialdatax-skills@latest weibo download-media --url "<weibo_media_url>" --output-dir ./downloads --pretty
 npx -y socialdatax-skills@latest wechat hot-search --pretty
 npx -y socialdatax-skills@latest wechat search --keyword "露营" --pretty
 npx -y socialdatax-skills@latest wechat article --url "<mp_article_url_or_share_text>" --pretty
@@ -357,7 +369,8 @@ Current XHS workflows include:
 - Fetch paginated replies under a first-level comment.
 - Read creator profile data from a profile link, short link, share text, or user ID.
 - Fetch paginated creator note lists from a user ID, profile link, short link, or share text for content style and account research.
-- Submit and check video note 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 15 秒.
+- Submit and check video note 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 210 秒，未完成时继续查询同一个 job_id 直到终态.
+- Save returned `image_items[].image_url`, `image_items[].live_photo.video_url`, or `video.video_url` media links locally with `xhs download-media`.
 
 Current Kuaishou workflows include:
 
@@ -370,7 +383,8 @@ Current Kuaishou workflows include:
 - Continue Kuaishou list pagination only when `next_page_token` is non-empty; an empty string means there are no more results to request.
 - Read creator profile data from a non-empty user_id, profile link, short link, or share text. Live/fw-user profile shares are supported for profile data; successful results return a reusable non-empty user_id.
 - Fetch paginated creator work lists from a non-empty user_id, or from a profile link, short link, or share text that resolves directly to a non-empty user_id. For live/fw-user profile shares, call creator profile first and use the returned non-empty user_id.
-- Submit and check video work 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 15 秒.
+- Submit and check video work 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 210 秒，未完成时继续查询同一个 job_id 直到终态.
+- Save returned `images[].url`, `video.play_url`, or `cover_image_url` media links locally with `kuaishou download-media`.
 
 Current Bilibili workflows include:
 
@@ -389,7 +403,8 @@ Current Douyin workflows include:
 - 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.
 - Fetch paginated creator short-drama series lists from a sec_user_id, profile link, short link, or share text.
-- Submit and check video work 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 15 秒.
+- Submit and check video work 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 210 秒，未完成时继续查询同一个 job_id 直到终态.
+- Save returned `images[].url`, `images[].live_photo.play_url`, `video.play_url`, `music.play_url`, or `cover_image_url` media links locally with `douyin download-media`.
 
 Current Weibo workflows include:
 
@@ -401,7 +416,8 @@ Current Weibo workflows include:
 - Continue Weibo list pagination only when `next_page_token` is non-empty; an empty string means there are no more results to request.
 - Read creator profile data from a profile link, short link, share text, or user_id.
 - Fetch paginated creator post lists from a user_id, profile link, short link, or share text.
-- Submit and check Weibo video 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 15 秒.
+- Submit and check Weibo video 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 210 秒，未完成时继续查询同一个 job_id 直到终态.
+- Save returned `image_urls[]` or `video.video_url` media links locally with `weibo download-media`.
 
 Current WeChat / 微信 workflows include:
 
@@ -415,7 +431,7 @@ Current WeChat / 微信 workflows include:
 - Continue WeChat Channels list pagination only when `next_page_token` is non-empty; an empty string means there are no more results to request.
 - Read creator profile data from a finder user_id.
 - Fetch paginated creator video lists from a finder user_id or a video link/share text.
-- Submit and check WeChat Channels / 视频号 video 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 15 秒.
+- Submit and check WeChat Channels / 视频号 video 口播转文字 / speech-to-text transcript jobs; submit tools 提交后最多等待 210 秒，未完成时继续查询同一个 job_id 直到终态.
 
 Current Sensitive Words Check workflows include:
 
@@ -439,9 +455,9 @@ Current Sensitive Words Check workflows include:
 | `xhs_get_user_info_by_profile_url` | Resolve a profile link, short link, or share text into creator profile data. |
 | `xhs_get_user_posted_notes_by_user_id` | Fetch a paginated list of notes published by a creator when the caller already has a user ID. |
 | `xhs_get_user_posted_notes_by_profile_url` | Fetch a paginated list of notes published by a creator from a profile link, short link, or share text. |
-| `xhs_submit_video_speech_text_by_note_url` | Submit an XHS video note speech-to-text transcript job from a note link, short link, or share text; submit waits up to 15 seconds. |
-| `xhs_submit_video_speech_text_by_note_id` | Submit an XHS video note speech-to-text transcript job when the caller already has a note ID; submit waits up to 15 seconds. |
-| `xhs_get_video_speech_text_job` | Check an XHS speech-to-text transcript job by job_id without creating a new task. Returns transcript plus content context, not summary. |
+| `xhs_submit_video_speech_text_by_note_url` | Submit an XHS video note speech-to-text transcript job from a note link, short link, or share text; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
+| `xhs_submit_video_speech_text_by_note_id` | Submit an XHS video note speech-to-text transcript job when the caller already has a note ID; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
+| `xhs_get_video_speech_text_job` | Check an XHS speech-to-text transcript job by job_id without creating a new task; optional wait_seconds 0-240 can long-poll the same job in one request. Continue querying the same job_id until is_terminal is true. Returns transcript plus content context, not summary. |
 
 ## Douyin Tools
 
@@ -460,9 +476,9 @@ Current Sensitive Words Check workflows include:
 | `douyin_get_user_posted_videos_by_profile_url` | Fetch a paginated list of works published by a creator from a profile link, short link, or share text. |
 | `douyin_get_user_series_by_sec_user_id` | Fetch a paginated list of short-drama series by a creator when the caller already has a sec_user_id. |
 | `douyin_get_user_series_by_profile_url` | Fetch a paginated list of short-drama series by a creator from a profile link, short link, or share text. |
-| `douyin_submit_video_speech_text_by_video_url` | Submit a Douyin video speech-to-text transcript job from a content page link, short link, or share text; submit waits up to 15 seconds. |
-| `douyin_submit_video_speech_text_by_aweme_id` | Submit a Douyin video speech-to-text transcript job when the caller already has an aweme_id; submit waits up to 15 seconds. |
-| `douyin_get_video_speech_text_job` | Check a Douyin speech-to-text transcript job by job_id without creating a new task. Returns transcript plus content context, not summary. |
+| `douyin_submit_video_speech_text_by_video_url` | Submit a Douyin video speech-to-text transcript job from a content page link, short link, or share text; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
+| `douyin_submit_video_speech_text_by_aweme_id` | Submit a Douyin video speech-to-text transcript job when the caller already has an aweme_id; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
+| `douyin_get_video_speech_text_job` | Check a Douyin speech-to-text transcript job by job_id without creating a new task; optional wait_seconds 0-240 can long-poll the same job in one request. Continue querying the same job_id until is_terminal is true. Returns transcript plus content context, not summary. |
 
 ## Kuaishou Tools
 
@@ -480,9 +496,9 @@ Current Sensitive Words Check workflows include:
 | `kuaishou_get_user_info_by_profile_url` | Resolve a Kuaishou profile link, including live/fw-user profile shares, short link, or share text into creator profile data; successful results return a reusable non-empty user_id. |
 | `kuaishou_get_user_posted_videos_by_user_id` | Fetch a paginated list of works published by a creator when the caller already has a non-empty user_id. |
 | `kuaishou_get_user_posted_videos_by_profile_url` | Fetch a paginated list of works published by a creator from a profile link, short link, or share text that resolves directly to a non-empty user_id; for live/fw-user profile shares, call creator profile first and use the returned non-empty user_id. |
-| `kuaishou_submit_video_speech_text_by_video_url` | Submit a Kuaishou video speech-to-text transcript job from a work page link, short link, or share text; submit waits up to 15 seconds. |
-| `kuaishou_submit_video_speech_text_by_photo_id` | Submit a Kuaishou video speech-to-text transcript job when the caller already has a photo_id; submit waits up to 15 seconds. |
-| `kuaishou_get_video_speech_text_job` | Check a Kuaishou speech-to-text transcript job by job_id without creating a new task. Returns transcript plus content context, not summary. |
+| `kuaishou_submit_video_speech_text_by_video_url` | Submit a Kuaishou video speech-to-text transcript job from a work page link, short link, or share text; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
+| `kuaishou_submit_video_speech_text_by_photo_id` | Submit a Kuaishou video speech-to-text transcript job when the caller already has a photo_id; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
+| `kuaishou_get_video_speech_text_job` | Check a Kuaishou speech-to-text transcript job by job_id without creating a new task; optional wait_seconds 0-240 can long-poll the same job in one request. Continue querying the same job_id until is_terminal is true. Returns transcript plus content context, not summary. |
 
 ## Bilibili Tools
 
@@ -505,9 +521,9 @@ Current Sensitive Words Check workflows include:
 | `weibo_get_user_info_by_profile_url` | Resolve a Weibo profile link, short link, or share text into creator profile data. |
 | `weibo_get_user_posts_by_user_id` | Fetch a paginated list of posts published by a creator when the caller already has a user_id. |
 | `weibo_get_user_posts_by_profile_url` | Fetch a paginated list of posts published by a creator from a profile link, short link, or share text. |
-| `weibo_submit_video_speech_text_by_post_url` | Submit a Weibo video speech-to-text transcript job from a post URL, short link, or share text; submit waits up to 15 seconds. |
-| `weibo_submit_video_speech_text_by_post_id` | Submit a Weibo video speech-to-text transcript job when the caller already has a post_id; submit waits up to 15 seconds. |
-| `weibo_get_video_speech_text_job` | Check a Weibo speech-to-text transcript job by job_id without creating a new task. Returns transcript plus content context, not summary. |
+| `weibo_submit_video_speech_text_by_post_url` | Submit a Weibo video speech-to-text transcript job from a post URL, short link, or share text; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
+| `weibo_submit_video_speech_text_by_post_id` | Submit a Weibo video speech-to-text transcript job when the caller already has a post_id; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
+| `weibo_get_video_speech_text_job` | Check a Weibo speech-to-text transcript job by job_id without creating a new task; optional wait_seconds 0-240 can long-poll the same job in one request. Continue querying the same job_id until is_terminal is true. Returns transcript plus content context, not summary. |
 
 ## WeChat Tools
 
@@ -524,9 +540,9 @@ Current Sensitive Words Check workflows include:
 | `wechat_get_user_info_by_user_id` | Fetch creator profile data when the finder user_id is already known. |
 | `wechat_get_user_posted_videos_by_user_id` | Fetch a paginated list of videos published by a creator when the finder user_id is already known. |
 | `wechat_get_user_posted_videos_by_url` | Fetch a paginated list of videos published by a creator from a video link or share text. |
-| `wechat_submit_video_speech_text_by_video_url` | Submit a WeChat Channels / 视频号 video speech-to-text transcript job from a video link or share text; submit waits up to 15 seconds. |
-| `wechat_submit_video_speech_text_by_encrypted_object_id` | Submit a WeChat Channels / 视频号 video speech-to-text transcript job when encrypted_object_id is already known; submit waits up to 15 seconds. |
-| `wechat_get_video_speech_text_job` | Check a WeChat Channels / 视频号 speech-to-text transcript job by job_id without creating a new task. Returns transcript plus content context, not summary. |
+| `wechat_submit_video_speech_text_by_video_url` | Submit a WeChat Channels / 视频号 video speech-to-text transcript job from a video link or share text; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
+| `wechat_submit_video_speech_text_by_encrypted_object_id` | Submit a WeChat Channels / 视频号 video speech-to-text transcript job when encrypted_object_id is already known; submit waits up to 210 seconds. If unfinished, continue checking the same job_id with get-job wait_seconds up to 240 until is_terminal is true. |
+| `wechat_get_video_speech_text_job` | Check a WeChat Channels / 视频号 speech-to-text transcript job by job_id without creating a new task; optional wait_seconds 0-240 can long-poll the same job in one request. Continue querying the same job_id until is_terminal is true. Returns transcript plus content context, not summary. |
 
 ## Sensitive Words Check Tools