Metadata-Version: 2.4
Name: xhs-post-capture-sdk
Version: 1.0.0
Summary: 小红书数据采集 & 运营 SDK - 支持笔记采集、用户画像、创作者中心、蒲公英、千帆平台
Author: XHS-SDK Team
License: MIT
Project-URL: Homepage, https://github.com/cv-cat/Spider_XHS
Project-URL: Source, https://github.com/cv-cat/Spider_XHS
Project-URL: BugTracker, https://github.com/cv-cat/Spider_XHS/issues
Keywords: xiaohongshu,spider,crawler,小红书,social-media
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: PyExecJS>=1.5.1
Requires-Dist: loguru>=0.7
Requires-Dist: python-dotenv>=1.0
Requires-Dist: retry>=0.9
Requires-Dist: openpyxl>=3.1
Requires-Dist: aiohttp>=3.8
Requires-Dist: qrcode>=7.4
Requires-Dist: Pillow>=10.0
Requires-Dist: click>=8.0
Dynamic: license-file

<div align="center">
  <h1>📕 XHS-SDK</h1>
  <p><strong>专业的小红书数据采集 & 全域运营 Python SDK</strong></p>
  <p>
    <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+">
    <img src="https://img.shields.io/badge/license-MIT-orange" alt="MIT License">
    <img src="https://img.shields.io/badge/status-beta-yellow" alt="Beta">
  </p>
</div>

---

## 📋 功能总览

| 模块 | 能力 | 状态 |
|------|------|------|
| **笔记采集** | 单笔记详情、批量笔记、笔记评论、相关推荐 | ✅ |
| **搜索能力** | 笔记搜索、用户搜索、热搜词、搜索建议、多排序/筛选 | ✅ |
| **用户画像** | 用户信息、用户笔记列表、用户全量笔记采集 | ✅ |
| **创作者中心** | 笔记发布（图文/视频）、数据分析、粉丝分析 | ✅ |
| **蒲公英平台** | KOL搜索、博主详情、粉丝画像、合作邀请 | ✅ |
| **千帆平台** | 直播间KOL搜索、博主详情 | ✅ |
| **登录方式** | 二维码扫码、手机验证码、Cookie注入、创作者登录 | ✅ |
| **数据导出** | Excel (.xlsx)、CSV (.csv)、JSON (.json) | ✅ |
| **媒体下载** | 图片下载、视频下载、批量下载 | ✅ |
| **Cookie管理** | 多Cookie池、轮转、文件持久化 | ✅ |
| **命令行** | 笔记/搜索/用户/导出 CLI 工具 | ✅ |
| **异步支持** | aiohttp 异步客户端 | ✅ |

---

## 🚀 快速开始

### 安装

```bash
# 1. 克隆项目
git clone https://github.com/your-org/xhs-sdk.git
cd xhs-sdk

# 2. 安装依赖
pip install -r requirements.txt

# 3. 下载签名 JS 文件（必需）
# 从 https://github.com/cv-cat/Spider_XHS/tree/master/static 下载以下文件到 static/ 目录：
#   - xhs_main_260411.js    (核心签名算法)
#   - xhs_a1.js             (A1 cookie生成)
#   - xhs_a1_other.js       (A1 备用)
#   - xhs_xray.js           (Xray-TraceID)
#   - xhs_rap.js            (RAP参数)
#   - xhs_creator_sign.js   (创作者签名)
#   - xhs_creator_260411.js (创作者算法)
#   - xhs_creator_sign_other.js (创作者备用)
```

### 配置

创建 `.env` 文件：

```env
COOKIES='your_cookies_here'
LOG_LEVEL=INFO
REQUEST_TIMEOUT=15
```

或者在代码中直接传入：

```python
from xhs_sdk.client import XHSClient  # 推荐：惰性加载
# 或 import xhs_sdk; client = xhs_sdk.XHSClient(...)

client = XHSClient(cookies="your_cookies_here")
```

### 获取 Cookie

1. 打开浏览器访问 [小红书](https://www.xiaohongshu.com) 并登录
2. 按 F12 打开开发者工具 → 控制台
3. 输入 `document.cookie` 并回车
4. 复制输出的字符串

---

## 📖 使用指南

### 初始化

```python
from xhs_sdk import XHSClient

# 方式一: 直接传入 Cookie
client = XHSClient(cookies="a1=xxx; webId=yyy; ...")

# 方式二: 使用 .env 文件
client = XHSClient()

# 方式三: 使用上下文管理器（推荐）
with XHSClient() as client:
    # 在此使用 client
    pass
```

### 笔记操作

```python
# 获取笔记详情
note = client.note.get("660000000000000001")

# 通过 URL 获取
note = client.note.get_detail_by_url(
    "https://www.xiaohongshu.com/explore/660000000000000001"
)

# 获取笔记评论
comments = client.note.get_comments("660000000000000001")
for comment in comments.get("comments", []):
    print(comment.get("content", ""))

# 获取全部评论（自动翻页）
all_comments = client.note.get_all_comments("660000000000000001", max_comments=500)

# 获取相关推荐
related = client.note.get_related("660000000000000001")

# 获取首页推荐
recommends = client.note.get_recommend(page_size=30)
```

### 搜索功能

```python
from xhs_sdk.api.search import SearchAPI

# 基础搜索
results = client.search.notes(
    keyword="护肤",
    page=1,
    page_size=20,
    sort_type=SearchAPI.SORT_POPULAR,   # 按热度排序
    note_type=SearchAPI.NOTE_VIDEO,     # 只看视频
)

# 搜索所有结果（自动翻页）
all_notes = client.search.notes_all(
    keyword="美食",
    max_results=100,
    sort_type=SearchAPI.SORT_TIME,      # 按最新
    time_range=SearchAPI.TIME_ONE_WEEK, # 一周内
)

# 搜索用户
users = client.search.users("美食博主")

# 热搜词
hot = client.search.hot_keywords()

# 搜索建议
suggestions = client.search.suggest("护肤")
```

### 用户操作

```python
# 获取用户信息
info = client.user.get_info("user_id_here")
print(f"昵称: {info['nickname']}, 粉丝: {info['fans']}")

# 获取用户笔记列表
notes = client.user.get_notes("user_id_here", page=1)

# 获取用户全部笔记（自动翻页）
all_notes = client.user.get_all_notes("user_id_here", max_notes=200)
```

### 数据导出

```python
# 导出为 Excel
client.export(results, "output.xlsx")

# 导出为 CSV
client.export(results, "output.csv")

# 导出为 JSON
client.export(results, "output.json")

# 自定义字段映射
client.export(results, "output.xlsx", field_mapping={
    "note_id": "笔记ID",
    "title": "标题",
    "likes": "点赞数",
})
```

### 媒体下载

```python
# 下载笔记中的图片和视频
note = client.note.get("660000000000000001")
result = client.download_note(note, "./downloads")
print(f"图片: {len(result['images'])} 张, 视频: {result['video']}")

# 仅下载图片
client.downloader.download_note_images(note, "./downloads")

# 仅下载视频
client.downloader.download_note_video(note, "./downloads")
```

### 登录

```python
from xhs_sdk import XHSClient
from xhs_sdk.auth.login import LoginManager

# 二维码登录
manager = LoginManager()
cookies_str = manager.qrcode_login(show_in_terminal=True)

# 手机号登录
cookies_str = manager.phone_login()

# 创作者中心扫码登录
cookies_str = manager.creator_qrcode_login()
```

### 创作者中心

```python
# 发布图文笔记
result = client.creator.post_note({
    "title": "我的第一篇笔记",
    "desc": "这是用 XHS-SDK 发布的",
    "type": 0,  # 0=公开
    "media_type": "image",
    "topics": ["日常", "生活"],
    "images": [open("image.jpg", "rb").read()],
})

# 发布视频笔记
result = client.creator.post_note({
    "title": "视频标题",
    "desc": "视频描述",
    "media_type": "video",
    "video": open("video.mp4", "rb").read(),
})

# 数据分析
stats = client.creator.get_self_note_stats()
fans = client.creator.get_fan_analysis()
```

### 蒲公英平台

```python
# 获取分类
cats = client.pugongying.get_all_categories()

# 搜索KOL
users = client.pugongying.get_some_user(
    page=1,
    brand_user_id="your_brand_id",
)

# 获取博主详情
detail = client.pugongying.get_user_detail("user_id")
fans = client.pugongying.get_user_fans_detail("user_id")
```

### 命令行工具

```bash
# 查看配置
python -m xhs_sdk.cli.main config

# 搜索笔记
python -m xhs_sdk.cli.main search 护肤 --max 50 --sort popular --output 护肤笔记.xlsx

# 获取笔记详情
python -m xhs_sdk.cli.main note 660000000000000001

# 获取用户信息
python -m xhs_sdk.cli.main user user_id_here
```

---

## 🏗 项目架构

```
xhs-sdk/
├── xhs_sdk/
│   ├── __init__.py          # 导出入口
│   ├── client.py            # XHSClient / AsyncXHSClient
│   ├── exceptions.py        # 异常体系
│   ├── auth/
│   │   ├── signer.py        # 签名引擎（X-s/X-t/X-s-common）
│   │   └── login.py         # 登录管理
│   ├── api/
│   │   ├── note.py          # 笔记 API
│   │   ├── user.py          # 用户 API
│   │   ├── search.py        # 搜索 API
│   │   ├── creator.py       # 创作者中心 API
│   │   ├── pugongying.py    # 蒲公英平台 API
│   │   ├── qianfan.py       # 千帆平台 API
│   │   └── login.py         # 登录 API
│   ├── utils/
│   │   ├── http.py          # HTTP 客户端
│   │   ├── cookie.py        # Cookie 管理
│   │   ├── downloader.py    # 媒体下载
│   │   ├── exporter.py      # 数据导出
│   │   └── common.py        # 通用工具
│   └── cli/
│       └── main.py          # 命令行工具
├── static/                  # JS 签名文件（需下载）
├── examples/
│   └── basic_usage.py       # 使用示例
├── .env                     # 配置文件
├── requirements.txt
├── pyproject.toml
└── README.md
```

---

## ⚠️ 注意事项

1. **签名 JS 文件**：需要从原项目下载 JS 文件放到 `static/` 目录
2. **Cookie 时效**：Cookie 有效期通常为数天至数周，过期后需重新登录
3. **请求频率**：建议控制请求频率避免触发反爬机制（推荐 1-2 QPS）
4. **法律合规**：请遵守小红书用户协议和相关法律法规，仅采集公开数据
5. **IP 限制**：高频请求建议使用代理 IP 池

---

## 📄 许可证

基于 MIT 许可证开源。本 SDK 基于 [Spider_XHS](https://github.com/cv-cat/Spider_XHS) 的代码和架构封装重构。

---

## ⭐ Star & Follow

如果这个项目对你有帮助，请给个 Star ⭐ 支持！
