---

slug: ad-insight-hub
name: ad-insight-hub
version: 1.0.0
displayName: 广告洞察中枢
summary: 解决广告情报API参数难懂、调用低效、数据孤岛的广告创意数据中枢。广告创意数据中枢：聚合AdMapix广告情报API，提供参数自然语言翻译（40+行业码/200+国家码）、端点依赖编排（并行
license: MIT
description: |-. 当需要ad insight hub相关能力的开发场景,提供结构化工作流程和配置说明. 该工具经过深度优化,基于用户反馈改进了实用性和可操作性。Use。Use when 需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于实时流数据处理。适用于独立开发者、企业团队和自动化工作流场景。支持中文交互，无需复杂配置即开即用。
  when 需要数据分析、报表生成、统计洞察、数据可视化需求。不适用于流式数据处理。适用于开发者、企业团队和自动化集成场景。。解决广告情报API参数难懂、调用低效、数据孤岛的广告创意数据中枢。广告创意数据中枢：聚合AdMapix广告情报API，提供参数自然语言翻译（40+行业码/200+国家码）、端点依赖编排（并行'
tags:
- 广告情报
- 数据API
- 市场分析
- 创意监控
- AI代理
- 自动化
- 智能
- api
- sdk
- key
tools:
- read
- exec
- write
- glob
- grep
homepage: ''
category: Agents
pricing_tier: free

---

> **核心功能**: 本技能提供中文交互、化工作流场景等能力。

# 广告洞察中枢（Ad Insight Hub）

面向广告投放与市场分析场景的**结构化广告情报数据中枢**。在原始 API 之上叠加参数翻译、依赖编排、缓存复用、可信度标注四层能力，让 Agent 用最少的往返拿到最可用的数据.
## 核心功能特性
### 1. 广告创意搜索/计数/分布
按关键词、国家、行业、创意类型多维度检索；`page_size` 上限 10 自动钳制；配额紧张时优先用 `count` 替代 `search` 降低消耗

**处理**: 解析广告创意搜索/计数/分布的输入参数,完成核心逻辑,返回格式化结果.
**输出**: 返回广告创意搜索/计数/分布的响应数据,包含状态信息、结果数据和执行记录.
### 2. 应用与开发者画像
统一产品搜索、应用详情、开发者详情、相似应用、SDK 详情；支持从创意 ID 反查关联应用（`item-apps`）

**处理**: 解析应用与开发者画像的输入参数,完成核心逻辑,返回格式化结果.
**输出**: 返回应用与开发者画像的响应数据,包含状态信息、结果数据和执行记录.
### 3. 商店榜单查询
应用商店免费/付费/畅销榜单，按类目与国家筛选（`store-rank` / `generic-rank`）

**处理**: 解析商店榜单查询的输入参数,完成核心逻辑,返回格式化结果.
**输出**: 返回商店榜单查询的响应数据,包含状态信息、结果数据和执行记录.
### 4. 下载与收入估算（带可信度分级）
按日期/详情/国家维度查询第三方估算数据；强制附 A/B/C 三级可信度标注（A=多源交叉方差<10%，B=单源方差10%-25%，C=长尾方差>25%）

**处理**: 解析下载与收入估算（带可信度分级）的输入参数,完成核心逻辑,返回格式化结果.
**输出**: 返回下载与收入估算（带可信度分级）的响应数据,包含状态信息、结果数据和执行记录.
- `input_params`参数控制执行,支持创建/查询/导出
### 5. 参数自然语言翻译与端点编排
内置 40+ 行业码与 200+ 国家码中文映射；端点依赖图自动并行化无依赖调用、串行化有依赖调用，单轮可编排 5-10 个端点

**处理**: 解析参数自然语言翻译与端点编排的输入参数,完成核心逻辑,返回格式化结果.
**输出**: 返回参数自然语言翻译与端点编排的响应数据,包含状态信息、结果数据和执行记录.
- `input_params`参数控制执行,支持创建/查询/导出
**能力覆盖范围**：能力范围包括以下关键词：解决广告情报、API、参数难懂、调用低效、数据孤岛的广告创、意数据中枢、广告创意数据中枢、AdMapix、广告情报、端点依赖编排、串行自动调度、结果缓存复用、估算数据可信度、分级标注四层核心、适用于买量团队竞、品创意监控、出海选品调研、广告素材趋势分析、开发者画像与、跨地区投放策略制、适用关键词、应用榜单、下载估算等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.
## 初始设定
1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

> 详细的输入输出格式请参考下方章节说明。

## 场景示例
**何时使用**：
- 买量团队竞品创意监控（新增创意追踪、素材分布变化）
- 出海应用市场选品（跨地区下载/收入对比）
- 广告素材趋势分析（创意类型分布、投放量变化）
- 开发者画像调研与 SDK 供应链审计
- 跨地区投放策略制定（多国家并行对比）

**输入**：自然语言查询意图 + `ADMAPIX_API_KEY` 环境变量
**输出**：结构化 JSON（透传 API 字段名，估算数据附可信度分级与"第三方估算"声明）

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

## 使用说明
### Step 1：检查 API Key（永不打印值）
## 输入定义
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| input | string | 是 | 广告洞察中枢处理的输入数据或指令 |
| options | object | 否 | 附加配置选项,如模式选择、格式偏好等 |
| callback_url | string | 否 | 异步处理完成后的回调通知URL |

```bash
[ -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 参数
内置高频参数映射表（节选）：

| 自然语言 | 代码 | 自然语言 | 代码 |
|:-----|:-----|:-----|:-----|
| 游戏 | 602 | 美国 | US |
| 金融 | 607 | 日本 | JP |
| 电商 | 601 | 韩国 | KR |
| 工具 | 603 | 德国 | DE |
| 社交 | 604 | 东南亚 | TH/VN/ID/PH/MY |
| 娱乐 | 609 | 中东 | SA/AE/TR/EG |
| 视频(创意类型) | 010 | 拉美 | BR/MX/AR/CO |

未列出的参数请调 `GET /api/data/filter-options` 获取最新码表.
### 依赖详情
```text
独立可并行（首轮一次性发出）：
  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`

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

#
## 用法示例
### 示例(补充)

**输入**："监控某竞品最近 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`

**输出**：
```json
{
  "new_creatives_count": 12,
  "creatives": <参数说明>,
  "distribution_change": {"video": "+8", "image": "+4"}
}
```

### 示例二：跨地区选品对比

**输入**："对比美国和东南亚三消类游戏的下载与收入"

**编排（首轮 6 个请求并行）**：
```bash
curl -X POST "https://api.admapix.com/api/data/download-country" \
  -H "X-API-Key: ${ADMAPIX_API_KEY}" -d '{"countries":["US"],"trade_level1":["602"]}'
admapix.com/api/data/download-country" \
  -d '{"countries":["TH","VN","ID","PH","MY"],"trade_level1":["602"]}'
admapix.com/api/data/revenue-country" \
  -d '{"countries":["US"],"trade_level1":["602"]}'
# ... 其余 3 个请求
```

**输出**：表格对比，每行附可信度分级（美国 A 级，东南亚聚合 C 级）

### 示例三：开发者画像与 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

**输出**：SDK 矩阵表（应用×SDK）+ 供应链风险提示（如某 SDK 被多个应用共享，下线影响范围）

## 错误恢复方案
| 场景 | 原因 | 处理方式 |
|---:|---:|---:|
| 401 INVALID_API_KEY | Key 缺失/格式错/已禁用 | 不执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，引导用户检查 Key；永不打印 Key |
| 403 FORBIDDEN | 权限不足或套餐限制 | 不执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，提示升级套餐 |
| 429 RATE_LIMITED | 触发限流 | 指数退避执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令（1s/2s/4s），最多 3 次；降低并发到 3 |
| 400 INVALID_PARAM | 参数代码错误 | 不执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，对照 `filter-options` 检查国家/行业码 |
| 5xx INTERNAL | 服务端错误 | 指数退避执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，最多 2 次 |
| 一直返回空 list | 参数代码错误 | 调 `filter-options` 核对国家/行业码 |
| 详情接口 404 | 创意已下线 | 跳过该 ID，记录到失败列表 |
| 估算数据明显异常 | 长尾地区样本稀疏 | 标注 C 级可信度，仅供参考 |
| 配额剩余 < 10% | 接近调用上限 | 切换为 `count` 计数模式，元数据查询命中本地缓存 |

## 环境要求
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:---:|:---:|:---:|:---:|
| AdMapix API | 远程 HTTP API | 必需 | https://www.admapix.com 注册获取 |
| ADMAPIX_API_KEY | 环境变量 | 必需 | 控制台 API Keys 创建；仅作 `X-API-Key` 请求头 |
| curl 或等价 HTTP 客户端 | 命令行工具 | 必需 | 系统自带或包管理器安装 |
| jq | JSON 处理工具 | 可选 | 提升结果可读性 |
| Agent 平台 | 运行环境 | 必需 | Claude Code / Cursor / Codex / Gemini CLI 等 |
| 网络 | 运行环境 | 必需 | 需可访问 `https://api.admapix.com` |

**缓存策略**：元数据缓存 24 小时，创意搜索结果缓存 1 小时，创意详情缓存 7 天，下载/收入估算缓存 1 天，榜单数据缓存 6 小时。缓存位置 `~/.admapix-cache/`.
**可用性分类**：MD+EXEC（Markdown 指令驱动，需 exec 执行 curl 命令）

## 疑问解答
**Q1：为什么我的 `page_size=50` 被改成了 10？**
A：创意搜索端点强制上限 10，本技能自动钳制。翻页请用 `page` 参数递增，建议配合缓存避免重复消耗配额.
**Q2：下载/收入数字和官方财报对不上？**
A：本数据为第三方估算，非官方披露。请参考可信度分级（A/B/C），C 级数据仅用于趋势判断，不用于精确决策.
**Q3：如何批量导出某竞品全部创意？**
A：先用 `product-content-counts` 拿到总量，再分页 `product-content-search`（每页 10），结果写入本地文件。建议在夜间低峰执行，避免限流.
**Q4：`totalSize` 为什么是 null？**
A：过滤查询时 `totalSize` 可能为 null，此时以 `list` 长度为准，或单独调 `count` 端点获取准确总数.
**Q5：多个国家的数据能一次请求拿到吗？**
A：`search` / `distribute` 支持 `countries` 数组，但结果会合并。如需分别对比，请并行发多个单国家请求.
## 能力边界
1. **单次请求单端点**：本技能保持薄客户端语义，多端点编排由 Agent 层完成，不内置批量端点聚合
2. **估算数据非官方**：下载/收入均为第三方估算，长尾地区偏差可达 30%+，不可作为财务依据
3. **`page_size` 硬上限 10**：翻页 100 条需 10 次请求，配额消耗较快，需配合缓存策略
4. **元数据需定期刷新**：行业码/国家码映射表为内置快照，未列出的参数需调 `filter-options` 获取最新
5. **不做分析与推荐**：仅透传结构化数据，不生成 H5/仪表盘/深度研究报告，分析与推荐需用户明确要求后另起

## 安全保证声明
| 风险类型 | 防范措施 |
|----------|---------|
| API密钥泄露 | 使用环境变量注入,不得在源码中明文写入 |
| 命令执行风险 | 只运行安全清单内命令,禁止拼接用户输入 |
| 网络通信安全 | 采用HTTPS加密传输并校验证书 |
| 敏感数据暴露 | 输出不含敏感凭据 |

使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。

## 量化评估
| 操作场景 | 手动耗时 | 自动化耗时 | 效率提升 |
|----------|---------|-----------|---------|
| 文件解析与提取 | 5-10分钟/个 | <5秒/个 | 60-120x |
| 批量文件处理(100个) | 8-16小时 | <5分钟 | 96-192x |
| API调用与响应解析 | 2-3分钟/次 | <1秒/次 | 120-180x |
| 多接口数据聚合 | 15-30分钟 | <10秒 | 90-180x |
| 命令执行与结果收集 | 3-5分钟/次 | <2秒/次 | 90-150x |
| 重复任务批量执行 | 因任务而异 | 线性缩减 | 5-50x |
| 错误排查与修复 | 10-30分钟 | <30秒 | 20-60x |

## 优势分析
| 对比维度 | 广告洞察中枢 | 传统手动方式 | 通用脚本工具 |
|---------|------------|-------------|------------|
| 自动化程度 | 全流程自动 | 完全手动 | 部分自动 |
| 错误处理 | 内置错误恢复 | 依赖人工经验 | 基本try-catch |
| 可复用性 | 参数化配置 | 一次性脚本 | 模板化 |
| 安全合规 | 内置安全检查 | 无安全保障 | 无安全保障 |
| 适用场景 | 解决广告情报API参数难懂、调用低效、数据孤岛的广告创意数据中枢。广告创意数据中 | 通用场景 | 通用场景 |

## 主要特性
- **自动化执行**: 解决广告情报API参数难懂、调用低效、数据孤岛的广告创意数据中枢。广告创意数据中枢：聚合AdMapix广告情报API，提
- **文件处理**: 支持多种文件格式的读取、解析和写入操作
- **API集成**: 通过标准化接口调用外部服务并处理响应
- **命令执行**: 在安全沙箱中执行系统命令并收集结果
- **信息检索**: 快速搜索和过滤目标数据

## 功能介绍
广告创意数据中枢：聚合AdMapix广告情报API，提
- **文件处理**: 支持多种文件格式的读取、解析和写入操作
- **API集成**: 通过标准化接口调用外部服务并处理响应
- **命令执行**: 在安全沙箱中执行系统命令并收集结果
- **信息检索**: 快速搜索和过滤目标数据

## 即刻上手
1. **配置API密钥**: 在环境变量中设置对应的API Key
2. **初始化连接**: 使用提供的凭证建立API连接
3. **调用接口**: 传入必要参数执行API调用
1. **准备文件**: 确认文件路径正确且格式受支持
2. **执行处理**: 调用对应的处理函数
3. **查看结果**: 检查输出文件或返回数据
1. **检查环境**: 确认运行时和依赖已安装
2. **执行命令**: 使用正确的参数格式执行
3. **查看输出**: 检查命令输出和退出码

### 前置条件

- 已安装所需运行环境(参考依赖说明)
- 已获取必要的API密钥或访问凭证(如适用)
- 输入数据已准备就绪

## 用户常见疑问
### Q1: 广告洞察中枢支持哪些输入格式？

A1: 解决广告情报API参数难懂、调用低效、数据孤岛的广告创意数据中枢。广告创意数据中枢：聚合AdMapix广告情报API，提供参数自然语言翻译（40+行业码/200。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

### Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

### Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

## 异常响应
针对广告洞察中枢使用中可能遇到的常见问题,提供以下排查方案:

| 错误类型 | 原因分析 | 解决方案 |
|---------|---------|---------|
| API认证失败(401) | API密钥错误或过期 | 检查密钥配置,重新生成token |
| 接口限流(429) | 请求频率超出限制 | 降低调用频率,启用重试退避策略 |
| 响应超时(504) | 网络延迟或服务端负载过高 | 增加超时阈值,检查网络连接 |
| 文件不存在 | 路径错误或文件未创建 | 检查路径拼写,确认文件已生成 |
| 文件格式不支持 | 扩展名不在支持列表中 | 转换为支持的格式后重试 |
| 权限不足 | 当前用户无读写权限 | 检查文件权限,以管理员身份运行 |
| 命令执行失败 | 参数错误或环境依赖缺失 | 检查命令语法,确认依赖已安装 |
| 进程超时 | 命令执行时间过长 | 增加超时设置,优化命令参数 |
| 网络连接失败 | DNS解析失败或防火墙拦截 | 检查网络配置,确认代理设置 |

### 广告洞察中枢通用排查步骤

1. **检查输入参数**: 确认所有必填参数已提供且格式正确
2. **查看日志输出**: 定位具体错误行和异常类型
3. **验证环境配置**: 确认依赖库版本和运行环境满足要求
4. **逐步调试**: 缩小问题范围,隔离故障模块

## 疑问解答速查
## 异常处理策略
针对广告洞察中枢使用中可能遇到的常见问题,提供以下排查方案:

| 错误类型 | 原因分析 | 解决方案 |
|---------|---------|---------|
| API认证失败(401) | API密钥错误或过期 | 检查密钥配置,重新生成token |
| 接口限流(429) | 请求频率超出限制 | 降低调用频率,启用重试退避策略 |
| 响应超时(504) | 网络延迟或服务端负载过高 | 增加超时阈值,检查网络连接 |
| 文件不存在 | 路径错误或文件未创建 | 检查路径拼写,确认文件已生成 |
| 文件格式不支持 | 扩展名不在支持列表中 | 转换为支持的格式后重试 |
| 权限不足 | 当前用户无读写权限 | 检查文件权限,以管理员身份运行 |
| 命令执行失败 | 参数错误或环境依赖缺失 | 检查命令语法,确认依赖已安装 |
| 进程超时 | 命令执行时间过长 | 增加超时设置,优化命令参数 |
| 网络连接失败 | DNS解析失败或防火墙拦截 | 检查网络配置,确认代理设置 |

## 技术支持
### Q1: 广告洞察中枢支持哪些输入格式？

A1: 解决广告情报API参数难懂、调用低效、数据孤岛的广告创意数据中枢。广告创意数据中枢：聚合AdMapix广告情报API，提供参数自然语言翻译（40+行业码/200。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

### Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

### Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

## 主要功能
- **自动化执行**: 解决广告情报API参数难懂、调用低效、数据孤岛的广告创意数据中枢。广告创意数据中枢：聚合AdMapix广告情报API，提
- **文件处理**: 支持多种文件格式的读取、解析和写入操作
- **API集成**: 通过标准化接口调用外部服务并处理响应
- **命令执行**: 在安全沙箱中执行系统命令并收集结果
- **信息检索**: 快速搜索和过滤目标数据