When you need to execute the complete decision rules, dialogue branches, and script details,you must first readin the same directory references/core_workflow.md and strictly follow the paths and step instructions therein.
Introduction
Aimed at brand seeding, MCN talent scouting, self-media creation, and content operations Xiaohongshu viral intelligence tool: replace "finding benchmarks by gut feeling" with reproducible data samples, shortening the path from topic selection to validation.
By searching with keywords and time windows, you can:
- 🔍 Scaled discovery: 2,000+ viral samples meeting the collection dimensions updated daily, reducing the cost of manually scraping rankings
- 🎯 Weaken head bias: combine dimensions such as low-follower viral hits, periodic high-likes, single-day interaction increments, and sustained growth to improve benchmark referenceability
- 📊 Ready-to-use delivery: structured summaries + visualized HTML, convenient for internal sharing, proposals, and reviews
Technical foundation：Python 3.8+、requests; data comes from Xiaohongshu public content aggregation interfaces (for specific fields and filtering logic, see references/core_workflow.md）。
Features
🎯 Core Features
- 📊 Multi-dimensional viral filtering: standard combinations such as low-follower viral hits, periodic high-likes, single-day outbreaks, and sustained growth, reducing misjudgments caused by "weak replicability of big accounts"
- 🏷️ Track alignment: supports 25 mainstream content categories, making it easy to narrow samples by vertical domain
- 🤖 Intent tiering: distinguishes general browsing, explicit needs, and data-oriented demands, matching output granularity and ranking emphasis
- 💡 Recommendation reason generation: generates non-templated explanations combining intent and interaction performance, with each reason no less than 15 characters (see workflow for rules)
✨ Highlights
- ⏰ Flexible time windows: supports the last 1 / 3 / 7 / 30 days; when samples are insufficient, automatically expands the interval according to the workflow and clearly indicates it
- 📤 Dual-form output: Markdown cards + local HTML files, convenient for preview, archiving, and secondary editing
- 🔗 Sub-keyword expansion: after identifying generalized keywords, provides about 10 sub-directions,executes only after user confirmationsearch, reducing invalid requests
- ⚡ Low integration cost: no Xiaohongshu account or API Key required; runs with configured dependencies and an optional proxy (compliant use is your own responsibility)
Usage Guide
Environment and dependencies (before installation)
- Install Python 3.8+, ensuring the terminal can execute
python。 - Enter the project root directory and install dependencies:
pip install requests>=2.28.0
- (Optional) Configure environment variables:
| Variable name | Required | Description |
|---|---|---|
XHS_API_PROXY |
No | Proxy address, example:http://127.0.0.1:7890 |
OUTPUT_PATH |
No | Generated .html save directory; defaults to the script's current working directory |
Basic usage (execution order)
Step 1: Align parameters
The user should provide track keywords(may be empty to indicate site-wide trending) and start date(format consistent with the workflow). If expressed verbally as "yesterday / the past week", etc., map it to a specific date according to references/core_workflow.md .
User: Check what low-follower viral hits related to "workplace outfits" in the past 7 days can be used as references. Assistant: Confirm keywords and date range → read
references/core_workflow.md→ run the script → provide a TOP summary and key patterns, and inform the HTML path.
If the user only says "check Xiaohongshu viral hits":Ask follow-up questions aboutkeywords (or whether it is site-wide), the date, and the dimensions of interest (for example, whether low-follower or trending is more important); do not assume the track without authorization.
Step 2: Run the script
Execute in the project root directory (just copy and replace the parameter placeholders):
# 有赛道关键词
python scripts/fetch_xhs_trends.py --keyword <关键词> --start-date <日期>
# 无赛道关键词（全站热门）
python scripts/fetch_xhs_trends.py --keyword "" --start-date <日期>
# 多个关键词（英文逗号分隔）
python scripts/fetch_xhs_trends.py --keyword "减脂餐,职场穿搭,健身" --start-date <日期>
Step 3: Delivery and expansion
- Default output file：
{keyword}_爆款数据.html(keyword rules are subject to the script and workflow). - When the user needs deeper breakdown (title formulas, topic clusters, competitor comparison): continue asking follow-up questions based on the existing ranking,and do not fabricate engagement data or rankings detached from the script results。
Common commands quick reference
| Example user wording | Assistant action |
|---|---|
| Check [date] [keyword] viral hits / benchmarks | Confirm parameters → run the script → summary + HTML path |
| Don't know what term to search | Use broad-term expansion → list subcategories → retrieve after the user selects |
| Want to see site-wide trending | --keyword "" + specify --start-date |
| Compare multiple tracks together | Comma-separated --keyword, output follows the workflow description |
When it fails or cannot be executed
- Missing parameters: Clearly list the missing items and ask the user to complete them; do not guess dates and keywords.
- Dependency or network failure: Explain the type of error (installation, timeout, proxy) and give suggestions for retrying or configuring
XHS_API_PROXY. - Data is empty or the interface is unavailable: Inform truthfully; fabricating note titles, links, and engagement numbers is prohibited.
Use cases
| Scenario | Role | Requirement description | How to use |
|---|---|---|---|
| Topic selection for cold start of a new account | Self-media creator | Has few followers and needs viral content samples that "accounts at the same level" can replicate | Pull rankings by track keywords + the past 7 to 30 days; prioritize the low-follower dimension; extract titles and topic clusters |
| Brand campaign seeding | Brand Xiaohongshu operator | Needs hot topics and format references with a sufficient evidence chain before the campaign | Search by category keywords; export HTML for internal review; align with the content paradigm in the influencer brief |
| Account screening before signing and incubation | MCN content scout | Wants the content trajectory of accounts with high engagement potential rather than a single accidental viral hit | Fixed-window multiple sampling; focus on sustained growth and periodic high likes; output account-level observations (within the scope allowed by the workflow) |
| Bidding and Weekly Report | Content Planning / Acting PM | The client needs a one-page conclusion of "trends + samples" | Script results are made into a structured summary; HTML attachment; conclusions strictly correspond to the data window |
Notes and Boundaries
- Data Authenticity: Rankings and figures all come from script pull results; when the API is abnormal or there is no data, state it truthfully,must not fabricateinteraction volume, ranking, and note metadata.
- Compliance and Privacy: Comply with platform community guidelines and local laws; do not encourage rule-violating traffic diversion; when displaying external links and body text excerpts, follow the desensitization and citation boundaries in the workflow.
- Capability Boundaries: Capabilities such as push subscriptions and PDF exportonly when actually implementedare promised; the default deliverables of this repository are script + HTML / Markdown, see
references/core_workflow.md。 - Executing Entity: The complete process is executed only by the main Agent, to avoid sub-agents making duplicate requests or bypassing the unified validation logic.