Skill: ligoudanblabla/xhs-search-skill (version 1.0.2)

--- name: xhs-keyword-research description: 小红书关键词调研技能，提供小红书搜索关键词、提取笔记内容和评论的完整工作流。使用 AgentBay 沙箱浏览器 + Playwright 实现登录检测、关键词搜索、笔记结构化提取。当用户提到“帮我在小红书搜/查/看热点/找笔记/提取评论/做舆情分析”时应使用本 skill。首次使用时需要在沙箱浏览器完成登录，后续沙箱会保持登录态。若缺少 AgentBay API Key，先引导用户开通并配置后再执行。 --- # 小红书关键词调研 ## 适用场景 当用户需要以下能力时使用本 skill： - 搜索小红书关键词并收集相关笔记 - 提取笔记正文、互动数据和评论 - 基于多条笔记做趋势、舆情、选题或产品反馈总结 ## 快速流程 1. 检查本地依赖与 API Key 配置 2. 检查 `status.md` 和登录状态 3. 先扩展关键词，再向用户确认配置 4. 根据确认后的关键词执行搜索 5. 提取笔记内容与评论 6. 汇总结果并向用户汇报 7. 删除 `status.md`，重置 `config.json` ## 目录结构 ```text xhs-search-skill/ ├── SKILL.md ├── config.json ├── status.md ├── requirements.txt ├── logs/ ├── output/ │ ├── searchUrls/search_urls_*.json │ └── notes/xhs_note_*.json └── scripts/ ├── common.py ├── check_env.py ├── env_setup.py ├── search_notes.py └── extract_note.py ``` ## 运行约定 以下命令默认在 skill 根目录 `xhs-search-skill/` 下执行。 ### config.json 关键字段 | 字段 | 默认值 | 说明 | |------|--------|------| | `session_id` | `""` | AgentBay session ID，留空则新建 | | `context_name` | `"xiaohongshu"` | Browser Context 名称，用于持久化 Cookie | | `agentbay_api_key` | `""` | AgentBay API Key，与环境变量 `AGENTBAY_API_KEY` 同名（小写），[开通入口](https://www.aliyun.com/product/agentbay) | | `agentbay_region_id` | `""` | 对应环境变量 `AGENTBAY_REGION_ID` | | `agentbay_endpoint` | `""` | 对应环境变量 `AGENTBAY_ENDPOINT` | | `agentbay_timeout_ms` | `"30000"` | 对应环境变量 `AGENTBAY_TIMEOUT_MS` | | `proxy` | `{}` | 代理配置；为空对象时不使用代理 | | `keywords` | `[]` | 关键词字符串数组，每个元素只能有 1 个关键词 | | `max_notes_per_keyword` | `3` | 每个关键词最多采集条数 | | `scroll_rounds` | `10` | 评论区滚动轮数 | proxy 示例： ```json { "proxy": { "server": "http://127.0.0.1:7890", "username": "", "password": "" } } ``` > 小红书反爬策略较强，建议配置高质量代理。 ### 状态驱动规则 每次开始任务前先检查 `status.md`： | 状态 | 含义 | 下一步 | |------|------|--------| | `error` | 本地依赖或 AgentBay 基础配置检查失败 | 修复配置后重试 | | `login_required` | 需要登录 | 引导用户通过 `resource_url` 登录，再重跑 `env_setup.py` | | `running` | 环境就绪 | 展示当前配置并开始搜索 | | `search_done` | 搜索完成 | 运行 `extract_note.py` | | `extract_done` | 提取完成 | 读取 `output/notes/` 做总结 | | 不存在或为空 | 没有进行中的任务 | 从 Step 1 开始 | 补充规则： - `status.md` 不存在或为空，说明上次任务已结束 - `status.md` 仍有状态，优先按当前状态续跑，不要重复从头执行 - 任务完成后删除 `status.md` ## 操作步骤 ### Step 1：检查本地依赖与 API Key 配置 先安装依赖并运行检查脚本： ```bash cd xhs-search-skill pip install -r requirements.txt python scripts/check_env.py ``` `check_env.py` 主要检查： - `agentbay`、`playwright` 等关键依赖是否已安装 - `agentbay_api_key` 是否已在 `config.json` 或环境变量中配置 - AgentBay 基础连接配置是否可用（API Key 必填，其他配置按需校验） - 会创建或复用一个可继续用于后续步骤的 AgentBay session，并写回 `config.json` 的 `session_id`，用于校验 key、region、endpoint 等配置是否可正常工作 API Key 二选一配置： ```json { "agentbay_api_key": [REDACTED_SECRET] } ``` 或： ```bash export AGENTBAY_API_KEY=akm-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx ``` 结果判断： - 脚本执行成功，说明依赖、API Key 和 AgentBay 基础连接校验通过，可进入 Step 2，并清理旧的 `error` 状态 - 如创建或复用了可用 session，会把 `session_id` 写回 `config.json`，供后续步骤继续使用 - 如果脚本写入 `status.md = error` 或提示缺少 API Key，不要进入下一步 如果没有配置 API Key： - 先让用户补齐 `config.json` 中的 `agentbay_api_key` - 或让用户设置环境变量 `AGENTBAY_API_KEY` - 配置完成后，重新运行 `python scripts/check_env.py` 缺少 API Key 时的固定处理： - 必须明确告知“当前无法执行小红书 skill，需要先配置 AgentBay API Key” - 必须给出开通入口：https://www.aliyun.com/product/agentbay - 不要在缺 key 时改用其他数据源、搜索引擎或网页抓取作为兜底 - 用户补齐 key 后，再继续 Step 2 ### Step 2：检查登录状态 只有在 `python scripts/check_env.py` 已通过后，才运行： ```bash python scripts/env_setup.py ``` 读取 `status.md`： - 如果是 `running`，直接进入 Step 3 - 如果是 `login_required`，按下面流程处理 - 如果是 `error`，返回 Step 1 重新检查本地配置 登录流程，最多重试 3 次： ```text 1. 读取 status.md 中的 session_id 和 resource_url 2. 将 session_id 写回 config.json；如果没有则置为空 3. 通知用户打开 resource_url，在沙箱浏览器中完成登录 4. 等待用户回复“已登录” 5. 重新运行 python scripts/env_setup.py 6. 如果仍是 login_required，继续重试；满 3 次后终止 ``` 说明： - `env_setup.py` 现在流程上只承担登录态检查步骤 - `session_id` 会自动更新，可复用 - 登录失败重试超过 3 次时，应明确终止任务 ### Step 3：先扩展关键词，再向用户确认配置 登录成功后、搜索前，先根据用户原始需求扩展关键词，再把扩展结果和其它配置一起展示给用户确认。 关键词扩展规则： - 用户只给 1 个关键词时，扩展到 3 个 - 用户给 2 个关键词时，可保持不变或补到 3 个 - 用户给 3 个及以上时，直接使用 关键词格式要求： - `keywords` 必须是字符串数组 - 每个数组元素只放 1 个关键词 - 多个关键词必须拆成多个元素，不能拼进同一个字符串 - 写 JSON 时建议一行一个关键词元素 正确示例： ```json { "keywords": [ "阿里云无影 评测", "阿里云无影 使用体验", "阿里云无影 最新动态" ] } ``` 错误示例： ```json { "keywords": [ "阿里云无影 评测，阿里云无影 使用体验，阿里云无影 最新动态" ] } ``` 推荐格式： ```text 环境已就绪，当前配置如下： - 关键词： - 关键词 1 - 关键词 2 - 关键词 3 - 每个关键词采集上限：N 条 - 代理：未配置 / 自定义代理 xxx 如需调整以上配置，请告诉我。 没问题的话我将开始搜索。 ``` 要求： - 必须先展示扩展后的关键词，再等待用户确认 - 如果用户要求增删改关键词，应先更新关键词列表，再继续后续步骤 - 关键词优先逐行展示，不要挤成一长串 - 如未配置代理，可提醒用户小红书风控较强 ### Step 4：根据确认后的关键词执行搜索 运行： ```bash python scripts/search_notes.py # 或 python scripts/search_notes.py --keywords "关键词1,关键词2,关键词3" ``` 数量规则： - 默认 `max_notes_per_keyword = 3` - “多找一些”可调到 `5-10` - “简单看看”可调到 `2-3` 搜索前必须说明： ```text 即将搜索以下已确认关键词： - xxx - xxx - xxx 每个关键词最多采集 N 条，预计共采集约 M 条笔记链接。 开始搜索... ``` 内部结果会写入 `output/searchUrls/search_urls_{timestamp}.json` 和 `status.md`，仅供后续步骤使用，不要展示给用户。 ### Step 5：提取笔记内容与评论 运行： ```bash python scripts/extract_note.py python scripts/extract_note.py --url "https://..." python scripts/extract_note.py --urls-file output/searchUrls/search_urls_20260309_120000.json ``` 提取前必须说明耗时： ```text 共 N 条笔记待提取，每条约需 50 秒，预计总耗时约 X 分钟。 请稍等，我开始提取。 ``` 调用建议： - 同步调用：`timeout >= N * 50 秒 + 30 秒` - 异步轮询：首次轮询延迟约 `N * 50 秒 * 0.8` 内部结果会写入 `output/notes/xhs_note_{timestamp}.json` 和 `status.md`，不要展示给用户。 ### Step 6：整理结果并汇报用户 当 `status.md` 为 `extract_done` 时，读取 `output/notes/` 下本次提取生成的笔记 JSON，输出结构化总结。 汇报原则： - 不要输出原始 JSON - 以整体观察为主，不要逐条笔记平铺 - 可引用少量代表性案例，但只用于支撑结论 - 评论只在能支撑判断时展示 推荐格式： ```text 共采集 N 条笔记，关键词：xxx、xxx、xxx 整体观察： - 这批内容主要集中在 xxx、xxx、xxx - 用户最关注的问题是 xxx - xxx 类型内容更容易获得互动 - 整体情绪偏 xxx 代表性内容： - 笔记 A：核心观点 + 为什么有代表性 - 笔记 B：核心观点 + 为什么有代表性 结论建议： - 舆情：总结讨论焦点和情绪走向 - 选题：提炼值得延展的方向 - 产品反馈：归纳好评、槽点和待验证问题 本次共分析 N 条笔记。 ``` 严格禁止： - 不要展示 `status.md`、`search_urls_*.json`、`xhs_note_*.json` - 不要展示任何 JSON 路径、目录路径或本地存储位置 - 不要添加“数据源”“文件位置”“保存位置”“本地目录”等区块 - 即使知道最终文件位置，也不要告诉用户 ### Step 7：任务完成后收尾 全部完成后： 1. 删除 `status.md` 2. 重置 `config.json` - `session_id = ""` - `keywords = []` ## 数据结构参考 以下结构仅供读取 JSON 时参考，不要原样展示给用户： ```json { "url": "https://www.xiaohongshu.com/explore/...", "title": "笔记标题", "content_text": "正文内容", "author": "作者昵称", "like_count": 1234, "collect_count": 567, "comment_count": 89, "comments": [ {"level": "一级评论", "text": "评论内容", "like_count": 10}, {"level": "二级评论", "text": "回复内容", "like_count": 2} ] } ```


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)