---
name: voc_research
description: "VOC 研究采集与分析工具。通过调用 VOC 后端 API 完成消费者声音数据的采集、查看和分析。在黑手党提案的准备阶段（UDE 诊断）特别有用。"
metadata:
  copaw:
    emoji: "📊"
    requires: {}
---

# VOC 研究工具

当用户需要**采集消费者声音数据、查看 VOC 分析结果、创建 VOC 研究**时，使用此 Skill。

本工具通过 `execute_shell_command` 调用 VOC 后端 REST API。

## API 基地址

```
https://brand.brainwork.club/voc/api/research
```

## 前置：TikHub API Key 配置

采集数据需要 TikHub API Key（每个用户自行充值）。

### 检查 Key 是否已配置

```bash
grep TIKHUB_API_KEY ~/.copaw/workspaces/mafia-expert/.env 2>/dev/null || echo "未配置"
```

### 首次使用时，引导用户配置 Key

如果未配置，告诉用户：

> 采集 VOC 数据需要 TikHub API Key。请前往 https://tikhub.io 注册并充值后，将 Key 告诉我。
> 单次研究成本约 $1-3（12 个关键词 × 2 平台）。

用户提供 Key 后，保存到 .env：

```bash
echo 'TIKHUB_API_KEY=用户提供的key' >> ~/.copaw/workspaces/mafia-expert/.env
```

### 所有涉及采集的 curl 调用必须带上 Key

```bash
# 1. 先加载 key
source ~/.copaw/workspaces/mafia-expert/.env 2>/dev/null

# 2. 检查 key 是否存在
if [ -z "$TIKHUB_API_KEY" ]; then
  echo "错误：未配置 TIKHUB_API_KEY，请先提供你的 TikHub Key"
  exit 1
fi

# 3. 调用 API 时带上 header
curl -s -X PUT "https://brand.brainwork.club/voc/api/research/{id}/card" \
  -H "Content-Type: application/json" \
  -H "X-TikHub-Key: $TIKHUB_API_KEY" \
  -d '{...}'
```

⚠️ **铁律：不带 X-TikHub-Key 的采集请求会被服务器拒绝。** 只有读取操作（查看数据、列表等）不需要 Key。

## 核心工作流

### 场景 1：为黑手党提案采集 VOC 数据

当用户说"帮我采集 XX 品牌的 VOC 数据"时：

**第零步：确认 TikHub Key 已配置**

```bash
source ~/.copaw/workspaces/mafia-expert/.env 2>/dev/null
[ -z "$TIKHUB_API_KEY" ] && echo "需要配置 TikHub Key" || echo "Key 已就绪: ...${TIKHUB_API_KEY: -6}"
```

如果未配置，先引导用户提供 Key（见上方"首次使用"流程）。

**第一步：检查是否有同品牌的已有研究**

```bash
curl -s https://brand.brainwork.club/voc/api/research/list | python3 -m json.tool
```

如果已有同品牌研究，直接使用其 `id`，跳到第三步。

**第二步：创建新研究（仅当无已有研究时）**

```bash
curl -s -X POST https://brand.brainwork.club/voc/api/research \
  -H "Content-Type: application/json" \
  -d '{"brand_name": "品牌名"}' | python3 -m json.tool
```

返回 `research_id`，记住它。

**第三步：提交研究卡片（自动触发采集）**

```bash
source ~/.copaw/workspaces/mafia-expert/.env
curl -s -X PUT "https://brand.brainwork.club/voc/api/research/{id}/card" \
  -H "Content-Type: application/json" \
  -H "X-TikHub-Key: $TIKHUB_API_KEY" \
  -d '{
    "brand_name": "天维美",
    "category": "跨境保健品",
    "focus_product": "护肝片",
    "competitors": [{"name": "Swisse"}, {"name": "Blackmores"}],
    "keywords": [
      {"keyword": "天维美 护肝片", "category": "brand"},
      {"keyword": "护肝片 推荐", "category": "category"},
      {"keyword": "Swisse 护肝", "category": "compete"}
    ]
  }' | python3 -m json.tool
```

> ⚠️ 提交卡片后，服务器用你的 TikHub Key 为你采集。采集是异步的，通常 30 秒到 2 分钟完成。

**第四步：检查采集状态**

```bash
curl -s https://brand.brainwork.club/voc/api/research/{id}/pipeline | python3 -m json.tool
```

等 `collect` 步骤的 `status` 变为 `done` 后再继续。

**第五步：查看 VOC 数据**

```bash
# 查看 VOC 列表（前 20 条）
curl -s "https://brand.brainwork.club/voc/api/research/{id}/voc-list?page=1&page_size=20" | python3 -m json.tool

# 查看聚类分析
curl -s "https://brand.brainwork.club/voc/api/research/{id}/focus-state?lens=task" | python3 -m json.tool
```

### 场景 2：查看已有研究的数据

这些只读操作不需要 TikHub Key：

```bash
# 列出所有研究
curl -s https://brand.brainwork.club/voc/api/research/list | python3 -m json.tool

# 获取研究详情
curl -s https://brand.brainwork.club/voc/api/research/{id} | python3 -m json.tool

# 获取 VOC 数据
curl -s "https://brand.brainwork.club/voc/api/research/{id}/voc-list?page=1&page_size=20" | python3 -m json.tool
```

### 场景 3：通过 Chat 发送指令（需要 Key）

```bash
source ~/.copaw/workspaces/mafia-expert/.env
curl -s -X POST "https://brand.brainwork.club/voc/api/research/{id}/chat" \
  -H "Content-Type: application/json" \
  -H "X-TikHub-Key: $TIKHUB_API_KEY" \
  -d '{"message": "按关键词采集"}' | python3 -m json.tool
```

## 与黑手党提案的整合

VOC 数据在黑手党提案流程中的作用：

1. **准备阶段 - UDE 诊断**：VOC 数据中的用户抱怨 = 不满意效果（UDE），直接用于诊断
2. **步骤 1 - 冲突图**：VOC 中矛盾性表达（如"想买但太贵"）= 冲突素材
3. **步骤 2 - 惯例揭示**：VOC 中的"大家都这样""行业惯例"表述 = 待打破的惯例
4. **步骤 5 - 提案验证**：VOC 数据量和情感分布 = 提案的实证基础

## 注意事项

- 采集/Chat 写操作必须带 `X-TikHub-Key` header，否则服务器拒绝采集
- 只读操作（list、voc-list、pipeline 等）无需 Key
- 全局缓存机制：同一关键词的数据跨研究复用，不会重复调 API（节省费用）
- TikHub Key 仅通过 HTTPS header 传输，不写入任何 DB