Metadata-Version: 2.4
Name: xiaohongshu-search
Version: 0.3.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 集成** - 稳定的小红书数据接口
- ✅ **远端任务同步** - 从后端获取任务并同步结果
- ✅ **双模式运行** - 本地搜索模式 / 远端任务模式
- ✅ **并发控制** - 多线程并发获取数据
- ✅ **限流保护** - 可配置请求间隔
- ✅ **统计信息** - 完整的耗时和成功率统计
- ✅ **数据导出** - JSON 和 Excel 格式
- ✅ **日志记录** - 详细的运行日志

## 安装

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

## 配置

### 1. 设置 TikHub API Key

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

或创建 `.env` 文件：

```bash
TIKHUB_API_KEY=your_api_key
```

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

远端任务模式需要：

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

## 使用

### 本地搜索模式

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

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

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

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

# 并发模式
xhs-search "数码评测" -n 10 -w 5 -o all.json

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

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

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

### 远端任务模式

```bash
# 启动远端任务轮询（默认 5 秒间隔）
xhs-search --remote

# 自定义轮询间隔
xhs-search --remote --poll-interval 10

# 并发配置
xhs-search --remote -w 5 -d 0.5
```

### Python API

```python
from xiaohongshu_search.core.search_processor import SearchProcessor

# 本地搜索
processor = SearchProcessor(api_key="your_api_key")
notes = processor.search(keyword="美食推荐", max_pages=5)
processor.export_json("results.json")

# 远端任务
from xiaohongshu_search.backend.task_sync import load_search_task, sync_task_result

task = load_search_task(task_type=1)
if task:
    notes = processor.search(keyword=task.crawl_url)
    # 同步结果...
```

## 选项

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `-p, --page` | 页码 | 1 |
| `-n, --max-pages` | 最大页数 | 1 |
| `-o, --output` | 输出 JSON 文件 | - |
| `--excel` | 输出 Excel 文件 | - |
| `--sort` | 排序方式 | general |
| `--type` | 笔记类型 | 不限 |
| `--time` | 时间筛选 | 不限 |
| `-w, --workers` | 并发工作线程数 | 1 |
| `-d, --delay` | 请求间隔（秒） | 0.1 |
| `--remote` | 启用远端任务模式 | false |
| `--poll-interval` | 远端轮询间隔（秒） | 5 |
| `-v, --verbose` | 显示详细信息 | false |

## 后端 API

### 获取任务

```
GET /gw2/generic/jylyscrawl/h5/m/loadDataCrawlTask?reqData={task_type}
```

### 同步结果

```
POST /gw2/generic/jylyscrawl/h5/m/syncDataCrawlResult
```

```json
{
  "reqData": {
    "taskId": 12345,
    "data": "{\"bizId\":\"xxx\",\"dataContent\":[...]}",
    "status": 4
  }
}
```

### 归还任务

```json
{
  "reqData": {
    "taskId": 12345,
    "status": 2,
    "errorMsg": "失败原因",
    "data": ""
  }
}
```

## 项目结构

```
xiaohongshu_search/
├── __init__.py
├── main.py                      # 命令行入口
├── core/
│   └── search_processor.py      # 搜索处理器
├── backend/
│   └── task_sync.py             # 远端任务同步
├── models/
│   └── task_models.py           # 数据模型
└── utils/
    └── __init__.py
```

## 依赖

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

可选：pandas, openpyxl（导出 Excel）

## 许可证

MIT

## 作者

叶浩
