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

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

## 核心能力

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

## 快速开始

### 安装

```bash
pip install -e .
playwright install chromium
```

### 运行测试

```bash
python -m pytest tests/ -v
```

### CLI 使用

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

```json
{
    "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` 文件（如未提供，可联系作者获取）。