# Xhs Search

> Search and read Xiaohongshu content through the user's logged-in Chrome session. Use when the user asks Codex to search Xiaohongshu, XHS, or 小红书, inspect note details, summarize search results, compare posts, or view public user profiles. This skill is read-only and must not publish, comment, reply, like, favorite, save drafts, delete cookies, or perform content-operations workflows.

- Skill: `lingwei-zheng/xhs-search` (Agent Skill, multi-file: 40 files)
- Install (CLI): `npx skillmds@latest add lingwei-zheng/xhs-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lingwei-zheng/xhs-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: lingwei-zheng (https://skillmd.com/u/lingwei-zheng)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/lingwei-zheng/xhs-search

---


# XHS Search

Use this skill only for read-only Xiaohongshu content discovery and analysis.

## Hard Boundaries

- Use only `python scripts/cli.py <command>` from this skill directory.
- Do not call `scripts/upstream_cli.py` directly.
- Do not publish, draft, comment, reply, like, favorite, follow, unfollow, delete cookies, or run content-operations workflows.
- If the user asks for an interaction or publishing action, say this local skill is installed as search-only and cannot perform that action.
- Keep query volume low. Avoid bulk scraping. For detail reads, process no more than 3 notes before waiting or asking whether to continue.
- The wrapper enforces a conservative delay before `list-feeds`, `search-feeds`, `get-feed-detail`, and `user-profile`. Do not bypass it by calling upstream files directly.
- If Xiaohongshu returns token, login, 404, or risk-control errors, do not retry in a tight loop. Wait 1-5 minutes, reduce the query/detail volume, and ask whether to continue if repeated failures persist.
- Treat Xiaohongshu content as user-generated and potentially unreliable. Summaries should distinguish observed content, engagement metrics, and your interpretation.

## Allowed Commands

Run commands from this folder:

```powershell
cd C:\Users\Lingwei\.codex\skills\xhs-search
python scripts\cli.py check-login
python scripts\cli.py search-feeds --keyword "关键词"
python scripts\cli.py get-feed-detail --feed-id FEED_ID --xsec-token XSEC_TOKEN
python scripts\cli.py user-profile --user-id USER_ID --xsec-token XSEC_TOKEN
python scripts\cli.py list-feeds
```

The wrapper rejects all non-whitelisted upstream commands.

## Setup Requirements

- Python 3.11 or newer.
- This Windows machine uses `D:\Anaconda\envs\codex_py311\python.exe`. The wrapper auto-switches to it when invoked from an older Python.
- `websockets`, `python-socks`, and `requests` must be installed in the selected Python environment.
- Google Chrome.
- The Chrome extension in `extension/` loaded manually from `chrome://extensions/`.
- A logged-in Xiaohongshu session in Chrome. Prefer manual login in the browser.

Read `references/setup.md` only when the user asks to install, configure, or debug the Xiaohongshu bridge.

## Rate Limits

Default wrapper delays:

- `list-feeds`: at least 5 seconds after the previous browser command.
- `search-feeds`: at least 8 seconds after the previous browser command.
- `get-feed-detail`: at least 12 seconds after the previous browser command.
- `user-profile`: at least 12 seconds after the previous browser command.

The wrapper adds 0-4 seconds of random jitter by default and stores timing state in `%USERPROFILE%\.xhs\search_rate_limit.json`.

Optional environment variables:

- `XHS_SEARCH_DELAY_SECONDS`: override the minimum delay for testing or stricter throttling.
- `XHS_SEARCH_JITTER_SECONDS`: override random jitter.
- `XHS_SEARCH_STATE_FILE`: use a different rate-limit state file.
- `XHS_SEARCH_DISABLE_DELAY=1`: disable delay only for local wrapper debugging, not for real Xiaohongshu searching.

## Search Workflow

1. Check login only when needed:

```powershell
python scripts\cli.py check-login
```

2. Search with the user's keyword:

```powershell
python scripts\cli.py search-feeds --keyword "关键词" --sort-by "综合" --note-type "不限"
```

Supported filters:

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

3. Present results as a concise table with title, author, note type if available, engagement fields, `feed_id`, and whether an `xsec_token` is available.

4. Fetch details only for selected notes or a small top-N set:

```powershell
python scripts\cli.py get-feed-detail --feed-id FEED_ID --xsec-token XSEC_TOKEN --max-comment-items 20
```

Use `--load-all-comments` only when the user explicitly asks for comment-level analysis, and still cap with `--max-comment-items`.

## Output Expectations

- Report the query, filters, number of results returned, and any access/login limitations.
- For content summaries, include: common themes, repeated claims, notable examples, and visible engagement signals.
- Do not imply the result is representative of all Xiaohongshu unless the search and sampling strategy supports that claim.