SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsxhs-business-validator

xhs-business-validator

Coding & development

View repository

Updated 10-15 23:59

About this skill

Xiaohongshu Business Idea Validator

Your Task

The user provides a business idea (e.g., "selling dried tangerine peel in Shenzhen"), and you need to complete 4 steps:

  1. Search Xiaohongshu notes — Call the TikHub API to search for related notes
  2. Fetch comments — Fetch comments for high-engagement notes
  3. AI analysis — Interpret notes and comments, extract pain points and market signals, and generate a comprehensive score
  4. Generate report — Save an HTML report and give the user a summary

⚠️ API Credential Management (Important: never hardcode any keys within the skill)

This skill is publicly exposed,SKILL.md must not contain any real keys / tokens. All credentials are provided by the user at runtime and saved to the user's local .env, and .env must be .gitignore ignored, andnever packaged into the publicly released skill package。

TikHub Token (required)

  • Purpose: Search notes, fetch comments — without it, Xiaohongshu data cannot be pulled.
  • Obtaining: The user registers on TikHub (https://tikhub.io) and creates an API Token.
  • Reading: Read from the skill working directory's .env read TIKHUB_TOKEN。
  • First-Run Flow (must be executed)：
    1. Check whether the working directory contains .env and whether it contains a non-empty TIKHUB_TOKEN。
    2. If it does not exist, ask the user using this prompt:"This skill requires a TikHub API Token to search Xiaohongshu data. Please obtain one from the TikHub backend and paste it to me (it will only be saved in your local .env, will not be shared externally, and will not be written into the skill files)."
    3. Once received, write it to .env：TIKHUB_TOKEN=<用户提供的值>, and remind the user to confirm that .env has been added to .gitignore。
    4. Afterwards, runs will read it directly and will not ask again.
  • If the user refuses to provide it, clearly inform them that you cannot continue, and stop execution.

LLM API (optional, only needed for "full mode + large number of comments")

  • Purpose: Only when the user selects "full mode" and the comment volume is relatively large (e.g., > 50 comments),optionallyuse it to delegate structured extraction and scoring of large numbers of notes/comments to an external model, reducing context pressure.
  • Quick mode does not require an LLM— simply use your (the agent's) own analysis capabilities to complete step 3, with no external requests at all.
  • This API is the user's secret,never hardcode it, and never let it appear in SKILL.md; also do not proactively ask for it unless the trigger conditions above are met.
  • Reading: If the user provides it, read from .env read OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL(compatible with the OpenAI interface).
  • Trigger timing for asking: Only when the user selects "Full Mode" and you judge that the comment volume is large and external model assistance is genuinely needed, ask the user whether to provide an LLM API; if the user does not provide one, continue with the built-in analysis (its capabilities are sufficient to cover most scenarios).
  • Security Red Lines：
    • Any real key may only exist locally on the user's machine .env, and must never be committed to a repository or packaged into a publicly released skill.
    • Do not echo the full key back to the user; if confirmation is truly needed, show only the first 4 characters.
  • .env Template (only this empty template goes into the release package, with no real values): 
    # TikHub（必需）
TIKHUB_TOKEN=
# 可选 LLM（仅完整模式大量评论时需要；OpenAI 兼容接口）
OPENAI_API_KEY=
OPENAI_BASE_URL=
OPENAI_MODEL=

Working Directory

  • The runtime working directory (the current workspace). Data artifacts are saved to data/, reports are saved to reports/, and credentials are saved to .env, all within the working directory.

TikHub API Endpoints

Search notes:

GET https://api.tikhub.io/api/v1/xiaohongshu/app_v2/search_notes
  ?keyword={URL编码关键词}&page={页码}&sort=general&noteType=_0
Headers: Authorization: Bearer {TIKHUB_TOKEN}

Get comments:

GET https://api.tikhub.io/api/v1/xiaohongshu/app_v2/get_note_comments
  ?note_id={笔记ID}
Headers: Authorization: Bearer {TIKHUB_TOKEN}

Note: the comments endpoint is quite sensitive to the requester's User-Agent , and using the Python urllib default UA may result in a 403; it is recommended to use curl or explicitly set a browser UA when making requests.

Note Data Structure (Key Fields)

Extract from items[].note :

  • id — Note ID (used to fetch comments)
  • title — Title
  • desc — Description/Content
  • time — Publish timestamp (milliseconds)
  • liked_count / collected_count / shared_count / comments_count — Engagement data
  • user.nickname — Author nickname

Comment Data Structure (Key Fields)

Extract from data.data.comments[] :

  • content — Comment content
  • like_count — Like count
  • ip_location — IP location (e.g. "Zhejiang")
  • user.nickname — User nickname
  • sub_comment_count / sub_comments[] — Sub-comments

Key Details for Calling the LLM API (only when using the optional LLM)

When sending an analysis request to the LLM, note the following two points:

1. JSON must use ensure_ascii=True(escaped Chinese)

# 错误：curl 会收到 "Invalid JSON"
curl -d '{"content": "中文"}'

# 正确：中文转义为 \uXXXX
python3 -c "import json; print(json.dumps({'content': '中文'}, ensure_ascii=True))"
# 输出: {"content": "\u4e2d\u6587"}

2. Complex analysis requests require a 120s timeout

curl --max-time 120 "..."

3. The response content may be wrapped in a markdown code block

// LLM 可能返回 ```json {...} ```，需要解析

Workflow

Step 0: Credential Preparation (required on first run)

  1. Read the working directory .env：
    • If there is no TIKHUB_TOKEN or it is empty → request it from the user and write it in according to the "TikHub Token First-Run Process" above.
    • If it is already "Full Mode" and the comment volume is expected to be large → decide whether to request LLM credentials from the user according to the "LLM API Trigger Timing" above (the built-in analysis is fully usable even without requesting them).
  2. Proceed to Step 1 only after confirming the TikHub Token is usable.

Step 1: Search Notes

Quick Mode(the user wants to see results quickly): search 1 page, take the first 5 notes Full Mode(default): search 2 pages, take the first 20 notes

Search with curl, then use Python or manually parse the JSON to extract the note list. For each note, calculate an engagement score for sorting:

# 互动评分 = 点赞 + 收藏×2 + 分享×3 + 评论×3
engagement = liked_count + collected_count * 2 + shared_count * 3 + comments_count * 3

Step 2: Fetch Comments

Sort by engagement score from high to low, and fetch comments for the top N notes. Leave at least 1 second between requests (to avoid rate limiting).

Call the comments endpoint with curl, and extract each comment's content and other fields.

Step 3: AI Analysis

This is the core step.By default, use your (the agent's) own analytical capabilities to complete this, no external LLM is needed. Only when the conditions of "full mode + large comment volume + user has provided LLM credentials" are met may you choose to hand off structured extraction to an external model.

Complete the following 3 subtasks:

3a. Single note analysis — For each note + comments, determine whether it is relevant to the business idea, and extract:

  • User pain points (pain_points)
  • Mentioned solutions (solutions_mentioned)
  • Market signals (market_signals)
  • User insights (user_insights, from comments)
  • Sentiment (sentiment: positive/negative/neutral)

3b. Comprehensive analysis — Aggregate all relevant notes and generate:

  • Comprehensive score (0-100): based on market demand, competition, user feedback, activity level, content quality
    • 80-100: 🟢 Huge market opportunity
    • 60-79: 🟡 Certain market potential
    • 40-59: 🟠 Needs further validation
    • 0-39: 🔴 Relatively high market risk
  • Market validation summary
  • Key pain points, existing solutions, market opportunities, recommendations

3c. Comment tag analysis — Classify comments using the four-dimension tag system:

  • Audience and scenario: who is discussing in what scenario
  • Functional value: product feature requirements
  • Assurance value: trust, safety, after-sales service
  • Experience value: emotion, aesthetics, experience

3d. User personas — Generate 3-5 typical user personas (gender, age, needs, motivations)

Step 4: Generate report

Generate a self-contained HTML file, save it to the reports/ directory, containing:

  • Comprehensive score (with color)
  • Statistics metrics grid (number of notes analyzed, number of relevant notes, average engagement score)
  • Market validation summary
  • Key pain points, solutions, market opportunities, recommendations
  • Top 3 popular notes (with engagement data)
  • Comment tag analysis
  • User personas
  • Metadata (generation time, data source)

Report file naming:reports/{业务创意}_{时间戳}.html

Notes

Rate limits

  • TikHub API: QPS 10/second, at least 1 second between each request
  • LLM API (optional): complex analysis requests may be slow (30-120s), set --max-time 120

Technical details

  • When sending JSON to the LLM, use ensure_ascii=True(Chinese escaped as \uXXXX), otherwise it may report "Invalid JSON"
  • LLM responses may be wrapped in markdown code blocks ```json {...} ``` , which need to be parsed and extracted
  • If the LLM returns empty, first check the raw response content; it may be text that does not conform to JSON format
  • The comment API is sensitive to User-Agent , Python urllib default UA may get 403, prefer using curl

Error handling

  • API returns empty → try more specific keywords
  • 401 error → check API Key (prompt the user to provide the Token again)
  • 403 error (comment API) → check the request UA, switch to curl or set a browser UA
  • Timeout → Reduce the data volume, use fast mode

Scoring explanation

Tell the user that the composite score is the result of AI analysis based on multiple dimensions, including:

  • Discussion popularity on Xiaohongshu (engagement data)
  • Pain points and needs expressed by users
  • The degree to which existing solutions satisfy them
  • The size of the market opportunity

How to converse with the user

  • Before starting:
    1. On the first run, confirm the TikHub Token first(see "Credential Management"); if missing, request it and write it to .env。
    2. Ask whether to use fast mode or full mode. Fast mode takes about 1-2 minutes, full mode 5-10 minutes.
    3. If the user chooses full mode and the comment volume is expected to be large, you may also ask whether they need to provide an LLM API (it can run without one too).
  • During execution: report progress (searching/analyzing/generating report)
  • After completion: first give a one-sentence summary (score + judgment), then expand into detailed information
  • If the user asks about the scoring principles: explain the engagement scoring formula and analysis dimensions
  • If the user wants to see the report: find the latest HTML file, read it, and summarize

Example conversation

User: "Help me validate the idea of selling chenpi in Shenzhen" You: "Sure! Let me first confirm the credentials: I detected that there is no TikHub Token locally yet. Could you provide one? (It will only be saved in your .env and will not be shared externally)" User: (provides token) You: "Saved. Fast mode or full mode? Fast mode takes about 1-2 minutes, full mode 5-10 minutes." User: "Fast mode" You: "Okay, starting to search for Xiaohongshu notes on 'selling chenpi in Shenzhen'..." [Execute search → get comments → AI analysis (built-in, no LLM needed) → generate report] "Done! Composite score 72/100 (some market potential 🟡). Key findings: ..."