@vocmarket/voc-skill 0.3.38 → 0.3.40

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "voc-intelligence",
   "description": "VOC intelligence skills for Claude Code: end-to-end VOC business workflows, Xiaohongshu/Douyin/WeChat Channels collection and trend reports, live social VOC collection, Fmode Doubao image analysis, token/recharge checks, evidence-card outputs, prioritized issue pools, single-problem deep dives, competitor maps, 7-day content plans, VOC-backed speaking script co-creation, boss/operator action plans, and multi-turn memory.",
-  "version": "0.3.38",
+  "version": "0.3.40",
   "author": {
     "name": "nkkj-BrainHack"
   }

package/mcp/catalog/voc-social-endpoints.json

@@ -915,7 +915,10 @@
           "desc": "连续翻页时透传上一次返回的 session_id。"
         }
       ],
-      "responseHint": "返回笔记列表，含 note_id、标题、作者、互动数；翻页递增 page 并透传 search_id/session_id。"
+      "responseHint": "返回笔记列表，含 note_id、标题、作者、互动数；翻页递增 page 并透传 search_id/session_id。",
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.app_v2.search_notes",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.note_detail",
@@ -952,7 +955,10 @@
           "desc": "可选：直接传小红书分享文案/链接，与 note_id 二选一。"
         }
       ],
-      "responseHint": "返回单条笔记对象，含正文、图片/视频、话题、互动数。"
+      "responseHint": "返回单条笔记对象，含正文、图片/视频、话题、互动数。",
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.app_v2.get_image_note_detail",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.note_comments",
@@ -997,7 +1003,8 @@
           "desc": "可选安全令牌，来自 search_notes 返回的 note.xsec_token；部分笔记风控需要。"
         }
       ],
-      "responseHint": "返回评论列表，含 comment_id、文本、点赞、子评论数；翻页用返回的游标。"
+      "responseHint": "返回评论列表，含 comment_id、文本、点赞、子评论数；翻页用返回的游标。",
+      "recommendationPriority": 80
     },
     {
       "id": "xiaohongshu.sub_comments",
@@ -1043,7 +1050,8 @@
           "desc": "分页游标，首页留空，翻页用上一次返回的 start。"
         }
       ],
-      "responseHint": "返回某条评论的回复列表；翻页用返回的 start。"
+      "responseHint": "返回某条评论的回复列表；翻页用返回的 start。",
+      "recommendationPriority": 70
     },
     {
       "id": "xiaohongshu.user_info",
@@ -1074,7 +1082,10 @@
           "desc": "用户 id（24 位 hex），来自 search_notes 返回的 note.user.userid；注意不是数字 red_id。"
         }
       ],
-      "responseHint": "返回用户资料对象，含粉丝数、获赞收藏、简介。"
+      "responseHint": "返回用户资料对象，含粉丝数、获赞收藏、简介。",
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.app_v2.get_user_info",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.user_notes",
@@ -1113,7 +1124,10 @@
           "desc": "分页游标，首页留空，翻页用上一次返回的 cursor。"
         }
       ],
-      "responseHint": "返回该用户的笔记列表；翻页用返回的 cursor。"
+      "responseHint": "返回该用户的笔记列表；翻页用返回的 cursor。",
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.app_v2.get_user_posted_notes",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.topic_notes",
@@ -1190,7 +1204,10 @@
           "desc": "翻页透传上一次返回的 session_id。"
         }
       ],
-      "responseHint": "返回话题下笔记列表；翻页透传 last_note_ct/last_note_id/cursor_score/session_id。"
+      "responseHint": "返回话题下笔记列表；翻页透传 last_note_ct/last_note_id/cursor_score/session_id。",
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.app_v2.get_topic_feed",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.search_products",
@@ -1276,7 +1293,10 @@
           "desc": "连续翻页时透传上一次返回的 session_id。"
         }
       ],
-      "responseHint": "返回商品列表，含标题、价格、销量、店铺。"
+      "responseHint": "返回商品列表，含标题、价格、销量、店铺。",
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.app_v2.search_products",
+      "recommendationPriority": -1000
     },
     {
       "id": "tiktok.web.fetch_post_detail",
@@ -10405,7 +10425,8 @@
         "app",
         "v2"
       ],
-      "requiredParams": []
+      "requiredParams": [],
+      "recommendationPriority": 90
     },
     {
       "id": "xiaohongshu.app_v2.get_video_note_detail",
@@ -10423,7 +10444,8 @@
         "app",
         "v2"
       ],
-      "requiredParams": []
+      "requiredParams": [],
+      "recommendationPriority": 90
     },
     {
       "id": "xiaohongshu.app_v2.get_note_comments",
@@ -10479,7 +10501,8 @@
         "app",
         "v2"
       ],
-      "requiredParams": []
+      "requiredParams": [],
+      "recommendationPriority": 60
     },
     {
       "id": "xiaohongshu.app_v2.get_user_posted_notes",
@@ -10487,7 +10510,7 @@
       "group": "app-v2",
       "channel": "social",
       "title": "获取用户笔记列表",
-      "summary": "获取指定用户已发布的笔记列表，使用游标分页 参数: - user_id: 用户ID，如 \"61b46d790000000010008153\" - share_text: 小红书分享链接（支持APP和Web端分享链接） - 优先使用`user_id`，如果没有则使用`share_t",
+      "summary": "按达人主页拉取已发布笔记。这是「指定达人/作者笔记」的现用入口：user_id 与分享链接二选一，首页 cursor 留空，下一页透传返回的 cursor。不要猜 get_user_note_list 或其他未登记路径。",
       "proxyPath": "xiaohongshu/app_v2/get_user_posted_notes",
       "method": "GET",
       "paramsIn": "query",
@@ -10497,7 +10520,12 @@
         "app",
         "v2"
       ],
-      "requiredParams": []
+      "requiredParams": [],
+      "recommendationPriority": 95,
+      "recommendedFor": [
+        "creator_homepage"
+      ],
+      "responseHint": "返回 notes、has_more、cursor。翻页时把 cursor 原样传回，直到 has_more=false。"
     },
     {
       "id": "xiaohongshu.app_v2.get_user_faved_notes",
@@ -10535,7 +10563,8 @@
       ],
       "requiredParams": [
         "keyword"
-      ]
+      ],
+      "recommendationPriority": 100
     },
     {
       "id": "xiaohongshu.app_v2.search_users",
@@ -10543,7 +10572,7 @@
       "group": "app-v2",
       "channel": "social",
       "title": "搜索用户",
-      "summary": "根据关键词搜索小红书用户，每页返回 20 条结果，支持分页 参数: - keyword: 搜索关键词（必需），如 \"美食博主\" - page: 页码，从 1 开始 - search_id: 搜索ID，翻页时传入首次搜索返回的值 - source: 来源，默认 \"explore_f",
+      "summary": "按达人昵称搜索小红书用户。返回项里的 userid 是 24 位 hex，可直接传给 app_v2/get_user_posted_notes。不要把数字小红书号或主页 URL 当作 user_id。",
       "proxyPath": "xiaohongshu/app_v2/search_users",
       "method": "GET",
       "paramsIn": "query",
@@ -10555,6 +10584,10 @@
       ],
       "requiredParams": [
         "keyword"
+      ],
+      "recommendationPriority": 85,
+      "recommendedFor": [
+        "creator_homepage"
       ]
     },
     {
@@ -10595,7 +10628,8 @@
       ],
       "requiredParams": [
         "keyword"
-      ]
+      ],
+      "recommendationPriority": 30
     },
     {
       "id": "xiaohongshu.app_v2.search_groups",
@@ -10715,7 +10749,8 @@
       ],
       "requiredParams": [
         "page_id"
-      ]
+      ],
+      "recommendationPriority": 40
     },
     {
       "id": "xiaohongshu.app_v2.get_topic_feed",
@@ -10735,7 +10770,8 @@
       ],
       "requiredParams": [
         "page_id"
-      ]
+      ],
+      "recommendationPriority": 40
     },
     {
       "id": "xiaohongshu.app_v2.get_creator_inspiration_feed",
@@ -23234,7 +23270,7 @@
       "platform": "xiaohongshu",
       "channel": "ecommerce",
       "title": "小红书·用户发布笔记",
-      "summary": "获取小红书用户发布笔记数据，包括笔记元数据、封面、发布时间、分页游标和互动信号，用于账号监控、创作者研究和内容分析。",
+      "summary": "电商通道的达人主页笔记列表。社媒 app_v2/get_user_posted_notes 不可用时使用。入参是 userId，翻页透传 lastCursor。不要调用无版本号的 get_user_note_list。",
       "method": "GET",
       "paramsIn": "query",
       "proxyPath": "xiaohongshu/get-user-note-list/v1",
@@ -23255,7 +23291,11 @@
         "ecommerce",
         "电商"
       ],
-      "billing": 1
+      "billing": 1,
+      "recommendationPriority": 80,
+      "recommendedFor": [
+        "creator_homepage"
+      ]
     },
     {
       "id": "xiaohongshu.get_user_note_list_v2",

package/mcp/src/server.js

@@ -66,7 +66,7 @@ function normalizeToolResult(result = {}) {
 function createServer() {
   const server = new McpServer({
     name: 'voc-intelligence',
-    version: '0.3.38'
+    version: '0.3.40'
   });
 
   server.registerTool(

package/mcp/src/tools/voc-api-catalog-run.js

@@ -37,7 +37,7 @@ async function searchVocApis(input = {}) {
   const matches = (query || input.platform || input.tag)
     ? searchEndpoints({ query, platform: input.platform, tag: input.tag, limit: input.limit || 20 })
     : listEndpoints();
-  const results = matches.map(summarizeEndpoint);
+  const results = matches.map(summarizeEndpoint).filter(item => !item.deprecated);
   const lines = [
     '## VOC 转发接口清单',
     '',
@@ -80,6 +80,12 @@ async function getVocApiDoc(input = {}) {
     });
   }
   endpoint = hydrateEndpoint(endpoint);
+  if (endpoint.deprecated) {
+    const replacement = endpoint.replacedBy ? `请改用 ${endpoint.replacedBy}。` : '请用 voc_api_search 改选现用接口。';
+    return errorResult(`接口「${endpoint.id}」已下架。${replacement}`, {
+      data: { endpoint: summarizeEndpoint(endpoint) }
+    });
+  }
   const paramLines = (endpoint.params || []).map(p => {
     const flag = p.required ? '必填' : '可选';
     const def = p.default !== undefined ? `，默认 ${JSON.stringify(p.default)}` : '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vocmarket/voc-skill",
-  "version": "0.3.38",
+  "version": "0.3.40",
   "description": "Claude Code VOC intelligence skills for Xiaohongshu, Douyin and WeChat Channels trend/content collection, live social VOC, Fmode image analysis, single-issue deep dives, boss/operator action plans, and multi-turn memory.",
   "type": "commonjs",
   "bin": {

package/skill-package-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-voc-intelligence",
-  "version": "0.3.38",
+  "version": "0.3.40",
   "capabilities": {
     "summary": "三类情报源同源接入：①社媒内容（含抖音/小红书/微信视频号等）②国内电商+创作者情报 ③海外选品。统一 search→doc→call、鉴权计费一致。",
     "channels": [

package/skills/voc-api-catalog/SKILL.md

@@ -46,6 +46,106 @@ VOC 后端是一个**通用转发网关**（`https://server.fmode.cn/api/voc-soc
 4. `voc_api_call` 用真实关键词调用；翻页/拉评论时把上一次返回里的 cursor / id 透传进下一次调用。
 5. 用返回数据继续后续分析（可交给 voc-issue-pool、voc-content-plan 等技能）。
 
+## 小红书现用接口（V2）
+
+小红书社媒采集只走下面这些健康的 V2 接口。`voc_api_search` 会把它们排在前面；标了 `deprecated` 的旧接口不要调用，也不要在给用户的说明里提到。
+
+| 用途 | 接口 id | proxyPath | 必填 |
+|---|---|---|---|
+| 笔记搜索 | `xiaohongshu.app_v2.search_notes` | `xiaohongshu/app_v2/search_notes` | `keyword` |
+| 图文详情 | `xiaohongshu.app_v2.get_image_note_detail` | `xiaohongshu/app_v2/get_image_note_detail` | `note_id` 或 `share_text` |
+| 视频详情 | `xiaohongshu.app_v2.get_video_note_detail` | `xiaohongshu/app_v2/get_video_note_detail` | `note_id` 或 `share_text` |
+| 一级评论 | `xiaohongshu.note_comments` | `xiaohongshu/app_v2/get_note_comments` | `note_id` |
+| 楼中楼 | `xiaohongshu.sub_comments` | `xiaohongshu/app_v2/get_note_sub_comments` | `note_id` + `comment_id` |
+| 用户资料 | `xiaohongshu.app_v2.get_user_info` | `xiaohongshu/app_v2/get_user_info` | `user_id` |
+| 用户笔记 | `xiaohongshu.app_v2.get_user_posted_notes` | `xiaohongshu/app_v2/get_user_posted_notes` | `user_id` |
+| 话题详情 | `xiaohongshu.app_v2.get_topic_info` | `xiaohongshu/app_v2/get_topic_info` | `page_id` |
+| 话题笔记 | `xiaohongshu.app_v2.get_topic_feed` | `xiaohongshu/app_v2/get_topic_feed` | `page_id` |
+| 商品搜索 | `xiaohongshu.app_v2.search_products` | `xiaohongshu/app_v2/search_products` | `keyword` |
+
+不要手写未登记路径，也不要在路径后面自己加 `/v1`。先用下面的 `id` 调 `voc_api_call`；参数拿不准时再跑 `voc_api_doc`。一次只拉一页，批量翻页前用 `voc_cost_estimate` 估算，结束后用 `voc_usage_report` 核对。
+
+### 按关键词找笔记
+
+`sort_type` 只用 `general`、`time_descending`、`popularity_descending`。`note_type` 只用 `不限`、`视频笔记`、`普通笔记`。翻页时递增 `page`，并透传首次返回的 `search_id`、`search_session_id`。
+
+```json
+{ "id": "xiaohongshu.app_v2.search_notes", "params": { "keyword": "防晒", "page": 1, "sort_type": "popularity_descending", "note_type": "不限" } }
+```
+
+从返回里取 `note.id` 和笔记类型。关键词搜索只代表「被搜到的样本」，不能当成某个达人主页的完整历史。
+
+### 笔记详情与评论
+
+视频笔记用视频详情，图文笔记用图文详情。类型不清楚时先调视频详情，没有正文再调图文详情。`note_id` 与 `share_text` 二选一，不要两个都空着。
+
+```json
+{ "id": "xiaohongshu.app_v2.get_video_note_detail", "params": { "note_id": "<note_id>" } }
+```
+
+```json
+{ "id": "xiaohongshu.app_v2.get_image_note_detail", "params": { "note_id": "<note_id>" } }
+```
+
+一级评论用 `note_id`。楼中楼再把一级评论返回的 `comment_id` 传进去，首页 `start` 留空。
+
+```json
+{ "id": "xiaohongshu.note_comments", "params": { "note_id": "<note_id>" } }
+```
+
+```json
+{ "id": "xiaohongshu.sub_comments", "params": { "note_id": "<note_id>", "comment_id": "<comment_id>", "start": "" } }
+```
+
+### 用户、话题、商品
+
+用户资料和达人主页都要 24 位 hex `user_id`。只有昵称时，先走下面的达人主页链路，不要把小红书号或主页 URL 直接当 ID。
+
+```json
+{ "id": "xiaohongshu.app_v2.get_user_info", "params": { "user_id": "<24位hex user_id>" } }
+```
+
+话题笔记先从笔记详情的话题字段拿 `page_id`，再拉话题信息和话题流。`sort` 只用 `trend` 或 `time`。
+
+```json
+{ "id": "xiaohongshu.app_v2.get_topic_info", "params": { "page_id": "<page_id>" } }
+```
+
+```json
+{ "id": "xiaohongshu.app_v2.get_topic_feed", "params": { "page_id": "<page_id>", "sort": "trend" } }
+```
+
+商品搜索按页递增，翻页透传返回的 `search_id`。
+
+```json
+{ "id": "xiaohongshu.app_v2.search_products", "params": { "keyword": "防晒", "page": 1 } }
+```
+
+### 按达人主页采集
+
+用户要「某达人主页的笔记 / 按作者拉笔记 / 补齐某账号历史」时，不要猜 `get_user_note_list`、`/v1` 或其他未登记路径。先查清单，再按下面的链路调用。
+
+1. 只有昵称时，先用 `xiaohongshu.app_v2.search_users` 拿 24 位 hex `user_id`。不要把数字小红书号、昵称或主页 URL 直接当 `user_id`。
+2. 拉主页笔记优先用 `xiaohongshu.app_v2.get_user_posted_notes`。它走社媒网关，首页 `cursor` 留空，下一页透传上次返回的 `cursor`，直到 `has_more=false`。
+3. 这条社媒接口翻不完、或明确要电商通道的账号笔记时，改用 `xiaohongshu.get_user_note_list_v1`（`channel=ecommerce`）。入参是 `userId`，翻页透传 `lastCursor`。不要调用无版本号的 `get_user_note_list`。
+4. 拿到 `note_id` 后，再走上面的图文/视频详情和评论接口。关键词搜索只能证明「这些笔记被搜到」，不能代替达人主页全量列表。
+
+可直接传给 `voc_api_call` 的示例：
+
+```json
+{ "id": "xiaohongshu.app_v2.search_users", "params": { "keyword": "达人昵称", "page": 1 } }
+```
+
+```json
+{ "id": "xiaohongshu.app_v2.get_user_posted_notes", "params": { "user_id": "<24位hex user_id>", "cursor": "" } }
+```
+
+```json
+{ "id": "xiaohongshu.get_user_note_list_v1", "params": { "userId": "<24位hex user_id>", "lastCursor": "" } }
+```
+
+一次只拉一页。批量拉多个达人、多个关键词或持续翻页前，先用 `voc_cost_estimate` 估算次数，跑完用 `voc_usage_report` 核对实际消耗。
+
 ## 创作者侧情报（channel=ecommerce）
 
 抖音星图 / 小红书蒲公英（PGY）的创作者数据是 VOC 在**创作者生态**维度的情报源——它服务的是 VOC 一贯的「内容战略、竞对理解、受众洞察、选题与脚本」闭环，而**不是**「替用户挑达人投广告」。同一套数据用来回答这些 VOC 问题：

package/skills/xiaohongshu-trend-intelligence/references/live-mode.md

@@ -16,10 +16,11 @@ live 模式默认保持小规模：
 
 ## 接口优先级
 
-live 采集走可用链路，不再依赖已不稳定的旧 App 搜索/详情：
+live 采集只走健康的 V2：
 
-- 搜索：`app_v2/search_notes` → 失败/空结果再降级 `web_v3/fetch_search_notes`
-- 详情：优先 `app_v2/get_image_note_detail` / `app_v2/get_video_note_detail`，再回退 `app/get_note_info`
+- 搜索：`app_v2/search_notes`，空结果再降级 `web_v3/fetch_search_notes`
+- 达人主页：`app_v2/get_user_posted_notes`；只有昵称时先用 `app_v2/search_users` 拿 `user_id`
+- 详情：视频笔记用 `app_v2/get_video_note_detail`，图文笔记用 `app_v2/get_image_note_detail`
 - 评论：`app_v2/get_note_comments`
 
 ## 媒体持久化