Xiaohongshu

Xiaohongshu

Search notes, read note details, view comments, browse user profiles, and get the home feed from Xiaohongshu (小红书).

Skill Directory

<SKILL_DIR> is the directory containing this SKILL.md file. Determine it ONCE at the start and reuse it.

Setup (run FIRST — every time, before any operation)

You MUST complete this setup before running any script. Do NOT skip.

sig status xiaohongshu 2>&1

Check the JSON output fields configured and valid:

• configured: false → run Provider Setup below.
• valid: false (but configured: true) → run sig login xiaohongshu --mode visible, complete the captcha, then re-check.
• valid: true → run Vendor Setup (one-time per machine), then execute the user's request.

Provider Setup

1. Read <SKILL_DIR>/references/provider-config.yaml
2. Append the provider block to ~/.sig/config.yaml under providers:
3. Run sig login xiaohongshu --mode visible — a browser opens; scan the QR code with the Xiaohongshu app and complete the slider/image captcha if prompted
4. Verify: sig status xiaohongshu should show valid: true

Why the validateRule is so picky — three response shapes

/api/sns/web/unread_count is a permissive endpoint that hides a "partially expired cookie" state behind what looks like a successful response. The provider's validateRule is built specifically to reject it:

If sig login exits without prompting you, but later API calls fail with empty data — the partially-expired-cookie state was bypassed by a stale rule. Re-pull references/provider-config.yaml and refresh the rule in ~/.sig/config.yaml, then re-login.

What this rule does NOT catch. unread_count is more permissive than search/feed APIs. A cookie that passes the rule (state #1) may still fail on search if the risk-control / session-token portion has aged out. If sig status shows valid:true but search keeps returning empty data, you're in this gray zone — the only fix is sig logout xiaohongshu && sig login xiaohongshu --mode visible. See Diagnosis below for how to confirm.

Vendor Setup (one-time per machine)

Unlike most skills, xiaohongshu signs every request via JS files at <SKILL_DIR>/vendor/static/, evaluated through PyExecJS. The skill ships those source files but not their npm/pip deps — install them once:

node --version                          # must be >= 18; install from https://nodejs.org if missing
cd <SKILL_DIR>/vendor && npm install    # installs crypto-js, jsdom
pip install --user -r <SKILL_DIR>/requirements.txt   # PyExecJS, requests, loguru, retry

If pip complains about externally-managed Python (PEP 668 on macOS/Debian), use a venv or pipx.

Smoke-test signing (no network, no cookie needed):

cd <SKILL_DIR>/vendor && python3 -c "
import sys; sys.path.insert(0, '.')
from xhs_utils.xhs_util import generate_x_rap_param, generate_xs_xs_common
xs, xt, xsc = generate_xs_xs_common('a1=test', '/api/sns/web/v1/feed', '', 'POST')
rap = generate_x_rap_param('/api/sns/web/v1/user_posted', '')
print('OK' if xs and rap else 'FAIL')
"

Expect OK. If it fails, see Error Handling.

Running Scripts

All scripts output JSON to stdout. Read operations need a cookie (the public site does not allow anonymous access to most endpoints).

Recommended — sig run injects the cookie as SIG_XIAOHONGSHU_COOKIE:

sig run xiaohongshu -- bash -c 'python3 <SKILL_DIR>/scripts/xiaohongshu_search_note.py --keyword "AI" --page 1'

Alternative — pass --cookie explicitly:

COOKIE=$(sig get xiaohongshu --no-redaction --format value)
python3 <SKILL_DIR>/scripts/xiaohongshu_search_note.py --keyword "AI" --cookie "$COOKIE"

Scripts Reference

All scripts are in this skill's scripts/ directory. Output is JSON to stdout.

Script Arguments

xiaohongshu_search_note.py

• --keyword (required) — search keyword
• --page — page number, default 1
• --sort — 0 general (default), 1 newest, 2 most-liked, 3 most-commented, 4 most-collected
• --note-type — 0 any (default), 1 video, 2 image
• --cookie — override env var

xiaohongshu_get_note_info.py

• --url (required) — full note URL like https://www.xiaohongshu.com/explore/<id>?xsec_token=...&xsec_source=pc_search
• --cookie

xiaohongshu_get_note_comments.py

• --note-id (required)
• --xsec-token (required) — comes from a search/feed result
• --cursor — pagination, default empty
• --cookie

xiaohongshu_get_user_info.py

• --user-id (required)
• --cookie

xiaohongshu_get_user_notes.py

• --user-id (required)
• --cursor — pagination, default empty
• --xsec-token, --xsec-source — pass through if available
• --cookie

xiaohongshu_get_homefeed.py

• --category — channel id, default homefeed_recommend
• --cursor-score — pagination
• --refresh-type, --note-index — feed iteration state
• --cookie

Key Concepts

• xsec_token / xsec_source: per-note security tokens issued by the search/feed endpoints. To call get_note_info or get_note_comments, you must first call search_note to obtain these tokens (they are embedded in the note URL returned).
• Why Node.js? XHS signs every request with x-s, x-t, x-s-common, x-rap-param, and x-xray-traceid derived from JSVMP-obfuscated JavaScript. The skill ships those JS files (<SKILL_DIR>/vendor/static/) and runs them via PyExecJS, which shells out to node. Pure-Python signing libraries (e.g. xhshow) currently miss x-rap-param and fail on data APIs with HTTP 406.