243 lines
7.7 KiB
Markdown
243 lines
7.7 KiB
Markdown
---
|
||
name: holy-crab
|
||
description: "Holy蟹搜索监测平台 — 当用户需要查询/分析小红书问一问任务结果、榜单数据、产品详情、评论情感时使用此技能。包含结果查询、榜单摘要、产品分析、情感统计等完整处理流程。"
|
||
---
|
||
|
||
# Holy蟹搜索监测 · AI 数据访问技能
|
||
|
||
## 概述
|
||
|
||
Holy Crab（Holy蟹）是一个基于小红书问一问 API 的搜索监测平台。
|
||
爬虫结果经 `extract_wenyiwen.py` 清洗后，以标准结构化格式存储。
|
||
|
||
**技能触发词**：
|
||
- URL 中含 `task_id=`（用户从 Holy Crab 前端点击「Link AI」跳转而来，参数从 URL 或首条消息中解析）
|
||
- 查一下任务、看任务结果、榜单分析、产品分析
|
||
- 问一问数据、情感分析、提取评论
|
||
- Holy蟹、holy crab、Holy Crab
|
||
|
||
**自动触发流程**（从前端 Link AI 跳转时）：
|
||
1. 从 URL 参数或首条用户消息中提取 `task_id`
|
||
2. 自动调用 `python3 scripts/query_tasks.py <task_id>` 获取任务数据
|
||
3. 若有 `task_name`/`keywords`/`mode` 参数，合并到报告上下文中
|
||
4. 生成完整分析报告
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 第 1 步：获取会话 Cookie（authCode 方式）
|
||
|
||
Holy Crab 后端使用钉钉 OAuth，AI 只需用户的 authCode 就能换出 session token，**全程不需要浏览器 Cookie**。
|
||
|
||
#### 自动流程（推荐）：
|
||
```bash
|
||
bash scripts/get-cookie.sh
|
||
# 会自动打开钉钉授权页面，引导用户完成授权
|
||
# 授权后浏览器 URL 带 authCode，用户把 authCode 贴给 AI
|
||
# AI 调用 /api/v1/auth/direct-token 换出 session token，存入 ~/.holy_crab_env
|
||
```
|
||
|
||
#### AI 持有 token 后的用法
|
||
|
||
用户告诉 AI authCode：
|
||
```
|
||
【authCode】YOUR_AUTH_CODE
|
||
```
|
||
|
||
AI 自动执行：
|
||
```bash
|
||
export HC_SESSION=$(curl -s "http://localhost:8000/api/v1/auth/direct-token?authCode=YOUR_AUTH_CODE" | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['token'])")
|
||
```
|
||
|
||
后续所有请求自动带 Cookie，无需用户再次操作。
|
||
|
||
```bash
|
||
# 先确保后端正在运行，然后执行：
|
||
bash ~/.qclaw/skills/holy-crab/scripts/get-cookie.sh
|
||
# 成功后会输出：✅ Cookie 已写入 ~/.holy_crab_cookie
|
||
```
|
||
|
||
> **如果自动方式失败**（后端未启动或网络不通），改为手动方式：
|
||
> 1. 在浏览器中登录 Holy Crab 前端
|
||
> 2. 打开浏览器 DevTools → Application → Cookies，复制 `hc_session` 的值
|
||
> 3. 写入文件：`echo "你的cookie值" > ~/.holy_crab_cookie`
|
||
|
||
### 第 2 步：查询任务列表
|
||
|
||
```bash
|
||
python3 ~/.qclaw/skills/holy-crab/scripts/query_tasks.py
|
||
# 输出：任务ID | 名称 | 关键词 | 状态 | 进度 | 创建时间
|
||
```
|
||
|
||
### 第 3 步：获取任务详情（含 extracted 数据）
|
||
|
||
```bash
|
||
python3 ~/.qclaw/skills/holy-crab/scripts/query_task.py <任务ID>
|
||
```
|
||
|
||
返回示例（`result.extracted` 部分）：
|
||
```json
|
||
{
|
||
"schema_version": "1.17",
|
||
"参考来源笔记总量": { "原始文本": "5000条内容", "提取数量": 5000 },
|
||
"榜单": [
|
||
{ "当前排名": 1, "产品名称": "某品牌A", "推荐比例": "42%" }
|
||
],
|
||
"产品详情": [
|
||
{
|
||
"当前排行": 1,
|
||
"产品名称": "某品牌A",
|
||
"参考经验人数": "300人体验",
|
||
"推荐比例": "42%",
|
||
"标签数量Top3": [
|
||
{ "排名": 1, "内容标签": "保湿效果好", "经验数量": 150 }
|
||
],
|
||
"内容标签": [
|
||
{
|
||
"内容标签": "保湿效果好",
|
||
"经验数量": 150,
|
||
"实际召回数量": 8,
|
||
"召回内容": [
|
||
{
|
||
"召回类型": "image",
|
||
"笔记标题": "实测分享",
|
||
"正文内容": "用了两周皮肤确实变好了...",
|
||
"字数": 120,
|
||
"点赞数量": 234,
|
||
"收藏数量": 56,
|
||
"笔记链接": "http://xhslink.com/..."
|
||
},
|
||
{
|
||
"召回类型": "comment",
|
||
"评论内容": "真的好用！",
|
||
"所属笔记点赞数量": 234,
|
||
"发布时间": "2026-07-20 14:30:00"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"普通筛选标签": ["成分党", "敏感肌"],
|
||
"提取警告": []
|
||
}
|
||
```
|
||
|
||
### 第 4 步：调用处理函数
|
||
|
||
```bash
|
||
# 榜单摘要
|
||
python3 ~/.qclaw/skills/holy-crab/scripts/process_data.py summarize <任务ID>
|
||
|
||
# 情感统计（从召回内容中提取 comment 类型）
|
||
python3 ~/.qclaw/skills/holy-crab/scripts/process_data.py sentiment <任务ID>
|
||
|
||
# 产品对比
|
||
python3 ~/.qclaw/skills/holy-crab/scripts/process_data.py compare <任务ID>
|
||
```
|
||
|
||
---
|
||
|
||
## API 参考
|
||
|
||
### 基础信息
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| 后端地址 | `http://localhost:8000`（本地）或 `http://<服务器IP>:8000` |
|
||
| API 前缀 | `/api/v1` |
|
||
| 认证方式 | Session Cookie（`hc_session`） |
|
||
|
||
### 核心接口
|
||
|
||
#### GET /api/v1/tasks
|
||
任务列表（支持 `?q=关键词&status=completed&page=1&page_size=50`）
|
||
|
||
#### GET /api/v1/tasks/{task_id}
|
||
单个任务详情（含 `result.extracted`）
|
||
|
||
#### GET /api/v1/tasks/{task_id}/files
|
||
任务文件列表
|
||
|
||
---
|
||
|
||
## result.extracted 数据解读
|
||
|
||
### 顶层字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `schema_version` | string | 数据版本，当前 `1.17` |
|
||
| `参考来源笔记总量` | object | brand_info 中解析的笔记总数 |
|
||
| `榜单` | array | 推荐产品排名列表 |
|
||
| `产品详情` | array | 各产品的详细标签和召回内容 |
|
||
| `普通筛选标签` | array | 普通命中关键词列表 |
|
||
| `提取元数据` | object | 包含 `召回统计` 和 `包含召回明细` |
|
||
| `提取警告` | array | 解析过程中的警告信息 |
|
||
|
||
### 榜单元素
|
||
|
||
```json
|
||
{ "当前排名": 1, "产品名称": "某品牌", "推荐比例": "42%" }
|
||
```
|
||
|
||
### 产品详情元素
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `当前排行` | 在榜单中的排名 |
|
||
| `产品名称` | 产品名称 |
|
||
| `参考经验人数` | 原始文本，如 "300人体验" |
|
||
| `推荐比例` | 在问一问中的推荐占比 |
|
||
| `标签数量Top3` | 按经验数量排序的前3个标签 |
|
||
| `内容标签` | 全部内容标签，含召回内容 |
|
||
|
||
### 召回内容类型
|
||
|
||
| `召回类型` | 含义 | 额外字段 |
|
||
|-----------|------|---------|
|
||
| `image` | 图文笔记 | `笔记标题`、`正文内容`、`字数`、`点赞数量`、`收藏数量`、`评论数量`、`笔记链接` |
|
||
| `video` | 视频笔记 | 同 image + `视频时长` |
|
||
| `comment` | 评论召回 | `评论内容`、`所属笔记点赞数量`、`发布时间` |
|
||
|
||
### 情感统计（需 AI 自行计算）
|
||
|
||
从 `产品详情[].内容标签[].召回内容[]` 中筛选 `召回类型 == "comment"` 的条目，
|
||
统计 `情感分类` 字段（正面/负面/中性）。
|
||
|
||
> **注意**：`情感分类` 字段需要通过 AI 语义分析补充，原始清洗数据中不含此字段。
|
||
> AI 应读取 `评论内容`，判断情感后补充统计。
|
||
|
||
---
|
||
|
||
## 认证机制详解
|
||
|
||
Holy Crab 使用钉钉 OAuth + Cookie 会话：
|
||
|
||
1. 用户访问 `/api/v1/auth/dingtalk/login` → 跳转到钉钉授权
|
||
2. 钉钉回调 `/api/v1/auth/dingtalk/callback` → 设置 `hc_session` Cookie
|
||
3. 后续请求携带该 Cookie 访问所有 `/api/v1/*` 接口
|
||
|
||
**AI 获取 Cookie 的方法**（按优先级）：
|
||
|
||
1. **环境变量**：`HC_SESSION=xxx`（最优先）
|
||
2. **Cookie 文件**：`~/.holy_crab_cookie`
|
||
3. **直接提示用户**提供 Cookie
|
||
|
||
```bash
|
||
# 设置环境变量方式
|
||
export HC_SESSION="用户提供的cookie值"
|
||
```
|
||
|
||
---
|
||
|
||
## 错误处理
|
||
|
||
| 错误信息 | 含义 | 处理方式 |
|
||
|---------|------|---------|
|
||
| `请先通过钉钉授权登录` | Cookie 无效或过期 | 提示用户重新登录后端或刷新 Cookie |
|
||
| `任务不存在` | task_id 有误 | 检查任务 ID 是否正确 |
|
||
| `服务器内部错误` | 后端异常 | 检查后端服务是否运行 |
|
||
| `提取警告` 数组有内容 | 数据解析有部分问题 | 查看 warning 字段了解详情 |
|