xiaohongshu-viral-note-agent-skill

# Tool List **Xiaohongshu Viral Note Agent Skill** [中文](#) | [English](README_EN.md) [](LICENSE) [](https://www.python.org/) [](https://modelcontextprotocol.io/) --- ## What is this As a professional with five years of experience in operating Xiaohongshu content, I have managed accounts across multiple categories including digital products, software, education, beauty, parenting, home, and local life. Over the past five years, I have repeatedly performed tasks such as browsing popular content for topic inspiration, dissecting the structure of viral posts, writing copy, refining content to eliminate AI-like tone, monitoring data for insights, and planning the next post. These experiences have become ingrained as muscle memory – what title mechanisms tend to go viral, what narrative frameworks are suitable for promoting products, what timing yields the best traffic, and how to recover from a dropped account weight. Last year, I began using AI to assist in content production and discovered a problem: **AI can write but lacks understanding of Xiaohongshu**. General large models either produce overly formal content, fabricate data, or violate compliance regulations. Therefore, I integrated five years of operational methodology with AI engineering capabilities to create this Skill – **a one-stop solution covering the entire process of Xiaohongshu operation from topic research, content generation, compliance verification, account analysis, QR code login, one-click publishing, to post-publishing review**. > **The goal is not to replace human creators with AI but to teach AI using your operational experience and methodology, enabling it to conduct research, generate content, and verify compliance according to your standards, while you focus on reviewing and publishing**. This solution includes 49 MCP tools covering the complete cycle from topic selection to post-review. It is compatible with Cursor, Claude, or any AI Agent. **Our vision is simple: to make Xiaohongshu content creation easier, lower the writing threshold, and enable everyone to become a Xiaohongshu viral note creator**. No five years of operational experience or AI engineering knowledge is required; just install and use. --- ## Product Showcase <p align="center"> <img src="assets/screenshots/screenshot-1.png" width="80%" alt="Product Screenshot 1"><br><br> <img src="assets/screenshots/screenshot-2.png" width="80%" alt="Product Screenshot 2"><br><br> <img src="assets/screenshots/screenshot-3.png" width="80%" alt="Product Screenshot 3"><br><br> <img src="assets/screenshots/screenshot-4.png" width="80%" alt="Product Screenshot 4"><br><br> <img src="assets/screenshots/screenshot-5.png" width="80%" alt="Product Screenshot 5"><br><br> <img src="assets/screenshots/screenshot-6.png" width="80%" alt="Product Screenshot 6"><br><br> <img src="assets/screenshots/screenshot-7.png" width="80%" alt="Product Screenshot 7"> </p> --- ## What problems does it solve | Problems You Encounter | How It Helps | |---|---| | Finding topics relies on intuition, and browsing popular content for hours doesn't yield ideas | Crawls public popular data, automatically analyzes trending topics, rising words, and content gaps, providing selectable topic lists | | Writing a post takes two hours, and refining AI-like content takes another hour | Generates complete text/image/video delivery packages from topics: titles, cover copy, body, topic tags, and CTAs, with built-in AI-like content refinement | | Pre-publishing anxiety about compliance | Three gate checks: statement verification, originality check, and compliance verification, with automatic blocking if any check fails | | Uncertain about current account status and direction | Imports authorized data, estimates account weight and content health, and recommends topics and note styles based on weaknesses | | Tedious publishing process | Authorized QR code login, draft preview, explicit approval, and automatic publishing, with full control | | Post-publishing analysis | Automatically synchronizes post metrics, attribution analysis, A/B testing, and review suggestions, enabling closed-loop operation | --- ## Get started in 30 seconds ```bash # Installation pip install -e '.[dev]' # Generate content from popular topics xhs-skill generate --topic "commuter sunscreen" --search-provider fixture --output output/package.json # Or use MCP to connect your AI Agent python -m xhs_skill.mcp.server --transport stdio ``` --- ## Core Capabilities ### Research / Topic Selection - Crawls public popular notes, automatically deduplicates, sorts, and categorizes trends - Returns selectable `topic_suggestions`, each with `generate_payload` for one-click generation - `hot_insights`: trending topics, rising words, early velocity signals, content gaps, and title mechanism statistics ### Content Generation - Multiple title/cover/body candidates, sorted by relevance and diversity - Graphic pagination / video scripting (15/30/45/60s templates) - Narrative frameworks: PAS / AIDA / BAB / QUEST / 4P / SCQA - Note types: reviews, product recommendations, warnings, lists, tutorials, store visits, comparisons, decision-making ### Compliance Verification - **Statement ledger**: automatic extraction of objective statements, with unverifiable statements requiring deletion or conversion to subjective ones - **Originality**: multi-dimensional detection including literal, semantic, rare phrases, and image pHash - **Compliance**: checks for extreme words, fabricated experiences, medical/financial commitments, and commercial disclosures - **AI origin**: records and identifies AI-generated or modified content ### Account Analysis - Account weight estimation (non-official score, clearly labeled) - Content health: interaction/collection/rhythm/search/risk multi-dimensional evaluation - Automatic recommendation of `note_style` and topic angles based on weaknesses ### Publishing and Operation - Authorized QR code login, AES-256-GCM encrypted session - Draft preview → explicit approval → publishing, with each step controllable - Post-publishing automatic metric synchronization: attribution analysis, weight trend, content calendar, series planning, A/B/n testing, and LinUCB multi-armed bandit --- ## Tool List (49 MCP Tools) | Group | Tool | Description | |---|---|---| | **Research/Topic Selection** | `search_hot_notes` `search_trending_topics` `analyze_hot_notes` `suggest_topics_by_health` | Popular research and topic suggestions | | **Generation/Rewriting** | `generate_xhs_note` `generate_from_hot` `rewrite_xhs_note` `diagnose_xhs_note` `plan_content_outline` `draft_comment_reply` `generate_xhs_note_variants` | Content generation, rewriting, diagnosis, and comment drafting | | **Compliance Verification** | `verify_claims` `check_originality` `check_compliance` | Statement, originality, and compliance verification | | **Account/Login** | `query_account_weight` `query_content_health` `diagnose_account` `sync_account_analytics` `start_account_login` `check_account_login` `logout_account` | Account analysis and authorized login | | **Publishing Process** | `create_publish_draft` `preview_publish_draft` `approve_publish_draft` `publish_note` `schedule_note` `get_publish_windows` | Drafting, previewing, approving, and publishing | | **Post-Publishing Operation** | `sync_published_metrics` `get_performance_attribution` `get_account_weight_trend` `create_content_calendar` `create_content_series` `create_abn_experiment` `choose_content_bandit` `generate_retrospective` `analyze_performance` | Metric synchronization, attribution, calendar, experimentation, and review | | **Enterprise Management** | `get_enterprise_controls` `get_enterprise_budget` `create_enterprise_approval` `decide_enterprise_approval` `verify_enterprise_audit` `enterprise_dlp_scan` | Tenant policies, budget, approval, audit, and DLP | Full contract: `contracts/mcp-tools.json` --- ## Supported Models | Provider | Compatibility | |---|---| | OpenAI / GPT | Responses API | | Anthropic / Claude | Messages API | | Google / Gemini | Generate Content API | | DeepSeek, Qwen, Ark, GLM, Kimi, MiniMax, Hunyuan, Qianfan | OpenAI-Compatible | | Amazon Bedrock | Converse API | | Azure OpenAI | OpenAI-Compatible | | Self-hosted (vLLM, etc.) | OpenAI-Compatible | Model identifiers are configurable, not hardcoded. See `assets/providers.yaml` for details. --- ## Search Providers | Provider | Description | |---|---| | `client_web` | Web results passed by the host Agent (no API key required) | | `brave` | Brave Search API | | `bing` | Bing Web Search | | `google_cse` | Google Custom Search | | `searxng` | Self-hosted SearxNG | | `openai_web` | OpenAI Web Search | | `fixture` | Offline development deterministic data | If no API key is configured, automatically returns `needs_web_search`, allowing the host Agent to supplement with its own search capabilities. --- ## Quick Start ```bash # 1. Installation python -m venv .venv && source .venv/bin/activate pip install -e '.[dev]' # 2. Configuration cp .env.example .env # Edit .env and fill in your API keys # 3. Required for browser publishing playwright install chromium # 4. Run xhs-skill serve --host 127.0.0.1 --port 8080 # HTTP API python -m xhs_skill.mcp.server --transport stdio # MCP ``` ### CLI Examples ```bash # Search popular content xhs-skill search-hot --query "commuter sunscreen" --provider fixture # Generate content xhs-skill generate --topic "commuter sunscreen" --search-provider fixture # Account analysis xhs-skill account weight --account demo --input examples/account_analytics.json # Publishing process xhs-skill publish draft --account demo --package output/package.json xhs-skill publish preview --draft <draft-id> xhs-skill publish approve --draft <draft-id> xhs-skill publish execute --draft <draft-id> --approval-token <token> ``` --- ## MCP Integration ### Cursor / Claude Desktop ```json { "mcpServers": { "xhs-skill": { "command": "python", "args": ["-m", "xhs_skill.mcp.server", "--transport", "stdio"] } } } ``` ### HTTP Endpoint ```bash POST /mcp ``` ### A2A ```bash GET /.well-known/agent-card.json ``` --- ## Security Boundaries This Skill **does not**: - Bypass CAPTCHA, risk control, or access control - Automate traffic brushing or fake comments - Plagiarize or replicate others' content - Conceal commercial cooperation relationships - Present estimated data as official data Three gate checks are required before publishing: statement verification, originality check, and compliance verification. If any check fails, the process is automatically blocked. --- ## Enterprise Version Supports OIDC / SCIM identity management, tenant isolation, multi-person approval, DLP, audit hash chain, and Vault / KMS key management. ```bash pip install -e '.[enterprise]' ``` --- ## Project Structure ```text ├── SKILL.md # Agent entry (the README protocol you're reading) ├── src/xhs_skill/ # Python source code │ ├── mcp/ # MCP protocol and 49 tools │ ├── research/ # Network research and trend analysis │ ├── generation/ # Content generation and rewriting │ ├── verifiers/ # Compliance, originality, and statement verification │ ├── accounts/ # Account weight and health │ ├── publishing/ # Authorized publishing process │ ├── operations/ # Post-publishing operation and experimentation │ ├── enterprise/ # Enterprise management │ └── ... ├── contracts/ # MCP / OpenAPI / A2A contracts ├── schemas/ # 34 JSON Schemas ├── references/ # Reference documents loaded by the Agent ├── scripts/ # CLI and maintenance scripts ├── tests/ # Tests (unit + contract + integration) └── evals/ # 1750 evaluation data points ``` --- ## Development ```bash pip install -e '.[dev,enterprise,ml,vision]' pytest ruff check . mypy src/xhs_skill scripts ``` --- ## License [MIT](LICENSE) --- <p align="center"> <strong>Let AI handle content research and generation, and you focus on reviewing and publishing.</strong><br> _{Xiaohongshu Viral Note Generation Agent Skill &mdash; From trend research to publishing, all in one go.}<br><br> _{Contact Email: <a href="mailto:contact@xhspro.com">contact@xhspro.com</a>} </p>