Herramienta de análisis de comentarios de Xiaohongshu (XHS Comment Analyzer)

Herramienta automatizada de extracción y análisis de comentarios UGC de Xiaohongshu orientada a equipos de marketing de marca. Admite buscar notas por combinación de palabra de marca + palabra de categoría, extraer comentarios por lotes (incluyendo subcomentarios), análisis tridimensional de palabras clave / sentimiento / popularidad, y exportar informes en formato Excel+JSON. Se ejecuta como un MCP Server y puede ser llamado directamente por clientes de IA como TRAE / Claude / Cursor, también admite ejecución independiente mediante CLI.

Capacidades principales

• Búsqueda automática de notas: busca por combinación de palabra de marca + palabra de categoría, carga automáticamente desplazándose, filtra inteligentemente contenido irrelevante

• Extracción de comentarios por lotes: abre la página de detalles de cada nota una por una, extrae información completa de comentarios principales y subcomentarios, admite reanudación de pausa

• Motor de análisis tridimensional: extracción de palabras clave con jieba+TF-IDF, clasificación de sentimiento mediante diccionario + reglas, puntuación de popularidad basada en interacciones × decaimiento temporal

• Exportación de informes en doble formato: informe Excel de 5 hojas + datos JSON estructurados

• Integración con flujo de trabajo de IA: el MCP Server expone 4 herramientas, admite impulso de todo el proceso mediante lenguaje natural

Related MCP server: Xiaohongshu (RedBook) MCP Server

Inicio rápido

Instalación

pip install -e .
playwright install chromium

Ejecutar pruebas

python -m pytest tests/ -v

Uso CLI

# 首次使用：检查登录状态（会打开浏览器，手动完成登录）
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

Configuración MCP

En la configuración MCP de TRAE / Claude / Cursor, añada:

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

Una vez configurado, el cliente de IA puede llamar mediante lenguaje natural: "Ayúdame a buscar comentarios de electrodomésticos pequeños de Bear Electric y generar un informe de análisis".

Lista de herramientas MCP

Estructura del proyecto

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

Formato de salida

Informe Excel (5 hojas)

Informe JSON

Datos completos estructurados, que incluyen configuración de la tarea, resumen estadístico, lista de palabras clave, lista completa de comentarios y rutas de archivos, facilitando el consumo secundario por parte de programas.

Algoritmos principales

Extracción de palabras clave (jieba + TF-IDF)

Cada comentario se trata como un documento independiente. Después de la segmentación con jieba, se filtran palabras vacías y caracteres individuales, se calcula el peso TF-IDF (suavizado estilo sklearn), y se devuelven las 10 palabras clave principales junto con su proporción. Un diccionario integrado de electrodomésticos pequeños (69 términos) evita que las palabras compuestas se dividan.

Análisis de sentimiento (diccionario + reglas)

Basado en diccionarios de sentimiento positivo/negativo + inversión de negación (ventana de 2 palabras anteriores, admite doble negación) + ponderación de adverbios de grado ("muy" ×1.5, "especialmente" ×2.0, etc.), normalizado al intervalo [-1, 1], mapeado a etiquetas positivo/negativo/neutral.

Puntuación de popularidad (interacciones × decaimiento temporal)

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

El peso de respuestas es el más alto (3), porque las respuestas indican discusión profunda; le siguen los me gusta (2); los subcomentarios tienen el peso más bajo (1). Decae un 5% cada día, asegurando que los comentarios recientes con alta interacción aparezcan primero.

Diseño de seguridad

• No elude la verificación: la herramienta no completa nombre de usuario/contraseña, no simula escaneo de códigos, no maneja códigos de verificación automáticamente

• Intervención manual prioritaria: todas las operaciones de inicio de sesión y verificación de códigos las realiza el usuario en una ventana visible del navegador

• Navegador visible: siempre se usa headless=False, el usuario puede ver e intervenir en cualquier momento

• Alerta de riesgo: se detiene automáticamente después de encontrar un código de verificación 3 veces consecutivas, evitando activar controles de riesgo

• Reanudación de pausa: admite reanudar después de interrupción, el progreso se guarda en progress.json

• Persistencia de cookies: el estado de inicio de sesión se guarda en xhs_cookies.json, evitando inicios de sesión frecuentes

Stack tecnológico

Documentación del producto

La documentación completa e interactiva del producto se encuentra en docs/xhs-product-doc.html, ábrala con un navegador. La documentación contiene 9 capítulos:

1. Resumen del producto

2. Documento de requisitos del producto (PRD)

3. Arquitectura del sistema

4. Flujo de trabajo

5. Algoritmos principales

6. Seguridad y antidetección

7. Modelo de datos

8. Interfaz MCP

9. Guía de uso

Datos de ejemplo

El directorio data/output/ contiene una salida de ejemplo de una ejecución real (categoría de electrodomésticos pequeños de Bear Electric), que puede servir como referencia:

• Número de notas: 8 (después de filtrar)

• Número de comentarios: 58 (incluyendo subcomentarios)

• Distribución de sentimiento: positivo 22.4%, negativo 10.3%, neutral 67.2%

• Palabras clave: Bear, gusta, vaporera

Configuración y variables de entorno

• La herramienta no requiere ninguna variable de entorno ni clave para funcionar de forma predeterminada; todo el inicio de sesión se realiza manualmente en un navegador visible, las cookies se persisten en data/cookies/.

• Si en el futuro se integran servicios externos (proxy, clave API, etc.), escriba la configuración en el archivo .env (ignorado por .gitignore) y consulte la plantilla .env.example. No envíe claves reales.

• Los siguientes directorios/archivos están excluidos por .gitignore y no entrarán en el repositorio: data/cookies/*.json (estado de inicio de sesión), data/output/* (productos de extracción), data/progress.json, data/error.log, .env, etc.

Descripción de directorios y archivos

Licencia

Este proyecto se publica bajo la licencia MIT. Consulte el archivo LICENSE (si no se proporciona, puede contactar al autor para obtenerlo).