小红书评论分析工具 (XHS Comment Analyzer)

面向品牌营销团队的小红书 UGC 评论自动化抓取与分析工具，支持按品牌词+品类词搜索笔记、批量提取评论（含子评论）、关键词/情感/热度三维分析，并以 Excel+JSON 双格式导出报告。以 MCP Server 形式运行，可被 TRAE / Claude / Cursor 等 AI 客户端直接调用，也支持 CLI 独立运行。

核心能力

• 自动搜索笔记：按品牌词+品类词组合搜索，自动滚动加载，智能过滤不相关内容
• 批量评论抓取：逐篇打开笔记详情页，提取父评论和子评论完整信息，支持断点续抓
• 三维分析引擎：jieba+TF-IDF 关键词提取、情感词典+规则情感分类、互动量×时效衰减热度评分
• 双格式报告导出：5-Sheet Excel 报告 + 结构化 JSON 数据
• AI 工作流集成：MCP Server 暴露 4 个工具，支持自然语言驱动全流程

快速开始

安装

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 工具列表

工具	功能
run_search_task	按品牌词+品类词批量搜索笔记、抓取评论、分析并导出
scrape_single_note	抓取单篇小红书笔记的评论并分析
analyze_comments	对已抓取的 JSON 文件重新进行关键词/情感/热度分析
check_login_status	检查小红书登录状态

项目结构

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)

Sheet	内容
评论明细	全部评论按热度排序，含笔记标题/URL/评论内容/作者/时间/点赞/回复/情感/热度
分析摘要	抓取笔记数、评论总数、产品相关评论、情感分布统计
关键词 Top10	高频关键词及占比
热门评论 Top10	热度评分最高的 10 条评论
笔记汇总	各笔记的点赞数、评论数、热度总分

JSON 报告

结构化全量数据，包含 task 配置、summary 统计、keywords 列表、comments 完整列表和文件路径，便于程序二次消费。

核心算法

关键词提取 (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%，确保近期高互动评论排在前面。

安全设计

• 不绕过验证：工具不填写账号密码、不模拟扫码、不自动处理验证码
• 人工介入优先：所有登录和验证码操作由人工在可见浏览器窗口中完成
• 可见浏览器：始终使用 headless=False，用户可随时查看和介入
• 风控预警：连续遇到验证码 3 次自动停止，防止触发风控
• 断点续抓：支持中断后恢复，进度保存在 progress.json
• Cookie 持久化：登录态保存到 xhs_cookies.json，避免频繁登录

技术栈

依赖	用途
Python 3.12+	运行时
Playwright	浏览器自动化
MCP SDK	MCP Server 协议
jieba	中文分词
openpyxl	Excel 导出
Pydantic	数据模型校验

产品文档

完整的交互式产品文档位于 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%
• 关键词：小熊、喜欢、蒸笼

配置与环境变量

• 工具默认无需任何环境变量或密钥即可运行；所有登录态以可见浏览器方式由人工完成，Cookie 持久化到 data/cookies/。
• 若后续接入外部服务（代理、API Key 等），请将配置写入 .env 文件（已被 .gitignore 忽略），并参考 .env.example 模板，切勿提交真实密钥。
• 以下目录/文件已被 .gitignore 排除，不会进入版本库：data/cookies/*.json（登录态）、data/output/*（抓取产物）、data/progress.json、data/error.log、.env 等。

目录与文件说明

路径	是否入库	说明
src/	✅	全部源代码
tests/	✅	单元测试
data/dictionaries/	✅	情感/分词词典（文本）
data/cookies/	❌（仅 .gitkeep）	登录 Cookie，敏感
data/output/	❌（仅 .gitkeep）	抓取与分析产物
docs/	✅	产品文档
.env / *.json 密钥	❌	敏感配置

许可证

本项目以 MIT 许可证开源。详见 LICENSE 文件（如未提供，可联系作者获取）。