From 52d1ae690026de66d5d9112cb473399637262a95 Mon Sep 17 00:00:00 2001
From: lidf <lidf@brainwork.club>
Date: Tue, 7 Apr 2026 01:27:37 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20VOC=20Skill=20=E5=BC=BA=E5=88=B6?=
 =?UTF-8?q?=E7=94=A8=E6=88=B7=E8=87=AA=E5=B8=A6=20TikHub=20Key?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 采集前必须检查 .env 中的 TIKHUB_API_KEY
- 所有写操作 curl 带 X-TikHub-Key header
- 不带 key 的采集请求被服务器拒绝
---
 agent/skills/voc_research/SKILL.md | 92 ++++++++++++++++++++++--------
 1 file changed, 69 insertions(+), 23 deletions(-)

diff --git a/agent/skills/voc_research/SKILL.md b/agent/skills/voc_research/SKILL.md
index e0b0f19..3091703 100644
--- a/agent/skills/voc_research/SKILL.md
+++ b/agent/skills/voc_research/SKILL.md
@@ -19,12 +19,65 @@ metadata:
 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
@@ -46,8 +99,10 @@ curl -s -X POST https://brand.brainwork.club/voc/api/research \
 **第三步：提交研究卡片（自动触发采集）**
 
 ```bash
-curl -s -X PUT https://brand.brainwork.club/voc/api/research/{id}/card \
+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": "跨境保健品",
@@ -61,7 +116,7 @@ curl -s -X PUT https://brand.brainwork.club/voc/api/research/{id}/card \
   }' | python3 -m json.tool
 ```
 
-> ⚠️ 提交卡片后, 服务器会自动开始采集。采集是异步的，通常 30 秒到 2 分钟完成。
+> ⚠️ 提交卡片后，服务器用你的 TikHub Key 为你采集。采集是异步的，通常 30 秒到 2 分钟完成。
 
 **第四步：检查采集状态**
 
@@ -79,30 +134,31 @@ curl -s "https://brand.brainwork.club/voc/api/research/{id}/voc-list?page=1&page
 
 # 查看聚类分析
 curl -s "https://brand.brainwork.club/voc/api/research/{id}/focus-state?lens=task" | python3 -m json.tool
-
-# 查看帖子分组
-curl -s "https://brand.brainwork.club/voc/api/research/{id}/items-grouped?view=included" | python3 -m json.tool
 ```
 
 ### 场景 2：查看已有研究的数据
 
-用户说"看看 XX 品牌的 VOC 数据"时：
+这些只读操作不需要 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：获取研究报告
+### 场景 3：通过 Chat 发送指令（需要 Key）
 
 ```bash
-curl -s https://brand.brainwork.club/voc/api/research/{id}/report | python3 -m json.tool
+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
 ```
 
 ## 与黑手党提案的整合
@@ -114,19 +170,9 @@ VOC 数据在黑手党提案流程中的作用：
 3. **步骤 2 - 惯例揭示**：VOC 中的"大家都这样""行业惯例"表述 = 待打破的惯例
 4. **步骤 5 - 提案验证**：VOC 数据量和情感分布 = 提案的实证基础
 
-## 关键字段说明
-
-VOC 列表返回的每条记录包含：
-- `text`：评论/笔记原文
-- `platform`：来源平台（douyin/xiaohongshu）
-- `like_count`：点赞数（可作为共鸣度指标）
-- `author_type`：real_user / brand_official / marketing
-- `tag`：LLM 标注的主题标签
-- `dimension`：归属的分析维度
-
 ## 注意事项
 
-- API 无需认证，直接 curl 即可
-- 所有写操作返回 `{received: true}`，实际结果通过 SSE 推送（但 Agent 不需要监听 SSE，等几秒后直接查询即可）
-- 采集需要 TikHub API Key，目前服务器已配置好。未来支持用户自带 Key
-- 全局缓存机制：同一关键词的数据跨研究复用，不会重复调 API
+- 采集/Chat 写操作必须带 `X-TikHub-Key` header，否则服务器拒绝采集
+- 只读操作（list、voc-list、pipeline 等）无需 Key
+- 全局缓存机制：同一关键词的数据跨研究复用，不会重复调 API（节省费用）
+- TikHub Key 仅通过 HTTPS header 传输，不写入任何 DB