# cv-cat/spider_xhs architecture

> Architecture diagram of the GitHub repository cv-cat/spider_xhs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cv-cat/spider_xhs
- Repository: https://github.com/cv-cat/spider_xhs

## Overview

Spider_XHS is a Python API toolkit for collecting Xiaohongshu data and managing Creator, live/messaging, Pugongying, and Qianfan operations. The main workflow starts with an operator or agent invoking the PC collection entry point, which uses authenticated PC APIs to retrieve platform data; data can then be processed externally and submitted through Creator APIs. Separate platform clients cover other documented capabilities. The source index and excerpts support the authentication, signing, and transport layers; some platform API details are documented only in the README, so those links are cited there.

Main entry points: [`apis/xhs_pc_apis.py`](https://github.com/cv-cat/spider_xhs/blob/master/apis/xhs_pc_apis.py) (PC Data API), [`apis/xhs_creator_apis.py`](https://github.com/cv-cat/spider_xhs/blob/master/apis/xhs_creator_apis.py) (Creator API), [`xhs_utils/xhs_pc/auth.py`](https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_pc/auth.py) (PC Auth State), [`xhs_utils/xhs_creator/auth.py`](https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_creator/auth.py) (Creator Auth State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["PC Collection"]
  node_spider["Collection Runner<br/>[spider.py]"]
  node_pc_api["PC Data API<br/>[xhs_pc_apis.py]"]
  node_data_util["Data Utilities<br/>[data_util.py]"]
end

subgraph group_identity["Login and Identity"]
  node_pc_login["PC Login API"]
  node_creator_login["Creator Login API"]
  node_unified_auth["Unified Auth<br/>[xhs_auth.py]"]
  node_pc_auth["PC Auth State<br/>[auth.py]"]
  node_creator_auth["Creator Auth State<br/>[auth.py]"]
end

subgraph group_creator["Creator Publishing"]
  node_creator_api["Creator API"]
end

subgraph group_platforms["Platform Services"]
  node_live_api["Live and Messaging<br/>[xhs_live.py]"]
  node_pugongying["Pugongying API"]
  node_qianfan["Qianfan API"]
end

subgraph group_signing["Signing and Transport"]
  node_pc_state["PC Signing State<br/>[state.py]"]
  node_pc_params["PC Request Signing<br/>[params.py]"]
  node_creator_state["Creator Signing State<br/>[state.py]"]
  node_creator_params["Creator Request Signing<br/>[params.py]"]
  node_core_http["Browser HTTP Transport<br/>[http.py]"]
end

node_operator(("Operator / Agent"))
node_xhs{{"Xiaohongshu Services"}}
node_ai(("External AI Agent"))

node_operator -->|"runs"| node_spider
node_spider -->|"calls"| node_pc_api
node_spider -->|"uses"| node_data_util
node_pc_api -->|"uses"| node_pc_auth
node_pc_api -->|"signs requests"| node_pc_params
node_pc_api -.->|"sends requests"| node_core_http
node_pc_api -->|"fetches data"| node_xhs
node_pc_login -->|"initializes"| node_pc_auth
node_creator_login -->|"initializes"| node_creator_auth
node_unified_auth -->|"creates view"| node_pc_auth
node_unified_auth -->|"creates lazily"| node_creator_auth
node_pc_auth -->|"owns state"| node_pc_state
node_pc_auth -->|"uses login"| node_pc_login
node_creator_auth -->|"owns state"| node_creator_state
node_creator_auth -->|"uses login"| node_creator_login
node_creator_api -->|"uses"| node_creator_auth
node_creator_api -->|"signs requests"| node_creator_params
node_creator_api -.->|"sends requests"| node_core_http
node_creator_api -->|"publishes content"| node_xhs
node_live_api -->|"handles live and messages"| node_xhs
node_pugongying -->|"queries KOL data"| node_xhs
node_qianfan -->|"queries distributor data"| node_xhs
node_pc_state -->|"provides signing state"| node_pc_params
node_creator_state -->|"provides signing state"| node_creator_params
node_ai -->|"requests collection"| node_pc_api
node_ai -->|"requests publishing"| node_creator_api

click node_spider "https://github.com/cv-cat/spider_xhs/blob/master/spider/spider.py"
click node_pc_api "https://github.com/cv-cat/spider_xhs/blob/master/apis/xhs_pc_apis.py"
click node_data_util "https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/data_util.py"
click node_pc_login "https://github.com/cv-cat/spider_xhs/blob/master/apis/xhs_pc_login_apis.py"
click node_creator_login "https://github.com/cv-cat/spider_xhs/blob/master/apis/xhs_creator_login_apis.py"
click node_unified_auth "https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_auth.py"
click node_pc_auth "https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_pc/auth.py"
click node_creator_auth "https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_creator/auth.py"
click node_creator_api "https://github.com/cv-cat/spider_xhs/blob/master/apis/xhs_creator_apis.py"
click node_live_api "https://github.com/cv-cat/spider_xhs/blob/master/apis/xhs_live.py"
click node_pugongying "https://github.com/cv-cat/spider_xhs/blob/master/apis/xhs_pugongying_apis.py"
click node_qianfan "https://github.com/cv-cat/spider_xhs/blob/master/apis/xhs_qianfan_apis.py"
click node_pc_state "https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_pc/state.py"
click node_pc_params "https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_pc/params.py"
click node_creator_state "https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_creator/state.py"
click node_creator_params "https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_creator/params.py"
click node_core_http "https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_core/http.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spider,node_pc_api,node_data_util toneBlue
class node_pc_login,node_creator_login,node_unified_auth,node_pc_auth,node_creator_auth toneAmber
class node_creator_api toneMint
class node_live_api,node_pugongying,node_qianfan toneRose
class node_pc_state,node_pc_params,node_creator_state,node_creator_params,node_core_http,node_operator,node_xhs,node_ai toneIndigo
```

## Components

### PC Collection

- [Collection Runner](https://github.com/cv-cat/spider_xhs/blob/master/spider/spider.py): `spider/spider.py`
- [PC Data API](https://github.com/cv-cat/spider_xhs/blob/master/apis/xhs_pc_apis.py): `apis/xhs_pc_apis.py`
- [Data Utilities](https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/data_util.py): `xhs_utils/data_util.py`

### Login and Identity

- [PC Login API](https://github.com/cv-cat/spider_xhs/blob/master/apis/xhs_pc_login_apis.py): `apis/xhs_pc_login_apis.py`
- [Creator Login API](https://github.com/cv-cat/spider_xhs/blob/master/apis/xhs_creator_login_apis.py): `apis/xhs_creator_login_apis.py`
- [Unified Auth](https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_auth.py): `xhs_utils/xhs_auth.py`
- [PC Auth State](https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_pc/auth.py): `xhs_utils/xhs_pc/auth.py`
- [Creator Auth State](https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_creator/auth.py): `xhs_utils/xhs_creator/auth.py`

### Creator Publishing

- [Creator API](https://github.com/cv-cat/spider_xhs/blob/master/apis/xhs_creator_apis.py): `apis/xhs_creator_apis.py`

### Platform Services

- [Live and Messaging](https://github.com/cv-cat/spider_xhs/blob/master/apis/xhs_live.py): `apis/xhs_live.py`
- [Pugongying API](https://github.com/cv-cat/spider_xhs/blob/master/apis/xhs_pugongying_apis.py): `apis/xhs_pugongying_apis.py`
- [Qianfan API](https://github.com/cv-cat/spider_xhs/blob/master/apis/xhs_qianfan_apis.py): `apis/xhs_qianfan_apis.py`

### Signing and Transport

- [PC Signing State](https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_pc/state.py): `xhs_utils/xhs_pc/state.py`
- [PC Request Signing](https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_pc/params.py): `xhs_utils/xhs_pc/params.py`
- [Creator Signing State](https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_creator/state.py): `xhs_utils/xhs_creator/state.py`
- [Creator Request Signing](https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_creator/params.py): `xhs_utils/xhs_creator/params.py`
- [Browser HTTP Transport](https://github.com/cv-cat/spider_xhs/blob/master/xhs_utils/xhs_core/http.py): `xhs_utils/xhs_core/http.py`

### Other components

- **Operator / Agent**
- **Xiaohongshu Services**
- **External AI Agent**

## Connections

- Operator / Agent → Collection Runner: runs (evidence: `README.md`)
- Collection Runner → PC Data API: calls (evidence: `spider/spider.py`)
- Collection Runner → Data Utilities: uses (evidence: `spider/spider.py`)
- PC Data API → PC Auth State: uses (evidence: `apis/xhs_pc_apis.py`)
- PC Data API → PC Request Signing: signs requests (evidence: `apis/xhs_pc_apis.py`)
- PC Data API → Browser HTTP Transport: sends requests
- PC Data API → Xiaohongshu Services: fetches data (evidence: `README.md`)
- PC Login API → PC Auth State: initializes (evidence: `apis/xhs_pc_login_apis.py`)
- Creator Login API → Creator Auth State: initializes (evidence: `apis/xhs_creator_login_apis.py`)
- Unified Auth → PC Auth State: creates view (evidence: `xhs_utils/xhs_auth.py`)
- Unified Auth → Creator Auth State: creates lazily (evidence: `xhs_utils/xhs_auth.py`)
- PC Auth State → PC Signing State: owns state (evidence: `xhs_utils/xhs_pc/auth.py`)
- PC Auth State → PC Login API: uses login (evidence: `xhs_utils/xhs_pc/auth.py`)
- Creator Auth State → Creator Signing State: owns state (evidence: `xhs_utils/xhs_creator/auth.py`)
- Creator Auth State → Creator Login API: uses login (evidence: `xhs_utils/xhs_creator/auth.py`)
- Creator API → Creator Auth State: uses (evidence: `apis/xhs_creator_apis.py`)
- Creator API → Creator Request Signing: signs requests (evidence: `apis/xhs_creator_apis.py`)
- Creator API → Browser HTTP Transport: sends requests (evidence: `apis/xhs_creator_apis.py`)
- Creator API → Xiaohongshu Services: publishes content (evidence: `README.md`)
- Live and Messaging → Xiaohongshu Services: handles live and messages (evidence: `README.md`)
- Pugongying API → Xiaohongshu Services: queries KOL data (evidence: `README.md`)
- Qianfan API → Xiaohongshu Services: queries distributor data (evidence: `README.md`)
- PC Signing State → PC Request Signing: provides signing state (evidence: `xhs_utils/xhs_pc/state.py`)
- Creator Signing State → Creator Request Signing: provides signing state (evidence: `xhs_utils/xhs_creator/state.py`)
- External AI Agent → PC Data API: requests collection (evidence: `README.md`)
- External AI Agent → Creator API: requests publishing (evidence: `README.md`)