Xiaohongshu-Kommentaranalyse-Tool (XHS Comment Analyzer)

Automatisiertes Tool zum Abrufen und Analysieren von UGC-Kommentaren auf Xiaohongshu, entwickelt für Markenmarketing-Teams. Es unterstützt die Suche nach Notizen nach Marken- und Kategoriebegriffen, das Extrahieren von Kommentaren (einschließlich Unterkommentaren) in großen Mengen, die dreidimensionale Analyse (Schlüsselwörter, Stimmung, Beliebtheit) und die Ausgabe von Berichten im Excel- und JSON-Format. Es läuft als MCP-Server und kann direkt von KI-Clients wie TRAE/Claude/Cursor aufgerufen werden, unterstützt aber auch den eigenständigen Betrieb über die CLI.

Kernfunktionen

• Automatische Notizensuche: Suche nach Kombinationen aus Marken- und Kategoriebegriffen, automatisches Scrollen und Laden, intelligente Filterung irrelevanter Inhalte.

• Batch-Kommentarerfassung: Öffnen Sie jede Notizdetailseite nacheinander, extrahieren Sie vollständige Informationen zu übergeordneten und untergeordneten Kommentaren, unterstützt unterbrechungsfreies Fortsetzen des Abrufs.

• Dreidimensionale Analyse-Engine: Schlüsselwortextraktion mit jieba+TF-IDF, Stimmungsklassifizierung basierend auf Wörterbuch und Regeln, Bewertung der Beliebtheit basierend auf Interaktionsrate × zeitlichem Abklingen.

• Berichtexport im Doppelformat: 5-Blatt-Excel-Bericht + strukturierte JSON-Daten.

• Integration in KI-Workflows: Der MCP-Server stellt 4 Tools bereit und unterstützt die natürliche Sprachsteuerung des gesamten Prozesses.

Related MCP server: Xiaohongshu (RedBook) MCP Server

Schnellstart

Installation

pip install -e .
playwright install chromium

Testlauf

python -m pytest tests/ -v

CLI-Nutzung

# 首次使用：检查登录状态（会打开浏览器，手动完成登录）
python run.py login

# 搜索并抓取评论（使用预设配置）
python run.py search

# 抓取单篇笔记评论
python run.py single "https://www.xiaohongshu.com/search_result/xxx?xsec_token=yyy"

# 对已有 JSON 重新分析
python run.py analyze data/output/report.json

MCP-Konfiguration

Fügen Sie in der MCP-Konfiguration von TRAE/Claude/Cursor Folgendes hinzu:

{
    "mcpServers": {
        "xhs-comment-analyzer": {
            "command": "python",
            "args": ["-m", "src.mcp_server"],
            "cwd": "/path/to/xhs-comment-analyzer-package"
        }
    }
}

Nach der Konfiguration kann der KI-Client über natürliche Sprache aufgerufen werden: „Hilf mir, Kommentare zu Xiaoxiong Electric Appliance Small Appliances zu suchen und einen Analysebericht zu erstellen.“

MCP-Tool-Liste

Projektstruktur

xhs-comment-analyzer-package/
├── src/                                # 源代码
│   ├── scraper/                        # 抓取层
│   │   ├── browser.py                  # Playwright 浏览器管理 (登录态持久化、反检测)
│   │   ├── comment_scraper.py          # 评论抓取核心 (搜索/单篇/批量/断点续抓)
│   │   └── models.py                   # 数据模型 (7 个 Pydantic 模型)
│   ├── analyzer/                       # 分析层
│   │   ├── keywords.py                 # 关键词提取 (jieba + TF-IDF)
│   │   ├── sentiment.py                # 情感分类 (词典 + 规则)
│   │   └── heat.py                     # 热度评分 (互动量 × 时效衰减)
│   ├── exporter/
│   │   └── excel_exporter.py           # 导出 Excel (5 Sheet) + JSON
│   └── mcp_server.py                   # MCP Server (4 个工具)
├── tests/                              # 单元测试 (38 个用例)
├── data/
│   ├── cookies/                        # 登录 cookie 持久化
│   ├── dictionaries/                   # 自定义词典
│   │   ├── domain_words.txt            # 领域词典 (69 个小家电术语)
│   │   ├── stopwords.txt               # 停用词表
│   │   ├── positive_words.txt          # 正面情感词
│   │   ├── negative_words.txt          # 负面情感词
│   │   ├── negation_words.txt          # 否定词
│   │   └── degree_adverbs.txt          # 程度副词 (词<TAB>权重)
│   └── output/                         # 导出文件 (Excel/JSON)
├── docs/                               # 产品文档
│   └── xhs-product-doc.html            # 完整产品文档 (PRD/架构/工作流/算法/接口)
├── run.py                              # CLI 入口 (login/search/single/analyze)
├── conftest.py                         # pytest 配置
├── pyproject.toml                      # 依赖管理
├── .gitignore
└── README.md

Ausgabeformat

Excel-Bericht (5 Blätter)

JSON-Bericht

Strukturierte vollständige Daten, einschließlich Aufgabenkonfiguration, Zusammenfassungsstatistiken, Schlüsselwortliste, vollständige Kommentarliste und Dateipfade, für die weitere maschinelle Verarbeitung.

Kernalgorithmen

Schlüsselwortextraktion (jieba + TF-IDF)

Jeder Kommentar wird als separates Dokument behandelt. Nach der Tokenisierung mit jieba werden Stoppwörter und einstellige Zeichen gefiltert. Die TF-IDF-Gewichtung (sklearn-artige Glättung) wird berechnet, um die Top 10 Schlüsselwörter und deren Anteil zurückzugeben. Ein integriertes Wörterbuch für den Bereich Kleinhaustechnik (69 Fachbegriffe) stellt sicher, dass zusammengesetzte Wörter nicht getrennt werden.

Stimmungsanalyse (Wörterbuch + Regeln)

Basierend auf einem positiven/negativen Stimmungswörterbuch + Negationsumkehrung (Fenster der vorherigen 2 Wörter, unterstützt doppelte Verneinung) + Gewichtung durch Gradadverbien („sehr“ ×1,5, „besonders“ ×2,0 usw.), normalisiert auf das Intervall [-1, 1], abgebildet auf die Labels positiv/negativ/neutral.

Beliebtheitsbewertung (Interaktionsrate × zeitliches Abklingen)

base_score = like_count × 2 + reply_count × 3 + sub_comment_count × 1
time_decay = 0.95 ^ days_ago
heat_score = (base_score × time_decay / max_raw_heat) × 100

Die Gewichtung der Antworten ist am höchsten (3), weil Antworten für tiefgehende Diskussionen stehen; Likes sind zweitwichtigster (2); Unterkommentare haben die niedrigste Gewichtung (1). Täglicher Abklingfaktor von 5 %, um sicherzustellen, dass aktuelle, stark interagierte Kommentare höher eingestuft werden.

Sicherheitsdesign

• Keine Umgehung der Verifizierung: Das Tool gibt keine Kontodaten ein, simuliert keine QR-Code-Scans und verarbeitet keine Captchas automatisch.

• Priorität menschlicher Eingriff: Alle Anmelde- und Captcha-Vorgänge werden manuell im sichtbaren Browserfenster durchgeführt.

• Sichtbarer Browser: Stets headless=False verwendet, der Benutzer kann jederzeit einsehen und eingreifen.

• Risikowarnung: Nach 3 aufeinanderfolgenden Captchas wird automatisch gestoppt, um Risikokontrollen zu vermeiden.

• Unterbrechungsfreies Fortsetzen: Unterstützt das Fortsetzen nach Unterbrechung, der Fortschritt wird in progress.json gespeichert.

• Cookie-Persistenz: Der Anmeldestatus wird in xhs_cookies.json gespeichert, um häufige Anmeldungen zu vermeiden.

Technologie-Stack

Produktdokumentation

Die vollständige interaktive Produktdokumentation befindet sich in docs/xhs-product-doc.html und kann im Browser geöffnet werden. Das Dokument umfasst 9 Kapitel:

1. Produktübersicht

2. Produktanforderungsdokument (PRD)

3. Systemarchitektur

4. Arbeitsablauf

5. Kernalgorithmen

6. Sicherheit und Anti-Erkennung

7. Datenmodell

8. MCP-Schnittstelle

9. Benutzerhandbuch

Beispieldaten

Das Verzeichnis data/output/ enthält eine Beispielausgabe eines tatsächlichen Durchlaufs (Kategorie Xiaoxiong Electric Appliance Small Appliances), die als Referenz dienen kann:

• Anzahl Notizen: 8 (nach Filterung)

• Anzahl Kommentare: 58 (einschließlich Unterkommentare)

• Stimmungsverteilung: positiv 22,4 %, negativ 10,3 %, neutral 67,2 %

• Schlüsselwörter: Xiaoxiong, mögen, Dampfgarer

Konfiguration und Umgebungsvariablen

• Das Tool läuft standardmäßig ohne Umgebungsvariablen oder Schlüssel; die Anmeldung erfolgt manuell im sichtbaren Browser, und Cookies werden in data/cookies/ persistiert.

• Wenn später externe Dienste (Proxy, API-Schlüssel usw.) angebunden werden, schreiben Sie die Konfiguration in die .env-Datei (die von .gitignore ignoriert wird) und beziehen Sie sich auf die Vorlage .env.example. Geben Sie keine echten Schlüssel preis.

• Die folgenden Verzeichnisse/Dateien werden von .gitignore ausgeschlossen und gelangen nicht in die Versionskontrolle: data/cookies/*.json (Anmeldestatus), data/output/* (Abrufergebnisse), data/progress.json, data/error.log, .env usw.

Verzeichnis- und Dateierklärung

Lizenz

Dieses Projekt ist unter der MIT-Lizenz Open Source. Weitere Informationen finden Sie in der Datei LICENSE (falls nicht vorhanden, kontaktieren Sie den Autor für eine Kopie).