socialdatax-skills 0.2.44 → 0.2.45

package/README.md

@@ -89,7 +89,18 @@ Common search phrases for this skill package:
 - Reserved future SocialDataX namespace names for existing platform listings without draft files yet: `com.socialdatax/kuaishou-insights`, `com.socialdatax/bilibili-insights`, `com.socialdatax/weibo-insights`, `com.socialdatax/wechat-channels-insights`, `com.socialdatax/zhihu-insights`, `com.socialdatax/instagram-insights`, `com.socialdatax/x-insights`, `com.socialdatax/youtube-insights`, and `com.socialdatax/tiktok-insights`.
 - Hosted endpoint without a repo-tracked standalone listing: Sensitive Words Check.
 - Unified MCP registry name: none; this package installs skills and calls explicit hosted MCP entries.
-- Current public capability version: `0.2.44`
+- Current public capability version: `0.2.45`
+
+## XHS 蒲公英 / Pugongying commercial note details
+
+Version `0.2.45` adds `xhs pgy-detail` and the matching `media-detail` Skill routing:
+
+```bash
+npx -y socialdatax-skills@latest xhs pgy-detail --note-id "<note_id>" --pretty
+npx -y socialdatax-skills@latest xhs pgy-detail --url "<note_url_or_share_text>" --pretty
+```
+
+Configure `SOCIALDATAX_API_KEY` before running these commands. Choose exactly one input: the complete note ID, or the original note URL, short link or share text. Each successful call costs **20 points**; failed calls are not charged. Use this route for requested 蒲公英 commercial details. Ordinary `xhs detail` stays on the public note-detail route and does not automatically switch to commercial data. Only notes from creators enrolled in 蒲公英 are eligible. When MCP structured code is `pgy_commercial_data_unavailable` (HTTP numeric code `1009`), the product treats this explicit no-commercial-data outcome as not enrolled: "该笔记所属博主未入驻蒲公英，无法查询蒲公英数据。本次查询失败，不扣费。" Use the structured code, not message text or internal reason_code, to identify this outcome. The CLI exits with status 1 and writes a JSON object containing only `code` and `message` to stderr for this outcome; stdout remains empty. Other errors retain their existing output format. Stop without retrying the other ID/URL route. Timeouts, service outages, authentication errors, insufficient balance, invalid inputs and unexplained empty responses retain their actual error or unresolved status; do not label them as not enrolled.
 
 ## Direct CLI
 
@@ -445,7 +456,7 @@ Available skills:
 
 - `socialdatax-content-research-assistant`: combine SocialDataX search, detail, comment, creator profile, and creator content workflows for cross-platform content research across XHS, Douyin, Kuaishou, Bilibili, Weibo, WeChat Channels, Zhihu, Instagram, X / Twitter, YouTube, and TikTok; also reads WeChat Official Account article link details.
 - `media-search`: search social media content by keyword; supports XHS notes, Douyin works, Kuaishou works, Bilibili videos/articles, Weibo posts, WeChat Channels videos, Zhihu content, Instagram posts, X / Twitter posts, YouTube videos, and TikTok posts.
-- `media-detail`: read WeChat Official Account article details and body text from article links. Read structured content details and metrics for XHS notes, Douyin works, Kuaishou works, Bilibili content, Weibo posts, WeChat Channels videos and image posts, Zhihu content, Instagram posts, X / Twitter posts, YouTube videos, and TikTok posts.
+- `media-detail`: supports requested XHS 蒲公英 / Pugongying commercial note details (20 points per successful call; failures are not charged). Read WeChat Official Account article details and body text from article links. Read structured content details and metrics for XHS notes, Douyin works, Kuaishou works, Bilibili content, Weibo posts, WeChat Channels videos and image posts, Zhihu content, Instagram posts, X / Twitter posts, YouTube videos, and TikTok posts.
 - `media-comments`: fetch and analyze comments/replies for XHS, Douyin, Kuaishou, Bilibili, Weibo, WeChat Channels, Zhihu, Instagram, X / Twitter, YouTube, and TikTok.
 - `media-transcript`: submit and check video 口播转文字 / speech-to-text transcript jobs; supports XHS, Douyin, Kuaishou, Weibo, and WeChat Channels through direct CLI commands or hosted MCP tools, plus Bilibili, Zhihu independent videos and video answers, Instagram regular video posts/Reels, X / Twitter video posts, TikTok, and YouTube through hosted MCP tools. Instagram photo and carousel posts and Zhihu plain answers without video are not processable.
 - `media-user-info`: retrieve creator profile information; supports XHS, Douyin, Kuaishou, Bilibili, Weibo, WeChat Channels, Zhihu, Instagram, X / Twitter, YouTube channels, and TikTok creators.
@@ -619,6 +630,8 @@ Current Sensitive Words Check workflows include:
 | `xhs_search_notes` | Search Xiaohongshu / 小红书 notes by keyword with optional sort, note type, and publish-time filters. |
 | `xhs_get_note_detail_by_note_url` | Resolve a shared XHS link, short link, or share text into structured note details. |
 | `xhs_get_note_detail_by_note_id` | Fetch structured note details when the caller already has a note ID. |
+| `xhs_pgy_get_note_detail_by_note_id` | Read 蒲公英 commercial note details by full note ID; 20 points per successful call, failures are not charged. |
+| `xhs_pgy_get_note_detail_by_note_url` | Read 蒲公英 commercial note details from a note URL, short link or share text; 20 points per successful call, failures are not charged. |
 | `xhs_get_note_comments_by_note_id` | Fetch paginated first-level comments when the caller already has a note ID; accepts optional comment `sort_type`. |
 | `xhs_get_note_comments_by_note_url` | Fetch paginated first-level comments directly from a shared note URL, short link, or share text; accepts optional comment `sort_type`. |
 | `xhs_get_note_sub_comments_by_comment_id` | Fetch paginated replies under a first-level comment by note ID and comment ID. |

package/cli.mjs

@@ -22,7 +22,7 @@ import { decryptWechatMediaCommand } from "./lib/media/wechat-decrypt.mjs";
 export { decryptWechatMediaCommand };
 
 const PACKAGE_NAME = "socialdatax-skills";
-const PACKAGE_VERSION = "0.2.44";
+const PACKAGE_VERSION = "0.2.45";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
 const LOG_PREFIX = `[${PACKAGE_NAME}]`;
 const MIN_NODE_VERSION = "20.18.1";
@@ -71,7 +71,7 @@ const AVAILABLE_SKILLS = [
   {
     name: "media-detail",
     summary:
-      "Read WeChat Official Account article details and body text. Read structured content details and metrics for XHS, Douyin, Kuaishou, Bilibili, Weibo, WeChat Channels, Zhihu, Instagram, X / Twitter, YouTube, and TikTok.",
+      "Read WeChat Official Account article details and body text. Read structured content details and metrics for XHS, Douyin, Kuaishou, Bilibili, Weibo, WeChat Channels, Zhihu, Instagram, X / Twitter, YouTube, and TikTok. Supports requested XHS 蒲公英 / Pugongying commercial note details.",
     emoji: "📄",
   },
   {
@@ -139,6 +139,7 @@ const XHS_DIRECT_ACTION_OPTIONS = {
     "pretty",
   ],
   detail: ["noteId", "url", "pretty"],
+  "pgy-detail": ["noteId", "url", "pretty"],
   comments: [
     "noteId",
     "url",
@@ -898,6 +899,16 @@ const PLATFORMS = {
         name: "xhs_get_note_detail_by_note_id",
         description: "Fetch structured note details by note ID.",
       },
+      {
+        name: "xhs_pgy_get_note_detail_by_note_id",
+        description:
+          "Read XHS 蒲公英 / Pugongying commercial note details by full note ID; 20 points per successful call, failures are not charged.",
+      },
+      {
+        name: "xhs_pgy_get_note_detail_by_note_url",
+        description:
+          "Read XHS 蒲公英 / Pugongying commercial note details from a note URL, short link or share text; 20 points per successful call, failures are not charged.",
+      },
       {
         name: "xhs_get_note_comments_by_note_id",
         description:
@@ -1782,7 +1793,14 @@ async function main() {
       process.exitCode = 1;
     }
   } catch (error) {
-    console.error(`${LOG_PREFIX} ${formatCliErrorMessage(error)}`);
+    if (error?.structuredContent?.code === "pgy_commercial_data_unavailable") {
+      console.error(JSON.stringify({
+        code: error.structuredContent.code,
+        message: error.structuredContent.message || error.message,
+      }));
+    } else {
+      console.error(`${LOG_PREFIX} ${formatCliErrorMessage(error)}`);
+    }
     process.exit(1);
   }
 }
@@ -2853,6 +2871,10 @@ function printHelp() {
   console.log(`  npx -y ${PACKAGE_SPEC} xhs detail --note-id "<note_id>" --pretty`);
   console.log("      Call the XHS note detail tool directly and print JSON.");
   console.log("");
+  console.log(`  npx -y ${PACKAGE_SPEC} xhs pgy-detail --note-id "<note_id>" --pretty`);
+  console.log("      蒲公英 / Pugongying commercial details: 20 points per successful call; failures are not charged.");
+  console.log("      Use --url instead of --note-id for a note link, short link or share text.");
+  console.log("");
   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("");
@@ -3912,6 +3934,20 @@ function buildXhsOperation(action, options) {
           urlDisplay: "--url",
         })
       );
+    case "pgy-detail":
+      return buildDirectOperation(
+        "pgy-detail",
+        buildOneOfCall(options, {
+          idOption: "noteId",
+          urlOption: "url",
+          idTool: "xhs_pgy_get_note_detail_by_note_id",
+          urlTool: "xhs_pgy_get_note_detail_by_note_url",
+          idArgument: "note_id",
+          urlArgument: "note_url",
+          idDisplay: "--note-id",
+          urlDisplay: "--url",
+        })
+      );
     case "comments":
       return buildDirectOperation(
         "comments",

package/package.json

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

package/skills/media-detail/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "media-detail"
-description: "Read structured social media content details and metrics from content IDs, URLs, short links, or share text for supported platforms including Xiaohongshu / XHS / RedNote, Douyin, Kuaishou, Bilibili, Zhihu, Instagram, X / Twitter, YouTube, TikTok, Weibo, and WeChat Channels. For WeChat Official Account articles, read article details and body text from article links."
+description: "Read structured social media content details and metrics from content IDs, URLs, short links, or share text for supported platforms including Xiaohongshu / XHS / RedNote, Douyin, Kuaishou, Bilibili, Zhihu, Instagram, X / Twitter, YouTube, TikTok, Weibo, and WeChat Channels. For WeChat Official Account articles, read article details and body text from article links. Supports XHS 蒲公英 / Pugongying commercial note details when requested."
 source_client: "socialdatax-skills"
 source_platform: "npm"
 source_skill: "media-detail"
@@ -24,7 +24,7 @@ metadata:
 
 # Media Detail
 
-Use this skill when the user provides an mp.weixin.qq.com article link and wants WeChat Official Account article body text. For other supported content links, short links, share text, or content IDs, use it for structured details or interaction metrics where supported.
+Use this skill when the user provides an mp.weixin.qq.com article link and wants WeChat Official Account article body text. For other supported content links, short links, share text, or content IDs, use it for structured details or interaction metrics where supported. For explicit XHS 蒲公英 / Pugongying commercial note requests, choose the commercial detail route (20 points per successful call; failures are not charged).
 
 Current platform support:
 
@@ -40,6 +40,7 @@ Current platform support:
 - Weibo / 微博 posts through the `weibo_get_post_detail_by_*` tools.
 - WeChat Channels / 视频号 video and image-post details through the `wechat_get_video_detail_by_*` tools.
 - WeChat Official Account / 微信公众号 articles through `wechat_get_mp_article_detail_by_url`.
+- Xiaohongshu / XHS 蒲公英 / Pugongying single-note commercial details through `xhs_pgy_get_note_detail_by_note_id` or `xhs_pgy_get_note_detail_by_note_url`.
 
 ## API Key
 
@@ -130,6 +131,14 @@ npx -y socialdatax-skills@latest wechat detail \
 npx -y socialdatax-skills@latest wechat article \
   --url "<mp_article_url_or_share_text>" --pretty --source-client socialdatax-skills \
   --source-platform npm --source-skill media-detail
+
+npx -y socialdatax-skills@latest xhs pgy-detail \
+  --note-id "<note_id>" --pretty --source-client socialdatax-skills \
+  --source-platform npm --source-skill media-detail
+
+npx -y socialdatax-skills@latest xhs pgy-detail \
+  --url "<note_url_or_share_text>" --pretty --source-client socialdatax-skills \
+  --source-platform npm --source-skill media-detail
 ```
 
 Optional arguments:
@@ -160,6 +169,11 @@ Optional arguments:
 Use either the ID option or the URL option for detail commands, not both.
 
 The command prints JSON with `platform`, `tool`, `arguments`, and `data`.
+For XHS 蒲公英 / Pugongying commercial note data, use `xhs pgy-detail`. Each successful call costs 20 points; failed calls are not charged.
+XHS 蒲公英 queries apply only to notes from creators enrolled in 蒲公英 / Pugongying.
+Use this route when the user asks for 蒲公英 / Pugongying commercial details. Ordinary note-detail requests continue to use `xhs detail`; do not automatically upgrade an ordinary request or retry it through the paid commercial route.
+Choose exactly one input: the complete `--note-id`, or `--url` with the original note link, short link or share text. Do not call both routes for the same note.
+If the user asks only for exposure, reads or pricing without establishing the 蒲公英 commercial scope, clarify that scope and the 20-point successful-call cost before calling. Do not ask again when the conversation has already established this scope.
 
 ## Safety Boundary
 
@@ -169,26 +183,17 @@ Platform detail access is read-only. It uses `SOCIALDATAX_API_KEY` from the user
 
 MCP tools matching the direct CLI commands above:
 
-- `xhs_get_note_detail_by_note_id`
-- `xhs_get_note_detail_by_note_url`
-- `douyin_get_video_detail_by_aweme_id`
-- `douyin_get_video_detail_by_url`
-- `kuaishou_get_video_detail_by_photo_id`
-- `kuaishou_get_video_detail_by_url`
-- `bilibili_get_content_detail_by_id`
-- `bilibili_get_content_detail_by_url`
-- `zhihu_get_content_detail_by_url`
-- `instagram_get_post_detail_by_post_id`
-- `instagram_get_post_detail_by_post_url`
-- `x_get_post_detail_by_post_id`
-- `x_get_post_detail_by_post_url`
-- `youtube_get_video_detail_by_url`
-- `tiktok_get_post_detail_by_url`
-- `weibo_get_post_detail_by_post_id`
-- `weibo_get_post_detail_by_post_url`
-- `wechat_get_video_detail_by_encrypted_object_id`
-- `wechat_get_video_detail_by_url`
-- `wechat_get_mp_article_detail_by_url`
+- XHS: `xhs_get_note_detail_by_note_id`, `xhs_get_note_detail_by_note_url`, `xhs_pgy_get_note_detail_by_note_id`, `xhs_pgy_get_note_detail_by_note_url`
+- DOUYIN: `douyin_get_video_detail_by_aweme_id`, `douyin_get_video_detail_by_url`
+- KUAISHOU: `kuaishou_get_video_detail_by_photo_id`, `kuaishou_get_video_detail_by_url`
+- BILIBILI: `bilibili_get_content_detail_by_id`, `bilibili_get_content_detail_by_url`
+- ZHIHU: `zhihu_get_content_detail_by_url`
+- INSTAGRAM: `instagram_get_post_detail_by_post_id`, `instagram_get_post_detail_by_post_url`
+- X: `x_get_post_detail_by_post_id`, `x_get_post_detail_by_post_url`
+- YOUTUBE: `youtube_get_video_detail_by_url`
+- TIKTOK: `tiktok_get_post_detail_by_url`
+- WEIBO: `weibo_get_post_detail_by_post_id`, `weibo_get_post_detail_by_post_url`
+- WECHAT: `wechat_get_video_detail_by_encrypted_object_id`, `wechat_get_video_detail_by_url`, `wechat_get_mp_article_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 the full `note_id` is already known; do not pass only a prefix.
@@ -211,6 +216,9 @@ If MCP tools are already available in the current agent, use one of these tools:
 - `wechat_get_video_detail_by_encrypted_object_id`: use when encrypted_object_id from search is already known.
 - `wechat_get_video_detail_by_url`: use for a WeChat Channels / 视频号 video or image-post link or share text.
 - `wechat_get_mp_article_detail_by_url`: use for WeChat Official Account / 微信公众号 article links or share text.
+- `xhs_pgy_get_note_detail_by_note_id`: for 蒲公英 / Pugongying commercial details when the full note_id is known.
+- `xhs_pgy_get_note_detail_by_note_url`: for 蒲公英 / Pugongying commercial details from a note URL, short link or share text.
+Both XHS 蒲公英 tools cost 20 points per successful call; failures are not charged. They are distinct from ordinary `xhs_get_note_detail_by_*` tools.
 
 ## Output Guidance
 
@@ -232,10 +240,15 @@ When the user wants to save Weibo media after detail, pass each returned `image_
 For WeChat Channels / 视频号 detail, preserve `object_id` and `object_nonce_id` because comments and replies need both values.
 When the user wants to save a WeChat Channels / 视频号 video after detail, pass the returned `video.video_url` to `npx -y socialdatax-skills@latest wechat decrypt-media --media-url "<video.video_url>" --output <file>`; this local save command decrypts when needed and does not require `SOCIALDATAX_API_KEY`.
 For WeChat Official Account / 微信公众号 article detail, include article title, account, publish time, body text, image URLs, linked articles, and embedded video cards when present.
+Label XHS 蒲公英 / Pugongying results as commercial note data, distinct from ordinary public note metrics; do not present ordinary note details as a successful commercial result.
+When MCP returns structured code `pgy_commercial_data_unavailable` (or HTTP returns numeric code `1009`), treat the creator as not enrolled and show the returned message: "该笔记所属博主未入驻蒲公英，无法查询蒲公英数据。本次查询失败，不扣费。" These identifiers retain the explicit no-commercial-data outcome; do not classify errors by matching message text or internal reason_code.
+After this no-data outcome, stop: do not retry through the other ID/URL route or automatically substitute ordinary details. If the user still wants ordinary details, use the ordinary detail route for that request.
+Do not classify timeouts, service outages, authentication failures, insufficient balance, invalid inputs, or an unexplained empty response as 未入驻蒲公英. Report the actual request error or unresolved outcome instead.
+For CLI calls, this no-commercial-data error exits with status 1 and writes a JSON object containing `code` and `message` to stderr; read that code instead of matching text. A text-only or unknown error is unresolved, not evidence of non-enrollment. Do not persist this single-note outcome as a permanent creator enrollment status.
 
 ## Troubleshooting
 
 - If an SDK/dependency, npm network, Node.js/npm/npx availability, permission, or missing runtime error appears, treat it as a local runtime, dependency installation, network, or agent authorization issue, not a SocialDataX API key or business data error. If the current environment has permission, install or restore automatically. When network or execution authorization is needed, ask the user to approve or finish authorization, then continue the same command; do not use public web search as a substitute for SocialDataX data.
-- For non-balance network or API errors, preserve the error message, check `SOCIALDATAX_API_KEY`, parameters, and link or ID format, then retry once when appropriate.
+- For non-balance network or API errors, preserve the error message, check `SOCIALDATAX_API_KEY`, parameters, and link or ID format, then retry once when appropriate. This retry advice excludes `pgy_commercial_data_unavailable` / HTTP `1009`: stop without retrying the same or alternate input route.
 - If the response returns `insufficient_balance` or says the balance/credits are insufficient, do not retry repeatedly. Show the recharge URL from the error exactly as returned, then continue the same command after the user recharges.
 - If the user has recharged but still sees insufficient balance, confirm `SOCIALDATAX_API_KEY` belongs to the same account that was recharged; if needed, copy a fresh API Key from the official dashboard.

package/skills/media-detail/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "Media Detail"
   short_description: "Read content details"
-  default_prompt: "Use $media-detail to read WeChat Official Account article details and body text. For supported XHS, Douyin, Kuaishou, Bilibili, Zhihu, Instagram, X / Twitter, YouTube, TikTok, Weibo, and WeChat Channels content, read structured details and metrics."
+  default_prompt: "Use $media-detail to read WeChat Official Account article details and body text. For supported XHS, Douyin, Kuaishou, Bilibili, Zhihu, Instagram, X / Twitter, YouTube, TikTok, Weibo, and WeChat Channels content, read structured details and metrics. When requested, use the XHS 蒲公英 commercial detail route; successful calls cost 20 points and failures are not charged."
 
 policy:
   allow_implicit_invocation: true