feat(voc-skill): expand douyin/xiaohongshu catalog to 18 endpoints with param docs; de-brand gateway; v0.3.18

claude-code/claude-code-voc-intelligence/mcp/catalog/voc-social-endpoints.json

@@ -1,24 +1,27 @@
 {
-  "version": "1.0.0",
-  "updatedAt": "2026-06-21",
+  "version": "1.1.0",
+  "updatedAt": "2026-06-22",
   "gateway": {
     "social": {
       "baseUrl": "https://server.fmode.cn/api/voc-social",
       "auth": "Authorization: Bearer <r: 开头的会话 token>",
-      "upstream": "TikHub (server.fmode.cn/thapi/v1)",
+      "upstream": "我们的中转网关（已封装请求头，直接中转，对外不暴露具体数据供应商）。",
       "billing": "每次转发调用扣除 1 次社交平台 API 额度（缓存命中也会计费）。",
-      "note": "这是一个通用转发网关：任意 proxyPath 都会被透传到上游 TikHub。本清单只列出已验证的常用接口；未列出的接口可以直接用 voc_api_call 传 rawPath + method + params 调用，无需改代码。",
-      "rawPathHint": "调用未在清单中的接口时，把上游的相对路径填到 voc_api_call 的 rawPath，例如 douyin/search/fetch_general_search_v2，并按上游文档拼 query/body。"
+      "note": "这是一个通用转发网关：任意 proxyPath 都会被透传到我们的中转上游。本清单列出已验证的抖音、小红书常用接口；未列出的接口可以直接用 voc_api_call 传 rawPath + method + params 调用，无需改代码。",
+      "rawPathHint": "调用未在清单中的接口时，把相对路径填到 voc_api_call 的 rawPath，例如 douyin/search/fetch_general_search_v2，并按对应平台的参数规则拼 query/body。"
     }
   },
   "platforms": [
-    { "key": "douyin", "label": "抖音", "status": "verified" },
-    { "key": "xiaohongshu", "label": "小红书", "status": "verified" },
-    { "key": "tiktok", "label": "TikTok", "status": "gateway_available" },
-    { "key": "youtube", "label": "YouTube", "status": "gateway_available" },
-    { "key": "twitter", "label": "Twitter/X", "status": "gateway_available" },
-    { "key": "instagram", "label": "Instagram", "status": "gateway_available" },
-    { "key": "linkedin", "label": "LinkedIn", "status": "gateway_available" }
+    {
+      "key": "douyin",
+      "label": "抖音",
+      "status": "verified"
+    },
+    {
+      "key": "xiaohongshu",
+      "label": "小红书",
+      "status": "verified"
+    }
   ],
   "endpoints": [
     {
@@ -26,118 +29,937 @@
       "platform": "douyin",
       "channel": "social",
       "title": "抖音综合搜索",
-      "summary": "按关键词搜索抖音视频（综合搜索 v2）。任意行业/方向关键词均可用于趋势与 VOC 选题采集。",
+      "summary": "按关键词做抖音综合搜索（视频/用户/话题混合）。任意行业/方向关键词均可用于趋势与 VOC 选题采集。",
       "proxyPath": "douyin/search/fetch_general_search_v2",
       "method": "POST",
       "paramsIn": "body",
+      "tags": [
+        "抖音",
+        "douyin",
+        "搜索",
+        "search",
+        "综合",
+        "视频",
+        "关键词",
+        "voc",
+        "趋势"
+      ],
+      "params": [
+        {
+          "name": "keyword",
+          "in": "body",
+          "type": "string",
+          "required": true,
+          "desc": "搜索关键词，任意行业/方向均可，例如 股权律师、医美 玻尿酸、少儿编程、新能源汽车。"
+        },
+        {
+          "name": "cursor",
+          "in": "body",
+          "type": "integer",
+          "required": false,
+          "default": 0,
+          "desc": "分页偏移游标，首页为 0，翻页用上一次返回的 cursor。"
+        },
+        {
+          "name": "sort_type",
+          "in": "body",
+          "type": "string",
+          "required": false,
+          "default": "0",
+          "desc": "排序：0 综合，1 最多点赞，2 最新发布。"
+        },
+        {
+          "name": "publish_time",
+          "in": "body",
+          "type": "string",
+          "required": false,
+          "default": "0",
+          "desc": "发布时间：0 不限，1 一天内，7 一周内，180 半年内。"
+        },
+        {
+          "name": "filter_duration",
+          "in": "body",
+          "type": "string",
+          "required": false,
+          "default": "0",
+          "desc": "时长筛选：0 不限，0-1 一分钟内，1-5 一到五分钟，5-10000 五分钟以上。"
+        },
+        {
+          "name": "content_type",
+          "in": "body",
+          "type": "string",
+          "required": false,
+          "default": "0",
+          "desc": "内容类型：0 不限，1 视频，2 图集，3 文章。"
+        },
+        {
+          "name": "search_id",
+          "in": "body",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "连续翻页时透传上一次返回的 search_id。"
+        },
+        {
+          "name": "backtrace",
+          "in": "body",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "连续翻页时透传上一次返回的 backtrace。"
+        }
+      ],
+      "responseHint": "data 下为搜索结果列表，含视频 aweme_id、作者、标题、互动数；翻页用返回的 cursor/search_id。"
+    },
+    {
+      "id": "douyin.search_video",
+      "platform": "douyin",
+      "channel": "social",
+      "title": "抖音视频搜索",
+      "summary": "按关键词只搜索抖音视频。适合按词采集相关短视频做内容/口碑分析。",
+      "proxyPath": "douyin/search/fetch_video_search_v2",
+      "method": "POST",
+      "paramsIn": "body",
+      "tags": [
+        "抖音",
+        "douyin",
+        "视频",
+        "video",
+        "搜索",
+        "search",
+        "关键词"
+      ],
+      "params": [
+        {
+          "name": "keyword",
+          "in": "body",
+          "type": "string",
+          "required": true,
+          "desc": "搜索关键词，任意行业/方向均可，例如 股权律师、医美 玻尿酸、少儿编程、新能源汽车。"
+        },
+        {
+          "name": "cursor",
+          "in": "body",
+          "type": "integer",
+          "required": false,
+          "default": 0,
+          "desc": "分页偏移游标，首页为 0，翻页用上一次返回的 cursor。"
+        },
+        {
+          "name": "sort_type",
+          "in": "body",
+          "type": "string",
+          "required": false,
+          "default": "0",
+          "desc": "排序：0 综合，1 最多点赞，2 最新发布。"
+        },
+        {
+          "name": "publish_time",
+          "in": "body",
+          "type": "string",
+          "required": false,
+          "default": "0",
+          "desc": "发布时间：0 不限，1 一天内，7 一周内，180 半年内。"
+        },
+        {
+          "name": "filter_duration",
+          "in": "body",
+          "type": "string",
+          "required": false,
+          "default": "0",
+          "desc": "时长筛选：0 不限，0-1 一分钟内，1-5 一到五分钟，5-10000 五分钟以上。"
+        },
+        {
+          "name": "content_type",
+          "in": "body",
+          "type": "string",
+          "required": false,
+          "default": "0",
+          "desc": "内容类型：0 不限，1 视频，2 图集，3 文章。"
+        },
+        {
+          "name": "search_id",
+          "in": "body",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "连续翻页时透传上一次返回的 search_id。"
+        },
+        {
+          "name": "backtrace",
+          "in": "body",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "连续翻页时透传上一次返回的 backtrace。"
+        }
+      ],
+      "responseHint": "返回视频列表，含 aweme_id、作者、统计数据；翻页用 cursor/search_id。"
+    },
+    {
+      "id": "douyin.search_user",
+      "platform": "douyin",
+      "channel": "social",
+      "title": "抖音用户搜索",
+      "summary": "按关键词搜索抖音用户/账号，定位某行业的达人或竞品账号。",
+      "proxyPath": "douyin/search/fetch_user_search_v2",
+      "method": "POST",
+      "paramsIn": "body",
+      "tags": [
+        "抖音",
+        "douyin",
+        "用户",
+        "user",
+        "账号",
+        "搜索",
+        "search",
+        "达人",
+        "kol"
+      ],
       "params": [
-        { "name": "keyword", "in": "body", "type": "string", "required": true, "desc": "搜索关键词，任意行业/方向均可，例如 股权律师、医美 玻尿酸、少儿编程、新能源汽车。" },
-        { "name": "cursor", "in": "body", "type": "integer", "required": false, "default": 0, "desc": "分页游标，首页为 0，翻页用上一次返回的 cursor。" },
-        { "name": "sort_type", "in": "body", "type": "string", "required": false, "default": "0", "desc": "排序：0 综合，1 最多点赞，2 最新发布。" },
-        { "name": "publish_time", "in": "body", "type": "string", "required": false, "default": "0", "desc": "发布时间：0 不限，1 一天内，7 一周内，180 半年内。" },
-        { "name": "filter_duration", "in": "body", "type": "string", "required": false, "default": "0", "desc": "时长筛选：0 不限，0-1 一分钟内，1-5 一到五分钟，5-10000 五分钟以上。" },
-        { "name": "content_type", "in": "body", "type": "string", "required": false, "default": "0", "desc": "内容类型：0 不限，1 视频，2 图集，3 文章。" },
-        { "name": "search_id", "in": "body", "type": "string", "required": false, "default": "", "desc": "连续翻页时透传上一次返回的 search_id。" },
-        { "name": "backtrace", "in": "body", "type": "string", "required": false, "default": "", "desc": "连续翻页时透传上一次返回的 backtrace。" }
+        {
+          "name": "keyword",
+          "in": "body",
+          "type": "string",
+          "required": true,
+          "desc": "搜索关键词（账号名/行业词）。"
+        },
+        {
+          "name": "cursor",
+          "in": "body",
+          "type": "integer",
+          "required": false,
+          "default": 0,
+          "desc": "分页偏移游标，首页为 0。"
+        },
+        {
+          "name": "search_id",
+          "in": "body",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "连续翻页时透传上一次返回的 search_id。"
+        }
       ],
-      "tags": ["抖音", "douyin", "搜索", "search", "视频", "关键词", "趋势", "voc"],
-      "billing": 1,
-      "responseHint": "返回视频列表，每条含 aweme_id、desc、统计字段等；aweme_id 可用于拉取评论。",
-      "example": { "keyword": "新能源汽车", "cursor": 0, "sort_type": "0" }
+      "responseHint": "返回用户列表，含 sec_user_id、昵称、粉丝数；sec_user_id 可继续用于 user_profile / user_posts。"
+    },
+    {
+      "id": "douyin.video_detail",
+      "platform": "douyin",
+      "channel": "social",
+      "title": "抖音视频详情",
+      "summary": "按视频 id 获取单个抖音视频的完整数据（标题、作者、统计、视频地址等）。",
+      "proxyPath": "douyin/app/v3/fetch_one_video",
+      "method": "GET",
+      "paramsIn": "query",
+      "tags": [
+        "抖音",
+        "douyin",
+        "视频",
+        "video",
+        "详情",
+        "detail",
+        "aweme"
+      ],
+      "params": [
+        {
+          "name": "aweme_id",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "视频 id（aweme_id），来自搜索/评论返回。"
+        }
+      ],
+      "responseHint": "返回单个视频对象，含统计、作者、话题、视频/图集地址。"
     },
     {
       "id": "douyin.video_comments",
       "platform": "douyin",
       "channel": "social",
       "title": "抖音视频评论列表",
-      "summary": "按 aweme_id 拉取某条抖音视频的评论，用于采集真实用户声音（VOC）。",
+      "summary": "按视频 id 拉取抖音视频的一级评论。VOC 主力接口：采集用户真实评论。",
       "proxyPath": "douyin/app/v3/fetch_video_comments",
       "method": "GET",
       "paramsIn": "query",
+      "tags": [
+        "抖音",
+        "douyin",
+        "评论",
+        "comment",
+        "voc",
+        "口碑",
+        "视频"
+      ],
       "params": [
-        { "name": "aweme_id", "in": "query", "type": "string", "required": true, "desc": "视频 ID，来自抖音综合搜索结果。" },
-        { "name": "cursor", "in": "query", "type": "integer", "required": false, "default": 0, "desc": "评论分页游标，首页 0。" },
-        { "name": "count", "in": "query", "type": "integer", "required": false, "default": 20, "desc": "每页评论数，建议 20。" }
+        {
+          "name": "aweme_id",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "视频 id（aweme_id）。"
+        },
+        {
+          "name": "cursor",
+          "in": "query",
+          "type": "integer",
+          "required": false,
+          "default": 0,
+          "desc": "分页游标，首页为 0，翻页用上一次返回的 cursor。"
+        },
+        {
+          "name": "count",
+          "in": "query",
+          "type": "integer",
+          "required": false,
+          "default": 20,
+          "desc": "每页数量，建议 20。"
+        }
       ],
-      "tags": ["抖音", "douyin", "评论", "comments", "voc", "用户声音"],
-      "billing": 1,
-      "responseHint": "返回评论列表，含评论文本、点赞数、cid（用于拉取楼中楼回复）。",
-      "example": { "aweme_id": "7300000000000000000", "cursor": 0, "count": 20 }
+      "responseHint": "返回评论列表，含 comment_id、文本、点赞、子评论数；翻页用返回的 cursor。"
     },
     {
       "id": "douyin.comment_replies",
       "platform": "douyin",
       "channel": "social",
-      "title": "抖音评论回复（楼中楼）",
-      "summary": "按视频 item_id 和评论 comment_id 拉取某条评论下的回复。",
+      "title": "抖音评论回复",
+      "summary": "按视频 id + 评论 id 拉取某条评论下的回复（楼中楼），用于深挖讨论。",
       "proxyPath": "douyin/app/v3/fetch_video_comment_replies",
       "method": "GET",
       "paramsIn": "query",
+      "tags": [
+        "抖音",
+        "douyin",
+        "评论",
+        "回复",
+        "reply",
+        "comment",
+        "楼中楼",
+        "voc"
+      ],
+      "params": [
+        {
+          "name": "item_id",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "视频 id（aweme_id）。"
+        },
+        {
+          "name": "comment_id",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "一级评论 id，来自 video_comments 返回。"
+        },
+        {
+          "name": "cursor",
+          "in": "query",
+          "type": "integer",
+          "required": false,
+          "default": 0,
+          "desc": "分页游标，首页为 0。"
+        },
+        {
+          "name": "count",
+          "in": "query",
+          "type": "integer",
+          "required": false,
+          "default": 20,
+          "desc": "每页数量，建议 20。"
+        }
+      ],
+      "responseHint": "返回某条评论的回复列表；翻页用返回的 cursor。"
+    },
+    {
+      "id": "douyin.user_profile",
+      "platform": "douyin",
+      "channel": "social",
+      "title": "抖音用户主页信息",
+      "summary": "按 sec_user_id 获取抖音用户主页资料（昵称、签名、粉丝/获赞等）。",
+      "proxyPath": "douyin/app/v3/handler_user_profile",
+      "method": "GET",
+      "paramsIn": "query",
+      "tags": [
+        "抖音",
+        "douyin",
+        "用户",
+        "user",
+        "主页",
+        "profile",
+        "达人",
+        "竞品"
+      ],
+      "params": [
+        {
+          "name": "sec_user_id",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "用户 sec_user_id，来自 search_user 或视频返回。"
+        }
+      ],
+      "responseHint": "返回用户资料对象，含粉丝数、获赞数、作品数、签名。"
+    },
+    {
+      "id": "douyin.user_posts",
+      "platform": "douyin",
+      "channel": "social",
+      "title": "抖音用户发布视频",
+      "summary": "按 sec_user_id 拉取某用户主页发布的视频列表，用于竞品/达人内容盘点。",
+      "proxyPath": "douyin/app/v3/fetch_user_post_videos",
+      "method": "GET",
+      "paramsIn": "query",
+      "tags": [
+        "抖音",
+        "douyin",
+        "用户",
+        "作品",
+        "posts",
+        "video",
+        "竞品",
+        "达人"
+      ],
+      "params": [
+        {
+          "name": "sec_user_id",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "用户 sec_user_id。"
+        },
+        {
+          "name": "max_cursor",
+          "in": "query",
+          "type": "integer",
+          "required": false,
+          "default": 0,
+          "desc": "分页游标，首页为 0，翻页用上一次返回的 max_cursor。"
+        },
+        {
+          "name": "count",
+          "in": "query",
+          "type": "integer",
+          "required": false,
+          "default": 20,
+          "desc": "每页数量，建议 20。"
+        },
+        {
+          "name": "sort_type",
+          "in": "query",
+          "type": "integer",
+          "required": false,
+          "default": 0,
+          "desc": "排序类型，0 默认。"
+        }
+      ],
+      "responseHint": "返回该用户的视频列表；翻页用返回的 max_cursor。"
+    },
+    {
+      "id": "douyin.video_statistics",
+      "platform": "douyin",
+      "channel": "social",
+      "title": "抖音视频数据统计",
+      "summary": "按一个或多个视频 id 获取统计数据（点赞、下载、播放、分享）。",
+      "proxyPath": "douyin/app/v3/fetch_video_statistics",
+      "method": "GET",
+      "paramsIn": "query",
+      "tags": [
+        "抖音",
+        "douyin",
+        "统计",
+        "statistics",
+        "点赞",
+        "播放",
+        "视频"
+      ],
       "params": [
-        { "name": "item_id", "in": "query", "type": "string", "required": true, "desc": "视频 ID（同 aweme_id）。" },
-        { "name": "comment_id", "in": "query", "type": "string", "required": true, "desc": "父评论 ID（来自评论列表的 cid）。" },
-        { "name": "cursor", "in": "query", "type": "integer", "required": false, "default": 0, "desc": "回复分页游标。" },
-        { "name": "count", "in": "query", "type": "integer", "required": false, "default": 20, "desc": "每页回复数。" }
+        {
+          "name": "aweme_ids",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "视频 id，多个用逗号分隔（aweme_ids）。"
+        }
       ],
-      "tags": ["抖音", "douyin", "评论", "回复", "replies", "voc"],
-      "billing": 1,
-      "responseHint": "返回某条父评论下的回复列表。",
-      "example": { "item_id": "7300000000000000000", "comment_id": "7300000000000000001", "cursor": 0, "count": 20 }
+      "responseHint": "返回各视频的 like/play/download/share 统计。"
+    },
+    {
+      "id": "douyin.hot_search_list",
+      "platform": "douyin",
+      "channel": "social",
+      "title": "抖音热搜榜",
+      "summary": "获取抖音热搜榜单数据，用于选题与趋势监测。",
+      "proxyPath": "douyin/app/v3/fetch_hot_search_list",
+      "method": "GET",
+      "paramsIn": "query",
+      "tags": [
+        "抖音",
+        "douyin",
+        "热搜",
+        "hot",
+        "榜单",
+        "趋势",
+        "选题"
+      ],
+      "params": [
+        {
+          "name": "board_type",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "0",
+          "desc": "榜单类型，0 默认热榜。"
+        },
+        {
+          "name": "board_sub_type",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "榜单子类型，可留空。"
+        }
+      ],
+      "responseHint": "返回热搜词条列表，含热度值。"
     },
     {
       "id": "xiaohongshu.search_notes",
       "platform": "xiaohongshu",
       "channel": "social",
       "title": "小红书笔记搜索",
-      "summary": "按关键词搜索小红书笔记，任意行业/方向均可，用于趋势与 VOC 选题采集。",
+      "summary": "按关键词搜索小红书笔记。任意行业/方向关键词均可用于 VOC 选题与口碑采集。",
       "proxyPath": "xiaohongshu/app/search_notes",
       "method": "GET",
       "paramsIn": "query",
+      "tags": [
+        "小红书",
+        "xiaohongshu",
+        "xhs",
+        "笔记",
+        "note",
+        "搜索",
+        "search",
+        "关键词",
+        "voc"
+      ],
       "params": [
-        { "name": "keyword", "in": "query", "type": "string", "required": true, "desc": "搜索关键词，任意行业/方向均可。" },
-        { "name": "page", "in": "query", "type": "integer", "required": false, "default": 1, "desc": "页码，从 1 开始。" },
-        { "name": "sort", "in": "query", "type": "string", "required": false, "default": "popularity_descending", "desc": "排序：general 综合，time_descending 最新，popularity_descending 最热。" },
-        { "name": "note_type", "in": "query", "type": "string", "required": false, "default": "_0", "desc": "笔记类型：_0 不限，_1 视频，_2 图文。" }
+        {
+          "name": "keyword",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "搜索关键词，任意行业/方向均可。"
+        },
+        {
+          "name": "page",
+          "in": "query",
+          "type": "integer",
+          "required": true,
+          "default": 1,
+          "desc": "页码，从 1 开始，翻页递增。"
+        },
+        {
+          "name": "sort_type",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "general",
+          "desc": "排序：general 综合，time_descending 最新，popularity_descending 最热。"
+        },
+        {
+          "name": "filter_note_type",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "不限",
+          "desc": "笔记类型筛选：不限 / 视频 / 图文。"
+        },
+        {
+          "name": "filter_note_time",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "不限",
+          "desc": "发布时间筛选：不限 / 一天内 / 一周内 / 半年内。"
+        },
+        {
+          "name": "search_id",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "连续翻页时透传上一次返回的 search_id。"
+        },
+        {
+          "name": "session_id",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "连续翻页时透传上一次返回的 session_id。"
+        }
       ],
-      "tags": ["小红书", "xiaohongshu", "xhs", "搜索", "search", "笔记", "关键词", "趋势", "voc"],
-      "billing": 1,
-      "responseHint": "返回笔记列表，每条含 note_id，可用于拉取详情和评论。",
-      "example": { "keyword": "敏感肌护肤", "page": 1, "sort": "popularity_descending", "note_type": "_0" }
+      "responseHint": "返回笔记列表，含 note_id、标题、作者、互动数；翻页递增 page 并透传 search_id/session_id。"
     },
     {
       "id": "xiaohongshu.note_detail",
       "platform": "xiaohongshu",
       "channel": "social",
       "title": "小红书笔记详情",
-      "summary": "按 note_id 拉取小红书笔记详情（正文、图片、统计等）。",
+      "summary": "按 note_id（或分享文案）获取小红书笔记完整内容。",
       "proxyPath": "xiaohongshu/app/get_note_info",
       "method": "GET",
       "paramsIn": "query",
+      "tags": [
+        "小红书",
+        "xiaohongshu",
+        "xhs",
+        "笔记",
+        "note",
+        "详情",
+        "detail"
+      ],
       "params": [
-        { "name": "note_id", "in": "query", "type": "string", "required": true, "desc": "笔记 ID，来自搜索结果。" }
+        {
+          "name": "note_id",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "笔记 id（note_id），来自 search_notes 返回。"
+        },
+        {
+          "name": "share_text",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "可选：直接传小红书分享文案/链接，与 note_id 二选一。"
+        }
       ],
-      "tags": ["小红书", "xiaohongshu", "xhs", "笔记", "详情", "note"],
-      "billing": 1,
-      "responseHint": "返回单条笔记的完整内容。",
-      "example": { "note_id": "650000000000000000000000" }
+      "responseHint": "返回单条笔记对象，含正文、图片/视频、话题、互动数。"
     },
     {
       "id": "xiaohongshu.note_comments",
       "platform": "xiaohongshu",
       "channel": "social",
       "title": "小红书笔记评论",
-      "summary": "按 note_id 拉取小红书笔记评论，用于采集真实用户声音（VOC）。",
+      "summary": "按 note_id 拉取小红书笔记的一级评论。VOC 主力接口。",
       "proxyPath": "xiaohongshu/app/get_note_comments",
       "method": "GET",
       "paramsIn": "query",
+      "tags": [
+        "小红书",
+        "xiaohongshu",
+        "xhs",
+        "评论",
+        "comment",
+        "voc",
+        "口碑"
+      ],
+      "params": [
+        {
+          "name": "note_id",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "笔记 id（note_id）。"
+        },
+        {
+          "name": "start",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "分页游标，首页留空，翻页用上一次返回的 start。"
+        },
+        {
+          "name": "sort_strategy",
+          "in": "query",
+          "type": "integer",
+          "required": false,
+          "default": 1,
+          "desc": "排序：1 默认。"
+        }
+      ],
+      "responseHint": "返回评论列表，含 comment_id、文本、点赞、子评论数；翻页用返回的 start。"
+    },
+    {
+      "id": "xiaohongshu.sub_comments",
+      "platform": "xiaohongshu",
+      "channel": "social",
+      "title": "小红书评论回复（楼中楼）",
+      "summary": "按 note_id + comment_id 拉取某条评论下的回复，用于深挖讨论。",
+      "proxyPath": "xiaohongshu/app/get_sub_comments",
+      "method": "GET",
+      "paramsIn": "query",
+      "tags": [
+        "小红书",
+        "xiaohongshu",
+        "xhs",
+        "评论",
+        "回复",
+        "reply",
+        "sub",
+        "楼中楼",
+        "voc"
+      ],
+      "params": [
+        {
+          "name": "note_id",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "笔记 id（note_id）。"
+        },
+        {
+          "name": "comment_id",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "一级评论 id，来自 note_comments 返回。"
+        },
+        {
+          "name": "start",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "分页游标，首页留空，翻页用上一次返回的 start。"
+        }
+      ],
+      "responseHint": "返回某条评论的回复列表；翻页用返回的 start。"
+    },
+    {
+      "id": "xiaohongshu.user_info",
+      "platform": "xiaohongshu",
+      "channel": "social",
+      "title": "小红书用户信息",
+      "summary": "按 user_id 获取小红书用户资料（昵称、简介、粉丝/获赞等）。",
+      "proxyPath": "xiaohongshu/app/get_user_info",
+      "method": "GET",
+      "paramsIn": "query",
+      "tags": [
+        "小红书",
+        "xiaohongshu",
+        "xhs",
+        "用户",
+        "user",
+        "信息",
+        "profile",
+        "达人",
+        "竞品"
+      ],
+      "params": [
+        {
+          "name": "user_id",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "用户 id（user_id），来自笔记/搜索返回。"
+        }
+      ],
+      "responseHint": "返回用户资料对象，含粉丝数、获赞收藏、简介。"
+    },
+    {
+      "id": "xiaohongshu.user_notes",
+      "platform": "xiaohongshu",
+      "channel": "social",
+      "title": "小红书用户发布笔记",
+      "summary": "按 user_id 拉取某用户发布的笔记列表，用于竞品/达人内容盘点。",
+      "proxyPath": "xiaohongshu/app/get_user_notes",
+      "method": "GET",
+      "paramsIn": "query",
+      "tags": [
+        "小红书",
+        "xiaohongshu",
+        "xhs",
+        "用户",
+        "笔记",
+        "notes",
+        "posts",
+        "竞品",
+        "达人"
+      ],
+      "params": [
+        {
+          "name": "user_id",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "用户 id（user_id）。"
+        },
+        {
+          "name": "cursor",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "分页游标，首页留空，翻页用上一次返回的 cursor。"
+        }
+      ],
+      "responseHint": "返回该用户的笔记列表；翻页用返回的 cursor。"
+    },
+    {
+      "id": "xiaohongshu.topic_notes",
+      "platform": "xiaohongshu",
+      "channel": "social",
+      "title": "小红书话题笔记",
+      "summary": "按话题 page_id 拉取该话题下的笔记，用于话题/品类维度的 VOC 采集。",
+      "proxyPath": "xiaohongshu/app/get_topic_notes",
+      "method": "GET",
+      "paramsIn": "query",
+      "tags": [
+        "小红书",
+        "xiaohongshu",
+        "xhs",
+        "话题",
+        "topic",
+        "笔记",
+        "品类",
+        "voc"
+      ],
+      "params": [
+        {
+          "name": "page_id",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "话题 page_id。"
+        },
+        {
+          "name": "first_load_time",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "首次加载时间戳（秒），首次请求传当前时间戳。"
+        },
+        {
+          "name": "sort",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "hot",
+          "desc": "排序：hot 最热 / time 最新。"
+        },
+        {
+          "name": "last_note_ct",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "翻页透传上一次返回的 last_note_ct。"
+        },
+        {
+          "name": "last_note_id",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "翻页透传上一次返回的 last_note_id。"
+        },
+        {
+          "name": "cursor_score",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "翻页透传上一次返回的 cursor_score。"
+        },
+        {
+          "name": "session_id",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "翻页透传上一次返回的 session_id。"
+        }
+      ],
+      "responseHint": "返回话题下笔记列表；翻页透传 last_note_ct/last_note_id/cursor_score/session_id。"
+    },
+    {
+      "id": "xiaohongshu.search_products",
+      "platform": "xiaohongshu",
+      "channel": "social",
+      "title": "小红书商品搜索",
+      "summary": "按关键词搜索小红书商品（带价格/服务保障筛选），用于电商相关 VOC。",
+      "proxyPath": "xiaohongshu/app/search_products",
+      "method": "GET",
+      "paramsIn": "query",
+      "tags": [
+        "小红书",
+        "xiaohongshu",
+        "xhs",
+        "商品",
+        "product",
+        "电商",
+        "搜索",
+        "search"
+      ],
       "params": [
-        { "name": "note_id", "in": "query", "type": "string", "required": true, "desc": "笔记 ID，来自搜索结果。" },
-        { "name": "cursor", "in": "query", "type": "string", "required": false, "default": "", "desc": "评论分页游标，翻页用上一次返回的 cursor。" }
+        {
+          "name": "keyword",
+          "in": "query",
+          "type": "string",
+          "required": true,
+          "desc": "搜索关键词。"
+        },
+        {
+          "name": "page",
+          "in": "query",
+          "type": "integer",
+          "required": true,
+          "default": 1,
+          "desc": "页码，从 1 开始。"
+        },
+        {
+          "name": "sort",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "排序方式，可留空用默认。"
+        },
+        {
+          "name": "scope",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "筛选范围，可留空。"
+        },
+        {
+          "name": "min_price",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "最低价筛选，可留空。"
+        },
+        {
+          "name": "max_price",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "最高价筛选，可留空。"
+        },
+        {
+          "name": "search_id",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "连续翻页时透传上一次返回的 search_id。"
+        },
+        {
+          "name": "session_id",
+          "in": "query",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "desc": "连续翻页时透传上一次返回的 session_id。"
+        }
       ],
-      "tags": ["小红书", "xiaohongshu", "xhs", "评论", "comments", "voc", "用户声音"],
-      "billing": 1,
-      "responseHint": "返回笔记评论列表。",
-      "example": { "note_id": "650000000000000000000000", "cursor": "" }
+      "responseHint": "返回商品列表，含标题、价格、销量、店铺。"
     }
   ]
-}
+}

claude-code/claude-code-voc-intelligence/mcp/src/tools/voc-api-catalog-run.js

@@ -39,7 +39,7 @@ async function searchVocApis(input = {}) {
   const lines = [
     '## VOC 转发接口清单',
     '',
-    `网关：${catalog.gateway?.social?.baseUrl || ''}（通用转发，任意 proxyPath 透传到上游 TikHub；每次调用计费 1 次）。`,
+    `网关：${catalog.gateway?.social?.baseUrl || ''}（通用转发，任意 proxyPath 透传到我们的中转上游；每次调用计费 1 次）。`,
     query ? `匹配关键词「${query}」的接口（${results.length} 条）：` : `全部已登记接口（${results.length} 条）：`,
     '',
     ...results.map(
@@ -196,14 +196,17 @@ async function callVocApi(input = {}) {
     method = endpoint.method;
     const parts = buildRequestParts(endpoint, input);
     if (parts.missing.length) {
-      return errorResult(
-        `缺少必填参数：${parts.missing.join(', ')}。这不是类目/关键词/余额问题，请补齐参数后再调用（可用 voc_api_doc 查看参数说明）。`,
-        {
-          status: 'needs_input',
-          summary: { endpoint: endpoint.id, missing: parts.missing },
-          data: { endpoint: summarizeEndpoint(endpoint), missing: parts.missing }
-        }
-      );
+      const missingMessage = `缺少必填参数：${parts.missing.join(', ')}。这不是类目/关键词/余额问题，请补齐参数后再调用（可用 voc_api_doc 查看参数说明）。`;
+      return {
+        status: 'needs_input',
+        assistantMessage: missingMessage,
+        summary: { endpoint: endpoint.id, missing: parts.missing },
+        data: { endpoint: summarizeEndpoint(endpoint), missing: parts.missing },
+        files: [],
+        nextActions: ['用 voc_api_doc 核对必填参数', '补齐参数后重新调用'],
+        warnings: [],
+        errors: [{ message: `缺少必填参数：${parts.missing.join(', ')}`, kind: 'request', httpStatus: 0 }]
+      };
     }
     query = parts.query;
     body = parts.body;

claude-code/claude-code-voc-intelligence/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@vocmarket/voc-skill",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@vocmarket/voc-skill",
-      "version": "0.3.17",
+      "version": "0.3.18",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.29.0",
         "zod": "^4.4.3"

claude-code/claude-code-voc-intelligence/package.json

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

claude-code/claude-code-voc-intelligence/skills/voc-api-catalog/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: voc-api-catalog
-description: 清单驱动的 VOC 社交数据采集。把所有转发接口做成清单，按需查清单、读参数文档，自己拼参数完成任意行业/任意方向的社交数据采集（抖音、小红书及 TikHub 上游其他平台）。当用户要采集某关键词的社交内容/评论、要调用某个社交数据接口、或现有专用工具不覆盖某接口时使用。
+description: 清单驱动的 VOC 社交数据采集。把所有转发接口做成清单，按需查清单、读参数文档，自己拼参数完成任意行业/任意方向的社交数据采集（目前覆盖抖音、小红书等国内社媒）。当用户要采集某关键词的社交内容/评论、要调用某个社交数据接口、或现有专用工具不覆盖某接口时使用。
 ---
 
 # VOC 接口清单驱动采集
 
 ## 核心理念
 
-VOC 后端是一个**通用转发网关**（`https://server.fmode.cn/api/voc-social/<proxyPath>`），任意 `proxyPath` 都会被透传到上游 TikHub。所以不需要为每个接口写死一个工具：你只要
+VOC 后端是一个**通用转发网关**（`https://server.fmode.cn/api/voc-social/<proxyPath>`），任意 `proxyPath` 都会被透传到我们的中转上游（请求头已封装，对外不暴露具体数据供应商）。所以不需要为每个接口写死一个工具：你只要
 
 1. **查清单**：用 `voc_api_search` 找到要用的接口；
 2. **读参数文档**：用 `voc_api_doc` 读该接口的详细参数；