@vocmarket/voc-skill 0.3.32 → 0.3.33

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

package/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: voc-intelligence
+description: 面向经营者的 VOC 用户经营洞察工作台。从社交媒体、电商和海外选品数据中提取用户声音，形成趋势情报、问题池、竞品图谱、单点深挖、7 天内容计划和口播脚本。用户要看顾客关心什么、先改哪里、下周发什么、查商品价格评论或进行样例与真实采集时使用。
+---
+
+# VOC 用户经营洞察
+
+这是一个可从自然语言开始的 VOC 经营工作台，包含趋势情报、问题管理、竞品分析、经营动作、内容计划和口播脚本等子技能，并提供统一的 MCP 数据接口清单。
+
+## 使用规则
+
+- 用户只需描述行业、品类、平台和目标，不要求用户了解 MCP 参数。
+- 用户没有明确要求真实采集时，先使用演示样例；用户明确说真实采集或 live 时，再检查凭证和余额。
+- 首轮输出采用“初步判断、机会假设、待校准”口径，并给出证据和下一步动作。
+- 用户要完整经营闭环时，调用 `voc_business_workflow_run`；要单项任务时，调用对应的趋势、问题池、深挖、竞品、内容或脚本工具。
+- 用户要查商品、价格、评论、销量或其他平台接口时，先用 `voc_api_search` 查清单，再用 `voc_api_doc` 读取参数，最后用 `voc_api_call` 调用。
+
+## 主要能力
+
+- 小红书和抖音趋势情报，支持样例与小规模真实采集。
+- VOC 问题池、单点问题深挖、竞品图谱和 7 天内容计划。
+- 基于用户声音的口播脚本共创、修改和定稿。
+- 淘宝/天猫、京东、1688、抖音电商等电商数据，以及亚马逊海外选品数据。
+- 图片、截图、海报、图表和商品图片分析。
+

package/docs/capability-map.md

@@ -145,6 +145,7 @@
 | `docs/claude-code-troubleshooting-playbook.md` | Claude Code 故障定位、误报修复、关键词修复和发散排查 |
 | `docs/payment-package-links.md` | 支付链接和套餐入口说明 |
 | `docs/context-budget-implementation-plan.md` | 上下文省 token 工作流 |
+| `docs/voc-cost-metering-and-balance-implementation-spec.md` | VOC 用量核算、任务成本预估、计费 API 与余额看板实施方案 |
 | `docs/deliverables/trend-insight-report.md` | 行业用户洞察趋势清单模板 |
 | `docs/deliverables/competitor-map-report.md` | 竞品图谱与错位机会报告模板 |
 | `docs/deliverables/voc-issue-pool-report.md` | VOC 问题清单与优先级模板 |

package/docs/taobao-item-detail-v7.md

@@ -0,0 +1,156 @@
+# 淘宝/天猫商品详情 V7 接口使用文档
+
+## 1. 适用范围
+
+V7 用于实时发起淘宝/天猫商品基础详情采集，适合获取较新的标题、基础价格、SKU、库存和店铺信息。
+
+V7 不是商品页全部字段的统一接口。以下信息需要按口径补充其它版本：
+
+- 页面展示的“已售/付款人数”：补充调用 V3，读取 `data.sellCount`。
+- 较完整的商品属性、SKU 标价和促销价：补充调用 V6。
+- 券后价或优惠后价：补充调用 V4。
+- 账号、地区、会员、店铺券和平台补贴共同影响的最终结算价：以实际结算页为准。
+
+## 2. 接口信息
+
+| 项目 | 值 |
+|---|---|
+| 接口 ID | `taobao.get_item_detail_v7` |
+| 请求路径 | `taobao/get-item-detail/v7` |
+| 请求方法 | `GET` |
+| 参数位置 | Query |
+| 通道 | `ecommerce` |
+| 计费 | 1 次接口调用 |
+| 推荐时效门槛 | 48 小时 |
+
+## 3. 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `itemId` | string | 是 | 淘宝或天猫商品 ID。可从商品链接的 `id` 参数中提取。 |
+
+示例商品链接：
+
+```text
+https://detail.tmall.com/item.htm?id=824950233983
+```
+
+对应 `itemId`：
+
+```text
+824950233983
+```
+
+## 4. 使用 `voc_api_call` 调用
+
+推荐使用清单 ID 调用，工具会自动选择 `ecommerce` 通道并应用重试、业务码识别和时效检查：
+
+```json
+{
+  "id": "taobao.get_item_detail_v7",
+  "params": {
+    "itemId": "824950233983"
+  }
+}
+```
+
+也可以先读取接口文档：
+
+```json
+{
+  "id": "taobao.get_item_detail_v7"
+}
+```
+
+不经过清单 ID 时，等价的原始路径调用参数为：
+
+```json
+{
+  "rawPath": "taobao/get-item-detail/v7",
+  "method": "GET",
+  "channel": "ecommerce",
+  "query": {
+    "itemId": "824950233983"
+  }
+}
+```
+
+## 5. 核心返回字段
+
+成功时，`voc_api_call` 返回 `status=ok`，上游结果位于 `data.result`，完整原始响应位于 `data.raw`。V7 重点读取以下字段：
+
+| 字段 | 含义 | 使用规则 |
+|---|---|---|
+| `subject` | 当前采集到的商品标题 | 可作为当前基础标题，但仍需结合 `recordTime` 判断时效。 |
+| `price` | 基础价格 | 标注为 V7 基础价，不表述为任意账号的最终结算价。 |
+| `skuVoList` | SKU 列表 | 可读取规格、SKU 价格和库存；数组长度可作为本次采集到的 SKU 数量。 |
+| `shopName` | 店铺名称 | 用于店铺识别。 |
+| `recordTime` | 上游数据采集时间 | 不是本次 API 请求时间，必须计算滞后时长。 |
+| `monthSold` | 月销相关字段 | 可能为 `null`，不作为稳定的页面销量来源。 |
+| `baseAttrList` | 基础属性列表 | 可能为 `null` 或不完整，关键属性应补充 V6。 |
+
+工具会在 `summary` 中返回时效判断信息：
+
+```json
+{
+  "recordTime": "2026-09-01T16:06:58",
+  "maxAgeHours": 48,
+  "ageHours": 0.5,
+  "stale": false
+}
+```
+
+## 6. 时效规则
+
+1. V7 会在调用时实时发起采集，但“实时发起”不等于每个返回字段都与商品页面同一秒刷新。
+2. `recordTime` 表示上游完成数据采集的时间，不是 VOC API 的请求时间。
+3. 技能包用“当前时间 - `recordTime`”计算 `ageHours`。
+4. `ageHours <= 48` 时，结果可作为当前基础详情使用。
+5. `ageHours > 48` 时，工具返回 `status=stale_data`；数据仍会保留在结果中，但只能作为历史参考。
+6. 上游未承诺固定刷新 SLA，因此结果中应同时注明接口版本、`recordTime` 和价格/销量口径。
+
+## 7. 状态与异常处理
+
+| 状态 | 含义 | 处理方式 |
+|---|---|---|
+| `ok` | V7 成功返回，且未超过 48 小时 | 读取标题、基础价、SKU、库存和店铺信息；按需补 V3/V4/V6。 |
+| `stale_data` | `recordTime` 已超过 48 小时 | 仅作历史参考，稍后重试 V7，不表述为当前页面数据。 |
+| `upstream_unstable` | 上游业务码 `301`、5xx、连接失败或重试后仍未恢复 | 工具默认自动重试；连续失败后稍后再次调用。 |
+| `not_supported` | 上游业务码 `202` | 当前商品或数据口径不受该接口支持，检查商品是否下架，并改用其它可用版本核验。 |
+| `needs_input` | 缺少 `itemId` 或参数格式有误 | 从商品链接提取正确的数字商品 ID 后重试。 |
+| `needs_valid_token` | token 缺失、失效或未被正确读取 | 配置有效的技能包调用凭据后重试。 |
+
+HTTP 200 只代表网关请求成功。响应内嵌的业务码 `301` 或 `202` 不会再被技能包误判为成功商品详情。
+
+## 8. 推荐调用顺序
+
+1. 调用 V7 获取较新的标题、基础价格、SKU、库存、店铺和 `recordTime`。
+2. 检查工具状态以及 `summary.ageHours`，只使用 48 小时内的数据作为当前基础详情。
+3. V7 返回 `301` 时让工具完成自动重试；连续失败后稍后再次调用同一接口。
+4. 需要页面展示销量时调用 V3，并同样检查其 `recordTime` 和 48 小时时效门禁。
+5. 需要完整属性或标价/促销价时调用 V6；需要券后价时调用 V4。
+6. 汇总时分别标注“V7 基础价”“V6 标价/促销价”“V4 优惠后价”“V3 页面销量”，不要合并成一个无口径说明的“真实价格/付款人数”。
+
+## 9. 版本职责对照
+
+| 版本 | 主要用途 | 重点字段/口径 | 注意事项 |
+|---|---|---|---|
+| V7 | 新鲜基础详情，首选 | `subject`、`price`、`skuVoList`、`shopName`、`recordTime` | `monthSold`、`baseAttrList` 可能为空。 |
+| V3 | 页面展示销量 | `data.sellCount` | 不返回价格；超过 48 小时后不能称为当前销量。 |
+| V4 | 优惠后价/券后价 | `DiscountPrice`、SKU 最终价字段 | 仍会受账号、SKU、地区和活动影响。 |
+| V6 | 较完整详情和属性 | 标价、促销价、SKU、属性 | 可能返回历史快照，必须检查 `recordTime`。 |
+| V9 | 兼容旧口径 | `num` 为销售量级信号，`totalCount` 为评价总量 | 两者都不是商品页当前付款人数，属性也可能是旧快照。 |
+
+## 10. 2026-09-01 实测记录
+
+| 商品 ID | V7 结果 | 说明 |
+|---|---|---|
+| `824950233983` | 成功；`recordTime=2026-09-01T16:06:58`；基础价 21.8；7 个 SKU | V7 返回了当天的新鲜基础详情。 |
+| `865522000056` | 成功；基础价 33.8；3 个 SKU | 可用于基础价格和 SKU 核验。 |
+| `872904000992` | 首次 `301`，重试后成功；基础价 32；12 个 SKU | 说明 `301` 应先重试，不能直接作为“无数据”。 |
+| `798980050440` | 多次返回 `301` | 本次采集不稳定，按 `upstream_unstable` 处理。 |
+| `1053323886896` | 返回 `301`，页面商品已不存在 | 商品下架或不存在时，不应继续使用旧版本残留快照作为当前详情。 |
+
+## 11. 结论
+
+需要一个优先返回较新基础详情的接口时，使用 V7。需要完整复刻淘宝/天猫商品页时，仍需按字段口径组合 V7、V3、V4 和 V6；当前不存在一个稳定覆盖页面标题、全部属性、页面销量、所有 SKU 优惠和最终结算价的单一接口。