feat: VOC Skill 强制用户自带 TikHub Key
- 采集前必须检查 .env 中的 TIKHUB_API_KEY - 所有写操作 curl 带 X-TikHub-Key header - 不带 key 的采集请求被服务器拒绝
This commit is contained in:
parent
4157ba6afb
commit
52d1ae6900
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user