---
name: voc-intelligence
description: 面向经营者的 VOC 用户经营洞察工作台。从社交媒体、电商和海外选品数据中提取用户声音，形成趋势情报、问题池、竞品图谱、单点深挖、7 天内容计划、口播脚本、成本预估和用量账单。用户要看顾客关心什么、先改哪里、下周发什么、查商品价格评论、测算任务成本、查询接口用量或进行样例与真实采集时使用。
---

# VOC 用户经营洞察

这个技能包做两件事：

1. **采数据**。1000+ 个数据接口，覆盖社媒内容、国内电商与创作者、海外选品三条通道，用三个工具按需查和调。
2. **出结论**。把采到的用户声音整理成趋势情报、问题池、竞品图谱、行动计划、内容选题和口播稿。

## 先看这张表：用户要什么，从哪里进

| 用户想做的事 | 用哪个工具 | 细则在哪个技能 |
|---|---|---|
| 一次看完「顾客关心什么、先改哪里、下周发什么」 | `voc_business_workflow_run` | `skills/voc-business-workflow` |
| 小红书 / 抖音趋势情报 | `voc_xiaohongshu_trend_run` / `voc_douyin_trend_run` | `skills/xiaohongshu-trend-intelligence`、`skills/douyin-trend-intelligence` |
| 把评论整理成问题清单并排优先级 | `voc_issue_pool_run` | `skills/voc-issue-pool` |
| 深挖一个具体问题，给老板能执行的动作 | `voc_problem_deep_dive_run` | `skills/voc-problem-deep-dive` |
| 竞品被夸什么、被骂什么 | `voc_competitor_map_run` | `skills/voc-competitor-map` |
| 7 天内容选题 / 口播稿 | `voc_content_plan_run` / `voc_speaking_script_run` | `skills/voc-content-plan`、`skills/voc-speaking-script` |
| 采某个平台的内容、评论、商品、价格、达人数据 | `voc_api_search` → `voc_api_doc` → `voc_api_call` | `skills/voc-api-catalog` |
| 估算任务要花多少钱、查余额 | `voc_cost_estimate`、`voc_billing_query` | `skills/voc-cost-controller` |
| 查已完成任务的调用次数和消耗 | `voc_usage_report` | `skills/voc-cost-controller` |
| 看图、识别截图里的文字 | `fmode_image_analysis` | `skills/fmode-image-analysis` |

## 数据接口怎么找

接口清单不写在本文件里。按下面的顺序找，通常两步就够：

1. `skills/voc-api-catalog/references/platforms.md`：全部平台和各平台最常用的接口 id，一个文件看完。
2. 运行时调 `voc_api_search`：不带参数返回平台总览；带 `platform`（如 `douyin`、`视频号`、`淘宝`）和 `query`（如 `评论`、`商品详情`）返回匹配的接口。
3. `voc_api_doc` 传接口 id 读参数，`voc_api_call` 传 `id` + `params` 调用。

其它参考：

| 文件 | 内容 |
|---|---|
| `skills/voc-api-catalog/SKILL.md` | 三条通道、各平台起步接口、调用与返回、失败处理、凭证 |
| `skills/voc-api-catalog/references/xiaohongshu.md` | 小红书完整链路、字段衔接、翻页 |
| `skills/voc-api-catalog/references/taobao-item-detail-v7.md` | 淘宝/天猫详情各版本怎么选、数据时效 |
| `skills/voc-api-catalog/references/error-codes.md` | 报错对照表 |

三条通道覆盖的平台：

- **社媒内容**：抖音、小红书、微信视频号、TikTok、微博、B站、快手、知乎、YouTube、Instagram、Twitter/X、LinkedIn、Reddit 等 18 个平台。
- **国内电商 + 创作者**：京东、淘宝/天猫、1688、抖音电商、TikTok Shop、闲鱼、得物；抖音星图、小红书蒲公英；公众号、视频号、豆瓣、IMDb 等。
- **海外选品**：亚马逊类目榜单、产品详情与销量、ABA 关键词、评论。

本文件只是摘要。某个平台或某类数据有没有，以 `voc_api_search` 的返回为准，不要凭这份摘要判断「没有这个能力」，也不要直接改用网页搜索。

> 安装位置：插件模式下上面的路径都相对于技能包根目录。workspace 模式下 `skills/<名称>/` 对应 `.claude/skills/<名称>/`，其余文件在 `.claude/plugins/voc-intelligence/`。

## 使用规则

- 用户只需描述行业、品类、平台和目标，不要求用户了解工具参数。
- 用户没有明确要求真实采集时，先用演示样例；用户说「真实采集」或「live」时，再检查凭证和余额。
- 首轮输出用「初步判断、机会假设、待校准」的口径，给出证据和下一步动作，不要写成最终结论。
- 多关键词、多账号或持续翻页的任务，先用 `voc_cost_estimate` 估算，结束后用 `voc_usage_report` 核对，并区分用户扣费与平台成本。
- 采集到的图片和视频会下载到任务目录的 `assets/` 并写入 `media-manifest.json`。报告只引用本地路径，技能包不向线上存储上传。
- 凭证由工具自动读取。token **绝不回显**。

## 调用失败时

1. **一次失败不等于平台不可用。** 瞬时故障（HTML 错误页、5xx、超时）工具会自动重试，返回 `upstream_unstable`。正确动作是用原参数再调 1–2 次，不是断言「某平台采集通道故障」。
2. **先看返回的类型，再决定动作。** 以 `status`、`summary.errorKind`、`summary.reason`、`summary.retryable` 为准：
   - `upstream_unstable` → 原参数重试；
   - `not_supported` + `replacedBy` → 接口已下架，改用返回的替代接口（未计费）；
   - `needs_input` → 用 `voc_api_doc` 核对参数或 HTTP 方法；
   - `needs_token` / `needs_valid_token` → 取 `sk-` token 后重试，这不是余额问题；
   - 只有 **402**（`needs_recharge`）才是余额不足，才给充值入口。

完整对照表见 `skills/voc-api-catalog/references/error-codes.md`。