xhs-search-workflow

XHS Search Workflow

When using this skill, treat it first as a standalone Xiaohongshu workflow toolbox, not as a thin wrapper around the original repository.

Execution flow

First confirm the runtime environment. Use skills/xhs-search-workflow/scripts/setup_env.sh to initialize dependencies. When executing scripts, prefer using skills/xhs-search-workflow/.venv/bin/python. When you need full installation, common commands, or validation commands, open references/quickstart.md。
First decide on the authentication method. When a valid COOKIES already exists, directly use --cookie or --env-file. When there is no login state, run xhs_full_cli.py login for QR code login. QR code login will automatically bootstrap an anonymous-state cookie, generate a terminal QR code and a local PNG image, and save the successful session locally to cookies.json. When you need to manually capture cookies, view QR code login details, or troubleshoot login failures, open references/quickstart.md and references/troubleshooting.md。

Choose the entry script according to the task. scripts/xhs_full_cli.py: unified entry point, preferred for general tasks such as login, status checks, users, comments, messages, home page, creators, and watermark-free links. scripts/search_notes.py: only performs note search. scripts/fetch_note_texts.py: extracts titles, body text, and image links, or downloads watermark-free images. scripts/export_notes.py: exports Excel and media files.
Follow the default media download policy. Once the user explicitly requests downloading images, videos, or media packages, use watermark-free links by default. Only use the original media address when the user explicitly requests keeping the original links or the watermarked version.
Control the output method. For interfaces with large return volumes, prefer using --out to write files. When batch export is needed, prefer using export_notes.py. When more reliable scraping is needed, keep the throttling and retry parameters of fetch_note_texts.py .

references/quickstart.md Open when you need installation, authentication, common commands, CLI subcommands, or validation commands.
references/troubleshooting.md Open when encountering risk control, expired login, empty results, API exceptions, or environment issues.
scripts/xhs_auth.py Responsible for QR code login, local session saving, and QR code image generation.
scripts/xhs_client.py Responsible for signed requests, cookie handling, and unified API request encapsulation.
assets/js/ Stores offline signing and the JS resources needed for running. Do not delete assets/js/vendor/crypto-js.js。

Do not depend on the original repository's Spider_XHS runtime modules.
Do not leak cookies, session files, or screenshots into chats, logs, or Git repositories.
Do not treat the system Python as the default interpreter unless you have confirmed the environment is compatible.
Do not switch to a watermarked media path without explanation.