@vocmarket/voc-skill 0.3.40 → 0.3.42

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

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

@@ -1,6 +1,6 @@
 {
-  "version": "1.6.0",
-  "updatedAt": "2026-06-28",
+  "version": "1.7.0",
+  "updatedAt": "2026-11-09",
   "gateway": {
     "social": {
       "baseUrl": "https://server.fmode.cn/api/voc-social",
@@ -10215,7 +10215,10 @@
       "requiredParams": [
         "note_id",
         "xsec_token"
-      ]
+      ],
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.app_v2.get_note_comments",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.web_v3.fetch_sub_comments",
@@ -10237,7 +10240,10 @@
         "note_id",
         "root_comment_id",
         "xsec_token"
-      ]
+      ],
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.app_v2.get_note_sub_comments",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.web_v3.fetch_search_notes",
@@ -10257,7 +10263,10 @@
       ],
       "requiredParams": [
         "keyword"
-      ]
+      ],
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.app_v2.search_notes",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.web_v3.fetch_search_users",
@@ -10277,7 +10286,10 @@
       ],
       "requiredParams": [
         "keyword"
-      ]
+      ],
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.app_v2.search_users",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.web_v3.fetch_trending",
@@ -10295,7 +10307,10 @@
         "web",
         "v3"
       ],
-      "requiredParams": []
+      "requiredParams": [],
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.hot_search_v1",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.web_v3.fetch_search_suggest",
@@ -10389,7 +10404,10 @@
       ],
       "requiredParams": [
         "user_id"
-      ]
+      ],
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.app_v2.get_user_posted_notes",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.web_v3.fetch_hot_list",
@@ -10407,7 +10425,10 @@
         "web",
         "v3"
       ],
-      "requiredParams": []
+      "requiredParams": [],
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.hot_search_v1",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.app_v2.get_image_note_detail",
@@ -10827,7 +10848,10 @@
       ],
       "requiredParams": [
         "note_id"
-      ]
+      ],
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.web_v3.fetch_homefeed",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.web_v2.fetch_feed_notes_v2",
@@ -10847,7 +10871,10 @@
       ],
       "requiredParams": [
         "note_id"
-      ]
+      ],
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.web_v3.fetch_homefeed",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.web_v2.fetch_home_notes_app",
@@ -10867,7 +10894,10 @@
       ],
       "requiredParams": [
         "user_id"
-      ]
+      ],
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.web_v3.fetch_homefeed",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.web_v2.fetch_note_comments",
@@ -10887,7 +10917,10 @@
       ],
       "requiredParams": [
         "note_id"
-      ]
+      ],
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.app_v2.get_note_comments",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.web_v2.fetch_sub_comments",
@@ -10908,7 +10941,10 @@
       "requiredParams": [
         "note_id",
         "comment_id"
-      ]
+      ],
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.app_v2.get_note_sub_comments",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.web_v2.fetch_user_info_app",
@@ -10928,7 +10964,10 @@
       ],
       "requiredParams": [
         "user_id"
-      ]
+      ],
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.app_v2.get_user_info",
+      "recommendationPriority": -1000
     },
     {
       "id": "xiaohongshu.web_v2.fetch_hot_list",
@@ -10946,7 +10985,10 @@
         "web",
         "v2"
       ],
-      "requiredParams": []
+      "requiredParams": [],
+      "deprecated": true,
+      "replacedBy": "xiaohongshu.hot_search_v1",
+      "recommendationPriority": -1000
     },
     {
       "id": "lemon8.app.fetch_user_profile",

package/mcp/src/features/voc-cost/workflow-planner.js

@@ -81,9 +81,9 @@ function planSocialTrend(input, mode, platform) {
   const commentPages = positive(input.commentPagesPerKeyword ?? input.maxCommentPages ?? input.commentPagesPerNote, mode === 'complete' ? 1 : 0);
   const commentCount = keywordCount * itemCount * commentPages;
   const isXhs = platform === 'xiaohongshu';
-  const searchPath = isXhs ? 'search_notes' : 'search/fetch_general_search_v2';
-  const itemPath = isXhs ? 'get_note_info' : 'app/v3/fetch_video_comments';
-  const commentPath = isXhs ? 'get_note_comments' : 'app/v3/fetch_video_comments';
+  const searchPath = isXhs ? 'app_v2/search_notes' : 'douyin/search/fetch_general_search_v2';
+  const itemPath = isXhs ? 'app_v2/get_image_note_detail' : 'douyin/app/v3/fetch_one_video';
+  const commentPath = isXhs ? 'app_v2/get_note_comments' : 'douyin/app/v3/fetch_video_comments';
   const operations = [
     operation('voc-social', searchPath, keywordCount, isXhs ? '小红书关键词搜索' : '抖音关键词搜索', { valueScore: 5, required: true }),
     isXhs

package/mcp/src/features/xiaohongshu-trend/live-collector.js

@@ -335,7 +335,9 @@ async function collectLiveDataset({ profile, token, fallbackToken, options = {}
         try {
           const detail = await api.getNoteDetail({
             noteId: rawNote.id,
-            noteType: rawNote.type
+            noteType: rawNote.type,
+            // 搜索结果里带的 xsec_token 是 web_v3 详情回退的必要入参。
+            xsecToken: rawNote.xsec_token || ''
           });
           note = normalizeNote(rawNote, keyword, extractDetailNote(detail.data));
         } catch (error) {

package/mcp/src/providers/ecommerce-gateway.js

@@ -32,7 +32,8 @@ async function callEcommerceGateway({ proxyPath, method = 'GET', query = {}, bod
     method: upper,
     body: upper === 'GET' ? undefined : body,
     retries,
-    headers
+    headers,
+    endpoint: proxyPath
   };
   try {
     const result = await requestJson(url, token, requestOptions);

package/mcp/src/providers/overseas-gateway.js

@@ -36,7 +36,7 @@ async function callOverseasGateway({ proxyPath, method = 'POST', query = {}, bod
     query: query || {},
     body: body || {}
   };
-  const requestOptions = { method: 'POST', body: envelope, retries, headers };
+  const requestOptions = { method: 'POST', body: envelope, retries, headers, endpoint: rawPath };
   try {
     const result = await requestJson(url, token, requestOptions);
     return { ...result, authMode: authModeForToken(token), fallbackUsed: false };

package/mcp/src/providers/voc-gateway.js

@@ -57,11 +57,73 @@ function isSuccessCode(json) {
   return true;
 }
 
-function classifyApiError({ response, json, message }) {
+/**
+ * 网关（voc-social-api）新契约里显式回传的失败原因。
+ * 有了它就不必再靠 HTTP 状态码猜「这是用法错了还是平台抖了」。
+ */
+const TRANSIENT_REASONS = new Set([
+  'upstream_html',
+  'upstream_invalid_body',
+  'upstream_unreachable',
+  'upstream_server_error'
+]);
+
+const USAGE_REASON_KINDS = {
+  method_not_allowed: 'method',
+  not_found: 'not_found',
+  request_invalid: 'request'
+};
+
+/** 上游返回 HTML 错误页 / 空响应 / 无法解析的响应体时，只给结论，绝不透传原文。 */
+function describeUnparsableBody(text, httpStatus) {
+  const status = Number(httpStatus) || 502;
+  if (/^\s*(<!doctype|<html|<head|<pre|<\?xml)/i.test(String(text || ''))) {
+    return `本次请求命中了平台侧的异常节点，返回的是 HTML 错误页而不是数据（HTTP ${status}）。该接口本身可用，属于瞬时故障，已自动重试。`;
+  }
+  if (!String(text || '').trim()) {
+    return `平台侧返回了空响应（HTTP ${status}），属于瞬时故障，已自动重试。`;
+  }
+  return `平台侧返回了无法解析的响应体（HTTP ${status}），属于瞬时故障，已自动重试。`;
+}
+
+/** 用法类错误（方法/路径/入参）的文案，措辞刻意不含「上游」，避免被误判成平台抖动。 */
+function describeUsageError({ reason, endpoint, httpStatus, serverMessage }) {
+  const detail = String(serverMessage || '').trim();
+  const hasCjk = /[一-龥]/.test(detail);
+  if (reason === 'method_not_allowed') {
+    return hasCjk
+      ? `${detail} 请按目录里的 method 字段重发。`
+      : `接口 ${endpoint} 不接受该 HTTP 方法（HTTP 405）。请按目录里的 method 字段重发。`;
+  }
+  if (reason === 'not_found') {
+    return `接口 ${endpoint} 在数据服务中不存在（HTTP 404），该路径可能已下线，请改用同平台的其他在售接口。`;
+  }
+  if (reason === 'request_invalid') {
+    return hasCjk
+      ? `${detail} 请按目录里的 requiredParams 补齐后重发。`
+      : `接口 ${endpoint} 入参校验未通过（HTTP ${httpStatus}）：${detail} 请按目录里的 requiredParams 补齐后重发。`;
+  }
+  return detail;
+}
+
+function classifyApiError({ response, json, message, reason }) {
   const httpStatus = response?.status || 0;
   const businessStatus = pickBusinessStatus(json);
   const status = businessStatus || httpStatus;
   const text = String(message || '');
+  if (reason && USAGE_REASON_KINDS[reason]) {
+    return USAGE_REASON_KINDS[reason];
+  }
+  if (reason === 'upstream_business_error') {
+    if (status === 401) return 'auth';
+    if (status === 402) return 'billing';
+    if (status === 403) return 'permission';
+    if (status === 202) return 'unsupported';
+    return 'upstream';
+  }
+  if (reason && TRANSIENT_REASONS.has(reason)) {
+    return 'upstream';
+  }
   if (/company或用户信息不存在|用户信息不存在|用户不存在|账[号户]信息不存在|未登录|登录失效|请输入.*token|sessiontoken/i.test(text)) {
     return 'auth';
   }
@@ -97,7 +159,20 @@ function authModeForToken(token) {
   return 'unknown';
 }
 
-async function requestJson(url, token, { method = 'GET', body, retries = 3, headers = {} } = {}) {
+function isMarkupText(text) {
+  return /^\s*(<!doctype|<html|<head|<pre|<\?xml)/i.test(String(text || ''));
+}
+
+function endpointFromUrl(url) {
+  try {
+    return new URL(url).pathname.replace(/^\/api\/voc-[a-z-]+\//, '');
+  } catch {
+    return String(url || '');
+  }
+}
+
+async function requestJson(url, token, { method = 'GET', body, retries = 3, headers = {}, endpoint } = {}) {
+  const endpointLabel = endpoint || endpointFromUrl(url);
   let lastError;
   for (let attempt = 0; attempt <= retries; attempt++) {
     let response;
@@ -115,31 +190,85 @@ async function requestJson(url, token, { method = 'GET', body, retries = 3, head
       });
       text = await response.text();
     } catch (networkError) {
-      lastError = networkError;
+      // 网络层失败基本都是瞬时故障：重试耗尽后给结论，不把 undici 的原文当结论抛出去。
       if (attempt < retries) {
         await delay(400 * (attempt + 1));
         continue;
       }
-      const error = new Error(redactSecret(networkError && networkError.message ? networkError.message : 'fetch failed'));
+      const error = new Error(
+        `连接平台数据服务失败（已重试 ${retries} 次）：${redactSecret(networkError && networkError.message ? networkError.message : 'fetch failed')}`
+      );
       error.kind = 'upstream';
+      error.reason = 'upstream_unreachable';
+      error.retryable = true;
       error.httpStatus = 0;
+      error.endpoint = endpointLabel;
+      error.attempts = retries + 1;
       throw error;
     }
+
     let json;
     try {
       json = JSON.parse(text);
     } catch {
       json = undefined;
     }
-    if (!response.ok || (json && !isSuccessCode(json))) {
-      const message = json?.message || json?.msg || json?.data?.msg || json?.data?.message || json?.mess || text || `HTTP ${response.status}`;
+
+    // —— 非 JSON 响应体 ——
+    // 典型场景：网关的上游负载均衡把请求打到了缺路由的节点，返回 HTML 错误页。
+    // 这是**瞬时**故障（同一接口重发即可成功），所以既重试，也绝不把 HTML 原文
+    // 或 `Unexpected token '<'` 这类解析器文本当成失败结论抛给调用方——否则技能
+    // 会把它读成「该平台能力不可用」。
+    if (!json) {
+      const error = new Error(describeUnparsableBody(text, response.status));
+      error.kind = 'upstream';
+      error.reason = isMarkupText(text) ? 'upstream_html' : 'upstream_invalid_body';
+      error.retryable = true;
+      // 非 JSON 响应说明请求根本没到达业务接口（典型是节点缺路由），此时 HTTP 状态
+      // 描述的是故障节点而非资源，统一按 503 归类，避免把「节点异常 404」误读成
+      // 「该路径已下线」。真实响应码保留在 message 里供排查。
+      error.httpStatus = 503;
+      error.endpoint = endpointLabel;
+      error.attempts = attempt + 1;
+      if (attempt < retries) {
+        lastError = error;
+        await delay(400 * (attempt + 1));
+        continue;
+      }
+      throw error;
+    }
+
+    if (!response.ok || !isSuccessCode(json)) {
+      const reason = typeof json.reason === 'string' ? json.reason : '';
+      const businessStatus = pickBusinessStatus(json);
+      const serverMessage = redactSecret(
+        json.message || json.msg || json.data?.msg || json.data?.message || json.mess || `HTTP ${response.status}`
+      );
+      // 网关显式回传 reason 时，HTTP 状态就是真实状态，业务码不再冒充 HTTP 状态；
+      // 没有 reason（老契约）时保持历史语义（业务码优先），避免下游摘要字段漂移。
+      const httpStatus = reason
+        ? Number(response.status) || businessStatus || 500
+        : businessStatus || Number(response.status) || 500;
+      const message = USAGE_REASON_KINDS[reason]
+        ? describeUsageError({ reason, endpoint: endpointLabel, httpStatus, serverMessage })
+        : serverMessage;
       const error = new Error(redactSecret(message));
-      error.httpStatus = pickBusinessStatus(json) || response.status || 500;
-      error.kind = classifyApiError({ response, json, message });
-      error.responseBody = redactSecret(text);
-      const retryableCollectionFailure = error.kind === 'upstream' &&
-        (error.httpStatus === 301 || /collect failed|send request again/i.test(message));
-      if ((error.httpStatus >= 500 || retryableCollectionFailure) && attempt < retries) {
+      error.kind = classifyApiError({ response, json, message, reason });
+      error.httpStatus = httpStatus;
+      if (businessStatus) error.businessCode = businessStatus;
+      if (reason) error.reason = reason;
+      error.endpoint = endpointLabel;
+      error.attempts = attempt + 1;
+      // 诊断信息只留结构化 JSON 片段，HTML 错误页不入库。
+      error.responseBody = isMarkupText(text) ? undefined : redactSecret(String(text || '').slice(0, 2000));
+      error.retryable = error.kind === 'upstream' && (
+        TRANSIENT_REASONS.has(reason) ||
+        json.retryable === true ||
+        Number(response.status) >= 500 ||
+        businessStatus === 301 ||
+        /collect failed|send request again|this operation was aborted|timeout|超时/i.test(serverMessage)
+      );
+      if (error.retryable && attempt < retries) {
         lastError = error;
         await delay(400 * (attempt + 1));
         continue;
@@ -162,7 +291,8 @@ async function callSocialGateway({ proxyPath, method = 'GET', query = {}, body,
     method: upper,
     body: upper === 'GET' ? undefined : body,
     retries,
-    headers
+    headers,
+    endpoint: proxyPath
   };
   try {
     const result = await requestJson(url, token, requestOptions);

package/mcp/src/providers/xiaohongshu-api.js

@@ -2,13 +2,15 @@ const { callSocialGateway } = require('./voc-gateway');
 
 const VOC_SOCIAL_API_ROOT = 'https://server.fmode.cn/api/voc-social';
 const XIAOHONGSHU_API_ROOT = `${VOC_SOCIAL_API_ROOT}/xiaohongshu`;
-const XIAOHONGSHU_APP_BASE_URL = `${XIAOHONGSHU_API_ROOT}/app`;
 
+// 只保留实测可用的路径。历史回退路径 web_v3/fetch_search_notes 与 app/get_note_info
+// 已于数据服务侧下线（实测稳定返回 404 Not Found），继续留着只会把「路径不存在」
+// 伪装成「平台不可用」，故整体移除。
 const SEARCH_APP_V2_PATH = 'app_v2/search_notes';
-const SEARCH_WEB_V3_PATH = 'web_v3/fetch_search_notes';
 const DETAIL_IMAGE_PATH = 'app_v2/get_image_note_detail';
 const DETAIL_VIDEO_PATH = 'app_v2/get_video_note_detail';
-const DETAIL_APP_FALLBACK_PATH = 'app/get_note_info';
+// 详情回退：web_v3/fetch_note_detail 实测可用，但需要 xsec_token（笔记分享链里带）。
+const DETAIL_WEB_V3_PATH = 'web_v3/fetch_note_detail';
 const COMMENTS_PATH = 'app_v2/get_note_comments';
 
 function normalizeXiaohongshuBaseUrl(baseUrl) {
@@ -40,13 +42,6 @@ function mapAppV2NoteType(noteType) {
   return value;
 }
 
-function mapWebV3NoteType(noteType) {
-  const value = String(noteType == null ? '_0' : noteType).trim();
-  if (value === '_1' || value === '1' || value === '视频' || value === '视频笔记' || value === 'video') return 1;
-  if (value === '_2' || value === '2' || value === '图文' || value === '普通笔记' || value === 'normal') return 2;
-  return 0;
-}
-
 function extractSearchItems(data) {
   if (!data || typeof data !== 'object') return [];
   const candidates = [data.items, data.note_list, data.notes, data.data && data.data.items];
@@ -99,52 +94,26 @@ class XiaohongshuApi {
     searchId = '',
     sessionId = ''
   }) {
-    const sortType = mapSortType(sort);
-    let firstError;
-
-    try {
-      const result = await this.request(SEARCH_APP_V2_PATH, {
-        query: {
-          keyword,
-          page,
-          sort_type: sortType,
-          note_type: mapAppV2NoteType(noteType),
-          search_id: searchId,
-          search_session_id: sessionId
-        }
-      });
-      if (extractSearchItems(result.data).length > 0) {
-        return {
-          ...result,
-          endpoint: SEARCH_APP_V2_PATH,
-          fallbackUsedForEndpoint: false
-        };
+    const result = await this.request(SEARCH_APP_V2_PATH, {
+      query: {
+        keyword,
+        page,
+        sort_type: mapSortType(sort),
+        note_type: mapAppV2NoteType(noteType),
+        search_id: searchId,
+        search_session_id: sessionId
       }
-    } catch (error) {
-      if (!isRetryableUpstream(error)) throw error;
-      firstError = error;
-    }
-
-    try {
-      const result = await this.request(SEARCH_WEB_V3_PATH, {
-        query: {
-          keyword,
-          page,
-          sort: sortType,
-          note_type: mapWebV3NoteType(noteType)
-        }
-      });
-      return {
-        ...result,
-        endpoint: SEARCH_WEB_V3_PATH,
-        fallbackUsedForEndpoint: true
-      };
-    } catch (error) {
-      throw firstError || error;
-    }
+    });
+    // 空结果就是空结果：不再降级到已下线的 web_v3 搜索路径，否则一次空结果会
+    // 触发一个必然 404 的请求，把「这个词没笔记」误报成「搜索能力故障」。
+    return {
+      ...result,
+      endpoint: SEARCH_APP_V2_PATH,
+      fallbackUsedForEndpoint: false
+    };
   }
 
-  async getNoteDetail({ noteId, noteType = '', shareText = '' }) {
+  async getNoteDetail({ noteId, noteType = '', shareText = '', xsecToken = '' }) {
     const query = {
       note_id: noteId,
       share_text: shareText
@@ -170,21 +139,24 @@ class XiaohongshuApi {
       }
     }
 
-    try {
-      const result = await this.request(DETAIL_APP_FALLBACK_PATH, {
-        query: {
-          note_id: noteId,
-          share_text: shareText
-        }
-      });
-      return {
-        ...result,
-        endpoint: DETAIL_APP_FALLBACK_PATH,
-        fallbackUsedForEndpoint: true
-      };
-    } catch (error) {
-      throw lastError || error;
+    // 详情回退只在拿到 xsec_token（分享链里带）时才走 web_v3，该接口实测可用；
+    // 没有 token 就如实抛出首个错误，不做注定失败的尝试。
+    if (xsecToken) {
+      try {
+        const result = await this.request(DETAIL_WEB_V3_PATH, {
+          query: { note_id: noteId, xsec_token: xsecToken }
+        });
+        return {
+          ...result,
+          endpoint: DETAIL_WEB_V3_PATH,
+          fallbackUsedForEndpoint: true
+        };
+      } catch (error) {
+        throw lastError || error;
+      }
     }
+
+    throw lastError || new Error(`未能获取笔记 ${noteId} 的详情`);
   }
 
   getNoteComments({ noteId, cursor = '', shareText = '', xsecToken = '' }) {
@@ -202,11 +174,10 @@ class XiaohongshuApi {
 module.exports = {
   VOC_SOCIAL_API_ROOT,
   XIAOHONGSHU_API_ROOT,
-  XIAOHONGSHU_APP_BASE_URL,
   SEARCH_APP_V2_PATH,
-  SEARCH_WEB_V3_PATH,
   DETAIL_IMAGE_PATH,
   DETAIL_VIDEO_PATH,
+  DETAIL_WEB_V3_PATH,
   COMMENTS_PATH,
   normalizeXiaohongshuBaseUrl,
   extractSearchItems,

package/mcp/src/server.js

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

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

@@ -200,6 +200,35 @@ async function callVocApi(input = {}) {
   }
   if (endpoint) endpoint = hydrateEndpoint(endpoint);
 
+  // 已下架接口直接拦在调用前：这些路径在数据服务侧已返回 404，发出去只会得到
+  // 一次必然失败的请求，还会被读成「平台能力不可用」。直接给出替代接口。
+  if (endpoint && endpoint.deprecated) {
+    const replacement = endpoint.replacedBy
+      ? `请改用 ${endpoint.replacedBy}（参数主要用于 keyword/page；可用 voc_api_doc 查看）。`
+      : '请用 voc_api_search 改选现用接口。';
+    return {
+      status: 'not_supported',
+      assistantMessage: [
+        `接口 ${endpoint.id} 已下架，本次未发起调用，也未产生任何费用。`,
+        '',
+        replacement,
+        '这不是余额、token 或关键词问题，也不影响同平台其他接口的可用性。'
+      ].join('\n'),
+      summary: {
+        endpoint: endpoint.id,
+        proxyPath: endpoint.proxyPath,
+        errorKind: 'deprecated_endpoint',
+        replacedBy: endpoint.replacedBy || null,
+        httpStatus: 0
+      },
+      data: { endpoint: summarizeEndpoint(endpoint), replacedBy: endpoint.replacedBy || null },
+      files: [],
+      nextActions: endpoint.replacedBy ? [`改用 ${endpoint.replacedBy} 重试`] : ['用 voc_api_search 改选现用接口'],
+      warnings: [],
+      errors: []
+    };
+  }
+
   // 计费优先走 NewAPI（fmode-api）的 sk- token；该 token 鉴权失败（含「未入仓」类报错）时
   // 自动回退平台 sessionToken 重试。注意：以前因为 sk- 直接请求会命中「入仓」错误，这里曾经
   // 直接拒绝 sk- token；现在改为「优先 sk-、鉴权失败再回退 sessionToken」，并对外只给友好提示。
@@ -421,6 +450,38 @@ async function callVocApi(input = {}) {
         errors: [{ message: safeMessage, kind, httpStatus }]
       };
     }
+    if (kind === 'method') {
+      return {
+        status: 'needs_input',
+        assistantMessage: [
+          `接口 ${proxyPath} 不接受当前的 HTTP 方法（${method}，HTTP 405）。`,
+          '',
+          '这是调用方式问题，不是平台能力问题，也不是余额或 token 问题。请按接口元数据里的 method 字段重发；如果目录里 method 缺失，说明该条元数据尚未补全。'
+        ].join('\n'),
+        summary: { endpoint: endpoint?.id || proxyPath, channel, errorKind: kind, httpStatus },
+        data: { message: safeMessage, method },
+        files: [],
+        nextActions: [`按目录中的 method 字段重新调用（当前用了 ${method}）`],
+        warnings: [],
+        errors: [{ message: safeMessage, kind, httpStatus }]
+      };
+    }
+    if (kind === 'not_found') {
+      return {
+        status: 'not_supported',
+        assistantMessage: [
+          `接口 ${proxyPath} 的路径在数据服务中不存在（HTTP 404），该路径很可能已经下线。`,
+          '',
+          '这是目录元数据过期，不代表该平台没有可用数据。请用 voc_api_search 重新查同平台的在售接口，不要据此判断「采集通道故障」。'
+        ].join('\n'),
+        summary: { endpoint: endpoint?.id || proxyPath, channel, errorKind: kind, httpStatus },
+        data: { message: safeMessage },
+        files: [],
+        nextActions: ['用 voc_api_search 改选同平台在售接口', '确认目录版本是否为最新（voc_api_search 返回的版本号）'],
+        warnings: [],
+        errors: [{ message: safeMessage, kind, httpStatus }]
+      };
+    }
     if (kind === 'unsupported') {
       return {
         status: 'not_supported',
@@ -436,16 +497,18 @@ async function callVocApi(input = {}) {
     return {
       status: 'upstream_unstable',
       assistantMessage: [
-        `接口 ${proxyPath} 这次调用失败，是上游数据接口返回错误或暂时不稳定（如 5xx、连接超时、fetch failed）。`,
+        `接口 ${proxyPath} 本次调用没有成功：${safeMessage}`,
+        '',
+        '这是**平台侧瞬时故障**（例如请求落到了缺少该路由的节点、返回 HTML 错误页，或上游 5xx / 超时），工具已自动重试若干次。它不代表这个接口或这类数据不可用——同一接口重发通常就能成功。',
         '',
-        '这不是关键词问题，也不是类目不支持、也不是余额不足：通常稍后重试即可（本工具已自动重试若干次）。'
+        '因此本轮结论不要写成「某平台采集通道故障」「平台不可用」这类判断。需要交付时，请先重试 1–2 次；仍失败再如实记录为「本次调用失败，能力本身可用」。'
       ].join('\n'),
-      summary: { endpoint: endpoint?.id || proxyPath, errorKind: kind, httpStatus },
-      data: { message: safeMessage },
+      summary: { endpoint: endpoint?.id || proxyPath, errorKind: kind, reason: error?.reason || null, retryable: error?.retryable !== false, httpStatus },
+      data: { message: safeMessage, reason: error?.reason || null },
       files: [],
-      nextActions: ['稍后重试该接口调用'],
+      nextActions: ['稍后重试该接口调用（瞬时故障，重发通常即可成功）', '不要据此判断该平台无数据或能力下线'],
       warnings: [],
-      errors: [{ message: safeMessage, kind, httpStatus }]
+      errors: [{ message: safeMessage, kind, httpStatus, reason: error?.reason || null }]
     };
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vocmarket/voc-skill",
-  "version": "0.3.40",
+  "version": "0.3.42",
   "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.40",
+  "version": "0.3.42",
   "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,6 +84,7 @@ 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` |
@@ -105,7 +133,7 @@ VOC 后端是一个**通用转发网关**（`https://server.fmode.cn/api/voc-soc
 { "id": "xiaohongshu.app_v2.get_user_info", "params": { "user_id": "<24位hex user_id>" } }
 ```
 
-话题笔记先从笔记详情的话题字段拿 `page_id`，再拉话题信息和话题流。`sort` 只用 `trend` 或 `time`。
+话题内容从笔记详情的 `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>" } }
@@ -146,6 +174,31 @@ VOC 后端是一个**通用转发网关**（`https://server.fmode.cn/api/voc-soc
 
 一次只拉一页。批量拉多个达人、多个关键词或持续翻页前，先用 `voc_cost_estimate` 估算次数，跑完用 `voc_usage_report` 核对实际消耗。
 
+### 单次失败时怎么处理
+
+一次 404、500 或空结果，只能说明「这一次请求或这一条路径失败」，不能据此说小红书能力不可用。先用同一凭证调用 `xiaohongshu.app_v2.search_notes` 做一次最小探测；它成功就说明采集通道仍可用，然后按失败类型处理。
+
+工具返回的 `summary.reason` 是网关给出的结构化失败原因，`summary.retryable` 表示是否值得重发——先看这两个字段，再决定怎么做：
+
+| 看到的结果 | 实际含义 | 下一步 |
+|---|---|---|
+| `reason = upstream_html` / `upstream_invalid_body`，文案提到「HTML 错误页」 | 网关把请求打到了缺少该路由的节点，属于**瞬时**故障 | 原参数重发 1–2 次。绝不要写成「某采集通道故障」或「平台不可用」 |
+| `kind = not_found`（404），或工具直接返回 `not_supported` + `replacedBy` | 该路径已下线 / 目录元数据过期 | 按 `replacedBy` 改用现用接口。不要据此说平台没有此能力 |
+| `kind = method`（405） | 该路径不接受当前 HTTP 方法 | 按目录里的 `method` 字段重发，不要换路径碰运气 |
+| 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 账户额度不足 | 转述充值入口。内层业务码或其它账户的额度问题不能混报成用户余额不足 |
+
+已确认下线的旧路径（不要再调用）：`web_v3/fetch_search_notes`、`web_v3/fetch_search_users`、`web_v3/fetch_note_comments`、`web_v3/fetch_sub_comments`、`web_v3/fetch_user_notes`、`web_v3/fetch_trending`、`web_v3/fetch_hot_list`、整个 `web_v2/*` 家族，以及 `app/get_note_info`。它们的现用替代是 `app_v2/*` 与 `web_v3/fetch_homefeed`、`hot_search_v1`；目录里已标记 `deprecated` 并带 `replacedBy`。
+
+探测请求也算一次调用。通道确认可用后，不要重复探测；回到用户原始任务继续。若现用接口和清单里的替代接口都按文档重试后仍失败，才说明是本次采集失败，并保留工具返回的 `status`，不能扩大成「小红书不可用」。
+
 ## 创作者侧情报（channel=ecommerce）
 
 抖音星图 / 小红书蒲公英（PGY）的创作者数据是 VOC 在**创作者生态**维度的情报源——它服务的是 VOC 一贯的「内容战略、竞对理解、受众洞察、选题与脚本」闭环，而**不是**「替用户挑达人投广告」。同一套数据用来回答这些 VOC 问题：
@@ -215,10 +268,10 @@ VOC 后端是一个**通用转发网关**（`https://server.fmode.cn/api/voc-soc
 - `needs_token`：没读到任何 token（**可恢复，不是没钱、不是功能用不了**）——优先去 `~/.claude/settings.json` 取 `env.ANTHROPIC_AUTH_TOKEN`（`sk-`）用 `FMODE_API_KEY=sk-…` 传入重试。`needs_valid_token`：token 缺失/失效/无效（HTTP 401）——**不是没钱**，提示配置有效 `sk-`（或回退 `r:`）token。
 - `needs_recharge`：**仅 HTTP 402（余额不足）**，透传工具生成的 Tokenized Balance 链接或二维码支付结果；Balance 链接格式为 `https://app.fmode.cn/dev/studio/balance/?token=USER_SESSION_TOKEN`。需要直接出二维码时，调用 `voc_billing_query` 时传 `createPaymentQr=true`，由技能包复用现有 `pay_code2` 链路。
 - `needs_permission`：**HTTP 403（账号禁用/无权限）**，**≠ 余额不足**，不引导充值，提示联系服务方确认权限。
-- `needs_input`：必填参数缺失或参数错误（不是类目/余额问题）。
+- `needs_input`：必填参数缺失、参数错误，或 HTTP 405（方法不对，看 `summary.errorKind=method`）——不是类目/余额问题，也不要换路径碰运气。
 - `stale_data`：接口有返回，但 `recordTime` 已超过该接口的时效门槛；只能作为历史参考。
-- `not_supported`：业务码 202，当前商品或数据口径不受该接口支持。
-- `upstream_unstable`：上游接口报错或波动（5xx / fetch failed），稍后重试。
+- `not_supported`：业务码 202（当前商品或数据口径不受支持），或命中了已下架的接口（`summary.errorKind=deprecated_endpoint`，会带 `replacedBy`）——本次**未发起调用、未产生费用**，按 `replacedBy` 改接口即可，不代表平台没有数据。
+- `upstream_unstable`：**平台侧瞬时故障**（5xx / 超时 / `reason=upstream_html` 的 HTML 错误页）。已自动重试，稍后用原参数重发通常即可成功；不要据此断言「该平台采集通道故障」。
 
 > ⚠️ 不要把 **403/401** 一律说成「余额不足」。只有 **402** 才是真的没钱要充值；403 是权限、401 是 token 问题。
 

package/skills/voc-api-catalog/references/error-codes.md

@@ -17,6 +17,9 @@
 | 402 | `余额不足` / `额度不足` | `billing` | `needs_recharge` | 「余额不足，请充值」 | 透传工具生成的 Tokenized Balance 链接或二维码支付结果 |
 | 403 | `用户禁用` / `无权限` / `permission` / `未开通` / `没开通` / `余额` / `额度` / `insufficient` / `balance` | `permission` | `needs_permission` | 「账号被禁用或没有该接口权限，**≠ 余额不足**」 | 联系服务方确认账号状态/接口权限，**不要**引导充值；只有 HTTP 402 才走充值 |
 | 400 / 422 | `参数` / `入参` / `keyword` / `bad request` | `request` | `needs_input` | 「参数有误，**不是没数据/不是类目不支持**」 | 用 `voc_api_doc` 核对参数后重试 |
+| 405 | `不接受 POST 请求` / `Method Not Allowed` | `method` | `needs_input` | 「调用方式不对，**不是平台没有这个能力**」 | 按目录里的 `method` 字段重发，不要换路径碰运气 |
+| 404 | `在上游不存在` / `Not Found` | `not_found` | `not_supported`（带 `replacedBy`） | 「该路径已下线，**不是该平台没有数据**」 | 按 `replacedBy` 改用现用接口；目录里 `deprecated` 的条目不要调用 |
+| 503 / 返回 HTML 错误页 | `返回了 HTML 错误页` / 响应体以 `<!DOCTYPE` 开头 | `upstream`（`reason=upstream_html`） | `upstream_unstable` | 「平台侧瞬时故障，接口本身可用」 | 原参数重发 1–2 次。**禁止**写成「采集通道故障 / 平台不可用」 |
 | 5xx / 连接失败 | `fetch failed` / 超时 / `500` | `upstream` | `upstream_unstable` | 「上游接口波动」 | 稍后重试，不要误报成关键词/余额问题 |
 
 ## 二、真实报文样例（实打抓取）

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,12 +16,15 @@ live 模式默认保持小规模：
 
 ## 接口优先级
 
-live 采集只走健康的 V2：
+live 采集只走健康的 V2。指定达人、话题或商品等精确任务，先按 voc-api-catalog 的「小红书现用接口」选择链路，不要猜路径：
 
-- 搜索：`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`
+- 关键词样本：`app_v2/search_notes`。空结果就是该词没有匹配笔记，如实记录，不要再降级到已下线的 `web_v3/fetch_search_notes`（该路径稳定 404）。这只是搜索结果，不是达人主页全量。
+- 达人主页：只有昵称时先用 `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`；两条都取不到且结果里带 `xsec_token` 时，用 `web_v3/fetch_note_detail` 兜底。已下线的 `app/get_note_info` 不再调用。
+- 评论：一级评论用 `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 时，才按对应的凭证或充值流程处理。
 
 ## 媒体持久化