广告洞察中枢（Ad Insight Hub）

面向广告投放与市场分析场景的结构化广告情报数据中枢。在原始 API 之上叠加参数翻译、依赖编排、缓存复用、可信度标注四层能力，让 Agent 用最少的往返拿到最可用的数据.

付费版专享能力

依赖说明

运行环境

• Agent 平台: 支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统: Windows / macOS / Linux
• 网络: 需可访问 https://api.admapix.com

依赖项

可用性分类

• 分类: MD+EXEC（Markdown 指令驱动，需 exec 执行 curl 命令）
• 说明: 基于自然语言指令驱动 Agent 调用 AdMapix API，透传结构化 JSON

缓存策略

核心能力

1. 广告创意搜索/计数/分布

按关键词、国家、行业、创意类型多维度检索广告创意。page_size 上限 10 自动钳制；配额紧张时优先用 count 替代 search 降低消耗。支持创意分布维度查询（distribute / distribute-dims）与创意关联应用反查（item-apps）. 输入: 用户提供广告创意搜索/计数/分布所需的指令和必要参数. 处理: 解析广告创意搜索/计数/分布的输入参数,执行核心处理逻辑,返回结构化结果和执行状态. 输出: 返回广告创意搜索/计数/分布的处理结果,包含执行状态码、结果数据和执行日志.

2. 应用与开发者画像

统一产品搜索（unified-product-search）、应用详情（app-detail）、开发者详情（developer-detail）、相似应用（similar-apps）、SDK 详情（sdk-detail）；支持从创意 ID 反查关联应用（item-apps）。- 验证返回数据的完整性和格式正确性

3. 商店榜单查询

应用商店免费/付费/畅销榜单（store-rank），按类目与国家筛选；通用榜单（generic-rank）支持自定义维度聚合. 输入: 用户提供商店榜单查询所需的指令和必要参数. 处理: 解析商店榜单查询的输入参数,执行核心处理逻辑,返回结构化结果和执行状态. 输出: 返回商店榜单查询的处理结果,包含执行状态码、结果数据和执行日志.

4. 下载与收入估算（带可信度分级）

按日期（download-date / revenue-date）、详情（download-detail / revenue-detail）、国家（download-country / revenue-country）维度查询第三方估算数据；强制附 A/B/C 三级可信度标注：

• A 级：多源交叉方差 < 10%，可用于定量对比
• B 级：单源方差 10%-25%，可用于趋势参考
• C 级：长尾方差 > 25%，仅用于方向性判断

输入: 用户提供下载与收入估算（带可信度分级）所需的指令和必要参数. 处理: 解析下载与收入估算（带可信度分级）的输入参数,执行核心处理逻辑,返回结构化结果和执行状态. 输出: 返回下载与收入估算（带可信度分级）的处理结果,包含执行状态码、结果数据和执行日志.

5. 参数自然语言翻译与端点编排

内置 40+ 行业码与 200+ 国家码中文映射；端点依赖图自动并行化无依赖调用、串行化有依赖调用，单轮可编排 5-10 个端点. 输入: 用户提供参数自然语言翻译与端点编排所需的指令和必要参数. 输出: 返回参数自然语言翻译与端点编排的处理结果,包含执行状态码、结果数据和执行日志。- 验证返回数据的完整性和格式正确性

• 参考参数自然语言翻译与端点编排的配置文档进行参数调优

参数映射表

行业码（trade_level1）

国家/地区码

未列出的参数请调 GET /api/data/filter-options 获取最新码表.

端点依赖编排

独立可并行（首轮一次性发出）：
  filter-options / distribute-dims / screen-types / page-config
  search / count / count-all / distribute
  market-search / unified-product-search / company-search
# ...
依赖前序结果（必须串行）：
  content-detail    ← 依赖 search 返回的创意 ID
  item-apps         ← 依赖 search 返回的创意 ID
  app-detail        ← 依赖 unified-product-search 或 item-apps 返回的 unifiedProductId
  developer-detail  ← 依赖 app-detail 返回的开发者 ID
  similar-apps / sdk-detail ← 依赖 app-detail

编排规则：

1. 首轮：把所有无依赖查询一次性并行发出（建议 5-8 个并发）
2. 解析首轮结果，提取 ID
3. 第二轮：基于 ID 的详情查询并行发出
4. 配额紧张时：用 count 替代 search，用 count-all 替代多次 distribute

适用场景

不适用于：H5/落地页/卡片/仪表盘生成、托管式深度研究与自主多步研究、数据分析/推荐（除非用户在收到数据后明确要求）

使用流程

Step 1：检查 API Key（永不打印值）

[ -n "${ADMAPIX_API_KEY:-}" ] && echo ok || echo missing

Step 2：缺失时引导配置

需要先配置 AdMapix API Key：

1. 访问 https://www.admapix.com 注册并登录
2. 在控制台 API Keys 创建 Key
3. 终端环境变量：export ADMAPIX_API_KEY="你的Key"
4. 配置完成后重新发起查询

安全红线：永不接受/回显/存储来自聊天输入的 Key；永不将 Key 写入日志或链接参数；Key 仅作为 X-API-Key 请求头使用.

Step 3：解析用户意图，翻译为 API 参数

将自然语言中的行业、国家、创意类型等翻译为 API 代码。未列出的参数调 GET /api/data/filter-options 获取.

Step 4：按依赖图编排端点

首轮并行发出无依赖查询，提取 ID 后第二轮并行发出详情查询。配额紧张时切换为 count 计数模式.

Step 5：透传结果并标注可信度

• 原始结构化 JSON 透传，不重命名、不丢弃、不总结、不排序、不评论
• 空列表是合法结果（无匹配），非错误
• 估算数据必须附："本数据为第三方估算，可能存在 10%-30% 偏差，仅供参考" + 可信度分级

案例展示

案例1：竞品创意监控

场景：买量团队需要监控某竞品最近 7 天在美国的视频创意变化

编排：

1. POST /api/data/product-search → 拿到竞品 unifiedProductId
2. POST /api/data/product-content-search（filter: 7d, US, video=010）
3. POST /api/data/product-content-counts（同条件）→ 拿到总量
4. 对比上次缓存的创意 ID 列表，仅对新增项调 content-detail

# Step 1: 搜索竞品产品
curl -s -X POST "https://api.admapix.com/api/data/product-search" \
  -H "X-API-Key: ${ADMAPIX_API_KEY}" -H "Content-Type: application/json" \
  -d '{"keyword":"竞品名称","page":1,"page_size":10}'
# ...
# Step 2: 查询近7天美国视频创意
curl -s -X POST "https://api.admapix.com/api/data/product-content-search" \
  -H "X-API-Key: ${ADMAPIX_API_KEY}" -H "Content-Type: application/json" \
  -d '{"unifiedProductId":"xxx","countries":["US"],"adTypes":["010"],"dateRange":"7d","page":1,"page_size":10}'

输出：

{
  "new_creatives_count": 12,
  "creatives": [
    {"id": "ad_001", "url": "https://...", "first_seen": "2026-07-15", "type": "video"},
    {"id": "ad_002", "url": "https://...", "first_seen": "2026-07-16", "type": "video"}
  ],
  "distribution_change": {"video": "+8", "image": "+4"}
}

分析：7 天内新增 12 条视频创意，视频类创意增长 8 条，图片类增长 4 条，竞品正在加大视频素材投放力度.

案例2：跨地区选品对比

场景：出海团队需要对比美国和东南亚三消类游戏的下载与收入

编排（首轮 4 个请求并行）：

# 美国下载估算
curl -s -X POST "https://api.admapix.com/api/data/download-country" \
  -H "X-API-Key: ${ADMAPIX_API_KEY}" -H "Content-Type: application/json" \
  -d '{"countries":["US"],"trade_level1":["602"],"genre":["match3"],"dateRange":"30d"}'
# ...
# 东南亚下载估算（多国合并）
curl -s -X POST "https://api.admapix.com/api/data/download-country" \
  -H "X-API-Key: ${ADMAPIX_API_KEY}" -H "Content-Type: application/json" \
  -d '{"countries":["TH","VN","ID","PH","MY"],"trade_level1":["602"],"genre":["match3"],"dateRange":"30d"}'
# ...
# 美国收入估算
curl -s -X POST "https://api.admapix.com/api/data/revenue-country" \
  -H "X-API-Key: ${ADMAPIX_API_KEY}" -H "Content-Type: application/json" \
  -d '{"countries":["US"],"trade_level1":["602"],"genre":["match3"],"dateRange":"30d"}'
# ...
# 东南亚收入估算
curl -s -X POST "https://api.admapix.com/api/data/revenue-country" \
  -H "X-API-Key: ${ADMAPIX_API_KEY}" -H "Content-Type: application/json" \
  -d '{"countries":["TH","VN","ID","PH","MY"],"trade_level1":["602"],"genre":["match3"],"dateRange":"30d"}'

输出：表格对比，每行附可信度分级

分析：美国市场下载量与收入均显著高于东南亚，ARPU 差距约 5 倍。东南亚数据为 C 级可信度，仅用于趋势判断.

案例3：开发者画像与 SDK 审计

场景：投资调研团队需要调研某开发者旗下所有应用的 SDK 使用情况

编排：

1. POST /api/data/company-search → 拿到开发者 ID
2. GET /api/data/developer-detail → 拿到旗下应用列表
3. （并行）对每个应用 GET /api/data/sdk-detail
4. 聚合：SDK 使用频次、共享 SDK、独家 SDK

# Step 1: 搜索开发者
curl -s -X POST "https://api.admapix.com/api/data/company-search" \
  -H "X-API-Key: ${ADMAPIX_API_KEY}" -H "Content-Type: application/json" \
  -d '{"keyword":"开发者名称","page":1,"page_size":10}'
# ...
# Step 3: 并行查询每个应用的SDK（示例）
curl -s "https://api.admapix.com/api/data/sdk-detail?unifiedProductId=app_001" \
  -H "X-API-Key: ${ADMAPIX_API_KEY}"

输出：SDK 矩阵表（应用 x SDK）+ 供应链风险提示

分析：Firebase 被 3 个应用共享，若下线影响范围最广；App C 未集成 AppsFlyer，归因数据可能不完整.

错误处理

常见问题

Q1：为什么我的 page_size=50 被改成了 10？

A：创意搜索端点强制上限 10，本技能自动钳制。翻页请用 page 参数递增，建议配合缓存避免重复消耗配额.

Q2：下载/收入数字和官方财报对不上？

A：本数据为第三方估算，非官方披露。请参考可信度分级（A/B/C），C 级数据仅用于趋势判断，不用于精确决策。长尾地区偏差可达 30%+.

Q3：如何批量导出某竞品全部创意？

A：先用 product-content-counts 拿到总量，再分页 product-content-search（每页 10），结果写入本地文件。建议在夜间低峰执行，避免限流。100 条创意需 10 次请求.

Q4：totalSize 为什么是 null？

A：过滤查询时 totalSize 可能为 null，此时以 list 长度为准，或单独调 count 端点获取准确总数.

Q5：多个国家的数据能一次请求拿到吗？

A：search / distribute 支持 countries 数组，但结果会合并。如需分别对比，请并行发多个单国家请求，首轮并发 5-8 个.

Q6：缓存数据过期了怎么办？

A：元数据缓存 24 小时、搜索结果 1 小时、详情 7 天。过期后自动重新拉取。如需强制刷新，删除 ~/.admapix-cache/ 对应目录.

已知限制

1. 单次请求单端点：本技能保持薄客户端语义，多端点编排由 Agent 层完成，不内置批量端点聚合
2. 估算数据非官方：下载/收入均为第三方估算，长尾地区偏差可达 30%+，不可作为财务依据
3. page_size 硬上限 10：翻页 100 条需 10 次请求，配额消耗较快，需配合缓存策略
4. 元数据需定期刷新：行业码/国家码映射表为内置快照，未列出的参数需调 filter-options 获取最新
5. 不做分析与推荐：仅透传结构化数据，不生成 H5/仪表盘/深度研究报告，分析与推荐需用户明确要求后另起