Metadata-Version: 2.4
Name: xiaohongshu-search
Version: 0.2.0
Summary: 小红书搜索工具 - 企业级实现
Project-URL: Homepage, https://coding.jd.com/u_py/xiaohongshu_search
Project-URL: Repository, https://coding.jd.com/u_py/xiaohongshu_search.git
Author: 叶浩
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: requests>=2.31.0
Requires-Dist: retrying>=1.4.2
Requires-Dist: tikhub-xiaohongshu>=0.1.1
Description-Content-Type: text/markdown

# 小红书搜索工具

企业级小红书笔记搜索工具，基于 TikHub API 实现。

## 特性

- ✅ **TikHub API 集成** - 稳定的小红书数据接口
- ✅ **Cookie 池管理** - 支持从后端服务动态获取 Cookie
- ✅ **并发控制** - 多线程并发获取数据
- ✅ **限流保护** - 可配置请求间隔
- ✅ **统计信息** - 完整的耗时和成功率统计
- ✅ **数据导出** - JSON 和 Excel 格式
- ✅ **日志记录** - 详细的运行日志

## 安装

```bash
pip install xiaohongshu-search
```

### 可选依赖（导出 Excel）

```bash
pip install xiaohongshu-search[excel]
```

## 配置

### 1. 设置 TikHub API Key

```bash
export TIKHUB_API_KEY="your_api_key"
```

或创建 `.env` 文件：

```bash
TIKHUB_API_KEY=your_api_key
```

### 2. （可选）配置后端服务

如果需要 Cookie 池管理功能：

```bash
# .env
BACK_END_API_BASE_URL=https://ms.jr.jd.com
SOURCE=xiaohongshu

# 或者直接使用环境变量中的 Cookie
COOKIES=cookie1;cookie2;cookie3
```

## 使用

### 命令行

```bash
# 基本搜索
xhs-search "美食推荐"

# 搜索并导出 JSON
xhs-search "北京旅游" -o results.json

# 搜索并导出 Excel
xhs-search "护肤心得" --excel results.xlsx

# 自动翻页获取多页数据
xhs-search "穿搭" -n 5 -o all.json

# 并发模式（10 个工作线程）
xhs-search "数码评测" -n 10 -w 10 -o all.json

# 按点赞数排序
xhs-search "健身" --sort popularity_descending

# 只看视频笔记
xhs-search "教程" --type 视频笔记

# 只看最近一周
xhs-search "评测" --time 一周内

# 获取笔记详情（慢）
xhs-search "探店" --fetch-details -o with_details.json

# 显示详细信息
xhs-search "数码" -v

# 完整示例：并发搜索 + 导出 Excel
xhs-search "北京美食" -n 5 -w 5 --excel beijing_food.xlsx
```

### Python API

```python
from xiaohongshu_search.core.search_processor import SearchProcessor
from xiaohongshu_search.backend.cookie_manager import CookiePool

# 简单模式
processor = SearchProcessor(api_key="your_api_key")
notes = processor.search(keyword="美食推荐", max_pages=5)
processor.export_json("results.json")
processor.export_excel("results.xlsx")

# 高级模式（带 Cookie 池）
cookie_pool = CookiePool()
processor = SearchProcessor(
    api_key="your_api_key",
    cookie_pool=cookie_pool,
    max_workers=5,
    delay=0.5,
)
notes = processor.search(keyword="美食推荐")

# 获取笔记详情
note_ids = [n["note_id"] for n in notes]
details = processor.fetch_details(note_ids)

# 获取统计信息
stats = processor.get_stats()
print(f"找到 {stats.total_found} 篇笔记")
print(f"耗时 {stats.search_time:.2f}秒")
```

## 选项

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `-p, --page` | 页码 | 1 |
| `-n, --max-pages` | 最大页数（自动翻页） | 1 |
| `-o, --output` | 输出 JSON 文件 | - |
| `--excel` | 输出 Excel 文件 | - |
| `--sort` | 排序方式 | general |
| `--type` | 笔记类型 | 不限 |
| `--time` | 时间筛选 | 不限 |
| `-w, --workers` | 并发工作线程数 | 1 |
| `-d, --delay` | 请求间隔（秒） | 0.1 |
| `--fetch-details` | 获取笔记详情 | false |
| `-v, --verbose` | 显示详细信息 | false |

### 排序方式

- `general` - 综合排序
- `time_descending` - 最新
- `popularity_descending` - 最多点赞
- `comment_descending` - 最多评论
- `collect_descending` - 最多收藏

### 笔记类型

- `不限` - 所有类型
- `视频笔记` - 仅视频
- `普通笔记` - 仅图文
- `直播笔记` - 仅直播

### 时间筛选

- `不限` - 所有时间
- `一天内` - 24 小时内
- `一周内` - 7 天内
- `半年内` - 6 个月内

## 项目结构

```
xiaohongshu_search/
├── __init__.py           # 包初始化
├── main.py               # 命令行入口
├── core/
│   ├── __init__.py
│   └── search_processor.py  # 搜索处理器（核心业务逻辑）
├── backend/
│   ├── __init__.py
│   └── cookie_manager.py    # Cookie 池管理（后端交互）
└── utils/
    └── __init__.py
```

## 依赖

- Python 3.12+
- tikhub-xiaohongshu >= 0.1.1
- python-dotenv >= 1.1.1
- requests >= 2.31.0
- retrying >= 1.4.2

可选依赖（导出 Excel）：
- pandas >= 2.2.0
- openpyxl >= 3.0.0

## 日志

运行日志保存在 `logs/` 目录下，文件名格式：`xhs_search_YYYYMMDD_HHMMSS.log`

## 与 xhs_review 的区别

| 特性 | xhs_review | xiaohongshu_search |
|------|------------|-------------------|
| API 来源 | 原始 HTTP + 签名 | TikHub API |
| Cookie 管理 | 复杂（后端 + 设备） | 简化（后端 + 环境变量） |
| 设备联动 | 支持（ADB） | 不支持 |
| 并发控制 | 支持 | 支持 |
| 数据导出 | 支持 | 支持 |
| 依赖复杂度 | 高 | 低 |
| 使用场景 | 企业级采集 | 快速搜索/轻量采集 |

## 许可证

MIT

## 作者

叶浩
