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

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

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}")

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

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