视频号选题关键词搜索
> 英文标识（目录名）：wechat-keyword-search
> 📖 使用说明（含提问示例）：见本目录下 README.md
Overview
输入一个关键词，调用 RedFox 视频号接口拉取相关作品，按点赞数降序取出前 N 条，在对话里输出一张 Markdown 表格，同时导出一份 Excel 文档供下载（含超链接、数值格式、冻结表头）。适用于选题调研、竞品/爆款分析、内容运营看板等场景。
- 接口：
POST https://redfox.hk/story/api/sphAllData/searchWork（文档号E7G00COY，广域库） - 鉴权：请求头
X-API-Key: <REDFOX_API_KEY> - 计费：约 ¥0.04 / 次调用
Prerequisites（一次性）
方式一：填写配置文件（推荐，最简单，一次配置永久生效）
技能目录下已附模板 config.example.env，按以下 3 步完成配置：
- 把
config.example.env复制一份并重命名为config.env（不要直接改模板文件，否则下次分发时模板就没了） - 用记事本 / VS Code 打开
config.env，把REDFOX_API_KEY=ak_xxxx中的ak_xxxx替换成你自己的密钥 - 保存即可。之后脚本会自动读取
config.env，无需设置任何环境变量
模板文件内含完整图文指引（如何获取密钥、格式说明、安全提示），照做即可。
方式二：设置环境变量（适合开发者/CI）
- Windows (PowerShell)：
$env:REDFOX_API_KEY = "ak_xxxx" - macOS/Linux：
export REDFOX_API_KEY=ak_xxxx - 或写进 shell 配置文件（
.bashrc/.zshrc）持久化
方式三：临时传入（仅本次有效，不落盘）
运行脚本时加 --key ak_xxxx。
> 密钥读取优先级：--key > 技能目录 config.env > 环境变量 REDFOX_API_KEY，找到即用。
> 默认行为：优先读取 config.env（一次配置永久生效）；若 config.env 未配置或仍是占位符，自动兜底读取用户环境变量 REDFOX_API_KEY。
> 获取密钥：RedFox 控制台 → 密钥管理：https://redfox.hk/dashboard/account（按调用量计费，约 ¥0.04/次）
> 安全提示：config.env 含真实密钥，请勿上传公开仓库或转发他人；如泄露请到控制台删除重建。
Workflow
当用户提出「搜视频号 + 关键词」类需求时，按以下步骤执行：
- 解析参数：从用户的话里提取
-keyword（必填，搜索关键词）
-top（取前几条，默认 10，最大 50）
-sort（接口排序方式，默认最多点赞；可选综合/最新/最多点赞/最多收藏）
-rank_by（排序指标，默认点赞；可选点赞/评论/转发/收藏。用户说「评论最多的」「转发最多的」「收藏最多的」时映射到对应指标）
-days（可选，仅保留最近 N 天内的作品；接口本身无时间参数，由脚本客户端按publishTime过滤。默认 0=不限时间） - 确认鉴权：检查 API Key 是否可用（脚本自动按
--key> 技能目录config.env> 环境变量REDFOX_API_KEY的顺序解析，默认读config.env、缺失时兜底到环境变量）。若仍缺失，按优先级尝试：
- 先看技能目录下是否有config.env（由config.example.env复制改名而来）。若存在但 key 仍是占位符ak_xxxx，引导用户填入真实密钥；若不存在，引导用户复制模板并填写。
- 用户若在 Windows「用户变量」里设了REDFOX_API_KEY，但 WorkBuddy 的 Bash 沙箱读不到（沙箱不与交互终端共享环境、且reg被安全策略禁用），改用 PowerShell 读取并注入进程环境后再运行脚本。一次性固化建议（强烈推荐）：既然能从用户变量读到密钥，直接用它的值生成技能目录下的config.env，此后所有 Bash 直接运行脚本，不再需要 PowerShell 注入、也不会踩乱码坑：
powershell $key = [Environment]::GetEnvironmentVariable('REDFOX_API_KEY','User') "REDFOX_API_KEY=$key" | Out-File -FilePath "C:\Users\Administrator\.workbuddy\skills\wechat-keyword-search\config.env" -Encoding ascii
若暂不固化，临时方案如下（注意：Excel 导出依赖 openpyxl，必须用隔离 venv 的 python 运行）：
powershell $key = [Environment]::GetEnvironmentVariable('REDFOX_API_KEY','User') if ($key) { $env:REDFOX_API_KEY = $key & "C:\Users\Administrator\.workbuddy\binaries\python\envs\default\Scripts\python.exe" "C:\Users\Administrator\.workbuddy\skills\wechat-keyword-search\scripts\search_shipinhao.py" --keyword "<关键词>" --top 10 --sort 最多点赞 }
（注意：PowerShell 工具不回显 stdout，可把脚本输出重定向到日志文件再查看。但重定向日志会因 GBK/UTF-8 双重转码导致中文乱码——正确做法：直接读取脚本自动导出的 md 文件（D:/Temp/视频号搜索_<关键词>_top<N>.md，UTF-8 编码），用 Read 工具或python -X utf8 -c "print(open(r'<md路径>',encoding='utf-8').read())"均可正常显示。重定向产生的临时日志文件（如_xxx_log.txt）用完随手删除，勿留在工作目录。）
- 否则提示用户去控制台创建密钥（https://redfox.hk/dashboard/account）并填入config.env
- 或询问用户是否愿意临时提供密钥（用--key传入，不落盘） - 运行脚本（必须用隔离 venv 的 python，Excel 导出依赖其中的 openpyxl）：
bash C:/Users/Administrator/.workbuddy/binaries/python/envs/default/Scripts/python.exe \ "C:/Users/Administrator/.workbuddy/skills/wechat-keyword-search/scripts/search_shipinhao.py" \ --keyword "<关键词>" --top 10 --sort 最多点赞
- 路径为占位，实际以当前环境 venv 解释器与 skill 目录为准。
- 想跳过 Excel 只出 Markdown，加--no-excel；想自定义路径加--excel-path <路径>。 - 呈现结果：
- 脚本先打印 Markdown 表格（含命中总数、排名、描述、作者、点赞/评论/转发/收藏数、发布时间、视频链接），原样展示给用户。
- 脚本末尾会打印一行📊 Excel 已导出：<路径>，用present_files把该 xlsx 一并呈现给用户下载（链接列在 Excel 中为可点击超链接）。
示例
用户输入：「搜一下 workbuddy，视频号里点赞最多的前 10 条」
→ 运行 --keyword workbuddy --top 10 --sort 最多点赞
→ 输出：
| 排名 | 描述 | 作者 | 点赞 | 评论 | 转发 | 收藏 | 发布时间 | 链接 |
|---|---|---|---|---|---|---|---|---|
| 1 | … | … | … | … | … | … | … | 视频 |
| … | … | … | … | … | … | … | … | … |
用户输入：「搜索 workbuddy，找出最近7天里，点赞最多的20条视频号视频」
→ 运行 --keyword workbuddy --top 20 --days 7
→ 脚本会改用 sort=最新 拉取，按发布时间过滤出最近 7 天窗口内的作品，再按点赞数降序取前 20 条输出表格。
用户输入：「搜一下企业管理培训，评论最多的 20 条」
→ 运行 --keyword 企业管理培训 --top 20 --rank-by comment
→ 脚本多拉几页作品（最多 5 页/250 条）后按评论数降序取前 20 条输出表格。
输出表格字段
| 列 | 来源字段 | 说明 |
|---|---|---|
| 排名 | （脚本计算） | 按指定排序指标降序（默认点赞） |
| 描述 | description |
作品文案，超长截断 |
| 作者 | nickname |
视频号昵称 |
| 点赞 | likeCount |
点赞数 |
| 评论 | commentCount |
评论数 |
| 转发 | forwardCount |
转发数 |
| 收藏 | favCount |
收藏数 |
| 发布时间 | publishTime |
如 2026-07-22 14:12:18 |
| 链接 | videoUrl |
可点击打开视频 |
> 脚本已对返回结果按排序指标（默认 likeCount）再做一次客户端降序排序，确保「前 N 条 = 该指标最多」成立，不受接口排序影响。切换排序指标用 --rank-by like|comment|forward|fav。
Excel 文档（默认导出）
- 保存路径默认
D:/Temp/视频号搜索_<关键词>_top<N>[_最近<days>天].xlsx，可用--excel-path覆盖。 - 工作表名为「视频号作品」，9 列：排名 / 描述 / 作者 / 点赞 / 评论 / 转发 / 收藏 / 发布时间 / 视频链接。
- 表头蓝色加粗、首行冻结；点赞/评论/转发/收藏为
#,##0数值格式；视频链接列写入可点击超链接（无链接则为空）。 - 用
--no-excel可仅输出 Markdown 表格。
时间窗口说明（--days）
- 接口没有时间范围参数（仅支持
keyword/sort/page/size），因此「最近 N 天」由脚本在客户端完成：
1. 用sort=最新拉取，按publishTime收集>= now - N 天的作品；
2. 「最新」排序下，一旦某页最老时间早于窗口即停止翻页（最多 20 页封顶）；
3. 窗口内作品再按排序指标（默认点赞，--rank-by可切换为评论/转发/收藏）降序取前 N 条。 - 该逻辑依赖沙箱本地时间 = 北京时间：已验证当前 WorkBuddy 沙箱
datetime.now()即东八区，与接口publishTime（北京时间）可直接比较，无需时区换算。
错误处理
| 现象 | 处理 |
|---|---|
未找到 API Key（--key/环境变量/config.env 均无） |
引导用户复制 config.example.env 为 config.env 并填入密钥；或临时 --key 传入 |
config.env 存在但 key 仍是占位符 ak_xxxx |
引导用户把 ak_xxxx 替换为真实密钥 |
code=401 鉴权失败 |
检查密钥是否有效、是否被禁用 |
code=403 |
当前密钥无该接口权限，确认接口权限 |
REDFOX_API_KEY 设在 Windows 用户变量但 Bash 沙箱读不到 |
走上面第 2 步的 PowerShell 读取方案 |
网络错误 WinError 10054 远程主机强制关闭连接 |
多为偶发重置，重试 1–3 次通常即通过（实测 Bash 沙箱网络可用、PowerShell 偶发重置） |
| 网络/超时错误 | 提示用户检查网络后重试 |
| 返回空列表 | 告知「该关键词未搜到作品」，建议换词或缩小范围 |
覆盖导出失败，报 Device or resource busy / PermissionError |
同名 视频号搜索_*.xlsx 或 *.md 正被预览面板/Excel 打开占用（文件锁），需彻底关闭该文件标签（仅切走/最小化不够），或换 --excel-path 输出到新文件 |
| 结果里混入与关键词弱相关的作品（模糊匹配，如本次"workbuddy"结果中出现无关搞笑视频） | 属接口模糊匹配的正常现象，解读/引用时按描述与作者人工过滤 |
部分条目链接列为 - |
接口对该作品未返回 videoUrl，属正常现象，不影响其他数据列 |
脚本参数速查
--keyword 搜索关键词（必填）
--top 取前 N 条，默认 10，最大 50
--sort 接口排序：综合|最新|最多点赞|最多收藏，默认 最多点赞
--rank-by 排序指标：like=点赞|comment=评论|forward=转发|fav=收藏，默认 like
--days 仅保留最近 N 天内的作品（客户端按发布时间过滤），默认 0=不限
--key 临时传入 RedFox API Key（不落盘）
--excel/--no-excel 是否额外导出 Excel（默认开；--no-excel 仅出 Markdown）
--excel-path 自定义 Excel 保存路径（默认 D:/Temp/视频号搜索_<关键词>_top<N>.xlsx）
