# xiaohongshu-ads-openapi

小红书开放平台广告数据 SDK + MCP Server + Skill 包。

封装乘风（报表）、聚光（笔记）、蒲公英（待开通）三个平台的 API，提供统一的认证、HTTP、异常、模型层，支持 AI Agent 通过 MCP 协议或 Skill 直接调用。

## 特性

- **统一 SDK**：三个平台共用认证、HTTP、异常、分页、Token 存储底座
- **MCP Server**：通过行业标准 MCP 协议暴露工具，支持 Claude、ChatGPT、Cursor、豆包等 AI Agent
- **Skill 包**：开箱即用的业务流程技能（每日投流数据抓取与飞书同步）
- **零外部依赖**：SDK 核心仅依赖 `certifi`（SSL 证书），不引入 requests 等重依赖
- **自动 Token 刷新**：access_token 过期自动刷新，支持内存/文件/SQLite 多种存储
- **可配置**：多应用、多账户支持，所有敏感信息从环境变量读取

## 快速开始

### 1. 安装

```bash
pip install -e .
# MCP Server 需要额外安装 mcp 包
pip install mcp
```

### 2. 配置

复制配置模板并填写你的应用信息：

```bash
cp examples/config.yaml config.yaml
# 编辑 config.yaml，填入 app_id、secret、refresh_token、advertiser_id
# 敏感信息也可以通过环境变量传入，配置文件中用 ${ENV_VAR} 引用
```

### 3. 使用 SDK

```python
from xhs_ads import AppConfig, ChengfengClient
from datetime import date

app = AppConfig(
    name="乘风-我的账户",
    platform="chengfeng",
    app_id="your_app_id",
    secret="your_secret",
    refresh_token="your_refresh_token",
    advertiser_id=12345678,
)

client = ChengfengClient(app)

# 抓昨天的单日报表
result = client.fetch_offline_report(
    level="campaign",
    start_date=date(2026, 9, 20),
    end_date=date(2026, 9, 20),
    time_unit="DAY",
)

for row in result.rows:
    print(f"{row.entity_name}: 消耗={row.fee}, 点击={row.click}, CTR={row.ctr}")
```

### 4. 运行 MCP Server

```bash
export XHS_ADS_CONFIG=/path/to/config.yaml
python -m mcp_server.server
```

在支持 MCP 的 AI 工具中配置 stdio MCP Server，即可调用以下工具：
- `list_apps` — 列出可用应用
- `fetch_daily_report` — 抓取单日报表
- `fetch_cumulative_report` — 抓取累计报表
- `fetch_realtime_base_map` — 获取计划/创意基础信息（含创建时间）

### 5. 运行 Skill（每日投流数据抓取）

```bash
export XHS_ADS_CONFIG=/path/to/config.yaml
python skills/daily_ad_report/run.py

# 测试模式（只抓不写飞书）
python skills/daily_ad_report/run.py --dry-run

# 指定日期和应用
python skills/daily_ad_report/run.py --date 2026-09-20 --app "乘风-我的账户"
```

## 项目结构

```
xiaohongshu-ads-openapi/
├── src/xhs_ads/                  # 核心 SDK
│   ├── __init__.py               # 包入口，导出所有公共 API
│   ├── exceptions.py             # 异常体系
│   ├── http_client.py            # HTTP 客户端（重试+限流）
│   ├── auth.py                   # 认证（Token 自动刷新+应用配置）
│   ├── token_store.py            # Token 存储抽象（内存/文件）
│   ├── models.py                 # 类型化数据模型+指标列常量
│   ├── config.py                 # 配置加载（YAML/环境变量）
│   └── chengfeng/                # 乘风子模块
│       ├── __init__.py
│       └── client.py             # 乘风报表客户端（offline+realtime）
├── mcp_server/                   # MCP Server
│   ├── __init__.py
│   └── server.py                 # MCP Server 入口（4个工具）
├── skills/                       # Skill 包
│   └── daily_ad_report/          # 技能1：每日投流数据抓取
│       ├── SKILL.md              # 技能说明
│       ├── run.py                # 编排脚本
│       └── feishu_client.py      # 飞书多维表格客户端
├── docs/                         # 文档
│   └── SPEC_daily_ad_report.md   # 技能1规格文档
├── examples/                     # 示例
│   └── config.yaml               # 配置模板
├── tests/                        # 测试
├── pyproject.toml                # 包配置
├── .gitignore
├── LICENSE
└── README.md
```

## 平台支持状态

| 平台 | 报表 | 笔记 | 其他 | 状态 |
|---|---|---|---|---|
| 乘风 (Chengfeng) | ✅ offline + realtime | — | — | 可用 |
| 聚光 (Juguang) | — | ✅ 笔记列表 | — | 可用（SDK 层已预留） |
| 蒲公英 (PGY) | — | — | 投后数据 | ⚠️ 需消耗达标（近1年500万）才能开通应用 |

## 注意事项

- **.env 不进仓库**：所有敏感信息（app_id、secret、token、advertiser_id）通过环境变量或本地配置文件传入，绝不提交到 Git
- **数据口径**：乘风 7 日归因 GMV 与千帆店铺支付金额是不同口径，不相加、不互相替代
- **离线报表 T+1**：昨天的数据建议每天上午 9 点后抓取，确保数据已产出
- **蒲公英门槛**：蒲公英应用创建需近 1 年蒲公英累计消耗 500 万元，未达标无法开通

## License

MIT