@vocmarket/voc-skill 0.3.31 → 0.3.32

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 and Douyin 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.31",
+  "version": "0.3.32",
   "author": {
     "name": "nkkj-BrainHack"
   }

package/mcp/catalog/params/taobao.json

@@ -17,6 +17,15 @@
       "desc": "淘宝/天猫上的唯一商品标识符（商品ID）。"
     }
   ],
+  "taobao.get_item_detail_v3": [
+    {
+      "name": "itemId",
+      "in": "query",
+      "type": "string",
+      "required": true,
+      "desc": "淘宝/天猫上的唯一商品标识符（商品ID）。"
+    }
+  ],
   "taobao.get_item_detail_v4": [
     {
       "name": "itemId",
@@ -35,6 +44,15 @@
       "desc": "淘宝/天猫上的唯一商品标识符（商品ID）。"
     }
   ],
+  "taobao.get_item_detail_v6": [
+    {
+      "name": "itemId",
+      "in": "query",
+      "type": "string",
+      "required": true,
+      "desc": "淘宝/天猫上的唯一商品标识符（商品ID）。"
+    }
+  ],
   "taobao.get_item_detail_v9": [
     {
       "name": "itemId",
@@ -167,6 +185,23 @@
       "default": 1
     }
   ],
+  "taobao.get_shop_item_list_v4": [
+    {
+      "name": "sellerId",
+      "in": "query",
+      "type": "string",
+      "required": true,
+      "desc": "用于标识淘宝/天猫店铺的卖家用户ID。"
+    },
+    {
+      "name": "page",
+      "in": "query",
+      "type": "integer",
+      "required": false,
+      "desc": "用于分页的页码。",
+      "default": 1
+    }
+  ],
   "taobao.get_item_sale_v1": [
     {
       "name": "itemId",
@@ -223,4 +258,4 @@
       "default": 1
     }
   ]
-}
+}

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

@@ -22542,7 +22542,11 @@
       "platform": "taobao",
       "channel": "ecommerce",
       "title": "淘宝天猫·商品详情",
-      "summary": "获取淘宝和天猫商品详情数据，包括价格、图片和店铺详情，用于商品研究、目录监控和电商分析。",
+      "summary": "淘宝天猫商品详情兼容版本，可能返回上游快照。查价格与完整详情优先使用 v6，查页面展示销量使用 v3。",
+      "recommendedFor": [
+        "legacy_detail_compatibility"
+      ],
+      "freshness": "recordTime 是上游数据采集时间，不代表本次请求时间；调用方应根据 recordTime 计算滞后时长。",
       "method": "GET",
       "paramsIn": "query",
       "proxyPath": "taobao/get-item-detail/v1",
@@ -22570,7 +22574,8 @@
       "platform": "taobao",
       "channel": "ecommerce",
       "title": "淘宝天猫·商品详情",
-      "summary": "通过任务驱动的v2流程获取淘宝和天猫商品详情数据。如果数据在短暂等待后仍未就绪，响应将返回待处理任务状态。",
+      "summary": "商品详情 V2 任务结果读取接口；直接调用不会发起商品数据采集。普通详情查询优先使用 v6。",
+      "recommendationPriority": -100,
       "method": "GET",
       "paramsIn": "query",
       "proxyPath": "taobao/get-item-detail/v2",
@@ -22593,12 +22598,52 @@
       ],
       "billing": 1
     },
+    {
+      "id": "taobao.get_item_detail_v3",
+      "platform": "taobao",
+      "channel": "ecommerce",
+      "title": "淘宝天猫·页面展示销量（V3）",
+      "summary": "通过商品 ID 获取淘宝或天猫商品页当前展示的销量，适合核对“已售/付款人数”；金额与 SKU 明细请使用 v6。",
+      "method": "GET",
+      "paramsIn": "query",
+      "proxyPath": "taobao/get-item-detail/v3",
+      "params": [],
+      "requiredParams": [
+        "itemId"
+      ],
+      "recommendationPriority": 90,
+      "recommendedFor": [
+        "page_sales",
+        "displayed_sales",
+        "buyer_count"
+      ],
+      "freshness": "recordTime 是上游数据采集时间；返回前必须与当前时间比较，不把请求时间当作采集时间。",
+      "responseHint": "页面销量读取 data.sellCount；该版本不返回商品价格。",
+      "tags": [
+        "taobao",
+        "淘宝天猫",
+        "淘宝",
+        "天猫",
+        "tmall",
+        "Taobao and Tmall",
+        "ecommerce",
+        "电商",
+        "商品",
+        "product",
+        "页面销量",
+        "已售",
+        "付款人数",
+        "sellCount",
+        "page sales"
+      ],
+      "billing": 1
+    },
     {
       "id": "taobao.get_item_detail_v4",
       "platform": "taobao",
       "channel": "ecommerce",
-      "title": "淘宝天猫·商品详情",
-      "summary": "获取淘宝和天猫商品详情数据，包括价格、图片和店铺详情，用于商品研究、目录监控和电商分析。",
+      "title": "淘宝天猫·券后价与商品详情（V4）",
+      "summary": "获取淘宝或天猫商品的标价、SKU 优惠后价格与商品详情；需要券后价/优惠后价口径时优先使用。",
       "method": "GET",
       "paramsIn": "query",
       "proxyPath": "taobao/get-item-detail/v4",
@@ -22606,6 +22651,13 @@
       "requiredParams": [
         "itemId"
       ],
+      "recommendationPriority": 95,
+      "recommendedFor": [
+        "coupon_price",
+        "discount_price"
+      ],
+      "freshness": "recordTime 是上游数据采集时间；优惠后价仍可因账号、SKU、地区、优惠券和活动时间与结算页不同。",
+      "responseHint": "价格单位通常为分：itemPrice 是标价，DiscountPrice 是优惠后价，SKU 读取 sku2info.finalPrice/finalSkuPrice。",
       "tags": [
         "taobao",
         "淘宝天猫",
@@ -22617,7 +22669,13 @@
         "ecommerce",
         "电商",
         "商品",
-        "product"
+        "product",
+        "商品详情",
+        "券后价",
+        "优惠后价",
+        "DiscountPrice",
+        "coupon price",
+        "discount price"
       ],
       "billing": 1
     },
@@ -22649,12 +22707,54 @@
       ],
       "billing": 1
     },
+    {
+      "id": "taobao.get_item_detail_v6",
+      "platform": "taobao",
+      "channel": "ecommerce",
+      "title": "淘宝天猫·商品详情与价格（V6）",
+      "summary": "通过商品 ID 获取淘宝或天猫商品详情、SKU 价格、促销价、图片和店铺信息；查价格与完整详情时优先使用。页面展示销量请另用 v3 核对。",
+      "method": "GET",
+      "paramsIn": "query",
+      "proxyPath": "taobao/get-item-detail/v6",
+      "params": [],
+      "requiredParams": [
+        "itemId"
+      ],
+      "recommendationPriority": 100,
+      "recommendedFor": [
+        "product_detail",
+        "price",
+        "sku_price",
+        "promotion_price"
+      ],
+      "freshness": "recordTime 是上游数据采集时间；返回前必须与当前时间比较，不把请求时间当作采集时间。",
+      "responseHint": "价格优先读取 itemPrice.price / promotionPrice 及 SKU 价格；页面展示销量以 v3 的 sellCount 为准。",
+      "tags": [
+        "taobao",
+        "淘宝天猫",
+        "淘宝",
+        "天猫",
+        "tmall",
+        "Taobao and Tmall",
+        "ecommerce",
+        "电商",
+        "商品",
+        "product",
+        "商品详情",
+        "价格",
+        "促销价",
+        "SKU",
+        "product detail",
+        "price"
+      ],
+      "billing": 1
+    },
     {
       "id": "taobao.get_item_detail_v9",
       "platform": "taobao",
       "channel": "ecommerce",
-      "title": "淘宝天猫·商品详情",
-      "summary": "获取淘宝和天猫商品详情数据，包括价格、图片和店铺详情，用于商品研究、目录监控和电商分析。",
+      "title": "淘宝天猫·商品详情兼容版（V9）",
+      "summary": "淘宝天猫商品详情 V9 兼容数据源。num 是该版本的销售量级信号，totalCount 是评价总量，两者均不等于商品页当前展示付款人数。价格/关键属性优先 v6，页面销量优先 v3。",
       "method": "GET",
       "paramsIn": "query",
       "proxyPath": "taobao/get-item-detail/v9",
@@ -22662,6 +22762,12 @@
       "requiredParams": [
         "itemId"
       ],
+      "recommendationPriority": -50,
+      "recommendedFor": [
+        "legacy_v9_compatibility"
+      ],
+      "freshness": "recordTime 只表示 V9 响应快照的采集时间；嵌套 attribute 可能来自更旧的属性源，不能仅根据 recordTime 判定每个属性都已刷新。",
+      "responseHint": "num=V9 销售量级信号；totalCount=评价总量；attribute=V9 属性快照。不要把 num/totalCount 当作当前页面付款人数，也不要用 V9 attribute 覆盖 V6 的更新关键属性。",
       "tags": [
         "taobao",
         "淘宝天猫",
@@ -22795,7 +22901,8 @@
       "platform": "taobao",
       "channel": "ecommerce",
       "title": "淘宝天猫·店铺商品列表",
-      "summary": "获取淘宝和天猫店铺商品列表数据，包括商品标题、价格和图片，用于卖家研究和目录跟踪。",
+      "summary": "已弃用的淘宝天猫店铺商品列表 V3；新调用使用 v4，只需 sellerId 并支持分页。",
+      "deprecated": true,
       "method": "GET",
       "paramsIn": "query",
       "proxyPath": "taobao/get-shop-item-list/v3",
@@ -22819,12 +22926,47 @@
       ],
       "billing": 1
     },
+    {
+      "id": "taobao.get_shop_item_list_v4",
+      "platform": "taobao",
+      "channel": "ecommerce",
+      "title": "淘宝天猫·店铺商品列表（V4）",
+      "summary": "通过 sellerId 分页获取淘宝或天猫店铺商品列表，支持全部淘宝和天猫店铺；新调用优先使用。",
+      "method": "GET",
+      "paramsIn": "query",
+      "proxyPath": "taobao/get-shop-item-list/v4",
+      "params": [],
+      "requiredParams": [
+        "sellerId"
+      ],
+      "recommendationPriority": 100,
+      "recommendedFor": [
+        "shop_product_list",
+        "seller_catalog"
+      ],
+      "tags": [
+        "taobao",
+        "淘宝天猫",
+        "淘宝",
+        "天猫",
+        "tmall",
+        "Taobao and Tmall",
+        "ecommerce",
+        "电商",
+        "店铺商品",
+        "店铺商品列表",
+        "sellerId",
+        "shop product list"
+      ],
+      "billing": 1
+    },
     {
       "id": "taobao.get_item_sale_v1",
       "platform": "taobao",
       "channel": "ecommerce",
       "title": "淘宝天猫·商品销量",
-      "summary": "获取淘宝和天猫商品销量数据，用于销售追踪、商品研究和电商监控。",
+      "summary": "已弃用的 30 天商品销量接口，上游可能返回空数据。核对商品页“已售/付款人数”使用 get_item_detail_v3。",
+      "deprecated": true,
       "method": "GET",
       "paramsIn": "query",
       "proxyPath": "taobao/get-item-sale/v1",
@@ -28379,4 +28521,4 @@
       "billing": 1
     }
   ]
-}
+}

package/mcp/src/core/api-catalog.js

@@ -78,7 +78,8 @@ function searchEndpoints({ query, platform, tag, limit = 20 } = {}) {
   const tagKey = normalize(tag);
   let results = listEndpoints().map(endpoint => ({
     endpoint,
-    score: scoreEndpoint(endpoint, terms)
+    score: scoreEndpoint(endpoint, terms),
+    preference: endpoint.deprecated ? -1000 : Number(endpoint.recommendationPriority || 0)
   }));
   if (platformKey) {
     results = results.filter(item => normalize(item.endpoint.platform) === platformKey);
@@ -87,7 +88,7 @@ function searchEndpoints({ query, platform, tag, limit = 20 } = {}) {
     results = results.filter(item => (item.endpoint.tags || []).some(t => normalize(t) === tagKey));
   }
   results = results.filter(item => item.score > 0);
-  results.sort((a, b) => b.score - a.score);
+  results.sort((a, b) => (b.score - a.score) || (b.preference - a.preference));
   return results.slice(0, Math.max(1, limit)).map(item => item.endpoint);
 }
 
@@ -99,6 +100,9 @@ function summarizeEndpoint(endpoint) {
     summary: endpoint.summary,
     method: endpoint.method,
     proxyPath: endpoint.proxyPath,
+    deprecated: Boolean(endpoint.deprecated),
+    recommendedFor: endpoint.recommendedFor || [],
+    freshness: endpoint.freshness || null,
     requiredParams: (endpoint.params && endpoint.params.length)
       ? endpoint.params.filter(p => p.required).map(p => p.name)
       : (endpoint.requiredParams || []),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vocmarket/voc-skill",
-  "version": "0.3.31",
+  "version": "0.3.32",
   "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": {

package/scripts/smoke-mcp.js

@@ -291,6 +291,55 @@ async function main() {
       throw new Error(`Expected voc_api_search to list douyin endpoints, got: ${JSON.stringify(apiSearchStructured)}`);
     }
 
+    const taobaoDetailSearchResult = await client.callTool({
+      name: 'voc_api_search',
+      arguments: { platform: 'taobao', query: '淘宝 商品详情' }
+    });
+    const taobaoDetailEndpoints = taobaoDetailSearchResult.structuredContent?.data?.endpoints || [];
+    const taobaoDetailIds = taobaoDetailEndpoints.map(endpoint => endpoint.id);
+    if (taobaoDetailIds[0] !== 'taobao.get_item_detail_v6') {
+      throw new Error(`Expected current Taobao endpoints with v6 preferred for product details, got: ${taobaoDetailIds.join(', ')}`);
+    }
+
+    const taobaoCatalogResult = await client.callTool({
+      name: 'voc_api_search',
+      arguments: { platform: 'taobao' }
+    });
+    const taobaoCatalogIds = (taobaoCatalogResult.structuredContent?.data?.endpoints || []).map(endpoint => endpoint.id);
+    for (const id of ['taobao.get_item_detail_v3', 'taobao.get_item_detail_v6', 'taobao.get_shop_item_list_v4']) {
+      if (!taobaoCatalogIds.includes(id)) {
+        throw new Error(`Expected current Taobao catalog to include ${id}, got: ${taobaoCatalogIds.join(', ')}`);
+      }
+    }
+
+    const taobaoSalesSearchResult = await client.callTool({
+      name: 'voc_api_search',
+      arguments: { platform: 'taobao', query: '淘宝 页面销量' }
+    });
+    const taobaoSalesEndpoints = taobaoSalesSearchResult.structuredContent?.data?.endpoints || [];
+    if (taobaoSalesEndpoints[0]?.id !== 'taobao.get_item_detail_v3' || taobaoSalesEndpoints[0]?.deprecated) {
+      throw new Error(`Expected Taobao v3 to be preferred for page sales, got: ${JSON.stringify(taobaoSalesEndpoints)}`);
+    }
+
+    const taobaoCouponPriceSearchResult = await client.callTool({
+      name: 'voc_api_search',
+      arguments: { platform: 'taobao', query: '淘宝 券后价' }
+    });
+    const taobaoCouponPriceEndpoints = taobaoCouponPriceSearchResult.structuredContent?.data?.endpoints || [];
+    if (taobaoCouponPriceEndpoints[0]?.id !== 'taobao.get_item_detail_v4') {
+      throw new Error(`Expected Taobao v4 to be preferred for coupon prices, got: ${JSON.stringify(taobaoCouponPriceEndpoints)}`);
+    }
+
+    const taobaoV9DocResult = await client.callTool({
+      name: 'voc_api_doc',
+      arguments: { id: 'taobao.get_item_detail_v9' }
+    });
+    const taobaoV9Endpoint = taobaoV9DocResult.structuredContent?.data?.endpoint || {};
+    if (!String(taobaoV9Endpoint.responseHint || '').includes('totalCount=') ||
+      Number(taobaoV9Endpoint.recommendationPriority) >= 0) {
+      throw new Error(`Expected Taobao v9 field semantics and compatibility priority, got: ${JSON.stringify(taobaoV9Endpoint)}`);
+    }
+
     const apiDocResult = await client.callTool({
       name: 'voc_api_doc',
       arguments: { id: 'douyin.search_general' }

package/skill-package-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-voc-intelligence",
-  "version": "0.3.31",
+  "version": "0.3.32",
   "capabilities": {
     "summary": "三类情报源同源接入：①社媒内容 ②国内电商+创作者情报 ③海外选品。统一 search→doc→call、鉴权计费一致。",
     "channels": [
@@ -28,7 +28,7 @@
         "key": "ecommerce",
         "label": "国内电商 + 创作者情报",
         "platforms": 32,
-        "apis": 285,
+        "apis": 288,
         "examples": [
           "京东",
           "淘宝天猫",
@@ -53,7 +53,7 @@
     ],
     "totals": {
       "platforms": 51,
-      "apis": 1340
+      "apis": 1343
     }
   },
   "description": "Claude Code native VOC intelligence package for cross-industry social VOC workflows. Includes Xiaohongshu and Douyin trend intelligence, live token checks, evidence-card reports, single-issue VOC deep dives, boss/operator action plans, and scoped multi-turn memory.",

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

@@ -66,7 +66,18 @@ VOC 后端是一个**通用转发网关**（`https://server.fmode.cn/api/voc-soc
    - 能力与性价比的客观评估：抖音 `douyin.xingtu.cost_performance_analysis` / `conversion_analysis`；小红书 `xiaohongshu.pgy.cost_effectiveness_analysis`。
 3. 把这些创作者侧事实**喂给下游 VOC 技能**（voc-competitor-map 做竞对达人布局、voc-content-plan / voc-speaking-script 做选题与脚本、voc-issue-pool 补充创作者 / 受众视角），形成洞察结论，而非「该投谁」的采买清单。
 
-> 提示：`voc_api_search` 用「星图 创作者」「蒲公英 画像」「受众分布」「性价比」等词即可定位创作者接口，用「京东 商品」「淘宝 评论」「1688 搜索」「亚马逊 选品」「ABA 关键词」等词定位电商/选品接口；`voc_api_doc` 会在请求行标注通道（ecommerce / overseas）并列出参数。当前清单 ecommerce 通道已登记约 285 个接口（电商商品 + 创作者 + 内容平台）、overseas 通道 37 个（亚马逊选品），未登记的可直接用 `voc_api_call` 传 `rawPath` + 对应 `channel` 调用。
+> 提示：`voc_api_search` 用「星图 创作者」「蒲公英 画像」「受众分布」「性价比」等词即可定位创作者接口，用「京东 商品」「淘宝 评论」「1688 搜索」「亚马逊 选品」「ABA 关键词」等词定位电商/选品接口；`voc_api_doc` 会在请求行标注通道（ecommerce / overseas）并列出参数。当前清单 ecommerce 通道已登记约 288 个接口（电商商品 + 创作者 + 内容平台）、overseas 通道 37 个（亚马逊选品），未登记的可直接用 `voc_api_call` 传 `rawPath` + 对应 `channel` 调用。
+
+## 淘宝/天猫版本选择与时效
+
+- 查商品详情、SKU 标价与促销价：优先 `taobao.get_item_detail_v6`；查券后价/优惠后价使用 `taobao.get_item_detail_v4`。价格必须标注是标价、促销价、活动价还是券后价，不要压成单一「真实价格」。
+- 查商品页当前展示的「已售/付款人数」：使用 `taobao.get_item_detail_v3` 的 `data.sellCount`。V3 不返回价格，价格与页面销量需分别调用 V6/V3。
+- `taobao.get_item_detail_v1` 仅用于兼容旧流程；`v2` 直接调用不会发起商品采集。`taobao.get_item_sale_v1` 和 `taobao.get_shop_item_list_v3` 已被上游标记弃用。
+- V9 的 `num` 是该版本销售量级信号，`totalCount` 是评价总量，两者都不是商品页当前展示付款人数。V9 `attribute` 可能是独立旧属性快照；价格和“上市时间”等关键属性优先 V6，页面销量优先 V3。
+- 返回里的 `recordTime` 是上游数据采集时间，不是本次 API 请求时间。每个版本有独立数据源/快照，必须用「当前时间 - recordTime」计算滞后并在结果中明示。
+- 上游文档未给出固定刷新 SLA，不要将返回值表述为「请求时实时数据」，也不要将旧版 `orderPayUV` 与商品页当前展示口径直接等同。需要页面口径时以 V3 `sellCount` 为准。
+- 实际结算价还会受 SKU、账号会员价、地区、店铺券、平台补贴和活动时间影响。API 返回的是对应口径快照，不等于任意账号在结算页的最终应付价。
+- 店铺商品列表的新调用优先 `taobao.get_shop_item_list_v4`，入参为 `sellerId` + 可选 `page`。
 
 ## Token（计费已迁移 NewAPI）