【宝哥】小红书选题关键词搜索 top20

> 作者：宝哥聊AI

功能概述

给定一个关键词，调用红狐(RedFox)小红书 searchArticle 接口（文档 384C6W6B，红狐称「优质库」），按互动数（最热）排序返回该关键词下最热的 20 条笔记，导出成：

• Excel（.xlsx）：排名/标题/博主/发布时间/点赞·收藏·评论·分享·互动总数/笔记链接，冻结首行 + 自动筛选，互动总数 ≥10000 标红，链接可点击。
• HTML（表格视图）：同数据的可筛选网页（带搜索框），方便预览与分享。

适用场景：宝哥做内容选题情报，想快速看「某个关键词下，小红书上互动最高的 20 条笔记长什么样」，从中挑可二创选题；或批量产出最热选题表格。

与「爆款 1000+」版（baoge-xhs-keyword-search-hit）的区别

一句话：要不限门槛、直接看最热 N 条 → 用本 skill；要只挑 1000+ 真爆款 → 用 hit 版。

前置依赖

1. REDFOX_API_KEY（红狐接口密钥）：必填。两种配置方式二选一，详见下方「配置 API Key」一节。
2. openpyxl：仅导出 Excel 时需要。已装在受管虚拟环境：
   C:/Users/Administrator/.workbuddy/binaries/python/envs/default/Scripts/python.exe
   该环境未装时，HTML 导出仍可用（纯标准库）。

配置 API Key（二选一）

脚本运行必须拿到 REDFOX_API_KEY（红狐接口密钥）。两种方式任选其一：

方式 A：配置文件（推荐新手 / 不想改系统环境变量）

技能目录已附带 config.example.env 模板：

# 1. 复制模板并重命名
cp "C:/Users/Administrator/.workbuddy/skills/baoge-xhs-keyword-search-top20/config.example.env" \
   "C:/Users/Administrator/.workbuddy/skills/baoge-xhs-keyword-search-top20/config.env"

# 2. 用编辑器打开 config.env，把 your_redfox_api_key_here 换成真实 Key，保存
# 3. 运行脚本时自动读取该文件，无需另设环境变量

> 安全：含真实 Key 的 config.env 不要提交到公开仓库或分享；config.example.env 只是模板，不含密钥，可安全提交与分发。打包/分发本 skill 前务必删除 config.env。

方式 B：系统 / 用户环境变量

• Windows 用户级：新建 REDFOX_API_KEY=<你的key>，设好后重启 WorkBuddy 生效。
• Bash 临时：export REDFOX_API_KEY=<你的key>（Bash 工具因源生 .bashrc 当下即可用）。

两种方式同时存在时，config.env 配置文件优先于环境变量。此外还可用命令行 --api-key <key> 显式传入，其优先级最高。完整优先级：

--api-key 命令行参数 > config.env / .env 文件 > 环境变量 REDFOX_API_KEY

> 典型坑：改完 Windows 用户级 REDFOX_API_KEY 后若没重启 WorkBuddy，运行中的进程仍持有旧值。此时把新 Key 写进 config.env 即可立即生效，无需重启。

还没有红狐 Key？前往 https://redfox.hk/dashboard/keys 注册并获取 API Key。

运行方式

脚本：scripts/fetch_and_export.py

# 用受管 venv 的 python（已含 openpyxl，可同时出 Excel + HTML）
VENV="C:/Users/Administrator/.workbuddy/binaries/python/envs/default/Scripts/python.exe"

# 默认：搜关键词、按最热(互动数)返回 20 条，同时导出 Excel + HTML
"$VENV" "$HOME/.workbuddy/skills/baoge-xhs-keyword-search-top20/scripts/fetch_and_export.py" \
  --keyword "企业AI" --output both --outdir "F:/zimeiti"

# 只出 Excel
"$VENV" ".../fetch_and_export.py" --keyword "制造业降本" --output excel

# 想看最热 50 条（自动翻页 3 次）
"$VENV" ".../fetch_and_export.py" --keyword "AI培训" --max-items 50

# 改用「最新发布」排序（而非最热）
"$VENV" ".../fetch_and_export.py" --keyword "老板获客" --sort-type _2

> ⚠️ 单关键词接口：searchArticle 是单关键词匹配接口，不支持多关键词/无关键词模式。用户给多个词时，请分别调用（或引导用 hit 版的多关键词能力）；脚本也会把空格分隔提示为整串查询，不会静默拆错。

参数说明：

> 🕐 按时间窗 + 指定排名维度（用户常问）：--days N 控制「最近 N 天」，配合 --sort-by 控制「按什么排」。
> 例如"最近 7 天评论最多的 20 条"：--days 7 --sort-by comments --max-items 20。
> 脚本先 sortType=_2 拉全窗口笔记 → 客户端按 workPublishTime 过滤 → 再按指定字段降序取前 N 条。
>
> bash > # 最近 7 天发布 · 评论最多 20 条 > "$VENV" ".../fetch_and_export.py" --keyword "workbuddy" --days 7 --sort-by comments --max-items 20 >

⚠️ 本机必坑点：Windows 路径翻译

本机是 Git Bash + 原生 Windows Python，原生 Python 会把 /c/Users/... 这种 POSIX 路径误当成相对当前盘符、拼成 C:\c\Users\... 报错 "No such file"。

规则：凡是把脚本路径传给 python.exe，必须先用 cygpath -w 转成 Windows 原生路径：

SCRIPT_WIN="$(cygpath -w "$HOME/.workbuddy/skills/baoge-xhs-keyword-search-top20/scripts/fetch_and_export.py")"
"$VENV" "$SCRIPT_WIN" --keyword "企业AI" --output both --outdir "F:/zimeiti"

（脚本内部读写 --outdir 用普通路径即可，只有「脚本自身路径」需要转 Windows 原生。）

执行流程（照做，缺一不可）

每次跑完必须走到第 ④ 步，否则用户看不到文件（已踩过坑：只生成不交付）。

1. 检查配置：确认 config.env 已含 REDFOX_API_KEY；确认用受管 venv 的 python（已含 openpyxl）。
2. 拼路径 + 运行：用 cygpath -w 转脚本路径，按需求组装 --keyword / --sort-type _4 / --max-items 20 / --output both --outdir F:/zimeiti 运行脚本。
3. 核对返回：看脚本 stdout —— 是否成功获取到条数；若 0 条（词太冷门）先判断要不要换词，再决定是否交付。
4. ⚠️ 交付展示（必须）：运行成功后，立即调用 present_files 把生成的 *.xlsx 与 *.html 一并交付（Excel + HTML 两个文件路径都传）。这一步不可替代——脚本只把文件写到磁盘，不会自动推给用户。绝不允许「生成完只回一句文字、不调用 present_files」或「验证完把临时产物删了就结束」。
5. （可选）归档：若本次结果要留作选题库，把绝对路径在回复里明确给出；若只是临时验证，再清理临时目录。

> 一句话口诀：跑完 → 看结果 → present_files 交付 → 才结束。

输出文件命名

文件名统一带 小红书_ 前缀，并追加 最热TOP20 标识（与 hit 版的 爆款笔记数据 区分），再追加生成时间戳 月日_时分：

• F:/zimeiti/小红书_企业AI_最热TOP20_0824_2130.xlsx
• F:/zimeiti/小红书_企业AI_最热TOP20_0824_2130.html

时间戳格式为 MMDD_HHMM（24 小时制），由脚本在运行时生成，Excel 与 HTML 共用同一戳，便于成对区分不同批次。

> ⚠️ 交付是硬性一步（详见上方「执行流程」第 ④ 步）：脚本只是把文件写到 --outdir，不会自动把文件交给用户。
> 跑完生成后，必须调用 present_files 把成品（xlsx / html 都传）交付，绝不可只回文字不交付、或验证完删临时产物就结束——用户要看到的是真实输出文件。

数据说明（依据文档 384C6W6B 实测核对）

• 接口：POST https://redfox.hk/story/api/xhsUser/searchArticle，请求头 Content-Type: application/json + X-API-KEY: <key>，请求体 {"keyword":"企业AI","offset":0,"sortType":"_4"}。
• sortType：_0 默认(相关性) / _2 最新(发布时间) / _4 最热(互动数)。本 skill 默认 _4。
• 不限 1000+ 门槛：这是「优质库」全量关键词匹配接口，任何互动量的笔记都可能返回，与 hit 版（仅 1000+ 爆款库）相反。因此结果里可能出现低互动笔记，这是预期行为，不是 Bug。
• 分页语义：服务端固定每页 20 条，pageSize/limit/count/size 等参数均被忽略，只能用 offset 游标逐页 +20。--max-items 超过 20 时脚本自动翻页（offset=0,20,40…），某页返回不足 20 即停止。
• 无内置时间筛选（已用 --days 解决）：接口不接收时间范围参数，返回的时间字段为 workPublishTime（可能为时间戳或日期串，脚本统一规整为 YYYY-MM-DD 展示）。要「某时间窗内最热」请用 --days N：脚本自动改 sortType=_2 拉取、按 workPublishTime 客户端过滤到窗口内、再按互动总数降序取前 N 条。不指定 --days 时仍直接给全量最热 N 条。
• 「互动总数」为派生字段：优质库不直接返回互动总数，脚本用 点赞+收藏+评论+分享 四项和派生，与小红书通用口径一致；排序（最热）即按此派生值降序。
• 💰 计费：本接口约 0.04 元/次；最热 20 条只需 1 次调用（offset=0 即满 20 条），性价比高；--max-items > 20 时按翻页次数计费。
• 字段映射详见 references/data_format.md（searchArticle 返回的 work* 字段与 Excel 列逐项对应）。

⚠️ 注意点

1. 该接口是单关键词：searchArticle 为单关键词匹配接口，不支持多关键词。需要搜多个词时，请分别调用本 skill，或直接用 baoge-xhs-keyword-search-hit 版（hit 版支持多关键词）。
2. --max-items 超过 20 会自动翻页（按次数计费，约 0.04 元/次）：服务端固定每页 20 条，要拿 >20 条需逐页 +20（offset=0,20,40…），每多翻一页就多一次 API 调用、多约 0.04 元。最热 20 条只需 1 次调用，性价比最高。
3. 提示词示例与计费实测：当用户说「搜索"xxx"关键词 7 天内的互动最多的 20 条作品」时，脚本会把"xxx"关键词所有 7 天的作品都列出来，20 条一页；如果是 75 条就是 4 页（offset=0/20/40/60），每一页 API 收费约 0.04 元/次，总计 4×0.04=0.16 元。即：窗口内总条数 ÷ 20（向上取整）= 翻页次数 = API 调用次数 = 调用次数 × 0.04 元。

选题跟进建议

导出后可进一步：从互动总数最高的条目里挑 3–5 条最贴合「宝哥聊 AI」定位（老板获客、制造业降本、AI 培训）的笔记做二创选题；或加一列「二创适配度」人工标注。小红书收藏数往往比点赞更能反映"干货/可复用"价值，选题时建议重点看收藏数。