xiaohongshu-search 0.3.0

小红书搜索工具 - 支持远端任务同步

小红书搜索工具

企业级小红书笔记搜索工具，支持本地搜索和远端任务同步。

特性

• ✅ TikHub API 集成 - 稳定的小红书数据接口
• ✅ 远端任务同步 - 从后端获取任务并同步结果
• ✅ 双模式运行 - 本地搜索模式 / 远端任务模式
• ✅ 并发控制 - 多线程并发获取数据
• ✅ 限流保护 - 可配置请求间隔
• ✅ 统计信息 - 完整的耗时和成功率统计
• ✅ 数据导出 - JSON 和 Excel 格式
• ✅ 日志记录 - 详细的运行日志

安装

pip install xiaohongshu-search

配置

1. 设置 TikHub API Key

export TIKHUB_API_KEY="your_api_key"

或创建 .env 文件：

TIKHUB_API_KEY=your_api_key

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

远端任务模式需要：

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

使用

本地搜索模式

# 基本搜索
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 一周内

远端任务模式

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

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

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

Python API

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

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

归还任务

{
  "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

作者

叶浩