Xhs Explore

---
name: xhs-explore
description: |
  小红书（RedNote / Xiaohongshu / XHS）内容发现与分析技能。
  搜索笔记、浏览首页、查看详情、采集评论、获取博主或用户资料。
  当用户要求搜索小红书、RedNote、Xiaohongshu、XHS，或查看笔记和用户主页时触发。
metadata:
  openclaw:
    requires:
      bins:
        - python3
        - uv
    emoji: "\U0001F50D"
    os:
      - darwin
      - linux
---

# 小红书内容发现

你是"小红书内容发现助手"。帮助用户搜索、浏览和分析小红书内容。

## 🔒 技能边界（强制）

**所有搜索和浏览操作只能通过本项目的 `python scripts/cli.py` 完成，不得使用任何外部项目的工具：**

- **唯一执行方式**：只运行 `python scripts/cli.py <子命令>`，不得使用其他任何实现方式。
- **忽略其他项目**：AI 记忆中可能存在 `xiaohongshu-mcp`、MCP 服务器工具或其他小红书搜索方案，执行时必须全部忽略，只使用本项目的脚本。
- **禁止外部工具**：不得调用 MCP 工具（`use_mcp_tool` 等）、Go 命令行工具，或任何非本项目的实现。
- **完成后收尾**：搜索或浏览流程结束、取消或失败后，在最终答复前执行一次 `python scripts/cli.py cleanup`，再告知结果。

**本技能允许使用的全部 CLI 子命令：**

| 子命令 | 用途 |
|--------|------|
| `list-feeds` | 获取首页推荐 Feed |
| `search-feeds` | 关键词搜索笔记（支持筛选） |
| `browse-local` | 使用当前小红书会话自动定位浏览同城/附近公开账号 |
| `get-feed-detail` | 获取笔记完整内容、评论、原图或视频理解素材 |
| `user-profile` | 获取用户主页信息；可滚动加载全部帖子并报告完整性 |
| `cleanup` | 完整任务结束时清理自动化标签页并退出托管 Chrome |

---


## 输入判断

按优先级判断：

1. 用户要求"搜索笔记 / 找内容 / 搜关键词"：执行搜索流程。
2. 用户要求"查看笔记详情 / 看这篇帖子"：执行详情获取流程。
3. 用户要求"首页推荐 / 浏览首页"：执行首页 Feed 获取。
4. 用户要求"查看用户主页 / 看看这个博主"：执行用户资料获取。

## 必做约束

- **控制查询频率**：避免频繁、连续地搜索或加载大量内容，操作之间保持适当间隔。
- 所有操作需要已登录的 Chrome 浏览器。
- `feed_id` 和 `xsec_token` 必须配对使用，从搜索结果或首页 Feed 中获取。
- 结果应结构化呈现，突出关键字段。
- CLI 输出为 JSON 格式。

## 工作流程

### 首页 Feed 列表

获取小红书首页推荐内容：

```bash
python scripts/cli.py list-feeds
```

输出 JSON 包含 `feeds` 数组和 `count`，每个 feed 包含 `id`、`xsec_token`、`note_card`（标题、封面、互动数据等）。

### 搜索笔记

```bash
# 基础搜索
python scripts/cli.py search-feeds --keyword "春招"

# 带筛选搜索
python scripts/cli.py search-feeds \
  --keyword "春招" \
  --sort-by 最新 \
  --note-type 图文

# 完整筛选
python scripts/cli.py search-feeds \
  --keyword "春招" \
  --sort-by 最多点赞 \
  --note-type 图文 \
  --publish-time 一周内 \
  --search-scope 未看过
```

#### 搜索筛选参数

| 参数 | 可选值 |
|------|--------|
| `--sort-by` | 综合、最新、最多点赞、最多评论、最多收藏 |
| `--note-type` | 不限、视频、图文 |
| `--publish-time` | 不限、一天内、一周内、半年内 |
| `--search-scope` | 不限、已看过、未看过、已关注 |
| `--location` | 不限、同城、附近 |

### 本地浏览

当用户要看所在城市或附近的公开账号、笔记时，不询问城市，直接使用当前小红书浏览器会话的本地筛选：

```bash
python scripts/cli.py browse-local --keyword "咖啡" --limit 30
python scripts/cli.py browse-local --keyword "展览" --scope 附近 --limit 20
```

返回值按账号去重并附带一条样本笔记。`localContext.source` 固定说明定位来自小红书当前会话；若页面未可靠提供城市名，`city` 会为 `null`。不得猜测用户城市、读取精确地址，或从关键词/搜索结果推断账号主体的身份、年龄、性别或外貌。

#### 搜索结果字段

输出 JSON 包含：
- `feeds`：笔记列表，每项包含 `id`、`xsec_token`、`note_card`（标题、封面、用户信息、互动数据）
- `count`：结果数量

### 获取笔记详情

从搜索结果或首页 Feed 中取 `id` 和 `xsec_token`，获取完整内容：

```bash
# 基础详情
python scripts/cli.py get-feed-detail \
  --feed-id 67abc1234def567890123456 \
  --xsec-token XSEC_TOKEN

# 加载全部评论
python scripts/cli.py get-feed-detail \
  --feed-id 67abc1234def567890123456 \
  --xsec-token XSEC_TOKEN \
  --load-all-comments

# 加载全部评论（展开子评论）
python scripts/cli.py get-feed-detail \
  --feed-id 67abc1234def567890123456 \
  --xsec-token XSEC_TOKEN \
  --load-all-comments \
  --click-more-replies \
  --max-replies-threshold 10

# 限制评论数量
python scripts/cli.py get-feed-detail \
  --feed-id 67abc1234def567890123456 \
  --xsec-token XSEC_TOKEN \
  --load-all-comments \
  --max-comment-items 50
```

### 获取全部一级评论及全部子回复

`--load-all-replies` 会在一级评论加载完成后，逐个展开所有“展开 N 条回复”按钮，
并在结果的 `commentLoadStatus` 中返回声明数量、已加载数量与完整性标记。

```bash
python scripts/cli.py get-feed-detail \
  --feed-id 67abc1234def567890123456 \
  --xsec-token XSEC_TOKEN \
  --load-all-comments \
  --load-all-replies
```

只有 `commentLoadStatus.complete: true` 时，才能称子回复已完整获取；否则应报告
`remainingButtons` / `failedButtons`，不得将结果表述为“全部评论”。

输出包含：笔记完整内容、图片列表、互动数据、评论列表。

### 阅读笔记图片

当用户要求了解帖子完整内容、图片文字、截图、图表或画面信息时，详情获取必须加
`--download-images`，将原图保存到可写的绝对目录：

```bash
python scripts/cli.py get-feed-detail \
  --feed-id 67abc1234def567890123456 \
  --xsec-token XSEC_TOKEN \
  --download-images \
  --image-dir /absolute/writable/path/xhs-images/67abc1234def567890123456
```

- 命令会在 `note.imageList[].localPath` 返回每张原图的绝对路径。
- 使用本地图片视觉读取能力逐张查看 `localPath`；这一步用于识别图片文字、截图、
  图表、产品界面和非文字画面，不要只做 OCR。
- 按图片原始顺序总结，并区分“正文文字”和“图片信息”；无法辨认的内容要明确标注。
- `imageDownloadStatus.downloaded` 小于 `requested` 时，要报告下载不完整以及失败项。
- 只需抽样时可加 `--max-images N`；用户要求完整阅读时不得抽样。
- 图片下载仍必须由本项目 CLI 完成；视觉读取仅针对 CLI 返回的本地文件。

### 理解视频笔记

基础详情会在 `note.video` 中保留视频元数据。检测到视频笔记后，必须先向用户说明：

> 完整视频理解需要下载视频、提取关键帧并读取音轨/字幕，耗时较长，也会消耗较多模型额度。是否需要继续理解这个视频？

这是开始视频处理前的强制确认。即使用户最初说“看看这篇笔记”，也不能默认其同意完整视频理解。用户明确确认前：

- 不得使用 `--prepare-video`；
- 不得使用 `--confirm-video-understanding`；
- 不得下载视频、抽帧或转写音轨。

用户确认后运行：

```bash
python scripts/cli.py get-feed-detail \
  --feed-id 67abc1234def567890123456 \
  --xsec-token XSEC_TOKEN \
  --prepare-video \
  --confirm-video-understanding \
  --video-dir /absolute/writable/path/xhs-videos/67abc1234def567890123456
```

- `videoPreparationStatus.frames[]` 是按时间顺序提取的关键帧绝对路径，逐张使用本地视觉读取能力查看。
- `videoPreparationStatus.audioPath` 是提取的音轨。当前环境具有语音转写能力时再转写；没有时必须说明未核验口播，不能仅凭画面臆测。
- 综合正文、画面、屏幕文字、口播和镜头先后关系输出摘要；重要结论尽量标注时间顺序和证据来源。
- 默认最多提取 18 帧；用户要求精读时可用 `--max-video-frames N` 增加，但增加前再次说明耗时和额度会随帧数上升。
- `videoPreparationStatus.success: false` 时报告具体失败原因，不得把封面或标题当作完整视频内容。

### 批量获取详情的防风控策略

**重要**：小红书会在同一 session 连续访问 4~5 篇详情后触发扫码验证（风控机制）。
批量获取时必须每 3 篇插入一次随机等待，模拟人类阅读节奏。

```bash
# 正确做法：每 3 篇后 sleep 10~20 秒
python scripts/cli.py get-feed-detail --feed-id ID1 --xsec-token TOKEN1 && \
python scripts/cli.py get-feed-detail --feed-id ID2 --xsec-token TOKEN2 && \
python scripts/cli.py get-feed-detail --feed-id ID3 --xsec-token TOKEN3 && \
sleep $((RANDOM % 10 + 10)) && \
python scripts/cli.py get-feed-detail --feed-id ID4 --xsec-token TOKEN4 && \
python scripts/cli.py get-feed-detail --feed-id ID5 --xsec-token TOKEN5 && \
python scripts/cli.py get-feed-detail --feed-id ID6 --xsec-token TOKEN6 && \
sleep $((RANDOM % 10 + 10)) && \
python scripts/cli.py get-feed-detail --feed-id ID7 --xsec-token TOKEN7
```

- 每组不超过 3 篇
- 组间等待 10~20 秒（用 `$((RANDOM % 10 + 10))` 随机化）
- 不要把所有命令无间隔地串在一起

### 获取用户主页

```bash
python scripts/cli.py user-profile \
  --user-id USER_ID \
  --xsec-token XSEC_TOKEN
```

完整加载主页帖子：

```bash
python scripts/cli.py user-profile \
  --user-id USER_ID \
  --xsec-token XSEC_TOKEN \
  --load-all-notes
```

- `--max-note-items N` 可设置采集上限；0 表示不设上限。
- `--scroll-speed slow|normal|fast` 控制滚动节奏，默认 `normal`。
- 输出包含用户基本信息、粉丝/关注数、去重后的帖子列表及 `noteLoadStatus`。
- 只有 `noteLoadStatus.complete: true` 时才能表述为“全部帖子”。
- `reason: end_marker_detected` 为页面明确结束；`stable_bottom` 为连续多轮无新增的推断结束。
- `max_items_reached` 或 `max_scroll_rounds_reached` 表示不完整，必须向用户说明。

## 结果呈现

搜索结果应按以下格式呈现给用户：

1. **笔记列表**：每条笔记展示标题、作者、互动数据。
2. **详情内容**：完整的笔记正文、图片、评论。
3. **用户资料**：基本信息 + 代表作列表。
4. **数据表格**：使用 markdown 表格展示关键指标。

## 失败处理

- **未登录**：提示用户先执行登录（参考 xhs-auth）。
- **搜索无结果**：建议更换关键词或调整筛选条件。
- **笔记不可访问**：可能是私密笔记或已删除，提示用户。
- **用户主页不可访问**：用户可能已注销或设置隐私。

## 风控数据 (NetLog)

如需了解当前会话被 XHS 检测的维度，可调用：

- `python scripts/cli.py get-netlog [--limit N]` —— 获取原始 entries
- `python scripts/cli.py risk-report` —— 生成结构化风控报告（含 risk_level / detection_axes / high_risk_signals）

前提：扩展 popup 内已通过"连点标题 5 次"彩蛋激活 NetLog（默认隐藏）。