샤오홍슈 댓글 분석 도구 (XHS Comment Analyzer)

브랜드 마케팅 팀을 위한 샤오홍슈 UGC 댓글 자동 수집 및 분석 도구입니다. 브랜드 키워드 + 카테고리 키워드로 노트를 검색하고, 댓글(하위 댓글 포함)을 일괄 추출하며, 키워드/감성/인기도 3차원 분석을 수행하고, Excel+JSON 이중 형식으로 보고서를 내보냅니다. MCP Server 형태로 실행되어 TRAE / Claude / Cursor 등 AI 클라이언트에서 직접 호출할 수 있으며, CLI 독립 실행도 지원합니다.

핵심 기능

• 자동 노트 검색: 브랜드 키워드+카테고리 키워드 조합으로 검색, 자동 스크롤 로딩, 관련 없는 내용 스마트 필터링

• 일괄 댓글 수집: 노트 상세 페이지를 하나씩 열어 부모 댓글과 하위 댓글의 전체 정보를 추출, 중단 지점부터 이어서 수집 지원

• 3차원 분석 엔진: jieba+TF-IDF 키워드 추출, 감성 사전+규칙 감성 분류, 상호작용량×시간 감쇠 인기도 점수

• 이중 형식 보고서 내보내기: 5-Sheet Excel 보고서 + 구조화된 JSON 데이터

• AI 워크플로우 통합: MCP Server가 4개의 도구를 노출, 자연어로 전체 프로세스 구동 지원

Related MCP server: Xiaohongshu (RedBook) MCP Server

빠른 시작

설치

pip install -e .
playwright install chromium

테스트 실행

python -m pytest tests/ -v

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

MCP 설정

TRAE / Claude / Cursor의 MCP 설정에 다음을 추가:

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

설정이 완료되면 AI 클라이언트가 자연어로 호출 가능: "샤오슝 전기기기 소형가전의 댓글을 검색하고 분석 보고서를 생성해줘."

MCP 도구 목록

프로젝트 구조

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

출력 형식

Excel 보고서 (5개 Sheet)

JSON 보고서

구조화된 전체 데이터로, task 설정, summary 통계, keywords 목록, comments 전체 목록 및 파일 경로를 포함하여 프로그램에서 2차 소비하기 용이합니다.

핵심 알고리즘

키워드 추출 (jieba + TF-IDF)

각 댓글을 독립 문서로 간주, jieba로 형태소 분석 후 불용어 및 단일 문자 단어를 필터링하고 TF-IDF 가중치(sklearn 스타일 평활화)를 계산하여 Top 10 키워드와 비율을 반환합니다. 소형가전 분야 사전(69개 용어)이 내장되어 복합어가 분리되지 않도록 합니다.

감성 분석 (사전 + 규칙)

긍정/부정 감성 사전 + 부정어 반전(앞 2단어 창, 이중 부정 지원) + 정도 부사 가중치("매우"×1.5, "특히"×2.0 등)를 기반으로 [-1, 1] 범위로 정규화하여 긍정/부정/중립 레이블로 매핑합니다.

인기도 점수 (상호작용량 × 시간 감쇠)

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

답글 수 가중치가 가장 높음(3) (답글은 깊이 있는 토론을 의미). 좋아요는 그 다음(2). 하위 댓글은 가장 낮음(1). 매일 5%씩 감쇠하여 최근 높은 상호작용의 댓글이 상위에 오도록 합니다.

보안 설계

• 인증 우회하지 않음: 도구는 계정/비밀번호를 입력하지 않으며, QR 코드를 시뮬레이션하지 않고, 자동으로 캡차를 처리하지 않습니다.

• 수동 개입 우선: 모든 로그인 및 캡차 작업은 사용자가 보이는 브라우저 창에서 직접 수행합니다.

• 보이는 브라우저: 항상 headless=False를 사용하여 사용자가 언제든지 확인 및 개입 가능.

• 리스크 경고: 연속으로 캡차를 3번 만나면 자동 중지, 리스크 트리거 방지.

• 중단 지점부터 이어서 수집: 중단 후 재개 가능, 진행 상황은 progress.json에 저장.

• 쿠키 지속: 로그인 상태를 xhs_cookies.json에 저장하여 빈번한 로그인 방지.

기술 스택

제품 문서

전체 대화형 제품 문서는 docs/xhs-product-doc.html에 있으며, 브라우저로 열어서 확인할 수 있습니다. 문서는 9개 장으로 구성:

1. 제품 개요

2. 제품 요구 사항 문서 (PRD)

3. 시스템 아키텍처

4. 워크플로우

5. 핵심 알고리즘

6. 보안 및 안티 디텍션

7. 데이터 모델

8. MCP 인터페이스

9. 사용 가이드

예시 데이터

data/output/ 디렉토리에 실제 실행 예시 출력(샤오슝 전기기기 소형가전 카테고리)이 포함되어 있으며, 참고용으로 사용 가능:

• 노트 수: 8편 (필터링 후)

• 댓글 수: 58개 (하위 댓글 포함)

• 감성 분포: 긍정 22.4%, 부정 10.3%, 중립 67.2%

• 키워드: 샤오슝, 좋아, 찜기

설정 및 환경 변수

• 도구는 기본적으로 어떠한 환경 변수나 API 키도 필요하지 않음; 모든 로그인 상태는 보이는 브라우저 방식으로 수동 완료, 쿠키는 data/cookies/에 지속 저장.

• 향후 외부 서비스(프록시, API Key 등)를 연동할 경우 .env 파일(.gitignore에 의해 무시됨)에 설정을 작성하고 .env.example 템플릿을 참고하며, 실제 키를 커밋하지 마십시오.

• 다음 디렉토리/파일은 .gitignore에 의해 제외되어 버전 관리에 포함되지 않습니다: data/cookies/*.json(로그인 상태), data/output/*(수집 산출물), data/progress.json, data/error.log, .env 등.

디렉토리 및 파일 설명

라이선스

이 프로젝트는 MIT 라이선스로 오픈소스입니다. 자세한 내용은 LICENSE 파일을 참조하세요 (제공되지 않은 경우 저자에게 문의하여 확인 가능).