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

name, description

name	description
holy-crab	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 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 自动执行：

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 ~/.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 步：查询任务列表

python3 ~/.qclaw/skills/holy-crab/scripts/query_tasks.py
# 输出：任务ID | 名称 | 关键词 | 状态 | 进度 | 创建时间

第 3 步：获取任务详情（含 extracted 数据）

python3 ~/.qclaw/skills/holy-crab/scripts/query_task.py <任务ID>

返回示例（result.extracted 部分）：

{
  "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 步：调用处理函数

# 榜单摘要
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	解析过程中的警告信息

榜单元素

{ "当前排名": 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

# 设置环境变量方式
export HC_SESSION="用户提供的cookie值"

---

错误处理

错误信息	含义	处理方式
请先通过钉钉授权登录	Cookie 无效或过期	提示用户重新登录后端或刷新 Cookie
任务不存在	task_id 有误	检查任务 ID 是否正确
服务器内部错误	后端异常	检查后端服务是否运行
提取警告 数组有内容	数据解析有部分问题	查看 warning 字段了解详情