holy-python/skills/holy-crab/SKILL.md

---
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 字段了解详情 |