@vocmarket/voc-skill 0.3.39 → 0.3.41

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.39",
+  "version": "0.3.41",
   "author": {
     "name": "nkkj-BrainHack"
   }

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

@@ -10510,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",
@@ -10521,7 +10521,11 @@
         "v2"
       ],
       "requiredParams": [],
-      "recommendationPriority": 50
+      "recommendationPriority": 95,
+      "recommendedFor": [
+        "creator_homepage"
+      ],
+      "responseHint": "返回 notes、has_more、cursor。翻页时把 cursor 原样传回，直到 has_more=false。"
     },
     {
       "id": "xiaohongshu.app_v2.get_user_faved_notes",
@@ -10568,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",
@@ -10580,6 +10584,10 @@
       ],
       "requiredParams": [
         "keyword"
+      ],
+      "recommendationPriority": 85,
+      "recommendedFor": [
+        "creator_homepage"
       ]
     },
     {
@@ -23262,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",
@@ -23283,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.39'
+    version: '0.3.41'
   });
 
   server.registerTool(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vocmarket/voc-skill",
-  "version": "0.3.39",
+  "version": "0.3.41",
   "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.39",
+  "version": "0.3.41",
   "capabilities": {
     "summary": "三类情报源同源接入：①社媒内容（含抖音/小红书/微信视频号等）②国内电商+创作者情报 ③海外选品。统一 search→doc→call、鉴权计费一致。",
     "channels": [

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

@@ -48,7 +48,34 @@ VOC 后端是一个**通用转发网关**（`https://server.fmode.cn/api/voc-soc
 
 ## 小红书现用接口（V2）
 
-小红书社媒采集只走下面这些健康的 V2 接口。`voc_api_search` 会把它们排在前面；标了 `deprecated` 的旧接口不要调用，也不要在给用户的说明里提到。
+客户 Agent 处理小红书时，先按任务选接口，再用下表的 `id` 调 `voc_api_call`。不要手写未登记路径，不要给路径自行追加版本号，也不要把标了 `deprecated` 的旧接口告诉用户。
+
+| 用户任务 | 第一步 | 下一步 | 不能下的结论 |
+|---|---|---|---|
+| 找某话题/关键词下的笔记 | `xiaohongshu.app_v2.search_notes` | 按 `type` 取详情，再取评论 | 这是搜索样本，不是达人主页全量 |
+| 看某条笔记完整内容和素材 | 视频用 `xiaohongshu.app_v2.get_video_note_detail`，图文用 `xiaohongshu.app_v2.get_image_note_detail` | 用 `note_id` 拉评论 | 类型不明时先试视频，空结果再试图文 |
+| 看用户怎么评价 | `xiaohongshu.note_comments` | 有回复时用 `xiaohongshu.sub_comments` | 只拉一级评论时，不能称已看完全部讨论 |
+| 找某个达人/账号 | `xiaohongshu.app_v2.search_users` | 取 24 位 hex `userid` 后拉资料和主页 | 昵称搜索结果不是该账号全部笔记 |
+| 拉达人主页历史 | `xiaohongshu.app_v2.get_user_posted_notes` | 翻完后再补详情和评论 | 关键词搜索不能代替主页列表 |
+| 看话题内容 | 从笔记详情取得话题 `id` 后调用 `xiaohongshu.app_v2.get_topic_feed` | 话题详情接口当前会返回参数错误，不要用它判断平台是否可用 | 没有话题 `id` 时不能猜话题接口 |
+| 找站内商品 | `xiaohongshu.app_v2.search_products` | 用返回的商品字段继续读取 | 这是商品搜索，不是笔记口碑 |
+| 看蒲公英创作者经营数据 | `xiaohongshu.pgy.creator_search` | 用返回的 `userId` 补画像、粉丝、笔记绩效 | 这是创作者生态数据，不是投放采买建议 |
+
+### 字段怎么接
+
+- 笔记：搜索或主页结果里的 `note.id` / `id` 作为后续 `note_id`；`type` 含 `video` 走视频详情，否则走图文详情。
+- 评论：一级评论返回的 `comments[].id` 作为楼中楼的 `comment_id`。`sub_comment_count > 0` 才需要继续拉楼中楼。
+- 用户：笔记结果使用 24 位 hex 的 `user.userid`；用户搜索结果使用 24 位 hex 的 `users[].id`。数字 `red_id`、昵称、主页 URL 都不是 `user_id`。
+- 话题：从笔记详情的 `topics` 或 `hash_tag` 读取 `id`，作为 `page_id`。搜索卡片里的展示标签不一定有这个 ID。
+- 翻页字段必须原样透传。笔记搜索用 `page`、`search_id`、`search_session_id`；达人主页先看顶层 `cursor`，没有时再用本页最后一条笔记的 `cursor`，并用 `has_more` 判断停止；电商主页备用接口用 `lastCursor`；楼中楼用 `start`。
+
+### 参数边界
+
+- 笔记搜索：`sort_type` 只取 `general`、`time_descending`、`popularity_descending`；`note_type` 只取 `不限`、`视频笔记`、`普通笔记`。
+- 话题流：`sort` 只取 `trend`、`time`。
+- 详情、用户资料、达人主页都是 `note_id`/`user_id` 与 `share_text` 二选一，不能两个都空着。
+- 一次调用只取一页。需要多关键词、多账号或持续翻页时，先用 `voc_cost_estimate` 估算，结束后用 `voc_usage_report` 核对。
+- 空列表要保留为「本次查询无结果」。只有缺少必填参数时才是 `needs_input`，不要改关键词来掩盖参数错误。
 
 | 用途 | 接口 id | proxyPath | 必填 |
 |---|---|---|---|
@@ -57,13 +84,113 @@ VOC 后端是一个**通用转发网关**（`https://server.fmode.cn/api/voc-soc
 | 视频详情 | `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.search_users` | `xiaohongshu/app_v2/search_users` | `keyword` |
 | 用户资料 | `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` |
 
-搜索先用 `xiaohongshu.app_v2.search_notes` 拿 `note_id`，再按笔记类型选图文或视频详情，评论和楼中楼继续用上表两条。不确定类型时先试视频详情，空结果再试图文详情。具体参数用 `voc_api_doc` 读取，不要手写旧路径。
+不要手写未登记路径，也不要在路径后面自己加 `/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>" } }
+```
+
+话题内容从笔记详情的 `topics[].id` 读取，传给话题流的 `page_id`。`sort` 只用 `trend` 或 `time`。`xiaohongshu.app_v2.get_topic_info` 目前用该 ID 会返回参数错误，不能作为话题能力是否可用的依据；先使用话题流结果。
+
+```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` 核对实际消耗。
+
+### 单次失败时怎么处理
+
+一次 404、500 或空结果，只能说明「这一次请求或这一条路径失败」，不能据此说小红书能力不可用。先用同一凭证调用 `xiaohongshu.app_v2.search_notes` 做一次最小探测；它成功就说明采集通道仍可用，然后按失败类型处理：
+
+| 看到的结果 | 实际含义 | 下一步 |
+|---|---|---|
+| 404，或路径是自己拼的 `get_user_note_list`、无版本号路径 | 路径不存在，不是平台没有此能力 | 回到本表选择现用 `id`。达人主页改用 `xiaohongshu.app_v2.get_user_posted_notes` |
+| 500，且路径包含旧的 `xiaohongshu/app/` | 旧接口失效 | 改用同用途的 `app_v2` 接口，不要把旧路径报告给用户 |
+| `needs_input`、参数错误 | 入参不完整或类型不对 | 用 `voc_api_doc` 核对。不要改关键词，也不要换一条路径碰运气 |
+| 视频详情无正文 | 笔记类型可能判断错 | 再用 `xiaohongshu.app_v2.get_image_note_detail` 试一次 |
+| 详情或主页没有 `page_id` | 当前结果没带话题 ID | 到笔记详情的 `topics`、`hash_tag` 中提取；仍没有就说明本次不能做话题分析 |
+| 空列表且参数正确 | 本次查询没有匹配数据 | 如实说无结果。不要声称接口损坏或该行业不支持 |
+| `upstream_unstable`、5xx、超时 | 上游波动 | 用原参数重试，不要改成 WebSearch 或其它抓取方式 |
+| `needs_token`、`needs_valid_token` | 凭证没读到或无效 | 按错误码速查自救，不要说功能下线 |
+| 只有 HTTP 402 | 当前 VOC 账户额度不足 | 转述充值入口。内层业务码或其它账户的额度问题不能混报成用户余额不足 |
+
+探测请求也算一次调用。通道确认可用后，不要重复探测；回到用户原始任务继续。若现用接口和清单里的替代接口都按文档重试后仍失败，才说明是本次采集失败，并保留工具返回的 `status`，不能扩大成「小红书不可用」。
 
 ## 创作者侧情报（channel=ecommerce）
 

package/skills/xiaohongshu-trend-intelligence/SKILL.md

@@ -71,6 +71,7 @@ node "<插件目录>/mcp/src/tools/xiaohongshu-trend-run.js" --collection-mode l
 - `references/user-workflow.md`：用户交互流程——第一次使用要问清的三件事、澄清话术、样例 vs 真实采集的判断。
 - `references/output-format.md`：第一轮趋势情报的推荐输出结构与段落格式。
 - `references/live-mode.md`：live 真实采集模式的接入说明与执行细节（先 sample 跑通再 live）。
+- 指定达人主页、单条笔记、话题或商品时，读取 voc-api-catalog 的「小红书现用接口」：先按任务选接口，再按 `note_id`、24 位 `userid`、`comment_id`、`page_id` 和对应游标衔接。
 - 错误码 / 充值计费的完整权威对照见 voc-api-catalog 技能的 `references/error-codes.md`。
 
 ## 推荐用户启动话术

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

@@ -16,11 +16,15 @@ live 模式默认保持小规模：
 
 ## 接口优先级
 
-live 采集只走健康的 V2：
+live 采集只走健康的 V2。指定达人、话题或商品等精确任务，先按 voc-api-catalog 的「小红书现用接口」选择链路，不要猜路径：
 
-- 搜索：`app_v2/search_notes`，空结果再降级 `web_v3/fetch_search_notes`
-- 详情：视频笔记用 `app_v2/get_video_note_detail`，图文笔记用 `app_v2/get_image_note_detail`
-- 评论：`app_v2/get_note_comments`
+- 关键词样本：`app_v2/search_notes`，空结果再降级 `web_v3/fetch_search_notes`。这只是搜索结果，不是达人主页全量。
+- 达人主页：只有昵称时先用 `app_v2/search_users` 获取 24 位 hex `userid`，再调用 `app_v2/get_user_posted_notes` 并按 `cursor` 翻页。
+- 详情：`type` 含 `video` 时用 `app_v2/get_video_note_detail`，否则用 `app_v2/get_image_note_detail`。
+- 评论：一级评论用 `app_v2/get_note_comments`；`sub_comment_count > 0` 时，再用该评论的 `id` 调用 `app_v2/get_note_sub_comments`。
+- 话题：从笔记详情的话题字段取得 `page_id` 后，依次调用 `app_v2/get_topic_info` 和 `app_v2/get_topic_feed`。
+
+一条路径 404、500 或空结果，只说明该次请求或旧路径失败。先按 voc-api-catalog 的失败处理表改用同用途的现用 V2 接口、核对参数或原参重试；`app_v2/search_notes` 仍能返回时，不得说小红书能力不可用。只有工具明确返回 `needs_token`、`needs_valid_token` 或 HTTP 402 时，才按对应的凭证或充值流程处理。
 
 ## 媒体持久化