小红书聚光投放API Skill v6.3.0

能力概览

本 Skill 提供小红书聚光广告投放平台的完整API接入能力，支持多账号管理模式，适合需要 24 小时自动化监控的场景。

核心能力：

• 授权与Token管理：OAuth授权链接生成、auth_code换取token、自动刷新(带重试)、过期预警、token文件安全备份
• 多账号管理：账号增删改查、启停切换、配置校验(verify)、健康检查(health-check)、字段白名单防误写
• 实时报表：今日数据即时查询(account维度)，支持多账号批量取数(带QPS延迟和自动重试)
• 离线报表：T+1历史数据(account/campaign/unit/creative/keyword/search_word/note/crowd/spu多维度)，支持逐日明细和汇总
• 数据对比：两天数据自动对比，计算变化百分比
• 广告管理CRUD：计划(创建/编辑/启停)、单元(列表/编辑/出价)、创意(搜索/编辑/状态修改)
• 账户服务：预算查询与修改、流水明细、余额查询
• 搜索词/关键词分析：搜索词报告(触发词诊断)、关键词效果排名、多维度数据报表(campaign/unit/creative/keyword/search_word)
• 关键词管理：关键词添加(支持批量+出价)、关键词推荐(种子词拓展)、词包查询
• 智能优化建议：综合分析关键词/搜索词/单元数据，自动诊断高消耗低转化词、挖掘高转化搜索词、计算开口成本、输出分级优化建议(high/medium/low)
• 创意深度分析：100分制多维度评分(CTR/开口成本/漏斗转化/消耗效率)→S/A/B/C星级分级→明星创意识别(建议复用加投)→烧钱创意诊断(建议暂停)→消耗集中度预警
• 辅助工具：操作历史查询、广告组管理
• 回调服务器：独立OAuth回调服务(端口58080)，含错误处理、state校验、路径保护
• 自动优化规则：可配置的自动调整策略(auto_rules)
• 首次接入引导：完整的SETUP.md从零配置指南

快速开始：首次使用请先阅读同目录下的 SETUP.md 完成配置。

官方API规范（必读）

• 请求域名: https://adapi.xiaohongshu.com
• 请求方式: 全部 POST，Header 传 Access-Token
• scope权限: report_service(报表) + ad_query(查询广告) + ad_manage(管理广告) + account_manage(账户管理)

Token生命周期

• access_token: 有效期 1天，用 access_token_expires_in(秒) 字段计算
• refresh_token: 有效期 30天，用 refresh_token_expires_in(秒) 字段计算
• 刷新后产生新 token 对，旧 token 5分钟内仍可用（平滑过渡）
• 刷新失败但 token 未过期 → 不影响使用，不算取数失败
• refresh_token 过期 → 必须重新授权（仅此情况）

实时报表API

POST /api/open/jg/data/report/realtime/account
请求: { advertiser_id, start_date, end_date }
返回: { success, data: { fee, impression, click, ctr, cpm, msg_leads_num, message_consult, message, like, comment, collect, follow, share, ... } }

注意：data 直接包含指标字段，没有 total_data 或 aggregation_data 嵌套。

离线报表API（T+1数据）

POST /api/open/jg/data/report/offline/{report_type}
report_type: account/campaign/unit/creativity/keyword/search_word/note/crowd/spu
请求: { advertiser_id, start_date, end_date, time_unit="SUMMARY"|"DAY", page=1, page_size=200 }
返回: { success, data: { aggregation_data: {...}, data_list: [...] } }

> 创意层级端点名注意：小红书API创意层级的路径是 creativity（不是 creative）。SDK 的 get_offline_report() 和 get_realtime_report() 方法会自动将 'creative' 映射为 'creativity'，调用方直接传 'creative' 即可。

数据结构说明：

• aggregation_data: 整个时间范围的汇总数据（同实时报表字段结构）
• data_list: 逐日/逐条明细数组
• 当 time_unit="DAY" 时，每条包含 time 字段（格式 "2026-06-15"，注意是 time 不是 date）
• 每条明细都包含完整的指标字段（fee, impression, click 等）
• 分页注意：如果 data_list 长度等于 page_size，说明可能有下一页，需翻页取全

返回示例：

{
  "success": true,
  "data": {
    "aggregation_data": {
      "fee": 389.84, "impression": 30057, "click": 5699, "ctr": "18.96%",
      "msg_leads_num": 72, "message_consult": 210, "message": 446
    },
    "data_list": [
      {"time": "2026-06-15", "fee": 45.20, "impression": 3500, "click": 650, ...},
      {"time": "2026-06-16", "fee": 52.10, "impression": 4100, "click": 780, ...}
    ],
    "page": {"page": 1, "page_size": 200, "total_count": 7}
  }
}

关键指标字段

私信四字段区分（重要）

注意：漏斗关系：开口(initiative_message) ≥ 进线(message_consult) ≥ 留资(msg_leads_num)。报告必须同时展示留资/进线/开口三个指标。

简单投实时报表API（4个层级）

简单投有独立的实时报表接口，路径前缀 /api/open/jg/data/report/realtime/ube/：

账号级汇总获取方式：简单投实时无账号级接口，通过标的层级(/ube/group)的data.total_data获取账号汇总。

columns参数（仅标的接口需要）：

["fee", "impression", "click", "ctr", "acp", "cpm",
 "like", "comment", "collect", "follow", "share", "interaction",
 "messageConsult", "initiativeMessage", "msgLeadsNum", "message",
 "leads", "validLeads"]

SDK方法：

sdk.get_easy_realtime_group(start_date, end_date)          # 标的层级
sdk.get_easy_realtime_campaign(group_id, start_date, end_date)  # 计划层级
sdk.get_easy_realtime_note(group_id, start_date, end_date)      # 笔记层级
sdk.get_easy_realtime_keyword(group_id, start_date, end_date)   # 关键词层级
sdk.get_easy_realtime_summary(start_date, end_date)             # 便捷方法：标的层级total_data

数据源选择规则（重要）

总消耗 = 标准投.fee + 简单投.fee（强制规则，所有报告默认展示合计+拆分）

官方API完整目录（100个接口）

以下接口全部来自官方文档站 https://ad-market.xiaohongshu.com/docs-center?bizType=943

OAuth/授权（5个）：Oauth2.0授权(#4437)、scope权限说明(#3195)、token管理、刷新token(#4808)、获取Token(#2605)

账户服务（8个）：代理商主子账号余额查询(#4417)、获取代理商子账号列表(#4112)、转账接口(#4300)、查询转账结果(#4301)、资金流水查询(#4302)、修改账户日预算(#4094)、获取计划流水(#3216)、获取账户日预算余额(#3215)、获取账户流水(#3211)

投放管理-新创编（2个）：新创编编辑接口(#4752)、新创编API(#4554)

投放管理-推广计划（3个）：编辑计划(#3148) POST /campaign/update、修改计划状态(#3149) POST /campaign/status/update、查询计划(#3150) POST /campaign/list

投放管理-推广单元（5个）：修改单元关键词(#4665)、修改单元出价(#4516)、编辑单元(#3151)、修改单元状态(#3152)、获取单元列表(#3044) POST /unit/list

投放管理-推广创意（3个）：编辑创意(#3156)、修改创意状态(#3157)、创意查询(#3158) POST /creativity/search

投放管理-广告组（4个）：创建(#4582)、删除(#4596)、更新(#4595)、查询列表(#4594) POST /campaign/group/base/list

投放管理-简单投（1个）：新建简单投(#4776) POST /ube/semi/auto/create

离线报表（13个）：创意层级(#4811) /offline/creativity、简单投标的(#4684) /offline/easy/promotion/group、人群包V2(#4654)、简单投笔记(#4647) /offline/easy/promotion/note、简单投计划(#4644) /offline/easy/promotion/base、人群包(#4065)、SPU层级(#3835) /offline/spu、笔记层级(#3803) /offline/note、搜索词层级(#3714) /offline/search/word、账户层级(#2738) /offline/account、计划层级(#2735) /offline/campaign、单元层级(#2736) /offline/unit、关键词层级(#3073) /offline/keyword

实时报表-标准投（5个）：账户层级(#2731) /realtime/account、计划层级(#2732) /realtime/campaign、创意层级(#2734) /realtime/creativity、定向层级(#3672) /realtime/target、广告组层级(#4597) /realtime/campaign/group

实时报表-简单投（4个）：简单投标的层级(#4716) /realtime/ube/group、简单投计划层级(#4719) /realtime/ube/campaign、简单投笔记层级(#4721) /realtime/ube/note、简单投关键词层级(#4724) /realtime/ube/keyword

实时报表-其他（1个）：AI智能笔记详情(#4792)

素材管理（31个）：可投剧集列表(#4806)、剧集修改(#4805)、剧集创建(#4802)、批量查询简单投标的ID(#4717)、行业商品列表(#4571)、创意标题和图片(#4558)、移动应用列表(#4557)、微信小程序列表(#4556)、红书小程序列表(#4555)、获取广告素材评论(#4692)、删除广告素材评论(#4693)、发布广告素材(#4445)、定向包关联单元(#4354)、删除定向包(#4347)、更新定向包(#4342)、创建定向包(#4341)、获取定向包列表(#4309)、获取笔记ID(#3787)、删除笔记(#3785)、查询否定词(#3696)、批量删除否定词(#3695)、批量添加否定词(#3676)、获取直达链接(#3194)、删除直达链接(#3193)、编辑直达链接(#3192)、创建直达链接(#3191)、资产事件(#3190)、资质列表(#3189)、门店信息(#3169)、笔记列表(#3162)、落地页表单(#3161)

工具（10个）：历史操作记录(#4096) POST /history/list、定向推词(#3168)、行业类目属性(#3167)、行业类目(#3166)、词包推荐(#3165)、人群预估(#3164)、关键词匹配词库(#3163)、推荐关键词(#3160)、定向信息(#3159)、名称重复校验(#3113)

附录（4个）：OAuth错误码排查(#4810)、聚光API FAQ(#4436)、蒲公英/乘风/私信API FAQ(#4439)、MAPI特殊开白(#4447)

SDK实现注意事项（扩展SDK必读）

以下三个陷阱在开发过程中反复踩坑，新增任何SDK方法时务必遵守：

陷阱1：data: null 的 Python .get() 陷阱

# ✗ 错误写法：API返回 {"success": true, "data": null} 时，.get('data', {}) 返回 None
data = result.get('data', {})
fee = data.get('fee')  # AttributeError: 'NoneType' object has no attribute 'get'

# ✓ 正确写法：用 or {} 兜底
data = result.get('data') or {}
fee = data.get('fee') or 0  # 安全，fee为null时返回0

原因：Python 的 .get('key', default) 只在 key 不存在 时返回 default。当 key 存在但值为 null（None），返回的是 None。小红书 API 在数据为空时常返回 "data": null。

同样适用于数值字段：float(x.get('fee', 0)) 在 fee 为 null 时会 TypeError，必须用 float(x.get('fee') or 0)。

陷阱2：分页格式区分

小红书 API 的分页参数有两种格式，混用会导致参数被忽略（返回0条或只有第1页）：

注意：列表端点的分页值必须是 整数，传 str(page_index) 会导致 API 不识别。

陷阱3：响应字段名兼容

列表端点的响应字段名在不同版本/文档中不一致，取值时需做 fallback：

# 推广计划
campaigns = (data.get('base_campaign_dtos')
             or data.get('campaign_dtos')
             or data.get('list') or [])

# 广告组
groups = (data.get('campaign_group_base_dtos')
          or data.get('campaign_groups')
          or data.get('list') or [])

# 创意
creatives = (data.get('creativity_dtos')
             or data.get('creative_dtos')
             or data.get('list') or [])

首次对接新端点时，建议打印 list(data.keys()) 确认实际返回的字段名。

执行流程规范（强制，违反=推送事故）

规则1：只发一条消息

定时报告/多账号监控任务，最终只向用户发送一条消息。

禁止：

• 遍历账号时"先发错误消息、再发成功消息"
• 为单个账号失败单独发消息
• token 刷新失败时立即发"授权过期"消息

正确流程：取全部数据 → 内存汇总 → 生成一条完整消息 → 一次性发出

规则2：取数失败 ≠ 授权过期

fetch_failed 的可能原因（按概率排序）：

1. 网络抖动 / QPS限流（最常见）
2. token 刷新暂时失败但 token 仍有效（不算失败）
3. 接口临时不可用
4. refresh_token 真正过期（仅当 全部账号都失败 且 refresh_token确实超30天 时才考虑）

禁止替用户下"授权过期"结论。在消息中只写具体失败原因。

规则3：0数据三态

规则4：QPS限流防护

小红书 API 有 QPS 限制（约 5-10 QPS），多账号场景必须加延迟：

• 每个账号取数之间：time.sleep(2) 强制等待 2 秒
• 失败重试之前：time.sleep(3) 等待 3 秒
• 离线报表分页之间：time.sleep(1) 等待 1 秒

违反会导致批量超时（15s timeout），误报为"网络问题"。

规则5：标准执行流程

1. 运行: python3 account_manager.py report-today all
2. 等待完整输出（不要中途打断）
3. 解析 ---JSON_RESULT--- 标记内的 JSON
4. 根据报告类型选择对应模板，生成一条汇总消息
5. 一次性发送给用户

规则6：消耗 = 标准投 + 简单投（强制）

小红书聚光有两种投放类型：标准投（标准推广）和简单投（简单推广）。

• 总消耗 = 标准投.fee + 简单投.fee（曝光、点击同理）
• 所有报告中展示的「消耗」「曝光」「点击」默认都是合计值
• 报告必须同时展示合计 + 拆分，格式：总消耗 XX元 (标准投 XX + 简单投 XX)
• 私信指标（开口/进线/留资/消息量）仅来自标准投，简单投 API 不返回这些字段
• 用户单独问某个投放类型时才拆分单独展示，否则默认给总计+拆分

JSON 输出中的拆分字段：

取数流程：标准投报表 → sleep(1) → 简单投报表 → 合并。两个 API 调用之间必须有 1 秒 QPS 延迟。

报告模板与渲染规则

渲染方式

两种渠道的数据洞察和建议内容必须一致，只是展示形式不同。

报告类型

数据分析框架（必须执行）

收到 JSON 数据后，必须按以下规则逐项分析并写入报告：

持续性差的表现（连续多天跑不起来/一直0消耗/开口长期为0）→ 用 😤⚫ 标记，别客气直接骂

漏斗转化率计算：

• 开口→进线：message_consult / initiative_message × 100%
• 进线→留资：msg_leads / message_consult × 100%

客资单价计算（分母为0时显示 -）：

• 开口成本：fee / initiative_message
• 进线成本：fee / message_consult
• 留资成本：fee / msg_leads

标准执行流程

1. 运行: python3 account_manager.py report-today all  (或其他命令)
2. 等待完整输出（不要中途打断）
3. 解析 ---JSON_RESULT--- 标记内的 JSON
4. 根据报告类型选择对应模板，生成一条汇总消息
5. 执行「数据分析框架」中的所有规则
6. 一次性发送给用户

日报模板（report-today）

📊 聚光日报 | {date}

📈 整体概况

| 指标 | 数值 |
|------|------|
| 💰 总消耗 | {fee}元 |
| ├ 标准投 | {normal_fee}元 |
| └ 简单投 | {easy_fee}元 |
| 👁 总曝光 | {impression} |
| 👆 总点击 | {click} |
| 📊 CTR | {ctr} |
| 💵 ACP | {acp}元 |
| 📡 取数 | 成功 {ok}/{total} |

👥 客资分析

| 指标 | 数量 | 单价 |
|------|------|------|
| 💬 开口 | {initiative_message}条 | {开口成本}元/条 |
| 📞 进线 | {message_consult}条 | {进线成本}元/条 |
| 📋 留资 | {msg_leads}条 | {留资成本}元/条 |
| 📨 消息量 | {message}条 | - |

🔄 漏斗转化：开口→进线 {rate1}% | 进线→留资 {rate2}%

📋 各账号明细

| 账号 | 消耗 | 曝光 | 点击 | CTR | 开口 | 进线 | 留资 | 开口成本 |
|------|------|------|------|-----|------|------|------|---------|
| {name1} | {fee}元 | {imp} | {click} | {ctr} | {n} | {n} | {n} | {cost}元 |
| {name2} | ... | ... | ... | ... | ... | ... | ... | ... |

{real_zero 账号} ○ {name}: 今日0消耗（可能计划暂停/预算耗尽）
{fetch_failed 账号} ✗ {name}: {fail_reason}

💡 数据洞察

{按「数据分析框架」逐条分析，2-3 条关键结论，必须带具体数字和账号名}
{语气要直接，好的夸、烂的骂，带表情区分}
例：
- "🔥 {name} CTR {ctr}% 太猛了，素材跑得很好，继续加预算！"
- "🤬 {name} 开口成本飙到 {cost}元，100块才来一个开口？落地页是不是该换了"
- "💀 {name} 连续{n}天开口为0，这个号基本等于白投，趁早停掉或换素材"
- "😤 {name} 一直跑不起来，消耗 {fee}元 但留资才{n}个，ROI 烂到离谱"
- "😎 整体漏斗转化率 {rate}%，客资链路跑通了，可以激进加量"

📝 投放建议

{大胆给投放建议，目标是激进跑量，跑不起来就骂}
{不怕说重话——反正不是花你的钱投，目的是帮用户快速决策}
例：
- "🚀 {name} 数据跑得好，建议直接把日预算拉到 {amount}元，趁热打铁放量"
- "🔪 {name} 开口成本太高，建议立刻砍掉 CTR<5% 的计划，把预算给 {好账号}"
- "😡 {name} 这个号别投了，连续{n}天0开口，素材全部下线重建"
- "⚡ 整体留资转化率偏低，建议全部账号换一版私信话术，第一句话直接抛利益点"
- "💪 当前整体成本可控，建议全账号提预算20~30%，测试放量后的成本变化"

范围报告模板（report-range）

适用于周报、月报、自定义日期范围。

📊 聚光报告 | {start_date} ~ {end_date}（共{days}天）

📈 汇总概况

| 指标 | 合计 | 日均 |
|------|------|------|
| 💰 消耗 | {fee}元 | {日均fee}元 |
| ├ 标准投 | {normal_fee}元 | {日均normal_fee}元 |
| └ 简单投 | {easy_fee}元 | {日均easy_fee}元 |
| 👁 曝光 | {impression} | {日均imp} |
| 👆 点击 | {click} | {日均click} |
| 📊 CTR | {ctr} | - |
| 💬 开口 | {initiative_message}条 | {日均}条 |
| 📞 进线 | {message_consult}条 | {日均}条 |
| 📋 留资 | {msg_leads}条 | {日均}条 |

👥 客资分析

| 指标 | 总量 | 单价 |
|------|------|------|
| 💬 开口 | {n}条 | {cost}元/条 |
| 📞 进线 | {n}条 | {cost}元/条 |
| 📋 留资 | {n}条 | {cost}元/条 |

🔄 漏斗：开口→进线 {rate1}% | 进线→留资 {rate2}%

📊 趋势分析

| 指标 | 峰值 | 低谷 | 趋势 |
|------|------|------|------|
| 消耗 | {date} {fee}元 | {date} {fee}元 | {↑/↓/→} |
| 开口 | {date} {n}条 | {date} {n}条 | {↑/↓/→} |

趋势判断方法：比较前半段和后半段均值，上升↑、下降↓、持平→

📋 各账号汇总

| 账号 | 消耗 | 日均 | CTR | 开口 | 进线 | 留资 | 开口成本 |
|------|------|------|-----|------|------|------|---------|
| {name} | {fee}元 | {日均}元 | {ctr} | {n} | {n} | {n} | {cost}元 |

📅 逐日明细（仅范围 ≤14 天时展示）

| 日期 | 消耗 | 曝光 | 点击 | 开口 | 进线 | 留资 |
|------|------|------|------|------|------|------|
| {date} | {fee}元 | {imp} | {click} | {n} | {n} | {n} |

💡 数据洞察
{2-3 条趋势分析，语气直接，好的夸烂的骂}
例：
- "📈 本周消耗整体上升，日均 {avg}元，投放节奏不错，继续加量！"
- "🤬 {date} 消耗突然飙到 {fee}元（+{pct}%），但开口没涨，钱花哪去了？查查是不是被刷了"
- "💀 {name} 连续 {n} 天开口为 0，这个号就是白占坑位，赶紧下线"
- "😤 {name} 日均消耗才 {avg}元，跑了{n}天连个留资都没有，素材全部换掉重来"

📝 投放建议
{1-2 条激进建议，跑不起来就骂}
例：
- "🚀 整体成本可控，建议下周直接加预算30%，别浪费好数据"
- "😡 {name} 这周花了 {fee}元 才 {n} 个留资，留资成本 {cost}元，这号废了，建议直接停投重建"

对比报告模板（compare）

📊 数据对比 | {dateA} → {dateB}

📈 整体对比

| 指标 | {dateA} | {dateB} | 变化 |
|------|---------|---------|------|
| 💰 消耗 | {a}元 | {b}元 | {▲/▼ pct}% |
| ├ 标准投 | {a}元 | {b}元 | {▲/▼ pct}% |
| └ 简单投 | {a}元 | {b}元 | {▲/▼ pct}% |
| 👁 曝光 | {a} | {b} | {▲/▼ pct}% |
| 👆 点击 | {a} | {b} | {▲/▼ pct}% |
| 📊 CTR | {a}% | {b}% | {▲/▼ pct}% |
| 💬 开口 | {a}条 | {b}条 | {▲/▼ pct}% |
| 📞 进线 | {a}条 | {b}条 | {▲/▼ pct}% |
| 📋 留资 | {a}条 | {b}条 | {▲/▼ pct}% |

变化标记：▲ 上升 | ▼ 下降 | - 持平
变化幅度 >30% 时加 ⚠️ 标记

📋 各账号对比

| 账号 | 消耗变化 | 开口变化 | 进线变化 | 留资变化 |
|------|---------|---------|---------|---------|
| {name} | {▲/▼ pct}% | {▲/▼ pct}% | {▲/▼ pct}% | {▲/▼ pct}% |

{标注消耗增幅最大和降幅最大的账号}
🏆 增幅最大：{name}（消耗 {▲pct}%）
⚠️ 降幅最大：{name}（消耗 {▼pct}%）

💡 数据洞察
{2-3 条对比分析，语气直接}
例：
- "🔥 {name} 消耗涨 {pct}% 开口也跟着涨 {pct}%，这波放量放对了！"
- "🤬 {name} 消耗涨了 {pct}% 但开口只涨 {pct}%，钱越花越没效果，赶紧收一收"
- "💀 {name} 全面下降，消耗 {▼pct}%、开口 {▼pct}%，素材该换一轮了"
- "😤 {name} 留资连续两天挂零，这个号趁早别投了"

📝 投放建议
{1-2 条激进建议}

账号状态说明

报告质量要求（强制）

• 数字格式：消耗/成本保留 2 位小数；曝光/点击/开口等用整数；CTR 保留 2 位小数带 %
• 0 值处理：数量为 0 显示 0；单价为 0 或分母为 0 时显示 -
• 禁止：只贴原始 JSON、只列数字不分析、分析不提及具体账号名
• 必须包含「💡 数据洞察」和「📝 投放建议」两个板块
• 必须按「数据分析框架」逐项检查，命中规则的要写入报告
• 洞察要求：具体到账号名 + 数字，禁止笼统描述（如"部分账号表现不错"）
• 建议要求：具体可执行（如"暂停XX计划"），不要泛泛而谈（如"建议优化"）
• 当全部账号取数失败时，说明可能原因（网络/限流/接口），不要笼统说"授权过期"
• 当部分账号有数据时，基于有数据的账号给出分析

报告语气规范（必须遵守）

• 表情分级：好数据用 😎🔥🏆🚀💪；差数据用 ⚠️😐📉；烂数据用 🤬💀😡🔪；一直拉胯用 😤⚫
• 投放建议要大胆：目标激进跑量，跑得好就建议加预算放量，跑得烂就直接说"别投了"
• 不怕说重话：数据烂就直说烂，建议停投就说停投，不要委婉绕弯子
• 好的要夸：CTR高、转化好、成本低的账号要明确表扬，建议加量
• 差的要骂：连续多天0开口、开口成本超100、留资挂零的，直接开骂+给具体处理方案
• 决策导向：每条建议必须指向一个明确的投放动作（加预算/砍计划/换素材/停账号/换话术）

错误码与故障排查

API错误码

常见问题排查

1. 授权码5分钟过期

OAuth回调收到的 auth_code 只有5分钟有效期。必须在5分钟内执行 exchange-token，否则需要重新授权。

2. advertiser_id类型错误

API要求 advertiser_id 为整数，但配置文件和token文件中可能是字符串。SDK已做 int() 转换，如果直接调API需手动转换。

3. scope权限不足

调用计划/单元/创意管理接口时报403，是因为授权时scope只选了 report_service 和 ad_query。需要重新授权并包含 ad_manage。

4. 离线报表数据为空

离线报表是T+1数据，今天只能查昨天及更早的数据。查今天会返回空 data_list。

5. 批量超时

多账号同时取数触发QPS限流。确保每个账号之间 sleep(2) 秒。

6. token刷新失败但不影响使用

access_token还有30分钟以上有效期时，刷新失败不会中断请求。但如果持续失败，需在过期前重新授权。

快速使用

多账号配置

{
  "version": "multi_account_v1",
  "accounts": [
    {
      "key": "account_a",
      "name": "账号A名称",
      "advertiser_id": "广告主ID",
      "app_id": "应用ID",
      "app_secret": "应用Secret",
      "token_file": "./tokens/account_a.json",
      "enabled": true
    }
  ]
}

命令

# 账号管理
python3 account_manager.py list              # 查看账号列表
python3 account_manager.py add key name advertiser_id token_file [app_id] [app_secret]
python3 account_manager.py remove key        # 删除账号
python3 account_manager.py update key field value  # 更新账号信息（字段白名单校验）
python3 account_manager.py toggle key        # 启用/停用切换
python3 account_manager.py health-check      # 检查配置/token/API连通性
python3 account_manager.py verify            # 轻量配置格式校验（无API调用）

# 授权与token
python3 account_manager.py setup-guide           # 首次配置引导（环境自识别+6步完整指引）
python3 account_manager.py auth-url          # 生成全部账号授权链接
python3 account_manager.py auth-url <key>    # 生成指定账号授权链接
python3 account_manager.py exchange-token X  # 换取账号X的token
python3 account_manager.py refresh-all       # 批量刷新即将过期的token

# 数据报告
python3 account_manager.py report-today all  # 今日全部账号实时数据
python3 account_manager.py report-today <key>  # 今日单账号数据
python3 account_manager.py report-range 2026-06-15 2026-06-21 [all|key]  # 离线报表（指定日期范围，可选指定账号）
python3 account_manager.py compare 2026-06-21 2026-06-22 [all|key]  # 两天数据对比（可选指定账号）

# 广告管理
python3 account_manager.py campaigns [key]          # 列出推广计划
python3 account_manager.py campaign-start <key> <id1> [id2...]  # 启用计划
python3 account_manager.py campaign-stop <key> <id1> [id2...]   # 暂停计划
python3 account_manager.py units [key]              # 列出推广单元
python3 account_manager.py unit-bid <key> <unit_id> <出价元>    # 修改出价
python3 account_manager.py unit-start <key> <id1> [id2...]      # 启用单元
python3 account_manager.py unit-stop <key> <id1> [id2...]       # 暂停单元
python3 account_manager.py creatives [key]          # 列出创意
python3 account_manager.py creative-start <key> <id1> [id2...]  # 启用创意
python3 account_manager.py creative-stop <key> <id1> [id2...]   # 暂停创意
python3 account_manager.py budget <key>             # 查询账户预算
python3 account_manager.py budget-update <key> <金额元>  # 修改日预算
python3 account_manager.py auto-rules [key] [date]  # 运行自动优化规则

# 搜索词/关键词/多维度报表
python3 account_manager.py search-words <key> <start> <end>    # 搜索词报告（用户搜了什么词触发广告）
python3 account_manager.py keywords <key> <start> <end>        # 关键词效果报告（每个词消耗/转化）
python3 account_manager.py report-dim <key> <dim> <start> <end>  # 多维度报表(campaign/unit/creative/keyword/search_word)

# 关键词管理
python3 account_manager.py keyword-add <key> <unit_id> <词:出价...>  # 添加关键词（出价单位元）
python3 account_manager.py keyword-recommend <key> <种子词>          # 关键词推荐
python3 account_manager.py word-bags <key>                           # 查询词包列表

# 辅助命令
python3 account_manager.py history <key> [page]         # 操作历史记录
python3 account_manager.py campaign-groups <key>        # 广告组列表

# 智能优化建议
python3 account_manager.py optimize <key> [start] [end]  # 综合分析：关键词+搜索词+单元，输出优化建议

# 创意深度分析
python3 account_manager.py creative-analysis <key> [start] [end]  # 创意评分(S/A/B/C)+明星创意识别+烧钱诊断+行动建议

# 关键词深度分析
python3 account_manager.py keyword-analysis <key> [start] [end]  # 关键词评分+搜索词挖掘(拓词/否定词)+账号诊断

# 多账号效率仪表盘
python3 account_manager.py fleet-overview [start] [end]  # 全部账号效率排名+预算分配建议

# 智能周期对比
python3 account_manager.py period-compare [all|key] [wow|mom|d7|d14|yesterday]  # 环比/同比/近7天/近14天/昨日对比

# 一键日报
python3 account_manager.py daily-report [all|key] [date]  # 昨日vs前日对比+异常告警+行动建议

# 实时异常检测
python3 account_manager.py anomaly-guard [all|key]  # 7种异常规则实时扫描(消耗飙升/骤降/CTR崩溃/零活跃等)

# 时段分析
python3 account_manager.py hourly-analysis <key> [date]  # 按时段分析效果，找出最佳/最差投放时段

# 创意级自动规则执行
python3 account_manager.py auto-rules-execute [all|key] [date] [dry_run|execute]  # 创意级规则：暂停烧钱创意/提价明星创意/出价建议

自动优化规则配置（auto_rules_config.json）

auto_rules_config.json 定义了 10 条可配置的自动调整策略，auto-rules 和 auto-rules-execute 命令读取此文件。每条规则可通过 enabled 开关独立启用/禁用。

confirm_required=true 的规则在 auto-rules-execute 的 dry_run 模式下只输出建议不执行，需要人工确认后才实际操作。

深度分析与诊断引擎

评分体系（100分制）

creative-analysis 和 keyword-analysis 共用同一套评分架构：

评分模式：valid 数据≥2 条时用相对评分（基于账号基准线 avg_ctr / avg_open_cost / avg_consult 做乘数对比），<2 条时 fallback 到固定阈值。

分级：S≥80 / A=60-79 / B=40-59 / C<40。消耗<5元标记为数据不足。

创意诊断引擎（_diagnose_creative）

6种创意级诊断，按投放漏斗顺序：

5种账号级诊断：content_quality（整体CTR偏低）、traffic_volume（曝光不足）、dm_conversion（开口→进线转化差）、consult_quality（进线质量低）、cost_efficiency（整体成本偏高）。

关键词诊断引擎（_diagnose_keyword）

6种关键词诊断：low_ctr / ctr_ok_no_open / high_cost / low_volume / no_spend / efficient。

5种账号级诊断：keyword_quality / keyword_cost / negative_gap / harvest_opportunity / budget_concentration。

输出字段

JSON 输出中每个创意/关键词 entry 新增：

顶层新增 account_diagnostics（账号级诊断数组）、diagnostic_summary（诊断计数）、benchmarks（账号基准线）。

设计原则（重要）

评分和诊断逻辑禁止依赖可选平台组件。部分账号未配置留资组件（直接发跳转名片），此时 msg_leads=0 是正常状态而非异常。因此：

• msg_leads / lead_cost / lead_rate 仅保留为补充展示字段，不参与评分和诊断
• 不存在 consult_ok_no_lead（有进线无留资）类型的诊断
• 不存在 service_quality（服务质量）类型的账号诊断
• 报告模板中留资列正常展示，但分析结论不因留资为0而降级

回调服务器

授权流程需要先启动回调服务器接收auth_code：

python3 callback_server.py  # 监听 http://localhost:58080/callback
# Ctrl+C 可优雅停止

回调服务器功能：

• OAuth错误处理：用户拒绝授权时显示错误信息（不再静默忽略）
• state校验：警告不在配置列表中的 state 参数（不阻断保存）
• 保存失败处理：磁盘/权限错误时返回500页面和错误详情
• 路径保护：非 /callback 路径返回404提示，favicon返回204
• 请求日志：每条请求打印时间戳+路径，方便调试

注意：auth-url 命令会提示启动回调服务器，确保在授权前已启动。

OAuth 授权流程（新用户/重新授权）

授权链接格式（scope 必须用 JSON 数组，逗号不编码）：

https://ad-market.xiaohongshu.com/auth?appId={app_id}&scope=["report_service","ad_query","ad_manage","account_manage"]&redirectUri={回调地址}&state={account_key}

完整步骤：

1. 启动回调服务器: python3 callback_server.py  (监听 58080 端口)
2. 为每个账号生成授权链接并在浏览器中打开
3. 用户在小红书页面点击授权
4. 浏览器跳转到 http://localhost:58080/callback?auth_code=xxx&state=account_key
5. 运行 python3 account_manager.py exchange-token {account_key} 换取正式token

生成授权链接示例（Python）：

from urllib.parse import quote
scope = '["report_service","ad_query","ad_manage","account_manage"]'
scope_encoded = quote(scope, safe=',')
url = f"https://ad-market.xiaohongshu.com/auth?appId={app_id}&scope={scope_encoded}&redirectUri={quote(redirect_uri, safe='')}&state={account_key}"

Python SDK

from sdk import XiaohongshuJuguangSDK

# 初始化（必须指定account_key）
sdk = XiaohongshuJuguangSDK(account_key="account_a")

# 实时报表（今日数据）
sdk.get_realtime_report("account", start_date="2026-06-22", end_date="2026-06-22")

# 离线报表（T+1，历史数据）
sdk.get_offline_report("account", "2026-06-15", "2026-06-21", time_unit="DAY")
# 返回: data.aggregation_data (汇总), data.data_list (逐日, 日期字段是time)

# 计划管理
sdk.get_campaign_list()
sdk.get_all_campaigns()
sdk.update_campaign_status(campaign_ids=[123, 456], action_type=0)  # 0=暂停 1=启用

# 单元管理
sdk.get_unit_list()
sdk.update_unit_bid(event_bid_list=[{"unit_id": 123, "bid": 500}])

# 创意管理
sdk.search_creativity(status=2)  # 2=投放中
sdk.update_creativity_status(creativity_ids=[789], action_type=0)

# 账户
sdk.get_account_budget()
sdk.get_daily_cost("2026-06-21")  # 昨日消耗（标准投+简单投）
sdk.get_daily_cost_range("2026-06-15", "2026-06-21")  # 日期范围消耗

# Token刷新
sdk.refresh_access_token()

注意：所有返回结果中 success=True 表示成功，data 字段包含业务数据。失败时 success=False，检查 message 和 fetch_status。

SDK 自动映射与容错

创意层级端点名映射：小红书API的创意层级端点统一使用 creativity（如 /offline/creativity、/realtime/creativity、/creativity/search），而非直觉上的 creative。SDK 在 get_offline_report() 和 get_realtime_report() 内部自动执行 api_type = 'creativity' if report_type == 'creative' else report_type，调用方传 'creative' 或 'creativity' 均可，无需手动转换。

auth-url app_id 回退：auth_url() 命令生成授权链接时，优先使用账号级 app_id（account['app_id']）。若账号未配置，自动回退到全局配置（conf['app_id']）。两者都没有时输出空字符串并警告，不会 KeyError 崩溃。

回调地址自动推导：redirect_uri 按以下优先级确定——账号级 redirect_uri > 全局级 redirect_uri > callback_port 自动生成（http://localhost:{port}/callback）> 默认 58080 端口。大多数用户只需在 accounts.json 中设置 callback_port 即可。

接口覆盖

定时监控配置（推荐方案）

适用于 OpenClaw 等 24 小时运行平台的定时任务配置：

推荐定时策略

OpenClaw 配置示例

在 OpenClaw 的定时任务中，按以下方式配置：

# 早报（每天上午10点）
python3 account_manager.py report-today all

# 晚报（每天下午6点）
python3 account_manager.py report-today all

# Token 自动刷新（每天凌晨6点）
python3 account_manager.py refresh-all

# 健康检查（每天上午8点）
python3 account_manager.py health-check

注意事项

• report-today 取数耗时：每个账号约 5-8 秒（含QPS延迟和重试），4个账号约 30 秒。定时任务需预留足够超时时间。
• 离线报表只能查T-1：今天只能查昨天及更早的数据，查今天用 report-today。
• Token 刷新与取数分离：建议 refresh-all 和 report-today 间隔 2 小时以上，避免刷新和取数同时进行。
• 连续失败保护：report-today 内置连续失败检测——如果前 2 个账号都失败，会等待 5 分钟后重试一次，而不是继续浪费 QPS 配额。

安全说明

包内不含真实 token/secret/advertiser_id。真实配置在本地 accounts.json 中自行填写。

更新日志

v6.3.0

• 简单投长周期聚合漏算修复：/data/report/offline/easy/promotion/base 接口在查询超过15天的日期范围时，aggregation_data 汇总数据会漏算部分天的消耗。新增 _fetch_easy_summary() 公共函数，自动将日期范围按15天一段拆分查询并合并，首段取 aggregation_data，后续段从 data_list 逐日累加
• 修复覆盖5个函数：report-range（离线报表）、creative-analysis（创意分析）、keyword-analysis（关键词分析）、fleet-overview（多账号总览）、period-compare（周期对比mom可达31天），统一使用分段查询
• 新增 _split_date_chunks() 工具函数：通用的日期范围分段，可被其他函数复用
• null trap 批量修复（上一版本延续）：.get('key', default) 当key存在但值为null时返回None而非default的问题，全部替换为 or {} / or [] 模式（共14处修复）
• fee 精度修复：所有 fee 提取统一使用 round(float(...), 2)，消除浮点精度导致的几毛到几块偏差（sdk.py 4处 + account_manager.py 10处）
• 标准投分页兼容：新增4种分页参数回退策略（page_num、flat page、page_index=0、bypass cache），以及响应字段自动发现机制
• 简单投计划回退：标准投计划列表为空时，自动从简单投标组接口拉取计划作为补充

v6.2.0

• 回调端口可配置：新增 callback_port 字段（默认 58080），不再硬编码端口。用户可自选端口，在小红书开放平台创建应用时填写对应回调地址
• 回调地址自动推导：redirect_uri 由 callback_port 自动生成，优先级：账号级 > 全局级 > callback_port 自动生成
• 新增 setup-guide 命令：首次配置指引，打印完整 6 步引导（选端口→创建应用→配置→启动回调→授权→换token）
• callback_server.py 动态读端口：从 accounts.json 读取 callback_port，修改后重启生效
• verify 配置检查更新：有 callback_port 时不再警告缺少 redirect_uri
• get_daily_cost() 修复：返回结果新增 success 字段，调用方可正确判断成功/失败
• 创意报表 404 修复：离线/实时报表的创意层级端点从 /offline/creative 修正为 /offline/creativity（与小红书API一致），SDK 层自动映射，所有调用方（creative-analysis/creative-dim/auto-rules）无需改动
• auth-url app_id 回退修复：账号未配 app_id 时自动使用全局配置，不再 KeyError 崩溃
• 环境自识别：setup-guide 自动检测本地/云端环境，云端部署给出内网穿透或本地回调两种方案

v6.1.0

• 简单投实时API全面接入：Playwright抓取官方文档站100个API接口页面，新增完整API目录(含articleId索引)
• SDK新增6个简单投实时方法：get_easy_realtime_group/campaign/note/keyword/summary + get_daily_cost()改用实时API
• report_today改用简单投实时：今日简单投数据从离线(/offline/easy/promotion/base)切换到实时(/realtime/ube/group)，新增easy_msg/easy_initiative_msg/easy_msg_leads字段
• 数据源选择规则：明确今日用实时API、历史用离线API的选择逻辑，避免今日简单投数据丢失
• 官方API完整目录：SKILL.md新增100个接口分类索引（OAuth 5个、账户服务 8个、投放管理 18个、离线报表 13个、实时报表 10个、素材管理 31个、工具 10个、附录 4个）

• 报告模板可视化升级：Markdown 表格替代纯文本框，支持飞书/IM 渲染
• 新增三种报告模板：日报（report-today）、范围报告（report-range）、对比报告（compare）
• 新增数据分析框架：7 项自动分析规则（消耗异常、CTR 预警、开口/留资成本、漏斗转化率、账号排名）
• 新增客资分析专区：开口/进线/留资成本单价、漏斗转化率（开口→进线→留资）
• 新增 QoderWork HTML Widget 模板（assets/report_widget.html）
• 消耗 = 标准投 + 简单投：所有报告默认展示总消耗（标准投+简单投），同时拆分明细
• 新增 13 个广告管理 CLI 命令：计划/单元/创意的列出、启用、暂停，单元出价修改，预算查询/修改，自动优化规则引擎接入
• 新增 9 个优化分析 CLI 命令：搜索词报告(search-words)、关键词效果报告(keywords)、多维度报表(report-dim)、关键词添加(keyword-add)、关键词推荐(keyword-recommend)、词包查询(word-bags)、操作历史(history)、广告组列表(campaign-groups)、智能优化建议(optimize)
• 智能优化引擎：optimize 命令综合分析关键词(高消耗低转化/高开口成本/优质词)、搜索词(否定词挖掘/拓词推荐)、单元(贵单元/零消耗单元)数据，输出分级建议(high/medium/low)
• 创意深度分析：creative-analysis 命令——100 分制多维度评分(CTR 25分+开口成本 30分+漏斗转化 25分+消耗效率 20分)→S/A/B/C 星级分级→明星创意识别(建议提取复用加投)→烧钱创意诊断(消耗>20元0开口建议暂停)→消耗集中度预警→潜力创意提价建议
• 创意诊断引擎：6种创意级诊断(low_impression/low_ctr/ctr_ok_no_open/open_ok_no_consult/high_cpc/efficient)+5种账号级诊断(content_quality/traffic_volume/dm_conversion/consult_quality/cost_efficiency)，自动识别投放漏斗瓶颈
• 关键词深度分析：keyword-analysis 命令——关键词评分(CTR 25+开口成本 30+消耗效率 25+转化能力 20)→搜索词挖掘(拓词推荐+否定词发现)→6种关键词诊断→5种账号级诊断
• 多账号效率仪表盘：fleet-overview 命令——跨账号效率排名(开口成本排序)→预算分配建议(最优账号加投/最差账号减投)→综合评分
• 智能周期对比：period-compare 命令——5种预设(wow/mom/d7/d14/yesterday)自动计算日期范围→全指标变化百分比→异常标记
• 一键日报：daily-report 命令——昨日vs前日自动对比→4种异常告警(消耗飙升/骤降/开口成本异常/CTR崩溃)→最多5条行动建议
• 实时异常检测：anomaly-guard 命令——7种异常规则(消耗飙升/骤降/CTR崩溃/零活跃/开口成本异常/曝光骤降/预算节奏)→今日实时+昨日基线仅需2次API调用
• 时段分析：hourly-analysis 命令——按时段效果分析→最佳/最差时段识别→投放时段建议
• 创意级自动规则：auto-rules-execute 命令——CreativeRuleEngine 6条规则(烧钱暂停/明星提价/高出价预警/低CTR标记/集中度风险/零进线标记)→dry_run/execute双模式→每次最多暂停5个创意+3条出价建议
• 范围报告新增：汇总概况（合计+日均）、趋势分析（峰值/低谷/方向）、逐日明细表格
• 对比报告新增：▲▼ 变化标记、>30% 异常高亮、增幅/降幅最大账号标注
• 报告质量要求升级：数字格式规范、0 值处理规则、洞察必须带具体账号名和数字
• 简单投数据补全：7个新功能(creative-analysis/keyword-analysis/fleet-overview/period-compare/daily-report/anomaly-guard/hourly-analysis)全部补上简单投数据拉取——账号级函数合并标准投+简单投=总消耗(含normal_fee/easy_fee拆分)，维度级函数(creative/keyword无简单投维度)输出account_easy_summary账号级汇总。anomaly-guard实时对比改用标准投基准线避免误报。

v6.0.0

• 多账号架构（每个账号独立 app_id/app_secret/token/advertiser_id）
• OAuth 授权：scope JSON 数组格式、camelCase 参数名、auth-url 命令生成授权链接
• 回调服务器：OAuth 错误处理、state 校验、保存异常捕获、路径保护、请求日志
• Token 生命周期管理：自动刷新（带重试）、过期不误报、refresh_token 预警
• 实时报表：多账号并行取数 + QPS 延迟 + 失败重试 + 三态判定
• 离线报表：T+1 数据（aggregation_data 汇总 / data_list 逐日，日期字段 time）
• 数据报告命令：report-today、report-range、compare（两天对比+百分比变化）
• 账号管理命令：add/remove/update（字段白名单校验）/toggle/health-check/refresh-all
• SDK：advertiser_id 全量 int() 转换 + 空值 fallback 到 accounts.json、内存缓存、__repr__ 调试
• SDK 字段安全：所有字段统一 or 兜底防 None（ctr/fee/impression/click 等）
• QPS 限流防护：账号间隔 2s、重试前 3s、分页间隔 1s、翻页/逐日查询间 1s
• 私信四字段区分：msg_leads_num（留资）、message_consult（进线）、initiative_message（开口）、message（消息量）
• Windows GBK 编码兼容（全文件）
• 错误码表 + 6 条常见问题排查